Claude Code subagents spawn grandchildren, depth set by env var CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH

The test used a four-layer chain in which each layer was told to delegate to the next, and the last layer was told to answer itself. The JSON output's subagent_stats field, rather than the AI's narration, provided the count: spawned=3, max_depth=3, spawned_by_subagents=2, completed=3, failed=0, with by_type showing layer1, layer2, and layer3. The prepared layer4 did not appear. This pattern held across three runs with no byte-level differences, which is why the author concluded that grandchildren were reached but a fourth layer was not.

Setting the environment variable changed the picture. With values 1, 2, 3, 4, and 5, all 13 runs matched the requested depth, and the author notes that raising the value also takes effect, so 3 is not a ceiling. A related observation concerns visibility: refused.depth_limit was 0 in all 39 runs, and a subagent at the nesting limit is normally not offered the tool itself. The search for a grandchild that is not running therefore returns no error, which the author says caused confusion.

The most difficult part was the first four runs, which stalled at one tier despite the same settings later reaching three. A remote feature flag name, maxSubagentSpawnDepthFromGrowthBook, appeared in the executable alongside other remotely fixed values, but the flag's value is not externally visible, so the cause remains unverifiable. Hooks also could not distinguish child from grandchild: across 175 logged lines, no key contained depth or parent information. For practitioners, the practical reading is that depth-sensitive designs may be safer with an explicit environment variable rather than relying on the default.