@xzzpig/pi-subagents 0.14.0 → 0.15.1

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 (206) hide show
  1. package/CHANGELOG.md +239 -0
  2. package/README.md +7 -6
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +55 -136
  7. package/docs/configuration.md +92 -14
  8. package/docs/extension-api.md +132 -74
  9. package/docs/fork-extensions.md +184 -0
  10. package/docs/missions.md +10 -2
  11. package/docs/models.md +11 -22
  12. package/docs/observability.md +63 -11
  13. package/docs/standalone-background.md +59 -0
  14. package/docs/tool-reference.md +42 -23
  15. package/docs/watchdog.md +39 -10
  16. package/docs/workflows.md +58 -19
  17. package/index.ts +5 -2
  18. package/inspector-runner.mjs +2 -2
  19. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
  20. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
  21. package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
  22. package/package.json +9 -4
  23. package/prompts/parallel-review.md +1 -1
  24. package/runner-peer-loader.mjs +24 -0
  25. package/runner-peer-preload.mjs +36 -0
  26. package/skills/pi-subagents/SKILL.md +34 -22
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  28. package/skills/pi-subagents/references/execution-controls.md +27 -8
  29. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  30. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  31. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  32. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  33. package/src/agents/advertised-agent-prompt.ts +94 -0
  34. package/src/agents/agent-eject.ts +339 -0
  35. package/src/agents/agent-management.ts +79 -387
  36. package/src/agents/agent-serializer.ts +6 -3
  37. package/src/agents/agents.ts +198 -72
  38. package/src/agents/builtin-names.ts +1 -0
  39. package/src/agents/chain-serializer.ts +5 -0
  40. package/src/agents/runtime-agent-registry.ts +7 -6
  41. package/src/api/agent-management.ts +2 -2
  42. package/src/api/delegation.ts +4 -0
  43. package/src/api/preflight.ts +131 -86
  44. package/src/api/required-child-extensions.ts +6 -0
  45. package/src/api/shared-types.ts +3 -1
  46. package/src/api/workflow-resources.ts +6 -0
  47. package/src/extension/config.ts +14 -37
  48. package/src/extension/fanout-child.ts +68 -5
  49. package/src/extension/herdr-pi-bridge.ts +164 -0
  50. package/src/extension/index.ts +141 -51
  51. package/src/extension/public-execution.ts +7 -6
  52. package/src/extension/rpc.ts +8 -21
  53. package/src/extension/schemas.ts +86 -84
  54. package/src/extension/tool-description.ts +32 -79
  55. package/src/inspectors/actions.ts +148 -0
  56. package/src/inspectors/ghostty/actions.ts +74 -0
  57. package/src/inspectors/ghostty/plugin.ts +17 -0
  58. package/src/inspectors/herdr/actions.ts +99 -179
  59. package/src/inspectors/herdr/plugin.ts +20 -0
  60. package/src/inspectors/herdr/project-panes.ts +4 -1
  61. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  62. package/src/inspectors/plugins.ts +8 -0
  63. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  64. package/src/inspectors/types.ts +51 -0
  65. package/src/integrations/pi-web-session-liveness.ts +73 -0
  66. package/src/intercom/intercom-bridge.ts +50 -8
  67. package/src/intercom/native-supervisor-channel.ts +142 -115
  68. package/src/intercom/supervisor-ui.ts +3 -2
  69. package/src/missions/workflow-state.ts +37 -16
  70. package/src/policy/authority.ts +4 -0
  71. package/src/profiles/profiles.ts +12 -6
  72. package/src/runs/background/active-async-capacity.ts +22 -18
  73. package/src/runs/background/active-run-index.ts +17 -1
  74. package/src/runs/background/async-execution.ts +359 -176
  75. package/src/runs/background/async-job-tracker.ts +41 -7
  76. package/src/runs/background/async-resume.ts +19 -12
  77. package/src/runs/background/async-retention.ts +20 -0
  78. package/src/runs/background/async-status-snapshot.ts +10 -12
  79. package/src/runs/background/async-status.ts +38 -35
  80. package/src/runs/background/auto-drain.ts +59 -35
  81. package/src/runs/background/binary-bootstrap.ts +38 -0
  82. package/src/runs/background/chain-append.ts +1 -1
  83. package/src/runs/background/chain-root-attachment.ts +22 -33
  84. package/src/runs/background/control-channel.ts +78 -44
  85. package/src/runs/background/fleet-view.ts +30 -2
  86. package/src/runs/background/notify.ts +193 -19
  87. package/src/runs/background/owned-process-tree.ts +35 -8
  88. package/src/runs/background/process-terminal.ts +23 -23
  89. package/src/runs/background/result-files.ts +8 -4
  90. package/src/runs/background/result-watcher.ts +19 -2
  91. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  92. package/src/runs/background/run-child-session.ts +118 -41
  93. package/src/runs/background/run-status.ts +78 -5
  94. package/src/runs/background/runner-aliases.ts +22 -5
  95. package/src/runs/background/runner-child-launch.ts +93 -0
  96. package/src/runs/background/runner-child-sessions.ts +5 -4
  97. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  98. package/src/runs/background/scheduled-runs.ts +51 -18
  99. package/src/runs/background/stale-run-reconciler.ts +38 -12
  100. package/src/runs/background/steering.ts +20 -2
  101. package/src/runs/background/subagent-runner.ts +770 -444
  102. package/src/runs/background/subagent-wait.ts +179 -28
  103. package/src/runs/background/wait-completions.ts +79 -27
  104. package/src/runs/background/wait-subscriptions.ts +9 -3
  105. package/src/runs/background/wait-tool.ts +5 -3
  106. package/src/runs/foreground/async-steering-action.ts +37 -7
  107. package/src/runs/foreground/async-stop-action.ts +93 -3
  108. package/src/runs/foreground/execution.ts +174 -194
  109. package/src/runs/foreground/foreground-history.ts +5 -2
  110. package/src/runs/foreground/prompt-audit.ts +12 -6
  111. package/src/runs/foreground/subagent-executor.ts +915 -411
  112. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  113. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  114. package/src/runs/shared/acceptance.ts +54 -14
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +172 -78
  117. package/src/runs/shared/capability-ceiling.ts +2 -0
  118. package/src/runs/shared/child-hooks.ts +167 -3
  119. package/src/runs/shared/child-launch-plan.ts +15 -3
  120. package/src/runs/shared/child-launch.ts +49 -85
  121. package/src/runs/shared/child-lifecycle.ts +6 -3
  122. package/src/runs/shared/child-runtime-config.ts +8 -1
  123. package/src/runs/shared/child-session.ts +130 -24
  124. package/src/runs/shared/child-tool-plan.ts +149 -112
  125. package/src/runs/shared/completion-evidence.ts +2 -2
  126. package/src/runs/shared/completion-guard.ts +6 -3
  127. package/src/runs/shared/dynamic-fanout.ts +2 -2
  128. package/src/runs/shared/effective-system-prompt.ts +33 -0
  129. package/src/runs/shared/external-cli-contract.ts +11 -1
  130. package/src/runs/shared/external-cli-preflight.ts +6 -2
  131. package/src/runs/shared/external-cli-runner.ts +9 -7
  132. package/src/runs/shared/herdr-connection.ts +134 -0
  133. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  134. package/src/runs/shared/herdr-machine.ts +279 -0
  135. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  136. package/src/runs/shared/herdr-placed-run.ts +263 -0
  137. package/src/runs/shared/host-step-status.ts +11 -11
  138. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  139. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  140. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  141. package/src/runs/shared/model-scope.ts +1 -1
  142. package/src/runs/shared/nested-events.ts +27 -34
  143. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  144. package/src/runs/shared/parallel-handoff.ts +57 -12
  145. package/src/runs/shared/parallel-utils.ts +10 -4
  146. package/src/runs/shared/pi-spawn.ts +10 -0
  147. package/src/runs/shared/profile-extensions.ts +134 -0
  148. package/src/runs/shared/profile-launch-env.ts +113 -0
  149. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  150. package/src/runs/shared/run-fanout-budget.ts +8 -8
  151. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  152. package/src/runs/shared/sandbox-profile-guard.ts +34 -0
  153. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  154. package/src/runs/shared/task-intent.ts +46 -13
  155. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  156. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  157. package/src/runs/shared/worktree-setup-command.ts +213 -0
  158. package/src/runs/shared/worktree.ts +437 -214
  159. package/src/shared/child-cache-retention.ts +43 -0
  160. package/src/shared/fork-context.ts +15 -72
  161. package/src/shared/launch-contract.ts +70 -8
  162. package/src/shared/model-response-aliases.ts +13 -0
  163. package/src/shared/opencode-session-headers.ts +30 -0
  164. package/src/shared/permission-profile.ts +14 -0
  165. package/src/shared/pruned-fork.ts +1 -1
  166. package/src/shared/required-child-extensions.ts +81 -0
  167. package/src/shared/sandbox-profile.ts +14 -0
  168. package/src/shared/settings.ts +5 -2
  169. package/src/shared/shortcuts.ts +0 -4
  170. package/src/shared/types.ts +163 -90
  171. package/src/shared/utils.ts +10 -2
  172. package/src/shared/watch-strategy.ts +2 -0
  173. package/src/shared/workflow-child-permit.ts +18 -13
  174. package/src/slash/delegation-adapters.ts +3 -1
  175. package/src/slash/delegation-request.ts +14 -0
  176. package/src/slash/slash-commands.ts +2 -7
  177. package/src/slash/subagents-admin.ts +31 -14
  178. package/src/tui/fleet-status.ts +165 -20
  179. package/src/tui/fleet.ts +30 -19
  180. package/src/tui/render.ts +210 -50
  181. package/src/watchdog/child-status.ts +28 -28
  182. package/src/watchdog/lsp-diagnostics.ts +1 -1
  183. package/src/watchdog/model-selection.ts +21 -1
  184. package/src/watchdog/permission-arbiter.ts +5 -2
  185. package/src/watchdog/register-child.ts +10 -2
  186. package/src/watchdog/register-main.ts +39 -35
  187. package/src/watchdog/render.ts +1 -1
  188. package/src/watchdog/review.ts +122 -74
  189. package/src/watchdog/rules.ts +1 -1
  190. package/src/watchdog/runtime.ts +100 -27
  191. package/src/watchdog/scope.ts +1 -1
  192. package/src/watchdog/settings.ts +3 -0
  193. package/src/watchdog/tool-actions.ts +13 -12
  194. package/src/watchdog/turn-delta.ts +23 -0
  195. package/src/watchdog/types.ts +5 -3
  196. package/src/watchdog/warning-format.ts +1 -1
  197. package/src/workflows/chat-progress.ts +3 -3
  198. package/src/workflows/scripted-workflow.ts +349 -26
  199. package/src/workflows/workflow-checklist.ts +17 -20
  200. package/src/workflows/workflow-child-summary.ts +57 -8
  201. package/src/workflows/workflow-preflight.ts +19 -19
  202. package/src/workflows/workflow-receipt.ts +24 -6
  203. package/src/workflows/workflow-resources.ts +108 -22
  204. package/src/workflows/workflow-settlement.ts +3 -0
  205. package/src/runs/shared/model-exclusions.ts +0 -373
  206. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
