[DOCS] `claude agents --json` docs omit `--all` flag, new `id` and `state` fields, and which session states the JSON output includes

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/agent-view#manage-sessions-from-the-shell

Section/Topic

"Manage sessions from the shell" — the claude agents --json row in the commands table, and the cross-reference to it from the claude agents entry in the cli-reference commands table.

Current Documentation

In docs/code.claude.com/docs/en/agent-view.md line 446, the claude agents --json row in the "Manage sessions from the shell" table says:

claude agents --json | Print live sessions as a JSON array and exit. Each entry has pid, cwd, kind, and startedAt, plus sessionId, name, and status when set. When status is waiting, waitingFor says what the session is blocked on, such as permission prompt or input needed. Combine with --cwd <path> to filter

In docs/code.claude.com/docs/en/cli-reference.md line 27, the claude agents row in the subcommands table says:

claude agents | Open agent view to monitor and dispatch parallel background sessions. Use --cwd <path> to show only sessions started under that directory, or --json to print live sessions as a JSON array for scripting. Pass --permission-mode, --model, --effort, or --agent to set defaults for dispatched sessions. Accepts --settings, --add-dir, --plugin-dir, and --mcp-config like the top-level claude command. Opening agent view requires an interactive terminal | claude agents --json

What's Wrong or Missing?

A. The --all flag is undocumented for claude agents --json

The changelog for v2.1.169 adds --all to claude agents --json so the JSON output can include completed sessions, not just live ones. Neither the claude agents --json row in the "Manage sessions from the shell" table in agent-view.md nor the claude agents row in the cli-reference.md subcommand table mentions --all. The only --all flag the page mentions is on claude respawn (line 451) and claude project purge (line 35 of cli-reference.md), which are unrelated commands.

B. The new id and state fields are missing from the documented JSON schema

The doc lists the entry fields as pid, cwd, kind, startedAt, and conditionally sessionId, name, and status. The v2.1.169 changelog adds id and state as new top-level fields. Neither name appears in the table row, so a script author reading the docs cannot know the new fields exist or what they hold. The doc also does not say what relationship the new id field has to the existing sessionId field (e.g. whether id is a short identifier and sessionId is the longer UUID, or whether one supersedes the other).

C. The set of states included in the JSON output is not stated

The v2.1.169 changelog fixes claude agents --json to stop omitting blocked and just-dispatched background sessions, and the --all flag extends it further to include completed sessions. The current doc says "Print live sessions" but does not enumerate which session states the JSON output covers by default versus which require --all, and does not call out that blocked and just-dispatched sessions are now included at all. The Read session state table earlier in the page (lines 109-117) lists six states — Working, Needs input, Idle, Completed, Failed, Stopped — but the claude agents --json row does not say which of those appear in the array.

D. The cli-reference cross-reference still reads "print live sessions"

In cli-reference.md line 27 the claude agents row says --json "print[s] live sessions as a JSON array for scripting". This wording is now stale in v2.1.169 because the default set is wider than the word "live" suggests and --all further widens it. A user who reads only the cli-reference and never clicks through to agent-view.md will be unaware of --all and of the blocked/just-dispatched/completed coverage.

Suggested Improvement

A. Add --all to the documented flags

Before (agent-view.md line 446):

claude agents --json | Print live sessions as a JSON array and exit. Each entry has pid, cwd, kind, and startedAt, plus sessionId, name, and status when set. When status is waiting, waitingFor says what the session is blocked on, such as permission prompt or input needed. Combine with --cwd <path> to filter

After:

claude agents --json | Print sessions as a JSON array and exit. Each entry has id, state, pid, cwd, kind, and startedAt, plus sessionId, name, and status when set. When status is waiting, waitingFor says what the session is blocked on, such as permission prompt or input needed. By default the array includes working, needs-input, idle, blocked, and just-dispatched sessions; pass --all to also include completed, failed, and stopped sessions. Combine with --cwd <path> to filter

B. Document the new id and state fields

State that id is the short session identifier (the same value that claude attach, claude logs, and claude stop accept) and that state is one of the six values from the "Read session state" table (working, needs_input, idle, completed, failed, stopped).

C. Enumerate the included states

Spell out which states the JSON output includes by default and which --all adds, using the state names from the existing "Read session state" table further up the same page.

D. Update the cli-reference row

Before (cli-reference.md line 27):

Use --cwd <path> to show only sessions started under that directory, or --json to print live sessions as a JSON array for scripting.

After:

Use --cwd <path> to show only sessions started under that directory, or --json to print sessions as a JSON array for scripting. Combine --json with --all to include completed, failed, and stopped sessions in the output. See agent view for the JSON schema and state coverage.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view#manage-sessions-from-the-shell | 446 | claude agents --json row in the "Manage sessions from the shell" table — missing --all, missing id and state fields, missing state-coverage list |
| https://code.claude.com/docs/en/cli-reference | 27 | claude agents subcommand row — calls output "live sessions" and does not mention --all or the new fields |

Total scope: 2 pages affected

Version: This gap was introduced in v2.1.169. The fix added --all to claude agents --json, made blocked and just-dispatched sessions part of the default output, and added the id and state fields to each JSON entry.

Cross-reference: The "Read session state" table in the same agent-view.md page (around line 109) is the existing source of truth for the six session states (Working, Needs input, Idle, Completed, Failed, Stopped) and can be cross-referenced by the updated claude agents --json row rather than restated.