pi-subagents 0.52.1 → 0.54.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## [Unreleased]
 
+## [0.54.0] - 2026-08-21
+
+### Highlights
+- Subagent model selection is more precise with per-agent restrictions and an `inherit` shortcut for the current parent model.
+- Package agents are easier to discover because list and detail output now shows where they come from and whether their external provider is ready.
+- Workflow runs are less fragile: tool-result backfill, context-overflow handling, resumed children, and permission asks now behave more predictably.
+- Child launches are lighter and safer because subagent processes avoid loading the parent extension graph and avoid unnecessary permission bridge setup.
+- Council Mode is easier to use from natural language and no longer requires invented advisor role labels.
+
+### Added
+- Add per-agent model restrictions and a current-parent `inherit` allow-list alias. Thanks to [@hieudmg](https://github.com/hieudmg) for #1328.
+
+### Changed
+- Show package names, versions, and external-job provider status in subagent list and detail output so package agents such as Surf's `gpt-pro` are easier to find and use.
+- Make scripted workflow helper support and stale-session recovery easier to see in `doctor` and the workflow guide (#1344).
+- Keep structured single-child execution receipts quieter by removing an internal conversion log from public workflow output.
+- Route natural-language requests for advisor councils, plan critique, cross-exam, or multiple model perspectives to the Council Mode protocol.
+- Simplify Council Mode advisor selection so model-based profiles provide the perspective and the question supplies the decision frame.
+
+### Fixed
+- Layer custom-agent user and project overrides without dropping user-only fields, while preserving project precedence. Thanks to [@jagaliano](https://github.com/jagaliano) for #1348.
+- Avoid child tool-call hangs by loading the external permission-system bridge only for explicit native permission rules and by failing stalled ask decisions closed. Thanks to [@moekyo](https://github.com/moekyo) for #1339.
+- Keep foreground workflow children from timing out after a tool result is backfilled without a separate execution-end event. Thanks to [@moekyo](https://github.com/moekyo) for #1339.
+- Mark completed foreground workflow children as resumable in keyed receipts when their persisted session file is available (#1335).
+- Avoid loading the parent extension graph in subagent child processes. Thanks to [@ccharname](https://github.com/ccharname) for #1330.
+- Stop model fallback on context-overflow failures and surface `contextOverflow`. Thanks to [@srcKod](https://github.com/srcKod) for #1323.
+- Stop empty slow result scans from spamming the session transcript. Thanks to [@afrodao2394](https://github.com/afrodao2394) for #1329.
+- Surface logical tool failures so subagent tool results backfill correctly. Thanks to [@abdwhb-png](https://github.com/abdwhb-png) for #1332 and [@moekyo](https://github.com/moekyo) for #1331.
+
+## [0.53.0] - 2026-08-20
+
+### Highlights
+- New `/council` mode helps with material decisions by running a small, bounded group of advisors and ending with a parent-written decision memo.
+- 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.
+- 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 `/council` and `council-mode` for bounded advisor councils. Use it for material decisions that need multiple perspectives: the parent picks 2–3 advisors, collects independent reports, optionally runs one cross-exam pass, and writes the final decision memo. The package also documents 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

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` with model-based advisors to compare this decision." |
 | 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

@@ -2,7 +2,7 @@
 
 `pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`. This page lists every key, plus the environment variables and the settings-file keys that affect config resolution.
 
-Settings-level keys (`subagents.defaultModel`, `defaultThinking`, `defaultExtensions`, `agentOverrides`, `modelScope`, `disableThinking`, `disableBuiltins`, watchdog settings) live in Pi settings files, not this config file. See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
+Settings-level keys (`subagents.defaultModel`, `defaultThinking`, `defaultExtensions`, `agentOverrides`, `modelScope`, `disableThinking`, `disableBuiltins`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, and `allow: ["inherit"]` permits the current parent model. See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
 
 ## Project root resolution (settings)
 
@@ -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 `"activity"`; 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 `"activity"` (default), it logs only scans that inspected or scheduled actual work. Use `"all"` to log every slow scan, including the periodic healthy rescan that inspects zero files while no async runs are pending, 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/models.md

@@ -10,6 +10,8 @@ Builtin agents inherit your current Pi default model. This keeps new installs fr
 
 Precedence, strongest first: per-run override → agent frontmatter `model` → `agentOverrides.<name>.model` → `subagents.defaultModel` → the parent session model.
 
+Use `model: "inherit"` in agent frontmatter or `agentOverrides.<name>.model` to select the current parent session model explicitly.
+
 ## Setting defaults and overrides
 
 In `~/.pi/agent/settings.json` (user) or the project config settings file (`.pi/settings.json` in standard Pi; project wins):
@@ -153,17 +155,29 @@ To keep subagents inside a budget or compliance profile, enforce a model scope.
     "modelScope": {
       "enforce": true,
       "strict": true,
-      "allow": ["anthropic/*", "openai/gpt-5-*"]
+      "allow": ["inherit", "openai/gpt-5-*"],
+      "agents": {
+        "worker": { "allow": ["openai/gpt-5-mini"] },
+        "reviewer": { "allow": ["inherit"] }
+      }
     }
   }
 }
 ```
 
-- `allow` is a list of glob patterns matched against the resolved `provider/id` (only `*` is special, case-insensitive). A resolved model that matches none of the patterns is rejected.
+- `allow` is a list of glob patterns matched against the resolved `provider/id` (only `*` is special, case-insensitive). The literal `inherit` means the current parent session model.
+- `agents.<name>` adds a second allow-list for that agent. The model must pass both the global list and the matching agent list, so an agent rule cannot weaken the global rule. Agent rules inherit `enforce` and `strict` when those fields are absent.
+- A top-level `enforce: true` with only agent allow-lists restricts only those named agents. Unknown names are allowed so settings can be shared across projects and machines.
 - Models you pass explicitly — the tool-call `model`, `--model`, or a clarify pick — error and abort the run.
 - By default, models from agent frontmatter, `subagents.defaultModel`, the inherited parent session model, or fallback chains only warn and remain available, so existing configurations keep working while you tighten the scope.
 - Set `strict: true` with `enforce: true` to reject every resolved out-of-scope model. This includes inherited models and fallback candidates. An invalid fallback fails the run instead of being removed from the candidate chain.
-- `enforce: true` requires a non-empty `allow` list; otherwise the config is rejected at load time.
+- `enforce: true` requires at least one non-empty global or agent `allow` list; otherwise the config is rejected at load time.
+
+Model scope is policy only. It rejects or warns; it does not select a cheaper model. Set `agentOverrides.worker.model` to choose a worker model and use `modelScope.agents.worker` to prevent a per-run override or fallback from escaping that restriction.
+
+`inherit` expands in the parent process at each launch. It is never sent to the child as a model id. A nested child therefore inherits its immediate parent's current model, not the original top-level model. If no parent model is available, an enforced `inherit` entry does not match and fails closed.
+
+Project `modelScope` settings replace the complete user `modelScope`, as with the existing project-over-user settings precedence. Project settings are trusted and can therefore replace user restrictions.
 
 ## Profiles and provider model catalogs
 

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/index.ts

@@ -1 +1,10 @@
-export { default } from "./src/extension/index.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {} from "./src/types/pi-runtime-compat.d.ts";
+
+const registerParentExtension = process.env.PI_SUBAGENT_CHILD === "1"
+	? undefined
+	: (await import("./src/extension/index.ts")).default;
+
+export default function registerSubagentExtension(pi: ExtensionAPI): void {
+	registerParentExtension?.(pi);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.52.1",
+  "version": "0.54.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,51 @@
+---
+description: Run a bounded supervisor-mediated council of advisors and write a decision memo
+argument-hint: "<question> [--advisors name,name] [--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, known advisor context modes, 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 agent names. Fail clearly on an
+  unknown agent. Do not require or invent per-advisor role labels.
+- 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.
+
+Profiles provide the model, tools, context, and advisor stance. The council
+question and scope provide the decision frame. If the user wants a specific lens,
+they should put it in the question, scope, or profile definition. 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,231 @@
+---
+name: council-mode
+description: Run a bounded supervisor-mediated advisor council. Use when the user asks for council mode, 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
+
+Use advisor profile names directly. A `council-*` profile defines model, tools,
+context, output defaults, and any persistent stance in the profile body. 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:
+
+```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 the council question independently. 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, known advisor context modes, and pass cap. If the user wants a specific
+   lens, keep it in the question, scope, or profile body instead of inventing a
+   per-advisor label.
+2. Before Pass 1, tell the user the roster, 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,
+    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, passes, fallbacks, and
+known advisor context modes. Identify advisors by profile name or model-based
+profile, not by invented role labels. 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

@@ -14,6 +14,8 @@ This skill is for the main parent orchestrator only. Do not inject or follow it
 
 Use this skill when the parent orchestrator needs one specialized child or composed orchestration. Use `workflowScript` for all execution, including one isolated child. Chaining is still supported, but it is code-driven: use `await runs.run(...)` for sequential steps, `runs.all([...])` for parallel fanout, and ordinary JavaScript for branching, retries, gate monitors, and aggregation. Keep workflow helpers portable: use plain helper functions or explicit Promise chains, not nested `async function` helpers, async arrows, or async methods. Do not use legacy top-level `chain` / `tasks` inputs or durable `.chain.md` execution. Scripted workflows normally start asynchronously unless config sets `asyncByDefault:false`; set `async:true` explicitly when async behavior matters. Pass `async:false` only when the parent must block until completion. Async mode still shows progress. Do not use `async:false` for final reviews, backlog gates, run-to-completion convenience, or because no other work is available.
 
+Package-installed agents appear in `subagent({ action: "list" })` with builtin, user, and project agents. If `surf-cli` is installed as a Pi package, the Surf browser extension is loaded, and Chrome is logged into a ChatGPT Pro account, Surf can expose `gpt-pro`: a read-only async advisor that reaches ChatGPT web through Surf Oracle. Check it with `subagent({ action: "get", agent: "gpt-pro" })` and run it with `subagent({ agent: "gpt-pro", task: "Review this plan and identify release risks." })`.
+
 ## How to use this router
 
 Read the matching reference file before acting. Paths are relative to this `SKILL.md`; resolve them against `skills/pi-subagents/` and load them with the read tool.
@@ -21,6 +23,7 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 | Task | Read |
 | --- | --- |
 | Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
+| Use council mode, convene several advisors, debate a decision, cross-examine recommendations, critique or improve a plan with multiple model perspectives, or run `/council` | `../council-mode/SKILL.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` |
@@ -32,7 +35,8 @@ For broad or uncertain requests, read more than one reference. For complex work,
 
 - 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.
+- For plan, design, or architecture advice that asks for council mode, asks to convene several advisors, compare model perspectives, debate a decision, cross-examine recommendations, or critique and improve a plan, read `../council-mode/SKILL.md` and use Council Mode instead of ad hoc parallel oracle calls.
+- For plan, design, or architecture advice that asks to consult, discuss with, or come to agreement with one `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.
 - For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one async `workflowScript` with stable keys and aggregate output unless there is truly only one child.

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

@@ -78,10 +78,23 @@ subagent({
 
 Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `emit`, captured `console`, and standard JavaScript. Pass explicit task text to `runs.run`. Mission-attached workflows also get `await state.get(key)` and `await state.set(key, value)` for durable JSON state shared across workflows on the same mission; `mission: false` workflows have no `state` global. Stable keys are required. Child launches follow ordinary single-agent execution controls. Give each child a distinct decision and output path when reports must outlive the workflow, then consume the aggregate workflow result before opening individual reports.
 
+If `runs.all` is missing in a running session, reload or update `pi-subagents` before retrying. The current runtime supports `runs.all`; `await Promise.all([runs.run(...)])` is also supported for advanced dynamic fanout.
+
 For one host-run verification command, pass `gate: "npm test"` on a `runs.run`/`runs.all` item (or at the top level as a workflow default). It is shorthand for verified acceptance with that single command: the runtime executes it on the host, records the result as evidence, and memoizes it per tracked workspace state and effective environment. `gate` cannot be combined with `acceptance`; use explicit `acceptance.verify` for multiple commands or custom criteria.
 
 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/prompting-and-roles.md

@@ -44,11 +44,18 @@ Packaged prompt shortcuts are also available for repeatable workflows. Treat the
 - `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
 - `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
 - `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
+- `/council` — bounded advisor council for material decisions, plan critique, cross-exam, and parent-written decision memos
 
 ## Applying Prompt Techniques Without Slash Commands
 
 The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. For targets outside the parent cwd, include the exact repository, explicit `cwd`, authority boundary, and expected output path in each child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
 
+### Council Mode technique
+
+Use Council Mode when the user asks to convene advisors, debate a material decision, cross-examine recommendations, or critique and improve a plan with several model perspectives. This includes requests such as “run a council on this architecture,” “have Sol, Fable, and Kimi critique this plan,” or “get multiple oracles to debate the tradeoffs.” Read `../council-mode/SKILL.md` and follow its bounded parent-supervised protocol instead of launching ad hoc parallel oracle calls.
+
+Council advisors are read-only. User or project `council-*` profiles can pin models such as GPT 5.6 Sol, Fable, or Kimi and define any persistent stance in the profile body. The council question and scope provide the decision frame; do not invent per-advisor role labels. The parent collects independent reports, optionally sends curated cross-exam packets, and writes the final memo. Do not treat the council as agent-to-agent chat, implementation authority, or a writer swarm.
+
 ### Parallel review technique
 
 Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.