---
name: subagents
description: Delegate isolated work through Pi subagent tools. Use when a workflow needs an independent worker, fresh context, parallel reviewers, or hidden role separation.
disable-model-invocation: true
---

# subagents

## 1. Confirm support

Prefer tool calls when the current runtime exposes them.
The supported tool names are `subagent_spawn`, `subagent_batch`, `subagent_list`, `subagent_status`, `subagent_result`, and `subagent_cancel`.

If these tools are unavailable, do not pretend that an in-process role switch is a subagent.
State that Pi subagent tools are unavailable in the current runtime.
Do not perform the delegated subagent work in-process.

Done when the run has a supported subagent tool path.

## 2. Prepare a bounded prompt

Give each subagent a self-contained prompt.
Include the role, task, repository path, relevant files or artifacts, constraints, and expected output shape.
Do not expose private planning state that the workflow is trying to isolate.
For test-driven development, send one behavior at a time rather than a backlog.
For review, send one review dimension at a time unless batching independent dimensions.

Use `context: "independent"` for a fresh worker by default.
Use `context: "fork"` only when the child intentionally needs the parent transcript as starting context.
Choose named agents only when the project has configured them.
Do not invent named agents as part of the delegation.

Done when the prompt is narrow enough that the subagent can complete without sharing hidden state or requiring follow-up orchestration.

## 3. Spawn and track workers

Use `subagent_spawn` for one worker.
Use `subagent_batch` when several independent workers can run in parallel.
Both spawn tools return before the child work is complete.
Record accepted child ids and per-entry failures.
Use `subagent_list` or `subagent_status` to track lifecycle when needed.
Use `subagent_result` to retrieve completion output.
Use `subagent_cancel` for stale or no-longer-needed workers.

Do not claim the delegated work is complete until every required child result is available or a failed child has an explicit disposition.
Treat `queued`, `starting`, `running`, and `settling` as incomplete states.
Treat `failed`, `cancelled`, `timed_out`, and `orphaned` as failures unless the caller explicitly accepts the missing result.

Done when every required worker result has been collected or every missing result has a stated disposition.

## 4. Integrate results

Use subagent output as evidence, not as an unquestioned command.
Preserve which child produced each material finding.
When subagents disagree, report the disagreement rather than averaging it away.
When a subagent result changes implementation direction, verify the relevant facts in the parent context before editing code.

Done when the parent has integrated child results into the caller workflow with provenance and limitations visible.