session-flow/orchestrate: nested-subagent claims are correct but mis-sourced — sub-agents page lags the changelog

[kyle-sexton]

Follow-up to the plugin-quality:audit of session-flow:orchestrate run against #1479. The audit's
ranked top finding (F2.1, HIGH) is refuted; a real but differently-targeted drift survives.

The finding as filed

context/sources.md:70-84 and SKILL.md:131-133 claim nesting is gated by listing Agent in
tools, and that the depth ceiling is "a configurable default of three." Both are wrong as of the
current sub-agents doc … Nesting is off by default today and requires explicit opt-in.

Why it is refuted

Re-verified 2026-07-26 against the byte-exact raw changelog (not a summarizing fetch — the audit
itself recorded that this page reads inconsistently through a summarizer, which is why the raw
markdown was used):

• v2.1.172 — "Sub-agents can now spawn their own sub-agents (up to 5 levels deep)"
• v2.1.217 — "Changed subagents to no longer spawn nested subagents by default; set
  CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to allow deeper nesting"
• v2.1.219 — "Subagents can now spawn nested subagents up to depth 3 by default (was 1); set
  CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting"
• v2.1.220 — bug fixes only; does not revert it

Installed harness is 2.1.220. So SKILL.md's three-state history and its "configurable default
of three" are correct, and were correct when the audit called them wrong.

Confirmed behaviorally as well: a non-fork general-purpose subagent one layer below a subagent
held a fully-schema'd Agent tool with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH unset in its
environment — which the prose page's account forbids outright. (The exact live ceiling was not
pinned: the probe that would have measured it was denied by the auto-mode permission classifier,
which evaluates spawns before launch and is a different gate entirely.)

The audit's own empirical reproduction ("the Agent tool was entirely absent from the nested
subagent's tool list") is most likely explained by the agent definition it dispatched rather than
by nesting being off: a restricted agent type whose tools list omits Agent produces exactly that
observation regardless of the nesting default.

What is actually wrong

1. The sub-agents page lags the changelog by one release. It still reads "By default, a
   subagent can't spawn subagents of its own… While nesting is off, Claude Code withholds the
   Agent tool from every subagent except a fork." It has not absorbed v2.1.219. The audit trusted
   this page; so did sources.md. Both official surfaces are cited by the skill, and they currently
   disagree.
2. context/sources.md:70-84 IS stale — just not for the reason filed. Its quotes "a background
   subagent at depth five does not receive the Agent tool" and "The limit is fixed and not
   configurable" appear nowhere in the current page and are contradicted by the env var existing.
3. SKILL.md cites sub-agents for a fact that page now contradicts. The depth-3 default needs
   re-attributing to the changelog, with the page kept for the env-var mechanism and cap semantics.
4. The audit's "in-repo SSOT drift" sub-claim is inverted: it names discovery's files as
   already correct, but they encode the superseded off-by-default state and are the stale ones.
   Tracked separately.

Scope

• Rewrite context/sources.md's imperative-5 block to current text; add the caps and a drift note.
• Re-attribute SKILL.md's depth paragraph; add a confirm-nesting-from-behavior rule, since a
  tree authored from either source alone can be wrong in both directions.
• Index the changelog and workflows pages in docs/OFFICIAL-DOCS.md — orchestrate cites both as
  load-bearing evidence and neither was in the indexed set.

Acceptance criteria

• Every behavioral claim in the imperative-5 sources block is version-pinned and quoted from a
  page fetched at edit time.
• The doc/changelog divergence is recorded explicitly, with which surface to believe for what.
• skill-quality:check passes on orchestrate with trigger keywords preserved.