Claude Code caps subagent fan-out at 20 by default

Claude Code 2.1.217 adds a concurrency cap on subagents, one of two backstops against runaway fan-out in this release. It defaults to 20 running at once and is overridable with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, per the changelog.

One message can no longer spawn unbounded background work. Raise the default for a job that genuinely needs more parallel agents, but the safety net stays on unless you say otherwise.

The same release fixes --max-budget-usd, the flag meant to cap total spend. It previously enforced that ceiling on foreground work only, per the changelog. Now, once the budget cap hits, new subagent spawns get denied and any background agents already running halt.

That's the wrong half to protect by default. Foreground work is what a person watches in real time and can kill by hand at will.

Background subagents run overnight or inside unattended CI. That's exactly where a runaway task needs a limit that actually applies, not one that quietly stops working once nobody's watching.

The budget fix matters more here than the concurrency cap. A spending ceiling that silently skipped background work is the bigger miss, because that's exactly where unattended cost adds up unnoticed. Anyone running Claude Code headless should re-test background runs against --max-budget-usd, confirming it stops the job rather than slowing it.