package/docs/workflows.md CHANGED
@@ -19,6 +19,14 @@ Child-safety boundaries are enforced at runtime:
19
19
  - By default, children do not register the `subagent` tool and receive boundary instructions that they are not the parent orchestrator and must not propose or run subagents.
20
20
  - The explicit exception is an agent whose resolved builtin `tools` includes `subagent`; that child gets a child-safe `subagent` tool for the fanout work the parent assigned, still bounded by `maxSubagentDepth`.
21
21
 
22
+ ### Failed lane recovery and execution-mode boundaries
23
+
24
+ A failure in the subagent workflow, child launch, prompt runtime, extension loading, or child tooling setup is a lane infrastructure blocker. It is not permission to silently retry through `interactive_shell`, `pi -ne`, Codex/Claude/Cursor CLI, a foreground agent, or another external execution mode.
25
+
26
+ Stop and report the exact failure, run/status, and repository/cwd/worktree/branch/ref state. Before a same-protocol retry or asking the owner, verify the worktree is clean or capture the partial diff. Retry or fix the `subagent` path only through a clear same-protocol action. For backlog lanes and other subagent-governed workflows, external/foreground/CLI fallback requires explicit owner approval. `interactive_shell` remains valid when the user explicitly requests visible foreground/CLI work or the task is outside the governed subagent protocol.
27
+
28
+ Pi core may print a generic `pi -ne` extension-load hint; that out-of-repo hint is not protocol-approved fallback. A verified compaction abort may continue the retained child once on its already resolved model; it does not authorize an execution-mode or model switch.
29
+
22
30
  ## Prompt shortcuts
