Agent Extension

A Pi extension that delegates work to specialized agents in isolated contexts.

Tool

agent

Delegate work to a specialized agent. Each invocation spawns a separate pi process with its own isolated context and persistent session.

Slash Command

The extension registers these slash commands:

• /agent <name> <prompt>
• /agent-resume <session-id> <prompt>

Example:

/agent reviewer Audit the current diff for correctness risks

This command does not run the subagent directly. Instead, it sends a user message that instructs the main agent to:

• rewrite the raw request into a self-contained, context-aware subagent prompt
• include relevant conversation, repository, working-directory, file, and constraint context
• call the agent tool with options.scope: "both"
• integrate the subagent result back into the normal conversation flow

This keeps the UI consistent with normal tool usage and ensures subagent output returns through the main agent.

Modes

Single Run

Run one agent with one prompt.

{
  "name": "worker",
  "prompt": "List all files in the current directory"
}

Override the agent's default model at runtime:

{
  "name": "reviewer",
  "prompt": "Audit the current diff for correctness risks",
  "options": {
    "model": "openai-codex/gpt-5.4",
    "thinking": "high"
  }
}

Resume a Saved Session

Resume a previously saved subagent session with its original tools, system prompt, cwd, and model/thinking overrides.

{
  "sessionId": "019d906a-3d5a-70b6-a359-1d16acea15dc",
  "prompt": "Continue the review and focus on race conditions"
}

Parallel Runs

Run multiple agents concurrently.

{
  "parallel": [
    { "name": "worker", "prompt": "Task 1" },
    { "name": "reviewer", "prompt": "Task 2" }
  ]
}

Per-run overrides are also supported in parallel mode:

{
  "parallel": [
    {
      "name": "worker",
      "prompt": "Task 1",
      "model": "google/gemini-2.5-pro",
      "thinking": "medium"
    },
    {
      "name": "reviewer",
      "prompt": "Task 2",
      "model": "openai-codex/gpt-5.4",
      "thinking": "high"
    }
  ]
}

Sequence Runs

Run agents sequentially, passing output to the next step via {previous}.

{
  "sequence": [
    { "name": "worker", "prompt": "Generate a list of items" },
    { "name": "reviewer", "prompt": "Process these items: {previous}" }
  ]
}

Parameters

Name	Type	Required	Description
name	string	No	Agent name for a single run
sessionId	string	No	Saved subagent session ID to resume
prompt	string	No	Prompt for a single run or resumed session
parallel	array	No	Array of {name, prompt, cwd?, model?, thinking?} for parallel runs
sequence	array	No	Array of {name, prompt, cwd?, model?, thinking?} for sequential runs
options	object	No	Optional configuration

Tool results include a per-run sessionId in details.results[]. Use that ID with the agent tool's resume mode or /agent-resume to continue the same specialized subagent configuration later.

options

Name	Type	Required	Description
scope	string	No	user, project, or both (default: user)
confirmProject	boolean	No	Prompt before running project agents (default: true)
cwd	string	No	Working directory for a single run
model	string	No	Default model override for the whole tool call
thinking	string	No	Default thinking override: `off

Agent Discovery

Agent frontmatter may define default model and thinking, but both can now be overridden at runtime through tool parameters.

Agents are discovered from:

• User agents: ~/.pi/agent/agents/
• Project agents: .pi/agents/ (in project root)