/pi-subagent

name: pi-subagent
description: Delegate tasks to specialized subagents for parallel or sequential execution.

Subagent Orchestration

Use the `subagent` tool to delegate tasks to isolated pi subprocesses. Each subagent gets a fresh context window — no shared state with the parent session.

When to use subagents

• A task can be split into independent pieces that run in parallel
• You need a chain of specialists (scout → planner → worker)
• A subtask benefits from a clean context window (no accumulated noise)
• You want crash isolation (failed subtask doesn't corrupt main session)

Modes

Single — one agent, one task

{ "agent": "scout", "task": "Find all REST endpoints in " }

Parallel — multiple agents concurrently (streams progress as each completes)

{ "tasks": [
    { "agent": "scout", "task": "Audit auth module" },
    { "agent": "scout", "task": "Audit API routes" },
    { "agent": "scout", "task": "Audit database queries" }
  ]
}

Chain — sequential pipeline, use `{previous}` for prior step's output

{ "chain": [
    { "agent": "scout", "task": "Find all TODO comments in the codebase" },
    { "agent": "planner", "task": "Categorize and prioritize these TODOs:\n{previous}" },
    { "agent": "worker", "task": "Fix the top 3 critical TODOs:\n{previous}" }
  ]
}

Per-task options

Every task (single, parallel item, chain step) supports these overrides:

| Option | Type | Description | |--------|------|-------------| | `model` | string | Model override (e.g. `"claude-haiku-4-5"` for fast, `"claude-sonnet-4-5"` for complex) | | `thinking` | string | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | | `extensions` | string[] | Extension paths to load (subagents run with `-ne` — only whitelisted) | | `skills` | string[] | Skill files/dirs to load via `--skill` | | `noTools` | boolean | Disable all built-in tools (`--no-tools`) — for analysis-only agents | | `noSkills` | boolean | Disable skill discovery (`-ns`) | | `cwd` | string | Working directory override |

**Priority:** per-task item > top-level params > agent .md frontmatter > global settings

Examples

**Fast recon with cheap model, no thinking overhead:**

{ "agent": "scout", "task": "Map the auth module", "model": "claude-haiku-4-5", "thinking": "off" }

**Research task needing web search:**

{ "agent": "worker", "task": "Find pricing for Vercel Pro", "extensions": ["extensions/pi-brave-search"] }

**Parallel with different models per task:**

{ "tasks": [
    { "agent": "scout", "task": "Map the codebase", "model": "claude-haiku-4-5" },
    { "agent": "reviewer", "task": "Review the PR diff", "model": "claude-sonnet-4-5", "thinking": "high" }
  ]
}

**Chain with escalating capability:**

{ "chain": [
    { "agent": "scout", "task": "Map the auth module", "model": "claude-haiku-4-5", "thinking": "off" },
    { "agent": "planner", "task": "Plan a refactor based on: {previous}", "thinking": "high" },
    { "agent": "worker", "task": "Implement the plan: {previous}", "thinking": "medium" }
  ]
}

Extension isolation

Subagents always run with `--no-extensions` (`-ne`). They cannot:

• Spawn further subagents (pi-subagent is always blocked)
• Send messages via channels, cron, or heartbeat
• Access the web dashboard or webserver

Whitelist only what a specific task needs via the `extensions` parameter.

Agent scope

• `"user"` (default) — loads from `~/.pi/agent/agents/*.md`
• `"both"` — also includes `.pi/agents/*.md` (prompts for confirmation)
• `"project"` — only project-local agents

Creating agents

Place `.md` files in `~/.pi/agent/agents/` with YAML frontmatter:

---
name: scout
description: Fast codebase reconnaissance
tools: read, grep, find, ls, bash
extensions: extensions/pi-dotenv
model: claude-haiku-4-5
---
System prompt for the agent goes here...

| Frontmatter | Description | |-------------|-------------| | `name` | Agent name (required) | | `description` | What the agent does (required) | | `tools` | Comma-separated tool whitelist | | `model` | Default model | | `extensions` | Comma-separated extension paths to load |

Tips

• **Scout first:** use scout (haiku, fast) for recon, then hand results to planner/worker
• **Parallel for independence:** only parallelize truly independent tasks
• **Chain for pipelines:** scout → planner → worker is the classic pattern
• **Model matching:** use haiku for simple recon, sonnet for analysis/implementation
• **Thinking levels:** `off` for fast tasks, `high`/`xhigh` for complex reasoning
• **Keep extensions minimal:** only whitelist what's actually needed per task