discovery: nested-spawn availability claims describe a state that lasted two releases

[kyle-sexton]

Surfaced while working the session-flow:orchestrate audit (#1570). That audit named discovery's
files as the in-repo copies that "already state the current, correct fact." They state the
superseded one. These are the stale copies, not the reference copies.

The claim

Four places in this plugin assert some form of:

the harness filters Agent out of every non-fork subagent unless
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH is set in the session

• plugins/discovery/agents/explorer.md:75-79
• plugins/discovery/agents/researcher.md:72-76
• plugins/discovery/skills/setup/SKILL.md:64-73
• plugins/discovery/skills/research-deep/SKILL.md:28 (and a related fork claim at ~83)

That was true for exactly two releases.

What the changelog says

Verified 2026-07-26 against byte-exact raw markdown (the rendered page reads inconsistently through
a summarizing fetch, so raw 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"

Confirmed behaviorally on 2.1.220: a non-fork general-purpose subagent held a fully-schema'd
Agent tool with the variable unset in its environment.

Note the upstream sub-agents prose page still documents the off-by-default state and has not
absorbed v2.1.219 — which is how both this plugin and the audit arrived at the same stale reading.

Why this is worth fixing rather than leaving as merely dated

The variable's polarity flipped. It used to be the opt-in that turned nesting on; it is now the
knob that also turns nesting off (=1). So "absent" no longer implies "off" — and
skills/setup/SKILL.md's dispatch-capability row recommends setting it on precisely that inference,
telling operators to configure something that is already the default and framing its absence as a
capability gap that does not exist.

The agent definitions are less harmful, because their operative instruction — "check whether the
tool is actually there rather than treating the flag as a guarantee" — is correct and survives the
change untouched. Only the stated reason is wrong.

Scope

• Restate all four as availability to be observed, not derived, with each state pinned to its
  version.
• setup's row: report the value against the running version instead of recommending it on a false
  premise.
• research-deep: replace "the Agent tool, which errors even inside a fork" with the invariant
  that actually holds — a fork cannot spawn a further fork.
• Add the caution that a denied spawn is a permission verdict, not a depth verdict: spawns are
  classifier-evaluated before launch (v2.1.178), so the error text is what distinguishes them.

Acceptance criteria

• No file claims absent CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH means nesting is unavailable
• Every behavioral claim is version-pinned so the next default move reads as drift
• The necessary-not-sufficient framing and the check-the-tool instruction are preserved
• check-changed-skills.sh introduces no new warnings