@xzzpig/pi-subagents 0.7.0 → 0.9.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 (234) hide show
  1. package/CHANGELOG.md +456 -4
  2. package/README.md +3 -3
  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 +13 -3
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +154 -42
  12. package/docs/configuration.md +85 -26
  13. package/docs/extension-api.md +81 -16
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +75 -11
  16. package/docs/observability.md +34 -21
  17. package/docs/tool-reference.md +142 -18
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +148 -4
  20. package/index.ts +10 -1
  21. package/install.mjs +1 -1
  22. package/package.json +7 -6
  23. package/prompts/council.md +19 -7
  24. package/prompts/parallel-review.md +5 -1
  25. package/prompts/review-loop.md +11 -7
  26. package/skills/council-mode/SKILL.md +44 -215
  27. package/skills/council-mode/references/pass-contracts.md +150 -0
  28. package/skills/pi-subagents/SKILL.md +90 -32
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +34 -223
  30. package/skills/pi-subagents/references/execution-controls.md +104 -19
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +16 -4
  33. package/skills/pi-subagents/references/prompting-and-roles.md +71 -36
  34. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  35. package/src/agents/agent-management.ts +471 -114
  36. package/src/agents/agent-refinements.ts +4 -4
  37. package/src/agents/agent-serializer.ts +16 -4
  38. package/src/agents/agents.ts +1076 -351
  39. package/src/agents/builtin-names.ts +6 -0
  40. package/src/agents/runtime-agent-events.ts +70 -0
  41. package/src/agents/runtime-agent-registry.ts +31 -20
  42. package/src/api/agents.ts +10 -5
  43. package/src/api/background-work.ts +12 -3
  44. package/src/api/capability-ceiling.ts +0 -1
  45. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  46. package/src/api/delegation.ts +0 -7
  47. package/src/api/external-job-provider.ts +10 -1
  48. package/src/api/external-runs.ts +67 -4
  49. package/src/api/preflight.ts +97 -34
  50. package/src/api/project-panes.ts +2 -0
  51. package/src/api/shared-types.ts +6 -0
  52. package/src/extension/config.ts +90 -0
  53. package/src/extension/doctor.ts +15 -13
  54. package/src/extension/fanout-child.ts +17 -16
  55. package/src/extension/index.ts +139 -41
  56. package/src/extension/public-execution.ts +113 -22
  57. package/src/extension/rpc.ts +182 -13
  58. package/src/extension/schemas.ts +63 -21
  59. package/src/extension/tool-description.ts +48 -23
  60. package/src/extension/tool-result.ts +19 -0
  61. package/src/inspectors/herdr/actions.ts +2 -1
  62. package/src/inspectors/herdr/client.ts +3 -3
  63. package/src/inspectors/herdr/focus.ts +55 -0
  64. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  65. package/src/inspectors/herdr/project-panes.ts +228 -44
  66. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  67. package/src/integrations/herdr-status.ts +75 -5
  68. package/src/intercom/native-supervisor-channel.ts +138 -60
  69. package/src/intercom/result-intercom.ts +2 -0
  70. package/src/intercom/supervisor-ui.ts +243 -0
  71. package/src/profiles/profiles.ts +5 -6
  72. package/src/runs/background/active-async-capacity.ts +103 -18
  73. package/src/runs/background/async-execution.ts +492 -125
  74. package/src/runs/background/async-job-tracker.ts +127 -28
  75. package/src/runs/background/async-resume.ts +67 -29
  76. package/src/runs/background/async-retention.ts +21 -4
  77. package/src/runs/background/async-status-snapshot.ts +23 -261
  78. package/src/runs/background/async-status.ts +199 -14
  79. package/src/runs/background/auto-drain.ts +1 -1
  80. package/src/runs/background/chain-append.ts +8 -3
  81. package/src/runs/background/chain-root-attachment.ts +79 -8
  82. package/src/runs/background/control-channel.ts +101 -214
  83. package/src/runs/background/fleet-view.ts +38 -22
  84. package/src/runs/background/inspect-rpc.ts +8 -8
  85. package/src/runs/background/notify.ts +295 -8
  86. package/src/runs/background/process-terminal.ts +16 -0
  87. package/src/runs/background/result-delivery-ownership.ts +45 -0
  88. package/src/runs/background/result-files.ts +28 -14
  89. package/src/runs/background/result-watcher.ts +43 -19
  90. package/src/runs/background/resume-guidance.ts +2 -2
  91. package/src/runs/background/retained-children.ts +1 -1
  92. package/src/runs/background/run-child-session.ts +613 -0
  93. package/src/runs/background/run-status.ts +99 -18
  94. package/src/runs/background/runner-aliases.ts +125 -0
  95. package/src/runs/background/runner-child-sessions.ts +31 -0
  96. package/src/runs/background/scheduled-runs.ts +174 -18
  97. package/src/runs/background/stale-run-reconciler.ts +13 -4
  98. package/src/runs/background/steering.ts +8 -15
  99. package/src/runs/background/subagent-runner.ts +959 -1159
  100. package/src/runs/background/subagent-wait.ts +86 -31
  101. package/src/runs/background/terminal-run-index.ts +1 -1
  102. package/src/runs/background/wait-completions.ts +45 -2
  103. package/src/runs/background/wait-config.ts +23 -9
  104. package/src/runs/background/wait-tool.ts +27 -19
  105. package/src/runs/foreground/async-steering-action.ts +3 -19
  106. package/src/runs/foreground/async-stop-action.ts +23 -2
  107. package/src/runs/foreground/execution.ts +585 -481
  108. package/src/runs/foreground/foreground-control.ts +13 -0
  109. package/src/runs/foreground/foreground-history.ts +26 -3
  110. package/src/runs/foreground/subagent-executor.ts +1549 -410
  111. package/src/runs/foreground/workflow-detach-reconcile.ts +141 -104
  112. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  113. package/src/runs/shared/abort-recovery.ts +119 -0
  114. package/src/runs/shared/acceptance.ts +147 -39
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +565 -0
  117. package/src/runs/shared/background-process-options.ts +9 -0
  118. package/src/runs/shared/capability-ceiling.ts +2 -2
  119. package/src/runs/shared/child-hooks.ts +25 -0
  120. package/src/runs/shared/child-identity.ts +62 -0
  121. package/src/runs/shared/child-launch-plan.ts +151 -0
  122. package/src/runs/shared/child-launch.ts +314 -0
  123. package/src/runs/shared/child-lifecycle.ts +25 -0
  124. package/src/runs/shared/child-runtime-config.ts +126 -0
  125. package/src/runs/shared/child-session.ts +342 -0
  126. package/src/runs/shared/child-tool-plan.ts +540 -0
  127. package/src/runs/shared/claude-code-adapter.ts +133 -0
  128. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  129. package/src/runs/shared/completion-evidence.ts +89 -0
  130. package/src/runs/shared/completion-guard.ts +57 -6
  131. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  132. package/src/runs/shared/dynamic-fanout.ts +4 -4
  133. package/src/runs/shared/extension-bindings.ts +78 -0
  134. package/src/runs/shared/external-cli-contract.ts +167 -0
  135. package/src/runs/shared/external-cli-preflight.ts +138 -0
  136. package/src/runs/shared/external-cli-runner.ts +349 -54
  137. package/src/runs/shared/external-job-bridge.ts +53 -37
  138. package/src/runs/shared/external-job-runner.ts +126 -23
  139. package/src/runs/shared/fast-mode-extension.ts +10 -0
  140. package/src/runs/shared/host-step-status.ts +231 -0
  141. package/src/runs/shared/lane-metadata.ts +126 -0
  142. package/src/runs/shared/launch-cwd.ts +16 -0
  143. package/src/runs/shared/long-running-guard.ts +2 -1
  144. package/src/runs/shared/mcp-config-sources.ts +422 -0
  145. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  146. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  147. package/src/runs/shared/model-exclusions.ts +141 -10
  148. package/src/runs/shared/model-fallback.ts +187 -33
  149. package/src/runs/shared/model-scope.ts +106 -39
  150. package/src/runs/shared/mutation-evidence.ts +199 -0
  151. package/src/runs/shared/nested-events.ts +38 -48
  152. package/src/runs/shared/nested-path.ts +0 -14
  153. package/src/runs/shared/nested-render.ts +9 -5
  154. package/src/runs/shared/orca-progress-tabs.ts +83 -16
  155. package/src/runs/shared/parallel-handoff.ts +423 -7
  156. package/src/runs/shared/parallel-utils.ts +28 -5
  157. package/src/runs/shared/permissions.ts +1 -14
  158. package/src/runs/shared/pi-spawn.ts +69 -35
  159. package/src/runs/shared/process-signal.ts +16 -0
  160. package/src/runs/shared/run-fanout-budget.ts +0 -13
  161. package/src/runs/shared/run-history.ts +21 -1
  162. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  163. package/src/runs/shared/single-output.ts +89 -22
  164. package/src/runs/shared/structured-output.ts +61 -7
  165. package/src/runs/shared/subagent-control.ts +6 -2
  166. package/src/runs/shared/subagent-prompt-runtime.ts +216 -360
  167. package/src/runs/shared/task-intent.ts +21 -7
  168. package/src/runs/shared/tool-availability.ts +18 -64
  169. package/src/runs/shared/tool-budget.ts +0 -14
  170. package/src/runs/shared/tool-timeout.ts +1 -1
  171. package/src/runs/shared/workflow-graph.ts +16 -0
  172. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  173. package/src/runs/shared/worktree.ts +571 -62
  174. package/src/shared/atomic-json.ts +3 -1
  175. package/src/shared/child-session-name.ts +46 -0
  176. package/src/shared/extension-context.ts +24 -0
  177. package/src/shared/fork-context.ts +21 -12
  178. package/src/shared/fork-session-cwd.ts +27 -0
  179. package/src/shared/formatters.ts +18 -3
  180. package/src/shared/jsonl-writer.ts +11 -0
  181. package/src/shared/launch-contract.ts +20 -6
  182. package/src/shared/pruned-fork.ts +450 -0
  183. package/src/shared/session-file-trust.ts +19 -0
  184. package/src/shared/session-tokens.ts +14 -3
  185. package/src/shared/settings.ts +21 -102
  186. package/src/shared/shortcuts.ts +17 -0
  187. package/src/shared/thinking-ceiling.ts +46 -0
  188. package/src/shared/types.ts +644 -75
  189. package/src/shared/utils.ts +60 -93
  190. package/src/shared/workflow-child-permit.ts +207 -0
  191. package/src/slash/delegation-adapters.ts +1 -9
  192. package/src/slash/delegation-request.ts +0 -4
  193. package/src/slash/prompt-template-bridge.ts +37 -1
  194. package/src/slash/slash-bridge.ts +1 -2
  195. package/src/slash/slash-commands.ts +383 -116
  196. package/src/slash/slash-live-state.ts +22 -11
  197. package/src/slash/subagents-admin.ts +29 -12
  198. package/src/tui/fleet-native-transcript.ts +4 -0
  199. package/src/tui/fleet-status.ts +278 -90
  200. package/src/tui/fleet-transcript.ts +11 -5
  201. package/src/tui/fleet.ts +54 -28
  202. package/src/tui/render-helpers.ts +31 -0
  203. package/src/tui/render.ts +1433 -166
  204. package/src/watchdog/change-signature.ts +40 -1
  205. package/src/watchdog/child-status.ts +54 -34
  206. package/src/watchdog/diff-tool.ts +77 -0
  207. package/src/watchdog/emission-guard.ts +5 -3
  208. package/src/watchdog/guidance.ts +20 -0
  209. package/src/watchdog/permission-arbiter.ts +59 -52
  210. package/src/watchdog/register-child.ts +28 -25
  211. package/src/watchdog/register-main.ts +10 -9
  212. package/src/watchdog/render.ts +4 -5
  213. package/src/watchdog/review.ts +15 -4
  214. package/src/watchdog/rules.ts +70 -0
  215. package/src/watchdog/runtime.ts +75 -92
  216. package/src/watchdog/scope.ts +0 -11
  217. package/src/watchdog/settings.ts +48 -104
  218. package/src/watchdog/turn-delta.ts +1 -1
  219. package/src/watchdog/types.ts +18 -32
  220. package/src/watchdog/warning-format.ts +0 -1
  221. package/src/workflows/chat-progress.ts +7 -3
  222. package/src/workflows/host-command.ts +235 -0
  223. package/src/workflows/scripted-workflow.ts +1142 -69
  224. package/src/workflows/workflow-checklist.ts +439 -0
  225. package/src/workflows/workflow-child-summary.ts +121 -0
  226. package/src/workflows/workflow-preflight.ts +297 -0
  227. package/src/workflows/workflow-receipt.ts +232 -6
  228. package/src/workflows/workflow-resources.ts +150 -0
  229. package/src/workflows/workflow-settlement.ts +246 -0
  230. package/src/runs/shared/child-protocol.ts +0 -401
  231. package/src/runs/shared/pi-args.ts +0 -858
  232. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  233. package/src/runs/shared/turn-budget.ts +0 -98
  234. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -21,7 +21,9 @@ import type {
21
21
  ResolvedAcceptanceGate,
22
22
  SingleResult,
23
23
  SubagentRunMode,
24
+ ChildWatchdogProgress,
24
25
  } from "../../shared/types.ts";
