@xzzpig/pi-subagents 0.8.0 → 0.10.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 (221) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +2 -2
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +195 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +7 -6
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +384 -115
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +14 -2
  35. package/src/agents/agents.ts +935 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +42 -21
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +77 -21
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +65 -29
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +7 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +417 -133
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +60 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +204 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +718 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +489 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1223 -402
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +364 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +366 -0
  115. package/src/runs/shared/child-tool-plan.ts +632 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +146 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +99 -77
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +20 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/sandbox-profile-guard.ts +85 -0
  149. package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
  150. package/src/runs/shared/single-output.ts +89 -22
  151. package/src/runs/shared/structured-output.ts +49 -9
  152. package/src/runs/shared/subagent-control.ts +6 -2
  153. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  154. package/src/runs/shared/task-intent.ts +21 -7
  155. package/src/runs/shared/tool-availability.ts +18 -62
  156. package/src/runs/shared/tool-budget.ts +0 -14
  157. package/src/runs/shared/tool-timeout.ts +1 -1
  158. package/src/runs/shared/workflow-graph.ts +16 -0
  159. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  160. package/src/runs/shared/worktree.ts +571 -62
  161. package/src/shared/atomic-json.ts +3 -1
  162. package/src/shared/child-session-name.ts +46 -0
  163. package/src/shared/extension-context.ts +24 -0
  164. package/src/shared/fork-context.ts +21 -12
  165. package/src/shared/fork-session-cwd.ts +27 -0
  166. package/src/shared/formatters.ts +18 -3
  167. package/src/shared/jsonl-writer.ts +11 -0
  168. package/src/shared/launch-contract.ts +11 -1
  169. package/src/shared/pruned-fork.ts +450 -0
  170. package/src/shared/sandbox-profile.ts +23 -0
  171. package/src/shared/session-file-trust.ts +19 -0
  172. package/src/shared/session-tokens.ts +14 -3
  173. package/src/shared/settings.ts +19 -105
  174. package/src/shared/shortcuts.ts +17 -0
  175. package/src/shared/thinking-ceiling.ts +0 -6
  176. package/src/shared/types.ts +545 -70
  177. package/src/shared/utils.ts +60 -93
  178. package/src/shared/workflow-child-permit.ts +207 -0
  179. package/src/slash/delegation-adapters.ts +1 -9
  180. package/src/slash/delegation-request.ts +0 -4
  181. package/src/slash/prompt-template-bridge.ts +37 -1
  182. package/src/slash/slash-bridge.ts +1 -2
  183. package/src/slash/slash-commands.ts +383 -116
  184. package/src/slash/slash-live-state.ts +22 -11
  185. package/src/slash/subagents-admin.ts +29 -12
  186. package/src/tui/fleet-native-transcript.ts +4 -0
  187. package/src/tui/fleet-status.ts +217 -82
  188. package/src/tui/fleet-transcript.ts +11 -5
  189. package/src/tui/fleet.ts +54 -28
  190. package/src/tui/render-helpers.ts +31 -0
  191. package/src/tui/render.ts +1429 -163
  192. package/src/watchdog/change-signature.ts +40 -1
  193. package/src/watchdog/child-status.ts +54 -34
  194. package/src/watchdog/diff-tool.ts +77 -0
  195. package/src/watchdog/emission-guard.ts +5 -3
  196. package/src/watchdog/guidance.ts +20 -0
  197. package/src/watchdog/register-child.ts +28 -25
  198. package/src/watchdog/register-main.ts +10 -9
  199. package/src/watchdog/render.ts +4 -5
  200. package/src/watchdog/review.ts +15 -4
  201. package/src/watchdog/rules.ts +70 -0
  202. package/src/watchdog/runtime.ts +75 -92
  203. package/src/watchdog/scope.ts +0 -11
  204. package/src/watchdog/settings.ts +48 -104
  205. package/src/watchdog/turn-delta.ts +1 -1
  206. package/src/watchdog/types.ts +18 -32
  207. package/src/watchdog/warning-format.ts +0 -1
  208. package/src/workflows/chat-progress.ts +7 -3
  209. package/src/workflows/host-command.ts +235 -0
  210. package/src/workflows/scripted-workflow.ts +988 -59
  211. package/src/workflows/workflow-checklist.ts +439 -0
  212. package/src/workflows/workflow-child-summary.ts +121 -0
  213. package/src/workflows/workflow-preflight.ts +297 -0
  214. package/src/workflows/workflow-receipt.ts +232 -6
  215. package/src/workflows/workflow-resources.ts +150 -0
  216. package/src/workflows/workflow-settlement.ts +246 -0
  217. package/src/runs/shared/child-protocol.ts +0 -401
  218. package/src/runs/shared/pi-args.ts +0 -935
  219. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  220. package/src/runs/shared/turn-budget.ts +0 -98
  221. package/src/shared/post-exit-stdio-guard.ts +0 -85
