[DOCS] --print flag docs missing team agent interaction caveat

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

--print / -p flag entry; also the headless/non-interactive usage section in headless.md

Current Documentation

cli-reference.md documents the --print flag as:

| --print, -p | Print response without interactive mode (see Agent SDK documentation for programmatic usage details) | claude -p "query" |

headless.md documents --print usage:

"Add the -p (or --print) flag to any claude command to run it non-interactively. All CLI options work with -p, including: ..."

Neither page mentions any interaction with team agents or --teammate-mode.

What's Wrong or Missing?

A changelog fix reveals a previously undocumented behavior: when team agents are configured, --print mode previously hung forever because its exit loop waited indefinitely on long-lived in_process_teammate tasks. The fix corrects this by not waiting on such tasks.

This reveals a real interaction between --print (non-interactive / headless mode) and team agent configurations that users need to be aware of:

1. If a project has team agents configured and the user runs claude -p "...", the behavior is now defined — but it was previously undefined (hanging forever).
2. Users combining --print with --teammate-mode in-process have no documentation about expected behavior or limitations.
3. The term in_process_teammate (the task type that caused the hang) has no reference in any documentation page.

Scripts and CI pipelines using claude -p in repositories with team agent configurations would have silently hung. Now they exit correctly, but users still have no documented guidance on --print + team agents.

Suggested Improvement

Add a note to the --print flag entry in cli-reference.md:

Note: When team agents are configured in the project, --print mode exits without waiting for long-lived in-process teammate tasks. Use interactive mode or the Agent SDK if you need teammate output in automated workflows.

Add a similar note in headless.md under --print usage, and cross-reference from agent-teams.md:

When running with --print (-p), in-process team agent tasks are not awaited. Headless mode exits after the primary agent's response is complete.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/cli-reference | --print flag entry — no team agent caveat |
| https://code.claude.com/docs/en/headless | --print usage section — no team agent mention |

Total scope: 2 pages affected

Source: Changelog v2.1.71

Exact changelog entry:

"Fixed --print hanging forever when team agents are configured — the exit loop no longer waits on long-lived in_process_teammate tasks"