[DOCS] `sub-agents.md` does not document the surplus-idle summary row collapse behavior in the subagent panel

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

"Spawn nested subagents" — the paragraph that describes the subagent panel below the prompt input (introduced alongside v2.1.193). The panel description stops at "the full tree" and never mentions how idle subagent rows are displayed after v2.1.199.

Current Documentation

From sub-agents.md line 809 (under "Spawn nested subagents"):

The subagent panel below the prompt input shows the full tree: each row displays a (+N) count of descendants, and as of v2.1.193, opening a row shows that subagent's siblings and direct children with a path back to main.

This is the only statement in the page that describes how rows are organized in the subagent panel. Nothing in sub-agents.md, interactive-mode.md, agent-view.md, or agent-teams.md (cross-references aside) describes the new surplus-idle collapse behavior for subagents. The same behavior is documented for teammates in agent-teams.md lines 86 and 375, but not for subagents.

What's Wrong or Missing?

A. Missing description of v2.1.199 idle-row behavior for subagents

The v2.1.199 changelog entry reads: "Fixed idle subagents vanishing from the agent panel while other subagents were still working; surplus idle agents now collapse into an expandable summary row." Two pieces of behavior changed:

1. Idle subagent rows no longer vanish from the panel while any subagent or teammate is still working.
2. When more than three subagents are idle at once, the rows beyond the first three collapse into a single summary row that counts the collapsed subagents (e.g. 2 idle agents), and Enter expands / Esc re-collapses it.

Neither piece is mentioned in sub-agents.md, even though that page is the primary documentation for the subagent panel. The teammate equivalent (lines 86 and 375 of agent-teams.md) is documented explicitly with a {/* min-version: 2.1.199 */} marker — sub-agents.md is missing the parallel annotation.

B. Page claim "shows the full tree" is no longer accurate on its own

Before v2.1.199 the panel did show the full tree. After v2.1.199, a working tree with many idle subagents now collapses some of those rows behind a summary row, so "shows the full tree" is now misleading without the idle-collapse clause. The sentence should either be qualified ("shows the full tree, except that surplus idle rows collapse into a summary row") or the idle-collapse behavior should be added as a separate sentence immediately after it.

C. No keyboard affordance for the new summary row

The "Spawn nested subagents" section describes panel rows ((+N), path back to main, etc.) but never lists keyboard behavior. The teammate-equivalent behavior already has the Enter/Esc interaction documented, so users reading the subagent page have no way to learn how to expand the new summary row without referencing the agent-teams page.

Suggested Improvement

Add a {/* min-version: 2.1.199 */} annotation in the "Spawn nested subagents" subsection of sub-agents.md, immediately after line 809. Suggested wording (parallel to agent-teams.md line 86):

{/* min-version: 2.1.199 */}As of v2.1.199, an idle subagent's row stays in the panel while any subagent or teammate is still working, so you can select it to review its transcript or send it more work. Once every agent in the panel is idle, idle rows hide after 30 seconds and reappear on the subagent's next turn; the subagent stays running and addressable while hidden.

When more than three subagents are idle at once, the rows beyond the first three collapse into a single row that counts the collapsed subagents, such as `2 idle agents` when five are idle. Select it and press Enter to expand the collapsed rows, or press Esc to collapse them again. Working subagents, failed subagents, and the subagent you're viewing always keep their own rows.

Then update line 809 to acknowledge the caveat: e.g. "The subagent panel below the prompt input shows the full tree, with surplus idle rows collapsed into a summary row that Enter expands."

If preferred, keep line 809 untouched and add a new short subsection ("Idle row behavior") directly under "Spawn nested subagents" so the existing 2.1.193 statement stays unmodified.

A minimal fix that resolves Section 6.A only is to add the four-sentence block above without touching line 809.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 809 | "Spawn nested subagents" — the "shows the full tree" sentence that no longer reflects post-v2.1.199 behavior |
| https://code.claude.com/docs/en/agent-teams | 84, 86, 375 | Teammate equivalent of the same idle-row behavior is already documented with min-version: 2.1.199; sub-agents.md is missing the matching block |

Total scope: 1 page affected (sub-agents.md); agent-teams.md is referenced for cross-checking, not as a fix target.

Version marker already in use elsewhere: The release's team-side documentation uses {/* min-version: 2.1.199 */} consistently, so the missing subagent-side block is the only inconsistency.

Changelog: https://code.claude.com/docs/en/changelog (see the v2.1.199 entry: "Fixed idle subagents vanishing from the agent panel while other subagents were still working; surplus idle agents now collapse into an expandable summary row")