Subagents

pw code can split work across subagents: helper agents that each run their own agent loop and report back. When a request contains independent pieces (a broad search, a refactor across many files, a research question), the agent can delegate each piece to a subagent instead of doing everything itself, and independent pieces run at the same time.

Each subagent:

• Starts with a fresh context: it sees none of your conversation, so the agent hands it a self-contained brief.
• Works in the same directory: it shares your working tree and your MCP tools, so its edits land in the same files you are looking at. (Custom agent types can opt into an isolated worktree instead; see Custom Agents.)
• Reports back a summary: when it finishes, its report is delivered into the main conversation.

The agent decides when delegating is worthwhile, and you can also ask for it directly: "delegate these three fixes to subagents" or "research this in the background while we keep working." This page covers how delegation behaves, the agent switcher, follow-ups, forks, models, persistence, and limits.

Background and Inline Delegation

• Background by default: when the agent delegates, the main conversation continues immediately; the subagent works on its own. When it finishes, its report arrives in the main conversation as a completion notice. If the session is sitting idle, the arrival wakes it so the agent can act on the result without you typing anything.
• Inline when a step depends on it: when a later step in the same turn depends on the result, the agent waits for the subagent and receives the report directly.
• Concurrent: several subagents launched in one turn run in parallel, up to the concurrency limit (10 by default; more wait for a free slot).
• Interim messages: if a running subagent hits a load-bearing finding or a blocker mid-task, it can surface an interim message to the main conversation and keep working. The main agent can answer with direction the same way you would (see Following Up below).
• Stopping is never silent: if you stop a subagent yourself, the main agent is told it was interrupted and returned no result; it can still be resumed later by its ID.

Whether it runs in the background or inline, every subagent has an ID like task-2 that appears with its report and is used for follow-up work.

The Agent Switcher

Once the session has at least one subagent, the agent switcher appears below the composer (one row per agent, starting with main). Each row shows a colored status dot, the agent's name, its custom agent type (when it has one), and a live activity line such as the file it is reading or Done (...). The footer hints ↓ for agents.

Press ↓ at the composer (past any input history; on a multi-line draft, with the cursor on the last line) to move the selection into the switcher. Your draft is preserved.

Typing any other key returns you to the composer and is handled normally.

Viewing and Prompting a Subagent

Selecting an agent with Enter switches you into its window: its full transcript, with its own composer. Each window keeps its own half-typed draft, so switching around never loses what you were writing.

You can prompt a subagent directly from its window, including after it has finished its task, which resumes it with its conversation intact. Press Esc while viewing a running subagent to stop it.

Task Blocks in the Transcript

In the main transcript, each delegation renders as a task block titled Task(description) (or the agent type's name for custom agents) with a colored dot matching the agent's switcher row. Collapsed (the default), a block shows a spinner and the latest action while running, then a one-line Done (...) summary:

Press Ctrl+O to expand it into the full step-by-step activity feed, and again to collapse it (clicking the block also works when mouse clicks are enabled in /settings).

The moment a background subagent's report reaches the conversation is also marked in the transcript, so you can see exactly when the main agent learned the result.

Permission Prompts from Subagents

When a subagent needs approval for a permission-gated command, the prompt appears in your session and names which agent is asking. Approvals you grant this way apply to that subagent only. Changing the session's permission mode while subagents are running applies to them immediately, in both directions. A custom agent definition can narrow a subagent's permissions but never widen them; see Permission Clamping.

Following Up

Every subagent report includes the subagent's ID (for example task-3). The main agent can send follow-up work to that ID, and the subagent picks it up with its full context retained, so there is no need to re-explain the task. Just ask: "have the same agent also update the tests."

If the subagent is still working, the follow-up is delivered mid-task as a course correction instead, and the original task continues with the new direction applied.

Follow-ups do not count against the per-session subagent budget, and they survive restarts: see Persistence and Resume.

Forking the Conversation

/fork <task> spawns a background subagent seeded with your conversation's full history (everything discussed so far) and sets it to work on the task. Use it for side-work that needs all the context you have built up, without derailing the main thread:

/fork write up the migration plan we just discussed as a design doc

• The current conversation is unaffected; the fork runs in the background in the same working tree.
• Check on it with ↓ like any other subagent; its result lands back in the main conversation, and you can follow up by its ID.
• /fork works from the main session only, and a fork cannot fork again.
• A fork always stays on the session's model, even when a subagent default model is set.

Models for Subagents

By default a subagent inherits the session's model. You can point delegated work at a different model (for example a cheaper, faster model for mechanical tasks) at several levels, where later ones win:

1. The session's model: the baseline every subagent inherits.
2. The subagent default: set via /settings → Subagent model (it shows (inherit session) when unset) or the subagentModel key in settings.json. Applies to all delegated tasks.
3. The agent definition's model: key: a custom agent type can name its own model.
4. A per-delegation choice: the agent can pick a model for one specific delegation ("use the small model for this"); that choice sticks for follow-ups to the same subagent.

Two exceptions: forks always keep the session's model, and changing the subagent default never changes the session's own model. See Models & Allocations.

Persistence and Resume

Subagents persist with their session:

• Stored beside the parent session: subagent transcripts live under their parent session's storage, never as standalone sessions, so they do not appear in the session picker.
• Revived on resume: pw code -r <session> brings every persisted subagent back as an idle agent in the switcher, with its conversation intact. You can view it, prompt it, and the main agent can send it follow-up work by its old ID.
• Hibernated when finished: a finished background subagent releases its conversation from memory until you view or prompt it, so sessions with many subagents stay light.
• Swept with the session: if you have enabled the session retention sweep (sessionRetentionDays), it deletes a session's subagent transcripts along with the session. See Sessions & Resume.
• Dirty worktrees survive: an isolated worktree holding uncommitted changes or new commits is kept, and resuming the session re-adopts the subagent inside it; see Worktree Isolation.

Non-Interactive Mode

In a one-shot run (pw code -p), there is no later turn to deliver a background result into, so every delegation runs inline: the agent waits for each subagent, and no work is lost when the process exits. For the stderr progress format and the usage roll-up, see Subagents in One-Shot Runs.

Limits and Controls

Example settings.json excerpt:

{
  "subagentModel": "owner:provider-name/small-model",
  "subagentConcurrency": 6,
  "subagentDepth": 1,
  "disableSubagents": false
}

See Settings for where settings files live.

Related Documentation

• pw code Overview: Feature overview and quick start
• Custom Agents: Define reusable agent types with their own tools, model, and prompt
• Permissions: Permission modes and approvals
• Sessions & Resume: Session storage, the picker, and retention
• Settings: The /settings menu and settings.json
• Non-Interactive Mode: One-shot runs with -p