@xzzpig/pi-subagents 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/CHANGELOG.md +164 -0
  2. package/README.md +1 -1
  3. package/agents/oracle.md +8 -19
  4. package/agents/researcher.md +0 -3
  5. package/agents/reviewer.md +17 -61
  6. package/agents/scout.md +1 -4
  7. package/agents/worker.md +8 -25
  8. package/docs/agents.md +72 -7
  9. package/docs/configuration.md +58 -7
  10. package/docs/extension-api.md +36 -11
  11. package/docs/fork-extensions.md +1 -0
  12. package/docs/fork-supervisor-routing.md +77 -0
  13. package/docs/missions.md +34 -17
  14. package/docs/models.md +1 -1
  15. package/docs/observability.md +10 -5
  16. package/docs/tool-reference.md +117 -84
  17. package/docs/watchdog.md +8 -6
  18. package/docs/workflows.md +16 -7
  19. package/index.ts +5 -0
  20. package/package.json +6 -3
  21. package/prompts/council.md +1 -1
  22. package/skills/pi-subagents/SKILL.md +1 -1
  23. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  24. package/skills/pi-subagents/references/execution-controls.md +16 -16
  25. package/skills/pi-subagents/references/management-authoring-rpc.md +16 -12
  26. package/skills/pi-subagents/references/prompting-and-roles.md +3 -3
  27. package/src/agents/advertised-agent-prompt.ts +9 -1
  28. package/src/agents/agent-management.ts +4 -0
  29. package/src/agents/agent-memory.ts +3 -3
  30. package/src/agents/agent-scope.ts +4 -0
  31. package/src/agents/agent-serializer.ts +8 -1
  32. package/src/agents/agents.ts +191 -145
  33. package/src/api/preflight.ts +8 -4
  34. package/src/api/supervisor-routing.ts +196 -0
  35. package/src/extension/config.ts +21 -2
  36. package/src/extension/context-injection.ts +6 -1
  37. package/src/extension/control-notices.ts +1 -9
  38. package/src/extension/declaration-pinning.ts +164 -0
  39. package/src/extension/doctor.ts +7 -10
  40. package/src/extension/fanout-child.ts +7 -8
  41. package/src/extension/index.ts +143 -134
  42. package/src/extension/reply-workflow-script.ts +20 -11
  43. package/src/extension/rpc.ts +11 -6
  44. package/src/extension/schemas.ts +34 -30
  45. package/src/extension/subagent-guide.ts +86 -6
  46. package/src/extension/subagent-options.ts +47 -0
  47. package/src/extension/tool-activation.ts +3 -2
  48. package/src/extension/tool-description.ts +51 -68
  49. package/src/inspectors/actions.ts +37 -11
  50. package/src/inspectors/plugins.ts +3 -2
  51. package/src/inspectors/tmux/actions.ts +204 -0
  52. package/src/inspectors/tmux/client.ts +85 -0
  53. package/src/inspectors/tmux/plugin.ts +21 -0
  54. package/src/integrations/herdr-status.ts +18 -49
  55. package/src/integrations/program-status.ts +215 -0
  56. package/src/intercom/fork-supervisor-routing.ts +533 -0
  57. package/src/intercom/native-supervisor-channel.ts +152 -13
  58. package/src/intercom/result-intercom.ts +3 -2
  59. package/src/intercom/supervisor-ui.ts +2 -174
  60. package/src/missions/store.ts +25 -5
  61. package/src/profiles/profiles.ts +24 -21
  62. package/src/runs/background/active-async-capacity.ts +58 -8
  63. package/src/runs/background/async-execution.ts +143 -38
  64. package/src/runs/background/async-job-tracker.ts +11 -4
  65. package/src/runs/background/async-resume.ts +5 -2
  66. package/src/runs/background/await-async-run.ts +14 -9
  67. package/src/runs/background/binary-bootstrap.ts +2 -1
  68. package/src/runs/background/calendar-schedule.ts +90 -0
  69. package/src/runs/background/chain-root-attachment.ts +9 -5
  70. package/src/runs/background/fleet-view.ts +5 -5
  71. package/src/runs/background/notify.ts +185 -12
  72. package/src/runs/background/result-files.ts +116 -5
  73. package/src/runs/background/result-watcher.ts +99 -66
  74. package/src/runs/background/resume-guidance.ts +2 -2
  75. package/src/runs/background/run-child-session.ts +16 -2
  76. package/src/runs/background/run-id-resolver.ts +8 -5
  77. package/src/runs/background/run-status.ts +21 -16
  78. package/src/runs/background/runner-child-launch.ts +1 -0
  79. package/src/runs/background/runner-http-dispatcher.ts +3 -0
  80. package/src/runs/background/scheduled-runs.ts +256 -61
  81. package/src/runs/background/subagent-runner-bootstrap.ts +4 -1
  82. package/src/runs/background/subagent-runner.ts +32 -12
  83. package/src/runs/background/subagent-wait.ts +38 -19
  84. package/src/runs/background/terminal-run-index.ts +46 -1
  85. package/src/runs/background/wait-completions.ts +1 -0
  86. package/src/runs/background/wait-tool.ts +33 -23
  87. package/src/runs/background/workflow-terminal-proof.ts +39 -22
  88. package/src/runs/foreground/async-stop-action.ts +48 -22
  89. package/src/runs/foreground/execution.ts +94 -52
  90. package/src/runs/foreground/foreground-history.ts +1 -0
  91. package/src/runs/foreground/subagent-executor.ts +232 -77
  92. package/src/runs/shared/child-commands.ts +2 -1
  93. package/src/runs/shared/child-hooks.ts +4 -3
  94. package/src/runs/shared/child-launch.ts +3 -0
  95. package/src/runs/shared/child-session.ts +41 -24
  96. package/src/runs/shared/child-tool-plan.ts +13 -26
  97. package/src/runs/shared/dynamic-fanout.ts +1 -1
  98. package/src/runs/shared/fork-command-result.ts +10 -0
  99. package/src/runs/shared/herdr-placed-run.ts +5 -4
  100. package/src/runs/shared/mcp-direct-tool-allowlist.ts +5 -3
  101. package/src/runs/shared/model-resolution-diagnostic.ts +25 -0
  102. package/src/runs/shared/model-resolution.ts +30 -1
  103. package/src/runs/shared/nested-events.ts +5 -0
  104. package/src/runs/shared/parallel-handoff.ts +56 -8
  105. package/src/runs/shared/parallel-utils.ts +2 -0
  106. package/src/runs/shared/partial-output.ts +48 -0
  107. package/src/runs/shared/runner-launcher.ts +25 -0
  108. package/src/runs/shared/single-output.ts +53 -0
  109. package/src/runs/shared/structured-output.ts +14 -7
  110. package/src/runs/shared/subagent-control.ts +3 -3
  111. package/src/runs/shared/subagent-prompt-runtime.ts +47 -24
  112. package/src/runs/shared/workflow-async-child-guidance.ts +1 -1
  113. package/src/runs/shared/worktree-cleanup-apply.ts +160 -0
  114. package/src/runs/shared/worktree-cleanup-plan.ts +41 -19
  115. package/src/runs/shared/worktree-lock.ts +29 -0
  116. package/src/runs/shared/worktree.ts +12 -1
  117. package/src/shared/atomic-json.ts +4 -2
  118. package/src/shared/edit-distance.ts +33 -0
  119. package/src/shared/file-lease.ts +74 -0
  120. package/src/shared/formatters.ts +1 -5
  121. package/src/shared/model-info.ts +22 -0
  122. package/src/shared/package-version.ts +17 -0
  123. package/src/shared/parent-wake.ts +79 -0
  124. package/src/shared/pruned-fork.ts +7 -1
  125. package/src/shared/runtime-module-path.ts +19 -0
  126. package/src/shared/settings-file-lease.ts +36 -0
  127. package/src/shared/types.ts +36 -2
  128. package/src/shared/utils.ts +8 -6
  129. package/src/slash/prompt-template-bridge.ts +21 -20
  130. package/src/slash/slash-commands.ts +3 -3
  131. package/src/slash/subagents-admin.ts +2 -1
  132. package/src/tui/fleet-native-transcript.ts +2 -0
  133. package/src/tui/fleet-transcript.ts +12 -3
  134. package/src/tui/fleet.ts +11 -8
  135. package/src/tui/render.ts +27 -19
  136. package/src/tui/subagent-messages.ts +305 -0
  137. package/src/watchdog/diff-tool.ts +2 -2
  138. package/src/watchdog/register-main.ts +2 -22
  139. package/src/watchdog/render.ts +2 -24
  140. package/src/watchdog/runtime.ts +6 -4
  141. package/src/watchdog/settings.ts +18 -13
  142. package/src/watchdog/tool-actions.ts +2 -2
  143. package/src/workflows/scripted-workflow.ts +20 -6
  144. package/src/workflows/workflow-resources.ts +11 -0
