@tintinweb/pi-subagents

Model Scope is an opt-in feature (enabled via /agents → Settings → Scope models) that validates subagent models against the enabledModels list configured in pi settings.

Scope Behavior by Source

Implementation Details

• Format: Only exact provider/modelId entries are honored (e.g., anthropic/claude-haiku-4-5-20251001). Glob patterns, bare IDs, or :thinking suffixes are silently dropped.
• Settings: It respects both global ~/.pi/agent/settings.json and project-local <cwd>/.pi/settings.json (project overrides global).

Nested delegation is disabled by default. To allow an agent to spawn its own subagents, you must set the allowed_subagents field in its frontmatter. This creates a privilege boundary: the parent can only delegate to the specific types listed.

Key Concepts

• Privilege Boundary: A child runs with its own tools:, extensions:, and isolated: settings. The parent's restrictions are NOT inherited; delegation grants the parent the union of what the listed agents can do.
• Depth Limit: The default maximum depth is 2 (main session $\rightarrow$ subagent $\rightarrow$ nested child). This can be changed via maxSubagentDepth in subagents.json.
• Lifecycle: When a parent agent is stopped or ends, its nested children are also stopped.
• Observability: Nested children write their own .output transcripts in the root session directory. Their token usage is folded into the ancestors' totals.
• Concurrency: Nested children do not occupy maxConcurrent slots; they are managed by the parent.

---
tools: read, grep, find
extensions: false
allowed_subagents: support-file-finder, support-callsite-tracer # or `all`
---

Agent capabilities are controlled by two distinct but composable fields: extensions: (which extensions load) and tools: (which tools are visible to the LLM).

Scoping Rules

• extensions: is the sole loading authority. If you use ext:foo/bar in tools:, it will not load the extension foo if it isn't in the extensions: list.
• exclude_extensions: takes precedence over everything else. An excluded extension will not load and its tools cannot be pulled back via ext: selectors.
• isolated: true is a hermetic mode that forces extensions: false, skills: false, and removes all ext: selectors, leaving only built-in tools.

Usage Examples

Narrowing built-ins only:

tools: read, grep, find

All built-ins plus one extension tool:

tools: "*, ext:mcp/search"
extensions: [mcp]

Hermetic specialist (one extension, one tool, no built-ins):

extensions: [mcp]
tools: "ext:mcp/search"

# Example: Specialist mode
extensions: [mcp]
tools: "*, ext:mcp/search"

# Example: Hermetic mode
isolated: true

Running agents in parallel

To run multiple agents for independent work concurrently, send a single message containing multiple tool calls, ensuring run_in_background: true is set on each call.

Foreground vs Background

• Foreground (default): Use when you need the agent's results immediately before you can proceed with your next step.
• Background: Use run_in_background: true for work that doesn't require immediate attention. You will be notified upon completion; do not poll or sleep while waiting.

Interacting with running agents

• Resume: Use resume with an agent ID to continue work from a previous agent run.
• Steer: Use steer_subagent to send mid-run messages to an agent that is currently running in the background.

Important Lifecycle Notes

• Fresh Starts: A new Agent call (without resume) starts with no memory of prior runs. The prompt must be self-contained.
• Results: When an agent finishes, it returns a single message. This result is not automatically visible to the user; you must send a text message with a concise summary to show the user the outcome.
• Verification: Always verify an agent's work. An agent's summary describes its intent, not necessarily its actual actions. Check code changes before reporting work as complete.

To prevent an agent from making direct changes to your working directory, set isolation: worktree. This runs the agent in a temporary, isolated git worktree.

Behavior:

• No changes made: The worktree is automatically cleaned up.
• Changes made: The worktree is cleaned up, and changes are committed to a new branch named pi-agent-<id>.
• Agent commits its own work: A new branch is created at the agent's current HEAD, preserving its commits. Uncommitted leftovers are committed on top first. These commits use --no-verify to bypass local pre-commit hooks.

Requirements:

• The project must be a git repository with at least one commit.
• If git worktree add fails, the Agent tool will return an error rather than running without isolation. isolation: "worktree" is a strict requirement.

Agent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })