Subagents

Subagents let an agent delegate work to a child agent with its own isolated context window. The child runs in-process with its own token budget, executes with a scoped set of tools, and sends a distilled result back to the parent. The parent’s conversation stays clean and focused.

How it works

When the agent calls the subagent tool, PizzaPi:

1. Discovers available agent definitions from multiple directories (see Agent discovery paths)
2. Creates an in-process AgentSession via the pi SDK (no child process, zero overhead)
3. Returns immediately so the parent can continue working
4. Runs the child behind the scenes and injects its final output as a follow-up message when done

Unlike spawn_session, subagents run inside the parent process — no child process, no separate worker. They are still visible: each run is mirrored to the relay as an ephemeral child session, so it appears nested under its parent in the session sidebar with a live transcript, just like a linked session. Result delivery is automatic; the parent should not poll or wait.

Visibility in the web UI

While a subagent runs, PizzaPi registers a short-lived relay session named <agent>: <task> (<agent> #N: <task> for chain steps) with the parent as its parentSessionId. It streams the subagent’s transcript, and ends when the subagent finishes — after which the run remains in the parent’s conversation as the usual inline subagent card.

The mirror is best-effort and entirely optional: when the relay isn’t configured (local TUI, no API key, or PIZZAPI_RELAY_URL=off), subagents run exactly as before with no mirroring.

Quick start

1. Create an agent definition

Create ~/.pizzapi/agents/researcher.md:

---
name: researcher
description: Read-only codebase research
tools: read,grep,find,ls
---
You are a research agent. Read files, trace dependencies,
and summarize findings without modifying anything.

2. Use it in a session

The agent can invoke the subagent tool like this:

{
  "agent": "researcher",
  "task": "Summarize the authentication module and list all endpoints"
}

The subagent starts in its own context and the tool returns immediately. When the work finishes, the summary arrives automatically as a follow-up that resumes the parent session. Only the summary enters the parent’s context window.

Agent definitions

Note

For a complete guide to writing agent definitions — frontmatter fields, discovery paths, tool restrictions — see Agent Definitions.

Agent definitions are markdown files with YAML frontmatter. PizzaPi is compatible with Claude Code agent files.

Agent discovery paths

Agents are discovered from multiple directories. Within each scope, .pizzapi/ paths are checked first (higher precedence), then .claude/ paths:

• User scope: ~/.pizzapi/agents/*.md, ~/.claude/agents/*.md — available in all your sessions
• Project scope: .pizzapi/agents/*.md, .claude/agents/*.md — repo-specific agents (walk-up search from cwd)

When agents with the same name exist in multiple directories, the first-found wins (.pizzapi before .claude, project overrides user).

Frontmatter fields

Field	Required	Description
name	✅	Unique identifier for the agent
description	✅	Brief description (shown in agent listings)
tools		Comma-separated list of allowed tools (e.g., read,grep,find)
disallowedTools		Comma-separated tools to deny (removed from inherited list)
model		Model override (e.g., claude-haiku-4-5, haiku, anthropic/claude-haiku-4-5). inherit or omit to auto-select the cheapest available model (not the parent’s model).
maxTurns		Maximum agentic turns before the subagent stops
permissionMode		Permission mode: default, acceptEdits, dontAsk, bypassPermissions, plan
background		If true, hints the agent should run as a background task

The markdown body after the frontmatter becomes the agent’s system prompt.

Note

The disallowedTools, maxTurns, permissionMode, and background fields provide compatibility with Claude Code agent definitions. Agent files that work with Claude Code’s Task tool will also work with PizzaPi’s subagent tool.

Example: Code reviewer

---
name: reviewer
description: Code review for bugs and style
tools: read,grep,find,ls
---
You are a code review agent. Identify bugs, security issues,
and style inconsistencies. Rate findings P0-P3 by severity.
Output "LGTM" if the code looks good.

Built-in task Agent

A general-purpose task agent is always available without any definition file. PizzaPi also ships bundled example agents (researcher, reviewer, refactorer) in packages/cli/agents/ — copy them to ~/.pizzapi/agents/ to use them as custom agents.

Agent	Tools	Purpose
task	built-in coding tools	General-purpose delegation
researcher	read, grep, find, ls	Read-only codebase analysis and research
reviewer	read, grep, find, ls	Code review with severity-rated findings
refactorer	read, write, edit, bash, grep, find, ls	Safe incremental code transformations

Execution modes

Single mode

Invoke one agent with one task:

{
  "agent": "researcher",
  "task": "What authentication strategy does this project use?"
}

Parallel mode

Run multiple agents concurrently (up to 4 at once, max 8 tasks):

{
  "tasks": [
    { "agent": "reviewer", "task": "Review src/auth/login.ts" },
    { "agent": "reviewer", "task": "Review src/auth/session.ts" },
    { "agent": "researcher", "task": "Find all SQL queries in the project" }
  ]
}

Chain mode

Run agents sequentially, passing each step’s output to the next via {previous}:

{
  "chain": [
    { "agent": "researcher", "task": "Analyze the database schema and list all tables" },
    { "agent": "reviewer", "task": "Review the schema design described here:\n\n{previous}" }
  ]
}

If any step fails, the chain stops and reports which step failed.

Multi-model routing

Use the model field in agent definitions to route cheap tasks to fast models:

---
name: scout
description: Quick file exploration
tools: read,find,ls
model: haiku
---
Quickly scan files and report what you find. Be brief.

This saves money by using an inexpensive model for exploration while the parent session uses a more capable model for synthesis.

Agent scope and security

Scope parameter

Control which agent directories are searched:

Scope	Searches
"user" (default)	~/.pizzapi/agents/ and ~/.claude/agents/
"project"	.pizzapi/agents/ and .claude/agents/
"both"	All directories (project overrides user on name conflict)

Project agent security

Project-scope agents (.pizzapi/agents/ and .claude/agents/) are loaded from the repository and could contain untrusted prompts. When agentScope includes project agents:

• PizzaPi prompts for confirmation whenever a UI is available (TUI or Web UI).
• In headless/runner contexts with no UI, the tool fails closed and refuses to run project agents.
• Set confirmProjectAgents: false in the subagent tool parameters to skip the prompt (only for trusted repos).

Caution

Project-scope agents come from the repository’s .pizzapi/agents/ or .claude/agents/ directory. Only use agentScope: "both" or "project" with repositories you trust.

Creating custom agents

1. Create a .md file in ~/.pizzapi/agents/
2. Add the required frontmatter (name, description)
3. Optionally restrict tools and set a model
4. Write a clear system prompt in the body

Tips for good agent prompts

• Be specific about the agent’s role and boundaries
• Define output format so results are predictable
• Restrict tools to the minimum needed (principle of least privilege)
• Keep prompts short (< 500 words) — the agent’s context should be spent on the task, not the prompt
• Use model routing for simple tasks — Haiku/Flash for exploration, Sonnet/Opus for analysis

Background execution

The launch card records that the subagent started in the background. The parent session remains usable while it runs. On completion or failure, PizzaPi injects the result as a follow-up message and automatically resumes the parent agent. No polling is needed.

Comparison with spawn_session

Feature	subagent	spawn_session
Communication	Automatic follow-up result	Triggers + tell_child
Context	Isolated in-process session	Fully independent session
UI	Inline in parent session	Separate session view
Overhead	Near-zero (in-process SDK)	Higher (relay round-trip, new PTY)
Best for	Background delegation with automatic results	Interactive child workflows, cross-runner tasks
Model selection	Via agent definition or parameter	Via spawn parameter
Agent definitions	File-based (~/.pizzapi/agents/)	Prompt-based (inline in spawn call)

Use subagent when you only need the result. Use spawn_session when you need an independent session, cross-runner execution, or interactive trigger communication.

Linked Session Triggers

When using spawn_session, spawned sessions are automatically linked — child events surface as trigger messages in the parent’s conversation. Three trigger types are delivered:

session_complete

Fires when the child session finishes. The trigger includes the child’s final output and an exitReason field:

• exitReason: 'completed' — normal completion
• exitReason: 'error' — the child hit a usage limit or provider failure

session_error

When a child session hits a usage limit or provider error, a session_error trigger fires immediately to the parent — before session_complete. This allows the parent to react early (e.g., retry with a different model, skip the task, or escalate to the user).

Tip

Check exitReason in the session_complete trigger to distinguish between successful completions and error exits. An exitReason of 'error' means the child hit a limit or provider failure.

plan_review and ask_user_question

When a child calls plan_mode or AskUserQuestion, a trigger appears in the parent’s conversation. The parent responds with respond_to_trigger(triggerId, response).

Push notification suppression

Linked child sessions (spawned via spawn_session) can trigger push notifications by default. Child-session push suppression is opt-in per subscription (suppressChildNotifications), and the ntfy/native push path currently delivers all events regardless of isChildSession. If you are orchestrating many children and want fewer notifications, enable suppressChildNotifications on the relevant push subscriptions.

Claude Code compatibility

PizzaPi subagents are designed to be compatible with Claude Code agent files:

What works

• Agent definition files — The same .md files with YAML frontmatter work in both systems
• Discovery paths — PizzaPi searches .claude/agents/ alongside .pizzapi/agents/
• Frontmatter fields — name, description, tools, disallowedTools, model, maxTurns, permissionMode, background
• Tool name — The Web UI renders both subagent and Task tool calls with the subagent card

Differences

Feature	Claude Code (Task)	PizzaPi (subagent)
Execution	In-process	In-process via pi SDK (isolated session)
Built-in agents	general-purpose, Explore, Plan	task (general-purpose)
Skills	skills frontmatter field	Not yet supported
MCP servers	mcpServers frontmatter field	Not yet supported
Hooks	hooks frontmatter field	Not yet supported
Memory	memory frontmatter field	Not yet supported
Modes	Single only	Single, parallel, chain

To use Claude Code agents with PizzaPi, simply ensure the agent .md files are in a directory PizzaPi scans. If you already have agents in .claude/agents/, they’ll be discovered automatically.

See also: Dynamic Workflows for large fan-out subagent orchestration that keeps intermediate output out of your context.