package/CHANGELOG.md CHANGED
@@ -1,7 +1,41 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.22.0]
4
+
5
+ ### Added
6
+
7
+ - 新增 `@xzzpig/pi-subagents/supervisor-routing` 导出:版本化的父会话内 supervisor 响应器注册
8
+ (`registerSupervisorResponderViaEvents`),作用域为 sessionId + delegation requestId + ownerRunId + nodeId + agent。
9
+ - 结构化委派执行器新增内部 launch hooks:在真实 foreground runId 分配、canonical agent 解析之后、
10
+ 任何 child prompt 之前触发 `beforeNativeChildLaunch`,不改变模型可见的 request schema 或子进程环境。
11
+ - 原生 supervisor 通道支持独占接管:被接管的提问不再唤醒主模型、不再触发 detach,回复仍走文件权威写入。
12
+
3
13
  ## [Unreleased]
4
14
 
15
+ ## [0.21.0] - 2026-10-10 (fork)
16
+
17
+ ### Changed
18
+
19
+ - Sync upstream `v0.75.0` → `v0.77.0`: slimmer tool declarations, bounded inline
20
+ result previews, opt-in native runner launchers, calendar schedules, reviewed
21
+ worktree cleanup, reliable parent wakes, and canonical mission storage paths.
22
+ - Context injection now excludes untrusted project contributions and refreshes
23
+ across trust changes without retaining a stale project advertisement.
24
+ - Preserve sandbox/permission profiles, context injection, native Fleet transcripts,
25
+ and the Pi 1.0.0 baseline; align the test fixture with the SDK APIs used upstream.
26
+
27
+ ### Fixed
28
+
29
+ - Read each tool result's own tool name before the pending-call fallback, so an
30
+ overlapping blocked bash call is not attributed to an unfinished read.
31
+ - Retry failed native Fleet transcript reads without caching the failure.
32
+ - Preserve permission-profile enforcement when native launchers route children to
33
+ background runners, including explicit empty extension lists.
34
+ - Treat Pi 1 command `isError` results as failures while retaining targeted
35
+ cancellation and run-abort semantics.
36
+
37
+ ## Previous fork changes
38
+
5
39
  ### Changed
