$ pi –delegate

TL;DR. A pi subagent is a separate pi process the parent spawns to do bounded work in an isolated context window. The official subagent example extension registers a task tool that supports three modes — { agent, task } for single, { tasks: [...] } for parallel (up to 8 tasks, 4 concurrent), and { chain: [...] } for sequential hand-offs. Agents are markdown files under ~/.pi/agent/agents/ (user-scope) or .pi/agents/ (project-scope, opt-in via agentScope: "both"); markdown frontmatter declares the system prompt, allowed tools, and model. The parent receives structured output, per-task usage (turns, tokens, cost, context), and can abort with Ctrl+C. Third-party projects (pi-flows, pi-tmux-orchestrator, dsh-pi-agent, pi-goal-list-loop-audit) all build on the same primitive: spawn a fresh pi subprocess and let it return a result.

This guide explains the official extension first, then the trust model and configuration knobs, then how the rest of the ecosystem wraps the same idea. It follows the Extensions reference and the subagent example in packages/coding-agent/examples/extensions/subagent.

What a subagent is

A subagent is a separate pi subprocess the parent session launches for a single bounded task. Because it runs in its own process and its own context window, the parent’s conversation stays focused on the decision, not on every file the child opened. Three properties make subagents useful in practice:

Isolated context. Each child starts with a fresh, narrow context. The parent’s accumulated tool call history, scratch reads, and conversation do not bleed into the child’s prompt. The child sees only the delegated task, the agent’s system prompt, and the working directory.
Streaming output. The parent can show the child’s tool calls and progress live, not just the final answer. Parallel mode streams all running tasks simultaneously.
Usage accounting. Each child returns its usage (input / output / cache read / cache write / cost / turns), which the parent surfaces in its footer and aggregates into session totals.

A practical consequence: a 50-file refactor that would otherwise bloat the parent session becomes a single delegated task that returns a diff.

The official subagent extension

The pi repository ships a reference implementation under packages/coding-agent/examples/extensions/subagent. It registers a task tool whose parameter shape selects the mode:

// Single — one agent, one task
{ agent: "scout", task: "Find all authentication code in /src" }

// Parallel — up to 8 tasks, 4 concurrent
{
  tasks: [
    { agent: "scout", task: "Find model definitions" },
    { agent: "scout", task: "Find provider implementations" }
  ]
}

// Chain — sequential, each step can reference {previous}
{
  chain: [
    { agent: "scout", task: "Map the auth surface" },
    { agent: "planner", task: "Plan a refactor for {previous}" },
    { agent: "worker", task: "Implement the plan from {previous}" }
  ]
}

Internally the extension spawns each child as a separate pi process and reads its output via JSON mode — the same headless interface covered in the rpc-and-json-mode guide. The implementation reuses the parent’s getAgentDir, the CONFIG_DIR_NAME constant, and the markdown theme for rendering.

Agent definitions

Agents are markdown files with frontmatter, not TypeScript modules. The discovery convention is:

Location	Scope	Default behavior
`~/.pi/agent/agents/*.md`	user	Always loaded
`.pi/agents/*.md`	project	Opt-in via `agentScope: "both"`

A minimal agent file looks like:

---
name: scout
description: "Fast recon, returns compressed context"
tools: [read, grep, find, ls]
model: claude-haiku-4-5
---

You are a read-only scout. Inspect the codebase for the requested information and return a compressed summary. Do not modify any files.

The frontmatter declares the agent name, a one-line description, the allowed tool set, and the model. The body is the system prompt. The subagent example ships four sample agents (scout, planner, reviewer, worker) and three workflow prompts (implement, scout-and-plan, implement-and-review) under agents/ and prompts/.

The reference impl uses MAX_PARALLEL_TASKS = 8 and MAX_CONCURRENCY = 4, with a PER_TASK_OUTPUT_CAP of 50 KiB per task. Outputs beyond the cap are truncated before they hit the parent context. Items beyond COLLAPSED_ITEM_COUNT = 10 are collapsed in the TUI and need a click to expand — this keeps long parallel runs readable.

