[DOCS] Headless page should cross-link to Agent SDK streaming and user-input docs

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

"Run Claude Code programmatically" page, overall structure and cross-references.

Current Documentation

The headless page covers basic CLI usage with -p and mentions the Agent SDK at the top:

The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as Python and TypeScript packages for full programmatic control.

The page then covers streaming output, auto-approving tools, creating commits, customizing system prompts, and continuing conversations -- all via CLI examples.

The "Next steps" section links to the Agent SDK quickstart and CLI reference but not to the specific SDK pages that cover the same topics in more depth.

What's Wrong or Missing?

The headless page covers several topics that have much more thorough treatment in the Agent SDK docs, but most sections don't cross-link to the deeper documentation:

| CLI topic on headless page | Agent SDK equivalent | Cross-link exists? |
|---|---|---|
| Stream responses (one jq example) | Stream responses in real-time (full event reference, message flow, UI examples) | Yes (added recently) |
| Auto-approve tools (--allowedTools) | Configure permissions (modes, rules, hooks) | No |
| No coverage of tool approval | Handle approvals and user input (canUseTool, AskUserQuestion) | No |
| No coverage of multi-turn input | Send messages to agents (streaming input mode) | No |

The streaming section now includes a cross-link ("For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](...) in the Agent SDK documentation"), but the other three topics listed above still have no cross-references.

Suggested Improvement

The streaming section already has a cross-link to the SDK streaming-output page. Add similar inline cross-references for the remaining sections. For example, after the "Auto-approve tools" section:

For programmatic tool approval with callbacks, see Handle approvals and user input in the Agent SDK documentation.

And in the "Next steps" cards, consider adding links to the permissions and user-input SDK pages alongside the existing quickstart and CLI reference links.

Impact

Medium - Makes feature difficult to understand

Additional Context

The Agent SDK docs are thorough and well-written. The headless page is the natural entry point for developers who want programmatic Claude Code access. Better cross-linking would help users discover the deeper SDK documentation.