@xzzpig/pi-subagents 0.13.0 → 0.15.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 (202) hide show
  1. package/CHANGELOG.md +243 -0
  2. package/README.md +6 -5
  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 +56 -15
  7. package/docs/configuration.md +93 -15
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +67 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/CHANGELOG.md +19 -0
  19. package/node_modules/@xzzpig/pi-components/README.md +28 -0
  20. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +46 -4
  21. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +65 -17
  22. package/node_modules/@xzzpig/pi-components/package.json +1 -1
  23. package/node_modules/@xzzpig/pi-components/src/transcript.ts +107 -14
  24. package/package.json +10 -5
  25. package/prompts/parallel-review.md +1 -1
  26. package/runner-peer-loader.mjs +24 -0
  27. package/runner-peer-preload.mjs +36 -0
  28. package/skills/pi-subagents/SKILL.md +34 -22
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  30. package/skills/pi-subagents/references/execution-controls.md +27 -8
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  33. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  34. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  35. package/src/agents/advertised-agent-prompt.ts +94 -0
  36. package/src/agents/agent-management.ts +71 -59
  37. package/src/agents/agent-serializer.ts +6 -3
  38. package/src/agents/agents.ts +198 -72
  39. package/src/agents/builtin-names.ts +1 -0
  40. package/src/agents/chain-serializer.ts +5 -0
  41. package/src/agents/runtime-agent-registry.ts +7 -6
  42. package/src/api/delegation.ts +4 -0
  43. package/src/api/preflight.ts +110 -71
  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 +32 -13
  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 +766 -432
  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 +896 -397
  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 +44 -16
  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 +145 -14
  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 +19 -10
  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/readonly-drain-observation.ts +42 -0
  148. package/src/runs/shared/run-fanout-budget.ts +8 -8
  149. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  150. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  151. package/src/runs/shared/task-intent.ts +46 -13
  152. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  153. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  154. package/src/runs/shared/worktree-setup-command.ts +213 -0
  155. package/src/runs/shared/worktree.ts +437 -214
  156. package/src/shared/child-cache-retention.ts +43 -0
  157. package/src/shared/fork-context.ts +15 -72
  158. package/src/shared/launch-contract.ts +70 -8
  159. package/src/shared/model-response-aliases.ts +13 -0
  160. package/src/shared/opencode-session-headers.ts +30 -0
  161. package/src/shared/pruned-fork.ts +1 -1
  162. package/src/shared/required-child-extensions.ts +81 -0
  163. package/src/shared/settings.ts +5 -2
  164. package/src/shared/shortcuts.ts +0 -4
  165. package/src/shared/types.ts +164 -90
  166. package/src/shared/utils.ts +10 -2
  167. package/src/shared/watch-strategy.ts +2 -0
  168. package/src/shared/workflow-child-permit.ts +18 -13
  169. package/src/slash/delegation-adapters.ts +3 -1
  170. package/src/slash/delegation-request.ts +14 -0
  171. package/src/slash/slash-commands.ts +2 -7
  172. package/src/slash/subagents-admin.ts +31 -14
  173. package/src/tui/fleet-native-transcript.ts +50 -6
  174. package/src/tui/fleet-status.ts +165 -20
  175. package/src/tui/fleet.ts +52 -21
  176. package/src/tui/render.ts +210 -50
  177. package/src/watchdog/child-status.ts +28 -28
  178. package/src/watchdog/lsp-diagnostics.ts +1 -1
  179. package/src/watchdog/model-selection.ts +21 -1
  180. package/src/watchdog/permission-arbiter.ts +5 -2
  181. package/src/watchdog/register-child.ts +10 -2
  182. package/src/watchdog/register-main.ts +39 -35
  183. package/src/watchdog/render.ts +1 -1
  184. package/src/watchdog/review.ts +122 -74
  185. package/src/watchdog/rules.ts +1 -1
  186. package/src/watchdog/runtime.ts +100 -27
  187. package/src/watchdog/scope.ts +1 -1
  188. package/src/watchdog/settings.ts +3 -0
  189. package/src/watchdog/tool-actions.ts +13 -12
  190. package/src/watchdog/turn-delta.ts +23 -0
  191. package/src/watchdog/types.ts +5 -3
  192. package/src/watchdog/warning-format.ts +1 -1
  193. package/src/workflows/chat-progress.ts +3 -3
  194. package/src/workflows/scripted-workflow.ts +349 -26
  195. package/src/workflows/workflow-checklist.ts +17 -20
  196. package/src/workflows/workflow-child-summary.ts +57 -8
  197. package/src/workflows/workflow-preflight.ts +19 -19
  198. package/src/workflows/workflow-receipt.ts +24 -6
  199. package/src/workflows/workflow-resources.ts +108 -22
  200. package/src/workflows/workflow-settlement.ts +3 -0
  201. package/src/runs/shared/model-exclusions.ts +0 -373
  202. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -14,6 +14,10 @@ export interface RunnerSubagentStep {
14
14
  sessionName?: string;
15
15
  task: string;
16
16
  runner?: ResolvedRunnerConfig;
17
+ /** Herdr saved machine this external-cli step runs on; `cwd` is then the directory on that machine. */
18
+ machine?: import("../../shared/types.ts").HerdrMachineReference;
19
+ remoteReads?: string[] | false;
20
+ machineEnv?: Record<string, string>;
17
21
  externalJobFollowUp?: {
18
22
  sourceRunId: string;
19
23
  sourceStepIndex: number;
@@ -41,15 +45,18 @@ export interface RunnerSubagentStep {
41
45
  fast?: boolean;
42
46
  thinking?: string;
43
47
  thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
44
- modelCandidates?: string[];
48
+ requestedModel?: string;
45
49
  /** The primary model is inherited from the parent session and should not be verified against the child-reported active registry model. */
46
50
  skipPrimaryModelVerification?: boolean;
47
51
  modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
52
+ modelResponseAliases?: Record<string, string[]>;
48
53
  tools?: string[];
49
54
  excludeTools?: string[];
50
55
  allowNestedSubagents?: boolean;
51
56
  extensions?: string[];
52
57
  subagentOnlyExtensions?: string[];
58
+ /** Private immutable host policy snapshot serialized to the native runner. */
59
+ requiredExtensions?: import("../../shared/required-child-extensions.ts").RequiredChildExtensionSnapshot;
53
60
  mcpDirectTools?: string[];
54
61
  mutationTools?: string[];
55
62
  completionGuard?: boolean;
@@ -80,8 +87,8 @@ export interface RunnerSubagentStep {
80
87
  launchBindingTask?: string;
81
88
  launchContractDigest?: string;
82
89
  extensionBindings?: import("./extension-bindings.ts").ExtensionBindings;
83
- launchResolvedExtensions?: import("../../shared/types.ts").LaunchResolvedChildExtensionsV1;
84
- runtimeAcknowledgedExtensions?: import("../../shared/types.ts").RuntimeAcknowledgedChildExtensionsV1;
90
+ launchResolvedExtensions?: import("../../shared/types.ts").LaunchResolvedChildExtensions;
91
+ runtimeAcknowledgedExtensions?: import("../../shared/types.ts").RuntimeAcknowledgedChildExtensions;
85
92
  effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
86
93
  acceptanceInput?: import("../../shared/types.ts").AcceptanceInput;
87
94
  acceptanceRole?: import("../../shared/types.ts").AcceptanceRole;
@@ -242,7 +249,6 @@ export interface ParallelTaskResult {
242
249
  error?: string;
243
250
  timedOut?: boolean;
244
251
  model?: string;
245
- attemptedModels?: string[];
246
252
  outputTargetPath?: string;
247
253
  outputTargetExists?: boolean;
248
254
  }
@@ -49,6 +49,7 @@ export interface PiSpawnDeps {
49
49
  platform?: NodeJS.Platform;
50
50
  execPath?: string;
51
51
  argv1?: string;
52
+ bunVersion?: string;
52
53
  existsSync?: (filePath: string) => boolean;
53
54
  realpathSync?: (filePath: string) => string;
54
55
  readFileSync?: (filePath: string, encoding: "utf-8") => string;
@@ -58,6 +59,15 @@ export interface PiSpawnDeps {
58
59
  env?: NodeJS.ProcessEnv;
59
60
  }
60
61
 
62
+ /** Compiled Pi's entrypoint is virtual; execPath is the real (possibly renamed) image. */
63
+ export function resolveBunPiExecutable(deps: PiSpawnDeps = {}): string | undefined {
64
+ const bunVersion = deps.bunVersion ?? process.versions.bun;
65
+ const entry = deps.argv1 ?? process.argv[1];
66
+ if (!bunVersion || !entry || !/^(?:\/\$bunfs\/|B:[\\/]~BUN[\\/])/.test(entry)) return undefined;
67
+ const env = deps.env ?? process.env;
68
+ return env[PI_SUBAGENT_PI_BINARY_ENV]?.trim() || (deps.execPath ?? process.execPath);
69
+ }
70
+
61
71
  interface PiSpawnCommand {
62
72
  command: string;
63
73
  args: string[];
@@ -0,0 +1,42 @@
1
+ const knownStates = new Set(["queued", "running", "complete", "failed", "partial", "paused", "stopped", "rejected"]);
2
+
3
+ /**
4
+ * Private, installation-owned evidence. Never changes drain/query behavior or retains statuses.
5
+ * Observes the ordinary indexed drain, not historical ownership or outside work appearing later.
6
+ */
7
+ export class ReadonlyDrainObservation {
8
+ private state: "pending" | "empty" | "denied" = "pending";
9
+ private started = false;
10
+ private first = false;
11
+ private readonly file: string;
12
+ private readonly guard: () => boolean;
13
+ constructor(file: string, guard: () => boolean) { this.file = file; this.guard = guard; }
14
+ deny(): void { this.state = "denied"; }
15
+ check(): boolean {
16
+ try { if (!this.guard()) this.deny(); } catch { this.deny(); }
17
+ return this.state !== "denied";
18
+ }
19
+ begin(file: string | null, native: boolean): void {
20
+ if (this.started || file !== this.file || !native) this.deny();
21
+ this.started = true;
22
+ this.check();
23
+ }
24
+ /** Called at the existing initial read, before reconciliation or filtering. */
25
+ readonly status: RawDrainStatusObserver = (status) => {
26
+ if (!status || typeof status.sessionId !== "string" || !status.sessionId
27
+ || !knownStates.has(status.state as string)) this.deny();
28
+ else if (status.sessionId === this.file && (status.state === "queued" || status.state === "running")) this.deny();
29
+ };
30
+ predicate(hasWork: boolean): void {
31
+ if (this.first) return;
32
+ this.first = true;
33
+ if (hasWork) this.deny();
34
+ }
35
+ complete(): void {
36
+ if (this.started && this.first && this.check()) this.state = "empty";
37
+ }
38
+ settled(): boolean { return this.check() && this.state === "empty"; }
39
+ }
40
+
41
+ /** Internal synchronous sink; null means an existing query encountered uncertainty. */
42
+ export type RawDrainStatusObserver = (status: { sessionId?: unknown; state?: unknown } | null) => void;
@@ -11,14 +11,14 @@ import {
11
11
 
12
12
  const RUN_FANOUT_ROOT = path.join(TEMP_ROOT_DIR, "run-fanout-budgets");
13
13
 
14
- interface ManifestV1 {
14
+ interface FanoutBudgetManifest {
15
15
  version: 1;
16
16
  rootRunId: string;
17
17
  limit: number;
18
18
  createdAt: number;
19
19
  }
20
20
 
21
- interface ClaimV1 {
21
+ interface FanoutBudgetClaim {
22
22
  version: 1;
23
23
  claimId: string;
24
24
  path: string;
@@ -41,16 +41,16 @@ function safeRootRunId(rootRunId: string): string {
41
41
  return rootRunId.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || randomUUID();
42
42
  }
43
43
 
44
- function parseManifest(value: unknown): ManifestV1 | undefined {
44
+ function parseManifest(value: unknown): FanoutBudgetManifest | undefined {
45
45
  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
46
- const manifest = value as Partial<ManifestV1>;
46
+ const manifest = value as Partial<FanoutBudgetManifest>;
47
47
  if (manifest.version !== 1 || typeof manifest.rootRunId !== "string" || !manifest.rootRunId
48
48
  || !Number.isInteger(manifest.limit) || (manifest.limit ?? 0) <= 0
49
49
  || typeof manifest.createdAt !== "number" || !Number.isFinite(manifest.createdAt)) return undefined;
50
- return manifest as ManifestV1;
50
+ return manifest as FanoutBudgetManifest;
51
51
  }
52
52
 
53
- function readManifest(directory: string): ManifestV1 {
53
+ function readManifest(directory: string): FanoutBudgetManifest {
54
54
  let parsed: unknown;
55
55
  try {
56
56
  parsed = JSON.parse(fs.readFileSync(path.join(directory, "manifest.json"), "utf-8"));
@@ -84,7 +84,7 @@ export function createRunFanoutBudget(rootRunId: string, limit: number): RunFano
84
84
  do directory = path.join(RUN_FANOUT_ROOT, `${safeRootRunId(rootRunId)}-${randomUUID()}`);
85
85
  while (fs.existsSync(directory));
86
86
  fs.mkdirSync(path.join(directory, "claims"), { recursive: true, mode: 0o700 });
87
- const manifest: ManifestV1 = { version: 1, rootRunId, limit, createdAt: Date.now() };
87
+ const manifest: FanoutBudgetManifest = { version: 1, rootRunId, limit, createdAt: Date.now() };
88
88
  fs.writeFileSync(path.join(directory, "manifest.json"), `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: "wx" });
89
89
  return { version: 1, rootRunId, directory, limit };
90
90
  }
@@ -230,7 +230,7 @@ function commitRunFanoutBatch<T>(descriptor: RunFanoutBudgetDescriptor, paths: s
230
230
  const fd = fs.openSync(slotPath, "wx", 0o600);
231
231
  created.push(slotPath);
232
232
  try {
233
- const claim: ClaimV1 = { version: 1, claimId: randomUUID(), path: claimPath, claimedAt: Date.now() };
233
+ const claim: FanoutBudgetClaim = { version: 1, claimId: randomUUID(), path: claimPath, claimedAt: Date.now() };
234
234
  fs.writeFileSync(fd, `${JSON.stringify(claim)}\n`, "utf-8");
235
235
  } finally { fs.closeSync(fd); }
236
236
  break;
@@ -1,4 +1,4 @@
1
- import type { RuntimeAcknowledgedChildExtensionsV1 } from "../../shared/types.ts";
1
+ import type { RuntimeAcknowledgedChildExtensions } from "../../shared/types.ts";
2
2
 
3
3
  export const RUNTIME_EXTENSION_ACK_EVENT = "subagent:acknowledge-extension";
4
4
  export const MAX_RUNTIME_ACKNOWLEDGED_EXTENSION_IDS = 32;
@@ -14,7 +14,7 @@ export function isRuntimeAcknowledgedExtensionId(value: unknown): value is strin
14
14
  && !value.includes("\\");
15
15
  }
16
16
 
17
- export function projectRuntimeAcknowledgedExtensions(ids: Iterable<unknown>): RuntimeAcknowledgedChildExtensionsV1 | undefined {
17
+ export function projectRuntimeAcknowledgedExtensions(ids: Iterable<unknown>): RuntimeAcknowledgedChildExtensions | undefined {
18
18
  const unique: string[] = [];
19
19
  const seen = new Set<string>();
20
20
  for (const id of ids) {
@@ -31,7 +31,7 @@ export function projectRuntimeAcknowledgedExtensions(ids: Iterable<unknown>): Ru
31
31
  };
32
32
  }
33
33
 
34
- export function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAcknowledgedChildExtensionsV1 | undefined {
34
+ export function sanitizeRuntimeAcknowledgedExtensions(value: unknown): RuntimeAcknowledgedChildExtensions | undefined {
35
35
  if (!value || typeof value !== "object") return undefined;
36
36
  const raw = value as Record<string, unknown>;
37
37
  if (raw.version !== 1 || raw.source !== "child-runtime" || !Array.isArray(raw.ids)) return undefined;
@@ -17,6 +17,7 @@ import { registerChildWatchdog } from "../../watchdog/register-child.ts";
17
17
  import type { ChildWatchdogConfig } from "../../watchdog/child-status.ts";
18
18
  import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
19
19
  import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
20
+ import { inheritedNestedRouteOf } from "./nested-events.ts";
20
21
  import { registerWaitTool } from "../background/wait-tool.ts";
21
22
  import { drainOutstandingWork } from "../background/auto-drain.ts";
22
23
  import {
@@ -441,15 +442,21 @@ function registerStructuredOutputTool(pi: ExtensionAPI, structured: NonNullable<
441
442
  }
442
443
 
443
444
  /** Register every child-side hook the prompt runtime owns for one child session. */
444
- export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config: ChildRuntimeConfig): void {
445
+ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?: ChildRuntimeConfig, drainObservation?: import("./readonly-drain-observation.ts").ReadonlyDrainObservation): void {
446
+ // A path-based load has no ChildRuntimeConfig. This can happen if an
447
+ // ambient-extension discovery path finds the runtime module in addition to
448
+ // the configured inline factory. It must be inert rather than crashing the
449
+ // child before startup; the inline factory remains the real registration path.
450
+ if (!config) return;
445
451
  registerRuntimeExtensionAcknowledgements(pi, config.runtimeAcknowledgements);
446
452
  registerPermissionGate(pi, config.permissions, config.childWatchdog);
447
453
  registerToolBudget(pi, config.toolBudget);
448
454
  registerChildWatchdog(pi, config.childWatchdog, config.watchdogStatus);
449
- const waitState = {
455
+ const waitState = config.runtimeState ?? {
450
456
  baseCwd: "",
451
457
  currentSessionId: null,
452
458
  asyncJobs: new Map(),
459
+ foregroundRuns: new Map(),
453
460
  foregroundControls: new Map(),
454
461
  lastForegroundControlId: null,
455
462
  cleanupTimers: new Map(),
@@ -460,7 +467,8 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config:
460
467
  watcherRestartTimer: null,
461
468
  resultFileCoalescer: { schedule: () => false, clear: () => {} },
462
469
  } as unknown as SubagentState;
463
- if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs);
470
+ const nestedRootRunId = inheritedNestedRouteOf(config)?.rootRunId;
471
+ if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs, { nestedRootRunId });
464
472
  const supervisorMetadata = childSupervisorMetadata(config);
465
473
  let nativeSupervisorClientRegistered = false;
466
474
  const registerNativeSupervisorClientOnce = (): void => {
@@ -481,8 +489,18 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config:
481
489
  if (diagnostic) throw new Error(formatChildToolDiagnostic(diagnostic));
482
490
  });
483
491
  onRuntimeEvent("agent_end", async (_event: unknown, ctx: unknown) => {
484
- if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) return;
485
- await drainOutstandingWork({ state: waitState, events: pi.events });
492
+ if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) drainObservation?.deny();
493
+ if (drainObservation) {
494
+ try {
495
+ if ((ctx as ExtensionContext)?.sessionManager?.getSessionFile() !== waitState.currentSessionId) drainObservation.deny();
496
+ } catch { drainObservation.deny(); }
497
+ }
498
+ config.holdFinalDrain?.(true);
499
+ try {
500
+ await drainOutstandingWork({ state: waitState, events: pi.events, nestedRootRunId, hasPendingSupervisorRequest: config.hasPendingSupervisorRequest }, drainObservation);
501
+ } finally {
502
+ config.holdFinalDrain?.(false);
503
+ }
486
504
  });
487
505
  if (config.structuredOutput) registerStructuredOutputTool(pi, config.structuredOutput);
488
506
 
@@ -7,6 +7,7 @@
7
7
  * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
8
8
  * task REQUIRE file changes? Consumed by the completion mutation guard,
9
9
  * which blocks completion, so its vocabulary is deliberately narrow.
10
+ * Verbs inside filenames and path-like tokens do not count.
10
11
  * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
11
12
  * acceptance level inference, which only raises evidence gates, so its
12
13
  * vocabulary is deliberately broad (any bare write verb).
@@ -18,16 +19,20 @@
18
19
  */
19
20
 
20
21
  const REVIEW_ONLY_PATTERNS = [
21
- /\breview only\b/i,
22
+ /\b(?:review|read)[- ]only\b/i,
23
+ /\bno\s+(?:source\s+)?edits?\b/i,
24
+ /\bwithout\s+edits?\b/i,
22
25
  /\bsuggest fixes only\b/i,
23
26
  /\bonly return findings\b/i,
24
27
  /\breturn findings only\b/i,
25
28
  ];
26
29
 
30
+ const NO_EDIT_BOUNDARY_ASSERTION_PATTERN = /\bno\s+(?:source\s+)?edits?\s*,\s*(?:commits?|pushes?|merges?|installs?|changes?|writes?)\b/i;
31
+
27
32
  const REVIEWER_REQUIRED_EDIT_PATTERNS = [
28
33
  /\bmust\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
29
34
  /\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
30
- /(?:^|[.!?\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
35
+ /(?:^|[.!?:;,\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
31
36
  /\bregardless\s+of\s+findings\b/i,
32
37
  /\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
33
38
  /\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
@@ -40,7 +45,7 @@ const REVIEWER_REQUIRED_EDIT_PATTERNS = [
40
45
  // being swallowed as the object.
41
46
  // Accept serialized line separators too: workflow prompts can carry literal
42
47
  // `\\n`/`\\r\\n` between clauses instead of decoded newlines.
43
- const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
48
+ const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change|implement)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
44
49
  const COORDINATED_NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+((?=(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b)(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*?\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b(?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
45
50
 
46
51
  /** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
@@ -85,13 +90,25 @@ const RESEARCH_AGENT_PATTERNS = [
85
90
  // CLI flags like "--fix" and genuine clause-level dashes like "branch—fix it"),
86
91
  // strip the known severity compounds (must|should|needs + dash + verb) from the
87
92
  // task text before matching. Dash coverage: ASCII hyphen + U+2010..U+2015.
88
- const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[\-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
93
+ const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
89
94
 
90
95
  function stripSeverityCompounds(task: string): string {
91
96
  return task.replace(SEVERITY_COMPOUND_PATTERN, " ");
92
97
  }
93
98
  export { stripSeverityCompounds };
94
99
 
100
+ // Quoted categories in a finding-classification request describe fixes, not
101
+ // instructions to perform them. Strip only that request, leaving sibling
102
+ // imperatives (including another "must fix") subject to the normal guards.
103
+ const FINDING_CLASSIFICATION_PATTERN = /\b(?:classify|categorize|weigh)\s+(?:(?:the|remaining)\s+)*(?:findings?|items?|issues?)\s+as\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]\s+(?:vs\.?|versus)\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]/gi;
104
+
105
+ const PATH_LIKE_TOKEN_PATTERN = /[^\s]+[/\\][^\s]+|[^\s/\\]+\.[A-Za-z][A-Za-z0-9]{0,9}\b/g;
106
+ const PATH_INTERNAL_IMPLEMENTATION_VERB = /\b(?:implement|edit|modify|refactor|delete|update|add|remove|replace|create)\b/i;
107
+
108
+ function stripPathLikeTokens(task: string): string {
109
+ return task.replace(PATH_LIKE_TOKEN_PATTERN, (token) => (PATH_INTERNAL_IMPLEMENTATION_VERB.test(token) ? " " : token));
110
+ }
111
+
95
112
  const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
96
113
 
97
114
  const WORKER_IMPLEMENTATION_PATTERNS = [
@@ -103,12 +120,18 @@ const WORKER_IMPLEMENTATION_PATTERNS = [
103
120
  /\bdo those fixes\b/i,
104
121
  ];
105
122
 
106
- const GENERAL_IMPLEMENTATION_PATTERNS = [
123
+ const FOLLOW_ON_IMPLEMENTATION_PATTERN = /(?:^|[.!?:;,\n])\s*(?:fix|patch|update|add|remove|replace|create|delete)\s+(?:(?:the|a|an|this|that|these|those|requested|specified|current|existing|approved|your|our)\s+)(?!(?:report|summary|findings?|analysis|recommendations?|answer|response|proposal|plan|issue|bug report)\b)[a-z][\w./-]*/i;
124
+ const ADVISORY_INFINITIVE_PATTERN = /\b(?:explain|recommend|describe)\s+how\s+to\s+(?:fix|patch|update|add|remove|replace|create|delete|implement|edit|modify|refactor)\b/i;
125
+ const EXPLICIT_IMPLEMENTATION_PATTERNS = [
107
126
  /\b(?:implement|edit|modify|refactor)\b/i,
108
- FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
109
127
  /\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
110
128
  /\bmake\s+(?:the\s+)?changes\b/i,
111
129
  /\bdo those fixes\b/i,
130
+ ];
131
+
132
+ const GENERAL_IMPLEMENTATION_PATTERNS = [
133
+ ...EXPLICIT_IMPLEMENTATION_PATTERNS,
134
+ FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
112
135
  /\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
113
136
  ];
114
137
 
@@ -141,10 +164,13 @@ interface NoEditProhibitionAnalysis {
141
164
  }
142
165
 
143
166
  function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis {
167
+ const readOnlyBoundary = NO_EDIT_BOUNDARY_ASSERTION_PATTERN.test(taskText);
144
168
  let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
145
- || NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
146
- let blanket = present;
147
- let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
169
+ || NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText))
170
+ || readOnlyBoundary;
171
+ let blanket = false;
172
+ let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS, ADVISORY_INFINITIVE_PATTERN]);
173
+ if (readOnlyBoundary) strippedText = stripPatterns(strippedText, [NO_EDIT_BOUNDARY_ASSERTION_PATTERN]);
148
174
  const stripNoEditProhibition = (match: string, object: string, offset: number, source: string): string => {
149
175
  present = true;
150
176
  if (GENERIC_PROHIBITION_OBJECT.test(object) && !hasScopedProhibitionContinuation(source.slice(offset + match.length))) blanket = true;
@@ -172,16 +198,23 @@ function hasImplementationIntent(agent: string, taskText: string): boolean {
172
198
  }
173
199
 
174
200
  export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
175
- const taskText = stripSeverityCompounds(stripFrameworkInstructions(task));
201
+ const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN]);
176
202
  const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
177
203
  const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
178
204
  if (prohibitions.present) {
179
205
  if (prohibitions.blanket) return { kind: "read-only" };
180
- return hasImplementationIntent(agent, prohibitions.strippedText) ? { kind: "implementation" } : { kind: "read-only" };
206
+ const remaining = stripPathLikeTokens(prohibitions.strippedText);
207
+ if (isReviewerStyleAgent(agent)) {
208
+ return hasImplementationIntent(agent, remaining) ? { kind: "implementation" } : { kind: "read-only" };
209
+ }
210
+ return EXPLICIT_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(remaining))
211
+ || FOLLOW_ON_IMPLEMENTATION_PATTERN.test(remaining)
212
+ ? { kind: "implementation" }
213
+ : { kind: "read-only" };
181
214
  }
182
215
 
183
216
  if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
184
- if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
217
+ if (hasImplementationIntent(agent, stripPathLikeTokens(taskText))) return { kind: "implementation" };
185
218
  if (isReviewerStyleAgent(agent)) return { kind: "read-only" };
186
219
  return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
187
220
  }
@@ -204,7 +237,7 @@ const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|mig
204
237
  * does.
205
238
  */
206
239
  export function taskMayMutate(task: string): boolean {
207
- const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
240
+ const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN, ...SCOPED_NO_EDIT_CONSTRAINT_PATTERNS]);
208
241
  const prohibitions = analyzeNoEditProhibitions(taskText);
209
242
  if (prohibitions.blanket) return false;
210
243
  return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));
@@ -0,0 +1,18 @@
1
+ import type { AsyncStatus, SubagentState } from "../../shared/types.ts";
2
+
3
+ /** Projection-only guidance, not a control route or proof of current child liveness. */
4
+ export function workflowAsyncChildSteeringGuidance(status: AsyncStatus, state?: SubagentState): string[] {
5
+ if (status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")
6
+ || !state?.currentSessionId || status.sessionId !== state.currentSessionId
7
+ || !state.workflowControllers?.has(status.runId)) return [];
8
+ const ids = new Set((status.steps ?? []).flatMap((step) =>
9
+ step.async === true && step.status === "running"
10
+ && step.runner?.type !== "external-cli" && step.runner?.type !== "external-job"
11
+ && typeof step.runId === "string" && /^[A-Za-z0-9_-]+$/.test(step.runId) && step.runId !== status.runId
12
+ ? [step.runId] : []));
13
+ if (ids.size === 0) return [];
14
+ return [
15
+ "Async children recorded as running; direct steering rechecks controls. Choose an exact child ID (queued does not mean consumed):",
16
+ ...[...ids].map((id) => ` subagent({ action: "steer", id: "${id}", mode: "follow_up", message: "..." })`),
17
+ ];
18
+ }
@@ -15,6 +15,7 @@ import type {
15
15
  } from "../../shared/types.ts";
16
16
  import { getAgentDir } from "../../shared/utils.ts";
17
17
  import { isTerminalParallelHandoffChildStatus } from "./parallel-handoff.ts";
18
+ import { MACHINE_DIFF_OPTIONS, validateWorktreePatchRepresentsCurrentWorktree } from "./worktree.ts";
18
19
 
19
20
  export const WORKTREE_CLEANUP_PLAN_VERSION = 1 as const;
20
21
  export const WORKTREE_CLEANUP_PLAN_TTL_MS = 30 * 60 * 1000;
@@ -572,7 +573,7 @@ function resolveBranchTip(repoRoot: string, branch: string): { value?: string; e
572
573
  return { value: result.stdout.trim() };
573
574
  }
574
575
 
575
- function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string): { path?: string; error?: string } {
576
+ function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string, baseCommit: string): { path?: string; error?: string } {
576
577
  const patchPath = metadataPatchPath(record);
577
578
  if (!patchPath || record.child.patch?.error !== undefined || record.child.patch?.changed !== true) return {};
578
579
  const inspection = inspectPath(patchPath);
@@ -587,6 +588,8 @@ function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string):
587
588
  if (!patchStat.isFile()) return { error: "captured handoff patch is not a file" };
588
589
  if (pathInside(worktreePath, inspection.realpath)) return { error: "durable handoff patch lives inside the worktree" };
589
590
  if (patchStat.size <= 0) return { error: "captured handoff patch is empty" };
591
+ const validationError = validateWorktreePatchRepresentsCurrentWorktree(worktreePath, baseCommit, patchPath);
592
+ if (validationError) return { error: `captured handoff patch failed validation: ${validationError}` };
590
593
  return { path: patchPath };
591
594
  }
592
595
 
@@ -665,14 +668,14 @@ function buildManagedEntry(input: {
665
668
  entry.preconditions.statusDigest = status.digest;
666
669
  if (status.output && status.output.trim()) return blockedEntry(entry, "dirty", "keep", "worktree has uncommitted or untracked changes");
667
670
 
668
- const diff = runGit(worktreePath, ["diff", "--quiet", resolvedBase.value, "--"]);
671
+ const diff = runGit(worktreePath, ["diff", "--quiet", ...MACHINE_DIFF_OPTIONS, resolvedBase.value, "--"]);
669
672
  if (diff.status !== 0 && diff.status !== 1) return blockedEntry(entry, "unknown", "unknown", `git diff safety check failed: ${gitFailure(diff, "git diff")}`);
670
673
  const ancestor = runGit(repoRoot, ["merge-base", "--is-ancestor", git.head, targetHead]);
671
674
  if (ancestor.status !== 0 && ancestor.status !== 1) return blockedEntry(entry, "unknown", "unknown", `local merge safety check failed: ${gitFailure(ancestor, "git merge-base --is-ancestor")}`);
672
675
  const branchTipIsAncestor = ancestor.status === 0;
673
676
  let divergenceSafe = diff.status === 0;
674
677
  if (!divergenceSafe) {
675
- const captured = isPatchCaptured(record, worktreePath);
678
+ const captured = isPatchCaptured(record, worktreePath, resolvedBase.value);
676
679
  if (captured.error) return blockedEntry(entry, "ineligible", "keep", captured.error);
677
680
  if (captured.path) {
678
681
  entry.patchPath = captured.path;