docs/config: subagent_depth defaults to 1 and is undocumented, so subagents can't delegate #59826

Activity

1. opencodejr commented on Oct 28, 2026

   

   opencodejrBot

   on Oct 28, 2026

   Contributor

   More actions

   Thanks for the clear write-up, @srobroek!

   You're asking for the default experimental.subagent_depth to allow at least one nested level (main → specialist → explore), or for the setting to be easier to find. Maintainers will consider it.

   Some context:

   • The default of 1 is intentional. The depth check in packages/core/src/tool/plugin/subagent.ts uses subagent_depth ?? 1, and the tests expect nesting to be blocked unless you raise the setting.
   • The setting is in the V2 docs, but only in the Experimental section of the config page ("Subagent depth"). It says the default is 1, so a subagent cannot start another subagent. It isn't mentioned on the agents page, which is probably where most people look when designing delegating agents.
   • Your workaround is the supported way to allow nesting:

     {
       "experimental": { "subagent_depth": 2 }
     }

     2 allows main → subagent → subagent; use higher values for deeper chains.

   Related issues:

   • subagent: tool remains advertised at the maximum session depth #53356: at the depth limit, subagents are still offered the subagent tool, so they try to delegate and fail with this error.
   • [FEATURE]:can subagent create subagent？my context is low and task is heavy #50539: a feature request for subagents to create subagents.
   • Desktop: running-subagents indicator never shows nested subagents (subagent_depth > 1) #58489: nested subagents (subagent_depth > 1) don't show in the Desktop running-subagents indicator.
   • feat(opencode): allow general nested task via depth #47106: a closed PR about nested delegation for the built-in general agent.