23
31
 
24
32
  The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
@@ -37,6 +45,10 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
37
45
 
38
46
  Use direct `{ agent, task }` for one bounded child. Use `workflowScript` when the parent needs a stable keyed child, sequence, fanout, steering, retry, or aggregation. For ordinary parallel fanout, use `await runs.all([{ key, agent, task }, ...])`. It resolves to an ordered array, not a key map, so use indexes, destructuring, or `.map(...)`, not `results.<key>`. Do not read `.output` from unawaited `runs.run` launches. Store a `runs.run` promise only when the script later observes it with `await`, `Promise.race`, or `Promise.all`, such as steering a live child before awaiting its result. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
39
47
 
48
+ For multi-step or parallel work, make exactly one top-level `subagent` workflow call with `async:true` and launch children only inside it. Read this guide for recipes rather than constructing a second top-level orchestration. Available sandbox helpers include `runs.run`, `runs.all`, `runs.lanes`, `runs.steer`, `runs.status`, `runs.ref`/`runs.refs`, `emit`, `console`, standard JavaScript, and mission `state` when enabled. No filesystem, shell, arbitrary Pi tools, or host globals are available; named resources alone may grant `runs.host` authority.
49
+
50
+ Workflow-level child controls default onto each `runs.run`/`runs.all` launch; explicit child fields override them. See [retained children](tool-reference.md#retained-children) for follow-up challenges, [output binding](tool-reference.md#output-mode-details) for durable artifacts, and [schedules](missions.md#schedules) for delayed/recurring scripts.
51
+
40
52
  Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
41
53
 
42
54
  Validate a script without launching children:
@@ -57,6 +69,16 @@ subagent({ action: "validate", workflowScriptPath: "workflows/review.js" });
57
69
 
58
70
  The fields are mutually exclusive. Relative paths resolve against the request `cwd`; absolute paths pass through. The host reads the file before validation, schedule creation, or workflow sandbox execution. The sandbox still has no filesystem access. Missing, unreadable, and empty files return file input errors instead of script syntax errors.
59
71
 
72
+ Inline and file-backed scripts accept bounded plain-JSON `args`:
73
+
74
+ ```js
75
+ subagent({ workflowScriptPath: "workflows/review.js", args: { target: "src/workflows" } });
76
+ // workflows/review.js
77
+ return runs.run("review", { agent: "reviewer", task: `Review ${args.target}` });
78
+ ```
79
+
80
+ Omitted arguments are an empty object. The `args` object, its nested objects, and its arrays are frozen in the sandbox. Arguments are data only: they do not grant `runs.host` or other authority. Normalized arguments are persisted with workflow and schedule evidence for replay and diagnosis, so do not put secrets in them. Routine status text does not render argument values.
81
+
60
82
  ### Named workflow resources for permission extensions
61
83
 
62
84
  Use a named workflow resource when a permission or policy extension needs to distinguish extension-resolved workflow content from raw model-authored scripts:
@@ -88,17 +110,18 @@ subagent({
88
110
  - `toolBudget` becomes the default for each child unless that child supplies a narrower value.
89
111
  - `usageBudget` accounts for reported usage across completed workflow children. Once exhausted, it rejects later child launches but does not stop children that are already running.
90
112
  - Budget and timeout stops return a structured `terminalOutcome` with `state: "partial"` and reason `budget_exhausted` or `timeout`. Workflow receipts keep settled child evidence for recovery.
113
+ - After an async workflow receipt is successfully published, `workflowReceiptPath` exposes its exact path in wait completion details, completion notifications, and exact status/debug details. Text responses also identify the receipt. Pending runs and failed receipt publications omit the reference; older status records are not backfilled. The reference records publication, not a guarantee against later retention cleanup. Raw result files retain `workflowReceipt: { path, receipt }`.
91
114
 
92
115
  These controls are opt-in. Avoid tight hard budgets for mutation-capable workers unless the workflow has an explicit checkpoint and handoff path.
93
116
 
94
- The result is `{ ok, errors }`. Invalid scripts return a tool error and include line and column data when available. Validation checks syntax, portable nested-async rules, literal `runs.run` and `runs.all` keys, duplicate literal keys in one `runs.all` group, direct keyed access to a known `runs.all` result, and statically clear non-JSON boundary values. Dynamic keys and other runtime-only values are accepted without a warning. Validation does not discover agents, launch children, or create run artifacts.
117
+ The result is `{ ok, errors }`. Invalid scripts return a tool error and include line and column data when available. Validation checks syntax, portable nested-async rules, literal `runs.run` and `runs.all` keys and child `baseRef` values, duplicate literal keys in one `runs.all` group, direct keyed access to a known `runs.all` result, and statically clear non-JSON boundary values. Dynamic keys and other runtime-only values are accepted without a warning. Validation does not discover agents, launch children, or create run artifacts.
95
118
 
96
119
  ```js
97
120
  subagent({ workflowScript: `
98
- const scan = await runs.run("scan", { agent: "scout", task: "Scan the codebase" });
121
+ const scan = await runs.run("scan", { label: "Map codebase behavior", agent: "scout", task: "Scan the codebase" });
99
122
  const reviews = await runs.all([
100
- { key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
101
- { key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
123
+ { key: "correctness", label: "Review codebase correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
124
+ { key: "tests", label: "Review test coverage", agent: "reviewer", task: "Review tests: " + scan.output }
102
125
  ]);
103
126
  return reviews.map(result => result.output);
104
127
  ` });
@@ -109,7 +132,7 @@ Keep helper functions portable across Node and Bun. Use top-level `await`, plain
109
132
  ```js
110
133
  subagent({ workflowScript: `
111
134
  function scan() {
112
- return runs.run("scan", { agent: "scout", task: "Scan the codebase" });
135
+ return runs.run("scan", { label: "Map codebase behavior", agent: "scout", task: "Scan the codebase" });
113
136
  }
114
137
  const result = await scan();
115
138
  return result.output;
@@ -120,8 +143,8 @@ Chaining is still supported. The supported form is scripted chaining: await one
120
143
 
121
144
  ```js
122
145
  subagent({ workflowScript: `
123
- const plan = await runs.run("plan", { agent: "scout", task: "Plan the migration" });
124
- const patch = await runs.run("patch", { agent: "worker", task: "Implement this plan:\n" + plan.output });
146
+ const plan = await runs.run("plan", { label: "Plan migration behavior", agent: "scout", task: "Plan the migration" });
147
+ const patch = await runs.run("patch", { label: "Implement migration behavior", agent: "worker", task: "Implement this plan:\n" + plan.output });
125
148
  return patch.output;
126
149
  ` });
127
150
  ```
@@ -136,16 +159,16 @@ subagent({ workflowScript: `
136
159
  {
137
160
  key: "api",
138
161
  stages: [
139
- { key: "writer", agent: "worker", task: "Implement the API change" },
140
- { key: "challenge", resume: "previous", task: "Challenge the API implementation" },
141
- { key: "review", agent: "reviewer", task: "Review the API lane" }
162
+ { key: "writer", label: "Implement API behavior", agent: "worker", task: "Implement the API change" },
163
+ { key: "challenge", label: "Challenge API behavior", resume: "previous", task: "Challenge the API implementation" },
164
+ { key: "review", label: "Review API behavior", agent: "reviewer", task: "Review the API lane" }
142
165
  ]
143
166
  },
144
167
  {
145
168
  key: "ui",
146
169
  stages: [
147
- { key: "writer", agent: "worker", task: "Implement the UI change" },
148
- { key: "review", agent: "reviewer", task: "Review the UI lane" }
170
+ { key: "writer", label: "Implement UI behavior", agent: "worker", task: "Implement the UI change" },
171
+ { key: "review", label: "Review UI behavior", agent: "reviewer", task: "Review the UI lane" }
149
172
  ]
150
173
  }
151
174
  ]);
@@ -194,7 +217,7 @@ subagent({ workflowScript: `
194
217
  ` });
195
218
  ```
196
219
 
197
- The receipt state is `queued`, `delivered`, `missed`, or `failed`. `delivered` means the child Pi session accepted the input. It does not mean the model followed it. `missed` means the keyed child became terminal or had no live route before delivery. This first slice uses the existing foreground and async steering transports but does not start steering recovery. Workflow traces include one steering attempt entry and one receipt entry.
220
+ The receipt state is `queued`, `delivered`, `missed`, or `failed`. For an async child, `delivered` means it consumed the correlated user input; for a foreground child, it means the in-process Pi transport accepted the input. It does not mean the model followed it. `missed` means the keyed child became terminal or had no live route before delivery. This first slice uses the existing foreground and async steering transports but does not start steering recovery. Workflow traces include one steering attempt entry and one receipt entry.
198
221
 
199
222
  Always await or return a `runs.steer` promise. The workflow waits for an observed steering side effect to settle before it exits and rejects fire-and-forget calls. Use ordinary `Promise.race` when the first child or steering receipt should advance the script. There is no callback API or child inbox access.
200
223
 
@@ -347,6 +370,8 @@ known, or for explicit emergency hotfix lanes.
347
370
 
348
371
  For watched same-repo workflows, pass `async:false` only when the parent must block until completion. That blocking mode also shows the live in-chat workflow card. `chatProgress` can force `off` or `live-card` when the automatic policy is not what you want. Blocking workflows default to a 30-minute timeout; async workflows have no default timeout. See the [tool reference](tool-reference.md) for the full parameter list.
349
372
 
373
+ Synchronous workflows publish trace and `emit(...)` updates through the tool update callback regardless of `chatProgress`, including RPC/headless and cross-repository runs. These updates include `details.workflow` and `details.workflowChildren`; `chatProgress: "off"` disables the live card, not transport progress. Running foreground child rows additionally expose bounded `activity` (current tool, timing, and counters), plus resolved model/thinking when available, keyed by `childId`. Activity-only updates coalesce over 100 ms; lifecycle updates remain immediate. Activity clears when children settle, and is not persisted for async workflows. Tool names are limited to 256 UTF-8 bytes and each activity object is below 2 KiB (including JSON escaping); arguments and transcripts are not forwarded.
374
+
350
375
  The legacy `/chain`, `/parallel`, and `/run-chain` commands are not registered.
351
376
 
352
377
  ## Direct commands
@@ -369,10 +394,14 @@ Each child uses the existing worktree lifecycle: it branches from clean HEAD, jo
369
394
 
370
395
  A top-level `{ workflowScript, worktree: true }` makes isolation the default for every workflow child. An individual child can override that default with `worktree: false`. Keep one writer when parallel writes are not intentionally isolated.
371
396
 
372
- Use `baseRef` to branch managed worktrees from a named commit or branch instead of the default `HEAD`. For example, `{ workflowScript, worktree: true, baseRef: "refs/heads/release" }` applies the release ref to children unless a child supplies its own `baseRef`. The source checkout must still be clean, and the ref must resolve to a commit before any worktree is allocated.
397
+ Before a materialized `runs.run` or `runs.all` group dispatches fresh children, isolated sources must be Git repositories with clean working trees (excluding `.pi/subagents/` runtime state). A rejected group dispatches no children and spends no fan-out slots or child output claims; key-level failure traces can remain. Checks are shared only within that group, are cancellable, and run again at allocation because sources can change. Retained resumes keep their stored contracts. Select the correct cwd or arrange an operator-approved commit/stash; isolation is never dropped automatically.
398
+
399
+ Use `baseRef` to branch managed worktrees from `HEAD` or a supported named ref such as `refs/heads/release`, `refs/tags/v1`, or `origin/main`. Full 40/64-character commit IDs and revision expressions such as `HEAD~1` are unsupported. For example, `{ workflowScript, worktree: true, baseRef: "refs/heads/release" }` applies the release ref to children unless a child supplies its own `baseRef`. If omitted, the default `HEAD` is resolved at worktree allocation, not when the script is validated or a schedule is created. The source checkout must still be clean, and the ref must resolve to a commit before any worktree is allocated.
373
400
 
374
401
  Configure the worktree provider, native path layout, base directory, and setup hook in [configuration.md](configuration.md).
375
402
 
403
+ Setup waits remain nonblocking and cancellable. Normal cleanup, including detached foreground finalization, waits for the same in-process setup turn rather than retaining worktrees merely because another setup is active. This is not a cross-process lock. Hooks must follow the [finite setup contract](configuration.md#worktreesetuphook).
404
+
376
405
  ### Lane metadata lifecycle
377
406
 
378
407
  Workflow children may declare a bounded `lane` object (`version`, `key`, optional
@@ -394,11 +423,13 @@ Older runs without lane metadata remain readable and retain their existing
394
423
  handoff/cleanup behavior. Missing lane, receipt, or handoff metadata is
395
424
  unknown—not eligible for destructive cleanup.
396
425
 
397
- For managed worktree launches, the runner writes the pending handoff and the
398
- display-only status path/branch from the deterministic setup plan before the
399
- first `git worktree add`. If setup then fails or is interrupted, that pending
400
- ownership record remains preserved evidence; cleanup still rechecks the actual
401
- worktree state before any removal.
426
+ Managed setup records actual allocation attempts in the handoff; only validated
427
+ allocations become cleanup tasks and display-only status paths/branches. On
428
+ cancellation or failure with unknown settlement, it retains actual/attempted
429
+ ownership evidence and artifacts for manual reconciliation, blocking further
430
+ unsafe setup and cleanup in that process. An allocator interrupted before
431
+ reporting its path may leave branch-only diagnostics, never an invented path.
432
+ Inspect the handoff before reconciliation; cleanup still requires fresh checks.
402
433
 
403
434
  ## Supervisor coordination (child asks parent)
404
435
 
@@ -424,6 +455,14 @@ Children should not ask for clarification when the only conflict is review-only/
424
455
 
425
456
  The parent replies with `subagent_supervisor({ action: "reply", replyTo, message })` or checks pending requests with `subagent_supervisor({ action: "pending" })`. Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
426
457
 
458
+ A nested coordinator needs both directions of coordination. If its agent declares an explicit `tools` allowlist, include `subagent_supervisor` to answer its own children, alongside `subagent` for delegation and `contact_supervisor` for asking its parent:
459
+
460
+ ```yaml
461
+ tools: read, subagent, contact_supervisor, subagent_supervisor
462
+ ```
463
+
464
+ For A → B → C, C's request belongs to B, not A. B can escalate a separate question to A with `contact_supervisor`, then answer C using C's original `replyTo` request id. A's reply to B does not resolve C's request, and steering is not a substitute for replying. Only fanout-authorized children get the downward supervisor provider; explicit tool exclusions and capability ceilings still apply, and ordinary leaves do not gain delegation or reply tools. Requesting `subagent_supervisor` without fanout authorization fails at launch with an actionable error. A coordinator that excludes the reply tool does not start downward supervision or receive prompts to use it. Explicitly selected native coordination tools survive host-builtin filtering because their providers are child runtime hooks, not host builtins.
465
+
427
466
  Child-side routine completion handoffs are not expected. If a child appears stalled, needs-attention notices show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
428
467
 
429
468
  If a `workflowScript` child detaches through `contact_supervisor`, the enclosing async workflow stays `paused` until that child exits. Then the extension reconciles it to `complete` or `failed`. Wait on the child until that happens.
package/index.ts CHANGED
@@ -1,10 +1,13 @@
1
1
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import type {} from "./src/types/pi-runtime-compat.d.ts";
3
+ import { HERDR_PI_MODE_ENV } from "./src/runs/shared/herdr-pi-protocol.ts";
3
4
 
4
- const registerParentExtension = process.env.PI_SUBAGENT_CHILD === "1"
5
+ const registerExtension = process.env[HERDR_PI_MODE_ENV] === "1"
6
+ ? (await import("./src/extension/herdr-pi-bridge.ts")).default
7
+ : process.env.PI_SUBAGENT_CHILD === "1"
5
8
  ? undefined
6
9
  : (await import("./src/extension/index.ts")).default;
7
10
 
8
11
  export default function registerSubagentExtension(pi: ExtensionAPI): void {
9
- registerParentExtension?.(pi);
12
+ registerExtension?.(pi);
10
13
  }
@@ -1,11 +1,11 @@
1
1
  import { createJiti } from "jiti";
2
2
 
3
3
  const jiti = createJiti(import.meta.url);
4
- const { runInspector } = await jiti.import("./src/inspectors/herdr/inspector-runner.ts");
4
+ const { runInspector } = await jiti.import("./src/inspectors/inspector-runner.ts");
5
5
 
6
6
  try {
7
7
  runInspector();
8
8
  } catch (cause) {
9
- process.stderr.write(`Herdr inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
9
+ process.stderr.write(`Inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
10
10
  process.exitCode = 1;
11
11
  }
@@ -54,11 +54,19 @@ type Theme = TranscriptTheme;
54
54
  type ThemeColor = string;
55
55
  type ThemeBackground = string;
56
56
  export type TranscriptNoticeTone = "info" | "warning" | "error";
57
+ /**
58
+ * How a turn ended. A host that distinguishes a completed exchange from one the
59
+ * user aborted or that failed records it on the turn's end boundary; rendering
60
+ * treats every finished turn the same, so this stays metadata for hosts/tests.
61
+ */
62
+ export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
57
63
  export type TranscriptEntry = {
58
64
  id: number;
59
65
  turnId: number;
60
66
  type: "turn-boundary";
61
67
  phase: "start" | "end";
68
+ /** Present on `end` boundaries when the host reported how the turn ended. */
69
+ outcome?: TranscriptTurnOutcome;
62
70
  } | {
63
71
  id: number;
64
72
  turnId: number;
@@ -206,10 +214,12 @@ export declare function findLatestEntry<TType extends TranscriptEntry["type"]>(s
206
214
  * Closes `turnId` (defaulting to the current turn): appends the end boundary
207
215
  * unless one already exists, clears streaming flags on the turn's entries,
208
216
  * and updates bookkeeping. Idempotent — finishing an already-finished turn is
209
- * a no-op for boundary creation. Public building block for hosts that know
210
- * when a replayed exchange is complete.
217
+ * a no-op for boundary creation. An optional `outcome` is recorded on the end
218
+ * boundary, letting hosts distinguish completed, aborted, and failed turns.
219
+ * Public building block for hosts that know when a replayed exchange is
220
+ * complete.
211
221
  */
212
- export declare function finishTurn(state: TranscriptState, turnId?: number | null): void;
222
+ export declare function finishTurn(state: TranscriptState, turnId?: number | null, outcome?: TranscriptTurnOutcome): void;
213
223
  export declare function removeTranscriptTurn(state: TranscriptState, turnId: number | null): void;
214
224
  /**
215
225
  * Degraded stand-in stored on a tool-call entry when the original arguments
@@ -314,17 +314,29 @@ export function findLatestEntry(state, turnId, type) {
314
314
  * Closes `turnId` (defaulting to the current turn): appends the end boundary
315
315
  * unless one already exists, clears streaming flags on the turn's entries,
316
316
  * and updates bookkeeping. Idempotent — finishing an already-finished turn is
317
- * a no-op for boundary creation. Public building block for hosts that know
318
- * when a replayed exchange is complete.
317
+ * a no-op for boundary creation. An optional `outcome` is recorded on the end
318
+ * boundary, letting hosts distinguish completed, aborted, and failed turns.
319
+ * Public building block for hosts that know when a replayed exchange is
320
+ * complete.
319
321
  */
320
- export function finishTurn(state, turnId = state.currentTurnId) {
322
+ export function finishTurn(state, turnId = state.currentTurnId, outcome) {
321
323
  if (turnId === null)
322
324
  return;
323
- const alreadyFinished = state.entries.some((entry) => entry.turnId === turnId &&
325
+ const endBoundary = state.entries.find((entry) => entry.turnId === turnId &&
324
326
  entry.type === "turn-boundary" &&
325
327
  entry.phase === "end");
326
- if (!alreadyFinished)
327
- appendEntry(state, { type: "turn-boundary", turnId, phase: "end" });
328
+ if (endBoundary) {
329
+ if (outcome !== undefined)
330
+ endBoundary.outcome = outcome;
331
+ }
332
+ else {
333
+ appendEntry(state, {
334
+ type: "turn-boundary",
335
+ turnId,
336
+ phase: "end",
337
+ ...(outcome === undefined ? {} : { outcome }),
338
+ });
339
+ }
328
340
  for (const entry of state.entries) {
329
341
  if (entry.turnId !== turnId)
330
342
  continue;
@@ -79,12 +79,21 @@ type ThemeBackground = string;
79
79
 
80
80
  export type TranscriptNoticeTone = "info" | "warning" | "error";
81
81
 
82
+ /**
83
+ * How a turn ended. A host that distinguishes a completed exchange from one the
84
+ * user aborted or that failed records it on the turn's end boundary; rendering
85
+ * treats every finished turn the same, so this stays metadata for hosts/tests.
86
+ */
87
+ export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
88
+
82
89
  export type TranscriptEntry =
83
90
  | {
84
91
  id: number;
85
92
  turnId: number;
86
93
  type: "turn-boundary";
87
94
  phase: "start" | "end";
95
+ /** Present on `end` boundaries when the host reported how the turn ended. */
96
+ outcome?: TranscriptTurnOutcome;
88
97
  }
89
98
  | { id: number; turnId: number; type: "user-message"; text: string }
90
99
  | {
@@ -555,22 +564,33 @@ export function findLatestEntry<TType extends TranscriptEntry["type"]>(
555
564
  * Closes `turnId` (defaulting to the current turn): appends the end boundary
556
565
  * unless one already exists, clears streaming flags on the turn's entries,
557
566
  * and updates bookkeeping. Idempotent — finishing an already-finished turn is
558
- * a no-op for boundary creation. Public building block for hosts that know
559
- * when a replayed exchange is complete.
567
+ * a no-op for boundary creation. An optional `outcome` is recorded on the end
568
+ * boundary, letting hosts distinguish completed, aborted, and failed turns.
569
+ * Public building block for hosts that know when a replayed exchange is
570
+ * complete.
560
571
  */
561
572
  export function finishTurn(
562
573
  state: TranscriptState,
563
574
  turnId: number | null = state.currentTurnId,
575
+ outcome?: TranscriptTurnOutcome,
564
576
  ): void {
565
577
  if (turnId === null) return;
566
- const alreadyFinished = state.entries.some(
567
- (entry) =>
578
+ const endBoundary = state.entries.find(
579
+ (entry): entry is Extract<TranscriptEntry, { type: "turn-boundary" }> =>
568
580
  entry.turnId === turnId &&
569
581
  entry.type === "turn-boundary" &&
570
582
  entry.phase === "end",
571
583
  );
572
- if (!alreadyFinished)
573
- appendEntry(state, { type: "turn-boundary", turnId, phase: "end" });
584
+ if (endBoundary) {
585
+ if (outcome !== undefined) endBoundary.outcome = outcome;
586
+ } else {
587
+ appendEntry(state, {
588
+ type: "turn-boundary",
589
+ turnId,
590
+ phase: "end",
591
+ ...(outcome === undefined ? {} : { outcome }),
592
+ });
593
+ }
574
594
  for (const entry of state.entries) {
575
595
  if (entry.turnId !== turnId) continue;
576
596
  if (
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xzzpig/pi-subagents",
3
- "version": "0.14.0",
3
+ "version": "0.15.1",
4
4
  "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
5
5
  "author": "Nico Bailon",
6
6
  "license": "MIT",
@@ -13,6 +13,8 @@
13
13
  "./agents": "./src/api/agents.ts",
14
14
  "./delegation": "./src/api/delegation.ts",
15
15
  "./capability-ceiling": "./src/api/capability-ceiling.ts",
16
+ "./workflow-resources": "./src/api/workflow-resources.ts",
17
+ "./required-child-extensions": "./src/api/required-child-extensions.ts",
16
18
  "./preflight": "./src/api/preflight.ts",
17
19
  "./agent-management": "./src/api/agent-management.ts",
18
20
  "./control-channel": "./src/api/control-channel.ts",
@@ -88,12 +90,13 @@
88
90
  "acorn": "8.18.0",
89
91
  "jiti": "2.7.0",
90
92
  "typebox": "1.1.38",
93
+ "undici": "8.10.0",
91
94
  "yaml": "2.8.3"
92
95
  },
93
96
  "devDependencies": {
94
- "@earendil-works/pi-agent-core": "^0.85.1",
95
- "@earendil-works/pi-ai": "^0.85.1",
96
- "@earendil-works/pi-tui": "^0.85.1",
97
+ "@earendil-works/pi-agent-core": "0.85.1",
98
+ "@earendil-works/pi-ai": "0.85.1",
99
+ "@earendil-works/pi-tui": "0.85.1",
97
100
  "@oxlint/plugins": "1.80.0",
98
101
  "@types/node": "24.13.3",
99
102
  "oxlint": "1.80.0",
@@ -107,6 +110,8 @@
107
110
  "@xzzpig/pi-components"
108
111
  ],
109
112
  "scripts": {
113
+ "build:pkg": "node scripts/build-package.mjs",
114
+ "pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
110
115
  "typecheck": "tsc --noEmit",
111
116
  "test": "npm run test:unit",
112
117
  "test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
@@ -28,7 +28,7 @@ Choose or adapt angles when the work calls for it:
28
28
 
29
29
  Prefer three strong reviewers over many vague reviewers.
30
30
 
31
- Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete, current, caused or made reachable by the target diff, and supported by source proof, a test or repro, or a contract contradiction. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
31
+ Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete and current within the named review target, and supported by 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. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
32
32
 
33
33
  Do not default first-pass reviews to `blockers only`. That phrase is valid only for final pre-merge re-checks after P1/P2 findings are already inventoried, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred.
34
34
 
@@ -0,0 +1,24 @@
1
+ import { pathToFileURL } from "node:url";
2
+
3
+ let aliases = {};
4
+ let nativeRunner = false;
5
+ let compiledRunner = false;
6
+ let packageRootUrl;
7
+ const redirected = new Set([
8
+ "@earendil-works/pi-tui",
9
+ ]);
10
+
11
+ export function initialize(data) {
12
+ aliases = data?.aliases ?? {};
13
+ nativeRunner = data?.nativeRunner === true;
14
+ compiledRunner = data?.compiledRunner === true;
15
+ packageRootUrl = data?.packageRootUrl;
16
+ }
17
+
18
+ export function resolve(specifier, context, nextResolve) {
19
+ const packageImport = typeof packageRootUrl === "string" && context.parentURL?.startsWith(packageRootUrl) === true;
20
+ if (nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier]) {
21
+ return nextResolve(pathToFileURL(aliases[specifier]).href, context);
22
+ }
23
+ return nextResolve(specifier, context);
24
+ }
@@ -0,0 +1,36 @@
1
+ import * as nodeModule from "node:module";
2
+ import { pathToFileURL } from "node:url";
3
+
4
+ // Upstream-original preload: JITI_ALIAS is written by the runner launcher, so a malformed value must fail loudly.
5
+ // pi-lens-ignore: unchecked-throwing-call-js
6
+ const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
7
+ const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
8
+ const compiledRunner = process.env.PI_ASYNC_COMPILED_RUNNER === "1";
9
+ // Pi's jiti loader owns aliases for external extensions; these hooks only supply peers to our compiled package.
10
+ const packageRootUrl = new URL("./", import.meta.url).href;
11
+ const redirected = new Set([
12
+ "@earendil-works/pi-tui",
13
+ ]);
14
+
15
+ // Upstream-original: Node version feature detection for registerHooks (Node 22.12+ vs register()).
16
+ // pi-lens-ignore: no-runtime-typeof
17
+ if (typeof nodeModule.registerHooks === "function") {
18
+ nodeModule.registerHooks({
19
+ resolve(specifier, context, nextResolve) {
20
+ const packageImport = context.parentURL?.startsWith(packageRootUrl) === true;
21
+ if ((nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier])) {
22
+ return nextResolve(pathToFileURL(aliases[specifier]).href, context);
23
+ }
24
+ try {
25
+ return nextResolve(specifier, context);
26
+ } catch (error) {
27
+ if (nativeRunner && specifier.endsWith(".js")) return nextResolve(`${specifier.slice(0, -3)}.ts`, context);
28
+ throw error;
29
+ }
30
+ },
31
+ });
32
+ } else {
33
+ nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
34
+ data: { aliases, nativeRunner, compiledRunner, packageRootUrl },
35
+ });
36
+ }
@@ -1,28 +1,25 @@
1
1
  ---
2
2
  name: pi-subagents
3
3
  description: |
4
- Delegate to builtin or custom subagents for single-agent handoffs, parallel
5
- review, scripted chaining, async work, forked context, and coordinated
6
- workflows. Use when one parent agent should stay in control while children
7
- supply focused context, planning, review, or execution.
4
+ Technical guidance for operator-requested delegation to builtin or custom
5
+ subagents: bounded handoffs, parallel review, scripted workflows, async work,
6
+ forked context, isolation, and coordinated execution.
8
7
  ---
9
8
 
10
9
  # Pi Subagents
11
10
 
12
- Choose a mode:
13
-
14
- - **Direct mode:** For tiny or focused work, the parent handles the task
15
- directly; a single bounded child handoff is fine. Skip workflow ceremony.
16
- - **Orchestrator mode:** For substantial or delegated work, the parent is the
17
- supervisor, arbiter, and authority holder—not the routine primary doer.
18
- Subagents may own planning/design, scouting, implementation,
19
- simplification/challenge, validation, and review as useful. The parent keeps
20
- user intent, constraints, authority, routing, arbitration, final acceptance,
21
- and publication.
22
- - A useful loop for substantial work is **writer → challenge/simplify → review**;
23
- the parent arbitrates between steps, and tiny tasks can skip it.
24
- - Direct parent edits during orchestrator mode should be intentional, small
25
- interventions with a brief reason.
11
+ The parent works directly by default. Invoke subagents only when the operator
12
+ requested delegation in the current request or through applicable user/project
13
+ instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
14
+ available specialist does not independently authorize delegation.
15
+
16
+ Once authorized, choose the smallest bounded shape that earns its token and
17
+ elapsed-time overhead through concrete evidence, independent review,
18
+ specialization, useful parallelism, or needed isolation. A single child is
19
+ valid; writer, challenge, and review stages must each earn their overhead rather
20
+ than becoming default ceremony. The parent keeps user intent, constraints,
21
+ routing, arbitration, decisions, final acceptance, and publication authority,
22
+ and may perform the work directly where it is the most efficient owner.
26
23
 
27
24
  Children do not spawn subagents unless the parent explicitly delegated fanout
28
25
  and their resolved `tools` allow `subagent`.
@@ -50,6 +47,18 @@ use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
50
47
  example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
51
48
  bounded, but do not add stages or ceremony just to satisfy this skill.
52
49
 
50
+ When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
51
+ supply a short verb + behavior display `label` derived from the task, unless
52
+ the user supplied an explicit label; preserve that label. Keep the stable
53
+ machine `key` independent (for example, `issue2011-writer` with
54
+ `label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
55
+ items, not lane objects. Use stage-appropriate labels for reviews and retained-child
56
+ follow-ups too (for example, `Review workflow steering`). Generate labels in
57
+ the orchestrator while composing the launch—no extra model call, runtime
58
+ generator, or schema change. Native direct `{ agent, task }` calls have no
59
+ top-level `label` parameter; do not invent one or wrap a tiny single task in
60
+ a workflow just to label it.
61
+
53
62
  Use async/background by default. Set `async:false` only when the parent must
54
63
  block. Final reviews, validation gates, oracle checks, and publication checks
55
64
  stay async.
@@ -71,6 +80,8 @@ that runner explicitly supports the option.
71
80
 
72
81
  ## Read the reference for the branch
73
82
 
83
+ For exact API fields and worked examples, call `subagent({action:"guide",topic:"tool-reference"})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
84
+
74
85
  | Branch | Read |
75
86
  | --- | --- |
76
87
  | Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
@@ -80,9 +91,9 @@ that runner explicitly supports the option.
80
91
  | List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
81
92
  | Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
82
93
 
83
- For complex work, read `prompting-and-roles.md` and `execution-controls.md`, then
84
- load `review-and-validation.md` and `constraints-and-recipes.md` before launch or
85
- review.
94
+ For an authorized complex delegated workflow, read `prompting-and-roles.md` and
95
+ `execution-controls.md`, then load `review-and-validation.md` and
96
+ `constraints-and-recipes.md` before launch or review.
86
97
 
87
98
  ## Operating rules
88
99
 
@@ -91,7 +102,8 @@ review.
91
102
  - Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
92
103
  - Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
93
104
  - For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. See `references/multi-lane-orchestration.md` for lane mechanics.
94
- - Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. See `references/execution-controls.md`.
105
+ - Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
106
+ - Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
95
107
  - For cross-codebase work, record the repo, explicit `cwd`, authority boundary, and expected output before launch.
96
108
  - Make parallel prompts distinct by source seam, evidence, and decision. Do not clone prompts with only item numbers swapped.
97
109
  - Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
@@ -52,10 +52,11 @@ This reference keeps cross-cutting policy and failure handling. Load the matchin
52
52
  | Independent lanes, repositories, worktrees, and handoffs | [`references/multi-lane-orchestration.md`](multi-lane-orchestration.md) |
53
53
  | Agent management, file authoring, prompt integration, or RPC | [`references/management-authoring-rpc.md`](management-authoring-rpc.md) |
54
54
 
55
- Choose the smallest recipe that fits:
55
+ After delegation is operator-authorized, choose the smallest recipe that earns
56
+ its overhead. Recipes select a shape; they do not authorize delegation:
56
57
 
57
58
  - **Recon → plan → implement:** run one focused `scout`, then one `worker` that consumes its findings.
58
- - **Non-trivial implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, scout load-bearing code, plan when useful, use one writer, run fresh review/validation, apply only accepted fixes with one writer, then inspect direct evidence and the final diff before parent acceptance. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
59
+ - **Implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, and use a bounded scout, writer, or fresh reviewer only where the requested delegation benefits from that stage. Keep one writer, inspect direct evidence, and require every added stage to earn its overhead. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
59
60
  - **Parallel analysis:** fan out only independent read/review/validation work, or isolate each writer in its own worktree. Never run concurrent writers in one checkout.
60
61
 
61
62
  ## Error Handling