package/CHANGELOG.md CHANGED
@@ -1,7 +1,484 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.10.0] - 2026-09-10 (fork release)
4
+
5
+ ### Added
6
+
7
+ - **`sandbox: <profile-name>` for native agents.** Agent frontmatter (or a
8
+ builtin override) may select one named `pi-sandbox` profile from the user's
9
+ global `<agentDir>/sandbox.json`. The selector is a scalar name only: objects,
10
+ empty values, path-like names, and the literal `false` are rejected, and the
11
+ field is refused for `external-cli` and `external-job` runners. The launcher
12
+ resolves and injects the installed `pi-sandbox` extension plus a startup guard
13
+ even when `extensions` is an explicit allowlist; a missing package, unreadable
14
+ manifest, capability-ceiling denial, unknown profile, or failed sandbox
15
+ initialization fails the launch before the child's first model turn.
16
+ - **Startup acknowledgement is verified before the first turn.** The guard
17
+ blocks the child when the profile never acknowledged successful startup, and
18
+ only the validated profile identity is persisted in async status, nested-event,
19
+ and intercom projections. The project trust decision travels with the child as
20
+ a boolean; a project-scoped selector is rejected unless the project is trusted
21
+ and the child cwd matches the trusted project root exactly.
22
+ - **A blocked child reports its real reason.** A startup block publishes its
23
+ failure through the child startup diagnostics channel (including the available
24
+ profile names), so callers see the profile error instead of "Subagent produced
25
+ no output (possible model cold-start or empty response)", and the failure is
26
+ classified as `startupBlocked` rather than a retryable model failure — it no
27
+ longer records a 24-hour model exclusion or triggers pointless model fallback.
28
+
29
+ ### Changed
30
+
31
+ - **Sandbox configuration is never injected into the child.** Only the selected
32
+ profile name, the trust snapshot, the startup acknowledgement channel, and the
33
+ diagnostics path cross the launch boundary, and those keys are restored on the
34
+ host immediately after the child session is created. Launches without a
35
+ `sandbox` selector keep the previous behavior unchanged.
36
+
37
+ ## [0.9.0] - 2026-09-05 (fork release)
38
+
39
+ ### Changed
40
+
41
+ - **Synced upstream v0.56.0 → v0.65.0.** Highlights: subagents now run as
42
+ native Pi `AgentSession`s instead of spawned `pi` CLI processes (#1844),
43
+ managed worktrees gain validated `baseRef` and per-project nesting,
44
+ compact workflow lane summaries, fail-closed model selection, agent scan
45
+ dirs (`subagents.agentScanDirs`), a file-watched agent discovery cache,
46
+ and the `pi-subagents/pi-args` subpath rename to `pi-subagents/child-tool-plan`.
47
+ Upstream's own tests now cover `resolvePermissionSystemExtension()`
48
+ (child-tool-plan-permission-system.test.ts); the fork's `@xzzpig`
49
+ candidate-priority test merged into that suite.
50
+ - Dropped the fork's Pi SDK `streamFn` option-naming divergence: upstream
51
+ ships `agentStreamOptions()` (dual `streamFn`/`streamFunction`) at every
52
+ call site, which is strictly more compatible than the fork's single-name form.
53
+ - Raised dev-dependency SDK baseline stays at 0.84.2 while adopting
54
+ upstream's oxlint tooling.
55
+
56
+ ### Preserved fork features across the merge
57
+
58
+ - `@xzzpig/pi-permission-system` priority in `resolvePermissionSystemExtension()`
59
+ (re-applied to the new `src/runs/shared/child-tool-plan.ts`).
60
+ - Context injection: `injectToContext` frontmatter, `subagents.injectAgents`
61
+ setting, session snapshot + `before_agent_start` injection, and
62
+ `/subagents-doctor` reporting, re-woven into upstream's
63
+ `discoverAgentSnapshot` discovery architecture.
64
+ - Fleet native transcript rendering (`v` key renderer toggle, native module
65
+ loader, mode-aware transcript cache) plus mouse-wheel scrolling, extended
66
+ to upstream's new `trustedFiles`/`trustedFileRoot` transcript read options.
67
+ - Foreground tool-result normalization with bounded `toolCallId` de-duplication
68
+ for mixed Pi host event shapes, ported to upstream's `processEvent`
69
+ child-session event architecture (shared `handleToolResult` path).
70
+ - The shared agent-eject API (`src/api/agent-management.ts`,
71
+ `ejectAgentDefinition`) used by pi-goal-x, adapted to upstream's renamed
72
+ imports (`resolveEffectiveThinking`, `child-tool-plan`).
73
+ - Fork package naming (`@xzzpig/pi-subagents`), env-isolated test scripts,
74
+ `prepack` bundle build, and `@xzzpig/pi-components` bundledDependencies.
75
+
3
76
  ## [0.7.0] - 2026-08-24
4
77
 
78
+ ## [0.65.0] - 2026-09-04
79
+
80
+ ### Highlights
81
+ - Subagents now run through native Pi sessions instead of spawning separate `pi` processes, making delegation simpler and less fragile.
82
+ - Workflow status is easier to scan with compact lane summaries and clearer supervisor messages.
83
+ - Model selection fails clearly when configured models are unavailable, instead of silently using a provider default.
84
+ - Managed worktrees are safer and more flexible, with validated `baseRef` support and per-project nesting.
85
+ - Background children can use provider-extension models reliably, including dynamically registered models such as router providers.
86
+
87
+ ### Added
88
+ - Include sanitized model, provider, reason, and expiry details when no usable subagent model candidates remain. Thanks [@AlexKucera](https://github.com/AlexKucera) for #1841.
89
+ - Allow managed worktrees to start from a validated `baseRef` instead of always using `HEAD`. Thanks [@jaudiger](https://github.com/jaudiger) for #1842.
90
+
91
+ ### Changed
92
+ - Run subagents as native Pi `AgentSession`s instead of spawned `pi` CLI processes (#1844). Foreground children run in the parent process, and background children run in the detached runner.
93
+ - Foreground children no longer load ambient extensions. Use background children for agents that need MCP tools or provider-extension models. Background children require Pi from the installed `@earendil-works/pi-coding-agent` package, not a standalone `pi` binary.
94
+ - Rename package subpath `pi-subagents/pi-args` to `pi-subagents/child-tool-plan`; `PI_SUBAGENT_PI_BINARY` now applies only to Herdr project panes and the profile model probe.
95
+ - Replace collapsed async workflow role summaries with a compact lane view while keeping full details available when expanded (#1827).
96
+ - Add `contact_supervisor` to the bundled reviewer and scout tool allowlists without adding mutation tools (#1846).
97
+
98
+ ### Fixed
99
+ - Drop only malformed persisted model-exclusion entries and rewrite the cleaned cache.
100
+ - Stop live workflow children when a run-level stop targets an in-memory async workflow controller.
101
+ - Fail closed when a fallback-only model configuration resolves no launch candidates. Thanks [@AdenosineTP](https://github.com/AdenosineTP) for #1853.
102
+ - Resolve native child models after child extensions register provider models. Thanks [@mystery4f](https://github.com/mystery4f) for #1855.
103
+ - Ignore stale authentication-related model exclusions after Pi's `auth.json` is refreshed, while preserving quota, rate-limit, overload, and model-unavailable exclusions. Thanks [@wesleyfei1](https://github.com/wesleyfei1) for #1835.
104
+ - Show native supervisor requests and outbound replies as bounded TUI cards in parent sessions (#1845).
105
+ - Suppress stale async supervisor-request notices after the native request has already been answered (#1838). Thanks [@VladimirGVP](https://github.com/VladimirGVP).
106
+ - Flush async workflow result assembly after session replacement when every child is already terminal, without permitting stale-context launches (#1833). Thanks [@redcomet168](https://github.com/redcomet168).
107
+ - Accept calendar/platform `claude --version` output during Claude Code adapter preflight while retaining required launch-flag validation. Thanks [@drouhard](https://github.com/drouhard).
108
+ - Show passive local command availability for external CLI agents in capability listings without replacing launch preflight (#1829). Thanks [@drouhard](https://github.com/drouhard).
109
+ - Nest native managed worktrees under per-project directories while preserving unsafe-location checks (#1831). Thanks [@moofone](https://github.com/moofone).
110
+
111
+ ## [0.64.0] - 2026-09-02
112
+
113
+ ### Highlights
114
+ - Watchdog can now warn or block child launches before they start, based on role and model rules.
115
+ - Watchdog reviews are easier to guide with safe diff access, reusable `WATCHDOG.md` instructions, and configurable child review cadence.
116
+ - Watchdog findings are easier to see in parent results, completion notices, acceptance evidence, and Fleet.
117
+ - Workflow status and async results are less noisy and more accurate.
118
+
119
+ ### Added
120
+ - Add watchdog launch rules under `subagents.watchdog.rules`, with per-role model allow and deny globs that warn or block before a child starts.
121
+ - Give watchdog reviewers a read-only `watchdog_diff` tool for session-start diffs, untracked paths, path narrowing, and stat summaries.
122
+ - Run child watchdog reviews on a configurable cadence with `children.cadence` and `children.overrides.<agent>.cadence`.
123
+ - Show child watchdog warnings in parent results, acceptance evidence, completion notices, and Fleet `wd:<n>` chips.
124
+ - Load watchdog reviewer instructions from project and agent `WATCHDOG.md` files.
125
+
126
+ ### Changed
127
+ - Reject unsupported watchdog settings that never took effect: `delivery`, `showDuringRun`, `syncBacklog`, `lateWarningPolicy`, `compactAtPercent`, `reviewRetryDelayMs`, `maxReviewFailures`, `asyncCompletion`, and `guidance.systemPromptPath`.
128
+ - Remove watchdog auto-follow. Pi 0.84+ already continues after displayed boundary warnings, and repeated identical warnings now stop after `subagents.watchdog.stalemateRepeats`. The `autoFollow` settings block is now unknown.
129
+
130
+ ### Fixed
131
+ - Keep advisory preflight checks out of runtime workflow rows and queued checklist counts (#1821). Thanks [@stekman08](https://github.com/stekman08).
132
+ - Preserve effective thinking in completed async step results. Thanks to [@Nickonomic](https://github.com/Nickonomic) for #1823.
133
+ - Forward workflow child control overrides through new and retained launches, and suppress idle needs-attention notices before the first assistant turn (#1817). Thanks [@rrocxela](https://github.com/rrocxela).
134
+
135
+ ## [0.63.0] - 2026-09-01
136
+
137
+ ### Highlights
138
+ - Workflow progress is easier to scan in status, Fleet, and live widgets.
139
+ - Additional agent folders can now be configured without copying definitions into one directory.
140
+ - Worktrunk users get managed worktrees automatically, with native Git available as the fallback.
141
+ - Fleet can jump straight into the selected child run's Herdr inspector.
142
+ - Async runs clean up and report edge cases more reliably.
143
+
144
+ ### Added
145
+ - Show workflow progress as stacked checklist summaries in status, Fleet, and live widget views (#1806).
146
+ - Add configurable extra agent scan directories with one-segment wildcard expansion. Thanks to [@mystery4f](https://github.com/mystery4f) for #1801.
147
+ - Make Worktrunk a first-class managed worktree provider, selected automatically when available with native Git as the fallback (#1800).
148
+ - Let Fleet open the selected async child in its child-specific Herdr inspector. Thanks to [@stekman08](https://github.com/stekman08) for #1790.
149
+
150
+ ### Changed
151
+ - Show workflow checklist phases first in collapsed views, while keeping child details available when expanded (#1810).
152
+
153
+ ### Fixed
154
+ - Keep isolated test runs from writing agent definitions into an inherited `PI_CODING_AGENT_DIR`. Thanks to [@mapleluvr](https://github.com/mapleluvr) for #1809.
155
+ - Prevent nested tool-availability diagnostics from failing an otherwise valid parent result. Thanks to [@robertvangor](https://github.com/robertvangor) for #1802.
156
+ - Free async capacity correctly after workflows finish, even when saved step status is stale. Thanks to [@boggylp](https://github.com/boggylp) for #1804.
157
+ - Make `subagents.agentOverrides.<name>` replace matching custom-agent frontmatter fields, consistently with builtin agents. Thanks to [@expoli](https://github.com/expoli) for #1796.
158
+ - Strip the trailing Pi turn-timing footer from child output. Thanks to [@fkhawajagh](https://github.com/fkhawajagh) for #1792.
159
+ - Keep inferred acceptance reports out of reviewer and read-only child prompts. Thanks to [@expoli](https://github.com/expoli) for #1797.
160
+ - Preserve coordinated read-only intent when direct async children resume, and show captured structured output in completion and status evidence. Thanks to [@fkhawajagh](https://github.com/fkhawajagh) for #1788.
161
+ - Keep macOS subagent tasks out of argv by delivering them through temporary files. Thanks to [@josephkallas](https://github.com/josephkallas) for #1793.
162
+
163
+ ## [0.62.0] - 2026-08-31
164
+
165
+ ### Highlights
166
+ - Child agents can report completion evidence more cleanly and stay away from tools they should not use.
167
+ - Session-only schedules keep personal scheduled work tied to the session that created it.
168
+ - Async forked runs now start and resume in the working directory you requested.
169
+ - Windows child launches are more reliable, with clearer errors when Pi cannot find a valid CLI.
170
+ - External CLI and read-only recovery paths are sturdier when workers disappear or prompts include unusual line separators.
171
+
172
+ ### Added
173
+ - Let native children with `outputSchema` include required acceptance evidence in the same `structured_output` call with `acceptance.report: "on"`; `acceptance.report: "off"` keeps fenced acceptance reports. Thanks [@mapleluvr](https://github.com/mapleluvr) for #1770.
174
+ - Add per-agent `excludeTools` deny-lists that compose with Pi's ambient or explicit child tool selection. Thanks [@expoli](https://github.com/expoli) for #1776.
175
+ - Add session-only durable schedules that only run in the session that created them. Thanks [@yangfeng20](https://github.com/yangfeng20) for #1777.
176
+
177
+ ### Fixed
178
+ - Keep async forked runs in the requested child `cwd` when they start or resume. Thanks [@stekman08](https://github.com/stekman08) for #1785.
179
+ - Accept JSON-encoded acceptance objects from model tool calls, while still failing clearly for malformed strings. Thanks [@mapleluvr](https://github.com/mapleluvr) for #1781.
180
+ - Keep steer and follow-up receipt statuses separate from their redacted message previews (#1773).
181
+ - Create async lifecycle sidecars before external CLI workers begin worktree changes, so disappeared runners are reported as failed runs. Thanks [@fkhawajagh](https://github.com/fkhawajagh) for #1764.
182
+ - Preserve explicit read-only intent when escaped line separators surround no-edit wording. Thanks [@fkhawajagh](https://github.com/fkhawajagh) for #1765.
183
+ - Launch child Pi processes through the resolved CLI JavaScript on Windows, and run JavaScript `PI_SUBAGENT_PI_BINARY` overrides with Node. Thanks [@caohuipeng](https://github.com/caohuipeng) for #1768.
184
+ - Resolve the installed Pi CLI on Windows wrapper hosts from the forwarded package root, and report a clear error when no verified CLI can be found. Thanks [@lux032](https://github.com/lux032) for #1780.
185
+
186
+ ## [0.61.0] - 2026-08-31
187
+
188
+ ### Highlights
189
+ - Subagent runs use less context and repeat less status text, so everyday delegation is cheaper and easier to scan.
190
+ - Status, Fleet, widgets, RPC, and background-work views refresh with less duplicated work.
191
+ - Async recovery is more reliable when active status files, child reports, or provider fallback attempts go wrong.
192
+ - Workflow permissions are clearer with named workflow resources and `bg_wait` as the primary background wait tool.
193
+ - Model listings now show effective models for discovered and runtime-registered agents.
194
+
195
+ ### Added
196
+ - Add extension-owned named workflow resources so permission and policy extensions can distinguish trusted workflow resources from raw scripts. Thanks [@mathiasloh](https://github.com/mathiasloh) for #1751.
197
+ - Add workflow-only `globalConcurrencyLimit` and `maxSubagentSpawnsPerRun` overrides for top-level `workflowScript` calls. Thanks [@RapierCraft](https://github.com/RapierCraft) for #1760.
198
+ - Remove the deprecated compatibility wait alias; use `bg_wait` instead (#1729).
199
+
200
+ ### Changed
201
+ - Show effective model mappings for discovered and runtime-registered subagents through management and `/subagents-models`. Thanks [@RapierCraft](https://github.com/RapierCraft) for #1732.
202
+ - Trim default subagent prompt guidelines to five parent-facing entries while keeping advanced workflow details in the packaged guide. Thanks [@Ran-Xing](https://github.com/Ran-Xing) for #1746.
203
+ - Reduce repeated heartbeat status updates during delegated runs while keeping foreground progress and complete terminal responses (#1739).
204
+ - Clarify that `fallbackModels` handles provider/model timeouts but not run-level `timeoutMs` / `maxRuntimeMs` expiry. Thanks [@kaplan-shaked](https://github.com/kaplan-shaked) for #1745.
205
+ - Pass requested session and timestamp context to background-work providers so they can avoid listing unrelated sessions while preserving strict validation (#1737).
206
+ - Avoid repeated external-run display normalization during Fleet refresh while still validating externally replaced or mutated records (#1736).
207
+ - Clarify that `oracle` and top-reasoning models are escalation tools, not routine defaults.
208
+ - Serve broad RPC status requests from restored in-memory state when safe, while preserving targeted status and transcript behavior (#1735).
209
+
210
+ ### Fixed
211
+ - Isolate corrupt active async status files during restoration so valid runs remain available and corrupt run artifacts are preserved. Thanks [@zhexulong](https://github.com/zhexulong) for #1756.
212
+ - Reduce async widget update churn during running workflows by repainting animation ticks without reinstalling the widget and coalescing close status refreshes (#1726).
213
+ - Avoid repeated staged workflow projection during widget rendering. Thanks [@kkkhs](https://github.com/kkkhs) for #1730.
214
+ - Preserve durable file-only child reports and continue read-only workflow review after malformed acceptance metadata (#1724).
215
+ - Preserve model origins across fallback and fork preparation, so eligible fallbacks work for unavailable configured primaries while invalid explicit models still fail closed. Thanks [@xz-dev](https://github.com/xz-dev) for #1747.
216
+ - Stop hidden 125ms spinner redraws while keeping progress refreshes and one-second animation frames (#1747).
217
+
218
+ ## [0.60.0] - 2026-08-30
219
+
220
+ ### Highlights
221
+ - Agent selection is easier with compact capability lists and structured capability details.
222
+ - Async status views are calmer and show workflow progress with clearer grouping and labels.
223
+ - Subagent guidance is clearer about when to work directly and when to orchestrate delegated planning, implementation, and review.
224
+ - Windows and macOS runs avoid more distracting console flashes, delayed failures, and startup hangs.
225
+ - Recovery paths preserve better diagnostics when child runs time out, fail early, or cannot provide requested output.
226
+
227
+ ### Added
228
+ - Add `action: "list", capabilities: true` for compact prompt-free agent capability discovery. Thanks to [@peedrr](https://github.com/peedrr) for #1717.
229
+ - Add structured `details.agentCapabilities` records so callers can select agents without parsing prose rows (#1720).
230
+
231
+ ### Changed
232
+ - Show `runs.lanes(...)` workflows with active-stage focus and planned-stage progress in async status widgets (#1699).
233
+ - Align foreground subagent result labels with async widget labels and disambiguate duplicate rows (#1697).
234
+ - Render parallel subagent workflow groups as readable cards with nested agent rows (#1696).
235
+ - Remove repeated one-child async widget status labels and compact progress echoes (#1695).
236
+ - Tighten packaged subagent and Council Mode guidance for one-child launches, composed `workflowScript` runs, generic review validation, and private policy boundaries.
237
+ - Clarify portable model-tier guidance for parent, worker, scout, reviewer, and critique subagents without requiring a specific provider.
238
+ - Trim duplicated orchestration recipes from the packaged skill while keeping detailed policy and execution references in one place.
239
+ - Clarify when the parent should work directly versus orchestrate delegated subagent work, including who owns decisions and publication (#1722).
240
+ - Clarify `workflowScript` portability and `runs.host(...)` working-directory limits, including outer workflow `cwd` and trusted `cd ... && command` patterns (#1679).
241
+
242
+ ### Fixed
243
+ - Treat malformed persisted async status states as partial, bound persisted workflow stage text, and fail closed when an explicit child-output path cannot be inspected before a run.
244
+ - Surface recovery diagnostics for dirty timed-out children that miss requested reports, while keeping them fail-closed (#1713).
245
+ - Keep retained-session resume runners from flashing console windows on Windows while preserving Unix background detachment. Thanks to [@Zethu5](https://github.com/Zethu5) for #1711.
246
+ - Hide mutation-evidence Git subprocess windows on Windows to prevent visible console flashes or terminal tabs. Thanks to [@dnnkeeper](https://github.com/dnnkeeper) for #1706.
247
+ - Deliver immediate async workflow terminal failures on macOS without requiring a later status refresh (#1700).
248
+ - Skip untracked-file enumeration for watchdog signatures when the Git root is the user home or has no tracked files, avoiding startup and turn hangs in accidental large home repositories. Thanks to [@AluxesLAS](https://github.com/AluxesLAS) for #1693.
249
+ - Reuse a fork-family prompt cache key for OpenAI-style forked subagent requests so sibling fork children keep cache affinity without pooling fresh children. Thanks to [@Shinkicast](https://github.com/Shinkicast) for #1682.
250
+ - Show workflow child `[fresh]` and `[fork]` context labels in Fleet status rows alongside model and thinking badges.
251
+ - Match pi-mcp-adapter direct-tool names when configured MCP server names contain hyphens. Thanks to [@unrelentingfox](https://github.com/unrelentingfox) for #1685.
252
+ - Animate running FleetView glyphs from the wall clock and repaint unchanged running entries. Thanks to [@Pudgey](https://github.com/Pudgey) for #1688.
253
+
254
+ ## [0.59.0] - 2026-08-28
255
+
256
+ ### Highlights
257
+ - Run host commands from workflow scripts with safer saved output and clearer command results.
258
+ - Build sequential parallel workflows with `runs.lanes(...)`, launch preflight labels, and better retained-resume behavior.
259
+ - See cleaner async status, child labels, and worktree handoff details without extra setup.
260
+ - Recover more reliably from stale contexts, provider aborts, missing outputs, malformed MCP metadata, and Windows file locks.
261
+ - Control live workflow children from more places, including non-TUI and RPC hosts.
262
+
263
+ ### Added
264
+ - Add `runs.host(...)` command steps to `workflowScript`, with required timeouts, saved output, and status and receipt evidence (#1648).
265
+ - Add CI and gate monitor rows that record monitor kind, terminal verdict, freshness, and report pointers in workflow status and receipts.
266
+ - Persist workflow lane metadata in child status, receipts, and existing worktree handoff manifests, including display-only worktree paths and branches.
267
+ - Add `runs.lanes(...)` for parallel sequential workflow stages with per-lane results and retained-resume support (#1633).
268
+ - Add display-only `preflight` lane metadata for workflowScript launches, with coverage warnings and planned-lane rendering in launch, status, and live-card views.
269
+ - Add a plan-only `worktree.cleanup` management action that records a cleanup plan without removing worktrees or branches.
270
+ - Give every subagent child session a human-readable display name, and include it in result, progress, status, workflow, nested, and intercom payloads. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #1615.
271
+ - Add `/subagents-steer <run-id> [--child <child-id>] <message>` so non-TUI sessions and RPC hosts can steer live async runs. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #1608.
272
+ - Add explicit `allowNestedSubagents` agent authorization for nested fanout without replacing inherited tools or extensions. Thanks to [@tutu359](https://github.com/tutu359) for #1587.
273
+ - Accept a child id on `/subagents-stop <run-id> <child-id>` so one child of a multi-child async run can be stopped without stopping the whole run. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #1603.
274
+
275
+ ### Changed
276
+ - Reduce noisy launch, status, output, settings, and worktree cleanup messages without changing behavior.
277
+ - Include a direct resumable child id in missing workflow receipt guidance when retained status proves it is safe.
278
+ - Clarify `workflowScript` contracts for retained resume keys and durable child output paths.
279
+ - Record merge or supersession evidence in existing worktree handoff manifests and show cleanup eligibility without removing anything.
280
+ - Show optional lane and work-item context in async status rows, including phase, gate, next action, output, run reference, and stale or blocked state.
281
+ - Show workflow child labels and phases in async status progress while preserving stable workflow keys.
282
+ - Remove assistant turn budgets, including hard termination, wrap-up prompt injection, and launch configuration.
283
+ - Split internal launch, status, settlement, evidence, and direct-MCP planning code into smaller modules without changing public behavior.
284
+
285
+ ### Fixed
286
+ - Match detached workflow completion by exact child identity, keep host gate rows in snapshots, and report missing host verdicts as inconclusive.
287
+ - Replace explicit `runs.host(...)` output files atomically inside their verified directory, and retry transient Windows destination locks.
288
+ - Reject malformed MCP direct-tool server and metadata-cache fields when JSON is loaded.
289
+ - Preserve live composite child tool-call ids for `cursor-native`, so Cursor MCP results keep matching pending execs. Thanks to [@moofone](https://github.com/moofone) for #1677 and #1678.
290
+ - Ignore stale cached UI contexts during background status refresh and session lifecycle cleanup (#1670).
291
+ - Compact workflow preflight status in default TUI and status views while keeping full details available when expanded (#1668).
292
+ - Give `runs.lanes(...)` stage-0 retained-resume validation actionable `runs.run(...)` guidance instead of a generic error (#1657).
293
+ - Remove the remaining `lane:` prefix from operator-facing async status rows in the TUI (#1658).
294
+ - Allow scheduled project roots shared through a registered Git worktree's `.pi` symlink while rejecting unrelated or unproven Git-layout escapes. Thanks to [@sususu98](https://github.com/sususu98) for #1656.
295
+ - Include delegated child usage in subagent tool results and `/subagent-cost`, including completed async workflow children and parent compaction usage with persisted workflow-receipt recovery when needed (#1662, #1666). Thanks to [@Geraldo-Morais](https://github.com/Geraldo-Morais) for #1662 and [@jf88888](https://github.com/jf88888) for #1666.
296
+ - Avoid false preflight mismatch warnings for generated `runs.lanes(...)` stage keys (#1649).
297
+ - Accept long host tool-call ids in workflow child summaries, matching the existing 4,096-byte session id bound. Thanks to [@SudoKillMe](https://github.com/SudoKillMe) for #1653.
298
+ - Keep an async `workflowScript` continuation live while an awaited child coordinates with its supervisor, so later sequential steps still run (#1634).
299
+ - Stop stale extension and slash-command contexts from escaping during reload or session replacement.
300
+ - Include saved workflow child output paths and inline previews in completion notices (#1629).
301
+ - Format million-scale context limits as `1M` instead of `1000k` in live status displays.
302
+ - Restore active workflow children under their workflow parent in Fleet Status after reload, while keeping unmatched shell rows visible.
303
+ - Prefer loaded workspace context over repeated internal workflow keys in async TUI lane rows (#1619).
304
+ - Accept path-like Pi session ids up to 4,096 characters when snapshotting background work. Thanks to [@dvishoot](https://github.com/dvishoot) for #1616.
305
+ - Accept bare leaf model ids reported by provider drivers when verifying provider-qualified launch candidates. Thanks to [@lallenlowe](https://github.com/lallenlowe) for #1609.
306
+ - Resume compaction-induced child aborts once when retained state is safe, and report the exact recovery blocker otherwise.
307
+ - Report aborted or signalled no-output child runs with their terminal stop, stderr, or process signal before missing-output handoff diagnostics.
308
+ - Apply `globalConcurrencyLimit` to `workflowScript` children launched through `runs.run` and `runs.all`, not only legacy multi-child runners. Thanks to [@mateominato](https://github.com/mateominato) for #1600.
309
+ - Ignore nested `.pi` and `sync-backups` directories during agent discovery so stale backup definitions cannot become executable agents. Thanks to [@arlishansenn](https://github.com/arlishansenn) for #1596.
310
+ - Let projects layer agent overrides by the active parent model provider without duplicating agent definitions. Thanks to [@arichiardi](https://github.com/arichiardi) for #1597.
311
+ - Let operators configure the default `subagent_wait` window and report window expiry as non-error active work while preserving strict headless draining. Thanks to [@Shujakuinkuraudo](https://github.com/Shujakuinkuraudo) for #1591.
312
+ - Degrade run status to the stored fan-out budget snapshot when persisted state is unavailable, instead of failing the entire run list. Thanks to [@qsgy-edge](https://github.com/qsgy-edge) for #1595.
313
+ - Enforce MCP server `includeTools` and `excludeTools` policies for child direct-tool grants, including adapter-compatible glob matching. Thanks to [@Shujakuinkuraudo](https://github.com/Shujakuinkuraudo) for #1590.
314
+ - Prevent Fleet prompt audit rendering from crashing on malformed non-string task payloads. Thanks to [@bengidev](https://github.com/bengidev) for #1586.
315
+ - Resume a retained child session once after a provider or transport abort follows useful progress, without restarting the task or involving the parent model.
316
+ - Retry unused fallback models after a provider reports a plain-text `500` or `internal server error`. Thanks to [@rafafortes](https://github.com/rafafortes) for #1642.
317
+ - Mark missing required child handoffs with useful mutation evidence as partial needs-attention results.
318
+
319
+ ## [0.58.0] - 2026-08-27
320
+
321
+ ### Highlights
322
+ - Launch MCP tools from more places, including runtime-registered servers, Pi package manifests, and Agent Plugin configs.
323
+ - Keep agent context smaller by default, with an explicit `inheritGlobalContext` opt-in when a child needs the operator's global context.
324
+ - Make detached and recovered workflow results more reliable, with clearer terminal handoffs and recovery actions.
325
+ - Show better launch and status diagnostics for workspace, authority, context-window, and missing-directory problems.
326
+ - Keep fast OpenAI-Codex launches compatible with priority service tier without losing provider request fields.
327
+
328
+ ### Added
329
+ - Support direct MCP tool launches from runtime-registered servers.
330
+ - Add `inheritGlobalContext` agent configuration so children can opt into the operator's global context file separately from repository context. Thanks to [@hknatm](https://github.com/hknatm) for #1560.
331
+ - Add process-local event registration so independent Pi extensions can register runtime agents through the installed owner. Thanks to [@fmoda3](https://github.com/fmoda3) for #1533.
332
+ - Add advisory launch preflight diagnostics for likely workspace scope and authority mismatches.
333
+ - Document per-run thinking suffixes in model-facing subagent guidance. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #1565.
334
+ - Document unsupported native child options for external CLI agents in the subagent tool help, packaged guide, and packaged skill.
335
+
336
+ ### Changed
337
+ - Agents now omit the operator's global context file by default, including existing agents with `inheritProjectContext: true`; set `inheritGlobalContext: true` to preserve the previous behavior. Thanks to [@hknatm](https://github.com/hknatm) for #1560.
338
+
339
+ ### Fixed
340
+ - Fail explicitly requested models closed when a cached model exclusion is active, instead of silently selecting a fallback. Thanks to [@harpsychord](https://github.com/harpsychord) for #1556.
341
+ - Preserve fast-mode provider request root fields when adding OpenAI's priority service tier. Thanks to [@nothingrotf](https://github.com/nothingrotf) for #1570.
342
+ - Classify workflow budget and timeout stops as partial terminal outcomes while preserving settled child evidence. Thanks to [@yceachan](https://github.com/yceachan) for #1530.
343
+ - Publish a deterministic terminal handoff with settled child evidence and keyed recovery actions when detached workflow lanes settle. Thanks to [@yceachan](https://github.com/yceachan) for #1530.
344
+ - Resolve direct MCP tool selections from Pi package manifests and Agent Plugin configs. Thanks to [@fmoda3](https://github.com/fmoda3) for #1541.
345
+ - Fail closed with a launch diagnostic when configured runtime-style MCP direct-tool selectors cannot be resolved.
346
+ - Sync Herdr status after restoring active async jobs, so recovered work appears without waiting for another lifecycle event. Thanks to [@vicocamacho](https://github.com/vicocamacho) for #1553.
347
+ - Show task intent and context-window use in compact in-progress async status rows.
348
+ - Report deterministic settlement diagnostics when background children fail before required output handoff.
349
+ - Auto-resume workflow children once after setup-phase aborts that produce zero usage, preserving the retained transcript instead of rerunning the whole task.
350
+ - Finalize detached foreground worktree handoffs after terminal child completion, preserving captured changes before cleanup. Thanks to [@jpriverar](https://github.com/jpriverar) for #1562.
351
+ - Fail native child launches before spawn when the requested local working directory is missing or not a directory, with the requested and resolved paths in the error.
352
+ - Map report paths requested in workflow child tasks to the actual saved child output when workflow output routing overrides them.
353
+ - Stop same-session workflows recovered after extension reload through the durable control channel.
354
+ - Let agents declare extension mutation tools so real non-Git or untracked edits satisfy the implementation completion guard. Thanks to [@AlphaGodzilla](https://github.com/AlphaGodzilla) for #1532.
355
+ - Deliver async results from an explicitly replaced predecessor session without accepting unrelated session results. Thanks to [@DresvyanskiyDenis](https://github.com/DresvyanskiyDenis) for #1531.
356
+ - Avoid attributing assistant-issued workflow stops to the user.
357
+
358
+ ## [0.57.0] - 2026-08-26
359
+
360
+ ### Highlights
361
+ - Run Codex, Claude Code, and Cursor Agent subagents with packaged read-only and writing profiles.
362
+ - Validate workflow scripts before launch, and reuse workflow code from files with `workflowScriptPath`.
363
+ - Resume, inspect, and recover workflow children more reliably after errors, compaction, or session reloads.
364
+ - See clearer Fleet and status output, including task labels and live context-window usage.
365
+ - Recover from more async, scheduling, discovery, model fallback, and Windows edge cases without losing useful run history.
366
+
367
+ ### Added
368
+ - Add read-only and workspace-writing profiles for `codex-exec`, `claude-code`, and `cursor-agent`, with bounded result capture and opt-in smoke checks.
369
+ - Add external one-shot runner support for bounded parser hooks and logs, environment allowlists, cached launch preflight, parser progress, and process cleanup.
370
+ - Add compact external CLI capability and receipt metadata for adapter identity, artifacts, handoff mode, supervisor support, and resumability.
371
+ - Add configured pruned fork sessions with budgeted transcript-overflow summaries, stable recovery refs, and private recovery sidecars.
372
+ - Add offline `workflowScript` syntax and structural validation through the public subagent tool. Thanks to [@elecnix](https://github.com/elecnix) for #1462.
373
+ - Add `workflowScriptPath` so workflows can be loaded from files for execution, validation, and schedules. Thanks to [@elecnix](https://github.com/elecnix) for #1464.
374
+ - Add bounded workflow-child summaries to workflow results, status, receipts, and completion replay. Thanks to [@rochecompaan](https://github.com/rochecompaan) for #1453.
375
+ - Add live context-window usage to status and Fleet views, separate from cumulative token spend. Thanks to [@nazzeDe](https://github.com/nazzeDe) for #1444.
376
+ - Add active workflow task labels to compact status surfaces and Herdr pane metadata. Thanks to [@phoenixdam](https://github.com/phoenixdam) for #1459.
377
+ - Add `modelExclusions.defaultTtlMs` for controlling how long model exclusions stay active, with launch diagnostics for skipped candidates. Thanks to [@mithyer](https://github.com/mithyer) for #1439 and #1438.
378
+ - Add a package-internal one-use permit for one exact native child in a foreground `workflowScript`. Thanks to [@maroffo](https://github.com/maroffo) for #1494.
379
+
380
+ ### Fixed
381
+ - Preserve agent frontmatter output defaults for prompt-template delegated leaves. Thanks to [@ashlineldridge](https://github.com/ashlineldridge) for #1521.
382
+ - Preserve structured-output and related bounded child contract fields when foreground workflow children resume. Thanks to [@Livan-pro](https://github.com/Livan-pro) for #1460.
383
+ - Preserve typed errors, partial output, transcript metadata, and artifact metadata when foreground workflow children resume. See #1513.
384
+ - Keep inline workflow children resumable from their foreground runs without mistaking a missing async directory for lost state. Thanks to [@lancegui](https://github.com/lancegui) for #1442.
385
+ - Make workflow validation and return serialization failures easier to recover from with no-child-launch diagnostics, portable rewrite guidance, workflow ids, and completed-child output references (#1432, #1434).
386
+ - Clarify terminal keyed workflow-resume failures when `workflow-receipt.json` is unavailable, including direct child-run recovery from status and event logs (#1512).
387
+ - Preserve bounded async child failure context after compaction, including missing file-only output, instead of leaving failed run summaries empty. See #1495.
388
+ - Ignore stale child-settled events from retrying compaction attempts, so resumed children are not aborted before their replacement attempt can finish. See #1504.
389
+ - Make async runs visible to exact status lookup as soon as launch succeeds, and deliver one completion when a runner dies before its normal status write. Thanks to [@rafafortes](https://github.com/rafafortes) for #1471 and [@VincentHanxiaoDu](https://github.com/VincentHanxiaoDu) for #1480.
390
+ - Record explicit completed, failed, timed-out, stopped, and interrupted outcomes in run history. Thanks to [@rafafortes](https://github.com/rafafortes) for #1474.
391
+ - Repair bounded dead async run candidates before retention classifies them, so stale run directories can be reclaimed without deleting ambiguous worktrees or branches. Thanks to [@rafafortes](https://github.com/rafafortes) for #1477.
392
+ - Exclude completed one-shot schedules from the pending schedule limit without deleting their durable history. Thanks to [@rafafortes](https://github.com/rafafortes) for #1478.
393
+ - Reclaim failed async capacity slots after a configurable abandoned timeout when the runner PID is gone, while keeping clear diagnostics for unknown process state. Thanks to [@rafafortes](https://github.com/rafafortes) for #1472.
394
+ - Preserve parent model inheritance for workflow children when workflow setup reads session data before launch, and avoid carrying a stale live-session model into scheduled owners. Thanks to [@alexei-led](https://github.com/alexei-led) for #1489 and #1490.
395
+ - Retry fallback models for transient provider connection failures. Thanks to [@genkikadomatsu](https://github.com/genkikadomatsu) for #1508.
396
+ - Resolve the `advisor` builtin alias through the bundled `oracle` definition in model listings. Thanks to [@smileBeda](https://github.com/smileBeda) for #1502.
397
+ - Follow symlinked directories during agent discovery without revisiting recursive links. Thanks to [@robsdudeson](https://github.com/robsdudeson) for #1505 and #1510.
398
+ - Explain unknown-agent failures with the effective cwd and discovery inputs. Thanks to [@genkikadomatsu](https://github.com/genkikadomatsu) for #1511.
399
+ - Resolve package subagents from bare HTTP(S) Git URLs stored in Pi settings. Thanks to [@trancikk](https://github.com/trancikk) for #1452.
400
+ - Preview runtime-recorded workflow child sessions in Fleet and inspect without trusting sibling transcripts. Thanks to [@JHa13y](https://github.com/JHa13y) for #1441.
401
+ - Distinguish same-agent parallel children in Fleet with their explicit task labels. Thanks to [@ljie-PI](https://github.com/ljie-PI) for #1487.
402
+ - Preserve the local user identity and temporary-directory environment needed by authenticated Claude Code adapter runs.
403
+ - Report child processes that exit during tool execution as mid-tool failures instead of cold starts, even when earlier assistant text exists. Thanks to [@cyzlmh](https://github.com/cyzlmh) for #1437.
404
+ - Keep unaddressable legacy result aliases and overlong public result filenames from blocking canonical hashed or pending fallbacks. Thanks to [@LeonardBode](https://github.com/LeonardBode) for #1440.
405
+ - Bypass repository fsmonitor hooks when collecting mutation evidence. Thanks to [@jpriverar](https://github.com/jpriverar) for #1497.
406
+ - Avoid the fatal Node `ReadFileUtf8` retention path. Thanks to [@pgoodjohn](https://github.com/pgoodjohn) for #1501.
407
+ - Base64-encode Herdr inspector session roots so `inspector.open` handles Windows PowerShell argument parsing correctly. Thanks to [@stavg91](https://github.com/stavg91) for #1499.
408
+ - Keep async runner terminal event delivery from crashing the session when the captured extension context is stale after a session replacement or reload. Thanks to [@AdrianAcala](https://github.com/AdrianAcala) for #1485.
409
+ - Reject non-string workflow-child summary identifiers when reading receipt metadata.
410
+
411
+ ## [0.56.0] - 2026-08-23
412
+
413
+ ### Highlights
414
+ - Run allowlisted OpenAI-Codex subagents with opt-in `fast` mode when you want priority service tier.
415
+ - Pass bounded extension metadata into native child launches without leaking that authority to external runners.
416
+ - Workflow scripts are easier to read when child results are stringified or returned.
417
+ - Completion guards now use safer tracked-file evidence, including large dirty files and interrupted runs.
418
+ - Model verification is less fragile for provider-qualified and variant-tagged model ids.
419
+
420
+ ### Added
421
+ - Add opt-in `fast: true` launches for allowlisted native OpenAI-Codex subagents, using OpenAI's priority service tier.
422
+ - Add bounded namespaced extension bindings to child launch contracts. Thanks to [@FL03](https://github.com/FL03) for #1410.
423
+
424
+ ### Fixed
425
+ - Render workflow child results as useful text when scripts stringify `runs.all` or awaited `runs.run` result objects.
426
+ - Keep checked acceptance compatible with strict workflow child `outputSchema` results. Thanks to [@rtbe](https://github.com/rtbe) for #1406.
427
+ - Use bounded tracked-file mutation evidence for implementation completion guards, including files that were already dirty when the child started. Thanks to [@rtbe](https://github.com/rtbe) for #1407.
428
+ - Bind fast mode into launch contract provenance and keep large tracked-file mutation evidence precise.
429
+ - Add timeout recovery summaries with changed tracked files, active child state, and session/artifact paths. Thanks to [@rtbe](https://github.com/rtbe) for #1409.
430
+ - Fail closed when reviewer runs are interrupted or detached workflow children settle without persisted top-level continuation proof. Thanks to [@rtbe](https://github.com/rtbe) for #1408.
431
+ - Stop flagging awaited `.then()` workflow chains as unawaited when a handler returns another child launch.
432
+ - Preserve variant-tagged model ids during verification and fallback exclusion parsing. Thanks to [@rafafortes](https://github.com/rafafortes) for #1420.
433
+
434
+ ## [0.55.0] - 2026-08-23
435
+
436
+ ### Highlights
437
+ - Stop a single stuck child in an async workflow without stopping the whole run.
438
+ - Continue finished external jobs, like `gpt-pro` from [Surf](https://github.com/nicobailon/surf-cli/), with follow-up requests through `resume`.
439
+ - Cap child thinking with `subagents.maxThinking` and set a preferred default provider for bare model ids.
440
+ - Scripted workflow outputs now land in the run's managed artifact directory instead of the repository root.
441
+ - Child launches fail fast with clear reasons when requested models or write tools are unavailable.
442
+
443
+ ### Added
444
+ - Add `subagents.maxThinking` to enforce a thinking ceiling across native subagent launches. Thanks to [@alex-real14](https://github.com/alex-real14) for #1397.
445
+ - Add `subagents.defaultProvider` and per-agent `defaultProvider` overrides so bare subagent model ids can prefer a configured provider. Thanks to [@swingtempo](https://github.com/swingtempo) for #1393.
446
+ - Add external-job follow-ups through `subagent({ action: "resume" })` for completed provider jobs that expose `followUp(input)`, with duplicate request dedupe, durable parent-job lineage (#1381), and clearer errors when a follow-up cannot start.
447
+ - Add child-scoped stop support and child stop observer events for async/workflow runs. Malformed child stop requests are rejected instead of widening to a run-level stop. Thanks to [@yanqianglu](https://github.com/yanqianglu) for #1367.
448
+ - Create one passive Orca observer tab per top-level subagent call, with shared chain/parallel progress and project-local observer manifests. Thanks to [@hyein-cbio](https://github.com/hyein-cbio) for #1360.
449
+ - Count Herdr project panes in inline status and report compact Herdr pane title suffixes for active subagent work.
450
+ - Let `agentOverrides` set or clear default `output` paths and `defaultReads`, while preserving explicit custom-agent frontmatter and preventing settings-derived values from being serialized into custom definitions. Thanks to [@mevatron](https://github.com/mevatron) for #1349.
451
+ - Surface copyable `provider/id` model selectors from `{ action: "models" }` and point invalid model warnings at that discovery path. Thanks to [@lixinglong27](https://github.com/lixinglong27) for #1365.
452
+ - Add bundled skill guidance for lightweight task profiles before subagent fanout. Thanks to [@srcKod](https://github.com/srcKod) for #1395.
453
+ - Add delegated review guidance that separates evidence requirements from severity labels so first-pass reviews do not default to `blockers only`.
454
+
455
+ ### Fixed
456
+ - Route relative `workflowScript` output paths through managed artifacts instead of creating report files in the repository root.
457
+ - Keep the async widget spinner and elapsed timer moving while the parent is idle by routing animation ticks through the live widget rebuild path. Thanks to [@0xFlo](https://github.com/0xFlo) for #1390.
458
+ - Slow async widget animation rerenders to 1 Hz so quiet running jobs do not repaint the full TUI at the liveness tick rate. Thanks to [@0xFlo](https://github.com/0xFlo) for #1376.
459
+ - Fail a Pi child launch when the child reports a different provider/model than the resolved requested model. Thanks to [@zzzubair](https://github.com/zzzubair) for #1377.
460
+ - Render detached workflow supervisor handoffs as paused/waiting and include workflow and child run ids in completion notifications.
461
+ - Report implementation runs blocked by missing child tools as blocked mutation effects instead of no-edit completion guard failures.
462
+ - Fail child launch attempts when the runtime lacks requested core write tools or an implementation worker has only read-only launch tools, including workflow children that inherit a read-only capability ceiling.
463
+ - Let read-only reviewer acceptance rely on the parent-side staged-file check instead of requiring child-reported `noStagedFiles` evidence.
464
+ - Run public single-child launches directly instead of wrapping them in a workflow, so async external-job agents do not show a completed workflow before the real provider job finishes.
465
+ - Start omitted-`async` public external-runner single-child launches in the supported background mode, so package agents such as `gpt-pro` from [Surf](https://github.com/nicobailon/surf-cli/) do not fail as foreground requests.
466
+ - Let workflow scripts await omitted-`async` external-runner children by launching them in the background internally and returning their terminal result.
467
+ - Report helpful workflow errors when `runs.all(...)` results are read as keyed objects instead of ordered arrays. Thanks to [@ravshansbox](https://github.com/ravshansbox) for #1351.
468
+ - Clarify that Council Mode can include installed external-runner advisors such as `gpt-pro` from [Surf](https://github.com/nicobailon/surf-cli/) when the `surf-cli` Pi extension has registered `surf-oracle`, with text JSON reports instead of `outputSchema`.
469
+
470
+ ## [0.54.0] - 2026-08-21
471
+
472
+ ### Highlights
473
+ - Subagent model selection is more precise with per-agent restrictions and an `inherit` shortcut for the current parent model.
474
+ - Package agents are easier to discover because list and detail output now shows where they come from and whether their external provider is ready.
475
+ - Workflow runs are less fragile: tool-result backfill, context-overflow handling, resumed children, and permission asks now behave more predictably.
476
+ - Child launches are lighter and safer because subagent processes avoid loading the parent extension graph and avoid unnecessary permission bridge setup.
477
+ - Council Mode is easier to use from natural language and no longer requires invented advisor role labels.
478
+
479
+ ### Added
480
+ - Add per-agent model restrictions and a current-parent `inherit` allow-list alias. Thanks to [@hieudmg](https://github.com/hieudmg) for #1328.
481
+
5
482
  ## [0.8.0] - 2026-08-24 (fork release)
6
483
 
7
484
  ### Changed
package/README.md CHANGED
@@ -14,7 +14,7 @@
14
14
  pi install npm:@xzzpig/pi-subagents
15
15
  ```
16
16
 
17
- That is the only required step.
17
+ That is the only required step. Background children require pi installed as the npm package (`@earendil-works/pi-coding-agent`): the detached runner imports pi's packages from that package directory. A standalone single-file pi binary has no package directory and cannot run background children; foreground children (`async: false`) still work there.
18
18
 
19
19
  ## Try this first
20
20
 
@@ -42,7 +42,7 @@ That is enough to start. Pi decides whether to call the `subagent` tool, which a
42
42
 
43
43
  Pi is the parent session. A subagent is a focused child Pi session with its own job.
44
44
 
45
- When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation. Background runs keep working and can be checked later.
45
+ When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground children run as sessions inside the parent Pi process and stream in the conversation. Background children run as sessions inside a detached runner process that keeps working and can be checked later.
46
46
 
47
47
  Installing the extension does not start an automatic reviewer in the background. It gives Pi a delegation tool. If you want every implementation reviewed, say so in your prompt or project instructions:
48
48
 
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: claude-code-writer
3
+ description: Explicit file-writing Claude Code CLI mode; requires local authentication and trusted user settings/hooks
4
+ runner:
5
+ type: external-cli
6
+ adapter: claude-code-writer
7
+ command: claude
8
+ promptDelivery: stdin
9
+ async: true
10
+ systemPromptMode: replace
11
+ inheritProjectContext: true
12
+ inheritSkills: false
13
+ ---
14
+
15
+ Prerequisites: the local Claude Code CLI is authenticated, and the operator trusts its user-level settings and hooks. Use only the code-owned Read, Write, Edit, Glob, and Grep tools. Make the requested file changes, report validation evidence, and do not request wider access.
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: claude-code
3
+ description: Read-only Claude Code CLI analysis; requires local authentication and trusted user settings/hooks
4
+ runner:
5
+ type: external-cli
6
+ adapter: claude-code
7
+ command: claude
8
+ promptDelivery: stdin
9
+ async: true
10
+ systemPromptMode: replace
11
+ inheritProjectContext: true
12
+ inheritSkills: false
13
+ ---
14
+
15
+ Prerequisites: the local Claude Code CLI is authenticated, and the operator trusts its user-level settings and hooks. Analyze only the supplied handoff in no-tools mode. Return a concise final answer with evidence. Do not edit files or request wider access.
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: codex-exec-writer
3
+ description: Explicit workspace-writing one-shot execution through the installed Codex CLI
4
+ runner:
5
+ type: external-cli
6
+ adapter: codex-exec-writer
7
+ command: codex
8
+ promptDelivery: stdin
9
+ async: true
10
+ systemPromptMode: replace
11
+ inheritProjectContext: true
12
+ inheritSkills: false
13
+ ---
14
+
15
+ Use the code-owned workspace-write sandbox to make the requested changes. Return a concise final answer with validation evidence. Do not request wider access or additional writable roots.
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: codex-exec
3
+ description: Read-only one-shot analysis through the installed Codex CLI
4
+ runner:
5
+ type: external-cli
6
+ adapter: codex-exec
7
+ command: codex
8
+ promptDelivery: stdin
9
+ async: true
10
+ systemPromptMode: replace
11
+ inheritProjectContext: true
12
+ inheritSkills: false
13
+ ---
14
+
15
+ Analyze the task in read-only mode. Return a concise final answer with evidence. Do not edit files or request wider access.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: cursor-agent-writer
3
+ description: Explicit workspace-writing one-shot execution through the installed Cursor CLI
4
+ runner:
5
+ type: external-cli
6
+ adapter: cursor-agent-writer
7
+ command: cursor-agent
8
+ async: true
9
+ systemPromptMode: replace
10
+ inheritProjectContext: true
11
+ inheritSkills: false
12
+ ---
13
+
14
+ Use the code-owned sandbox to make the requested workspace changes. Return a concise final answer with validation evidence. Do not request wider access or additional workspace roots.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: cursor-agent
3
+ description: Read-only one-shot analysis through the installed Cursor CLI
4
+ runner:
5
+ type: external-cli
6
+ adapter: cursor-agent
7
+ command: cursor-agent
8
+ async: true
9
+ systemPromptMode: replace
10
+ inheritProjectContext: true
11
+ inheritSkills: false
12
+ ---
13
+
14
+ Analyze the task in read-only ask mode. Return a concise final answer with evidence. Do not edit files or request wider access.