[DOCS] Headless docs omit `claude -p` background-shell cleanup after final result

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

claude -p stdin/exit behavior, especially when a turn launches a background Bash command

Current Documentation

The headless page currently says:

Non-interactive mode reads stdin, so you can pipe data in and redirect the response out like any other command-line tool.

It also documents follow-up -p invocations as one-shot commands:

Use --continue to continue the most recent conversation, or --resume with a session ID to continue a specific conversation.

And the CLI reference summarizes -p as:

claude -p "query" | Query via SDK, then exit

Separately, the Bash tool docs say:

For long-running processes such as dev servers or watch builds, Claude can set run_in_background: true to start the command as a background task and continue working while it runs. List and stop background tasks with /tasks.

What's Wrong or Missing?

The docs describe claude -p as a stdin-driven command that prints a result and exits, and they describe background Bash commands as long-running tasks, but they never explain how those behaviors interact in headless mode.

The v2.1.163 changelog entry says:

Fixed claude -p hanging forever after its final result when a backgrounded command never exits - background shells are now stopped ~5s after the result once stdin closes

That leaves one user-visible lifecycle gap in the docs:

A. Headless mode does not document what happens to lingering background shells after the final result

Users embedding claude -p in CI, scripts, or subprocess calls can reasonably infer from Query via SDK, then exit that the process ends once the final result is printed. They can also infer from the Bash tool docs that a background command may keep running. The docs never state which rule wins when a -p turn launches a background shell that outlives the answer.

After v2.1.163, Claude Code resolves that ambiguity by stopping background shells shortly after the final result once stdin closes, but the headless docs do not mention that cleanup behavior or when to prefer an interactive/background-session workflow instead.

Suggested Improvement

Add a short note to headless and cross-link it from the Bash tool docs.

Suggested wording:

In claude -p, background Bash commands are not intended to outlive the headless invocation indefinitely. After Claude prints the final result and stdin closes, Claude Code gives any background shell a short grace period, then stops it so the -p process can exit cleanly.

Also add a usage note such as:

If you need a long-lived dev server, watch process, or other background task that should survive beyond one printed result, use an interactive session, /tasks, or a background session instead of claude -p.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/headless | 69-82, 232-247 | Describes stdin-driven claude -p usage and follow-up invocations, but not background-shell lifetime or cleanup |
| https://code.claude.com/docs/en/cli-reference | 17 | Summarizes claude -p as Query via SDK, then exit without any lifecycle caveat |
| https://code.claude.com/docs/en/tools-reference | 124 | Explains run_in_background: true and /tasks, but not how headless -p runs clean up lingering background shells |

Total scope: 3 pages affected

Version context: The missing lifecycle note became user-visible in Claude Code v2.1.163, which changed headless cleanup so a never-ending background shell no longer keeps claude -p hanging forever after the final result.