[DOCS] Document `claude -p` / `claude --print` parity boundaries and route known print/headless issues

Parent tracking issue: https://github.com/anthropics/claude-code/issues/59105

Context note: This is a frontend/product-boundary parity issue, not a criticism
of any individual implementation. Since -p / --print behavior is already a
known pain point, and upcoming mid-June frontend-facing changes may depend on
predictable CLI/TUI parity, this should be evaluated as a user-facing parity
risk. The goal is to reduce verification time and avoid customer-facing
regressions with potential business impact.

Summary

Claude Code documentation should clearly state whether claude -p is intended
to be:

1. non-interactive Claude Code CLI with TUI-equivalent semantics, or
2. a separate headless/SDK-style execution surface with different identity,

tools, hooks, skills, MCP, auth, and lifecycle behavior.

Current behavior and current docs leave users assuming (1), while packet capture
and many open issues indicate (2).

Why this matters

Users deploy claude -p in frontend-facing workflows, CI, eval loops,
scheduled jobs, pre-commit hooks, and internal developer tooling. When -p
differs from TUI without a clear parity contract:

• production behavior surprises users
• security controls may be assumed active when they are not
• CI/evals may test a different agent than humans use
• auth/cost behavior may differ from manual operation
• support/debugging workflows compare non-equivalent modes

This is a docs issue even if the implementation is also fixed.

Documented surfaces needed

Please document, explicitly, for claude -p / print / headless mode:

• product identity and request attribution
• whether it is expected to use cli or sdk-cli
• hooks that fire and hooks that do not
• --allowedTools enforcement behavior
• skill loading and skill triggering behavior
• MCP connector behavior
• auth/subscription/API-key precedence
• Task/subagent behavior
• stream-json and JSON output limitations
• whether TUI and -p are intended to be eval-equivalent

Rediscovery track

Users can verify this without reverse engineering by capturing
claude -p / claude --print through a local recorder, capturing a same-state
TUI main-thread request, selecting packets by debug source, and comparing
User-Agent, attribution system block, identity system block, beta header,
and tool names.

If maintainers inspect the source, the stable search literals are
CLAUDE_CODE_ENTRYPOINT, sdk-cli, --print, process.stdout.isTTY,
source=repl_main_thread, source=sdk, and the two identity prompt strings.

Related upstream issues to route

Representative open issues:

• #18131 - print-mode-only API 400 tool-use concurrency error
• #20508 - duplicate tool_use IDs in -p
• #33343 - hooks and --allowedTools not enforced in headless -p
• #36570 - skills do not trigger in claude -p
• #44756 - skills silently fail in print mode
• #39453 - non-interactive -p cannot use Claude Pro login
• #39271 - MCP bearer-token regression in claude -p
• #50777 - MCP cleanup hang after claude -p
• #52917 - -p exits before background subagents complete
• #56540 - non-TTY -p hangs on parallel Task fan-out
• #55802 - ambient sdk-cli session storm

Mitigation note

Until official parity is fixed or documented, users who require
TUI-equivalent semantics can route print-mode workflows through the TUI scaffold.

One existing third-party implementation is:

• https://github.com/smithersai/claude-p
• npm claude-p@0.0.4

It drives the real interactive Claude Code TUI inside a PTY, injects the prompt
with hooks, reads the transcript after the Stop hook, and emits
claude -p-compatible output. This is safer than rewriting API requests because
it preserves the TUI scaffold by construction.

This should not be the long-term official answer. It is evidence that users need
a supported TUI-equivalent print mode.