[DOCS] `claude stop <id>` reliability against supervisor respawn is not documented — agent view docs describe supervisor restart behavior without stating that stops are honored

[coygeek]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/agent-view#the-supervisor-process

Section/Topic

The The supervisor process subsection of agent-view.md, specifically the paragraph that describes how the supervisor restarts sessions on auto-update and reconnects to detached background processes. The Stop a session CLI command reference (in the same page's CLI command table) and the Stopped row in the session state legend also need to be aligned.

Current Documentation

The agent-view page describes the supervisor's reconnect behavior as:

The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular auto-updater replaces it. This is a local file watch, not a network check. Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them. An idle pinned session is also restarted in place onto the new version so it picks up the update without you reattaching.

The CLI command table lists:

claude stop <id> — Stop a session. Also accepts claude kill

The session state legend lists:

| Stopped | Grey | The session was stopped with Ctrl+X or claude stop |

The changelog itself notes, in an earlier entry, that background agents were at one point resurrecting after being stopped — "Fixed background agents resurrecting after being stopped — stopping an agent from the tasks panel is now permanent" — but the supervisor section in agent-view.md was never updated to reflect that claude stop is also honored by the supervisor's respawn path, not only by the /tasks panel.

What's Wrong or Missing?

A. Stop-vs-respawn interaction is undocumented

The supervisor section explains that "Background sessions ... keep running through the restart and the new supervisor reconnects to them" but does not say what happens to a session that the user has just stopped with claude stop if a respawn is in flight. As of v2.1.199 the respawn honors the stop, but readers have to infer that from the changelog.

B. claude stop description omits the supervisor guarantee

claude stop <id> is documented only as "Stop a session." A user cannot tell from this entry alone that the stop is durable across the kinds of supervisor activity described in the page — auto-updates, restart into a new version, memory-pressure reap cycles — versus being silently undone by an in-flight respawn.

C. Stopped state legend does not note durability

The Stopped legend row labels the state and ties it to two trigger commands (Ctrl+X and claude stop), but it doesn't say whether the state survives a supervisor restart. The earlier changelog line about background agents resurrecting after being stopped implies that durability was once inconsistent; the current docs do not reassure the reader that this is now consistent for the CLI command as well.

Suggested Improvement

Option A: Minimum fix — one sentence in the supervisor section

Add a sentence to the supervisor section clarifying that user-initiated stops (claude stop, claude kill, Ctrl+X) are durable across supervisor respawns:

A session you stopped with claude stop, claude kill, or Ctrl+X is not revived by a supervisor respawn — the respawn honors the stop and the session stays in the Stopped state.

Option B: Comprehensive fix — also update the CLI command table and legend

In addition to the sentence above, expand the claude stop <id> row to mention durability:

claude stop <id> — Stop a session. The stop is honored by any in-flight supervisor respawn and survives the supervisor's auto-update restart, so the session stays in the Stopped state until you explicitly respawn or remove it. Also accepts claude kill.

And add a short parenthetical to the Stopped legend row:

| Stopped | Grey | The session was stopped with Ctrl+X or claude stop; the stop survives supervisor respawn |

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Line(s)	Context
https://code.claude.com/docs/en/agent-view	482	claude stop <id> CLI command table row
https://code.claude.com/docs/en/agent-view	118	Stopped state legend row
https://code.claude.com/docs/en/agent-view	525	Supervisor auto-update and reconnect paragraph
https://code.claude.com/docs/en/cli-reference	43	claude stop <id> command reference table

Total scope: 2 pages affected (both reference the same agent-view supervisor section, plus its CLI mirror in cli-reference).

Version: Behavior clarified in v2.1.199. The /tasks panel stop-permanence fix shipped in an earlier release covers the UI surface; this entry covers the CLI claude stop surface. Both share the supervisor theme but address different docs sections (CLI command table vs /tasks panel description).