26
+ import { unresolvedChildWatchdogBlockers } from "../../watchdog/child-status.ts";
25
27
  import { isAgentContractV1 } from "./agent-contract.ts";
26
28
  import { classifyTaskMutationIntent, stripSeverityCompounds, taskMayMutate } from "./task-intent.ts";
27
29
 
@@ -47,7 +49,7 @@ const VALID_EVIDENCE_KINDS: AcceptanceEvidenceKind[] = [
47
49
  const VALID_EVIDENCE = new Set<AcceptanceEvidenceKind>(VALID_EVIDENCE_KINDS);
48
50
  const ACCEPTANCE_EVIDENCE_HELP = `Supported evidence kinds: ${VALID_EVIDENCE_KINDS.join(", ")}. Example: { level: "checked", evidence: ["commands-run", "changed-files"] }.`;
49
51
  const ACCEPTANCE_OBJECT_EXAMPLE = "Example: { level: \"checked\", evidence: [\"commands-run\", \"changed-files\"] }.";
50
- const ACCEPTANCE_CONFIG_KEYS = new Set(["level", "criteria", "evidence", "verify", "review", "stopRules", "reason"]);
52
+ const ACCEPTANCE_CONFIG_KEYS = new Set(["level", "report", "criteria", "evidence", "verify", "review", "stopRules", "reason"]);
51
53
  const ACCEPTANCE_GATE_KEYS = new Set(["id", "must", "evidence", "severity"]);
52
54
  const ACCEPTANCE_VERIFY_KEYS = new Set(["id", "command", "timeoutMs", "cwd", "env", "allowFailure"]);
53
55
  const ACCEPTANCE_REVIEW_KEYS = new Set(["agent", "focus", "required"]);
@@ -100,12 +102,13 @@ function inferLevel(input: {
100
102
  const writeTask = taskMayWrite
101
103
  || (input.acceptanceRole === "writer" && !readOnlyTask)
102
104
  || (input.acceptanceRole === undefined && /\bworker\b/.test(agent) && !readOnlyTask);
103
- const inferredReadOnly = readOnlyTask || (input.acceptanceRole === "read-only" && !taskMayWrite);
105
+ const inferredReadOnly = readOnlyTask || ((readOnlyAgent || input.acceptanceRole === "read-only") && !taskMayWrite);
104
106
  const roleResolvesReadOnly = input.acceptanceRole !== undefined && inferredReadOnly;
107
+ const dynamicResolvesReadOnly = inferredReadOnly && !writeTask;
105
108
  const keywordRiskReadOnly = input.acceptanceRole === undefined ? intent.kind === "read-only" : inferredReadOnly;
106
109
  const risky = Boolean(input.async && writeTask)
107
- || (Boolean(input.dynamic) && !roleResolvesReadOnly)
108
- || (Boolean(input.dynamicGroup) && !roleResolvesReadOnly)
110
+ || (Boolean(input.dynamic) && !roleResolvesReadOnly && !dynamicResolvesReadOnly)
111
+ || (Boolean(input.dynamicGroup) && !roleResolvesReadOnly && !dynamicResolvesReadOnly)
109
112
  || (!keywordRiskReadOnly && /\b(?:release|migration|migrate|security|data[- ]loss|destructive|post-review|fix pass)\b/.test(task));
110
113
 
111
114
  if (risky) {
@@ -131,7 +134,7 @@ function inferLevel(input: {
131
134
  if (readOnlyAgent || readOnlyTask) {
132
135
  reasons.push(input.acceptanceRole === "read-only" && !readOnlyTask ? "declared read-only acceptance role" : readOnlyAgent ? "read-only/reviewer-style agent" : "read-only task wording");
133
136
  return {
134
- level: "attested",
137
+ level: "none",
135
138
  reasons,
136
139
  criteria: ["Return concrete findings with file paths and severity when applicable"],
137
140
  evidence: ["review-findings", "residual-risks"],
@@ -146,11 +149,46 @@ function inferLevel(input: {
146
149
  };
147
150
  }
148
151
 
149
- export function normalizeAcceptanceInput(input: AcceptanceInput | undefined): AcceptanceConfig {
152
+ type AcceptanceInputNormalizationResult = { value: unknown; error?: string };
153
+
154
+ function normalizeAcceptanceValue(input: unknown, pathLabel = "acceptance"): AcceptanceInputNormalizationResult {
155
+ if (typeof input !== "string") return { value: input };
156
+ const trimmed = input.trim();
157
+ if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return { value: input };
158
+ let parsed: unknown;
159
+ try {
160
+ parsed = JSON.parse(trimmed);
161
+ } catch (error) {
162
+ return {
163
+ value: input,
164
+ error: `${pathLabel} JSON string must encode a valid acceptance object: ${error instanceof Error ? error.message : String(error)}`,
165
+ };
166
+ }
167
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
168
+ const kind = parsed === null ? "null" : Array.isArray(parsed) ? "an array" : typeof parsed;
169
+ return { value: input, error: `${pathLabel} JSON string must encode an object; got ${kind}.` };
170
+ }
171
+ return { value: parsed };
172
+ }
173
+
174
+ export function normalizeAcceptanceInput(input: unknown): AcceptanceConfig {
175
+ const normalized = normalizeAcceptanceValue(input);
176
+ if (normalized.error) throw new Error(normalized.error);
177
+ input = normalized.value;
150
178
  if (input === undefined || input === "auto") return { level: "auto" };
151
179
  if (input === false) return { level: "none", reason: "disabled by deprecated false shorthand" };
152
- if (typeof input === "string") return { level: input };
153
- return { ...input };
180
+ if (typeof input === "string") return { level: input as AcceptanceConfig["level"] };
181
+ return { ...(input as AcceptanceConfig) };
182
+ }
183
+
184
+ export type ResolvedAcceptanceReportMode = "off" | "optional" | "required";
185
+
186
+ export function resolveAcceptanceReportMode(input: unknown): ResolvedAcceptanceReportMode {
187
+ const normalized = normalizeAcceptanceValue(input);
188
+ if (normalized.error) throw new Error(normalized.error);
189
+ const value = normalized.value;
190
+ const report = value && typeof value === "object" && !Array.isArray(value) ? (value as AcceptanceConfig).report : undefined;
191
+ return value === false || report === "off" ? "off" : report === "on" ? "required" : "optional";
154
192
  }
155
193
 
156
194
  type GateAcceptanceNormalizationResult =
@@ -158,7 +196,11 @@ type GateAcceptanceNormalizationResult =
158
196
  | { ok: false; error: string };
159
197
 
160
198
  export function normalizeGateAcceptance(gate: unknown, acceptance: AcceptanceInput | undefined): GateAcceptanceNormalizationResult {
161
- if (gate === undefined) return acceptance === undefined ? { ok: true } : { ok: true, acceptance };
199
+ if (gate === undefined) {
200
+ if (acceptance === undefined) return { ok: true };
201
+ const normalized = normalizeAcceptanceValue(acceptance);
202
+ return normalized.error ? { ok: false, error: normalized.error } : { ok: true, acceptance: normalized.value as AcceptanceInput };
203
+ }
162
204
  if (typeof gate !== "string" || !gate.trim()) return { ok: false, error: "gate must be a non-empty command string." };
163
205
  if (acceptance !== undefined) return { ok: false, error: "gate cannot be combined with acceptance; use one gate command or acceptance.verify." };
164
206
  return { ok: true, acceptance: { level: "verified", verify: [{ id: "gate", command: gate.trim() }] } };
@@ -168,6 +210,10 @@ function explicitAcceptanceCanDisable(explicit: AcceptanceConfig): boolean {
168
210
  return explicit.level === "none" && typeof explicit.reason === "string" && explicit.reason.trim().length > 0;
169
211
  }
170
212
 
213
+ function explicitAcceptanceRequestsPolicy(explicit: AcceptanceConfig): boolean {
214
+ return (explicit.level !== undefined && explicit.level !== "auto") || Object.keys(explicit).some((key) => key !== "level");
215
+ }
216
+
171
217
  function unsupportedEvidenceKindMessage(pathLabel: string, item: unknown): string {
172
218
  const value = typeof item === "string" ? ` "${item}"` : "";
173
219
  return `${pathLabel}${value} is not a supported evidence kind. ${ACCEPTANCE_EVIDENCE_HELP}`;
@@ -177,6 +223,9 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
177
223
  const errors: string[] = [];
178
224
  if (input === undefined) return errors;
179
225
  if (input === false) return errors;
226
+ const normalized = normalizeAcceptanceValue(input, pathLabel);
227
+ if (normalized.error) return [normalized.error];
228
+ input = normalized.value;
180
229
  if (typeof input === "string") {
181
230
  if (input === "reviewed") errors.push(`${pathLabel} ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
182
231
  else if (!VALID_LEVELS.has(input as AcceptanceLevel)) errors.push(`${pathLabel} has invalid level '${input}'.`);
@@ -197,6 +246,9 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
197
246
  } else if (value.level !== undefined && (typeof value.level !== "string" || !VALID_LEVELS.has(value.level as AcceptanceLevel))) {
198
247
  errors.push(`${pathLabel}.level must be one of auto, none, attested, checked, verified.`);
199
248
  }
249
+ if (value.report !== undefined && value.report !== "on" && value.report !== "off") {
250
+ errors.push(`${pathLabel}.report must be on or off.`);
251
+ }
200
252
  if (value.level === "none" && (typeof value.reason !== "string" || !value.reason.trim())) {
201
253
  errors.push(`${pathLabel}.reason is required when level is none.`);
202
254
  }
@@ -304,29 +356,45 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
304
356
 
305
357
  export function validateExecutionAcceptance(input: {
306
358
  acceptance?: unknown;
307
- tasks?: Array<{ acceptance?: unknown }>;
359
+ outputSchema?: unknown;
360
+ tasks?: Array<{ acceptance?: unknown; outputSchema?: unknown }>;
308
361
  chain?: Array<{
309
362
  acceptance?: unknown;
310
- parallel?: Array<{ acceptance?: unknown }> | { acceptance?: unknown };
363
+ outputSchema?: unknown;
364
+ parallel?: Array<{ acceptance?: unknown; outputSchema?: unknown }> | { acceptance?: unknown; outputSchema?: unknown };
311
365
  }>;
312
366
  }): string[] {
313
367
  const errors = validateAcceptanceInput(input.acceptance, "acceptance");
368
+ errors.push(...validateAcceptanceReportMode(input.acceptance, input.outputSchema, "acceptance"));
314
369
  for (const [index, task] of (input.tasks ?? []).entries()) {
315
370
  errors.push(...validateAcceptanceInput(task.acceptance, `tasks[${index}].acceptance`));
371
+ errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `tasks[${index}].acceptance`));
316
372
  }
317
373
  for (const [stepIndex, step] of (input.chain ?? []).entries()) {
318
374
  errors.push(...validateAcceptanceInput(step.acceptance, `chain[${stepIndex}].acceptance`));
375
+ errors.push(...validateAcceptanceReportMode(step.acceptance, step.outputSchema, `chain[${stepIndex}].acceptance`));
319
376
  if (Array.isArray(step.parallel)) {
320
377
  for (const [taskIndex, task] of step.parallel.entries()) {
321
378
  errors.push(...validateAcceptanceInput(task.acceptance, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
379
+ errors.push(...validateAcceptanceReportMode(task.acceptance, task.outputSchema, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
322
380
  }
323
381
  } else if (step.parallel) {
324
382
  errors.push(...validateAcceptanceInput(step.parallel.acceptance, `chain[${stepIndex}].parallel.acceptance`));
383
+ errors.push(...validateAcceptanceReportMode(step.parallel.acceptance, step.parallel.outputSchema, `chain[${stepIndex}].parallel.acceptance`));
325
384
  }
326
385
  }
327
386
  return errors;
328
387
  }
329
388
 
389
+ function validateAcceptanceReportMode(acceptance: unknown, outputSchema: unknown, pathLabel: string): string[] {
390
+ const normalized = normalizeAcceptanceValue(acceptance, pathLabel);
391
+ if (normalized.error) return [];
392
+ acceptance = normalized.value;
393
+ if (!acceptance || typeof acceptance !== "object" || Array.isArray(acceptance)) return [];
394
+ if (!("report" in acceptance)) return [];
395
+ return outputSchema === undefined ? [`${pathLabel}.report requires outputSchema.`] : [];
396
+ }
397
+
330
398
  function normalizeCriteria(criteria: Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }> | undefined, evidence: AcceptanceEvidenceKind[]): ResolvedAcceptanceGate[] {
331
399
  return (criteria ?? []).map((criterion, index): ResolvedAcceptanceGate => {
332
400
  if (typeof criterion === "string") {
@@ -376,12 +444,13 @@ export function resolveEffectiveAcceptance(input: {
376
444
  };
377
445
  }
378
446
  const inferred = inferLevel(input);
447
+ const inferredLevel = inferred.level === "none" && explicitAcceptanceRequestsPolicy(explicit) ? "attested" : inferred.level;
379
448
  const level = explicitAcceptanceCanDisable(explicit)
380
449
  ? "none"
381
450
  : explicitLevel === "auto"
382
- ? inferred.level
383
- : (LEVEL_RANK[explicitLevel] >= LEVEL_RANK[inferred.level] ? explicitLevel : inferred.level);
384
- const evidence = unique([...(level === inferred.level ? inferred.evidence : requiredEvidenceForLevel(level)), ...(explicit.evidence ?? [])]);
451
+ ? inferredLevel
452
+ : (LEVEL_RANK[explicitLevel] >= LEVEL_RANK[inferredLevel] ? explicitLevel : inferredLevel);
453
+ const evidence = unique([...(level === inferredLevel ? inferred.evidence : requiredEvidenceForLevel(level)), ...(explicit.evidence ?? [])]);
385
454
  const criteria = normalizeCriteria(
386
455
  (explicit.criteria?.length ? explicit.criteria : inferred.criteria) as Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }>,
387
456
  evidence,
@@ -391,8 +460,8 @@ export function resolveEffectiveAcceptance(input: {
391
460
  level,
392
461
  explicit: input.explicit !== undefined,
393
462
  inferredReason: inferred.reasons,
394
- criteria,
395
- evidence,
463
+ criteria: level === "none" ? [] : criteria,
464
+ evidence: level === "none" ? [] : evidence,
396
465
  verify: explicit.verify ?? [],
397
466
  review,
398
467
  stopRules: explicit.stopRules ?? [],
@@ -404,7 +473,7 @@ function acceptanceRequiresChildReport(acceptance: ResolvedAcceptanceConfig): bo
404
473
  return acceptance.criteria.length > 0 || acceptance.evidence.length > 0;
405
474
  }
406
475
 
407
- export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, options: { reportOptional?: boolean } = {}): string {
476
+ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, options: { reportOptional?: boolean; structuredOutput?: boolean } = {}): string {
408
477
  if (acceptance.level === "none") return "";
409
478
  if (options.reportOptional && !acceptanceRequiresChildReport(acceptance)) return "";
410
479
  const lines = [
@@ -431,13 +500,15 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
431
500
  }
432
501
  lines.push(
433
502
  "",
434
- "Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
503
+ options.structuredOutput
504
+ ? "Include an `acceptanceReport` object in your final `structured_output` tool call in this shape:"
505
+ : "Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
435
506
  "Use empty arrays when no items apply; array fields contain strings unless object entries are shown.",
436
507
  "Empty-string entries (`[\"\"]`) are ignored; use `[]` when nothing applies.",
437
508
  "`criteriaSatisfied[].status` must be exactly one of: satisfied, not-satisfied, not-applicable.",
438
509
  "`commandsRun[].result` must be exactly one of: passed, failed, not-run.",
439
510
  "`manualNotes` and `notes` are optional strings; an empty string means no note and does not satisfy `manual-notes` evidence.",
440
- "```acceptance-report",
511
+ ...(options.structuredOutput ? [] : ["```acceptance-report"]),
441
512
  JSON.stringify({
442
513
  criteriaSatisfied: acceptance.criteria
443
514
  .filter((criterion) => criterion.severity !== "recommended")
@@ -452,7 +523,7 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
452
523
  reviewFindings: ["blocker: file.ts:12 - issue found, or no blockers"],
453
524
  manualNotes: "anything else the parent should know",
454
525
  }, null, 2),
455
- "```",
526
+ ...(options.structuredOutput ? [] : ["```"]),
456
527
  );
457
528
  return lines.join("\n");
458
529
  }
@@ -676,7 +747,15 @@ function parseAcceptanceReportBody(body: string): { report?: AcceptanceReport; e
676
747
  return validateAcceptanceReport(parseReportJson(body));
677
748
  }
678
749
 
679
- function parseUnterminatedAcceptanceReportFence(output: string): { report?: AcceptanceReport; error?: string } {
750
+ interface AcceptanceReportParseResult {
751
+ report?: AcceptanceReport;
752
+ error?: string;
753
+ /** True when an acceptance-report signal was found but its envelope was invalid. */
754
+ malformed?: boolean;
755
+ sourcePath?: string;
756
+ }
757
+
758
+ function parseUnterminatedAcceptanceReportFence(output: string): AcceptanceReportParseResult {
680
759
  const opener = /```acceptance[-_]report\b[^\n]*\n/gi.exec(output);
681
760
  if (!opener) return {};
682
761
  const bodyStart = opener.index + opener[0].length;
@@ -685,13 +764,13 @@ function parseUnterminatedAcceptanceReportFence(output: string): { report?: Acce
685
764
  const validation = validateAcceptanceReport(JSON.parse(output.slice(bodyStart).trim()) as unknown);
686
765
  return validation.report
687
766
  ? { report: validation.report }
688
- : { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
767
+ : { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
689
768
  } catch (error) {
690
- return { error: `Failed to parse acceptance-report: ${error instanceof Error ? error.message : String(error)}` };
769
+ return { error: `Failed to parse acceptance-report: ${error instanceof Error ? error.message : String(error)}`, malformed: true };
691
770
  }
692
771
  }
693
772
 
694
- function parseGenericJsonAcceptanceReportBody(body: string): { report?: AcceptanceReport; error?: string } {
773
+ function parseGenericJsonAcceptanceReportBody(body: string): AcceptanceReportParseResult {
695
774
  const parsed = parseReportJson(body);
696
775
  const normalized = normalizeAcceptanceReportValue(parsed);
697
776
  const hasCriteriaMarker = normalized.value !== null
@@ -702,12 +781,12 @@ function parseGenericJsonAcceptanceReportBody(body: string): { report?: Acceptan
702
781
  const validation = validateAcceptanceReport(parsed);
703
782
  return validation.report
704
783
  ? { report: validation.report }
705
- : { error: `Invalid acceptance-report: ${validation.errors.join("; ")}` };
784
+ : { error: `Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
706
785
  }
707
786
 
708
787
  export const ACCEPTANCE_REPORT_NOT_FOUND = "Structured acceptance report not found.";
709
788
 
710
- export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
789
+ export function parseAcceptanceReport(output: string): AcceptanceReportParseResult {
711
790
  const explicitFencePresent = /```acceptance[-_]report\b/i.test(output);
712
791
  const fenced = fencedBlocks(output, "acceptance[-_]report");
713
792
  const parseErrors: string[] = [];
@@ -720,17 +799,17 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
720
799
  parseErrors.push(error instanceof Error ? error.message : String(error));
721
800
  }
722
801
  }
723
- if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
802
+ if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}`, malformed: true };
724
803
  if (explicitFencePresent) {
725
804
  const recovered = parseUnterminatedAcceptanceReportFence(output);
726
805
  if (recovered.report || recovered.error) return recovered;
727
- return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence." };
806
+ return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence.", malformed: true };
728
807
  }
729
808
  for (const body of fencedBlocks(output, "(?:json|jsonc|json5)")) {
730
809
  try {
731
810
  const parsed = parseGenericJsonAcceptanceReportBody(body);
732
811
  if (parsed.report) return { report: parsed.report };
733
- if (parsed.error) return { error: `Failed to parse acceptance-report: ${parsed.error}` };
812
+ if (parsed.error) return { error: `Failed to parse acceptance-report: ${parsed.error}`, malformed: parsed.malformed };
734
813
  } catch {
735
814
  // Ignore unrelated malformed generic JSON. A recognizable report shape
736
815
  // returns exact validation errors above instead of being mistaken for prose.
@@ -740,20 +819,20 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
740
819
  if (markerIndex !== -1) {
741
820
  const jsonStart = output.indexOf("{", markerIndex);
742
821
  if (jsonStart === -1) {
743
- return { error: "Failed to parse acceptance-report: Expected a JSON object after ACCEPTANCE_REPORT:." };
822
+ return { error: "Failed to parse acceptance-report: Expected a JSON object after ACCEPTANCE_REPORT:.", malformed: true };
744
823
  }
745
824
  const json = extractBalancedJson(output, jsonStart);
746
825
  if (!json) {
747
- return { error: "Failed to parse acceptance-report: Unterminated JSON object after ACCEPTANCE_REPORT:." };
826
+ return { error: "Failed to parse acceptance-report: Unterminated JSON object after ACCEPTANCE_REPORT:.", malformed: true };
748
827
  }
749
828
  try {
750
829
  const parsed = JSON.parse(json) as unknown;
751
830
  const validation = validateAcceptanceReport(parsed);
752
831
  if (validation.report) return { report: validation.report };
753
- return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
832
+ return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
754
833
  } catch (error) {
755
834
  const message = error instanceof Error ? error.message : String(error);
756
- return { error: `Failed to parse acceptance-report: ${message}` };
835
+ return { error: `Failed to parse acceptance-report: ${message}`, malformed: true };
757
836
  }
758
837
  }
759
838
  return { error: ACCEPTANCE_REPORT_NOT_FOUND };
@@ -762,14 +841,18 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
762
841
  function parseAcceptanceReportSources(
763
842
  output: string,
764
843
  fileOutput: { content: string; path: string; authoritative?: boolean } | undefined,
765
- ): { report?: AcceptanceReport; error?: string } {
844
+ ): AcceptanceReportParseResult {
766
845
  const fromText = () => parseAcceptanceReport(output);
767
846
  const fromFile = () => {
768
847
  if (!fileOutput) return { error: ACCEPTANCE_REPORT_NOT_FOUND };
769
848
  const parsed = parseAcceptanceReport(fileOutput.content);
770
849
  return parsed.report || parsed.error === ACCEPTANCE_REPORT_NOT_FOUND
771
850
  ? parsed
772
- : { error: `${parsed.error} (in configured output ${fileOutput.path})` };
851
+ : {
852
+ ...parsed,
853
+ error: `${parsed.error} (in configured output ${fileOutput.path})`,
854
+ sourcePath: fileOutput.path,
855
+ };
773
856
  };
774
857
  const [primary, secondary] = fileOutput?.authoritative ? [fromFile, fromText] : [fromText, fromFile];
775
858
  const first = primary();
@@ -837,7 +920,7 @@ function validateStringArrayField(errors: string[], value: unknown, pathLabel: s
837
920
  }
838
921
  }
839
922
 
840
- function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: AcceptanceReport; errors: string[] } {
923
+ export function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: AcceptanceReport; errors: string[] } {
841
924
  const normalized = normalizeAcceptanceReportValue(value, pathLabel);
842
925
  value = normalized.value;
843
926
  pathLabel = normalized.pathLabel;
@@ -959,6 +1042,7 @@ function checkNoStagedFiles(cwd: string): AcceptanceRuntimeCheck {
959
1042
  function runStructuralChecks(acceptance: ResolvedAcceptanceConfig, report: AcceptanceReport, cwd: string): AcceptanceRuntimeCheck[] {
960
1043
  const checks: AcceptanceRuntimeCheck[] = [];
961
1044
  for (const kind of acceptance.evidence) {
1045
+ if (kind === "no-staged-files" && report.noStagedFiles === undefined) continue;
962
1046
  const status = reportEvidenceStatus(report, kind);
963
1047
  checks.push({
964
1048
  id: `evidence:${kind}`,
@@ -1269,14 +1353,16 @@ export async function evaluateAcceptance(input: {
1269
1353
  * be misattributed). Searched for the acceptance report; searched before
1270
1354
  * the assistant output when `authoritative` (outputMode "file-only").
1271
1355
  */
1272
- fileOutput?: { content: string; path: string; authoritative?: boolean };
1356
+ fileOutput?: { content: string; path: string; authoritative?: boolean; durable?: boolean };
1273
1357
  report?: AcceptanceReport;
1358
+ reportError?: string;
1274
1359
  reviewResult?: AcceptanceReviewResult;
1275
1360
  signal?: AbortSignal;
1276
1361
  abortMessage?: string;
1277
1362
  reportOptional?: boolean;
1278
1363
  artifactsDir?: string;
1279
1364
  runId?: string;
1365
+ watchdog?: ChildWatchdogProgress;
1280
1366
  }): Promise<AcceptanceLedger> {
1281
1367
  const acceptance = input.acceptance;
1282
1368
  const initialStatus = acceptance.level === "none" ? "not-required" : "claimed";
@@ -1292,14 +1378,32 @@ export async function evaluateAcceptance(input: {
1292
1378
  };
1293
1379
  if (acceptance.level === "none") return ledger;
1294
1380
 
1295
- const parsed = input.report
1381
+ if (input.watchdog) {
1382
+ const unresolved = unresolvedChildWatchdogBlockers(input.watchdog);
1383
+ ledger.runtimeChecks.push(unresolved.length
1384
+ ? { id: "watchdog-blocker", status: "failed", message: `Unresolved watchdog blocker: ${unresolved[0]!.summary}` }
1385
+ : { id: "watchdog-blocker", status: "passed", message: "No unresolved watchdog blockers." });
1386
+ }
1387
+
1388
+ const parsed: AcceptanceReportParseResult = input.reportError
1389
+ ? { error: input.reportError }
1390
+ : input.report !== undefined
1296
1391
  ? (() => {
1297
1392
  const validation = validateAcceptanceReport(input.report);
1298
1393
  return validation.report
1299
1394
  ? { report: validation.report }
1300
- : { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
1395
+ : { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}`, malformed: true };
1301
1396
  })()
1302
1397
  : parseAcceptanceReportSources(input.output, input.fileOutput);
1398
+ const durableFileOutput = input.fileOutput?.authoritative && input.fileOutput.durable ? input.fileOutput : undefined;
1399
+ if (parsed.malformed && parsed.sourcePath && durableFileOutput) {
1400
+ ledger.recovery = {
1401
+ status: "available-for-review",
1402
+ reason: "acceptance-metadata-rejected",
1403
+ reportPath: parsed.sourcePath,
1404
+ reportHash: hash(durableFileOutput.content),
1405
+ };
1406
+ }
1303
1407
  const needsReport = acceptanceRequiresChildReport(acceptance);
1304
1408
  if (parsed.report) {
1305
1409
  ledger.childReport = parsed.report;
@@ -1308,6 +1412,10 @@ export async function evaluateAcceptance(input: {
1308
1412
  } else if (!input.reportOptional || needsReport || parsed.error !== ACCEPTANCE_REPORT_NOT_FOUND) {
1309
1413
  ledger.childReportParseError = parsed.error;
1310
1414
  ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
1415
+ if (ledger.recovery) {
1416
+ ledger.status = "rejected";
1417
+ ledger.evidenceStatus = "rejected";
1418
+ }
1311
1419
  if (!input.reportOptional) {
1312
1420
  ledger.status = "rejected";
1313
1421
  ledger.evidenceStatus = "rejected";
@@ -12,7 +12,7 @@ export function buildExecutionProjection(result: Pick<SingleResult, "exitCode" |
12
12
  return { status: "stopped", success: false, exitCode: result.exitCode, stopped: true, ...(result.error ? { error: result.error } : {}) };
13
13
  }
14
14
  if (result.interrupted) {
15
- return { status: "paused", success: true, exitCode: result.exitCode, interrupted: true, ...(result.error ? { error: result.error } : {}) };
15
+ return { status: "paused", success: false, exitCode: result.exitCode, interrupted: true, ...(result.error ? { error: result.error } : {}) };
16
16
  }
17
17
  const success = result.exitCode === 0 && !result.error && !result.timedOut;
18
18
  return {