# pi-subagent User Guide

## Concepts

pi-subagent lets you delegate tasks to **subagents** — in-process SDK sessions that run with their own isolated context window. Each subagent is a fresh session: it doesn't share your current conversation history, tools state, or context. This makes subagents ideal for parallelising independent work, keeping expensive or noisy subtasks out of your main context, or applying a specialist prompt to a specific problem.

---

## Defining an Agent

An agent is a `.md` file with a YAML frontmatter header. The body of the file is appended to the agent's system prompt.

```yaml
---
name: my-agent
description: Does a specific thing well
model: anthropic/claude-sonnet-4.6
tools: read,bash,edit
---

You are a specialist in X. Keep responses concise.
Always confirm before making destructive changes.
```

### Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Identifier used when invoking the tool |
| `description` | Yes | Shown in agent listings |
| `model` | No | `<provider>/<id>` format (e.g. `anthropic/claude-sonnet-4.6`). Resolution failure (malformed, not found, no auth) halts the run with an error. Falls back to the SDK default if absent. |
| `thinkingLevel` | No | `off \| minimal \| low \| medium \| high \| xhigh`. Clamped to the model's supported levels by the SDK. Falls back to the SDK default if absent. |
| `tools` | No | Comma-separated list of allowed tools; all tools if absent |
| `extensions` | No | Omit or empty → none; list of paths → exactly those extensions loaded. Supports `${ENV_VAR}` substitution. |
| `skills` | No | Omit or empty → none; list of names → exactly those skills loaded |

### `extensions` and `skills`

Subagents start with **no extensions and no skills** by default. The agent config must list them explicitly.

| Frontmatter | Behaviour |
|-------------|-----------|
| Field absent or empty | No extensions/skills loaded |
| `extensions` with paths (`extensions: /path/a, /path/b`) | Exactly those extensions loaded. |
| `skills` with names (`skills: my-skill, other-skill`) | Exactly those skills loaded. |

---

## Agent Discovery

pi-subagent scans several locations at startup. Agents are loaded in two phases: **user** first, then **project**. Within each phase, later entries overwrite earlier ones on name collision. Because the project phase runs second, **project agents win over user agents** with the same name.

Project-scoped agents are only loaded when the project is trusted.

| Phase | Order (low → high) | Scope |
|---|---|---|
| User | installed packages → user extensions → `~/.pi/agent/agents` | `"user"` |
| Project | installed packages → project extensions → `cwd/.pi/agents` | `"project"` |

---

## Env-Var Substitution in Extension Paths

`${VAR_NAME}` tokens in `extensions` path lists are substituted from `process.env` at load time. Unknown variables are left as-is.

This is useful for extensions that bundle both an agent definition and skills: the extension can register its own install path as an environment variable, and the agent frontmatter can reference it without hardcoding an absolute path.

```typescript
// In your extension's index.ts, set the variable before agents are loaded:
process.env.MY_EXT_DIR = __dirname;
```

```yaml
---
name: my-bundled-agent
description: Agent that uses extensions from the same package
extensions: ${MY_EXT_DIR}/extensions/my-ext
---
```

This works regardless of whether the extension is installed globally, per-project, from git, or from npm.

---

## Modes

### Single Mode

Dispatch one task to one named agent:

```json
{
  "agent": "my-agent",
  "task": "Summarise the changes in the last 10 commits",
  "cwd": "/path/to/repo"
}
```

`cwd` is optional; the subagent inherits the caller's working directory if omitted.

### Parallel Mode

Dispatch multiple tasks concurrently (up to 8 tasks, max 4 running at once):

```json
{
  "tasks": [
    { "agent": "reviewer", "task": "Review src/auth.ts for security issues" },
    { "agent": "reviewer", "task": "Review src/api.ts for security issues" },
    { "agent": "docs-writer", "task": "Write JSDoc for src/utils.ts" }
  ]
}
```

Each task in the array accepts the same fields as single mode (`agent`, `task`, `cwd`).

---

## Tips

- **Keep system prompts focused.** Subagents have isolated context — a tight, specific system prompt produces better results than a general-purpose one.

- **Use `skills:` to prevent skill bleed.** Subagents load no skills by default. If you want to keep it that way, omit the `skills` field or leave it empty.

- **Debug with session logs.** Every subagent run persists a session under `~/.pi/agent/sessions/`. Open the session in pi to replay the conversation and inspect what the subagent did.

- **Name agents clearly.** The calling agent selects subagents by name. A name like `security-reviewer` is easier to select correctly than `reviewer`.