6
40
 
7
41
  - **Synced upstream `v0.74.0` → `v0.75.0`**: background subagents work on Pi 1.0.0
@@ -58,6 +92,136 @@
58
92
  and the fleet-native transcript renderer were re-applied on top of the
59
93
  upstream runner refactor; upstream's removal of `completionGuard` was
60
94
  adopted.
95
+
96
+ ## [0.77.0] - 2026-10-09
97
+
98
+ ### Highlights
99
+
100
+ - 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.
101
+ - Upgrading pi-subagents no longer costs resumed sessions their prompt cache, and upgrading under a running Pi no longer breaks every child launch.
102
+ - 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.
103
+ - 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.
104
+ - A session that declined project trust no longer takes models, agents, or settings from that project.
105
+
106
+ ### Added
107
+
108
+ - 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))
109
+ - 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))
110
+ - 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))
111
+ - 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))
112
+ - 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).
113
+ - 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))
114
+ - 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))
115
+
116
+ ### Changed
117
+
118
+ - 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))
119
+ - 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))
120
+ - 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))
121
+ - 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))
122
+ - 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))
123
+ - 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))
124
+ - 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))
125
+ - 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))
126
+ - `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))
127
+ - 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).
128
+ - 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).
129
+
130
+ ### Fixed
131
+
132
+ - 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))
133
+ - 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))
134
+ - 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))
135
+ - 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).
136
+ - 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.
137
+ - 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).
138
+ - 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))
139
+ - 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))
140
+ - 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))
141
+ - 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))
142
+ - 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))
143
+ - 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)).
144
+ - 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)).
145
+ - 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).
146
+ - 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))
147
+ - 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))
148
+ - 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))
149
+ - 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))
150
+ - 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))
151
+ - 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))
152
+ - 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))
153
+ - 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))
154
+ - 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).
155
+ - 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).
156
+ - 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))
157
+ - 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))
158
+ - 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))
159
+ - 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))
160
+ - 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))
161
+ - 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))
162
+
163
+ ## [0.76.1] - 2026-10-05
164
+
165
+ ### Highlights
166
+
167
+ - 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.
168
+ - 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.
169
+ - In Herdr, a child asking its parent agent for help no longer turns the pane red.
170
+ - `stop` works on a paused run whose result was already delivered, and `subagent doctor` now shows the same async capacity that launches use.
171
+ - Reloading extensions while a child's result is waiting no longer lets a host such as pi-web lose that result.
172
+
173
+ ### Changed
174
+
175
+ - The npm package now has the `extension` keyword, so Pi's extension catalog lists pi-subagents under Extensions instead of Unlabelled.
176
+
177
+ ### Fixed
178
+
179
+ - 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).
180
+ - 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).
181
+ - 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).
182
+ - 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))
183
+ - 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).
184
+ - `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).
185
+ - `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).
186
+ - 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).
187
+
188
+ ## [0.76.0] - 2026-10-04
189
+
190
+ ### Highlights
191
+
192
+ - Schedules can run every day or every week at a local time, in a timezone you choose, and on the weekdays you choose.
193
+ - `worktree.cleanup` can now delete the worktrees in a plan you reviewed and saved. Before, it could only list them.
194
+ - Background results are no longer lost in headless sessions (`pi -p`, SDK hosts) or when pi-web replaces a session it thinks is idle.
195
+ - Two Pi sessions running at the same time no longer overwrite each other's settings changes, schedules, or schedule history.
196
+ - A child that times out or crashes now returns the text it had written so far. A child with `outputSchema` now saves its structured result to the output file, not a closing sentence.
197
+
198
+ ### Added
199
+
200
+ - Schedules accept `every: "day"` or `every: "week"` with a local `HH:mm` time and an IANA timezone, plus the weekdays to run on for weekly schedules. If a daylight-saving change skips the time, that run is skipped. If the time happens twice, it runs once. After a restart, the next run is calculated again from the local date. Overlap, catch-up, quiet, and mission options work the same as on other schedules. Thanks to [@quifox](https://github.com/quifox) for [#815](https://github.com/nicobailon/pi-subagents/issues/815).
201
+
202
+ ### Changed
203
+
204
+ - `worktree.cleanup` can now apply a plan you saved and reviewed, once you authorize discarding those worktrees. Before it deletes anything, it checks Git state and ownership again. It keeps any worktree whose path now points outside the directory it was created in, any worktree that is locked or has been resumed, and any ignored files. It never deletes local branches, and each plan can be applied only once. Worktrees created before this version are always kept. Thanks to [@quifox](https://github.com/quifox) for [#1622](https://github.com/nicobailon/pi-subagents/issues/1622).
205
+
206
+ ### Fixed
207
+
208
+ - In a headless session (`pi -p`, or an SDK host without a UI), a background run's completion message could be lost. The turn could end before the message was sent, and the host then closed the session. Finished results are now handed to Pi before the turn ends, and Pi runs the completion turn next. Thanks to [@felores](https://github.com/felores) for [#2644](https://github.com/nicobailon/pi-subagents/issues/2644).
209
+ - pi-web could see a session as idle while a child's result was still on its way to the parent, so it could replace the session and lose the result. The session now counts as busy until Pi starts processing the result. Thanks to [@brettinternet](https://github.com/brettinternet) for [#2674](https://github.com/nicobailon/pi-subagents/pull/2674).
210
+ - A child with `outputSchema` and an `output` path wrote its final text to that file whenever the text was not empty. A short closing line such as "Enough; writing up." could replace the structured result. If the child returns a structured result and does not write the file itself, the file now holds that result as indented JSON. The child's returned output and output artifact show the same JSON. Thanks to [@tara-marchand](https://github.com/tara-marchand) for [#2672](https://github.com/nicobailon/pi-subagents/issues/2672).
211
+ - A child that timed out or crashed partway through a reply lost the text it was still writing. The parent now gets that text, labeled `Partial output before timeout:` or `Partial output before child error:`, and the result has `outputPartial: true`. The run still fails. The partial text is never saved as the output file and never counts as acceptance evidence. Runs that are stopped, interrupted, aborted, or exit with an ordinary error are unchanged. Thanks to [@yanqianglu](https://github.com/yanqianglu) for [#2653](https://github.com/nicobailon/pi-subagents/pull/2653) (#2549).
212
+ - An async workflow could keep its `maxActiveAsyncRunsPerSession` slot forever after it ended. This happened when one of its async children failed and there was no record that the child's process had exited, for example after a reload. The new `capacity.abandonedSlotReleaseAfterMs` setting frees the slot once the workflow has been over for longer than that time and each such child has failed, has no running runner, and has been inactive for a while. Set it to `false` to keep the slot. Thanks to [@jihunkim0](https://github.com/jihunkim0) for [#2658](https://github.com/nicobailon/pi-subagents/issues/2658).
213
+ - Two Pi sessions that changed extension settings at the same time could lose one of the changes. Agent override saves, `/subagents-load-profile`, and Watchdog setting changes now lock `settings.json.write-lock` beside the settings file while they read and save, so the second session waits for the first. If the settings directory is read-only, the lock cannot be created and the save fails with an error. Thanks to [@quifox](https://github.com/quifox) for [#2676](https://github.com/nicobailon/pi-subagents/pull/2676).
214
+ - Two sessions recording runs for the same schedule could each rewrite its run history from an old copy. A run could disappear from the history and its completion was never recorded, so the schedule stayed marked as running. History updates now use a short lock. Completion, restore, and delete now read the record of the run that is actually active. Thanks to [@quifox](https://github.com/quifox) for [#2677](https://github.com/nicobailon/pi-subagents/pull/2677).
215
+ - A session that lost the race to start a scheduled run could save its outdated copy of the schedule over the copy used by the session running it. That no longer happens. The session that lost still protects the active run from being deleted, and only postpones its own timer while the other session starts the run. Thanks to [@quifox](https://github.com/quifox) for [#2675](https://github.com/nicobailon/pi-subagents/pull/2675).
216
+ - If a session claimed a scheduled run but could not write the run id into the claim, for example because the disk was full, the empty claim file stayed behind. Every later run of that schedule was then skipped. The failed claim is now removed unless another session has already replaced it, and the original error is reported. Thanks to [@quifox](https://github.com/quifox) for [#2678](https://github.com/nicobailon/pi-subagents/pull/2678).
217
+ - On Windows, some file checks lost precision on large file ids, so two different files or folders could look like the same one. A schedule claim that failed to write could then delete another session's lock, and the agent-memory and worktree-cleanup checks could treat two directories as one. File ids are now compared exactly. ([#2679](https://github.com/nicobailon/pi-subagents/pull/2679), [#2685](https://github.com/nicobailon/pi-subagents/issues/2685))
218
+ - An agent that named a built-in MCP server with `_` in place of `-`, such as `mcp:codebase_memory` for the server `codebase-memory`, got none of the server's tools. The launch failed 10 seconds later saying the tools did not register. Both spellings now work, the same way Pi's MCP treats `-` and `_` as the same server. Thanks to [@trellis-zz](https://github.com/trellis-zz) for [#2668](https://github.com/nicobailon/pi-subagents/issues/2668).
219
+ - `workflow: true` failed with "found 0" when the model marked its script as plain ```` ```js ```` instead of ```` ```js workflow ````. If a reply has exactly one plain `js` block and no `js workflow` block, that block now runs. When no block is found, the error shows the exact opening line it looked for and suggests passing a script file path instead. Thanks to [@thetechpadawan](https://github.com/thetechpadawan) for [#2659](https://github.com/nicobailon/pi-subagents/issues/2659).
220
+ - `workflow: true` also said "found 0" when the model's reply reached the session with no text at all, which made it look as if the model had left out the script. Some providers drop the reply's visible text before Pi saves it. The error now says the reply text never arrived and suggests passing a script file path. ([#2669](https://github.com/nicobailon/pi-subagents/issues/2669))
221
+ - Creating an agent with a description longer than one line, or updating only the prompt of such an agent, saved only the first line of the description. The description is now saved as a YAML block, so every line is kept. Thanks to [@March-7](https://github.com/March-7) for [#2681](https://github.com/nicobailon/pi-subagents/pull/2681).
222
+ - When jobs leave a crowded async widget, it now shrinks to fit the jobs that remain instead of keeping blank rows. While the same jobs are listed, its height still stays fixed. Thanks to [@tara-marchand](https://github.com/tara-marchand) for [#2651](https://github.com/nicobailon/pi-subagents/issues/2651).
223
+ - The main watchdog no longer flags work you asked for mid-run as scope drift. Messages you send while the agent is running (steer or follow-up) now count as part of the task. Its review and `watchdog_diff` now also say that the list of changed paths covers the whole working tree. That list can include edits made before the session or by another session in the same checkout. Thanks to [@tara-marchand](https://github.com/tara-marchand) for [#2652](https://github.com/nicobailon/pi-subagents/issues/2652).
224
+
61
225
  ## [0.75.0] - 2026-10-02
62
226
 
63
227
  ### Highlights
package/README.md CHANGED
@@ -114,7 +114,7 @@ For bounded orchestration, `maxSubagentSpawnsPerRun` limits cumulative logical c
114
114
 
115
115
  or ask: "Check whether subagents and intercom are set up correctly."
116
116
 
117
- 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`.
117
+ 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`.
118
118
 
119
119
  ## Documentation
120
120
 
package/agents/oracle.md CHANGED
@@ -14,40 +14,29 @@ You are the oracle: a high-context decision-consistency subagent.
14
14
 
15
15
  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.
16
16
 
17
- 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.
17
+ 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.
18
18
 
19
19
  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.
20
20
 
21
- 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.
21
+ 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.
22
22
 
23
- 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`.
24
-
25
- 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.
23
+ 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.
26
24
 
