pi-delegate
Load when dispatching work to subagents as `runs: [{agent, task, …}]`: each entry is one run with its own worker session, and each collapses to a single tool result. A `mode: "supervised"` run additionally forks the main agent into a private multi-turn conversation with its worker. Prefer this over the fire-and-forget `subagent` tool whenever the worker is likely to need review, clarification, redirection, or iterative refinement (advisory review, implementation handoffs, parallel exploration, long-running QA). Also covers steering and cancelling running work, background vs awaited execution, and git-worktree isolation for parallel work.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- load
- recognition
- name
- pi-delegate
- description
- Load when dispatching work to subagents as `runs: [{agent, task, …}]`: each entry is one run with its own worker session, and each collapses to a single tool result. A `mode: "supervised"` run additionally forks the main agent into a private multi-turn conversation with its worker. Prefer this over the fire-and-forget `subagent` tool whenever the worker is likely to need review, clarification, redirection, or iterative refinement (advisory review, implementation handoffs, parallel exploration, long-running QA). Also covers steering and cancelling running work, background vs awaited execution, and git-worktree isolation for parallel work.
03 SKILL.md 正文
pi-delegate
Use this skill when you need a subagent to do real work. One delegate call
dispatches a list of runs; each run gets its own worker session and collapses to
one result in the main thread.
The ordinary in-process modes are:
solo(the default) — send the task to one worker, return its answer.supervised— insert a fork of the main agent (same model, same system prompt) between you and the worker. It chats privately with the worker for up toroundsturns, then collapses. Use it when you might want to push back on the first answer. Solo and supervised worker conversations never enter the main thread's history; only their collapsed result does.
Empty harvests fail loudly
A run that finishes with no substantive output is now a loud failure offering recovery, not a silent success. Do not treat a resolved worker turn or lifecycle chatter as proof that the run completed. The solo runner and supervised worker channel share one harvest classifier:
- substantive assistant text is a deliverable;
- an explicit provider or assistant failure is a terminal failure; and
- no assistant output, empty output, or cancellation-only output is a terminal
failedresult withNo substantive assistant output recovered.
When recovery is available, the existing delegate:fork-failed wake offers it.
If an earlier substantive response was genuinely recovered, the harvest method
is recorded as salvage; a terminal substantive response uses terminal.
Ordered-run output, progress, and {previous} propagation happen only after a
validated substantive completion. This shared classifier closes the independent
blind spots that solo and supervised paths previously had.
Slash syntax
pi-delegate registers exactly /delegate, /delegate-cancel,
/delegate-inspector, and /delegate-help. The dispatch grammar is:
/delegate TASK [--direct | --fork | --supervised | --chain NAME] [--agent NAME] [--foreground | --fg] [--worktree] [--model MODEL] [--thinking LEVEL] [--skill NAME ...] [--cwd PATH]
/delegate-cancel [RUN_ID [ENTRY]]
For operator cancellation, omit both values to pick one live target. Supply
RUN_ID ENTRY to cancel one canonical entry immediately. Supply only RUN_ID
to confirm whole-batch cancellation. Completion lists unique live run IDs, then
canonical entry names for the chosen run. Picker dismissal leaves work running.
The task comes first. /delegate TASK runs the built-in delegate worker
directly in the background. --direct is the explicit default. --fork and
--supervised select supervised execution. --foreground and --fg wait for
the result. /delegate TASK --chain NAME runs a saved chain and permits only the
task, --cwd, and foreground control.
Quote task tokens whose text looks like an option. A quote starts a structural
region only at the beginning of a token, so contractions and possessives such
as don't and module's remain ordinary task text. Backslash escapes the next
character. Unclosed quotes, unknown options, missing values, conflicting
selectors, invalid thinking levels, unknown workers or chains, and incompatible
chain options are rejected before dispatch.
/delegate Review the authentication changes
/delegate "Review text ending in --foreground"
/delegate Review the change --fork --agent reviewer --thinking high --skill code-review
/delegate Summarize the repository --chain discovery-report --cwd /repo --fg
/delegate-cancel
/delegate-cancel RUN_ID ENTRY
Use management forms alone: /delegate --agents, /delegate --chains,
/delegate --health, and /delegate --help. Bare /delegate and
/delegate-help show the same help. Use /delegate-inspector for status and
transcripts. Inline chains and parallel workers remain available through the
delegate tool API, not the slash interface.
Composing saved chains
A saved chain can reference another saved chain with this exact canonical heading; do not insert whitespace after the colon:
## chain:reusable-review
Review {task} after {previous}.
The management equivalent is { chain: "reusable-review", task?: "..." }.
It is a distinct step variant and cannot carry agent or worker-only options.
The parser accepts legacy whitespace after chain: for compatibility, but the
serializer always writes ## chain:<name>. The chain: heading prefix is
reserved: a worker agent used in a saved chain must not have a name beginning
with chain: because that spelling is parsed as a saved-chain reference.
A deterministic command stage uses ## run:<label> followed by required
command and optional cwd, env, and timeoutMs lines. Its management shape
is { run, command, cwd?, env?, timeoutMs? }; it cannot carry a task or worker
fields. It starts no LLM. A successful command leaves scoped {previous}
unchanged. Any failure stops the chain. Project-scoped commands require project
trust, and all command stages are preflighted before the first worker starts. A
confined nested caller cannot invoke a command stage because its separate shell
process cannot inherit the caller's write guard.
Every reference creates a local template scope. The reference task is evaluated
once against the parent's scoped {task} and current {previous}. That result
is frozen as {task} for the referenced chain, including its first worker and
all deeper references. {previous} is different: it starts empty inside each
referenced chain, advances after each local worker or completed child reference,
stays unchanged across a successful command stage, and returns the referenced
chain's final output to its parent.
Resolution is recursive and eager. Every referenced name uses normal saved-chain discovery precedence. The complete reference graph resolves and every command stage validates before any worker starts. A missing reference, cycle, or invalid command stage rejects the whole invocation before side effects begin.
Nested-delegation policy applies to the resolved worker leaves, not to
saved-chain names. nestedDelegateAgents must allow every resolved leaf agent. The
caller's write-confinement authority also bounds every resolved leaf: inherited
worker directories must remain within the caller's roots, and a leaf cannot
waive confinement or add an outside root. Allow-list or confinement rejection
happens before worker construction.
Composition expands in place. All workers and command stages belong to one
chain run and share its single chainDir; a referenced chain never creates a
second artifact directory.
Expansion makes no nested delegate call, so each reference adds zero delegation
depth.
When to prefer delegate over subagent
| Situation | Tool |
|---|---|
| Likely to need review / clarify / redirect with the worker | delegate |
| Parallel specialists where each may iterate independently | delegate (up to 6 runs) |
| Long-running review/QA you can dispatch and forget | delegate (background is the default) |
| Git-isolated parallel implementation work | delegate with worktree: true |
| Truly fire-and-forget single-shot question | subagent (simpler) |
| You specifically need pi-subagents' chain/parallel orchestration DSL | subagent |
Default to delegate unless the task is clearly one-shot.
Tool surface
delegate— dispatch 1..6 parallel runs. The main call.delegate_control— inspect and control ordinary runs:status— list active/completed dispatched runs.result— replay a dispatched run's authoritative output byrunId.steer— guide an explicit supervised run's copied supervisorfork. Direct workers, chain steps, and unknown in-process shapes reject steering; use sparingly.cancel— abort one run or the whole dispatch.recover— relaunch a single failed worker entry. Foreground-only: a delegated worker is refused this action.
delegate_escalation— one tool, three actions:list— list canonical pending escalation requests and their holders.resolve— resolve a root-held request within root authority, or a user-held request only after the operator actually chose andonBehalfOfUser: trueis supplied.pass_up— pass a root-held request upward, normally to the user.
Both appear only once there is something to control, so they are absent from an
idle session. The eleven names they replace still work in a tools: allowlist.
Minimum viable call
delegate({
runs: [
{ agent: "reviewer", task: "Review packages/api/src/session-store.ts for race conditions" }
]
})
Solo and supervised background runs return immediately with a runId; when they
finish, the main agent gets a custom_message wake-up containing the collapsed
output.
Key parameters per run entry
delegate({ runs: [{
agent: "reviewer", // agent definition name (required)
task: "...", // initial framing (required unless `after`-gated)
name?: "reviewer-a", // the key you steer/cancel/recover this run by
mode?: "solo", // "solo" (default) | "supervised"
// solo only — reject on a supervised entry
after?: ["scout"] | "previous", // order this run behind a whole earlier layer
count?: 3, // fan out N copies of this entry
artifact?: "notes.md", // private returned file; basename only, never a workspace path
check?: "validate-notes notes.md", // validate that artifact; independent solo runs only
reads?: ["spec.md"], // seed the worker with file contents
progress?: true, // direct/chain progress file; supervised ignores and warns once
// supervision. `rounds` REJECTS on a solo entry; `clone_mode` and
// `collapse_mode` are accepted there and silently do nothing (#286).
rounds?: 5, // total worker-message budget; exact first turn consumes one
clone_mode?: "full" | "snippet" | "task_only", // history seeding, default "full"
task_delivery?: "direct-first-turn" | "supervisor-mediated", // exact caller task first by default
snippet_last_n?: 10, // for "snippet" mode
collapse_mode?: "final_output" | "summary",
// Omit for no provider call; pin provider/model, or use "auto" for built-in Haiku 4.5.
summary_model?: "anthropic/claude-haiku-4-5" | "auto",
supervisor_instructions?: "be strict about error handling",
heartbeat_interval_ms?: 180_000, // supervisor wait: heartbeat after this much worker silence
max_consecutive_heartbeats?: 5, // silent heartbeats before a wind-down steer, then abort
// solo and supervised
thinking?: "high" | false, // worker-only initial level override
thinkingMin?: "medium" | false, // worker-local adaptive lower bound
thinkingMax?: "high" | false, // worker-local adaptive upper bound
skills?: "code-review" | ["code-review"] | false,
cwd?: "packages/api", // per-run cwd (rejected when worktree:true)
interactive?: false, // route worker UI prompts to overlay
worktree?: false, // one fresh git worktree for this run
escalation?: "off" | "local" | object, // per-entry structured escalation policy
fabric?: false, // keep native tools, no fabric_exec; only narrows
model?: "openai/gpt-5", // worker model override
fallbackModels?: ["openai/gpt-5-mini"], // ordered worker fallback models
depth?: 1, // nested-delegation cap
env?: { GRAFT_MAIN_REF?: string | null }, // per-worker env patch
handoff?: { tasks: [...] }, // seed the durable task list
}] })
For a supervised run, omission of task_delivery means direct-first-turn: the
runtime sends the caller's exact task to the worker, then seeds the supervisor
with that completed exchange. The exchange consumes round 1. Use explicit
task_delivery: "supervisor-mediated" only when the supervisor should compose
the first worker instruction.
progress?: boolean is accepted on a supervised entry for compatibility, but it
is ignored and warns once per dispatch because the supervisor controls the
message stream. The supervised artifact and reads fields remain
rejected. Direct and chain runs retain their existing progress.md behavior.
env merges over the inherited process environment on direct and chain worker
surfaces; null explicitly unsets a non-delegate-owned variable. Delegate
lineage, routing, authentication, and child-control variables cannot be replaced
or removed. Saved agent defaults may declare the same field and invocation
values take precedence. Workers use the already-loaded extension code from the
parent session; rebuilding an extension while a session is running does not
update existing runs.
Durable agent/chain/config definitions store env values in plaintext.
When the worker loads pi-fabric, it gets fabric_exec unless it is
readOnly, has an explicit tools list, or sets fabric: false (agent, run
entry, or top level). A readOnly worker stays on native read, bash,
write and edit until pi-fabric supports a worker write policy, so it can
still write its scratch files and artifact; its result reports
surfaceReason: readonly-worker. A run entry's fabric: true never undoes an
agent's fabric: false. Each result reports surface (fabric or native) and
surfaceReason, its text has a line such as surface: native (fabric-opt-out),
and status details count them in workerSurfaces. See
docs/fabric-mode.md.
Name-only operational displays are redaction, not encryption of those files.
Never save API keys, tokens, passwords, or other secrets in these definitions;
use the process environment or a secret manager instead.
Start/reload a fresh Pi session when a task depends on newly built extension
code.
clone_mode cheat sheet. It seeds a supervisor, so it only means something
with mode: "supervised". A solo entry accepts it and drops it — inert, not
invalid — so it never fails a dispatch, and never does anything either:
full— the supervisor fork sees the entire main thread (highest fidelity, costs the most). Default. Watch token cost on long sessions.snippet— the fork sees only the last N main-thread messages. Cheap mid-session delegations.task_only— the fork sees just the task framing. Cheapest; use for self-contained questions.
Seed and read a worker checklist
When a delegated worker has several steps worth tracking and a session_tasks
claimant is loaded, request a durable checklist in that entry's namespaced handoff:
delegate({
runs: [{
name: "worker-lane",
agent: "worker",
task: "Implement the requested change.",
handoff: { tasks: [{ title: "Read the spec" }, { title: "Implement and test" }] },
}],
})
When a session_tasks claimant is loaded, the runtime stores the seed as a
context-aware.tasks.v1 session entry and supplies the worker's list-maintenance
instruction; do not duplicate that runtime instruction here. Without a claimant,
the worker receives a prompt checklist instead; it is not durable and has no subtree
or progress rows to read. With a claimant, progress rows ride the
existing updated bus event; read the worker's subtree with session_tasks action=subtree
rather than waiting for a prose update. Worker task IDs belong to its own address space
and are marked id-kind="local"; never reconcile them against the dispatcher's own t1/t2 ids.
The receiver bounds come from src/task-seam.ts: MAX_SEED_TASKS tasks,
one-level subtasks via the parseSlotTask depth guard and MAX_SEED_SUBTASKS,
and notes capped by MAX_SEED_NOTE_CHARS. Keep these names in documentation and
code references so the limits cannot drift silently.
Name your runs
name: is the addressing key. Every later delegate_control call takes it, the completion envelope reports it as
forkNames, and the widget shows it. Set it on every entry of a multi-run
dispatch, and name it after the work — an issue reference, a lane, a
component — never after the agent.
Omitted, it falls back to the agent's name, with #2, #3 appended for
duplicates. The runtime then derives a display label from the task so the row
still says something, but it can only work from the text you sent: three entries
briefed from the same file are indistinguishable to it and come back as
worker 1/3, worker 2/3, worker 3/3. Naming them costs one field and makes
the whole run legible.
runs: [
{ name: "#128-widget", agent: "implementer", task: "…" },
{ name: "#128-overlay", agent: "implementer", task: "…" },
]
Bounded adaptive thinking
Agent frontmatter can declare thinking, thinkingMin, and thinkingMax from
off|minimal|low|medium|high|xhigh. A bounded worker begins at thinking, then
a compatible adaptive-thinking extension may adjust only inside the session's
range. Bounds are isolated per worker and never rewrite global adaptive-thinking
configuration. Invocation and chain-slot overrides use the same fields; false
clears one field for that invocation.
For least privilege, load the extension explicitly and select only its adaptive tool, for example:
thinking: high
thinkingMin: medium
thinkingMax: high
extensions: /path/to/adaptive-thinking/index.ts
tools: read, bash, ext:adaptive-thinking/set_thinking_effort
ext:<extension>/<tool> resolves after worker extension loading. If the provider is
missing, the selector is skipped with a diagnostic; it never activates sibling
extension tools. A configured provider that fails to load or is removed by explicit policy
remains a setup error. Ambiguous or malformed selectors still fail closed. Explicit
allowlists that select no usable tools also fail closed instead of widening to
Pi defaults. Bounds remain dormant if adaptive-thinking is absent. A loaded
set_thinking_effort provider must acknowledge pi-delegate's session-local
policy protocol v1 or the worker fails before model work.
Nested delegation uses a separate depth policy. Its conservative default is 3,
but a fresh root agent may set maxSubagentDepth to 3, 4, 5, or another
deliberate value up to the global hard ceiling of 16. Ordinary descendants can
tighten that inherited root cap but cannot raise it. This keeps ordinary calls
shallow without rejecting valid multi-stage orchestrator trees.
Detached driver mode
mode: "driver" hosts exactly one durable pi-daemon session that survives
caller exit. Launch returns after prompt acceptance; use delegate_control
prompt_status and result to retrieve completion after caller or daemon
restart. Pi-daemon's session file is authoritative; pi-delegate stores only its
locator.
Driver entries accept model, env, and task handoff, but reject cwd,
interactive, worktree, and escalation; thinking and skills are inert.
Task handoff reaches a usable session-tasks claimant before the first model
request, otherwise it is delivered once as Markdown. The child rechecks
adaptive-thinking policy and keeps the established minimum nested-delegation
depth of 3. Foreground write confinement does not cover the detached child.
Driver control uses the authenticated daemon route:
prompt_statusqueries the durable prompt outcome without a lease.steer,follow_up, andui_answerdeliver guidance or a correlated answer.cancelacquires the lease and callsabort; live contention returnslease_held.recoverresumes an interrupted driver.
The overlay shows drivers in a status-only section with elapsed time, last
activity, PID, phase, and terminal reason. status returns that projection;
health reports the active-detached count; raw errors remain result-only. A
runner that exits before publishing a result is persisted as runner-exited and
delivered through the normal pending-wake path.
Driver runs cannot use retryOf; recover them through the control route.
Top-level parameters
{
runs: [...], // 1..6 entries, required
task?: "shared task", // used by entries that omit their own
concurrency?: 4, // max simultaneous workers
failFast?: false, // stop an ordered dispatch at the first failed layer
chain?: "saved-chain-name", // invoke a saved `.chain.md` template
agent_scope?: "user" | "project" | "both", // default "both"
worktree?: false, // one fresh git worktree per run
await?: false, // true only when the next action requires the result
sync?: false, // deprecated compatibility alias for await
notifyOnFailure?: true, // default true; set false to opt out of early failure wakes
fabric?: false, // native tools for every run; a run's true cannot undo it
}
Background (default) vs awaited completion
- Background (default for every ordinary dispatch): the tool returns immediately
with
runId+ run names; runs execute in the background; the main agent keeps working. Combined output arrives later as acustom_messagethat wakes you when you would otherwise stop. Do NOT poll or sleep; one status check at a natural checkpoint is fine. Otherwise continue with other work or let your turn end. await: true: the tool blocks until all runs finish and returns the combined output as the current tool result. Use this explicit dependency barrier only when the next action requires the answer and blocking the normal conversational path for run-control instructions is acceptable.sync: trueis a deprecated compatibility alias.
Early failure wakes and recovery (default-on)
A bounded delegate:fork-failed wake is emitted immediately when a background
run reaches terminal failure. This is on by default (notifyOnFailure: true).
Set notifyOnFailure: false to opt out to aggregate-only behavior. The wake is
bounded to runId, run identity, categorical reason, sibling statuses, and
recovery availability; it contains no free-form error/task/prompt/transcript,
path, URL, environment, or worker-output data.
Healthy siblings continue and the normal aggregate delegate:complete wake still
arrives once.
When the wake says recoveryAvailable: true, call
delegate_control({action: "recover", runId, forkName, strategy: "auto"}) only for that failed
run. Recovery dispatches an independent child run with its own runId and
completion wake — the original dispatch is never delayed or mutated. auto tries
resume (new child seeded only with a categorical failure kind, whether partial
output existed, and bounded categorical tool-activity facts) if available,
otherwise falls back to fresh (exact original config, no prior context).
strategy: "resume" fails closed when no safe context exists. Recovery preserves
the exact applicable original invocation configuration (including explicit
false/zero values), is idempotent per run, never cancels healthy siblings,
and is also available after the original aggregate completes while the same live
process and dispatching foreground session own the descriptor. Hydrated,
replacement-session, and pending-wake paths fail closed. A halted chain step is
intentionally not recoverable. See docs/early-failure-recovery.md.
Omitting both await and deprecated sync always dispatches in the background.
Structured escalation (strict opt-in, resolved per slot)
Enable escalation when safe progress may require a bounded decision outside the worker's authority, the worker may be unable to proceed, or the task, plan, spec, or model may need amendment. Workers should still decide reversible implementation-local details supported by task and repository evidence. Do not guess material scope/product changes, conflicting requirements, security or permission questions, compatibility or migration risk, destructive or irreversible actions, external side effects, meaningful cost, or anything the task explicitly requires to be escalated.
Escalation is strictly opt-in, and every slot resolves its effective mode
independently. Only a resolved mode: "local" enables a slot. Use
escalation: "local" or an object with mode: "local" to opt in an individual
run entry or saved chain step.
An agent or global policy may also supply the opt-in mode for a slot, while a
higher-precedence layer can opt it back out; authority alone does not enable
escalation. Enabled workers receive:
escalate_decisionfor a bounded choice with 2–5 explicit options; include the requiredcategory:implementationfor reversible implementation-local choices,scope-productfor material scope/product/UX changes, orsecurity-permissionfor security or permission questions;escalate_blockerwhen progress is impossible, including the cause and what would unblock it; andescalate_amendmentwhen the task/plan/spec/model needs an exact proposed change and rationale.
A generic extension ask never reaches the operator from a worker dispatch. In an
escalation-enabled slot it is safely routed to escalate_decision only when
question, 2–5 options, zero-based recommendation, explicit category, and
multiselect semantics are representable; otherwise the adapter fails closed.
Translated decisions do not apply a timeout default. In an escalation-disabled
slot, ask returns an actionable error telling the worker to stop and report the
unresolved question upward; no escalation tool exists there to call. Do not
self-answer, infer implementation for scope/product or security/permission
questions, or treat cancellation as an answer. Foreground interactive ask
remains unchanged.
In supervised mode, the fork supervisor uses resolve_escalation only when its
declared authority covers the request and it can choose safely. Otherwise it
uses escalate to pass the request upward with useful context and a
recommendation. At the root, first call delegate_escalation(action="list") to re-read
canonical state. Resolve root-held requests only inside root authority; use
action pass_up for “not mine; pass up.” A user-held request may be resolved
with delegate_escalation(action="resolve", ..., onBehalfOfUser: true) only after the
operator actually chose. Never infer or manufacture the operator's answer.
A pending request durably suspends only the raiser's tool call, without
model-token burn. Supervisors and root hops wake briefly to resolve or pass;
they must not poll, sleep, or busy-wait. Escalation relies on background
delivery, so preflight rejects await: true (and sync: true) whenever any
slot resolves to enabled. Let the current turn end while an operator-held
request remains pending; a later resolution wakes and resumes the raiser.
See docs/escalation.md for the complete schemas,
authority matrix, routing, timeout defaults, and cleanup semantics.
Parallel work with git worktrees
delegate({
worktree: true,
runs: [
{ agent: "worker", task: "Implement feature A on branch a" },
{ agent: "worker", task: "Implement feature B on branch b" },
]
})
Each run gets a fresh worktree under the OS tmpdir, branched from current
HEAD. Diffs are summarised in the combined output and the worktree is cleaned
up automatically. Requires a clean git tree in the main cwd. Per-run cwd
is rejected when worktree: true (worktree owns cwd assignment).
All delegate-owned in-process workers enforce writable-root confinement by
default and receive a unique per-worker scratch directory. write/edit paths
are checked lexically, case-aware per filesystem root, and through existing
symlinks. Use readOnly: true on the run entry to restrict primary-root
write/edit paths; scratch and separate artifact roots remain writable, while
the primary root and its ancestors are excluded. It also refuses mutating git
unless git runs (tool cwd or -C) and targets only inside scratch or the
artifact workspace, so a read-only reviewer cannot commit or switch branches in
the shared checkout; read-only git forms such as git status, git log, and
git diff run anywhere. readOnly guards against accidental writes through
write, edit, and git. It is not isolation: other bash commands are not
classified and run on the host with the worker's own permissions, so they can
write anywhere the OS allows. Prose and a tool list do not enforce read-only
behavior. To isolate a worker from your checkout, use worktree: true.
The repository-pollution guard rejects reserved or declared artifact names and
the protected .pi/pi-delegate.json config for write/edit and common shell
writes in Git worktrees. It detects the effective (last) static dd of= operand
and awk output redirection whose complete target expression is one string-literal
path. Projects can use that config's artifactNameExceptions list for legitimate
repository paths. The bash name
guard is best effort against deliberate command-form evasion, not a sandbox.
Dynamic or computed target construction, unmodelled interpreter file-open APIs
such as os.open, fs.openSync, sysopen, and File.binwrite, nested shells,
unparsed mutators, and arbitrary custom tools remain accepted residuals. The
authoritative guarantee that reserved files never reach Git is the delivery/CI
gate, whose git-level staged/tracked check catches files however they were
created. Direct
workers and supervised forks report git-only mutation attribution. Configure
writableRoots or confineWrites: false per slot; see
docs/write-confinement.md.
A worker may write only inside its cwd, its own scratch directory, its artifact
path, and roots granted with writableRoots; a readOnly worker loses its cwd.
Other absolute paths, including the rest of /tmp, are refused, so "write the
report to /tmp/foo.md" fails however it is phrased. Scratch is removed when
the run ends.
Pick the worker by what the task returns
- Findings, a review or an answer:
readOnly: true. The worker returns its findings in its final message, and you read them from the result. It can still orient itself:git status,git log,git branch --show-currentandgit remote -vrun without a refusal, so a rule to name the repository and branch is satisfiable. - A file you want back:
artifact: "<name>.<ext>"(one basename; works withreadOnly). The runtime gives the worker one absolute path inside that worker's own attempt directory, then validates the file and returns it with the result. That path is never the worker cwd or a sharedoutput/directory under pi-delegate's data root. Its root defaults to the OS temporary directory, so it can be under/tmp; use the exact path given. - A file in the workspace: a writable worker (no
readOnly) that writes at a workspace-relative path. GrantwritableRootsfor a path outside its cwd.
delegate({ runs: [{ agent: "reviewer", readOnly: true, task: "Review src/auth.ts for token leaks. Report findings in your final message." }] })
delegate({ runs: [{ agent: "worker", readOnly: true, artifact: "audit.md", task: "Write the audit as Markdown to your artifact path." }] })
delegate({ runs: [{ agent: "worker", task: "Write docs/auth.md describing the token flow." }] })
readOnly: true does not combine with writableRoots. A read-only worker may
write only its scratch directory and its artifact workspace, so a granted root
never takes effect -- including one outside the worker's own root. A grant at,
inside, or containing the primary root is now rejected at dispatch rather than
silently ignored; before that, the worker did its whole task and the write
failed at the end, after which the scratch directory was removed and the work
was unrecoverable.
The worker is told its own write scope automatically, so the task text does not need to name a scratch path — and must not hard-code an out-of-scope one.
Steering a supervised fork
Steering is supported for an explicit supervised run. It targets the fork,
the copied main-agent supervisor context; guidance reaches that supervisor,
which guides the delegated worker. Direct workers, chain steps, and unknown
in-process shapes reject steering rather than assuming a supervisor.
Use it sparingly — frequent interruptions defeat the purpose of delegation. Prefer letting the supervised session finish unless it's clearly off-track.
delegate_control({
action: "steer",
runId: "...",
forkName: "reviewer-a", // the compatibility field for this run's address
message: "Focus only on the locking logic; skip naming nits.",
deliverAs: "steer" // or "followUp" or "queue"; default = best-effort ladder
})
forkName also accepts the display label the widget shows, when exactly one
live supervised entry owns it; the result then tells you which supervised entry it resolved to. A name
that matches nothing, or a label that matches two supervised entries, is an error that
changes nothing — it never falls back to the broadcast. The run name is the generic
addressing key used by control actions across direct workers, supervised forks,
and chain steps; forkName remains the control API's compatibility spelling.
The user can also steer interactively from the overlay (Option-O / Alt+O,
or Ctrl+Alt+D → select entry → Tab → type → Enter).
Cancelling
The operator-facing command is /delegate-cancel [RUN_ID [ENTRY]]. With no
arguments it lists live targets. RUN_ID ENTRY cancels one exact entry without
confirmation. Bare RUN_ID confirms whole-batch cancellation.
Esc keeps its local context: foreground-turn interruption, inspector ascent or
close, and confirmation dismissal. Use /delegate-cancel for an explicit target.
The agent-facing equivalent is:
delegate_control({ action: "cancel", runId, forkName?, reason? })
Cancellation addresses any ordinary delegated run entry: a direct worker, a
supervised fork plus its delegated worker, or a chain step. Existing
authorization rules still apply. Omit forkName to abort the whole batch. Any
blocking worker UI prompts resolve to their default. Completion still wakes the
main agent.
Run-entry timeout policy is opt-in by default: global perForkMaxDurationMs
(0 by default) is an absolute operator ceiling. Agent definitions and
run entries can set max_duration_ms and
wind_down_grace_ms; precedence is invocation > agent > global, with explicit
0 disabling a layer unless a positive global ceiling clamps it. Solo runs
resolve the same budget at the dispatch boundary through the same precedence
(#287). They arm it when the first worker session becomes steerable, before
extension binding and prompt delivery. max_duration_ms is the
explicit worker execution limit; it is not a promise that the
outer delegate call returns at that exact wall-clock instant. On timeout,
the supervisor/fork-clone still has to wind down, cancel its worker, persist
the terminal result, and collapse the fork. That shutdown overhead can make
observed wall-clock duration exceed max_duration_ms, while the result still
correctly reports cancelReason: "timeout". A refusal fallback shares that first
deadline; changing models does not restart the clock.
For a long solo run that writes incremental findings, set one artifact file.
The worker must write it at the absolute artifact-workspace path the runtime injects. On clean
completion, the runtime reads its non-empty contents and uses them as the
worker's deliverable. Missing or invalid artifacts fail the step; the runtime
never substitutes the final assistant message.
check is an optional shell command beside artifact on an independent solo run.
The runtime runs it after the producer finishes. A failed check retries that producer
exactly once with the checker's bounded output, and a second failure fails the run.
A successful artifact writes manifest.json: check.status is pending without a
checker and records the checker result otherwise.
Per-run check does not compile into ordered runs. A dispatch with any after entry
rejects a per-run check instead of dropping it. For an ordered or saved-chain
producer, declare both artifact and check in that producer's agent frontmatter;
the agent-level checker applies to its chain step.
Timeouts do not inspect or publish a declared artifact. The run remains
truthfully aborted/timeout, and any final message remains a handoff.
Choosing and retrying timeout budgets
Budget for the work the worker must do, not just the model's next response:
- Start bounded inspections and code reviews at 5–10 minutes. Use 15–30 minutes for builds, integration tests, or work that may wait on tools.
- Add a
wind_down_grace_mslarge enough for the supervisor to collect a useful result. A 60–120 second grace window is a practical starting point when the worker may finish near the limit. - If a timeout is otherwise healthy, retry once with roughly 2× the worker budget and a matching grace window before changing the task or model.
- If a second timeout occurs, inspect
delegate_control(action="result")and the run activity. Then narrow the task, split the work, or stop retrying. Do not treat a longer outer wall-clock wait as proof that the worker received more execution time.
Discovering available agents
Bundled builtin agents (always available): delegate and worker. Companion
development-tool packages can ship the scout, planner, reviewer,
implementer, and integrator workflow agents. Plus anything in
~/.pi/agent/agents/, ~/.agents/, or project-local .agents/ / .pi/agents/
directories.
implementer is the language-agnostic implementation worker (it loads
implement plus the matching implement-<language> orientation).
integrator is the narrow merge helper for putting finished parallel work onto
one branch (it loads merge-coordinate). For planning and dispatching that
parallel work in the first place, load orchestrate-work.
Use /delegate --agents (humans) or read the relevant .md definition
(agents) to see what each one does.
Picking a collapse mode
final_output(default) — return whatever the supervisor passes tofinish_delegation({ final_output }). Use this when the supervisor itself has produced the answer you want.summary— ask the supervisor for a concise closing note. With nosummary_model, that note is returned verbatim with zero summarizer provider calls. Pinprovider/modelto refine the full transcript, or use literal"auto"to select onlyanthropic/claude-haiku-4-5. If Haiku is unavailable, collapse retains the supervisor hint and does not select another model. Before any worktree or fork is created, the dispatch preflight emits at most one diagnostic warning when configured summary references are unavailable in the active registry or session scope. For a narrow registry, set per-runsummary_model, agent frontmattersummary_model, ordelegateConfig.agentOverrides.<agent>.summaryModelto an available model. The per-run value wins over the effective agent default. The warning is advisory and never selects a fallback. For reviews, preferfinal_outputunless a separate transcript-collapse pass is genuinely needed.
Common patterns
Advisory review of staged work (supervised, so clone_mode is valid):
delegate({ runs: [{ agent: "reviewer", task: "Review the diff for bugs",
mode: "supervised", clone_mode: "snippet", snippet_last_n: 20 }] })
Two specialists in parallel:
delegate({ runs: [
{ name: "callsites", agent: "scout", task: "Find every call site of foo()" },
{ name: "refactor", agent: "planner", task: "Plan a refactor that renames foo to bar" },
]})
Cheap self-contained research (solo — no clone_mode, there is no supervisor):
delegate({ runs: [{ agent: "worker", task: "Summarise the OAuth2 PKCE flow" }] })
For web research, see the README guidance on host-specific search/fetch tools.
Ordered pipeline — each layer waits for the whole one before it:
delegate({ runs: [
{ name: "scout", agent: "scout", task: "Inventory the session store" },
{ name: "plan", agent: "planner", task: "{previous}", after: "previous" },
{ name: "review", agent: "reviewer", task: "{previous}", after: "previous" },
]})
Implementation handoff with git isolation:
delegate({ worktree: true, runs: [
{ agent: "worker", task: "Implement plan in scratch/plan.md", mode: "supervised", rounds: 8 },
]})
Watching delegated work live
- Status widget below the editor — one line per active run. Wide rows show
each run's current deterministic or opt-in semantic ticker headline and
update immediately when it changes; a ~10 s refresh advances elapsed time.
Each row also shows a compact rolling chip such as
12k tok/$0.084, summed across the supervisor clone (when present), worker, caches, and that run's activity-ticker usage. Message counts use the compact8msgform. The narrow◆Nrow aggregates usage over the visible runs. - Footer ticker — aggregate live and briefly retained terminal counts for every run count; per-run identities and headlines stay in the widget.
- Transcript inspector —
Option-O/Alt+O,Ctrl+Alt+D, or/delegate-inspector.- The header keeps a persistent
live N:summary;N live elsewhereexplains historical selection. ←/→switch run entry,{/}switch run,[/]jump message,ljumps to/cycles live runs.↑/↓scroll,Endresumes auto-follow,tcycles thinking detail, andgcycles tool detail.s→ compose →Enterto steer the selected supervised fork.xthenyto cancel the selected run entry.
- The header keeps a persistent
Gotchas
- Never poll or sleep after dispatching. Results wake you when you would
otherwise stop. A single
delegate_control(action="status")check at a natural checkpoint is fine; a status loop orbash sleepwastes tokens and time. clone_mode: "full"copies the entire main-thread history into the fork. Cheap mid-session delegations should usesnippetortask_only.- Fork-clone needs the main agent's model configured in
ModelRegistry— if your main model lacks auth, fork creation fails. - Worker sessions are saved under
~/.pi/agent/sessions/forks/— a discoverable subdir of the main sessions dir, kept out of/resume's per-cwd picker. Open withpi --session <path>. - Outside the opt-in escalation native prompt and existing overlay controls,
there is no general mid-fork user-driven supervisor UI. The main agent still
drives the fork; a
supervisor: "user"mode is not implemented.
Reference
- Use
pi listto locate the active package source; editable package checkouts should not live under~/.pi/agent/extensions/. - Full package docs:
README.mdanddocs/escalation.mdrelative to the active package root (parameters, config, builtin agents, testing, and security notes).
Retrying a failed attempt
Use retryOf: { runId, forkName } on an ordinary supervised run entry, direct
run entry, or single direct run. Copy the exact stored forkName, provide a corrected
task and any needed cwd or worktree settings, and expect a new attempt.
Only failed and aborted predecessors qualify; count > 1, live/completed/
paused predecessors, duplicate or already-replaced references, chains, and
saved chains are rejected. A valid unresolved lane is retained as one component within the 25-run durable
completed-record budget; malformed hydrated relationships are quarantined and fail
closed without hiding their rows. retryOf hides only the valid predecessor
row in the owner-scoped ambient widget. Public retry metadata is capped at 32
entries separately from the 24-attempt retention-safe lineage bound and reports explicit
incomplete/truncated flags consistently across status, result, synchronous
returns, live wakes, and durable redelivery. Cumulative presentation may carry
prior usage for a zero-usage attempt, while accounting stays attempt-local. It
is not delegate_recover, which has separate recovery/resumption authority.
Nested coordinator synthesis
For a nested coordinator, delegate:complete starts a fresh result window. Its
next answer must be one self-contained synthesis of the completed children;
pre-wake progress is not concatenated into that result. While owned children
remain live, pi-delegate keeps the coordinator session available through
agent_end until a child wake, queued input, cancellation, or provider failure
advances the lifecycle. Coordinator shutdown aborts its unfinished children.
04 同仓库更多 Skills
work-execution
Execute a validated pi-work node or wave when you need the ready-set, by-reference work_plan brief, Fabric default, pi-delegate fallback, explicit tree-bound verification, remediation, scope amendments, or a post-integration refactor pass. Use after decomposition and before claiming any node is done.
work-decomposition
Turn a validated pi-work intent into a strict workspec work graph when the work is too large for one bounded worker. Use when assigning criterion homes, dependencies, honest write scopes, open decisions, or optional model-change nodes before planning execution.
work-authoring
Draft a pi-work workspec when an outcome, scope, or proof obligation is still unclear. Use this before turning a conversation, issue, or design into a markdown draft, especially when acceptance criteria need to survive lossless promotion into strict YAML.
intent-records
Draft or approve an intent record when a person asks for a change, or describe existing behaviour before retrofitting compiled intent. Use before turning intent into a pi-work workspec.
intent-conformance
Connect an approved finite Bend model to actual application code with a language-neutral conformance manifest, app-language oracles and a broken-model control. Load when proving implementation parity or diagnosing decision drift.
compiled-intent-model
Author or change a finite Bend model from an approved intent record, review its meaning, obtain human law approval, and produce an offline-verifiable Jev receipt. Load for model-change nodes, not for emergent runtime behaviour.