pi-subagent

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"] }