Native nested sub-agents

[Spielewoy]

Feature Description

Native nested sub-agents extend the current sub-agent system beyond one level.

A sub-agent can spawn its own planning, worker, or verifier agents when its task needs to be split further

I've attatched my prompt you can copy over 1:1 to implement this under "Additional Context"

Use Case

I use agents in layers throughout my normal workflow. One parent agent owns a task and delegates focused parts such as planning, research, implementation, and verification to separate children. If one of those tasks becomes large, that child may need to delegate further.

Without nested sub-agents, I have to open and manage more terminals, manually pass context between them.
Also when subagents split their work into more subagents that often leads to better code quality & faster output(in my opinion)

Additional Context

main feature: native nested sub-agents

sub-features required for this:

• recursive tool access
• configurable depth limits
• agent tree state
• named agent resolution
• runtime inheritance
• permission enforcement
• spawn target controls
• tree-wide concurrency
• parent-child result routing
• background agent control
• follow-up messaging
• tree-aware cancellation
• durable child sessions
• reload and resume
• task system integration
• agent tree visibility
• headless lifecycle events
• usage and cost aggregation
• runtime test coverage
• agent runtime cleanup

our harness already has /agents, project and personal agent files, custom agent identifiers, custom system prompts, descriptions, tool allowlists, disallowedTools, per-agent models, maxTurns, permissionMode, background runs, showOutput, dynamic subagent_type registration, and parallel agent calls.

keep all of that working exactly as it does now. parallel calls are already fine. the blocker is that the current runtime removes agent and agent_output from every child, even when its configuration uses tools: "*". that is what prevents a sub-agent from becoming the parent of another sub-agent.

first trace the current implementation end to end. find where the agent tool creates the child loop, where the child toolset is filtered, how foreground and background agents are registered, how agent_output resolves an agent_id, how custom agent definitions are loaded, how permissions and hooks are applied, how sessions and transcripts are stored, how headless events are emitted, and how cancellation works. extend the current architecture and dont touch unrelated working compartments.

make agent and agent_output normal grantable tools for custom agents. tools: "agent, agent_output" needs to work, and tools: "*" should include both when the configured depth allows it. disallowedTools still wins. remove the unconditional filtering that currently makes every hierarchy one level deep.

add proper settings for maximum agent depth, maximum total concurrent agents, and maximum children per agent. depth 0 is the root, depth 1 is its direct child, depth 2 is the first nested child, and so on. use a default maximum depth of 3.

Claude Code exposes CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH for this(in .env), while Codex exposes agents.max_depth in config.toml. Command Code should expose the same capability through its own existing settings system, /config, and --config, using names consistent with the current settings schema.

enforce every limit in the runtime. dont rely on prompts telling the model not to spawn. when the depth limit is reached, remove agent from that child’s available schema and also reject any stale or manually constructed call with a clear structured result containing the current depth and configured maximum. concurrency must be counted across the complete tree. queued children should start when capacity becomes available instead of silently exceeding the limit.

every agent run needs real lineage: agent_id, session_id, parent_agent_id, parent_session_id, root_agent_id, root_session_id, subagent_type, depth, status, timestamps, model, reasoning effort, usage, cost, transcript, and an optional linked task id. use one shared tree registry owned by the root runtime instead of disconnected flat registries.

keep the dynamic named-agent registry at every level. when a definition changes under .commandcode/agents/ or ~/.commandcode/agents/, an allowed child should see the updated subagent_type list on its next turn just like the root does.

preserve the complete selected agent definition for every nested run: name, description, system prompt, tools, denied tools, model, reasoning effort, maxTurns, permission mode, background default, and output behavior. every child still receives its own isolated context and session state.

model: inherit must inherit from the agent that actually spawned the child, not from the root or Command Code’s default. reasoning effort works the same way. a different model or effort may be used when the user explicitly requests it, when the named agent definition explicitly sets it, or when automatic parent selection is enabled through .env.

model selection and effort selection need separate .env controls and must be disabled by default. instructions in the current user prompt override .env, including instructions not to choose another model or effort. a nested child must never silently switch to another model.

inherit the direct parent’s effective environment, cwd, workspace scope, project instructions, skills, MCP tools, hooks, permissions, sandbox runtime when active, and the runtime state already required by a normal child. use the same inheritance path for direct and nested children instead of building a weaker second path for nesting.

permissions must work across the complete tree. the root permission mode, workspace scope, explicit deny and ask rules, and active sandbox are the hard ceiling. a nested agent cannot escape plan mode, enable bypass, access a blocked path, weaken a denial, or widen the root session’s authority.

dont intersect the child’s configured operational tools with the parent’s own file and shell tools. a parent sub-agent may intentionally have only agent and agent_output, while the named child it is allowed to start has edit_file and shell_command. the parent must be allowed to spawn that target, and the child’s actual tool calls must still pass through the root permission pipeline.

