--forward-subagent-text CLI Flag / Claude Code v2.1.211

What

New flag for --print mode that forwards subagent text and thinking blocks as structured assistant/user messages with parent_tool_use_id set, enabling callers to reconstruct the full agent conversation tree from the stream.

Usage

claude --print --output-format=stream-json --forward-subagent-text "your prompt"

Details

Requires both --print and --output-format=stream-json. When explicitly specified on the CLI without those flags, the process exits with: "Error: --forward-subagent-text requires --print and --output-format=stream-json." When the option is supplied programmatically via the SDK forwardSubagentText: true init-config field, it silently degrades to false rather than erroring if the output conditions are not met.
Without the flag, only tool_use and tool_result content blocks from subagent turns are forwarded upstream in the progress event stream. With the flag enabled, all content types — including text and thinking blocks — are forwarded.
Forwarded subagent messages are emitted as progress events (data.type === "agent_progress") carrying the full assistant or user message wrapper. The stream-json serializer converts these into top-level assistant/user message events with parent_tool_use_id set to the spawning agent's tool-use ID, allowing callers to reconstruct the full agent conversation tree.
When forwardSubagentText is active, thinking blocks in subagent turns are not suppressed: the thinking configuration object is returned unchanged rather than having its display property overridden to "omitted" — which is the default behaviour for non-interactive stream-json sessions.
Allows external tooling (CI pipelines, orchestration layers) to receive the complete content of nested subagent turns rather than only the top-level result.

Evidence

New CLI flag added to the argument parser (search for "--forward-subagent-text"); forwarding gate (search for "forwardSubagentText" near "tool_use" and "tool_result" checks); thinking-config passthrough in Flc function

Strings lifted out of the shipped bundle, so the claim above can be checked against them.

How sure we are

One source agreesOne thing we can check says the same as this entry.

Anthropic's release notes agreeAdded --forward-subagent-text flag and CLAUDE_CODE_FORWARD_SUBAGENT_TEXT environment variable to include subagent text and thinking in…

See this entry in the whole of v2.1.211 →

The build it came inv2.1.211

15 Jul 2026 · 14 entries, this one is #2.

Either side of it

v2.1.210Older
v2.1.212Newer

Open the release →

Names in this entry

cli--forward-subagent-text
Emit subagent text and thinking blocks in the output stream as assistant and user messages with parent_tool_use_id set, so you can reconstruct each subagent's transcript. Without this flag, Claude Code omits the text and thinking blocks of a subagent that runs in the foreground. Requires --print and --output-format stream-json. Claude Code also forwards messages from nested subagents, setting parent_tool_use_id to the ID of the Agent or Skill tool call that started each one; this requires Claude Code v2.1.219 or later, and messages of subagents that a forked skill spawns, and of nested forked skills, require v2.1.275 or later. The CLAUDE_CODE_FORWARD_SUBAGENT_TEXT environment variable enables the same behavior. Requires Claude Code v2.1.211 or later
cli--print
Print response without interactive mode (see Agent SDK documentation for programmatic usage details)
settinguser
Recalled memories no longer get silently dropped when the model echoes back the category label with the name.

Anthropic's note

Upstream's own release notes for v2.1.211 name something this entry names, so the two are probably about the same change. Probably: the pairing is made on a shared name rather than on the words around it.

Added --forward-subagent-text flag and CLAUDE_CODE_FORWARD_SUBAGENT_TEXT environment variable to include subagent text and thinking in stream-json output

Is this right?