--append-subagent-system-prompt help says "only works with --print" but has no print-mode gate

Summary

--append-subagent-system-prompt advertises itself as --print-only, but there is no print-mode gate on it: it is accepted and applied in interactive sessions too. Either the restriction is missing or the help text is wrong.

Verified on 2.1.219 / 2.1.220, macOS.

The claim

The option's own (hidden) help text reads:

Append a system prompt to every Task-tool subagent's system prompt, propagated to nested subagents (only works with --print). Implies CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT=1.

What the code actually does

• The option is consumed in the CLI setup path that runs for both interactive and print mode, with no --print check guarding it. Its only effect there is to set CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT=1.
• At the Task-tool subagent spawn site, the append is gated on exactly three things: an unrelated subagent-shape flag, that env var, and the option value being non-empty. There is no interactive/non-interactive check.
• By contrast, the sibling options that really are print-only — --plan-mode-instructions, --prompt-suggestions, --include-partial-messages, --forward-subagent-text, --no-session-persistence — all hard-error with an explicit "can only be used with --print mode" message from that same function. No such error string exists for this option.

So the documented restriction is not enforced anywhere.

Also worth documenting

CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT=1 on its own does nothing: the spawn-site condition also requires the option value, which is only populated from the CLI flag (or the SDK's appendSubagentSystemPrompt init option). Since passing the flag already sets the env var itself, exporting the variable manually is redundant for CLI use — its only real purpose is the SDK path. The help text implies the env var is the gate you need to open, which reads the other way around.

Ask

Pick one: enforce the print-mode restriction like the sibling options do, or correct the help text to say it works in interactive mode too. The current state means anyone reading the help will avoid a working configuration, and anyone testing it will get behaviour the docs say is impossible.