pi-subagents 0.82.0 → 0.83.0

package/bundle/intercom-bridge.js

@@ -1,9 +1,9 @@
 import {
   resolveIntercomSessionTarget
-} from "./chunk-XSWOTIA3.js";
+} from "./chunk-MHX22USZ.js";
 import "./chunk-7F6RKT6W.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+import "./chunk-7F5SK2U3.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
 import "./chunk-Z7KVHQHL.js";
 export {

package/bundle/preflight.js

@@ -2,22 +2,22 @@ import {
   buildEffectiveSystemPrompt,
   canPreferForkFromSnapshot,
   resolveSubagentLaunchContext
-} from "./chunk-GJECHSAR.js";
-import "./chunk-PLCCBLPY.js";
+} from "./chunk-HLE22FSH.js";
+import "./chunk-Y3I6H6DV.js";
 import {
   loadConfig
-} from "./chunk-NGGAFDL6.js";
+} from "./chunk-RZJN63GU.js";
 import {
   nestedResultsPath,
   processTerminalCandidatePath,
   processTerminalPath,
   resultFilePath
-} from "./chunk-NRQ75MGH.js";
+} from "./chunk-5ESXK62X.js";
 import {
   applyIntercomBridgeToAgent,
   resolveIntercomBridge,
   validateIntercomBridgeConfig
-} from "./chunk-XSWOTIA3.js";
+} from "./chunk-MHX22USZ.js";
 import {
   AGENT_DEFINITION_PROJECTION_VERSION,
   resolveLaunchBinding,
@@ -26,7 +26,7 @@ import {
 import {
   applyThinkingSuffix,
   resolvePiLaunchToolPlan
-} from "./chunk-4SDU2BZX.js";
+} from "./chunk-CSSZRTKY.js";
 import {
   assertRequiredChildExtensionsAdmitted,
   resolveRequiredChildExtensions
@@ -34,7 +34,7 @@ import {
 import {
   getArtifactPaths,
   getArtifactsDir
-} from "./chunk-5TYMSZX3.js";
+} from "./chunk-VTMNBPCQ.js";
 import {
   assertClaudeCodeModelScope,
   assertThinkingWithinCeiling,
@@ -61,12 +61,12 @@ import {
   resolveSkillsWithFallback,
   resolveStepBehavior,
   unknownAgentDiagnosticContext
-} from "./chunk-CIZQXJ5Q.js";
+} from "./chunk-7F5SK2U3.js";
 import {
   DIRS,
   SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
   TEMP_ROOT_DIR
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
 import {
   capabilityCeilingAgentRestrictionMessage,

package/bundle/project-panes.js

@@ -8,11 +8,11 @@ import {
   openProjectPane,
   projectPaneBindingPath,
   readProjectPaneBinding
-} from "./chunk-52UBALJL.js";
+} from "./chunk-WG2OTTAK.js";
 import "./chunk-7J4ZXMY7.js";
-import "./chunk-5TYMSZX3.js";
-import "./chunk-CIZQXJ5Q.js";
-import "./chunk-5LFLVSTM.js";
+import "./chunk-VTMNBPCQ.js";
+import "./chunk-7F5SK2U3.js";
+import "./chunk-JEZOSEWG.js";
 import "./chunk-YFCK7H2S.js";
 import "./chunk-Z7KVHQHL.js";
 export {

package/bundle/shared-types.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_FORK_PREAMBLE,
   wrapForkTask
-} from "./chunk-5LFLVSTM.js";
+} from "./chunk-JEZOSEWG.js";
 export {
   DEFAULT_FORK_PREAMBLE,
   wrapForkTask

package/docs/agents.md

@@ -43,7 +43,7 @@ Builtins load at the lowest priority, so a user or project agent with the same n
 | `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
 | `evidence-auditor` | Independent evidence review of important claims in an existing research brief. |
 | `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
-| `reviewer` | Code review and small fixes. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
+| `reviewer` | Read-only code review. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
 | `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
 | `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
 
@@ -650,11 +650,10 @@ The package bundles a `pi-subagents` skill that is automatically available to th
 
 What it covers:
 
-- **Delegation patterns**: how to select a bounded agent and single, parallel, scripted, or async shape after delegation is authorized, including fresh or forked context.
-- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel review, review-loop, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup.
-- **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers.
-- **Safety boundaries**: child agents must not run subagents unless their resolved builtin tools explicitly include `subagent`, must not invent intercom targets, and must escalate unapproved decisions.
-- **Intercom conventions**: when to ask vs send, and how parent-side supervisor/result delivery works through the native channel.
-- **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action.
+- **Calls**: the common `subagent` calls, workflow script and resume shapes, and async waiting rules.
+- **Delegation rules**: when to delegate at all, what every child brief contains, one writer per worktree, fresh or forked context, and what to do when a lane fails.
+- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command: parallel review, review loop, parallel research, gather-context-and-clarify, parallel cleanup, and oracle consultation.
+- **Orchestration**: splitting work into lanes, review loops, finding disposition, and gate-failure triage.
+- **Lookups**: which `guide` section answers each rarer question, so the skill does not copy this reference.
 
 If you are writing an agent that has been asked to orchestrate subagents, the bundled skill helps it behave correctly without guessing the patterns. If you are a human user, you do not need to read it; the README and prompt shortcuts encode the same workflows in user-facing form.

package/docs/configuration.md

@@ -124,7 +124,7 @@ Pi records each tool definition and prompt section a session declares, and decla
 { "disabledFeatures": ["watchdog", "panes", "preflight", "lane-metadata", "gates"] }
 ```
 
-Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, and any request that still uses one of its parameters or actions fails with an error naming this setting. The check covers the parent tool, fanout-child tools, RPC, slash commands, prompt templates, scheduled launches, delegated launches, and workflow `runs.run`/`runs.all`/`runs.lanes` children, which are rejected before they launch. The built-in tool descriptions, the unknown-action list, the fanout-child tool description, and RPC `ping` no longer mention disabled features, and `{ action: "guide", options: { topic: "tool-reference" } }` starts with a notice listing what is disabled. Custom tool descriptions are not changed. Nothing is disabled by default, and the default schema and description are unchanged. An unknown or duplicate feature name fails config loading rather than silently re-enabling every feature.
+Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, and any request that still uses one of its parameters or actions fails with an error naming this setting. The check covers the parent tool, fanout-child tools, RPC, slash commands, prompt templates, scheduled launches, delegated launches, and workflow `runs.run`/`runs.all`/`runs.lanes` children, which are rejected before they launch. The built-in tool descriptions, the unknown-action list, the fanout-child tool description, and RPC `ping` no longer mention disabled features. Every `{ action: "guide" }` response starts with a notice: a topic lists what is disabled, and a section points to the `tool-reference` topic for that list. With `workflow-scripts` disabled, the notice also says to use the top-level `tasks` or `chain` fields instead. Custom tool descriptions are not changed. Nothing is disabled by default, and the default schema and description are unchanged. An unknown or duplicate feature name fails config loading rather than silently re-enabling every feature.
 
 | Feature | Parameters removed | Actions rejected |
 |---|---|---|

package/docs/extension-api.md

@@ -129,6 +129,7 @@ Method notes:
 Capability advertisements on `ping`:
 
 - `events.asyncComplete` — exact process-local completion correlation after RPC `spawn`.
+- `events.jobsChanged`, `events.asyncStarted`, `events.childStatus`, `events.processTerminal` — the event names a host can listen to instead of polling `status` (see [Refresh a host view without polling](#refresh-a-host-view-without-polling)).
 - `managementActions` — exact schedule management actions accepted by RPC `manage`.
 - `launchResolvedExtensions` — the optional launch-resolved extension projection in status details.
 - `runtimeAcknowledgedExtensions` — the optional child-runtime acknowledgement projection and event name.
@@ -141,6 +142,20 @@ Capability advertisements on `ping`:
 
 Structured delegation progress updates carry `runId` as soon as foreground execution allocates it, so a caller can retain the package-owned revival target even if its own tool turn is interrupted before the terminal response. Foreground `details.results[]` rows also include a numeric `index` that is unique within the run and stable across partial progress snapshots and the final result; use `(runId, index)` instead of row position to correlate single, counted parallel, and chain children.
 
+### Refresh a host view without polling
+
+A host that shows background subagent activity (an editor panel, a footer, a status bar) can read `status` when something changed instead of on a timer:
+
+1. Subscribe to the names under `ping.events`: `jobsChanged`, `asyncStarted`, `childStatus`, `asyncComplete`, and `processTerminal`.
+2. Read `status` once, when the host starts or reconnects. Events are not replayed after a host restart, and subscribing first means a change during that read still triggers another one.
+3. When any of the events fires, read `status` again. Events can arrive in bursts and can repeat, so coalesce them in the host, for example one `status` read per 250 ms, and keep a refresh that arrives while a read is in flight for after it ends.
+
+`subagent:jobs-changed` carries only `{ version: 1 }`. It fires whenever the parent's background job view changes: a run starts, moves to another step (no other event reports a chain or parallel run's step changes), reports new activity (a tool, a turn, tokens, or output), finishes, or is cleared from the widget. While a child streams output this can be about once per second per run. Starts and finishes fire right away; step and activity changes fire when the parent next reads the run's status file, which on macOS is a check every 5 seconds. It fires only in sessions with a UI, which covers interactive and RPC mode; print mode (`pi -p`) and SDK embeddings without a UI do not get it. It fires even when the async widget is turned off.
+
+Foreground children are not background jobs. Their progress arrives as updates to the parent's `subagent` tool call (Pi's `tool_execution_update` events), with the `details.results[]` rows described above.
+
+To rebuild what ran in a session after a reload, read the records the session file already holds: the `subagent` tool result's `details.results[]` for foreground runs and the `subagent-notify` message's `details.runs[]` for background runs (see [Host session lifetime and completion wakes](#host-session-lifetime-and-completion-wakes)). The `cost` method returns per-child rows built from the same records.
+
 ### Direct async launch correlation
 
 Direct async runs retain their originating `toolCallId` in status and result
@@ -440,16 +455,16 @@ const dispose = registerBackgroundWorkProvider({
   name: "my-background-extension",
   wakeChannels: ["my-extension:job-finished"],
   listActiveWork: (context) => jobs
-    .filter((job) => job.status === "running" && (!context || job.ownerSessionId === context.sessionId))
+    .filter((job) => job.status === "running" && (!context || context.sessionIds.includes(job.ownerSessionId)))
     .map((job) => ({ id: job.id, sessionId: job.ownerSessionId })),
-  reconcile: ({ sessionId, nowMs }) => reconcileJobs(sessionId, nowMs),
+  reconcile: ({ sessionIds, nowMs }) => reconcileJobs(sessionIds, nowMs),
 });
 ```
 
 Semantics:
 
-- Each item needs a stable provider-local ID and the exact Pi session ID that owns it. `bg_wait` captures those identities rather than a count, so one job finishing while another starts still satisfies first-completion waits without losing the replacement.
-- `listActiveWork` receives an optional `{ sessionId, nowMs }` context during snapshots. Providers can use `sessionId` to avoid scanning unrelated work; existing zero-argument `() => items` providers continue to work, and returned items are still validated and filtered to the exact requested session.
+- Each item needs a stable provider-local ID and the session that owns it, as either `ctx.sessionManager.getSessionId()` or the session file path (`ctx.sessionManager.getSessionFile()`); both are accepted. `bg_wait` captures those identities rather than a count, so one job finishing while another starts still satisfies first-completion waits without losing the replacement.
+- `listActiveWork` receives an optional `{ sessionId, sessionIds, nowMs }` context during snapshots, and `reconcile` receives the same fields. `sessionIds` holds every form of the current session (its file path when it has one, and its session id); `sessionId` is the first of them. Providers can use them to avoid scanning unrelated work; existing zero-argument `() => items` providers continue to work, and returned items are still validated and filtered to the current session. Each provider is called once per snapshot.
 - It filters snapshots to the active session, fails closed if a provider disappears while its work is tracked, and surfaces malformed snapshots or provider errors with provider context.
 - Wake channels only shorten polling; validated snapshots remain authoritative.
 - Providers share a registry through `Symbol.for("pi-subagents.background-work.v1")`, allowing independently loaded extension modules to meet in one Pi process.

package/docs/observability.md

@@ -334,6 +334,7 @@ Async events:
 
 - `subagent:async-started`
 - `subagent:async-complete`
+- `subagent:jobs-changed` (see [extension-api.md](extension-api.md#refresh-a-host-view-without-polling))
 
 For regular async starts, the `subagent:async-started` payload includes redacted `task` and `goal` prompt fields. Async workflow script roots emit the same event with `mode: "workflow"` after their initial `status.json` is durable; workflow roots can omit `task`, and any included prompt fields are redacted. Their keyed children are then announced dynamically through `subagent:child-status`. Companion UI extensions can combine those hints with the authoritative live lifecycle artifacts under `asyncDir` without scraping terminal output.
 

package/docs/tool-reference.md

@@ -110,7 +110,7 @@ The `subagent` tool schema lists `agent`, `task`, `workflow`, `args`, `async`, `
 | `options.checkpointBeforeDeadlineMs` | number | none | Async single-agent runs only. The runner requests that the child "checkpoint and stop" this many milliseconds before the run deadline (finish the current tool call, report changed files, build/test state, remaining work, commit/PR state; start no new work). This best-effort steer uses the normal steering lifecycle at the next tool boundary, so the receipt is visible in status and events; the ordinary deadline kill still applies. Precedence: call value → config `checkpointBeforeDeadlineMs`. Disarmed when the deadline leaves under one second before the checkpoint. |
 | `options.toolBudget` | object | none | Optional child tool-call budget `{ soft?, hard, block? }`: `hard` is a positive integer and `soft`, if set, is a positive integer no greater than `hard`. At `soft` the child is nudged to finalize. After `hard`, configured tools are blocked; `block` defaults to `read`, `grep`, `find`, and `ls`, and accepts either a nonempty array of tool names or `"*"` for every tool call. Final assistant text is never blocked. |
 | `options.usageBudget` | object | none | Optional root-only reported-usage budget `{ tokens?: { soft?, hard }, costUsd?: { soft?, hard } }`. Include at least one metric; each `hard` must be positive and each optional `soft` positive and no greater than its `hard`. Soft limits are status-only. Hard limits prevent later child launches after reported usage is reconciled; already-running children are not stopped and no reservations are made. |
-| `options.extensionBindings` | object | none | Child-only plain JSON keyed by namespaces like `package.name/1` (positive version): at most 16 namespaces, nesting depth 16, 256 total object properties, and 16 KiB of canonical UTF-8 JSON. Native Pi launches only; external runners and retained resumes reject it. |
+| `options.extensionBindings` | object | none | Child-only plain JSON keyed by namespaces like `package.name/1` (positive version): at most 16 namespaces, nesting depth 16, 256 total object properties, and 16 KiB of canonical UTF-8 JSON. Native Pi launches only; external runners and retained resumes reject it. A child's extensions read it as canonical JSON from `PI_SUBAGENT_EXTENSION_BINDINGS` in their factory or `session_start`; a foreground child sees it only until its session has started, after which the parent's environment is restored. |
 | `options.preflight` | object | none | Advisory lane hints for raw scripts (`workflow: true` or a script path) only; not accepted with named workflows or direct children. See [bounded workflows](workflows.md#opt-in-bounded-workflows). |
 | `cwd` | string | runtime cwd | Override working directory. With `machine`, the directory on that machine. |
 | `options.machine` | string | - | Herdr saved machine (label or profile id) for external-cli agents; see [agents.md](agents.md#running-external-cli-agents-on-a-herdr-saved-machine). |

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "pi-subagents",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",

package/skills/council-mode/SKILL.md

@@ -9,10 +9,7 @@ Council mode is parent-supervised advice for a material decision with real trade
 
 The parent selects the roster, relays only curated claims, decides validity, and writes the memo. Advisors stay read-only and do not see peer transcripts by default.
 
-Before launch, read:
-
-- `skills/pi-subagents/references/execution-controls.md`
-- `skills/council-mode/references/pass-contracts.md`
+Before launch, read `skills/council-mode/references/pass-contracts.md`.
 
 ## Roster
 

package/skills/pi-subagents/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pi-subagents
 description: |
-  Technical guidance for operator-requested delegation to builtin or custom
-  subagents: bounded handoffs, parallel review, scripted workflows, async work,
-  forked context, isolation, and coordinated execution.
+  Delegate work to Pi subagents after the operator asks for it: one child,
+  parallel or scripted workflows, async runs, resume/steer/stop, review fanout,
+  and multi-lane or worktree orchestration.
 ---
 
 # Pi Subagents
@@ -14,111 +14,134 @@ instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
 available specialist does not independently authorize delegation.
 
 Once authorized, choose the smallest bounded shape that earns its token and
-elapsed-time overhead through concrete evidence, independent review,
-specialization, useful parallelism, or needed isolation. A single child is
-valid; writer, challenge, and review stages must each earn their overhead rather
-than becoming default ceremony. The parent keeps user intent, constraints,
-routing, arbitration, decisions, final acceptance, and publication authority,
-and may perform the work directly where it is the most efficient owner.
+elapsed-time overhead through evidence, independent review, specialization,
+useful parallelism, or isolation. A single child is valid. The parent keeps
+intent, routing, decisions, final acceptance, and publication authority, and
+does the work itself where that is cheaper.
+
+## Calls
+
+```typescript
+subagent({ agent: "worker", task: "<brief>" })                    // one child; async by default
+subagent({ workflow: "parallel", args: { tasks: [{ agent, task, cwd?, model? }] } })  // independent children
+subagent({ workflow: true })              // runs the one ```js workflow block in this same reply
+subagent({ workflow: "./lane.js", args }) // script file, path relative to the request cwd
+subagent({ action: "validate", workflow: "./lane.js" })          // check a script without launching
+subagent({ action: "status", id })        // options: { view: "fleet" } or { view: "transcript", index: 0 }
+subagent({ action: "resume", id, message })   // completed or paused child; returns a new run id
+subagent({ action: "steer", id, message })    // live async child
+subagent({ action: "stop", id })              // ends the run; not resumable
+subagent({ action: "interrupt", id })         // pauses the child's current turn
+subagent({ action: "list" })  ·  subagent({ action: "models" })
+subagent({ action: "guide", options: { topic: "<section address>" } })
+```
+
+Launches are async by default. Set `async: false` only when the parent must
+block; final reviews and gates stay async. After launching, keep doing safe
+independent work, or yield: native completion wakes this session. Do not sleep,
+poll, or call `bg_wait` for ordinary children. Use `bg_wait` only for provider
+or detached work that has no native notification and whose result this turn
+needs.
+
+## Workflow scripts
+
+Use a script when later steps depend on earlier results, or for keyed,
+retried, aggregated, or resumed children. Write one ```` ```js workflow ````
+block in the reply and call `subagent({ workflow: true })` in the same reply.
+For a long script, write it to a file and pass `workflow: "./path.js"`; calls in
+one reply run at the same time, so write the file in one reply and `validate` or
+launch it in the next. When a `workflow: true` call reports the block missing,
+pass the source as `options: { script: "..." }` in place of `workflow: true` for
+the rest of the turn: on some hosts, text after a tool call reaches the session
+as a summary without the block.
+
+```js workflow
+const scan = await runs.run("scan", { label: "Map auth flow", agent: "scout", task: "..." });
+const reviews = await runs.all([
+  { key: "correctness", label: "Review auth correctness", agent: "reviewer", task: "... " + scan.output },
+  { key: "tests", label: "Review auth tests", agent: "reviewer", task: "..." },
+]);
+return reviews.map((review) => review.output);
+```
+
+- Scripts are statement bodies with an explicit `return`, top-level `await`,
+  and plain helpers. Nested async functions, arrows, and methods are rejected.
+- Every `runs.run` / `runs.all` item needs a stable `key`. Add a short
+  verb + behavior `label` unless the user gave one.
+- Bind files with `output: "plans/x.md"` (relative paths land in run
+  artifacts) and return `outputReference` or `artifactPaths`. A filename in
+  task text does not route output. Never send reports to the repo root.
+- `runs.lanes([{ key, stages: [...] }])` runs a predeclared plan: first stages
+  together, later stages in order per lane.
+
+Resuming a retained child:
+
+```js workflow
+let child = await runs.run("fix-1", { agent: "worker", task: "..." });
+child = await runs.run("fix-2", { resume: child.runId, task: "Apply these accepted findings: ..." });
+return child.output;
+```
+
+- Always resume the latest returned run id; every resume returns a new one.
+- Use a new stable key for every resume pass.
+- `resume` excludes `agent` and `gate`; the child keeps its agent, model, and tools.
+- Resume a completed child; steer a live one. Top-level `{ action: "resume" }` is detached.
+
+## Briefs
+
+Every child starts cold. Its task states: goal; repo, explicit `cwd`, and
+ref; authority and edit boundary; relevant files, decisions, and evidence;
+success criteria; validation; expected output; and when to stop or ask.
+Make parallel briefs differ by seam, evidence, and decision, not just an item
+number.
+
+## Rules
+
+- One writer per cwd or worktree. Parallelize reading, review, and
+  validation. `worktree: true` needs a clean checkout (untracked files count;
+  `.pi/subagents/` does not). For Pi extension repos, put lane worktrees
+  outside `~/.pi/agent/extensions`, for example `~/.pi/agent/worktrees`.
+- Reviewers use fresh context. Use `context: "fork"` only when the child needs
+  the parent's history; it requires a persisted parent session.
+- Children do not spawn subagents unless the parent delegated fanout and their
+  resolved `tools` include `subagent`.
+- A failed workflow, launch, prompt runtime, extension load, or child tool
+  setup blocks the lane. Stop, report the exact failure and run/worktree state,
+  verify a clean worktree or capture the partial diff, then retry the same way
+  once. Switching to `interactive_shell`, `pi -ne`, or another CLI needs owner
+  approval.
+- As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+- Route workers and scouts to a fast capable tier, serious reviews to a strong
+  tier, and top reasoning only to bounded read-only critique. Exact model names
+  belong in user or project settings, not here.
+- `subagent`, `subagents_enable`, `subagent_supervisor`, `contact_supervisor`, and `structured_output` are model-only: call them as ordinary model tool calls. Codemode scripts cannot reach them through `tools.*`, `ALL_TOOLS`, or `searchTools`.
+- Receipts, CI, and review bots are evidence, not authority. Backlog, release,
+  and merge policy belong to the user's or project's own skill.
 
-Children do not spawn subagents unless the parent explicitly delegated fanout
-and their resolved `tools` allow `subagent`.
+## Look up the rest
 
-## Launch shape
+If only `subagents_enable` is visible, call it first; `subagent` and `guide`
+work from the next request. Read one section, not a whole topic:
 
-| Need | Use |
-| --- | --- |
-| One bounded task for one child | direct `{ agent, task }` |
-| JavaScript control flow or data-dependent branching; sequence, fanout, retry, rolling fanout, or aggregation | a workflow script with `runs.run(...)` / `runs.all(...)` |
-| A broad plan split into visible narrow stages per lane | a workflow script with `runs.lanes([{ key, stages: [...] }])` |
-| Independent worktree or repository lanes | `references/multi-lane-orchestration.md` |
-| Council of advisors | `../council-mode/SKILL.md` |
-| Management, status, steering, authoring, or inspection | `action` |
-
-To launch a workflow script, write it as one ```` ```js workflow ```` fenced
-block in your reply, then call `subagent({ workflow: true, ... })` in the same
-reply. Use `workflow: "./path/to/script.js"` for a script file and
-`workflow: "<name>"` for a named resource.
-
-A workflow script is code-driven: `runs.run(...)` for keyed steps,
-`runs.all([...])` for fanout, plain JavaScript for branching and aggregation.
-Keep scripts portable: use top-level `await`, plain helpers, or explicit Promise
-chains, not nested async helpers. Legacy top-level `chain` / `tasks` inputs and
-durable `.chain.md` execution are inspection or migration material only, except
-that `disabledFeatures: ["workflow-scripts"]` replaces scripts with top-level
-`chain` and `tasks` (see [configuration](../../docs/configuration.md#chain-and-tasks-without-workflow-scripts)).
-
-Use `runs.lanes(...)` only inside a workflow script, not as a top-level mode,
-when a broad, predeclared plan benefits from visible per-lane stages; otherwise
-use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
-example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
-bounded, but do not add stages or ceremony just to satisfy this skill.
-
-When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
-supply a short verb + behavior display `label` derived from the task, unless
-the user supplied an explicit label; preserve that label. Keep the stable
-machine `key` independent (for example, `issue2011-writer` with
-`label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
-items, not lane objects. Use stage-appropriate labels for reviews and retained-child
-follow-ups too (for example, `Review workflow steering`). Generate labels in
-the orchestrator while composing the launch—no extra model call, runtime
-generator, or schema change. Native direct `{ agent, task }` calls have no
-top-level `label` parameter; do not invent one or wrap a tiny single task in
-a workflow just to label it.
-
-Use async/background by default. Set `async:false` only when the parent must
-block. Final reviews, validation gates, oracle checks, and publication checks
-stay async.
-
-In an ordinary interactive session, yield after launching or triaging useful
-async lanes and let Pi wake the parent on completion; ordinary async subagents
-already have native completion notifications, so do not call `bg_wait()` merely
-because a child is active. Use blocking `bg_wait()` only for provider,
-detached, or other background work without a native notification when a
-headless/run-to-completion contract or a required same-turn artifact makes the
-result necessary before this turn ends. For
-“continue/orchestrate/work until done,” keep the lane board moving while a safe
-immediate action remains; if only async lanes are running, record the revisit
-trigger and yield.
-
-Package agents appear in `subagent({ action: "list" })`. External CLI/job agents
-use their own runner contract. Do not pass native Pi child options to them unless
-that runner explicitly supports the option.
-
-## Read the reference for the branch
-
-For exact API fields and worked examples, call `subagent({action:"guide",options:{topic:"tool-reference"}})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
-
-| Branch | Read |
+| Need | Guide section |
 | --- | --- |
-| Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
-| Execute single, scripted, async, scheduled, mission, forked, watchdog, oracle, or intercom workflows | `references/execution-controls.md` |
-| Review, validate, triage gate failures, or prepare delivery | `references/review-and-validation.md` |
-| Coordinate lanes, worktrees, repositories, or writer waves | `references/multi-lane-orchestration.md` |
-| List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
-| Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
-
-For an authorized complex delegated workflow, read `prompting-and-roles.md` and
-`execution-controls.md`, then load `review-and-validation.md` and
-`constraints-and-recipes.md` before launch or review.
-
-## Operating rules
-
-- Avoid duplicate scouts, overlapping writers, and vague prompts without a concrete deliverable.
-- Call `subagent`, `subagents_enable`, `subagent_supervisor`, `contact_supervisor`, and `structured_output` as ordinary model tool calls. They are model-only, so codemode scripts cannot reach them through `tools.*`, `ALL_TOOLS`, or `searchTools`.
-- Keep the parent on the ordinary strong default model. Route workers/scouts to a fast capable tier, serious reviews to a strong tier, and top reasoning to bounded read-only critique.
-- Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
-- Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
-- Before launching a writer for substantial mutation work, classify it as single-seam or multi-seam and partition multi-seam work across exclusive component owners, gates, and durable handoffs before an integration-only owner. See `references/multi-lane-orchestration.md`.
-- For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. `worktree: true` refuses to launch unless the source checkout is clean (untracked files count; `.pi/subagents/` does not), so commit your own changes first or plan the lane without managed isolation. See `references/multi-lane-orchestration.md` for lane mechanics.
-- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
-- Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
-- For cross-codebase work, record the repo, explicit `cwd`, authority boundary, and expected output before launch.
-- Make parallel prompts distinct by source seam, evidence, and decision. Do not clone prompts with only item numbers swapped.
-- Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
-- For Pi extension repos under `~/.pi/agent/extensions`, put lane worktrees outside extension auto-discovery, such as `~/.pi/agent/worktrees`.
-- Preserve capability ceilings, including child tool limits and allowed-agent restrictions.
-- Preserve parent authority and escalate unresolved choices.
-- Treat receipts, CI, review bots, and external-run records as evidence, not authority.
-- For backlog maintenance, releases, merge queues, or other public-repo mutation policy, load the matching user/project skill. This package defines delegation primitives, not private policy.
-- As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+| Script API: `runs.*`, `state`, limits | `workflows/scripted-workflows` |
+| Typed gates, host commands, rolling fanout | `workflows/typed-post-run-checks-and-typed-steps`, `workflows/host-command-steps`, `workflows/advanced-rolling-child-runs` |
+| Budgets, timeouts, `baseRef`, `gate`, `output` | `tool-reference/execution-parameters`, `tool-reference/output-mode-details` |
+| Fresh or forked context | `tool-reference/fork-context-details` |
+| Resume, steer modes, stop, status | `tool-reference/retained-children`, `tool-reference/resume`, `tool-reference/steer`, `tool-reference/stop`, `tool-reference/status` |
+| Acceptance and review gates | `tool-reference/acceptance-gates` |
+| Worktrees and handoffs | `workflows/worktree-isolation` |
+| Child asks the parent (`contact_supervisor`) | `workflows/supervisor-coordination-child-asks-parent` |
+| Agent create, update, eject, disable, refine | `tool-reference/management-actions`, `agents/frontmatter-reference` |
+| Missions and schedules | `missions/missions`, `missions/schedules` |
+| Watchdog | `watchdog/when-it-runs`, `watchdog/choosing-a-model` |
+| Model overrides and profiles | `models/setting-defaults-and-overrides` |
+| Other projects in panes | `tool-reference/herdr-project-panes` |
+| Setup looks wrong | `subagent({ action: "doctor" })` |
+
+## References
+
+- Choosing roles, writing prompts, review/research/cleanup techniques, oracle → [prompting-and-roles.md](references/prompting-and-roles.md)
+- Several lanes, worktrees, repositories, staged fixes, review loops, finding and gate triage → [orchestration.md](references/orchestration.md)
+- Advisor council → [../council-mode/SKILL.md](../council-mode/SKILL.md)

package/skills/pi-subagents/references/orchestration.md

@@ -0,0 +1,124 @@
+# Orchestration
+
+Use this when several tasks need coordinated children, worktrees, or
+repositories, or when a change goes through write, review, and fix rounds.
+Create lanes only after delegation is operator-authorized and each lane
+materially improves evidence, independent review, specialization, useful
+parallelism, or isolated execution. Keep dependent work serial.
+
+## Recipes
+
+Recipes select a shape; they do not authorize delegation. Pick the smallest:
+
+- **Recon then implement:** one focused `scout`, then one `worker` that gets its findings.
+- **Implementation:** settle scope and acceptance first, then use a scout, writer, or fresh reviewer only where that stage earns its overhead. Split large work into serial milestones, not a writer swarm.
+- **Parallel analysis:** fan out only independent read, review, or validation work, or give each writer its own worktree.
+
+## Seams before writers
+
+Before launching a writer for substantial mutation work, classify it as
+**single-seam** or **multi-seam**. Two or more independently testable
+contracts or source boundaries make it multi-seam. One PR does not imply one
+writer.
+
+- **Multi-seam:** give each component writer exclusive file or contract
+  ownership, a focused gate, and a committed or otherwise durable handoff.
+  Start one integration-only owner after those handoffs are ready. Repartition
+  any writer brief that owns all major outcomes across independent boundaries.
+- **Single-seam:** one writer is right when the work is one coupled seam, or
+  when splitting would create overlapping ownership or artificial handoffs.
+  Record that evidence. Do not split coupled work to raise the lane count.
+
+## Lane board
+
+Before more than one mutation-capable lane starts, record in the parent:
+
+`Lane | repo/cwd | decision | owned files or contract | isolation path | authority | next gate | handoff | why independent`
+
+One source seam or decision is one lane. Record each lane's delivery target,
+allowed actions, validation, and review rigor. For cross-repository work,
+name the shared contract and which repository changes first. A blocked
+decision is a lane state: owner, options, recommended default, and the
+evidence needed to continue.
+
+Mutation lanes need distinct isolation paths and explicit `cwd` values.
+`worktree: true` branches from `HEAD` (or `baseRef`) and refuses a dirty
+checkout; in a shared or dirty checkout, commit first or give each lane a
+worktree you created. Use one async workflow for a coordinated wave:
+`runs.all` for independent lanes, `runs.run` for dependent stages, repo slug
+or lane key in every child key and output path.
+
+While one lane waits, run safe independent preparation, validation, or
+read-only review. When only async lanes remain, record what reopens work and
+yield; completion wakes the parent.
+
+## Review loop
+
+1. Inspect the source, diff, issue, or plan directly.
+2. One writer implements inside its boundary and runs focused validation that can fail for the changed behavior.
+3. When the delegation contract calls for independent review, fresh-context read-only reviewers inspect the actual worktree. Otherwise parent inspection is enough; skip review for trivial wording, renames, or local probes.
+4. The parent classifies findings (below) and sends accepted fixes to one writer: resume the original worker with its latest run id, or launch one forked `worker` as `/review-loop` does.
+5. Re-run affected validation and review only the changed blast radius.
+6. Stop when no blocker or fix worth doing now remains, an unapproved product, scope, or architecture decision appears, or the round cap is reached (default 3). Do not loop for polish. Children never decide the loop outcome.
+
+An async writer's handoff is an intermediate state, not completion, unless the
+user asked for writer-only work.
+
+| Situation | Review shape |
+| --- | --- |
+| One coherent diff or risk | one reviewer |
+| Independent risks (correctness, tests, security, UI) | parallel reviewers with distinct contracts |
+| Possible over-scope | same-writer challenge before fresh review |
+| Material design tradeoff | council mode |
+
+### Staged fixes
+
+When reviews have produced findings across several clusters:
+
+1. Run a read-only planning fanout, one reviewer per cluster or angle, each returning exact files, lines, fixes, and validation.
+2. Classify the accepted fixes as single-seam or multi-seam (above) on the lane board before any writer starts.
+3. Give a writer only its assigned stage. Pass each earlier result into the later task by variable or by its declared `output` path, not as a whole aggregate blob. With `runs.lanes`, keep stages narrow: red test, helper change, one render seam, validation, review.
+4. Validate the integrated result with fresh read-only reviewers on distinct angles.
+
+When a child returns a target list, validate it in JavaScript and map bounded
+entries into `runs.all`.
+
+## Finding disposition
+
+Classify each finding against the current head:
+
+- **Valid blocker:** concrete failure, repro, security issue, contract mismatch, or source-proven regression. Fix now.
+- **Valid non-blocker:** real but outside the slice. Record or defer.
+- **Stale:** already fixed or absent. Cite current evidence.
+- **Invalid:** contradicted by source, tests, docs, or approved scope. Cite it.
+- **Out of scope or policy:** needs an unapproved product, architecture, authority, or release decision. Escalate.
+- **Speculative:** no contract, repro, or reachable failure. Do not block.
+
+Classify bot comments the same way before assigning severity.
+
+## Gate failures
+
+1. Confirm the run belongs to the exact head under judgment.
+2. Read the focused failing log; name the failing test, assertion, or contract.
+3. Classify: current diff, stale test, environment, or existing flake.
+4. Reproduce with the narrowest command when practical.
+5. Patch forward when the diff caused it. For a stale or flaky failure, collect proof before one rerun.
+6. Re-run the affected command or exact-head gate after every fix.
+
+## Handoff and cleanup
+
+A handoff states lane status, repository and worktree, changed files,
+validation, open decisions, next action, and artifact or receipt paths. Copy
+only final evidence to memory, a mission, a PR, or an approved docs path, then
+remove scratch reports from the worktree.
+
+Keep a worktree until its handoff is durable, no run owns it, and no later
+gate needs it. If a run stops or needs attention, preserve its worktree and
+artifacts, then resume that run or start one replacement lane from the
+handoff. Never start a second writer while worktree ownership is unclear.
+
+Before reporting done, check the board: every lane terminal or blocked with a
+named next action; one writer per worktree; required validation and fresh
+review done; accepted findings fixed and revalidated; publication authority
+present before any push, comment, merge, or release; residual risks and
+skipped checks stated.