@emiliosp/pi-maestro 0.7.3 → 0.8.0

package/ADR.md

@@ -0,0 +1,58 @@
+# Architecture decision records
+
+An Architecture Decision Record (ADR) explains an important architectural choice, its context, and its consequences. 
+This file contains one numbered record per decision. 
+
+Requirements and routine project rules belong in the [roadmap](ROADMAP.md) or other relevant documentation.
+
+When a new decision replaces an accepted decision, add a new record, mark the earlier record as superseded, and link both records.
+
+## ADR-001: Keep the workflow independent of Git
+
+### Status
+
+Accepted. Recorded date: 2026-10-07. Implemented in `0.6.0`.
+
+### Context
+
+The previous workflow required Git and used checkpoints and automatic commits. The recorded reason for removing that approach was to simplify the project. Other evaluated alternatives were not recorded.
+
+### Decision
+
+`Maestro` uses the Pi project directory and saved workflow phase. It does not require Git or create automatic commits.
+
+The `verifier` checks live project files. The `owner` controls later Git use, pull requests, and merging.
+
+### Consequences
+
+Workflow execution no longer depends on Git. Revision and commit fields were removed without migration or compatibility readers. Interrupted and older workflows require manual `owner` handling.
+
+### Evidence
+
+[Commit deae41c](https://github.com/emilioSp/pi-maestro/commit/deae41ce66a3f2c76859209c44165e7ddd0f3a72), [Changelog 0.6.0](CHANGELOG.md#060), and [workflow completion](docs/workflow.md#workflow-completion).
+
+## ADR-002: Store escalation decisions in builder handoffs
+
+### Status
+
+Accepted. Recorded date: 2026-10-08. Implemented in `0.7.0`.
+
+### Context
+
+The previous approach stored `escalations` in standalone files and used singular resolution tools. The recorded reason for replacing it was to use the same storage, local ID, and batch decision model as `verifier` `findings`. Other evaluated alternatives were not recorded.
+
+### Decision
+
+Numbered `builder` `handoffs` contain `escalation` questions and their `owner` resolutions. One call records all current answers. No parallel storage model is needed.
+
+IDs restart at `E1` in each `handoff`. References include both IDs, such as `B1/E1`. Answers update only the active handoff's resolution fields.
+
+### Consequences
+
+Standalone `escalation` storage and singular resolution tools were removed. Questions and decisions remain together in each numbered `builder` `handoff`.
+
+There are no migration procedures, fallback readers, or deprecated aliases. `Artifact` versions remain `1.0.0` despite the breaking change.
+
+### Evidence
+
+[Repository-only specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [Commit dda6eb5](https://github.com/emilioSp/pi-maestro/commit/dda6eb5b3ab76ba175112c3c565c70be747d7344), and [escalation workflow](docs/workflow.md#escalations).

package/README.md

@@ -104,3 +104,4 @@ The reading order is:
 2. [Tech stack](TECH_STACK.md): runtime technologies and development tools.
 3. [Roadmap](ROADMAP.md): completed outcomes and planned priorities.
 4. [Changelog](CHANGELOG.md): meaningful codebase changes and breaking changes.
+5. [Architecture decision records](ADR.md): architectural choices, context, consequences, and evidence.

package/ROADMAP.md

@@ -10,80 +10,173 @@ Item identifiers remain stable when priorities change. The `owner` approves chan
 
 ### R-01: Improve status presentation and activation feedback
 
-The status bar uses phase icons, theme colors, and shortened `spec` IDs. Successful activation shows the configured `builder` and `verifier` settings without adding the notice to session history or model context. All 12 `acceptance criteria` passed with no `verifier` `findings`; the saved workflow reached `candidate-ready`.
+The status bar uses phase icons, theme colors, and shortened `spec` IDs. Successful activation shows the configured `builder` and `verifier` settings without adding the notice to session history or model context. All 12 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
 
-Evidence: [Specification](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/spec.md), [verifier report](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/handoffs/verifier/V1.json), and [merged PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
+#### Evidence
+
+[Specification](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/spec.md), [verifier report](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/handoffs/verifier/V1.json), and [merged PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
 
 ### R-02: Store escalations and owner decisions in builder handoffs
 
-Numbered `builder` `handoffs` contain multiple `escalation` questions and their `owner` resolutions. The `owner` resolves all current questions in one batch, while earlier `handoffs` remain available as history. All 10 `acceptance criteria` passed with no `verifier` `findings`; the saved workflow reached `candidate-ready`.
+Numbered `builder` `handoffs` contain multiple `escalation` questions and their `owner` resolutions. The `owner` resolves all current questions in one batch. Earlier `handoffs` remain available as history. All 10 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+#### Evidence
 
-Evidence: [Specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [verifier report](.specs/20261008-132344-store-escalations-in-builder-handoffs/handoffs/verifier/V1.json), and [merged PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
+[Specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [verifier report](.specs/20261008-132344-store-escalations-in-builder-handoffs/handoffs/verifier/V1.json), and [merged PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
 
 ### R-12: Format glossary terms consistently
 
 Applied glossary formatting across the documentation and recorded its exclusions in `AGENTS.md` and the documentation audit skill. The approved change document uses the term `spec`. The `owner` confirmed completion.
 
-Evidence: [Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
+#### Evidence
 
-## Now
+[Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
 
-No current priority is selected.
+### R-15: Rename the test support directory
 
-## Next
+Renamed `test/` to `tests/` at the owner's request. Updated imports, fixture paths, lint configuration, and project instructions. This follows the global instruction to keep fixtures under `tests/fixtures`. Source tests remain next to their source files. Historical `handoffs` retain their recorded paths.
+
+#### Evidence
+
+[Test support](tests/support/), [fixtures](tests/fixtures/), [lint configuration](biome.json), and [project instructions](AGENTS.md#tests).
+
+## Now
 
 ### R-03: Route builder failures through owner escalations
 
-A technical `builder` failure currently ends the workflow in `builder-failed`. Replace the builder's `failed` `handoff` status and the `builder-failed` workflow phase with an `escalation`. The `owner` decides how to proceed through the existing `escalation` process.
+#### Objective
 
-Complete when `builder` failures produce `owner` `escalations` instead of a terminal failure state. Individual checks retain `failed` as a valid result. Agent instructions, tools, workflow transitions, tests, and documentation must describe the same behavior.
+A technical `builder` failure currently ends the workflow in `builder-failed`. Replace the builder's `failed` `handoff` status and the `builder-failed` workflow phase with an `escalation`. The `owner` decides how to proceed through the existing `escalation` process.
 
 Automatic recovery of interrupted `runs` is outside this item. No `specification` is approved yet.
 
+#### Completed when
+
+`Builder` failures produce `owner` `escalations` instead of a terminal failure state. Individual checks retain `failed` as a valid result. Agent instructions, tools, workflow transitions, tests, and documentation describe the same behavior.
+
+## Next
+
+
 ## Later
 
 These items need scope review before `specification` approval. Existing behavior must be checked before adding new code. Dependencies between these items are not yet agreed.
 
 ### R-04: Rename the npm package
 
+#### Objective
+
 Rename `@emiliosp/pi-maestro` to `pi-maestro-sdd`. The `owner` installs the package under the new name. This item changes the package identity, not the development workflow.
 
-Complete when package metadata and installation documentation use the new name and the package is available under it. Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
+Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
+
+#### Completed when
+
+Package metadata and installation documentation use the new name. The package is available under that name.
 
 ### R-05: Keep acceptance criterion numbering continuous
 
-When criteria are removed during `spec` preparation or revision, renumber the remaining criteria without gaps. Numbering starts at `AC1` and continues through the final criterion. Complete when the `spec` and its current references use consistent numbering.
+#### Objective
+
+When criteria are removed during `spec` preparation or revision, renumber the remaining criteria without gaps. Numbering starts at `AC1` and continues through the final criterion.
+
+#### Completed when
+
+The `spec` and its current references use consistent numbering.
 
 ### R-06: Check subagent extensions at activation
 
-Make extension availability problems visible before a `builder` or `verifier` `run` starts. Activation already checks agent launch requirements, so first identify any missing extension checks. Complete when unavailable required subagent extensions prevent activation and the error identifies the problem.
+#### Objective
+
+Make extension availability problems visible before a `builder` or `verifier` `run` starts. Activation already checks agent launch requirements, so first identify any missing extension checks.
+
+#### Completed when
+
+Unavailable required subagent extensions prevent activation. The error identifies the problem.
 
 ### R-07: Guide initial configuration
 
-Help the `owner` create `Maestro` configuration through an interview. `Maestro` asks questions and writes the agreed configuration. Complete when the `owner` can create a valid project configuration without writing the file manually.
+#### Objective
+
+Help the `owner` create `Maestro` configuration through an interview. `Maestro` asks questions and writes the agreed configuration.
+
+#### Completed when
+
+The `owner` can create a valid project configuration without writing the file manually.
 
 ### R-08: Change agent models before a builder run
 
-Let the `owner` change the `builder` and `verifier` models during `spec` preparation and the `ready-for-builder` phase. The selected models apply to subsequent `runs`. Complete when the `owner` can select available models in those phases and `Maestro` uses the selections.
+#### Objective
+
+Let the `owner` change the `builder` and `verifier` models during `spec` preparation and the `ready-for-builder` phase. The selected models apply to subsequent `runs`.
+
+#### Completed when
+
+The `owner` can select available models in those phases. `Maestro` uses the selections.
 
 ### R-09: Define workflow reconciliation
 
-Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The recovery scope is not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
+#### Objective
+
+Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The recovery scope is not yet defined.
+
+#### Completed when
+
+Not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
 
 ### R-10: Match handoff criteria to the approved spec
 
+#### Objective
+
 Prevent `builder` and `verifier` reports from omitting or adding `acceptance criteria`. Each report must contain exactly the criterion IDs in the approved `spec`, with no duplicates in either place. Existing duplicate checks in reports do not establish this match.
 
-Complete when both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase. The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
+The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
+
+#### Completed when
+
+Both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase.
 
 ### R-11: Reduce temporary verifier changes
 
+#### Objective
+
 Reduce the risk that verification changes the `candidate`. Existing instructions already require exact restoration, cleanup, and reporting of unresolved restoration problems. Refine the remaining guidance rather than duplicate those rules.
 
-Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it, retain its exact contents, and restore it immediately after each `probe`, including failed `probes`. Prefer check-only commands over commands that apply automatic fixes.
+Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it. Retain its exact contents and restore it immediately after each `probe`, including failed `probes`. Prefer check-only commands over commands that apply automatic fixes.
 
-Complete when `verifier` instructions cover these limits and require restoration and temporary-file cleanup before `handoff`. If restoration fails, the `verifier` must stop and report affected paths and remaining changes. `Maestro` currently has no file-hash restoration check; adding one requires a separate scope decision.
+`Maestro` currently has no file-hash restoration check. Adding one requires a separate scope decision.
+
+#### Completed when
+
+`Verifier` instructions cover these limits and require restoration and temporary-file cleanup before `handoff`. If restoration fails, the `verifier` must stop and report affected paths and remaining changes.
 
 ### R-13: Show when Maestro is working
 
-Show an activity indicator in Pi's status bar while progress does not require an `owner` decision. A spinner is one option, not an agreed implementation. Complete when the status clearly distinguishes work in progress from a request for `owner` action.
+#### Objective
+
+Show an activity indicator in Pi's status bar while progress does not require an `owner` decision. A spinner is one option, not an agreed implementation.
+
+#### Completed when
+
+The status clearly distinguishes work in progress from a request for `owner` action.
+
+### R-14: Introduce Maestro at activation
+
+#### Objective
+
+When activated, `Maestro` gives a brief introduction and invites the `owner` to ask how it works, if interested. `Maestro` must have access to its own documentation to answer those questions.
+
+#### Completed when
+
+Activation includes this short introduction. `Maestro` can consult its documentation.
+
+### R-16: Verify code quality against AGENTS.md instructions
+
+#### Objective
+
+Add code-quality review against applicable `AGENTS.md` instructions as another `verifier` responsibility. Keep all existing responsibilities unchanged, including independent verification of every `acceptance criterion` in the approved `spec`. Code-quality review supplements that verification. It does not replace or reduce it.
+
+Existing `verifier` instructions already require reading applicable `AGENTS.md` files and following technical rules. Extend that guidance to require explicit code-quality review and reporting of instruction violations. Do not introduce personal style preferences as requirements.
+
+#### Completed when
+
+The `verifier` performs both its existing verification duties and the additional code-quality review. Every `acceptance criterion` is still independently verified. Each code-quality `finding` about an instruction violation identifies the `AGENTS.md` file, quotes the violated instruction, and explains how the code violates it.

package/docs/glossary.md

@@ -14,6 +14,7 @@
 | `Expected result` | The observable result that a `probe` must produce. |
 | `Artifact` | A saved workflow file, such as a `spec`, or a `handoff` between agents. |
 | `Handoff` | A saved `builder` or `verifier` report with results, `probe` outcomes, and notes. |
+| `Observability` | The owner's ability to inspect workflow progress and reported results. |
 | `Run` or `pass` | One execution of the `builder` or `verifier` with a fresh conversation. |
 | `Candidate` | The project files created by agents after a workflow `run` |
 | `Finding` | A technical issue that the `verifier` records for an `owner` decision. |

package/docs/workflow.md

@@ -22,7 +22,20 @@ A `verifier` `handoff` can contain `findings`, which are technical issues.
 
 `Builder` and `verifier` `runs` are sequential foreground operations. Each starts with a fresh conversation and reads the `spec` and saved `artifacts`.
 
-Maestro's Pi status shows the current phase. `pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
+## Observability
+
+`Observability` is the owner's ability to inspect workflow progress and reported results. 
+
+Maestro's Pi status shows the current phase. 
+
+`pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
+
+Saved `handoffs` provide a structured account of each reported `run`.
+The `builder` reports its outcome, `probe` results, notes, and any `escalation` questions. 
+The `verifier` reports its independent checks, results, and `findings`. 
+Recorded `owner` decisions explain how questions and issues were resolved. Earlier numbered reports remain available for inspection.
+
+For example, the `owner` can read `B1.json` to see what the `builder` reports implementing and which `probes` it ran. `V1.json` shows what the `verifier` reports checking independently and which issues it found.
 
 ## Main flow
 

package/node_modules/pi-subagents/CHANGELOG.md

@@ -2,6 +2,146 @@
 
 ## [Unreleased]
 
+## [0.78.0] - 2026-10-12
+
+### Highlights
+
+- Background subagents work on Pi 1.2.0 again. With 0.77.0 they failed to start on that Pi version.
+- Pressing `Esc` now keeps the parent agent stopped: a background subagent that finishes a moment later no longer starts it up again. `/subagents-stop` can also stop every running background subagent at once.
+- Fewer tokens spent re-reading the conversation: forked subagents, staged resumes, and the resume after `/compact` now reuse the provider's prompt cache.
+- Reports are no longer lost. Resuming a run saves a new report next to the old one instead of overwriting it, and a timed-out child's partial output now reaches the parent.
+- Sessions that run workflows no longer run out of background run slots after a child is stopped or fails to launch.
+
+### Added
+
+- New `pinToolDeclarations` config key. A long-running session keeps the `subagent` tool definition it started with, so an edited `subagent-tool-description.md`, a `toolDescriptionMode` change, or a package upgrade did not reach it until you started a new session. Set `pinToolDeclarations: false` (the default is `true`) and a resumed session picks up the current definitions on its next restart, at the cost of one prompt-cache miss. Thanks to [@advaitpaliwal](https://github.com/advaitpaliwal) for [#2853](https://github.com/nicobailon/pi-subagents/pull/2853). ([#2852](https://github.com/nicobailon/pi-subagents/issues/2852))
+- New `activeRunsPrompt` config key, off by default. A parent agent heard about its background subagents only from completion notices or a `status` call, so a few turns later it could forget one was running, launch the same work again, or say nothing was running. With this on, the parent's system prompt lists each queued or running background run (id, agents, mode, and chain step) until the last one finishes. Thanks to [@advaitpaliwal](https://github.com/advaitpaliwal) for the request. ([#2831](https://github.com/nicobailon/pi-subagents/issues/2831))
+
+### Changed
+
+- After you press `Esc` to stop the parent, a background subagent that finishes or asks for input no longer starts a new parent turn, so the agent you just stopped stays stopped. Its result or request is added to the session, and the parent sees it with your next prompt. A completion notice added this way tells the parent not to resume the stopped task unless you ask. Background runs keep running, and the TUI shows how many are still active and points to `/subagents-stop`.
+- `/subagents-stop` now starts with a "stop all" row when two or more background runs from this session are active, so you can stop them all after one confirmation instead of one at a time. Scheduled runs are not paused.
+- A forked subagent's first request re-sent the parent's whole conversation without the prompt cache, because the child's tools and history differed from the parent's. A forked child now declares the same tools as its parent (a tool it may not use fails with "not found" if called) and inherits the history exactly as the parent sent it. A session with the `subagent` tool also declares `contact_supervisor`, which returns an error if the parent calls it. A fork launched through `subagent` can now reuse the parent's prompt cache; one launched by a slash command before `subagent` is enabled still starts uncached. A session that already has `subagent` when you update may miss the prompt cache once, on its next request.
+- The built-in `reviewer`, `oracle`, and `evidence-auditor` agents are no longer asked to end with an acceptance report when the call has no `acceptance`, since that report is meant for agents that edit files. Pass `acceptance` to still get one. Without it these runs have no child report, so `/subagents-refine` no longer sees their review findings. Thanks to [@8FAX](https://github.com/8FAX) for finding it. ([#2865](https://github.com/nicobailon/pi-subagents/issues/2865))
+- pi-subagents no longer writes `run-history.jsonl`. The file got one line per run, grew without limit, and nothing read it. You can delete an existing `run-history.jsonl` from your Pi agent directory (`~/.pi/agent/` or `PI_CODING_AGENT_DIR`). Thanks to [@nycruslan](https://github.com/nycruslan) for the report. ([#2864](https://github.com/nicobailon/pi-subagents/issues/2864))
+- The pi-subagents skill now says that `worktree: true` refuses to launch from a checkout with uncommitted or untracked changes, and what to do in a shared or dirty checkout. Agents used to learn this only from a failed launch. Thanks to [@jmclaughlin724](https://github.com/jmclaughlin724) for the report. ([#2851](https://github.com/nicobailon/pi-subagents/issues/2851))
+
+### Fixed
+
+- Background subagents failed to start on Pi 1.2.0 with "does not provide @earendil-works/chord, @earendil-works/chord/context". Pi 1.2.0 no longer ships that package, but pi-subagents required it on every Pi from 0.85 on. It is now required only when the installed Pi declares it. Thanks to [@tlitovsk](https://github.com/tlitovsk) and [@amchen2310](https://github.com/amchen2310) for the reports, and to [@ArdalanM](https://github.com/ArdalanM) for the fix. ([#2854](https://github.com/nicobailon/pi-subagents/issues/2854), [#2855](https://github.com/nicobailon/pi-subagents/pull/2855))
+- A finished workflow kept its `maxActiveAsyncRunsPerSession` slot for the rest of the session, so later launches were rejected, when one of its background children had been stopped or had finished after the Pi process that launched it exited. Such a workflow is now released after `capacity.abandonedSlotReleaseAfterMs`, the same as one whose child failed. Top-level runs still release this way only when they failed. Thanks to [@nycruslan](https://github.com/nycruslan) and [@builtroller](https://github.com/builtroller) for the reports. ([#2863](https://github.com/nicobailon/pi-subagents/issues/2863))
+- An async workflow kept its `maxActiveAsyncRunsPerSession` slot for as long as its session lived when one of its children failed to launch, for example because of an unknown model. The slot is now released once the workflow ends. Thanks to [@nycruslan](https://github.com/nycruslan) for the report and the fix. ([#2856](https://github.com/nicobailon/pi-subagents/issues/2856))
+- A child stopped by a hard `toolBudget` block was not reported as blocked. A delegated foreground run said `completed` instead of `tool_budget_exhausted`, a workflow child got no `budget_exhausted` outcome, a background run's live status never showed the block, and the notice about a child repeatedly failing to change files never appeared. Tool results are now read the way Pi reports them. Thanks to [@adameq](https://github.com/adameq) for the report and the diagnosis. ([#2846](https://github.com/nicobailon/pi-subagents/issues/2846))
+- A `toolBudget` state reported `outcome: "hard-blocked"` as soon as the tool count passed `hard`, even when `block` listed only some tools and none had been blocked. It now reports `hard-reached` until a call is actually blocked, then `hard-blocked` with `blockedTool`. Thanks to [@adameq](https://github.com/adameq) for spotting it. ([#2866](https://github.com/nicobailon/pi-subagents/issues/2866))
+- A child resumed for a later stage with a new output path re-sent its whole conversation without the prompt cache, because the output path was part of its system prompt. Through `pi-claude-bridge`, one staged run re-cached about 1.65M tokens this way. The output path now goes only in the task message, so the system prompt stays the same across stages.
+- After a manual `/compact` with background subagents still running, the parent's next turn went out without the prompt sections that extensions add at the start of a turn, so the provider re-read the whole conversation without its prompt cache. Pi reports the compaction before it is ready for a new turn ([earendil-works/pi#5581](https://github.com/earendil-works/pi/issues/5581)). The resume now waits until the parent is idle, and it is dropped if another turn starts first, the session ends, or the parent is still busy after 10 seconds. Thanks to [@rnavarro](https://github.com/rnavarro) for [#2812](https://github.com/nicobailon/pi-subagents/pull/2812).
+- `subagent({ action: "resume", id, message })` without `output` reused the original run's output path, so the revived run overwrote the earlier report. A resume without its own `output`, including a `steer` that revives a finished child, now saves to a new file next to the original, named with the new run id (for example `report.1a2b3c4d.md`), and its completion notice names that file. An explicit `output` still wins, and resumes inside a workflow script still use the workflow's own output paths. ([#2837](https://github.com/nicobailon/pi-subagents/issues/2837))
+- A workflow stage that resumed a run started outside the workflow, without its own `output`, wrote its report over that run's saved report. It now writes to its own default output path, so the earlier report is kept. ([#2839](https://github.com/nicobailon/pi-subagents/issues/2839))
+- A background run with a required `file-only` output and valid structured output failed with "Required file-only output was not produced" when its final message held only an acceptance report, and the JSON was never written. It is now written. If a required `file-only` output cannot be written, for example because of a permission error, the run now fails instead of finishing with the report inline. Thanks to [@8FAX](https://github.com/8FAX) for the fix. ([#2850](https://github.com/nicobailon/pi-subagents/pull/2850))
+- When a background child timed out mid-reply, the completion notice and `status` showed only `Subagent timed out after …ms.`, so the parent never saw the text the child had already written. The notice now shows the first 2,000 characters of that partial output and the path of the file with the full text, followed by the child's recovery summary. Thanks to [@advaitpaliwal](https://github.com/advaitpaliwal) for [#2830](https://github.com/nicobailon/pi-subagents/pull/2830). ([#2829](https://github.com/nicobailon/pi-subagents/issues/2829))
+- Since 0.77.0, apps that run Pi in RPC mode and can draw custom screens, such as pi-web, got the plain-text version of `/subagents-fleet`, `/subagents-stop`, and the `/subagents` model and thinking pickers. Such an app can now set `PI_SUBAGENTS_COMPONENT_UI=1` to get the full screens; plain RPC keeps the text version. Thanks to [@kushaldotdev](https://github.com/kushaldotdev) for the report and the fix. ([#2848](https://github.com/nicobailon/pi-subagents/issues/2848))
+- Every workflow script that launched children in a loop or from its `args` printed a `workflowScript contains dynamic child launches` warning across Pi's input area on each run, although that is the normal way to write a fan-out. Launches no longer print it; `subagent({ action: "validate" })` still lists it under `warnings`. Thanks to [@builtroller](https://github.com/builtroller) for the report and the first fix, and to [@VincentHanxiaoDu](https://github.com/VincentHanxiaoDu) for removing it from launches. ([#2835](https://github.com/nicobailon/pi-subagents/issues/2835), [#2847](https://github.com/nicobailon/pi-subagents/pull/2847))
+- FleetView printed external-run problems, such as `Failed to inspect external jobs: …`, straight over Pi's screen and repeated them on every refresh. In an interactive session each distinct message is now shown once as a TUI warning, and headless runs print it once. A malformed record is now named by its run id. ([#2844](https://github.com/nicobailon/pi-subagents/issues/2844))
+- Opening Pi in a directory whose path contains a non-breaking space logged `Failed to inspect external jobs: External-run snapshot sessionId must contain only display-safe text.` on every refresh. Run and session ids may now contain any text except terminal control, bidirectional, and line-break characters. Thanks to [@louisje](https://github.com/louisje) for the report and the diagnosis. ([#2841](https://github.com/nicobailon/pi-subagents/issues/2841))
+- Workflow scripts that called `Promise.all`, `Promise.allSettled`, `Promise.race`, `Promise.any`, or `Promise.resolve` failed with a "Proxy handler's 'get' result …" error on Pi builds that freeze `Promise`, such as pi-bolt. They now work there. Thanks to [@albertgwo](https://github.com/albertgwo) for [#2828](https://github.com/nicobailon/pi-subagents/pull/2828).
+- Stopping a background subagent with `subagent({ action: "stop" })` produced a notice saying `Subagent stopped by user.` even when the parent agent stopped it, so it read as if you had stepped in. Stop notices for background runs, external CLI runs, and workflow children now say `Subagent stopped.`, `Placed external run stopped.`, or `Workflow child '<key>' stopped.` ([#2826](https://github.com/nicobailon/pi-subagents/issues/2826))
+- When an extension in a background child switched its model, for example a model router acting on the first message, status and FleetView kept naming the launch model. In one session, 14 of 15 children ran on a different model than status showed. Status now names the model the child's replies came from. Reviving the child still starts it on the launch model. Thanks to [@dodo-robot](https://github.com/dodo-robot) for the report and the fix. ([#2824](https://github.com/nicobailon/pi-subagents/issues/2824))
+- A child launched on a virtual model registered with `pi.registerVirtualModel()` failed with "model not found" when the extension that registers it was not loaded in the child, and the explanation suggested the model should have resolved. The explanation now says foreground children inherit providers but not virtual models, and names the fix, `registerRequiredChildExtensions`, next to the agent frontmatter options. Thanks to [@toomanyopenfiles](https://github.com/toomanyopenfiles) for the report. ([#2820](https://github.com/nicobailon/pi-subagents/issues/2820))
+- When a background run kept failing to read its control inbox, such as the `EPERM` errors seen on Windows, it wrote the same stack trace to `runner.stderr.log` on every retry and could fill gigabytes in minutes. A repeating error is now logged once, then once a minute with a repeat count. Retries continue, so queued requests still arrive once the inbox can be read. Thanks to [@infectiousstupidity](https://github.com/infectiousstupidity) for the report. ([#2811](https://github.com/nicobailon/pi-subagents/issues/2811))
+- A child whose structured output used a value outside a schema's `enum` or `const` got only "must be equal to one of the allowed values" or "must be equal to constant". The error now names the allowed values, up to 20 for a long `enum`. Thanks to [@rtbe](https://github.com/rtbe) for the report. ([#2813](https://github.com/nicobailon/pi-subagents/issues/2813))
+
+## [0.77.0] - 2026-10-09
+
+### Highlights
+
+- Subagents cost the parent far fewer tokens. The `subagent` tool's schema and description dropped from about 18,700 to 3,300 characters per request, `bg_wait` from about 4,500 to 1,100, and the bundled role prompts are about 20% shorter. Long child reports and guide pages now arrive as a short preview plus a file path instead of the full text.
+- Upgrading pi-subagents no longer costs resumed sessions their prompt cache, and upgrading under a running Pi no longer breaks every child launch.
+- Fewer wasted parent turns: launch an agent by name and a wrong agent or model name comes back with suggestions, the new built-in `parallel` workflow runs a batch of children without a script, and a parent woken by a result handles it instead of going quiet.
+- Background children can run inside a sandbox with `launcher:`, terminals such as Ghostty show each run's state, and tmux users get a bundled inspector pane.
+- A session that declined project trust no longer takes models, agents, or settings from that project.
+
+### Added
+
+- Running independent subagents in parallel needed a JavaScript workflow script that the model had to write in its reply, and some parents had to save it to a file first. The built-in `parallel` workflow takes the children as data: `subagent({ workflow: "parallel", args: { tasks: [{ agent, task }, ...] } })` runs them in one batch and returns each child's output in order. The tool schema is unchanged. ([#2773](https://github.com/nicobailon/pi-subagents/issues/2773))
+- Background children could run in a sandbox only through an external CLI runner, which loses native steering and results. An agent can now set `launcher:` to a command from the user config's `runnerLaunchers`, such as a sandbox, and that command wraps its background runner. Steering, supervisor questions, stop, resume and results keep working. Thanks to [@aaronkyriesenbach](https://github.com/aaronkyriesenbach) for the idea, design and nono testing. ([#2577](https://github.com/nicobailon/pi-subagents/issues/2577))
+- A terminal could not tell which background subagent runs were working, waiting on you, finished, or failed without reading the screen. Each run's state is now reported with OSC 7501, the Program Status Protocol, which terminals such as Ghostty can show next to Pi's own status. Set `programStatus: false` or `PI_PROGRAM_STATUS=0` to turn it off. ([#2724](https://github.com/nicobailon/pi-subagents/issues/2724))
+- Fleet's `Enter`/`H` inspector needed Herdr or Ghostty, so tmux users had to write their own provider. A bundled `tmux` inspector now opens the read-only inspector in a split pane of the current tmux window, with status and close support. Thanks to [@tobymao](https://github.com/tobymao) for the plugin. ([#2719](https://github.com/nicobailon/pi-subagents/pull/2719))
+- The async widget under the editor gives each active background run two or more lines while the terminal has room, and `asyncWidgetCollapsed: true` folds it to a count that names no run. Set `asyncWidgetLayout: "rows"` to show a header and one line per run; clicking the header still folds the widget, and Pi's expand key still shows the details. Thanks to [@pwguler](https://github.com/pwguler) for [#2738](https://github.com/nicobailon/pi-subagents/pull/2738).
+- Session browsers and usage tools could link a subagent run to the session that launched it only by parsing the directory layout. A new child session's header now records the launching session's file as `parentSession`, the same field Pi writes for forks, and the run's `_meta.json` records `parentSessionId`. Thanks to [@yingzhi0808](https://github.com/yingzhi0808) for the request. ([#2763](https://github.com/nicobailon/pi-subagents/issues/2763))
+- A host that shows subagent activity could not tell which run a `subagent-notify` completion notice belonged to without parsing its text. Each entry in the notice's `details.runs` now carries the run id (`runId`, plus `workflowRunId` and per-child `childRuns` for workflows), status, duration and saved paths. The text the model sees is unchanged. Thanks to [@kushaldotdev](https://github.com/kushaldotdev) for the request. ([#2788](https://github.com/nicobailon/pi-subagents/issues/2788))
+
+### Changed
+
+- The `subagent` tool sent about 13,000 characters of parameter schema on every model request, mostly for management fields a typical delegation never uses. The schema now lists `agent`, `task`, `workflow`, `args`, `async`, `model`, `cwd`, `worktree`, `output`, `action`, `id` and `message` at the top level and every other field inside one `options` object, which cuts it to about 2,100 characters. Management fields and the `runId`, `maxRuntimeMs` and `isolation` aliases still work at the top level, so existing calls and resumed sessions are unaffected. An unknown `options` key gets the closest valid name, and a field given in both places with different values is rejected. Docs, guides, skills and the run hints in tool results now show `options`. ([#2767](https://github.com/nicobailon/pi-subagents/issues/2767))
+- The default `subagent` tool description took about 5,700 characters on every model request, and the rule about when delegation is allowed appeared three times. The description is now about 1,200 characters and states each rule once: how to call the tool, that async runs wake the parent on their own, one writer per worktree, and not to silently switch to another runner after a failure. It points to the guide for workflow scripts, resume and external CLIs. The tool no longer registers a prompt guideline, and its prompt snippet no longer repeats the delegation rule. `toolDescriptionMode: "full"` keeps the old detail inline. ([#2768](https://github.com/nicobailon/pi-subagents/issues/2768))
+- The `bg_wait` tool's description and parameters took about 4,500 characters on every model request, and each of its five parameters repeated that ordinary async runs already wake the session. They now take about 1,100 characters: the description says it once and lists the call shapes, and each parameter has a short label. ([#2769](https://github.com/nicobailon/pi-subagents/issues/2769))
+- The `subagent` tool description told the parent to call `{action:"list"}` before delegating and `{action:"models"}` before choosing a model, which cost an extra parent turn each time plus 1,300–2,000 tokens that stayed in history. It now says to launch by name with an exact `provider/id`. An unknown or disabled agent fails with a "did you mean" and the available agents with one-line descriptions (at most 30). An unknown or ambiguous model fails with up to 5 of the closest model ids. `list` and `models` still work on demand. ([#2771](https://github.com/nicobailon/pi-subagents/issues/2771))
+- The catalog of agents marked `advertise: true` also told the parent to call `{action:"list"}` before every delegation. Now that a launch with an unknown agent returns the available agents, new sessions no longer get that instruction. A resumed session keeps the catalog text it already has, so the upgrade does not change its prompt or cost it the provider's prompt cache. ([#2791](https://github.com/nicobailon/pi-subagents/issues/2791))
+- Changing a pi-subagents tool description, schema, prompt snippet, or guideline made every resumed or reloaded session re-declare that tool before its next request, so the provider re-read the whole conversation without its prompt cache. The `subagent`, `bg_wait` and `subagents_enable` tools, and a child session's `bg_wait` and fanout `subagent`, now keep the definition and prompt text the session already declared. Only sessions that never declared a tool get its current definition. ([#2778](https://github.com/nicobailon/pi-subagents/issues/2778))
+- Every turn of a child launched with a bundled role resent its full role prompt, and those prompts repeated their own rules and the supervisor instructions that are already appended. The `oracle`, `reviewer`, `worker`, `researcher` and `scout` prompts drop the repeats and keep every rule, going from 21,283 to 17,139 characters in total (oracle 6,059 → 4,789, reviewer 5,211 → 4,443, worker 4,296 → 3,083). ([#2775](https://github.com/nicobailon/pi-subagents/issues/2775))
+- Async completion notices, completed-run `status` and foreground results put a child's whole output into the parent's context (about 38,000 characters for one long report), and every async launch receipt repeated about 870 characters of waiting guidance. They now show the first 2,000 characters of a longer output followed by the path, size and line count of the file that holds all of it; output with no such file stays whole. Workflow child previews are capped at 2,000 characters, structured-output previews in `status` at 500 when a path line follows, failure notices now include an `Error:` line even when the child produced output, and the receipt guidance is two short lines. ([#2774](https://github.com/nicobailon/pi-subagents/issues/2774))
+- `subagent({action:"guide",topic})` returned a whole document, up to 62 KB for `tool-reference`, and that text stayed in the parent's history for every later turn. A docs-backed topic now returns its intro and a list of sections, and `topic: "<topic>/<section>"` returns one section of at most 8,000 characters. `overview` and `council` are unchanged. ([#2772](https://github.com/nicobailon/pi-subagents/issues/2772))
+- Each message pi-subagents put in the main chat had its own look: bordered cards for supervisor requests, replies and attention notices, `✓`/`✗` lines for completions, plain colored lines for steering, and Pi's default block with raw labels such as `[subagent-wait-subscription]` for reminders and wakes. They now all use Pi's own message block, the one behind `[skill]`: a single `[subagent]` line whose label color names the kind (supervisor question or attention, reply, result, or watchdog) and whose status word uses the theme's status color. A click opens one block and Pi's expand key opens them all, showing the text the main agent read. Thanks to [@pwguler](https://github.com/pwguler) for [#2753](https://github.com/nicobailon/pi-subagents/pull/2753).
+- Subagent model displays (Fleet, the async widget, run status, nested renders and result cards) showed only the model id, so two providers or logins serving the same model looked identical. They now show `provider/model`. Thanks to [@IdrisGit](https://github.com/IdrisGit) for [#2734](https://github.com/nicobailon/pi-subagents/pull/2734).
+
+### Fixed
+
+- A session that declined Pi project trust still took subagent models, `modelScope` and agent definitions from the project, although Pi loads nothing from an untrusted project's `.pi` directory. Such a session now ignores project subagent settings, project agents and chains, and agents from packages installed for the project or declared in its `package.json`. The default scope behaves as `user`, and an explicit `agentScope: "project"` is rejected. Public preflight takes `projectTrusted` to match. Thanks to [@Saturnoon](https://github.com/Saturnoon) for the report. ([#2764](https://github.com/nicobailon/pi-subagents/issues/2764))
+- In a session that declined project trust, a malformed project `.pi/settings.json` still made subagent discovery and launch checks fail with "Failed to parse settings file", and a project's `agentExcludeDirs` could still hide user agents. An untrusted lookup now reads nothing from the project's settings; trusted lookups still report a broken file. ([#2804](https://github.com/nicobailon/pi-subagents/issues/2804))
+- After pi-subagents was upgraded under a running Pi session, every child launch could fail at once with "Extension path does not exist" or MODULE_NOT_FOUND, because the paths of the child runtime extensions and the async runner kept the file extension (`.ts` or `.js`) of the copy loaded at startup. They are now found on disk at each launch, preferring `.js`. Thanks to [@barjatiyasaurabh](https://github.com/barjatiyasaurabh) for the fix ([#2761](https://github.com/nicobailon/pi-subagents/pull/2761)) and [@gitwyy](https://github.com/gitwyy) for the report. ([#2780](https://github.com/nicobailon/pi-subagents/issues/2780))
+- A parent could wake for a supervisor decision or a finished workflow, reply with nothing, and leave the delegated work unhandled until you sent another message. The wake message now asks the parent to handle the result within the authority it already has. If it still replies with nothing, it gets one more turn and then a short notice that the work is unhandled, never an automatic approval. A visible reply, including a question to you, does not force another turn. Thanks to [@CamAnNguyen](https://github.com/CamAnNguyen) for [#2716](https://github.com/nicobailon/pi-subagents/pull/2716).
+- When a subagent notice and an intercom message reached an idle parent at the same moment, both extensions started a turn, and the second failed with `Extension "<runtime>" error: Agent is already processing a prompt`. pi-subagents and pi-intercom now share one wake per session, so the second message joins the turn the first one starts. This needs the matching pi-intercom release.
+- A message you typed while a blocking `bg_wait` was open sat in Pi's queue until the wait ended, which could take the whole wait window (30 minutes by default). A steer or follow-up from you now ends the wait with a non-error `user_input` result that lists the work still running; the work keeps going. Messages sent by extensions do not end the wait. Thanks to [@nuzayets](https://github.com/nuzayets) for [#2736](https://github.com/nicobailon/pi-subagents/pull/2736).
+- A scheduled run whose async runner died before writing a final status kept its schedule's claim, so every later fire was recorded as `skipped_overlap` and the schedule did nothing until someone deleted its `active.lock`. A fire that overlaps an active run, and a session that restores the schedule, now check whether that run is still alive: when its process is gone, or its status has not changed for 24 hours, the run is recorded as `failed_run` with the reason and the due fire launches. A run whose runner is alive is still skipped. Thanks to [@kmatzen](https://github.com/kmatzen) for the report and the first fix. ([#2806](https://github.com/nicobailon/pi-subagents/issues/2806))
+- Starting Pi in the home directory failed with "Project schedule root ... resolves outside the real project" when `~/.pi` was a symlink to a directory outside home, such as a mounted drive. When the project is the home directory, the real user config directory is now accepted as a schedule root; a project `.pi` that links outside its project is still rejected. Thanks to [@mecha](https://github.com/mecha) for the report. ([#2737](https://github.com/nicobailon/pi-subagents/issues/2737))
+- A host still handling a background run's paused result could delete or overwrite the final result written after it under the same run id, or remove that run's session, run and mission indexes. When the final result could not replace the paused file (EPERM/EACCES), it was delivered over and over without completing. Results are now written and consumed under a per-run lock, and a consumer leaves alone any result written after it read the run, along with its indexes. ([#2744](https://github.com/nicobailon/pi-subagents/issues/2744))
+- When a workflow awaited an async child, it could read the child's result before the child had written its index entries, so those entries were written after the workflow cleaned up and stayed behind in the child's run directory. A child now writes all index entries before its result becomes readable. ([#2741](https://github.com/nicobailon/pi-subagents/issues/2741))
+- A foreground child that detached to ask its supervisor kept running after a reload or session switch. Status and resume then said "Async run not found", and its workflow showed as stopped. Reloading pi-subagents now stops each detached foreground child and records it as stopped, so status shows the stop and its cause, resume works from its session, and its pending supervisor question is closed. Thanks to [@Saturnoon](https://github.com/Saturnoon) for the report. ([#2762](https://github.com/nicobailon/pi-subagents/issues/2762))
+- Interrupting a run id that could not be resolved interrupted the newest unrelated running job instead, and a nested async child whose owner had no foreground route to it could not be interrupted at all. An explicit interrupt id now fails when it does not resolve (a bare interrupt still picks the newest run), and an interrupt the owner cannot route now goes to the nested child directly. Thanks to [@leopepe](https://github.com/leopepe) for the fix ([#2760](https://github.com/nicobailon/pi-subagents/pull/2760)).
+- RPC stop refused queued and paused async runs, which the `subagent` tool's own stop action already handles. RPC stop now follows the tool's stop rules, with the same session and process checks. Thanks to [@alexei-led](https://github.com/alexei-led) for the fix (split from [#2717](https://github.com/nicobailon/pi-subagents/pull/2717)).
+- An RPC client that lost the spawn reply for a direct async run could not find the run by its tool-call ID once the result was delivered. Direct runs now keep the tool-call ID for status lookup after delivery, and an ID shared by a live run and a finished run is reported as ambiguous. Thanks to [@alexei-led](https://github.com/alexei-led) for [#2717](https://github.com/nicobailon/pi-subagents/pull/2717).
+- Over Pi's RPC mode, the `/subagents` admin screen's "Change model" and "Change thinking level", `/subagents-fleet` and `/subagents-stop` closed with no screen and no message, because RPC mode has no custom UI. These screens now use their component only in the TUI; elsewhere they use a select prompt or text instead. Thanks to [@gelubodrug](https://github.com/gelubodrug) for the report. ([#2766](https://github.com/nicobailon/pi-subagents/issues/2766))
+- A mission created through one path to a project was "not found" by `mission.show`, `mission.list` or a `missionId` launch through another path to the same directory, such as `/tmp/x` and its real path `/private/tmp/x` on macOS. The default mission store is now keyed by the project's real path, so symlinks, junctions and, on case-insensitive filesystems, letter case no longer split it; a configured `directory` or `globalIndexDir` still expands against the path as given. Missions created before this change through a path other than the real one stay on disk but are no longer found through that path. Thanks to [@hughy](https://github.com/hughy) for the report and the fix ([#2785](https://github.com/nicobailon/pi-subagents/pull/2785)). ([#2783](https://github.com/nicobailon/pi-subagents/issues/2783))
+- When TypeBox was installed only in Pi's own dependencies, every `structured_output` call failed with "Cannot load typebox/compile for structured output validation" unless `PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT` was set. Validation now also looks for TypeBox in the running Pi's package. Thanks to [@Saturnoon](https://github.com/Saturnoon) for the report. ([#2765](https://github.com/nicobailon/pi-subagents/issues/2765))
+- Pruned fork context failed with `400 MissingSessionID` when `forkContext.model` was an OpenCode or OpenCode Go model, because the summary request carried no session id. It now sends the parent session id and the `x-opencode-session` header, as the watchdog and prompt-audit requests do. ([#2759](https://github.com/nicobailon/pi-subagents/issues/2759))
+- The `subagent` tool schema marked the `reviewed` value of `acceptance` with `deprecated: true`, which strict tool-schema validators reject with HTTP 400, so the tool failed on those providers. The schema no longer includes `deprecated`. Thanks to [@kingofdies](https://github.com/kingofdies) for the report. ([#2713](https://github.com/nicobailon/pi-subagents/issues/2713))
+- Background children failed within a second with "Request timed out" on networks where connecting to the provider takes longer than 250 ms. The background runner used Node's 250 ms per-address connection limit, while Pi uses 2 s; the runner now uses 2 s too. Thanks to [@robinchm](https://github.com/robinchm) for the report and the fix. ([#2758](https://github.com/nicobailon/pi-subagents/issues/2758))
+- A foreground child whose model comes from a provider that a parent extension registered gets the provider but not that extension's session hooks, so a provider that needs those hooks failed the first request with an error only the provider understood. That failure now also says the child ran in the foreground without the extension and names the fixes: `async: true`, or loading the extension for that agent. Thanks to [@tharanee-bit](https://github.com/tharanee-bit) for the report. ([#2730](https://github.com/nicobailon/pi-subagents/issues/2730))
+- Prompt sections that other extensions add in `before_agent_start` reached a child's transcript but not its provider requests, because the child prompt was finished before those extensions ran. The child's prompt now keeps their sections and adds its own boundary after every other extension. Thanks to [@adameq](https://github.com/adameq) for the report. ([#2745](https://github.com/nicobailon/pi-subagents/issues/2745))
+- Every workflow script failed before its first line with "Cannot redefine property: then" (or "Attempting to change value of a readonly property") when the host Pi build froze `Promise.prototype` everywhere, including the workflow sandbox. The runner now works with a frozen `Promise.prototype` and still catches children that were never awaited. Thanks to [@albertgwo](https://github.com/albertgwo) for [#2793](https://github.com/nicobailon/pi-subagents/pull/2793).
+- A workflow script failed with "emit.<field> must be a JSON value; received undefined" when it emitted an object with an undefined field, such as a child result's missing `outputPathMapping`, although `return` accepted the same object. `emit` now drops undefined object fields and turns undefined array entries into `null`, as `return` does, and workflow script errors report the script's own line numbers instead of one line later. Thanks to [@vip0351](https://github.com/vip0351) for [#2751](https://github.com/nicobailon/pi-subagents/issues/2751).
+- A workflow stage that resumed an earlier stage without its own `output` reused the earlier stage's report path, so it failed before launch when the earlier stage ran in the background, and overwrote the earlier report otherwise. It now writes to its own default report path. ([#2711](https://github.com/nicobailon/pi-subagents/issues/2711))
+- A background workflow's child rows showed no token usage or turn count, although each child's own status had them and the workflow total was their sum. Each child row now shows the usage and turn count from that child's result. Thanks to [@moxuun](https://github.com/moxuun) for the report. ([#2715](https://github.com/nicobailon/pi-subagents/issues/2715))
+- A long-running foreground child re-formatted every past tool call on each progress update, although progress shows only the latest 64, so each update got slower as the child's history grew. Progress updates now format only those 64 calls. ([#2704](https://github.com/nicobailon/pi-subagents/issues/2704))
+- Fleet reread and re-rendered the selected transcript every 750 ms even when it had not changed, which took hundreds of milliseconds per refresh for a long transcript. It now reuses the rendered transcript until the file, selection, width or tool view changes. ([#2705](https://github.com/nicobailon/pi-subagents/issues/2705))
+- A Herdr-placed Pi child's bridge kept every frame it received, so a healthy run failed and started reconnecting after its 1,024th frame. Frames are now released once the session has taken them. ([#2706](https://github.com/nicobailon/pi-subagents/issues/2706))
+- Two inspector opens for the same run or child at once, for example from Fleet and a tool call or from two Pi processes, could each open a pane and save a binding, so one pane could no longer be reached by `inspector.status` or `inspector.close`, and a close racing an open could miss the pane the open created. Open and close for the same run or child now wait for each other, across processes too. ([#2727](https://github.com/nicobailon/pi-subagents/issues/2727))
+
+## [0.76.1] - 2026-10-05
+
+### Highlights
+
+- When a subagent result wakes an idle parent, that run keeps the subagent list, MCP servers, and other extensions' prompt sections, and no longer churns the provider's prompt cache.
+- Updating pi-subagents while Pi is running now stops `/reload` with a clear "restart Pi" error instead of running a mix of old and new code.
+- In Herdr, a child asking its parent agent for help no longer turns the pane red.
+- `stop` works on a paused run whose result was already delivered, and `subagent doctor` now shows the same async capacity that launches use.
+- Reloading extensions while a child's result is waiting no longer lets a host such as pi-web lose that result.
+
+### Changed
+
+- The npm package now has the `extension` keyword, so Pi's extension catalog lists pi-subagents under Extensions instead of Unlabelled.
+
+### Fixed
+
+- When a subagent result, supervisor question, or other notice woke an idle parent, the run it started skipped Pi's normal prompt setup. From its second request on, it lost the subagent list, the MCP server list, and other extensions' prompt sections, and the changing prompt could invalidate the provider's prompt cache. The parent now gets the notice followed by a short `Subagent updates above.` message, which starts the run the normal way. Thanks to [@ashlineldridge](https://github.com/ashlineldridge) for [#2688](https://github.com/nicobailon/pi-subagents/issues/2688).
+- Reloading extensions while a child's result was waiting in Pi's queue made the session look idle, so a host such as pi-web could replace the session and lose the result. The session now stays busy until Pi picks up the result. Thanks to [@brettinternet](https://github.com/brettinternet) for [#2687](https://github.com/nicobailon/pi-subagents/pull/2687).
+- After pi-subagents was updated while Pi was running, `/reload` ran a mix of old and new code and failed with errors such as `completionNotifier.messageStarted is not a function`. Node cannot reload a module it has already imported, so loading now stops with an error that names both versions and asks you to restart Pi. Thanks to [@TheAsda](https://github.com/TheAsda) for [#2695](https://github.com/nicobailon/pi-subagents/issues/2695).
+- Child system prompts started with pi-subagents' own instructions instead of Pi's base prompt. Providers and extensions that recognize Pi's default prompt by its first sentence then sent `systemPromptMode: append` children Pi's whole prompt unchanged. Pi's prompt now comes first. ([#2692](https://github.com/nicobailon/pi-subagents/issues/2692))
+- When a per-tool timeout stopped a foreground child, its output said `Subagent timed out after <run timeout>ms.` (or `0ms` when no run timeout was set), naming a deadline that never fired. It now names the tool timeout, for example `Tool 'find' exceeded its timeout of 300000ms.` Thanks to [@mannainsect](https://github.com/mannainsect) for [#2691](https://github.com/nicobailon/pi-subagents/issues/2691).
+- `stop` failed with `paused result is missing` on a paused run whose result had already been delivered or was never written, and a finished parent workflow kept that run's async capacity slot. When the run's process has exited, `stop` now marks it stopped and the slot is freed. Thanks to [@builtroller](https://github.com/builtroller) for reporting [#2699](https://github.com/nicobailon/pi-subagents/issues/2699).
+- `subagent doctor` could report `usage: 0/3 used` while launches were rejected with `3/3 used`, for example in a session resumed with `pi --session <id>`, because doctor counted a different capacity pool than launches do. It now reads the same pool for both active async capacity and the spawn budget. Thanks to [@builtroller](https://github.com/builtroller) for reporting [#2698](https://github.com/nicobailon/pi-subagents/issues/2698).
+- In Herdr, the pane turned red, which means a person needs to act, whenever an async child needed attention, including a child waiting for its parent agent's answer. Those requests go to the parent agent, so pi-subagents no longer marks the pane blocked; the `⚠` in the pane's subagent label still shows it. Thanks to [@nateberkopec](https://github.com/nateberkopec) for reporting [#2702](https://github.com/nicobailon/pi-subagents/issues/2702).
+
 ## [0.76.0] - 2026-10-04
 
 ### Highlights

package/node_modules/pi-subagents/README.md

@@ -110,7 +110,7 @@ For bounded orchestration, `maxSubagentSpawnsPerRun` limits cumulative logical c
 
 or ask: "Check whether subagents and intercom are set up correctly."
 
-For installed-version help, use `/subagents-guide [topic]` or `subagent({ action: "guide", topic: "workflows" })`. The default topic is `overview`; available topics are `overview`, `workflows`, `agents`, `missions`, `observability`, `tool-reference`, `configuration`, `models`, `watchdog`, `extension-api`, and `council`.
+For installed-version help, use `/subagents-guide [topic]` or `subagent({ action: "guide", options: { topic: "workflows" } })`. The default topic is `overview`; available topics are `overview`, `workflows`, `agents`, `missions`, `observability`, `tool-reference`, `configuration`, `models`, `watchdog`, `extension-api`, and `council`.
 
 ## Documentation
 

package/node_modules/pi-subagents/agents/evidence-auditor.md

@@ -2,6 +2,7 @@
 name: evidence-auditor
 description: Independent evidence reviewer for checking whether important research claims are supported by their sources
 tools: read, web_search, fetch_content, get_search_content, source_check
+acceptanceRole: read-only
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true

package/node_modules/pi-subagents/agents/oracle.md

@@ -3,6 +3,7 @@ name: oracle
 aliases: advisor
 description: High-context decision-consistency oracle that protects inherited state and prevents drift
 tools: read, grep, find, ls, bash
+acceptanceRole: read-only
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -14,40 +15,29 @@ You are the oracle: a high-context decision-consistency subagent.
 
 Your primary job is to prevent the main agent from making hidden, conflicting, or inconsistent decisions by treating the inherited forked context as the authoritative contract. You are not the primary executor. You do not silently become a second decision-maker.
 
-Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
+Before anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. They form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
 
 Match search scope to the question. For runtime behavior, begin with specific source symbols, types, methods, and paths. For product, plan, policy, or decision drift, treat supplied documents and inherited context as first-class evidence. If source conflicts with docs about runtime behavior, trust source and report the conflict.
 
-If the task asks about asking or consulting the oracle, or asks to ask, consult, discuss with, or come to agreement with the oracle about a plan, design, or architecture decision, treat it as a short live consultation unless the parent explicitly requests a one-shot report. In a first response, return the strongest challenge point or focused follow-up question when a material tradeoff remains, so the parent can resume this same session for one targeted round. A one-shot response remains suitable for an explicit one-shot request, a trivial question, or a fully settled first answer. When runtime bridge instructions provide `contact_supervisor`, ask one focused question or challenge if a material unknown, contradiction, or unapproved decision would make a final recommendation guessy. If no supervisor channel is available, return the best recommendation and name the decision that still needs the main agent.
+If the task asks about asking or consulting the oracle, or asks to ask, consult, discuss with, or come to agreement with the oracle about a plan, design, or architecture decision, treat it as a short live consultation unless the parent explicitly requests a one-shot report. In a first response, return the strongest challenge point or focused follow-up question when a material tradeoff remains, so the parent can resume this same session for one targeted round. A one-shot response suits an explicit one-shot request, a trivial question, or a fully settled first answer.
 
-If you need clarification from the main agent and bridge instructions provide `contact_supervisor`, use it with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
-
-Do not send routine completion handoffs. If no coordination is needed, or after needed coordination is answered, return the final oracle recommendation normally. If `contact_supervisor` is unavailable, return the best recommendation and name the decision that still needs the main agent. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
+When runtime bridge instructions provide `contact_supervisor` and a material unknown, contradiction, or unapproved decision would make a recommendation guessy, ask one focused question with `reason: "need_decision"` and wait for the reply. Do not guess. Use `reason: "progress_update"` only for concise updates when blocked, when explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful; do not narrate your review through `contact_supervisor` or send routine completion handoffs. If no supervisor channel is available, return the best recommendation and name the decision that still needs the main agent. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
 
 Core responsibilities:
-- reconstruct inherited decisions, constraints, and open questions from the context
-- identify drift between the current trajectory and those inherited decisions
+- identify drift between the current trajectory and the inherited decisions, and call out when a proposed move conflicts with an earlier decision or constraint
 - surface contradictions and hidden assumptions the main agent may be missing
-- call out when a proposed move conflicts with an earlier decision or constraint
 - protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
-- when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
-- exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
+- when you recommend a pivot, explain exactly which prior assumption or decision should be revised and why
+- use your clean forked context to spot what the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
 - look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
 
 What you do not do by default:
-- do not edit files or write code
+- do not edit files or write code; use `bash` only for inspection, verification, or read-only analysis
 - do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
 - do not assume a `worker` implementation handoff is the default outcome
-- do not propose broad pivots unless the context clearly supports them
+- do not propose broad pivots unless the context clearly supports them; prefer narrow, specific corrections to the current path over rewriting the whole plan
 - do not continue the user conversation directly
 
-Working rules:
-- Use `bash` only for inspection, verification, or read-only analysis.
-- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` when bridge instructions provide that tool. If no supervisor channel is available, return the best recommendation and name the unresolved decision instead of guessing.
-- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` when bridge instructions provide that tool. If no supervisor channel is available, mark the decision as still needed in the final recommendation.
-- When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
-- Prefer narrow, specific corrections to the current path over rewriting the whole plan.
-
 Your output should follow this shape. If no executor handoff is warranted, say so plainly.
 
 Inherited decisions:

package/node_modules/pi-subagents/agents/researcher.md

@@ -57,6 +57,3 @@ Unverified claims and unresolved questions.
 
 ## Next steps
 Only the most useful follow-up research.
-
-## Supervisor coordination
-If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed research brief normally.