← Docs

Delegation

Delegation lets a session’s agent hand scoped tasks to other sessions — subagents — that run in parallel and feed their results back into the parent’s reasoning, so one agent can truly orchestrate work across multiple assistants at once.

A delegator is any session whose agent has a roster of allowed subagents. Each subagent is an ordinary child session running its own agent in the background. The parent continues its turn immediately (spawn-and-return), so it can issue multiple delegations that execute concurrently.

If an agent is the assistant you chat with, and a session is one conversation with it, then delegation is how one conversation spawns others to multiply what you can do in a single prompt.

Rostering subagents

A delegating agent must be configured with a roster — the set of agent ids it is allowed to delegate to. Add, remove, enable, or disable rostered agents on the agent’s edit page under Sub-Agents. An agent can be added to a roster only if it has a provider and model pinned, so delegate targets are always resolvable at spawn time.

Disabled agents remain in the roster (grayed out) and can be re-enabled later; delegating to a disabled agent returns a clear error. Deleted agents are silently dropped from the roster with a log warning.

The delegate tool

When a session has a non-empty roster and no parent, its tool set includes a delegate tool. The tool’s agent_id parameter is an enum constrained to exactly the rostered ids, so the model cannot name an off-roster agent.

The call signature:

delegate({ agent_id: <rostered id>, prompt: string, worktree?: string })

It returns immediately:

{ "child_session_id": "sess-…", "status": "spawned" }

The child runs one full turn with the prompt as its first user message. Its terminal assistant message becomes the result.

Depth is limited to one level: a child session never receives the delegate tool, so subagents cannot spawn further subagents.

Async parallel runs and results

Delegations run truly in parallel. The delegator receives each finished child’s result in a result inbox. When at least one result is ready, the parent is automatically woken (auto-wake) with an injected message listing all currently queued results (coalescing). Results arriving while the parent turn is already running wait for the next wake.

Each result is labeled with the child’s session id, agent id, status (done, interrupted, error, or needs_decision), an optional reason, and the worktree name, so the delegator can tell children apart and understand what finished.

Interrupted or errored children are delivered as clearly-labeled partials.

The Subagents panel

The Subagents panel shows the live delegation tree as a caret tree hierarchy under each parent session. Each child displays its status (running, done, interrupted, error, needs_decision) and updates live.

You can open a running child from the panel to watch it without stopping it. A writer-conflict badge flags a child whose edits would touch the parent’s HEAD — already-done children are excluded, since their work is settled.

Where the panel lives

The panel is dual-mounted per workspace, via Settings → Appearance → Subagents panel position:

  • Explorer (default) — the panel lives inside the Explorer card, alongside the project’s Diff and Files modules.
  • Chat — the Explorer card hides and the panel renders full-width above the transcript, suited to keeping the delegation tree in view while reading a long conversation.

Caret nodes auto-expand when a child first appears under a parent, so a fresh delegation doesn’t stay collapsed. Once you collapse a branch by hand it stays collapsed — your manual choice sticks across kills, kills-all, and new turns.

The panel reconciles itself after the kill-subagents shortcut fans out: cleared children disappear, running ones stay.

Killing subagents

Stopping the parent and stopping its children are separate actions. Press Esc to stop the parent turn only — children keep running.

To stop children, use:

  • Ctrl+B K — kill every child of the current session (the “Kill all subagents” action). Press the leader to open the which-key menu, then K; you can also run it from the command palette, or remap it from Settings → Hotkeys.
  • Per-child buttons in the Subagents panel — kill one child without touching the others.

“Kill all” warns before discarding uncommitted work, so a child’s edits in an isolated worktree aren’t lost silently. See Keyboard shortcuts for the binding and remapping.

Parallel cap

The fan-out cap is the upper limit on how many subagents a parent can spawn in parallel per turn. Set it from Settings → Appearance → Max concurrent subagents — the default is 3, with a clamped range of 1–20. Above the cap, additional delegate calls in the same turn queue and start as running children free up.

Worktree isolation

By default, a subagent shares the parent’s worktree. You can override this:

  • Omit worktree or name the parent’s current one → shared worktree. Read-only helpers (reviewers, explorers) need no special setup.
  • Supply a different worktree name → the child gets an isolated worktree reused or created off the parent’s commit, so it can edit and commit safely without affecting the parent.

In a shared, live worktree, file edits proceed but git commit is refused while the parent is live, preventing the child from rewriting the parent’s HEAD. Isolated worktrees permit commits; they persist as orphaned branches for later manual merge.

See Worktrees for the full picture.

Non-interactive subagents

A non-interactive subagent never pops a modal or waits for human input. If it hits a hook that would normally ask a question, it self-terminates and reports the question in its result so the parent (or you) can resolve it. This keeps parallel delegations from ever blocking on a single subagent.