Trust and scope

Project-local agents live in the repository and can instruct the model to read files, run bash commands, or take any other action the parent model can take. The reference impl therefore ships with a conservative default: only user-level agents from ~/.pi/agent/agents/ are loaded. To opt in to project-local agents, pass agentScope: "both" (or "project") when configuring the tool. Only do this for repositories you already trust.

When agentScope: "both" is set, the tool prompts for confirmation before running a project-local agent in an untrusted project. Trusted projects skip the prompt. To disable the confirmation entirely (for fully-trusted setups), set confirmProjectAgents: false.

The trust plumbing is consistent with how the rest of pi handles project-local state: project-local extensions, skills, agents, and prompts all gate on the same defaultProjectTrust setting the installation-and-updates guide describes. There is no separate trust model for agents.

Running a subagent interactively

In a pi session, the parent LLM calls the task tool when the user’s request maps to delegated work. From the user’s perspective:

> Scout the codebase for everything related to authentication.

pi delegates this to `scout` and returns the findings. You do not name an agent or write JSON — pi reads your intent and picks.

To be explicit, name the agent or pass the exact call shape:

> Use scout to find the authentication entrypoints.

> Use task with {"agent": "scout", "task": "find auth entrypoints"}

For a broader task that needs planning first:

> Document login, refresh, and session storage. Have overwatch review
> the breakdown before the research starts.

The reviewer can request a bounded revision. Workers start only after the breakdown receives PASS.

Ctrl+C propagates to the running children — the subagent extension wires process.kill into the parent’s abort signal so a long-running parallel sweep can be cancelled cleanly.

Extending the same primitive

The official extension is the simplest possible implementation. The same primitive — spawn a separate pi process and let it return a result — is what the rest of the multi-agent ecosystem builds on:

pi-flows registers a flow tool with 15 delegation modes (single, parallel, chain, evaluate, vote, route, orchestrate, graph, loop, search, workflow, worktree, and presets). It adds budget enforcement (cost / token caps), OpenInference-shaped JSONL traces, contract validation on returned results, and a /flows report viewer.
pi-tmux-orchestrator does the same delegation inside a six-pane tmux grid with a Unix-socket broker. Implementer, reviewer, and optional probe agents each run as their own pi child, with the broker dashboard showing workflow, role, model, usage, and recent metadata.
dsh-pi-agent runs a headless pi --mode rpc --no-session child as the DSH AgentFactory. Every DSH session is then driven by the pi child; the plugin also exposes a SubagentProvider row so tool-subagent with provider: pi spawns fresh pi -p <task> processes per delegation.
pi-goal-list-loop-audit spawns an auditor worker as a fresh, extension-less pi RPC process. The auditor has read / grep / find / ls / bash in intentional power mode and cannot see the implementing conversation or its parent state — the separation of implementation from verification is enforced by the process boundary.

The pattern across all four: a separate pi process, an isolated context, structured output back to the parent. The official subagent example is the right starting point; everything else is a wrapper around it.

When NOT to use a subagent

A subagent is not the default. Simple answers, obvious shell commands, tiny edits, and quick single-file lookups are cheaper and clearer in the parent session. The cost of delegation is the cost of a fresh pi subprocess plus the boilerplate of marshalling the request and the result through JSON mode. Use a subagent when the next step would make your parent session noisy, expensive, or hard to trust — not before.

A small delegation checklist

Decide between user-scope and project-scope agents. User-scope agents always load; project-scope agents require agentScope: "both" plus confirmProjectAgents left at default.
Pin the agent’s tool set in its frontmatter. A scout agent that can write or edit defeats the read-only intent; even the bundled sample scout ships with bash for read-only inspection but omits write/edit entirely.
Pin the model. Different agents should use different models — a scout does not need the most expensive frontier model.
Surface usage. Each delegated task should return its usage so the parent can aggregate it into the footer and /session.
Wire abort. Ctrl+C must propagate to running children; partial results should not pollute the parent context.

Subagents and Delegation