[DOCS] Headless CLI docs omit `--forward-subagent-text` and `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` for stream-json subagent output

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference

Section/Topic

The CLI flags table (print/stream-json options) and the cross-links from the headless streaming guide.

Current Documentation

The headless guide documents stream-json output and subagent behavior only indirectly:

Use --output-format stream-json with --verbose and --include-partial-messages to receive tokens as they're generated.

The Agent SDK TypeScript reference documents the SDK option:

forwardSubagentText — Forward subagent text and thinking blocks as assistant and user messages with parent_tool_use_id set, so consumers can render a nested transcript. By default only tool_use and tool_result blocks from subagents are emitted.

The CLI reference and environment-variable reference do not list --forward-subagent-text or CLAUDE_CODE_FORWARD_SUBAGENT_TEXT.

What's Wrong or Missing?

Claude Code v2.1.211 added a CLI flag and environment variable to include subagent assistant text and thinking in stream-json output. Integrators using claude -p rather than the Agent SDK have no documented way to enable the same nested transcript behavior that SDK users get from forwardSubagentText.

Suggested Improvement

Add to the CLI reference flags table:

--forward-subagent-text — Include subagent assistant text and thinking in stream-json output as complete messages with parent_tool_use_id set. Requires --print and --output-format stream-json. Equivalent to the Agent SDK forwardSubagentText option.

Add an env-vars.md row for CLAUDE_CODE_FORWARD_SUBAGENT_TEXT with the same semantics.

In headless.md under "Stream responses", add a short subsection with an example:

claude -p "Run a reviewer subagent" \
  --output-format stream-json --verbose --forward-subagent-text

Cross-link to the TypeScript SDK forwardSubagentText option for field-level behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/cli-reference | ~90–102 | --output-format, --include-partial-messages, and related print flags |
| https://code.claude.com/docs/en/headless | ~142–199 | Stream-json output section |
| https://code.claude.com/docs/en/env-vars | — | No CLAUDE_CODE_FORWARD_SUBAGENT_TEXT entry |
| https://code.claude.com/docs/en/agent-sdk/typescript | 423, 1192 | SDK forwardSubagentText already documented |

Total scope: 4 pages affected (3 missing CLI/env/headless coverage; 1 SDK reference to cross-link)

Version: Behavior added in Claude Code v2.1.211.