# Subagents

The built-in `subagent` tool lets the model delegate tasks to child pi processes, each with its own context window and tools. It is active by default and works with zero configuration: subagents inherit the current model.

Use cases:

- **Independent review**: a subagent with a clean context reviews a diff without the biases and context buildup of the session that wrote it.
- **Second opinions**: a subagent receives a full copy of the conversation and weighs in on a hard problem.
- **Parallel investigation**: several read-only subagents explore different parts of a codebase concurrently, each burning its own context instead of the parent's.

Since sibling tool calls run in parallel, the model can spawn several subagents in one turn. Sequential subagent calls form chains naturally: later calls see earlier results through the parent conversation.

## Context modes

| Mode | What the child sees | When |
|------|--------------------|------|
| `shared` | A fork of the current conversation, plus the task | Default when the child inherits the parent model. The forked prefix is served from the provider prompt cache, so it costs almost nothing. |
| `fresh` | Only the task | Default when the child uses a different model. Also the right choice for independent reviews: a clean context avoids anchoring and context rot. |

`shared` with a different model re-sends the entire conversation uncached. That is acceptable for a one-off consult, but for repeated work prefer `fresh` plus `resume`.

## Resuming

Every subagent result includes an id like `sa-1a2b3c4d`. Passing `resume` with that id continues the subagent with everything it previously read and did still in its context. This is useful for follow-up questions, iterating with the same worker, or continuing after an interruption: child sessions are ordinary session files stored under `<session dir>/subagents/`, so aborted or crashed subagents lose nothing and can be resumed at any time - including after restarting pi.

## Model tiers

By default the only choice is inheriting the parent model. To let the model route work to other models, configure tiers in settings (`/settings` → Subagents, or JSON):

```json
{
  "subagents": {
    "enabled": true,
    "models": {
      "heavy": "anthropic/claude-opus-4-5",
      "medium": "anthropic/claude-sonnet-4-5",
      "light": "google/gemini-2.5-flash"
    },
    "maxConcurrent": 4
  }
}
```

Only configured tiers appear in the tool schema. The intended routing: `heavy` for judgment-heavy consults, `medium` for general implementation and review, `light` for mechanical or read-heavy work. Tier changes made through `/settings` take effect immediately (note that changing the tool schema mid-session invalidates the provider prompt cache prefix once); JSON edits apply on the next session.

## Behavior and limits

- Children run `pi --mode json -p` in the same working directory and rediscover settings, extensions, skills, and context files from there. CLI-only flags of the parent invocation (e.g. `-e`, `--tools`) are not forwarded.
- If the project is trusted in the parent, the child is started with `--approve` so it loads the same project resources.
- Subagents cannot spawn subagents.
- At most `subagents.maxConcurrent` children run at once (default 4); further calls queue.
- Reports returned to the parent are truncated to 2000 lines or 50KB; the full transcript stays in the child session file.
- Aborting the parent (Esc) terminates running children. The error message includes the subagent id for resuming.

Writes should stay single-threaded: parallel subagents are best used for read-only analysis, or for writers with explicitly disjoint file scopes. The tool's prompt guidelines instruct the model accordingly.