27
25
  Core responsibilities:
28
- - reconstruct inherited decisions, constraints, and open questions from the context
29
- - identify drift between the current trajectory and those inherited decisions
26
+ - identify drift between the current trajectory and the inherited decisions, and call out when a proposed move conflicts with an earlier decision or constraint
30
27
  - surface contradictions and hidden assumptions the main agent may be missing
31
- - call out when a proposed move conflicts with an earlier decision or constraint
32
28
  - protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
33
- - when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
34
- - 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
29
+ - when you recommend a pivot, explain exactly which prior assumption or decision should be revised and why
30
+ - 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
35
31
  - look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
36
32
 
37
33
  What you do not do by default:
38
- - do not edit files or write code
34
+ - do not edit files or write code; use `bash` only for inspection, verification, or read-only analysis
39
35
  - do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
40
36
  - do not assume a `worker` implementation handoff is the default outcome
41
- - do not propose broad pivots unless the context clearly supports them
37
+ - do not propose broad pivots unless the context clearly supports them; prefer narrow, specific corrections to the current path over rewriting the whole plan
42
38
  - do not continue the user conversation directly
43
39
 
44
- Working rules:
45
- - Use `bash` only for inspection, verification, or read-only analysis.
46
- - 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.
47
- - 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.
48
- - 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.
49
- - Prefer narrow, specific corrections to the current path over rewriting the whole plan.
50
-
51
40
  Your output should follow this shape. If no executor handoff is warranted, say so plainly.
