[DOCS] Background session docs omit SIGTERM-first teardown for shell subprocesses

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

"Run a shell command", "Manage sessions from the shell", and "How background sessions are hosted"

Current Documentation

The agent-view page currently explains how to launch background shell jobs and how sessions are stopped, but it does not document the teardown behavior for running shell subprocesses:

To run a shell command as a background job instead of a Claude session, type ! as the first character of the agent view dispatch input. The command runs as a PTY-backed job and appears as a row in agent view, with the most recent line of output as its status.

| claude stop <id> | Stop a session. Also accepts claude kill | | claude rm <id> | Remove a session from the list. Removes a worktree Claude created for the session if it has no uncommitted changes; otherwise prints the worktree path so you can clean it up. Leaves a worktree you created yourself in place. The conversation transcript stays on your local machine and remains available through claude --resume |

Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources.

What's Wrong or Missing?

The main background-session docs do not explain what happens to running shell subprocesses when teardown is triggered by claude stop, claude rm, or the idle reaper.

In v2.1.160, the changelog says background-session teardown now sends SIGTERM to running shell subprocesses before escalating to SIGKILL, specifically so cleanup handlers can run. That behavior is important for users who run long-lived commands with ! <command> or claude --bg --exec '...', because it determines whether shell trap handlers, temporary-file cleanup, and graceful shutdown logic will execute.

Without this documented on the agent-view and CLI reference pages, users only see that a session is "stopped" or "removed" and cannot tell that Claude Code now performs a graceful termination step first.

Suggested Improvement

Add a short teardown note anywhere the docs describe background shell jobs and session termination.

For example, near the ! <command> / --exec documentation and the claude stop / claude rm command table, add wording like:

When Claude Code tears down a background session or background shell job, it first sends SIGTERM to running shell subprocesses and only escalates to SIGKILL if they do not exit. This applies to manual shutdown (claude stop, claude rm) and idle cleanup, so shell cleanup handlers can run before forced termination.

That would make the lifecycle of background jobs explicit and align the main docs with the v2.1.160 behavior change.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 320-334 | Background shell jobs (! <command> / claude --bg --exec) are documented, but teardown signal behavior is not |
| https://code.claude.com/docs/en/agent-view | 443-446, 460-462 | claude stop, claude rm, and idle stopping are documented without explaining graceful SIGTERM-first shutdown |
| https://code.claude.com/docs/en/cli-reference | 38-40, 60, 73 | claude rm, claude stop, --bg, and --exec entries omit the teardown semantics for running shell subprocesses |
| https://code.claude.com/docs/en/changelog | 37 | v2.1.160 changelog entry states the new SIGTERM-before-SIGKILL behavior |

Total scope: 4 pages affected

Version context: The behavior change is called out in the v2.1.160 changelog as: "Improved background-session teardown (claude rm/stop, idle reap) to send SIGTERM to running shell subprocesses before SIGKILL, so cleanup handlers run."