[DOCS] `claude agents --json` docs omit the `waitingFor` field for blocked sessions

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Manage sessions from the shell" table, especially the claude agents --json row

Current Documentation

The agent view page currently 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. Combine with --cwd <path> to filter

The CLI reference also summarizes --json only as a way to print live sessions as a JSON array for scripting.

What's Wrong or Missing?

The documented JSON shape is now incomplete.

In v2.1.162, claude agents --json adds a waitingFor field that shows what a waiting session is blocked on, such as a permission prompt. The current docs still enumerate the older field set and do not explain that blocked sessions can now expose their specific blocker in the JSON output.

That creates one root-cause documentation gap across the scripting docs:

A. The primary schema description is outdated

The agent-view page lists the returned fields but omits waitingFor, so readers do not get the current object shape.

B. The scripting-oriented CLI reference does not mention the new blocker detail

Readers are told --json is useful for scripting, but not that they can now detect why a session is waiting instead of only seeing a generic blocked/status state.

Suggested Improvement

Update the claude agents --json documentation to include waitingFor in the returned object description and explain when it appears.

For example, revise the schema description to say that each entry includes the existing fields plus waitingFor when a session is waiting for input, and note that the field describes the blocker (for example, a permission prompt).

If possible, add a short JSON example for a waiting session so script authors can see how to branch on status together with waitingFor.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 446 | claude agents --json field list omits waitingFor |
| https://code.claude.com/docs/en/cli-reference | 27 | claude agents summary mentions --json for scripting but not the blocker detail |

Total scope: 2 pages affected

Version context: This gap matters for the v2.1.162 release entry that added waitingFor to claude agents --json so waiting sessions can report what they are blocked on.