Nested subagent spawn depth silently defaulted 1 → 3 in CC v2.1.219 — set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH explicitly fleet-wide

[olegbrok]

What changed

Claude Code v2.1.219 (2026-07-24):

"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"

We are on v2.1.220, so this default is already live on every agent host.

Why it matters here

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH is not set anywhere in this repo or in .env — verified by grep. So we silently inherited a change from "a subagent cannot spawn subagents" to "a subagent can spawn subagents, which can spawn subagents."

That interacts badly with two things we already know about this fleet:

1. The inflight watchdog kills long fan-outs. Operational experience puts the safe ceiling around 4–5 concurrent agents before the watchdog starts declaring wedges on the parent. Depth-3 nesting multiplies rather than adds: a parent spawning 4, each spawning 4, each spawning 4 is 64 concurrent agents from one dispatch that previously capped at 4.
2. Cost and rate limits are per-fleet, not per-agent. A nested fan-out on Opus 5 at 1M context is not a marginal cost, and nothing in our current setup bounds it.

Neither of these is hypothetical breakage — no incident has been attributed to this yet. The point is that the blast radius of a single dispatch changed underneath us without a decision, and the fix is one line of config.

Suggested

• Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH explicitly, fleet-wide, to whatever we actually want. 1 restores the prior behaviour and is the conservative default; 2 is defensible if we want one level of nesting for genuinely hierarchical work. The value matters less than it being chosen rather than inherited.
• Put it where agent env is set for all transports, not just one — a setting that lands on tmux agents but not Codex agents (or vice versa) is worse than either default, because the fleet then behaves inconsistently under load.
• Consider whether the workflow-size guideline (workflowSizeGuideline, also new in v2.1.219, default "medium / under 15 agents") should be pinned in settings for the same reason: it is advisory, but an advisory default we didn't choose is still a default we didn't choose.

Related, lower priority — a stale model row that can now only fail

Also in the 2026-07-24 API notes: fast mode was removed for claude-opus-4-7, and unlike 4.6 it does not fall back to standard speed — requests with speed: "fast" now error outright.

No registered agent is on 4.7 (roster checked via list_agents), so nothing is broken. But claude-opus-4-7 is still offered as a selectable model in agent_registry.py:4720 and priced in pricing.py:136. Anyone who picks it and fast mode now gets a hard error with no fallback. Worth either removing the row or marking it standard-speed-only, whenever the model tables are next touched.

---

🤖 Filed by Barsik