52
41
 
53
42
  Inherited decisions:
@@ -57,6 +57,3 @@ Unverified claims and unresolved questions.
57
57
 
58
58
  ## Next steps
59
59
  Only the most useful follow-up research.
60
-
61
- ## Supervisor coordination
62
- 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.
@@ -8,63 +8,26 @@ inheritProjectContext: true
8
8
  inheritSkills: false
9
9
  ---
10
10
 
11
- You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
11
+ You are a disciplined review subagent. Inspect, evaluate, and report findings with evidence. Do not guess; verify from the code, tests, docs, or requirements.
12
12
 
13
- ## Review types you handle
14
-
15
- ### 1. Code diffs (changed files)
16
- Inspect the actual diff or changed files. Verify:
17
- - Implementation matches intent and requirements.
18
- - Code is correct, coherent, and handles edge cases.
19
- - Tests cover the change and still pass.
20
- - No unintended side effects or regressions.
21
- - The change is minimal and readable.
22
-
23
- ### 2. Plans
24
- Validate a proposed plan for:
25
- - Feasibility and completeness.
26
- - Missing steps or hidden risks.
27
- - Alignment with existing architecture and constraints.
28
- - Whether the scope is appropriately bounded.
29
-
30
- ### 3. Proposed solutions
31
- Evaluate a suggested approach for:
32
- - Correctness and tradeoffs.
33
- - Fit with existing codebase patterns.
34
- - Whether simpler alternatives exist.
35
- - Edge cases the proposal may miss.
36
-
37
- ### 4. Current overall state of the codebase
38
- Assess codebase health by inspecting key files, tests, and structure. Look for:
39
- - Architecture drift or tech debt.
40
- - Inconsistent patterns or naming.
41
- - Areas lacking tests or documentation.
42
- - Obvious bugs or fragile code.
43
- - Opportunities to simplify or consolidate.
44
-
45
- ### 5. Specific PR or issue
46
- Review a PR or issue by understanding the context, then verifying:
47
- - The fix or feature addresses the root cause.
48
- - Changes are minimal and focused.
49
- - No regressions are introduced.
50
- - Tests and docs are updated as needed.
13
+ ## What to check by review type
14
+ - Code diffs: the implementation matches intent and requirements; it is correct and handles edge cases; tests cover the change and still pass; no unintended side effects or regressions; the change is minimal and readable.
15
+ - Plans: feasibility and completeness, missing steps or hidden risks, fit with existing architecture and constraints, and appropriately bounded scope.
16
+ - Proposed solutions: correctness and tradeoffs, fit with codebase patterns, simpler alternatives, and missed edge cases.
17
+ - Codebase state: architecture drift or tech debt, inconsistent patterns or naming, areas lacking tests or docs, obvious bugs or fragile code, and chances to simplify or consolidate.
18
+ - A specific PR or issue: understand the context, then verify the change addresses the root cause, stays minimal and focused, introduces no regressions, and updates tests and docs as needed.
51
19
 
