{"name":"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH","slug":"claude-code-max-subagent-spawn-depth","family":"env","title":"Environment variables","noun":"environment variable","description":"Number of [subagent layers](\/docs\/en\/sub-agents#let-subagents-spawn-their-own-subagents) allowed below the main conversation (default: 3). At the default, subagents can spawn their own subagents, and a subagent at the third layer can't spawn further; set `1` to turn nesting off. In v2.1.217 through v2.1.218, the default was 1, so a subagent couldn't spawn its own unless you raised the limit; v2.1.219 raised the default to 3. Accepts a positive whole number in plain digits; anything else is ignored, so the limit can be adjusted but not removed. Requires Claude Code v2.1.217 or later","description_source":"docs","described_by":{"doc":"claude-code\/env-vars","title":"Environment variables"},"presence":{"first_seen":"2.1.217","removed_in":null,"in_current_build":true,"newest_mined":"2.1.309","builds":81,"mined_builds":150,"first_cited":{"version":"2.1.217","released_at":"2026-07-21 19:55:38","spans":1}},"aliases":[],"entries":[{"version":"2.1.238","anchor":"refused-subagent-launches-are-recorded-with-a-reason","heading":"Refused subagent launches are recorded with a reason","line":"A turned-down subagent launch now records whether it hit the nesting cap, the concurrency cap or a budget.","released_at":"2026-08-20 18:01:54","reason":"found in this entry's text"},{"version":"2.1.217","anchor":"worker-agent-system-prompt","heading":"Worker Agent System Prompt","line":null,"released_at":"2026-07-21 19:55:38","reason":"found in this entry's text"}],"entries_total":2,"docs":[{"source":"claude-code","path":"env-vars","title":"Environment variables","documented":true},{"source":"api","path":"build-with-claude\/prompt-engineering\/prompting-claude-opus-5","title":"prompting-claude-opus-5","documented":false},{"source":"claude-code","path":"agent-sdk\/subagents","title":"Subagents in the SDK","documented":false},{"source":"claude-code","path":"sub-agents","title":"Create custom subagents","documented":false}],"docs_total":4,"gates":[],"related":[{"name":"CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION","slug":"claude-code-max-subagents-per-session","description":"Removed in v2.1.224 and now a no-op. Previously capped the total number of [subagents](\/docs\/en\/sub-agents) Claude could spawn with the Agent tool in one session (default: 200); spawning past the cap failed with `Subagent spawn limit reached`. The [concurrent subagent limit](\/docs\/en\/sub-agents#concurrent-subagent-limit) and the [depth limit](\/docs\/en\/sub-agents#let-subagents-spawn-their-own-subagents) still apply"}],"url":"https:\/\/changelogs.core-directive.com\/reference\/env\/claude-code-max-subagent-spawn-depth","family_url":"https:\/\/changelogs.core-directive.com\/reference\/env.json"}