subagent

Asynchronous subagent delegation for pi. Run specialist agents in dedicated child sessions, share main-session context when needed, and receive results as completion notifications.

[!WARNING] Subagents run headlessly as pi child processes without approval prompts and can use every tool declared by their agent definition. This extension is not a sandbox. Use trusted repositories, prompts, and agent definitions only.

Install

Requires pi 0.80.6 or later. Compatibility is tested with pi 0.80.7.

pi install npm:@ryan_nookpi/pi-extension-subagent

Quick start

Create a global agent at ~/.pi/agent/agents/worker.md, or a project agent at .pi/agents/worker.md:

---
name: worker
description: Implements requested changes
thinking: medium
tools: read,bash,edit,write
---

Implement the requested changes and verify them.

Then launch it from pi:

/sub:isolate worker implement the requested change and run tests

Equivalent AI tool call:

{ "command": "subagent run worker --isolated -- implement the requested change and run tests" }

Tool launches are asynchronous. Wait for the automatic completion or failure notification instead of polling immediately. Both are sent as steer messages, so the agent can use the results after its current response and tool batch finish, without waiting for the whole agent run to end. Pi drops queued messages when you press Escape; if a completion was still queued when the run stops, it is added to the session without starting a new turn, and the agent sees it with your next message.

Agent definitions

Agent files use YAML frontmatter followed by the system prompt. name and description are required.

Field	Description
model	pi model ID
thinking	off, minimal, low, medium, high, xhigh, or max
tools	Comma-separated tool names

Omitted optional fields use pi defaults. Every agent runs on pi. A legacy runtime field is ignored, except runtime: claude, which is no longer supported and marks the agent invalid.

Agents are discovered in this order; later definitions override earlier agents with the same name:

