--append-subagent-system-prompt flag / Claude Code v2.1.205

What

Appends a custom system prompt to every Task-tool subagent launched by Claude Code, propagated recursively to nested subagents.

Usage

claude --print --append-subagent-system-prompt "Always respond in JSON" ...

Details

Only works with --print (non-interactive mode)
Sets CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT=1 automatically
Propagates the appended prompt through nested subagent chains
Useful for enforcing output format, language, or tool constraints across all agents in a pipeline

Evidence

CLI flag description (search for "Append a system prompt to every Task-tool subagent") — UCp() at line ~763864

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

The build it came inv2.1.205

8 Jul 2026 · 18 entries, this one is #3.

Either side of it

Open the release →

Names in this entry

cli--print
Print response without interactive mode (see Agent SDK documentation for programmatic usage details)
envCLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT
Gates the extra subagent system prompt: when this is truthy and a prompt was supplied by the hidden --append-subagent-system-prompt option, its file variant, or the SDK's appendSubagentSystemPrompt initialize field, the text is appended to a Task-tool subagent's system prompt (skipped for agents with an isolated context and in one other case). Claude Code sets it to 1 itself when either command-line option supplies a prompt.

Is this right?