coderClaw

Sub-agents

Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (agent:<agentId>:subagent:<uuid>) and, when finished, announce their result back to the requester chat channel.

Slash command

Use /subagents to inspect or control sub-agent runs for the current session:

/subagents info shows run metadata (status, timestamps, session id, transcript path, cleanup).

Spawn behavior

/subagents spawn starts a background sub-agent as a user command, not an internal relay, and it sends one final completion update back to the requester chat when the run finishes.

Primary goals:

Cost note: each sub-agent has its own context and token usage. For heavy or repetitive tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model. You can configure this via agents.defaults.subagents.model or per-agent overrides.

Tool

Use sessions_spawn:

Tool params:

Allowlist:

Discovery:

Auto-archive:

Nested Sub-Agents

By default, sub-agents cannot spawn their own sub-agents (maxSpawnDepth: 1). You can enable one level of nesting by setting maxSpawnDepth: 2, which allows the orchestrator pattern: main → orchestrator sub-agent → worker sub-sub-agents.

How to enable

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
        maxConcurrent: 8, // global concurrency lane cap (default: 8)
      },
    },
  },
}

Depth levels

Depth Session key shape Role Can spawn?
0 agent:<id>:main Main agent Always
1 agent:<id>:subagent:<uuid> Sub-agent (orchestrator when depth 2 allowed) Only if maxSpawnDepth >= 2
2 agent:<id>:subagent:<uuid>:subagent:<uuid> Sub-sub-agent (leaf worker) Never

Announce chain

Results flow back up the chain:

  1. Depth-2 worker finishes → announces to its parent (depth-1 orchestrator)
  2. Depth-1 orchestrator receives the announce, synthesizes results, finishes → announces to main
  3. Main agent receives the announce and delivers to the user

Each level only sees announces from its direct children.

Tool policy by depth

Per-agent spawn limit

Each agent session (at any depth) can have at most maxChildrenPerAgent (default: 5) active children at a time. This prevents runaway fan-out from a single orchestrator.

Cascade stop

Stopping a depth-1 orchestrator automatically stops all its depth-2 children:

Authentication

Sub-agent auth is resolved by agent id, not by session type:

Note: the merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet.

Announce

Sub-agents report back via an announce step:

Announce payloads include a stats line at the end (even when wrapped):

Tool Policy (sub-agent tools)

By default, sub-agents get all tools except session tools and system tools:

When maxSpawnDepth >= 2, depth-1 orchestrator sub-agents additionally receive sessions_spawn, subagents, sessions_list, and sessions_history so they can manage their children.

Override via config:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

Concurrency

Sub-agents use a dedicated in-process queue lane:

Stopping

Limitations

This site is open source. Improve this page.