1. $PI_CODING_AGENT_DIR/agents/*.md (normally ~/.pi/agent/agents/*.md)
2. Nearest .claude/agents/**/*.md
3. Nearest .pi/agents/*.md

.claude/agents is searched recursively. .pi/agents is not.

Run /subagents, subagent agents, or the list-agents tool to inspect discovered agents.

Optional starter pack

If no agents are found, /subagents can offer an optional, opinionated starter pack. It copies eight agent templates, two workflow skills, and missing global subagent settings. Existing files and configured values are not overwritten.

The two skills are installed into $PI_CODING_AGENT_DIR/skills and become available after /reload:

Skill	Purpose
stress-interview	Cross-review one target with verifier, reviewer, and challenger in parallel, then compare their findings
self-healing	Run at most two stress-interview cycles and apply evidence-backed worker fixes between them

/skill:stress-interview review the staged diff in packages/subagent before release

Both skills expect the starter agents, so they report a missing agent instead of silently reviewing with one.

If you already defined your own agents, the full pack is never offered. In that case /subagents offers only the workflow skills that are missing, and it leaves your agents and settings untouched.

The starter pack is not required. Decline it if you prefer to define agents manually.

Context modes

• --isolated starts without copying the main conversation. It is the default for tool launches.
• --main passes selected main-session context to the child.
• /sub:isolate and /sub:main provide the same choice for interactive commands.
• Continuing a run preserves its original child session and context mode.

Active child processes stop when pi replaces or reloads the parent extension runtime. This follows pi's official extension lifecycle guidance.

Tool interface

The extension registers two tools:

• list-agents lists discovered agents and their settings
• subagent executes a CLI-style command string

These strings are tool input, not shell commands. Do not run them in Bash.

subagent help
subagent agents
subagent runs
subagent run <agent> [--main|--isolated] -- <task>
subagent continue <runId> [--agent <agent>] [--main|--isolated] -- <task>
subagent batch [--main|--isolated] --agent <agent> --task <task> ...
subagent chain [--main|--isolated] --agent <agent> --task <task> ...
subagent status <runId|groupId>
subagent detail <runId|groupId>
subagent abort <runId|groupId|runId,runId|all>
subagent remove <runId|runId,runId|all>

batch runs independent tasks in parallel:

{
  "command": "subagent batch --main --agent worker --task \"implement feature A\" --agent reviewer --task \"review feature B\""
}

chain runs steps sequentially and gives each step the previous result as reference:

{
  "command": "subagent chain --isolated --agent worker --task \"implement the change\" --agent reviewer --task \"review the implementation\""
}

Use status and detail for one-off inspection, not polling loops.

Interactive commands

Command	Description
/subagents	List agents, offer the starter pack when none exist, and offer missing workflow skills otherwise
/sub:main [agent|runId] <task>	Launch or continue with main-session context
/sub:isolate [agent|runId] <task>	Launch or continue with isolated context
/sub:peek [runId]	Show the latest result
/sub:open [runId]	Open the child session replay
/sub:history	Show run history, including removed runs
/sub:abort [runId|all]	Abort running work
/sub:rm [runId]	Remove a run, aborting it first if necessary
/sub:clear [all]	Clear finished runs, or all runs

When an agent is omitted, launch commands use defaultAgent.

Shortcuts

Shortcut	Description
>> [agent|runId] <task>	Visible run with main-session context
> [agent|runId] <task>	Hidden run with main-session context
#<runId> <task>	Continue a run
>><symbol> <task> / ><symbol> <task>	Run an agent from symbolMap
<>runId	Peek at a result
<< [runId|runId,runId]	Abort running or clear finished runs
<<< [all]	Clear finished runs, or all runs

Hidden runs are available only in the interactive UI and do not add start or completion messages to the main transcript.

Prompt mentions

Use >agent-name inside a prompt to reference a discovered agent. Exact names are highlighted and rewritten to subagent:agent-name before the main LLM receives the prompt; they do not launch a run directly. Unknown names remain unchanged.

Delegate implementation to >worker and review to >reviewer.

A mention has no space after >. Launch shortcuts remain separate, such as > worker implement this.

Configuration

Global settings belong under subagent in $PI_CODING_AGENT_DIR/settings.json:

{
  "subagent": {
    "defaultAgent": "worker",
    "symbolMap": {
      "?": "searcher",
      "!": "reviewer"
    }
  }
}

A nearest project .pi/subagent.json overrides global values:

{
  "defaultAgent": "worker",
  "symbolMap": {
    "?": "searcher"
  }
}

• defaultAgent: used when an interactive launch omits the agent; defaults to worker
• symbolMap: one-character shortcuts mapped to agent names; a valid project map replaces the global map

Set PI_SUBAGENT_CONTEXT_GUARD_TOKENS to a positive integer to override the proactive context limit for child runs. Set it to 0 or an empty value to disable the guard.

Escalation

Children receive an ask_master tool. Calling it reports a decision or blocker to the parent and immediately terminates the child run. Use it only when the child cannot proceed safely.

Troubleshooting

• Configured defaultAgent "worker" was not found: create a matching agent, choose another agent explicitly, or update defaultAgent.
• runtime "claude" is no longer supported: remove the runtime field from the agent file; agents always run on pi.
• Hidden run shows no transcript message: inspect it with /sub:peek, <>runId, or /sub:open.
• /skill:stress-interview reports a missing agent: run /subagents to install the starter pack, then /reload.
• Starter skills are missing although agents exist: run /subagents and accept the workflow skill offer, then /reload.

When reporting a bug, include the pi and extension versions, OS and Node version, launch command, reproduction steps, and sanitized error output. Do not attach full session files because they may contain prompts, tool output, or secrets.

Security

• Children can use every tool declared by their agent.
• Project agent definitions are repository-controlled instructions. Review .pi/agents and .claude/agents in unfamiliar repositories.
• Restrict each agent's tools list to the minimum required.
• --isolated separates conversation context, not filesystem, process, credential, or network access.

Stability

This package is pre-1.0. Documented commands, configuration, and agent frontmatter are the supported surface; internal TypeScript modules may change between releases.

License

MIT