pi-subagents 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 ## [Unreleased]
 
+## [0.53.0] - 2026-08-20
+
+### Highlights
+- Pi extensions can now register runtime agents without writing user or project config.
+- Async workflows are easier to resume because completed children now have durable keyed receipts.
+- Model fallback is less noisy and less wasteful when a model fails or the prompt is too large.
+- Fleet and `/council` now give clearer supervision cues while keeping control in the parent session.
+- Extension RPC hosts can safely inspect status, launch async work, steer children, and manage schedules.
+
+### Added
+- Carry full model registry metadata, including tiered pricing, into normalized model information. Thanks to [@srcKod](https://github.com/srcKod) for #1317.
+- Add runtime agent registration for Pi extensions, with name and alias collision checks. Thanks to [@fmoda3](https://github.com/fmoda3) for #1310.
+- Skip recently failed fallback models for a TTL-backed window during model selection. Thanks to [@srcKod](https://github.com/srcKod) for #1318.
+- Add a schedule-only `manage` method to extension RPC for list/show/history/pause/resume/run/delete, while rejecting unrelated management actions. Thanks to [@aboubakrine](https://github.com/aboubakrine) for #1319.
+- Let agent definitions and `agentOverrides` set a default `outputMode`, while
+  call-level output mode stays higher priority. Thanks to [@bbbRye007](https://github.com/bbbRye007) for #1305.
+- Add `context: "profile"` for workflow children that should use the selected
+  agent profile's declared context instead of the global default (#1303).
+- Add durable keyed async workflow receipts and resume-by-key selectors for
+  retained workflow children (#1302).
+- Add the `resultScanLogging` config to control result scan logging. Thanks to [@apoapostolov](https://github.com/apoapostolov) for #1293.
+- Add packaged `/council` and `council-mode` resources for a bounded,
+  supervisor-mediated advisor loop, plus documented model-based `council-*`
+  profile examples (#1295).
+
+### Changed
+- Show bounded workflow progress in Fleet detail views while keeping workflow
+  parents as the only actionable async items (#1304).
+- Make `/council` easier to supervise with structured advisor contracts,
+  aggregate pass receipts, and visible pass checkpoints (#1301).
+- Reuse validated workflow launch fingerprints during `runs.all` batch setup, reducing focused fingerprint bookkeeping time by 48.7% (#1287).
+- Speed up recent terminal run history reads when the marker history is large and the requested limit is small.
+- Reduce repeated serialization while applying async status snapshot byte caps (#1288).
+
+### Fixed
+- Add tolerant `subagent_wait({ stopOnAttention: false })` blocking waits and scale idle attention defaults for higher-thinking children. Thanks to [@elecnix](https://github.com/elecnix) for #1315 and #1316.
+- Add a separate classifier for model context-overflow errors. Thanks to [@srcKod](https://github.com/srcKod) for #1312.
+- Normalize child result metadata before workflow return persistence (#1307).
+- Quote only confidently identified leading Windows executable paths in acceptance verification commands. Thanks to [@srcKod](https://github.com/srcKod) for #1294.
+- Keep forked subagent sessions out of top-level `pi -c` discovery by storing them under the parent session root. Thanks to [@xz-dev](https://github.com/xz-dev) for #1297.
+- Preserve `/council` advisor context defaults during fallback and cross-exam runs (#1298).
+
+## [0.52.1] - 2026-08-20
+
+### Highlights
+- Model setup errors now point to the right alternate provider when there is one clear match.
+- Surf's optional `gpt-pro` package agent has a smoother path to run ChatGPT Pro web jobs through the external-job bridge when the user is logged in.
+- External-job providers can add metadata or extra operations without breaking provider discovery.
+- The packaged skill now includes a concise guide for coordinating multiple tasks, worktrees, and repositories.
+- Pi extension worktrees now have clearer guidance to avoid duplicate auto-loaded tools and shortcuts.
+
+### Fixed
+- Suggest the unique alternate provider model when an explicit qualified subagent model is unavailable, without resolving across providers. Thanks to [@lallenlowe](https://github.com/lallenlowe) for #1280.
+- Accept extra fields on registered external-job providers, such as `kind`, `wakeChannels`, or additional operations. This keeps integrations such as Surf's `gpt-pro` package agent from breaking provider discovery as they add browser-backed job metadata, while job payload validation stays strict.
+
+### Changed
+- Add a pi-subagents reference for coordinating multiple tasks, worktrees, and repositories, including guidance for keeping Pi extension worktrees outside auto-discovered extension directories.
+
 ## [0.52.0] - 2026-08-19
 
 ### Highlights

package/README.md

@@ -67,12 +67,16 @@ Rule of thumb: `scout` before you understand the code, `researcher` before you t
 
 ## Common workflows
 
+The package includes `/council` and `council-mode`, plus documented model-based
+`council-*` profile examples that you add in your own agent directory.
+
 | Want | Ask naturally |
 |------|---------------|
 | Get a second opinion | "Ask oracle to review this plan and challenge assumptions." |
 | Solve a hard problem | "Use oracle to investigate this bug before we edit." |
 | Review a diff | "Use reviewer to review this diff." |
 | Run parallel reviewers | "Run reviewers for correctness, tests, and cleanup." |
+| Debate a material decision | "Use `/council` to convene architect and skeptic advisors." |
 | Implement then review | "Implement this, then review it." |
 | Review until clean | "Run a review loop on this change with a max of 3 rounds." |
 | Execute a plan carefully | "Have worker implement this approved plan, then run reviewers and apply the feedback." |

package/docs/configuration.md

@@ -160,10 +160,20 @@ Controls the under-editor widget for active background runs. It defaults to `tru
 
 Keeps the `subagent_wait` tool registered but makes direct calls return immediately instead of blocking on active subagent or provider work. The default is enabled. You can also set `"waitTool": false`; set `PI_SUBAGENT_WAIT_TOOL_ENABLED=false` (or `0`, `off`, `disabled`) to override config for one process. The effective value is passed explicitly to child runtimes. Headless `agent_end` auto-drain remains a lifecycle safeguard even when direct wait calls are disabled. Invalid config or environment values fail instead of being coerced.
 
-Blocking `subagent_wait({ id: "..." })` keeps the current tool call open until that run changes. In a long-lived interactive parent session, `subagent_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work.
+Blocking `subagent_wait({ id: "..." })` keeps the current tool call open until that run changes. By default it returns when a run needs attention. Use `subagent_wait({ stopOnAttention: false })` only for run-to-completion flows that should wait through idle or long-thinking attention; supervisor/contact requests still stop the wait. In a long-lived interactive parent session, `subagent_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work.
 
 This is different from `waitTool.enabled=false`, which returns immediately without registering any future wake. Provider items remain available only to blocking fleet-wide waits; non-blocking subscriptions require one async or remembered detached foreground run id.
 
+## `resultScanLogging`
+
+```json
+{ "resultScanLogging": "activity" }
+```
+
+Controls how slow result-index scans are logged. Defaults to `"all"`; valid values are `"all"`, `"activity"`, and `"off"`.
+
+The watcher logs `Subagent result scan inspected … scheduled …` through `console.error` whenever a result-index scan passes the slow threshold (500ms). With `"all"` (default) every slow scan is logged, including the periodic healthy rescan that inspects zero files while no async runs are pending. Those empty scans add noise to the session transcript with no signal; choose `"activity"` to log only scans that inspected or scheduled actual work, or `"off"` to silence slow-scan logging entirely. `"off"` does not disable result delivery or the watcher itself, only its slow-scan log line.
+
 ## `forceTopLevelAsync`
 
 ```json

package/docs/extension-api.md

@@ -23,10 +23,11 @@ pi.events.emit("subagents:rpc:v1:request", {
 });
 ```
 
-The RPC methods are `ping`, `status`, `spawn`, `steer`, `interrupt`, `stop`, and `resume`. `status`, `steer`, `interrupt`, and `resume` reuse the normal package-owned actions.
+The RPC methods are `ping`, `status`, `manage`, `spawn`, `steer`, `interrupt`, `stop`, and `resume`. `status`, `manage`, `steer`, `interrupt`, and `resume` reuse normal package-owned actions.
 
 Method notes:
 
+- `manage` exposes a narrow schedule-only allowlist: `schedule.list`, `schedule.show`, `schedule.history`, `schedule.pause`, `schedule.resume`, `schedule.run`, and `schedule.delete`. All actions except `schedule.list` require `id`. Mission, agent, config, worktree, and arbitrary management actions are rejected before executor dispatch. `ping.capabilities.managementActions` advertises the exact allowlist.
 - `spawn` requires `workflowScript` and is async-only: omit `async` or set `async: true`, omit `clarify`, and do not pass management `action` values. It goes through the same executor as the `subagent` tool, so agent discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status all behave the same.
 - `steer` requires an async run `id` (plus optional child `index`) and a non-empty `message`; its reply preserves the normal acknowledged-delivery result. Optional `mode` values are `steer` (default), `follow_up`, and `auto`, and receipts include `deliveryStatus: "delivered" | "queued"`. RPC steering disables the direct tool's pause-and-revive recovery in every mode so an extension keeps authority over the exact child it spawned; `ping.capabilities.nonRecoveringSteer` advertises this guarantee.
 - `resume` requires a run target and non-empty `message`. It delegates to the existing revival path, which validates current-session ownership, persisted session/recovery metadata, stopped/live state, capability ceilings, and the exclusive session lease before returning the new async run details. Callers may request a `file-only` output path for the revived result without overriding its model, tools, or budgets. `ping.capabilities.resume` advertises this seam.
@@ -35,6 +36,7 @@ Method notes:
 Capability advertisements on `ping`:
 
 - `events.asyncComplete` — exact process-local completion correlation after RPC `spawn`.
+- `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.
 - `processTerminalProof` — the process-terminal proof status (see [observability.md](observability.md#process-terminal-proof)).

package/docs/workflows.md

@@ -37,6 +37,8 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
 
 All model-facing subagent execution is expressed through `workflowScript` in the `subagent` tool. Use stable keys and ordinary JavaScript for one child, sequence, and parallelism. For ordinary parallel fanout, use `await runs.all([{ key, agent, task }, ...])`; do not read `.output` from unawaited `runs.run` launches. Store a `runs.run` promise only when the script later observes it with `await`, `Promise.race`, or `Promise.all`, such as steering a live child before awaiting its result. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
 
+Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
+
 ```js
 subagent({ workflowScript: `
   const scan = await runs.run("scan", { agent: "scout", task: "Scan the codebase" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -10,6 +10,7 @@
     "./background-work": "./src/api/background-work.ts",
     "./external-job-provider": "./src/api/external-job-provider.ts",
     "./external-runs": "./src/api/external-runs.ts",
+    "./agents": "./src/api/agents.ts",
     "./delegation": "./src/api/delegation.ts",
     "./capability-ceiling": "./src/api/capability-ceiling.ts",
     "./preflight": "./src/api/preflight.ts",

package/prompts/council.md

@@ -0,0 +1,48 @@
+---
+description: Run a bounded supervisor-mediated council of advisors and write a decision memo
+argument-hint: "<question> [--advisors name:role,name:role] [--max-passes 2|3] [--scope ...] [--non-goals ...]"
+---
+
+Run a bounded, supervisor-mediated council on this question. You, the parent
+session, are the supervisor. You select the roster, curate cross-advisor packets,
+decide which feedback is valid, and write the final memo. Advisors do not talk
+directly or see peer transcripts by default. This is not free-form agent chat.
+
+Before you orchestrate, read `skills/council-mode/SKILL.md` and
+`skills/pi-subagents/references/execution-controls.md`.
+
+Parse the invocation yourself. The flags below are conventions, not runtime
+options. Record a brief with the question, scope, non-goals, evidence targets,
+roster, roles, and pass cap. Default `--max-passes` to 2. Clamp it to 2 or 3. If
+the question is trivial or settled, answer directly instead of convening a council.
+
+## Roster
+
+- If `--advisors` is given, use exactly those `name:role` pairs. Fail clearly on an
+  unknown agent.
+- Otherwise list agents with `subagent({ action: "list" })`, then prefer 2–3
+  executable names that start with `council-`.
+- If fewer than two profiles are available, fill the roster with `oracle`, then
+  `reviewer`, until it has two advisors. Launch fallback `oracle` with
+  `context: "fork"` so global defaults cannot remove its parent-chat context.
+  Let `reviewer` use its normal profile context. Note the fallback and known
+  context modes in the memo.
+- Use the normal single-oracle loop only when a requested roster or unavailable
+  builtins leaves fewer than two advisors. Label the memo as degraded mode.
+
+Roles belong to this request, not to the profiles. Keep the roster at 2–3 and never
+exceed 4.
+
+## Run the protocol
+
+Use the canonical workflow, structured advisor contracts, aggregate pass receipts,
+and memo requirements in `skills/council-mode/SKILL.md`. Keep the parent as the
+only synthesizer and decision maker. Do not introduce a chair advisor, peer chat,
+or transcript sharing.
+
+Use its required boundary checkpoints, yield for each async workflow without
+polling, and write its required final memo.
+
+Question and options from the slash command invocation:
+
+$@

package/skills/council-mode/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: council-mode
+description: Run a bounded supervisor-mediated advisor council. Use when the user asks to convene advisors, debate a decision, cross-examine recommendations, or run /council.
+---
+
+# Council Mode
+
+This skill is for the parent supervisor only. Do not inject it into advisors. The
+parent selects the roster, curates all cross-advisor communication, decides which
+feedback is valid, and writes the decision memo. Advisors do not talk directly or
+see peer transcripts by default. This is not free-form agent chat.
+
+Use council mode for a material decision with real tradeoffs. Do not use it for a
+trivial or settled question, or for implementation work. Read
+`skills/pi-subagents/references/execution-controls.md` before you launch advisors.
+
+## Roster and limits
+
+Roles such as architect, skeptic, operator, and performance reviewer belong to the
+`/council` request. A `council-*` profile defines only model, tools, context, and
+output defaults. Its profile configuration or explicit invocation owns its context
+choice.
+
+Create model-based profiles in your user or project agent directory. Do not add
+them to this package. This is a valid example; roles still come from `/council`:
+
+```markdown
+---
+name: council-sol
+description: Read-only fresh-context advisor for bounded council decisions
+tools: read, grep, find, ls
+model: openai-codex/gpt-5.6-sol
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fresh
+acceptanceRole: read-only
+---
+
+Analyze only the assigned council role. Inspect evidence directly. Do not edit,
+run mutating commands, commit, push, contact peers, or spawn subagents. Return
+concise, cited advice using the report contract in the council task.
+```
+
+After `subagent({ action: "list" })`, prefer 2–3 executable names that start with
+`council-`. The prefix is a naming convention, not runtime selection. If fewer
+than two profiles are available, fill the roster with `oracle`, then `reviewer`,
+until it has two advisors. Launch fallback `oracle` with `context: "fork"` so
+global defaults cannot remove its parent-chat context. Let fallback `reviewer`
+use its normal profile context. Note the fallback and known context modes in the
+memo. Use the normal single-oracle consultation loop only when a requested roster
+or unavailable builtins leaves fewer than two advisors.
+Label that result as degraded mode. Never use more than four advisors.
+
+Pass 1 is independent reports. Pass 2 is one cross-exam. The default pass cap is
+2. Run pass 3 only when `--max-passes 3` was requested and a material dispute can
+be settled by evidence an advisor can produce. Never run an unbounded loop.
+
+## Protocol
+
+1. The parent writes a brief with the question, scope, non-goals, evidence targets,
+   roster, roles, and pass cap.
+2. Before Pass 1, tell the user the roster, roles, requested or known context
+   modes, and pass cap. Use a stable key, `phase`, and concise `label` for every
+   workflow child. For example, use `advisor-oracle`, `phase: "Council pass 1"`,
+   and `label: "Oracle — intent and consistency"`.
+3. Launch one async `workflowScript` with `runs.all` for independent advisor
+   reports. Set `context` when the selected advisor has a known profile context or
+   a fallback rule requests one, because a global default can otherwise override
+   that profile. Set `context: "fork"` for fallback `oracle`. If no advisor context
+   is known, omit `context` and disclose the unknown runtime default in the memo.
+   Each advisor is read-only and must not spawn children, edit files, run mutating
+   commands, commit, or push. Set `output: false` unless separate advisor artifacts
+   are explicitly requested or useful for the decision.
+4. Return one aggregate Pass 1 receipt. After it completes, tell the user the
+   completion count, agreement count, dispute count, and whether Pass 2 is needed.
+5. The parent synthesizes a claim matrix in session. It contains agreements,
+   disputed claims, missing proof, owner decisions, and a relay set of at most five
+   high-impact claims per advisor. Do not delegate this synthesis.
+6. Before Pass 2, tell the user how many claims are relayed and why each is
+   material. Launch a second async `workflowScript` with `runs.all` resume calls.
+   Each task is a curated challenge packet, not a peer transcript. A resume requires
+   a retained run id and a non-empty task. It excludes `agent` and rejects `gate`.
+   Record the new run id from every resume. Pass 3 resumes those latest ids. Return
+   one aggregate Pass 2 receipt.
+7. After Pass 2, tell the user whether the council converged or which owner
+   decisions remain. The parent writes the final memo. Do not delegate it.
+
+If an advisor is not resumable, run the same profile in fresh context with its own
+pass-1 report and the challenge packet. Label that response as a fresh-context
+fallback, not a true cross-exam.
+
+Do not set `clarify`, `worktree`, `gate`, turn budgets, tool budgets, or tight usage
+budgets on advisors. Bound work through the roster, pass cap, and report length.
+
+## Advisor contracts and pass receipts
+
+Pass-1 reports are at most about 600 words. Give each advisor the same
+`outputSchema`, so reports are comparable without heading cleanup. The following
+shape is a contract template. Use the runtime schema syntax supported by the
+workflow and keep narrative fields as strings:
+
+```js
+const pass1OutputSchema = {
+  type: "object",
+  required: [
+    "recommendation", "evidence", "assumptions", "risks", "confidence",
+    "challengeClaims", "ownerDecisions", "changeMyMind"
+  ],
+  properties: {
+    recommendation: { type: "string" },
+    evidence: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["claim", "sources"],
+        properties: {
+          claim: { type: "string" },
+          sources: { type: "array", items: { type: "string" } }
+        }
+      }
+    },
+    assumptions: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["assumption", "status"],
+        properties: {
+          assumption: { type: "string" },
+          status: { enum: ["verified", "unverified"] }
+        }
+      }
+    },
+    risks: { type: "array", items: { type: "string" } },
+    confidence: {
+      type: "object",
+      required: ["level", "reason"],
+      properties: {
+        level: { enum: ["high", "medium", "low"] },
+        reason: { type: "string" }
+      }
+    },
+    challengeClaims: { type: "array", items: { type: "string" }, maxItems: 3 },
+    ownerDecisions: { type: "array", items: { type: "string" } },
+    changeMyMind: { type: "array", items: { type: "string" } }
+  }
+};
+```
+
+Include this contract in each Pass 1 task: inspect supplied evidence directly; do
+not see or ask about other advisors; stay read-only; do not spawn children; return
+only the structured report.
+
+After `runs.all`, return one aggregate receipt rather than making the parent find
+separate artifacts. Preserve the result order or map it by stable key so each row
+contains the advisor identity and report:
+
+```js
+return {
+  pass: 1,
+  advisors: results.map((result, index) => ({
+    key: result.key,
+    agent: result.agent,
+    role: roster[index].role,
+    requestedContext: roster[index].context ?? "runtime-default-unknown",
+    runId: result.runId,
+    report: result.structuredOutput
+  }))
+};
+```
+
+Do not replace `runtime-default-unknown` with a guessed context. It records that
+the launch intentionally omitted context.
+
+A challenge packet contains only disputed claims, strong conflicting evidence,
+missing proof, owner decisions, and high-impact risks. Attribute peer content as
+"another advisor". Do not include full peer reports. Use a common Pass 2 contract:
+
+```js
+const pass2OutputSchema = {
+  type: "object",
+  required: ["responses", "recommendationChanged", "outOfScopeFindings"],
+  properties: {
+    responses: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["claimId", "disposition", "reason", "sources"],
+        properties: {
+          claimId: { type: "string" },
+          disposition: {
+            enum: ["accept", "reject", "refine", "owner-decision"]
+          },
+          reason: { type: "string" },
+          sources: { type: "array", items: { type: "string" } }
+        }
+      }
+    },
+    recommendationChanged: {
+      type: "object",
+      required: ["changed", "reason"],
+      properties: { changed: { type: "boolean" }, reason: { type: "string" } }
+    },
+    outOfScopeFindings: { type: "array", items: { type: "string" } }
+  }
+};
+```
+
+Use stable resume keys such as `cross-oracle`, `phase: "Council pass 2"`, concise
+labels, and `output: false` unless separate artifacts are requested or useful. The
+aggregate Pass 2 receipt uses the same row shape as Pass 1, with the new `runId`
+and `structuredOutput`.
+
+## Stop and memo
+
+Converged means no disputed claim remains that both materially affects the
+recommendation and can plausibly be settled by evidence. Stop at convergence, the
+pass cap, failed fallback, or user interruption. Put unresolved disputes in owner
+decisions. Never add a round for polish or symmetry.
+
+The parent memo states the question and scope, recommendation, rationale, accepted
+and rejected feedback with reasons, owner decisions, evidence and run ids,
+confidence, what would change the decision, and the roster, roles, passes,
+fallbacks, and known advisor context modes. State that fallback `oracle` is
+context-aware and forked.
+
+Council mode is not agent-to-agent chat, a transcript dump, mutation authority,
+auto-escalation to writer lanes, or a council UI. Escalate to a writer only after
+the parent memo and only when the user explicitly requests it.

package/skills/pi-subagents/SKILL.md

@@ -22,6 +22,7 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 | --- | --- |
 | Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
 | Run one-child, scripted, async, scheduled, mission-backed, forked, watchdog, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
+| Coordinate several independent tasks, worktrees, repositories, or writer lanes | `references/multi-lane-orchestration.md` |
 | List/create/update/delete/eject/disable agents, inspect legacy chain records, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
 | Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
 
@@ -30,6 +31,7 @@ For broad or uncertain requests, read more than one reference. For complex work,
 ## Always-on constraints
 
 - Keep the parent as orchestrator and final decision-maker.
+- Before multiple mutation-capable lanes, record a lane board and each lane's isolation path.
 - For plan, design, or architecture advice that asks to consult, discuss with, or come to agreement with `oracle`, use a short same-session consultation loop: read the first result, resume once with a targeted challenge when material tradeoffs remain, then synthesize the parent decision. Keep explicit one-shot, trivial, and fully settled consultations one-shot.
 - Use one writer per cwd/worktree unless isolated worktrees are intentional.
 - For cross-codebase work, record the target repo, explicit `cwd`, authority boundary, and expected output before launch. Do not assume the parent session cwd is the child repo.

package/skills/pi-subagents/references/constraints-and-recipes.md

@@ -36,6 +36,7 @@ In an interactive chat, do not call `subagent_wait()` merely to wait after launc
 - `subagent_wait()` — return when the next initially active async run or registered provider item finishes, or a subagent needs attention.
 - `subagent_wait({ all: true })` — block until every async run and provider item active at call time finishes, or a subagent needs attention.
 - `subagent_wait({ id: "..." })` — block on one async or remembered detached foreground run (id or prefix). Provider items are not selected through this parameter.
+- `subagent_wait({ stopOnAttention: false })` — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.
 - `subagent_wait({ timeoutMs })` — cap the block; active work keeps running if it elapses.
 
 Providers are discovered through the `pi-subagents/background-work` registry and must return stable item IDs with exact owning session IDs. Child agents receive no provider automatically: keep `subagent_wait` in the child `tools` allowlist and load provider extensions through `extensions` or `subagentOnlyExtensions`.

package/skills/pi-subagents/references/execution-controls.md

@@ -82,6 +82,17 @@ For one host-run verification command, pass `gate: "npm test"` on a `runs.run`/`
 
 Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids and reports each row as `resumable` or `not resumable` with a reason. Resume only rows reported `resumable`. For a retained-child challenge, use `resume` instead of `steer` when the child is complete. If no retained child is resumable, launch a same-role fallback challenge and label it as fallback. A later workflow continues a resumable child with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside `workflowScript`, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached. Pass explicit follow-up task text. Assign each returned child result back to the loop variable because every resume can return a new retained `runId`; always resume the latest returned id. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
 
+Terminal async workflows also persist `workflow-receipt.json` beside `status.json`. It maps each stable child key to its agent, requested and resolved context when known, latest run id, resumability, output reference, and continuation lineage. A later workflow can resume the latest retained child without copying its run id:
+
+```js
+return runs.run("cross-oracle", {
+  resume: { workflowRunId: "<pass-1-workflow-id>", key: "advisor-oracle", latest: true },
+  task: "Review the focused challenge packet."
+});
+```
+
+Keyed resume reads that one exact receipt and revalidates the retained run at launch. It fails when the workflow or key is missing, the receipt is stale, `latest` is not `true`, or the recorded child is no longer resumable. Foreground workflow results expose the same receipt in `details.workflow.receipt`, but cross-workflow keyed lookup requires the durable receipt from an async workflow.
+
 ### Async/background
 
 Prefer async mode for every subagent launch. Set `async: true` no matter the task unless the parent must block until completion. This applies to scouts, researchers, workers, reviewers, validators, oracle checks, one-off delegates, final review gates, backlog gates, and scripted workflows. Keep the write path single-threaded even when the run is async.

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

@@ -0,0 +1,39 @@
+# Multi-Lane Orchestration
+
+Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other pi-subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
+
+## Lane board and authority
+
+Before multiple mutation-capable lanes start, record this board in the parent context:
+
+`Lane | repo/cwd | exact decision | claimed files or contract | isolation path | authority | next gate | handoff | why independent`
+
+Record the isolation path before the first mutation. Do not split one source seam or decision into duplicate lanes. Make overlapping work one lane with one source of truth.
+
+For every lane, record the delivery target, allowed actions, required validation, and review rigor. For cross-repository work, name the shared contract and which repository changes first. A blocked decision is a lane state: record the owner, options, recommended default, and evidence needed to continue.
+
+## Partitioned runs
+
+Use one writer per repo/cwd or worktree. Mutation lanes need distinct isolation paths and explicit `cwd` values. Set `worktree: true` when a run needs managed worktree isolation within one repository. Read-only runs can share a checkout only when they cannot change state or create generated files.
+
+For Pi extension repositories, keep lane worktrees outside auto-discovered extension directories such as `~/.pi/agent/extensions`. A stale extension worktree there can auto-load duplicate tools and shortcuts. Remove or move it only after its handoff is durable, the worktree is clean, and no run owns it.
+
+Partition fanout by repository, source seam, decision, or review angle. Each run needs a stable key, lane-specific task, and durable output path. Do not launch prompts that differ only by item name or broad file glob.
+
+Use one async `workflowScript` for a coordinated wave. Use `runs.all` for independent lanes and `runs.run` for dependent lane stages. Give cross-repository runs explicit `cwd` values and lane-qualified outputs. Use `outputMode: "file-only"` when a report must survive the run or feed a later stage.
+
+## Keep independent work moving
+
+While one lane waits, run safe independent preparation, validation, or fresh read-only review lanes. Do not block the parent just because a run is active. If no safe lane remains, record the blocker and the event that will reopen work.
+
+An ordinary coordinated workflow has one mission. Use its durable state, artifacts, run records, and receipts for recovery. Treat a receipt as evidence, not as authority or acceptance.
+
+After a writer produces a candidate, run the required fresh-context, read-only reviewer. The reviewer inspects the exact worktree and returns evidence-backed findings. The parent decides which findings are in scope and whether the lane is ready. Send accepted fixes to that lane's sole writer, then rerun only the affected gate.
+
+## Handoff, cleanup, and recovery
+
+Use stable lane-qualified paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths.
+
+Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
+
+Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.

package/src/agents/agent-management.ts

@@ -36,10 +36,11 @@ import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
 import type { AcceptanceInput, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
 import { getProjectConfigDir } from "../shared/utils.ts";
 import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
+import { listRuntimeAgentConfigs, mergeRuntimeAgents, type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
 
 type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete" | "eject" | "disable" | "enable" | "reset";
 type ManagementScope = "user" | "project";
-type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { model?: ExtensionContext["model"]; config?: ExtensionConfig; currentSessionId?: string };
+type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { model?: ExtensionContext["model"]; config?: ExtensionConfig; currentSessionId?: string; runtimeAgentOwner?: RuntimeAgentOwner };
 
 interface ManagementParams {
 	action?: string;
@@ -142,7 +143,7 @@ function diagnosticsForScope(diagnostics: AgentDiscoveryDiagnostic[] | undefined
 	return diagnostics?.filter((diagnostic) => diagnostic.source !== excludedSource);
 }
 
-const AGENT_SOURCE_PRECEDENCE: Record<AgentSource, number> = { builtin: 0, package: 1, user: 2, project: 3 };
+const AGENT_SOURCE_PRECEDENCE: Record<AgentSource, number> = { builtin: 0, package: 1, user: 2, project: 3, runtime: 4 };
 
 // Returns the highest-precedence definition for a resolved canonical name (project > user > package > builtin),
 // matching mergeAgentsForScope for "both", including disabled agents so disable/enable can locate hidden targets.
@@ -213,6 +214,7 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 	const base = agent.override?.base;
 	const {
 		override: _override,
+		outputMode: _outputMode,
 		model: _model,
 		fallbackModels: _fallbackModels,
 		thinking: _thinking,
@@ -240,6 +242,7 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 
 	return withDeclaredExtensionPaths({
 		...editable,
+		...(base.outputMode !== undefined ? { outputMode: base.outputMode } : {}),
 		...(base.model !== undefined ? { model: base.model } : {}),
 		...(base.fallbackModels !== undefined ? { fallbackModels: [...base.fallbackModels] } : {}),
 		...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
@@ -311,6 +314,7 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
 	if (hasKey(cfg, "acceptance")) changed("acceptance");
 	if (hasKey(cfg, "acceptanceRole")) changed("acceptanceRole");
 	if (hasKey(cfg, "output")) changed("output");
+	if (hasKey(cfg, "outputMode")) changed("outputMode");
 	if (hasKey(cfg, "reads")) changed("defaultReads");
 	if (hasKey(cfg, "progress")) changed("defaultProgress");
 	if (hasKey(cfg, "maxSubagentDepth")) changed("maxSubagentDepth");
@@ -501,6 +505,10 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.output === "string") target.output = cfg.output;
 		else return "config.output must be a string or false when provided.";
 	}
+	if (hasKey(cfg, "outputMode")) {
+		if (cfg.outputMode === "inline" || cfg.outputMode === "file-only") target.outputMode = cfg.outputMode;
+		else return "config.outputMode must be 'inline' or 'file-only' when provided.";
+	}
 	if (hasKey(cfg, "reads")) {
 		if (cfg.reads === false || cfg.reads === "") delete target.defaultReads;
 		else if (typeof cfg.reads === "string") {
@@ -610,6 +618,7 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.subagentOnlyExtensions !== undefined) lines.push(`Subagent-only extensions: ${agent.subagentOnlyExtensions.length ? agent.subagentOnlyExtensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
+	if (agent.outputMode) lines.push(`Output mode: ${agent.outputMode}`);
 	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
 	if (agent.defaultProgress) lines.push("Progress: true");
 	if (agent.maxSubagentDepth !== undefined) lines.push(`Max subagent depth: ${agent.maxSubagentDepth}`);
@@ -623,7 +632,17 @@ function formatAgentDetail(agent: AgentConfig): string {
 export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd);
-	const scopedAgents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package)
+	let scopedAgents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
+	if (ctx.runtimeAgentOwner && listRuntimeAgentConfigs(ctx.runtimeAgentOwner).length > 0) {
+		const configuredAgents: AgentConfig[] = [
+			...d.builtin,
+			...d.package,
+			...d.user,
+			...d.project,
+		];
+		scopedAgents = mergeRuntimeAgents(ctx.runtimeAgentOwner, { agents: scopedAgents }, configuredAgents).agents;
+	}
+	scopedAgents = scopedAgents
 		.sort((a, b) => a.name.localeCompare(b.name));
 	const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
 	const visibleAgents = scopedAgents.filter((a) => !a.disabled);

package/src/agents/agent-serializer.ts

@@ -28,6 +28,7 @@ export const KNOWN_FIELDS = new Set([
 	"extensions",
 	"subagentOnlyExtensions",
 	"output",
+	"outputMode",
 	"defaultReads",
 	"defaultProgress",
 	"interactive",
@@ -113,6 +114,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 	}
 
 	if (config.output) lines.push(`output: ${config.output}`);
+	if (config.outputMode || preserve("outputMode")) lines.push(`outputMode: ${config.outputMode ?? ""}`);
 
 	const readsValue = joinComma(config.defaultReads);
 	if (readsValue) lines.push(`defaultReads: ${readsValue}`);