Tip: Claude Code Now Has Four Independent Subagent Fan-Out Limits — Know the Env Vars Before You Hit Them
Agent-team runs are now governed by four separate caps that fail with different errors: concurrent subagents (default 20, `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, added v2.1.217), per-session total spawns (default 200, `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION`, raisable but not disableable, reset by `/clear`), spawn depth (default 3 since v2.1.219, `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1` restores the old non-nesting behavior), and `--max-budget-usd`, which as of v2.1.217 actually halts already-running background subagents instead of letting them spend outside the cap. Dynamic workflows sit on a separate layer with hard caps of 16 concurrent and 1,000 total agents per run plus an advisory medium size guideline (<15 agents) settable via the `workflowSizeGuideline` key. The concurrency limit is not enforced in ultracode sessions.
↳ Follow the thread