Agent Orchestration
Autonomous "agent team" delegation: a planning agent, N implementation agents, and a review/validation agent, coordinated by the main agent you talk to, auto-invoked when a task is non-trivial. Works in both the lite and full installs.
This is a set of kit extensions (pi-package resources). It does not modify pi core. Subagents are separate
piprocesses with their own isolated context windows.
Pieces
| Extension | Role |
|---|---|
subagent (vendored) |
The one delegation engine: single or parallel delegation to role agents in isolated pi subprocesses (tool restriction, per-role model, skill preloading), plus workflows. Every other launcher goes through the same launch contract. |
delegation-guard |
The launch contract: decides which extensions a child loads, reserves its budget, and verifies inside the child that its protections loaded. See Child governance. |
effort |
The effort tier and the shared delegation ledger every launch reserves against. |
orchestrator |
The autonomy: scores task complexity and, when non-trivial, steers the main agent into the plan → implement → validate flow (via a context-sieve message). |
goal-core |
Persists the mission goal to .pi/GOAL.yaml (survives compaction). |
task-graph |
Shared DAG task board (.pi/task-graph.json): planner emits units, implementers claim the next unblocked one. (full) |
verifier-board |
Definition-of-done gate (.pi/verdicts.json): the mission isn't done until verdicts pass and at least one trusted source (verify/review/validator:<id>) passes. (full) |
branch-lab |
Git worktree leases so parallel implementers don't clobber each other. (full) |
Roles
Resolved in this order, later sources overriding earlier ones by name:
- kit:
packages/kit/agents/*.md(scout,planner,implementer,reviewer). Always available and trusted, including inside headless children. - user:
~/.pi/agent/agents/*.md. Copy a kit role here to customise it. - project:
.pi/agents/*.md, only withagentScope: "project" | "both". It needs interactive approval, or an exact digest inPI_KIT_TRUSTED_PROJECT_ROLES.
Older kits copied the roles into each project's .pi/agents. Those copies are now ignored
by default. A one-time notice lists only the copies whose content differs from the current
built-in roles; byte-identical copies are not flagged.
Role frontmatter: name, description, tools (comma list), model (provider/id),
thinking (off … max), skills (SKILL.md bodies preloaded into the role's system
prompt), extensions (extra kit extensions for the isolated child), max_runtime
(30m), effort (ask for a lower effort tier for this role) and scout: true
(count against the scout limit).
Subagent model policy
A role's model: is used when set. Otherwise the child gets the parent session's active
model. Set PI_KIT_SUBAGENT_INHERIT_MODEL=1 to force the parent model for every role.
Child governance
A child is a separate pi process started with --no-extensions plus an allowlist that
delegation-guard builds. Every launch path uses it: the subagent tool, /workflows, the
completion reviewer in verify-gate, the specialists and validators in conductor, the second-model
reviewer in dual-review (/review and the dual_review tool), and recovery. A test scans the
extension sources and fails when a launcher of pi children does not ask the guard
(tests/delegation-guard-smoke.ts). There is one engine, so there is one set of rules:
flowchart TD
call[A launcher asks to start a child] --> guard{delegation-guard}
guard -->|missing protection, no ledger,<br/>policy unreadable| refuse[Refused, with the reason]
guard --> reserve[Reserve a slot in the shared effort ledger]
reserve -->|over budget| refuse
reserve --> start[pi --no-extensions -e governance... -e companions...]
start --> self{Child checks its own protections}
self -->|one did not load| fail[Blocks every tool, exits 78]
self --> run[Child runs, at the parent's tier or lower]
run --> settle[Slot settled: no refund]
- Governance first. The child loads
delegation-guard, thenprotected-paths,secret-guardandtool-firewall(each if the parent has it), then any other extension whose manifest sayschildGovernance: true(effort,engagement-governance), then the companionsfinish-reason-retryandtodo. The firewall is always ahead of anything that could act. - Fail closed. If a required protection cannot be located or did not load in the child, the
child is not started, or (if it started) blocks every tool call and exits with code 78
(
EX_CONFIG) so the parent sees a visible failure. A child is never started with weaker protection than its parent, at any depth: grandchildren go through the same contract. - Fatal, not retried. A denied or misconfigured launch is not treated as a transient failure.
- Budgeted. Every launch reserves a slot in the effort ledger; a child's tier is its parent's or lower.
- Roles that need more. A role whose tools include
subagentalso gets thesubagentextension, when the launch grants it and the nesting limit allows another level: depth 1 is the default, so a direct child that should delegate needs the maximum depth raised to 2 (tests/subagent-roles-isolation-smoke.ts). A role or step can addextensions:, by name: a kit extension's registry name, never a path, so a role, workflow or settings file cannot load arbitrary code into a governed child (a name that is not one is skipped). Ambient launchers (a engagement specialist that needs the operator's MCP servers) keep the operator's extensions but are always givendelegation-guardexplicitly and the guard's environment, so the child-side check runs even if the child's settings would not have loaded it.
A governed child is started with --no-skills --no-prompt-templates --no-themes: its skills come
from the role's skills preload, and a headless child uses no command or theme. A read-only or
scout role also gets --no-context-files, so it does not re-read the project's AGENTS.md (6.7k
characters in the measured worker logs) on top of a task that already says what it needs; a role
that writes keeps its context files. PI_KIT_SUBAGENT_DISCOVERY=1 restores every discovery. Pinned
by tests/subagent-roles-isolation-smoke.ts.
PI_KIT_SUBAGENT_EXTENSIONS=a,b replaces the companion list (governance cannot be removed).
PI_KIT_SUBAGENT_ISOLATE=0 no longer disables isolation. The task reaches the child over stdin
(print mode merges it into the prompt), not as one argument, so large tasks cannot hit the
128 KiB argument limit.
How autonomy works
pi is model-driven — there is no hidden background spawn; a subagent runs only when the main agent
calls the subagent tool. So "automatic" means: the orchestrator scores each request and, above a
threshold, injects a high-priority directive telling the main agent to delegate. Tune it:
PI_KIT_ORCH_THRESHOLD— complexity score needed to auto-delegate (default3; raise for lite / small models)./orchestrate on|off|auto|status— force always-delegate, never, or automatic for the session.PI_KIT_ORCH_DISABLE=1— turn the layer off entirely.
Subagent reliability, observability and recovery
A subagent is a long-lived child process; the parent must never be wedged by one. The guards:
- Idle watchdog —
PI_KIT_SUBAGENT_IDLE_TIMEOUT_MS(default 15 min, 0 disables). Keys on child output, and is paused fromtool_execution_startuntil the matchingtool_execution_end, so a long silent tool call is not a stall; it rearms after the last open call ends (tests/subagent-progress-smoke.ts). A conductor specialist's own idle watchdog is held the same way, with its own wall clock,PI_KIT_SPECIALIST_MAX_RUNTIME_MS(default 30 min), so setting that to 0 leaves a hung tool unbounded (tests/conductor-specialist-bounds-smoke.ts). - Wall-clock ceiling —
PI_KIT_SUBAGENT_MAX_RUNTIME_MS(default 30 min, 0 disables). The backstop for a child that keeps dripping output, and the only limit on a tool call that never ends, so setting it to 0 leaves a hung tool unbounded. ReportsstopReason: "wall-clock"(tests/subagent-progress-smoke.ts). Either limit is capped at about 24.8 days, the longest a timer can run. - Live heartbeat —
PI_KIT_SUBAGENT_HEARTBEAT_MS(default 5 s, 0 disables). Emits elapsed / idle / bytes to the parent (and the TUI footer) while the child is silent. - Cancel and background. Esc (a cancelled tool call) stops the children, so there's no
hidden token spend and a run's output can't be silently truncated. For long work you don't need
this turn, pass
background: true(single or parallel mode). The call returns immediately, and the result is delivered to the agent (a session message) and to you (a notification) when it finishes.PI_KIT_SUBAGENT_DETACH_SIGNAL=1restores the old detach-on-cancel behaviour. Live children are stopped when the session ends. - Bounded headless approvals — a tool-firewall
askinside a headless child is answered for at mostPI_KIT_SUBAGENT_APPROVAL_TIMEOUT_MS(default 2 min) before failing closed, rather than the 15-minute root default. - Live TUI footer — the tool sets a persistent
subagentstatus line (agent, step, turn, elapsed, last tool + target, run id) for the duration and clears it on finish.
The main agent can inspect and stop runs with workflow_status / workflow_control (and the
operator surface /workflows); every run also writes .pi/subagent/<id>.log and
.pi/subagent/runs.jsonl. Run ids carry a random suffix (parallel runs of one role no longer
collide), the registry is compacted to the last 500 runs, and a run whose process died is shown
as orphaned instead of running forever.
Autonomous stall escalation
progress-guard watches the main session for repetition, oscillation, and reads-without-a-write.
When one signature keeps recurring it injects a review/delegate checkpoint on its own — in either
mode, with no reminder command and no mode switch — and writes a per-session
.pi/recovery/sessions/<session id>/escalation.json for that session's recovery-orchestrator
(tests/recovery-grounding-smoke.ts). The reads-since-edit signal defaults to PI_KIT_GUARD_STALL (10) and is
suppressed entirely in a session with no write-capable tool active. See
packages/extensions/src/progress-guard/README.md.
Lite vs full
- Lite ("Plan→Do→Check"):
planner → implementer → reviewersequence, in-place, higher threshold. Shipssubagent,orchestrator,goal-core+ the role agents. No external deps. - Full ("Agent Team"): adds
scout, parallel implementers inbranch-labworktrees, thetask-graphDAG and theverifier-boardgate.
Manual entry points
/orchestrate-plan <task>: scout + planner produce a plan (no changes). Sent as a message./orchestrate-implement-review <task>: planner → implementer → reviewer, looping until it passes./workflows run feature goal=…/bugfix/research: the same flows as saved, resumable workflows.workflow({name: "review-changes", args})and the other kit built-in script workflows (understand,design-panel,research-sweep,migrate); theworkflow-authoringskill is the reference for writing your own script (tests/workflow-builtin-smoke.ts).- Or just ask in plain language: "plan this with a subagent, then implement and review it."
Verification lifecycle
Conversation does not require a verifier board. The gate is armed by an active
implementation/delegation workflow, or successful write/edit results in a
project that declares scripts.verify with PI_KIT_VERIFY_ON_TURN=1. Plan-only commands and ordinary report
edits without that project contract do not create failing npm verdicts.
With PI_KIT_VERIFY_ON_TURN=1, verify-gate runs after edits when the assistant
finishes its tool sequence, awaiting the check before subsequent hooks inspect
the board. Load verify-gate before orchestrator for this ordering (as in the lite
surface and live harness). Automatic checks skip projects without a verify script.
The check command is bounded to two minutes and one MiB of captured output.
Explicit /verify (operator) and verify_completion (agent) are a general
completion check, not only a test run. They run the check command if one exists,
then an isolated read-only reviewer that judges the goal, todos, task graph, and
recent requests against the repository. The reviewer records review on the
board and writes .pi/verify-report.md. If neither a check nor a review can
run, /verify still records FAIL. See packages/extensions/src/verify-gate/README.md.
The orchestrator sends at most one labeled custom diagnostic per user request at
the final turn_end, while Pi can consume it in the current loop. It does not
inject a user message at agent_end, which could otherwise remain queued until
the next user request. The diagnostic requests actual check results or an honest
blocker report; it never authorizes fabricating PASS verdicts or executing operator
slash commands as shell commands. A failed board remains failed after the bounded
correction.
Automatic delegation also checks that subagent is in the active tool set.
Unavailable tools do not produce delegation directives or phantom completion
requirements; explicit delegation commands report the missing tool to the operator.
Automatic edit detection covers successful built-in write and edit tools.
Shell-only changes and external tools still need explicit project checks or an
explicit workflow. This completion guidance is not an authorization boundary or
proof that model-authored evidence is correct.
Root orchestration with Conductor
conductor is the layer-4 orchestration layer above this task-level orchestrator. It owns durable,
multi-phase engagements, dynamically synthesises least-privilege specialists rather than relying only
on static .pi/agents/*.md roles, and routes claimed findings/results through causally independent
validation. See Subagents and orchestration and the
engagement-conductor and dynamic-agent-synthesis skills under
Orchestration & recovery, and the
independent-finding-validation skill under
Evidence & reporting in the skills catalogue.