target-specific spawn permissions need to use subagent_type. the current permission matcher already understands Agent targets, but createPermissions.check currently allows agent before those rules are evaluated. remove that bypass. support rules such as Agent(writer) and Agent(subagent_type:writer) for allow, ask, and deny. once Agent-specific rules exist, unmatched targets must follow the active permission mode instead of automatically being allowed.

plan mode remains read-only for the entire tree. a child cannot spawn another child to work around it. MCP tools remain unavailable in plan mode, and existing plan-mode hook behavior should stay unchanged.

outside plan mode, hooks need to work for direct and nested tool calls. pass each child’s real session id, transcript, cwd, permission mode, parent, root, type, and depth. a hook may further deny, halt, audit, or inject context, but it cannot override the permission engine or widen authority.

foreground behavior stays simple. the parent calls agent, the child runs, and the final result returns to that direct parent. results move upward one layer at a time. a nested child’s transcript and low-level tool calls should not flood the root model context.

background behavior needs to work at every depth. run_in_background returns an agent_id to the direct parent. that parent can list, inspect, wait for, message, resume, or kill agents in its own subtree. the root can inspect and control the complete tree. unrelated siblings cannot control each other.

add follow-up messaging without forcing a new agent. extend agent_output with a send action or add one small dedicated tool. sending to a running child queues another instruction at the next safe boundary. sending to a completed child resumes the same durable session and context.

cancellation must be tree-aware. killing a parent cancels its live descendants. killing one child affects only that child’s subtree. interrupting an agent_output wait only stops the wait unless kill was explicitly requested. root shutdown must cancel every live descendant and any shell processes owned by them.

persist every child through the existing JSONL session layer. child sessions can stay hidden from the normal resume picker, but they need to appear beneath the root session and remain resumable by exact id. compaction, /reload, restart, and root-session resume must preserve lineage, completed results, and honest statuses. stale in-memory handles must never pretend an agent is still running.

durable means the transcript and resumable session survive. it does not mean a random child process may remain alive after the root exits.

connect nested execution to the existing task system instead of creating another task database. an agent call may reference an existing task id and record the assigned agent and session in that task’s metadata. dont automatically complete a task just because an agent returned.

keep /agents for agent definitions. expose live and completed nested runs through the existing /tree UI, including type, task or description, parent, depth, model, status, duration, current tool, usage, and cost.

headless JSON needs proper nested lifecycle events for start, progress, waiting, follow-up, resume, result, failure, cancellation, and stop. include child, parent, root, session, type, depth, status, usage, cost, and structured failure data. a headless run cannot exit successfully while required foreground descendants are still running.

usage and cost must be correct per agent, per subtree, and for the complete root run. aggregate provider-reported input, output, cache-read, and cache-write usage once. dont count a child result again when it is returned to its parent. unknown pricing must stay unknown instead of becoming zero.

keep the existing one-level workflow working. when maximum depth is 1, direct agents should behave as they do today apart from cleaner lineage and durable ids. existing custom agents, built-ins, parallel batches, background runs, permissions, hooks, models, sessions, and headless behavior cannot regress.

tests need to prove the real runtime:

• root spawns a named parent agent and that agent spawns a named nested child
• the nested result returns to its direct parent before the parent returns its result to root
• a parent with only agent and agent_output can start an allowed child whose own definition has edit and shell tools
• root plan and deny restrictions still block that child from writing
• named prompts, tools, models, efforts, skills, MCP tools, and hooks work beyond depth 1
• explicit model and effort overrides work, while inherit follows the direct parent
• two nested children genuinely run concurrently
• global, per-parent, and depth limits are enforced
• target-specific Agent rules allow and deny the correct subagent_type
• background nested agents support list, status, wait, send, resume, and kill
• killing a parent cancels its descendants without touching unrelated siblings
• failures return to the direct parent without corrupting the root run
• transcripts and lineage survive compaction, reload, restart, and resume
• headless events contain the correct tree metadata
• task state, usage, and cost aggregation remain correct
• no child agent or shell process remains after root termination
• all existing direct-agent and permission tests remain green

inspect the actual package scripts and run the correct commands from the repository. at minimum run the equivalents of pnpm typecheck, pnpm test, pnpm test:integration, pnpm test:non-interactive, and pnpm test:e2e. also run one actual built-CLI headless smoke test proving root to parent agent to nested child through the real runtime, not only mocked unit tests.

after it works, clean up only the touched agent runtime. remove the old flat-only filtering and lifecycle branches, consolidate duplicate lineage state, and update the source docs plus bundled Command Code knowledge. dont turn this into an unrelated runtime rewrite.

done means i can define a parent agent under .commandcode/agents/, grant it agent and agent_output, configure a depth above 1, restrict which named children it may start, and give Command Code one request. that parent can then spawn and manage its own children in foreground or background mode while the complete tree remains inside the root permission and runtime boundary. it must work interactively, headlessly, and after reload or resume. return the files changed, architecture used, every test command and result, the built-CLI smoke-test output, and any real remaining limitation.

How important is this to you?

Important for my workflow