52
20
  ## Working rules
53
- - Start from the exact diff and named source seam for code-behavior review. Use specific source, symbol, type, method, and path searches for discovery. Use broad or unscoped `grep` only when exhaustive verification is required, such as checking call sites, imports, removed names, or absence of a pattern.
54
- - Read the relevant files first. Read plan and progress when the task supplies them.
55
- - Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
56
- - Use `watchdog_diff` to inspect the bounded staged and unstaged working-tree delta against reviewer-launch `HEAD`, plus the bounded untracked-path inventory. It does not inspect committed ranges; when a task asks for one, require a supplied artifact or report that limitation rather than claiming the commit was reviewed.
57
- - Do not use shell commands, mutate the repository, or request general Git access. Report any test command that a supervisor must run.
58
- - Do not invent issues. Only report problems you can justify from evidence.
59
- - Prefer small corrective edits over broad rewrites.
60
- - If everything looks good, say so plainly.
61
- - If you are asked to maintain progress, record what you checked and what you found.
62
- - If review-only or no-edit instructions conflict with progress-writing instructions, review-only/no-edit wins. Do not write `progress.md`; mention the conflict in your final review only if it matters.
21
+ - Start from the exact diff and named source seam for code-behavior review. Discover with specific source, symbol, type, method, and path searches. Use broad or unscoped `grep` only when exhaustive verification is required, such as checking call sites, imports, removed names, or absence of a pattern.
22
+ - Read the relevant files first, and the plan and progress when the task supplies them.
23
+ - Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them because they are untracked; in a coding repo they should stay untracked and be covered by `.gitignore`.
24
+ - `watchdog_diff` does not inspect committed ranges. When a task asks for one, require a supplied artifact or report that limitation rather than claiming the commit was reviewed.
25
+ - Do not use shell commands, mutate the repository, or request general Git access. Report any test command a supervisor must run.
26
+ - Prefer small corrective edits over broad rewrites in your recommendations.
27
+ - If asked to maintain progress, record what you checked and found. If review-only or no-edit instructions conflict with progress-writing instructions, no-edit wins: do not write `progress.md`, and mention the conflict only if it matters.
63
28
 
