docs(delegation): subagent fan-out is capped at 20 since Claude Code 2.1.217

[elhoim]

Problem

DelegationSystem.md line 67 tells readers:

• Launch as many as needed (no artificial limit)

That is no longer true, and the way it fails is silent.

Why it matters

Claude Code 2.1.217 introduced two runtime ceilings on subagents:

• A cap of 20 concurrently-running subagents. Once reached, further spawns are denied, not queued — a fan-out wider than 20 loses the overflow with no error surfaced to the reader who followed this doc.
• Nested spawning is disabled by default — a subagent can no longer spawn subagents.

Both are overridable, but only if you know they exist. A delegation guide that promises no limit leads users to design swarm patterns that quietly execute partially. The failure mode is the dangerous kind: it looks like it worked.

Fix

Replaces the bare claim with the two ceilings and names the override for each:

• CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS
• CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH

Documentation-only change; no behavior is modified.

Affected versions

Introduced in Claude Code 2.1.217. Any LifeOS install running 2.1.217 or later is affected.

[danielmiessler]

Verified against the official changelog before porting: the 2.1.217 concurrency cap (default 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), the nested-spawn default-off (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH), and both env vars all check out — thank you for tracking harness releases this closely. One nuance: the changelog doesn't actually state denied-vs-queued for over-cap spawns, so our ported wording stays neutral on that.

Context on where it landed: DelegationSystem.md was retired to history-only status on 2026-07-21 (delegation guidance now lives in native harness surface), but the file still ships, and a known-false claim shouldn't ride under a RETIRED banner — so the correction is in with your credit. (Closing rather than merging — generated-repo doctrine.)