[FEATURE]: Subagent fan-out is bounded by depth but not by breadth #38960

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

subagent_depth bounds how deep a subagent tree can go. Nothing bounds how wide it gets.

A subagent that spawns children in a loop will keep spawning — each child is a real session with real token spend — and the only thing that stops it is someone noticing. Depth 1 hides this today because subagents cannot spawn at all, but that is a side effect of the default, not a guard. Raising subagent_depth removes the only thing standing between a buggy prompt and unbounded fan-out.

The failure mode that matters is sequential, not concurrent: a subagent dispatching one child, waiting, dispatching another, indefinitely. A concurrent-only limit would not see it.

Suggested behaviour

A subagent_max_children config option, enforced at spawn time.

Two details that are easy to get wrong:

• Root sessions should be exempt. A root orchestrator legitimately dispatches hundreds of subagents over a long session. Capping that breaks normal use. The pathological case is a subagent spawning many children, not a human-driven root doing so.
• The count should be lifetime, not concurrent — otherwise the sequential loop above passes straight through.

Version

v1.18.5

Additional context

PR #38954 implements this.