[DOCS] `/tasks` panel stop is now permanent for background agents — docs still describe supervisor auto-resurrect behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

The supervisor process section (under How background sessions are hosted), the Read session state shape table, and the Sessions show as failed after shutdown troubleshooting entry. Cross-references from https://code.claude.com/docs/en/sub-agents (Resume subagents section) and https://code.claude.com/docs/en/tools-reference (the SendMessage description) describe the same outdated auto-resurrect semantics.

Current Documentation

The agent-view page documents that a stopped background session's process can be brought back by the supervisor on the next user interaction:

∙ | The process has exited. You can still peek, reply, or attach, and Claude restarts from where it left off (agent-view.md, Read session state shape table)

Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. … The transcript and state stay on disk either way, and the next time you attach, peek, or reply to a stopped session, the supervisor starts a fresh process from where it left off. (agent-view.md, The supervisor process)

Shutting down or restarting your machine stops running background sessions, so they show as failed when you next open agent view. Attach, peek, or reply to any of them and the session restarts from where it left off. (agent-view.md, Sessions show as failed after shutdown)

Once a session has finished and sat unattached for about an hour, the supervisor stops its process to free resources. Attaching starts a fresh process from where it left off, which takes a moment. (agent-view.md, A session is slow to respond after attaching)

The sub-agents page applies the same resurrect-on-message behavior to stopped subagents:

If a stopped subagent receives a SendMessage, it auto-resumes in the background without requiring a new Agent invocation. (sub-agents.md, Resume subagents)

And the tools reference repeats it for the SendMessage tool:

Sends a message to an agent team teammate, or resumes a subagent by its agent ID. Stopped subagents auto-resume in the background. (tools-reference.md, tool summary table)

The /tasks command is documented as a stop surface for in-session background work without any caveat about resurrection:

/tasks — View and manage everything running in the background. Also available as /bashes (commands.md, built-in commands table)

For anything running in the background of the current session, /tasks lists each item and lets you check on, attach to, or stop it. (agents.md, parallel-work overview)

What's Wrong or Missing?

Claude Code v2.1.191 fixed a bug where background agents stopped from the /tasks panel resurrected after being stopped:

Fixed background agents resurrecting after being stopped — stopping an agent from the tasks panel is now permanent

The current docs continue to describe the pre-fix behavior as the expected one. They do not distinguish between a session that the supervisor stopped on its own (idle timeout, host low-memory, machine shutdown) and a session that the user explicitly stopped from the /tasks panel, Ctrl+X Ctrl+K, or claude stop. After v2.1.191 only the first category resurrects on attach/peek/reply/SendMessage; an explicit stop is now permanent and will not be restarted by the supervisor on subsequent interaction.

This affects at least three documented promises:

1. The ∙ shape row in the state table — "You can still peek, reply, or attach, and Claude restarts from where it left off" is no longer true for sessions the user stopped themselves.
2. The Once a session finishes and sits unattached for about an hour… paragraphs in two places — both read as a blanket guarantee that any stopped session restarts on the next user touch.
3. If a stopped subagent receives a SendMessage, it auto-resumes… and the matching SendMessage tool description — these describe the same resurrection behavior for explicitly stopped subagents.

Without a doc fix, users reading the agent-view or sub-agents pages have no signal that Ctrl+X, /tasks → stop, or Ctrl+X Ctrl+K is now a permanent stop, and they may avoid using those controls out of fear of an unwanted resurrection, or conversely be surprised when a stopped session does not come back on attach.

Suggested Improvement

Split the supervisor-resurrection behavior in the docs into two cases — supervisor-initiated stops (still resurrect) versus user-initiated stops (now permanent) — and reflect that in each affected passage.

A. agent-view.md — Read session state shape table

Tighten the ∙ row so it does not claim a blanket resurrect on user touch:

∙ — The process has exited. The supervisor can restart a session it stopped itself (idle, low memory, shutdown) on your next attach, peek, or reply. Sessions you explicitly stopped from the tasks panel are permanent and will not be restarted.

B. agent-view.md — The supervisor process and Sessions show as failed after shutdown

Add a short note clarifying that the resurrect-on-touch guarantee applies only to supervisor-initiated stops. Suggested wording for the supervisor paragraph:

Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. A session you have pinned with Ctrl+T is exempt. The transcript and state stay on disk either way, and the next time you attach, peek, or reply to a session the supervisor stopped itself, it starts a fresh process from where it left off. Sessions you explicitly stopped from the tasks panel, Ctrl+X Ctrl+K, or claude stop are permanent and are not restarted.

Apply the same distinction in Sessions show as failed after shutdown (machine shutdown → resurrect still applies; user stop → does not).

C. sub-agents.md — Resume subagents

Replace the blanket auto-resumes line with the explicit/permanent distinction:

If a stopped subagent receives a SendMessage, it auto-resumes in the background without requiring a new Agent invocation. This does not apply to subagents you stopped from the /tasks panel — that stop is permanent as of v2.1.191.

D. tools-reference.md — SendMessage tool summary

Update the SendMessage row so it does not promise auto-resume for explicitly stopped subagents:

Sends a message to an agent team teammate, or resumes a subagent by its agent ID. Stopped subagents the supervisor stopped itself auto-resume in the background. Subagents stopped from the tasks panel are permanent and are not resumed.

E. commands.md / agents.md — /tasks

Add a one-line note in the /tasks row that stopping an entry is permanent and the session will not be restarted by the supervisor:

/tasks — View and manage everything running in the background. Stopping an entry is permanent; the session will not be restarted on a later attach. Also available as /bashes.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | ~123 | Read session state shape table — ∙ row claims restart on user touch |
| https://code.claude.com/docs/en/agent-view | ~484 | The supervisor process — describes restart on attach/peek/reply for any stopped session |
| https://code.claude.com/docs/en/agent-view | ~537 | Sessions show as failed after shutdown — restart-on-attach phrasing |
| https://code.claude.com/docs/en/agent-view | ~573 | A session is slow to respond after attaching — same restart-on-attach phrasing |
| https://code.claude.com/docs/en/sub-agents | ~834 | Resume subagents — If a stopped subagent receives a SendMessage, it auto-resumes |
| https://code.claude.com/docs/en/tools-reference | ~39 | SendMessage tool summary — Stopped subagents auto-resume in the background |
| https://code.claude.com/docs/en/commands | ~130 | /tasks row — no caveat that stop is permanent |
| https://code.claude.com/docs/en/agents | ~53 | /tasks overview paragraph — same missing caveat |

Total scope: 6 pages affected, 8 documentation passages.

Version where behavior changed: v2.1.191 — Fixed background agents resurrecting after being stopped — stopping an agent from the tasks panel is now permanent.

Cross-references:

• https://code.claude.com/docs/en/keybindings (Ctrl+X Ctrl+K → chat:killAgents) is the matching keyboard surface and should be checked for a parallel "stop is permanent" note once the text-level pages are updated.
• https://code.claude.com/docs/en/interactive-mode documents the Ctrl+X Ctrl+K shortcut and currently says only Stop all running background subagents in this session. Press twice within 3 seconds to confirm — adding the same permanence note keeps the keyboard-surface docs aligned with the panel docs.