64
29
  ## Supervisor coordination
65
- 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. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
66
-
67
- If `contact_supervisor` is unavailable, report the blocking decision in your final review. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
30
+ 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. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally. If `contact_supervisor` is unavailable, report the blocking decision in your final review. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
68
31
 
69
32
  ## Review output format
70
33
  Structure your findings clearly:
@@ -79,13 +42,6 @@ Structure your findings clearly:
79
42
 
80
43
  When reviewing code, cite file paths and line numbers. When reviewing plans, cite specific sections and assumptions.
81
44
 
82
- Filter findings by evidence, not by severity. Report only concrete current issues
83
- within the named review target, and support each one with source proof, a test
84
- or repro, or a contract contradiction. For a diff review, require that the issue
85
- is caused or made reachable by that diff. Use P0 for issues
86
- that block merge, P1 for issues that should be fixed before release, and P2 for
87
- report-only notes. Say exactly `No issues found.` when nothing qualifies.
45
+ Filter findings by evidence, not by severity. Report only concrete current issues within the named review target, and support each one with source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Use P0 for issues that block merge, P1 for issues that should be fixed before release, and P2 for report-only notes. Say exactly `No issues found.` when nothing qualifies.
88
46
 
89
- Use `blockers only` only for a final pre-merge re-check after the P1/P2
90
- inventory is already captured, or for an explicit emergency hotfix where the
91
- parent intentionally defers non-blocking findings.
47
+ Use `blockers only` only for a final pre-merge re-check after the P1/P2 inventory is already captured, or for an explicit emergency hotfix where the parent intentionally defers non-blocking findings.
package/agents/scout.md CHANGED
@@ -22,7 +22,7 @@ Focus on the minimum context another agent needs in order to act:
22
22
  - constraints, risks, and open questions
23
23
 
24
24
  Working rules:
25
- - Use `grep`, `find`, `ls`, and `read` to map the area before diving deeper. Reserve unscoped `grep` for exhaustive exact-literal verification after a scoped source/path pass.
25
+ - Reserve unscoped `grep` for exhaustive exact-literal verification after a scoped source/path pass.
26
26
  - Use `bash` only for non-interactive inspection commands.
27
27
  - When you cite code, use exact file paths and line ranges.
28
28
  - If you are told to write output, write it to the provided path and keep the final response short.
@@ -45,6 +45,3 @@ Explain how the pieces connect.
45
45
 
46
46
  ## Start Here
47
47
  Name the first file another agent should open and why.
48
-
49
- ## Supervisor coordination
50
- 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 scout findings normally.
package/agents/worker.md CHANGED
@@ -15,41 +15,24 @@ defaultProgress: true
15
15
 
16
16
  You are `worker`: the implementation subagent.
17
17
 
18
- You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
18
+ You are the single writer thread. Execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
19
19
 
20
- Use the provided tools directly. First read the provided context, supplied files, plan, task paths, and named seams. Then implement carefully and minimally. Use broad search only to verify or expand from that starting point.
20
+ Use your tools directly. First read the provided context, supplied files, plan, task paths, and named seams; use broad search only to verify or expand from that starting point. Then implement carefully and minimally.
21
21
 
22
- The builtin worker uses a strict tool allowlist. It does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
22
+ Your tools are a strict allowlist: you do not inherit the parent session's extension tools. Using an extension tool requires a custom agent that lists it in `tools` and loads its provider through `extensions` or `subagentOnlyExtensions`.
23
23
 
24
24
  If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
25
25
 
26
- If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. If `contact_supervisor` is unavailable, stop and report the required decision in your final response. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
27
-
28
- Default responsibilities:
29
- - validate the task or approved direction against the actual code
30
- - implement the smallest correct change
31
- - follow existing patterns in the codebase
32
- - verify the result with appropriate checks when possible
33
- - keep `progress.md` accurate when asked to maintain it
34
- - report back clearly with changes, validation, risks, and next steps
26
+ If the implementation needs a decision that was not approved, including a gap in the approved direction, pause and escalate instead of deciding it yourself. Runtime bridge instructions, when present, are the source of truth for which supervisor to contact and how. Use `contact_supervisor` with `reason: "need_decision"` and stay alive for the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking updates that help or were requested. Keep any blocked/progress update short and still return the full task result normally. If `contact_supervisor` is unavailable, stop and report the required decision in your final response. Do not send routine completion handoffs, and do not end your final response with a question the supervisor must answer before you can continue.
35
27
 
36
28
  Working rules:
37
- - Prefer narrow, correct changes over broad rewrites.
29
+ - Validate the task or direction against the actual code; implement the smallest correct change and follow existing patterns.
38
30
  - Preserve source discoverability: use specific names, clear types, one spelling per concept, source-named tests, and definition comments only when they explain a needed constraint.
39
31
  - Do not add speculative scaffolding or future-proofing unless explicitly required.
40
32
  - Do not leave placeholder code, TODOs, or silent scope changes.
41
- - Use `bash` for inspection, validation, and relevant tests.
42
- - If there is supplied context or a plan, read it first.
43
- - If implementation reveals a gap in the approved direction, pause and escalate with `contact_supervisor` and `reason: "need_decision"` instead of silently patching around it with an implicit decision.
44
- - If implementation reveals an unapproved product or architecture choice, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
45
- - If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
46
- - If you send a blocked/progress update through `contact_supervisor`, keep it short and still return the full structured task result normally.
47
- - Do not send routine completion handoffs. Return the completed implementation summary normally when no coordination is needed.
48
-
49
- When running in a chain, expect instructions about:
50
- - which files to read first
51
- - where to maintain progress tracking
52
- - where to write output if a file target is provided
33
+ - Use `bash` for inspection, validation, and relevant tests; verify the result when possible.
34
+ - Keep `progress.md` accurate when asked to maintain it.
35
+ - If your task expects code or file edits and you have not made them, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
53
36
 
54
37
  Your final response should follow this shape:
55
38