@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
@@ -7,6 +7,7 @@ import { createHash } from "node:crypto";
7
7
  import * as fs from "node:fs";
8
8
  import * as path from "node:path";
9
9
  import { fileURLToPath } from "node:url";
10
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
10
11
  import {
11
12
  formatUnresolvedMcpDirectToolSelectors,
12
13
  resolveMcpDirectToolResolution,
@@ -16,13 +17,13 @@ import {
16
17
  import {
17
18
  TEMP_ROOT_DIR,
18
19
  type JsonSchemaObject,
19
- type LaunchResolvedChildExtensionsV1,
20
+ type LaunchResolvedChildExtensions,
20
21
  } from "../../shared/types.ts";
21
22
  import { THINKING_LEVELS } from "../../shared/model-info.ts";
22
23
  import { getAgentDir } from "../../shared/utils.ts";
23
- import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
24
- import { validatePermissionProfileName } from "../../shared/permission-profile.ts";
25
24
  import type { PermissionRules } from "./permissions.ts";
25
+ import { resolveProfileExtensions } from "./profile-extensions.ts";
26
+ import { snapshotRequiredChildExtensions, type RequiredChildExtensionSnapshot } from "../../shared/required-child-extensions.ts";
26
27
  import {
27
28
  capabilityCeilingAgentRestrictionSources,
28
29
  intersectSubagentCapabilityCeilings,
@@ -34,18 +35,18 @@ import {
34
35
  const MAX_LAUNCH_RESOLVED_EXTENSION_IDS = 32;
35
36
  const PROMPT_RUNTIME_EXTENSION_PATH = path.join(
36
37
  path.dirname(fileURLToPath(import.meta.url)),
37
- "subagent-prompt-runtime.ts",
38
+ `subagent-prompt-runtime${path.extname(fileURLToPath(import.meta.url))}`,
38
39
  );
39
40
  const FANOUT_CHILD_EXTENSION_PATH = path.join(
40
41
  path.dirname(fileURLToPath(import.meta.url)),
41
42
  "..",
42
43
  "..",
43
44
  "extension",
44
- "fanout-child.ts",
45
+ `fanout-child${path.extname(fileURLToPath(import.meta.url))}`,
45
46
  );
46
47
  const FAST_MODE_EXTENSION_PATH = path.join(
47
48
  path.dirname(fileURLToPath(import.meta.url)),
48
- "fast-mode-extension.ts",
49
+ `fast-mode-extension${path.extname(fileURLToPath(import.meta.url))}`,
49
50
  );
50
51
  const SANDBOX_PROFILE_GUARD_EXTENSION_PATH = path.join(
51
52
  path.dirname(fileURLToPath(import.meta.url)),
@@ -66,6 +67,39 @@ const FAST_MODE_ALLOWED_MODELS = new Set([
66
67
  "openai-codex/gpt-5.6-sol",
67
68
  ]);
68
69
  const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
70
+ const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
71
+ const REPOSITORY_INSPECTION_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "powershell"]);
72
+ const REVIEW_OR_SCOUT_AGENT_PATTERN = /\b(?:reviewer|scout)\b/i;
73
+
74
+ export function isReviewOrScoutLaneAgent(agentName: string | undefined): boolean {
75
+ return typeof agentName === "string" && REVIEW_OR_SCOUT_AGENT_PATTERN.test(agentName);
76
+ }
77
+
78
+ export function missingPermittedRepositoryInspectionTools(
79
+ unavailableHostBuiltins: readonly string[],
80
+ excludeTools: readonly string[] = [],
81
+ ): string[] {
82
+ const excluded = new Set(excludeTools);
83
+ return unavailableHostBuiltins.filter((tool) => REPOSITORY_INSPECTION_TOOLS.has(tool) && !excluded.has(tool));
84
+ }
85
+
86
+ export function formatReviewLaneToolContractFailure(input: {
87
+ agentName?: string;
88
+ missingTools: readonly string[];
89
+ requestedTools?: readonly string[];
90
+ effectiveTools: readonly string[];
91
+ ceilingSources?: readonly string[];
92
+ excludeTools?: readonly string[];
93
+ }): string {
94
+ const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
95
+ return [
96
+ `${subject}: tool contract could not be satisfied; host runtime does not provide permitted required repository tools [${input.missingTools.join(", ")}].`,
97
+ `Requested tool names: ${input.requestedTools ? `[${input.requestedTools.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${input.effectiveTools.join(", ")}].`,
98
+ ...(input.ceilingSources?.length ? [`Active capability ceiling sources: [${input.ceilingSources.join(", ")}].`] : []),
99
+ ...(input.excludeTools?.length ? [`Explicit excludeTools: [${input.excludeTools.join(", ")}].`] : []),
100
+ "This is a lane infrastructure failure, not a completed review/scout result.",
101
+ ].join(" ");
102
+ }
69
103
 
70
104
  export function deriveForkPromptCacheKey(parentSessionId: string | undefined): string | undefined {
71
105
  const parent = parentSessionId?.trim();
@@ -119,9 +153,9 @@ function stripThinkingSuffix(model: string): string {
119
153
  : model;
120
154
  }
121
155
 
122
- function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fast" | "model" | "modelCandidates" | "agentName">): string[] {
156
+ function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fast" | "model" | "agentName">): string[] {
123
157
  if (!input.fast) return [];
124
- const candidates = (input.modelCandidates?.length ? input.modelCandidates : input.model ? [input.model] : [])
158
+ const candidates = (input.model ? [input.model] : [])
125
159
  .map(stripThinkingSuffix);
126
160
  if (candidates.length === 0) {
127
161
  throw new Error(`fast mode requires an explicit supported native OpenAI-Codex model${input.agentName ? ` for agent '${input.agentName}'` : ""}.`);
@@ -139,6 +173,7 @@ export interface ResolvePiLaunchToolPlanInput {
139
173
  allowNestedSubagents?: boolean;
140
174
  extensions?: string[];
141
175
  subagentOnlyExtensions?: string[];
176
+ requiredExtensions?: RequiredChildExtensionSnapshot;
142
177
  mcpDirectTools?: string[];
143
178
  cwd?: string;
144
179
  requireReadTool?: boolean;
@@ -151,7 +186,6 @@ export interface ResolvePiLaunchToolPlanInput {
151
186
  };
152
187
  fast?: boolean;
153
188
  model?: string;
154
- modelCandidates?: readonly string[];
155
189
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
156
190
  inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
157
191
  agentName?: string;
@@ -161,7 +195,17 @@ export interface ResolvePiLaunchToolPlanInput {
161
195
  sandbox?: string;
162
196
  /** A validated global pi-permission-system profile selected by the agent definition. */
163
197
  permissionProfile?: string;
164
- }
198
+
199
+ /**
200
+ * When provided, child tool plans intersect known Pi core tool slots with
201
+ * this set. Core tools the agent declares but the host does not provide are
202
+ * omitted with a non-fatal warning (tracked in `unavailableHostBuiltins`).
203
+ * Review/scout lanes fail closed when a requested, still-permitted
204
+ * repository inspection tool is among those host omissions. Intentionally
205
+ * empty or ceiling-restricted allowlists are not a minimum-tool contract.
206
+ * Non-core names remain allowed and are validated in the child's registry.
207
+ */
208
+ hostAvailableBuiltins?: readonly string[];}
165
209
 
166
210
  export interface PiLaunchToolPlan {
167
211
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -181,11 +225,14 @@ export interface PiLaunchToolPlan {
181
225
  sandboxExtension?: string;
182
226
  runtimeExtensions: string[];
183
227
  configuredExtensions: string[];
228
+ requiredExtensions: RequiredChildExtensionSnapshot;
184
229
  extensionArgs: string[];
185
230
  disableAmbientExtensions: boolean;
186
231
  capabilityAudit?: SubagentCapabilityAudit;
187
232
  /** Non-fatal launch warnings; they do not change behavior. */
188
233
  warnings: string[];
234
+ /** Builtin tools the agent declared but the host runtime does not provide. */
235
+ unavailableHostBuiltins: string[];
189
236
  }
190
237
 
191
238
  function extensionIdentifier(value: string): string {
@@ -223,10 +270,11 @@ export function projectLaunchResolvedChildExtensions(
223
270
  PiLaunchToolPlan,
224
271
  | "runtimeExtensions"
225
272
  | "configuredExtensions"
273
+ | "requiredExtensions"
226
274
  | "extensionArgs"
227
275
  | "disableAmbientExtensions"
228
276
  >,
229
- ): LaunchResolvedChildExtensionsV1 {
277
+ ): LaunchResolvedChildExtensions {
230
278
  const runtime = boundedExtensionIdentifiers(toolPlan.runtimeExtensions);
231
279
  const configured = boundedExtensionIdentifiers(toolPlan.configuredExtensions);
232
280
  const effective = boundedExtensionIdentifiers(toolPlan.extensionArgs);
@@ -236,10 +284,12 @@ export function projectLaunchResolvedChildExtensions(
236
284
  disableAmbientExtensions: toolPlan.disableAmbientExtensions,
237
285
  runtime: runtime.ids,
238
286
  configured: configured.ids,
287
+ required: toolPlan.requiredExtensions.map(({ id }) => id),
239
288
  effective: effective.ids,
240
289
  omitted: {
241
290
  runtime: runtime.omitted,
242
291
  configured: configured.omitted,
292
+ required: 0,
243
293
  effective: effective.omitted,
244
294
  },
245
295
  };
@@ -311,70 +361,30 @@ export function resolvePermissionSystemExtension(): string | undefined {
311
361
  return undefined;
312
362
  }
313
363
 
314
- export function resolveSandboxExtensionForProfile(profileName: string): string {
315
- validateSandboxProfileName(profileName, "sandbox profile");
316
- return resolveSandboxExtension();
317
- }
318
-
319
- function resolveSandboxExtension(): string {
320
- const agentDir = getAgentDir();
321
- const candidates = [
322
- path.join(agentDir, "npm", "node_modules", "@xzzpig", "pi-sandbox"),
323
- path.join(agentDir, "npm", "node_modules", "pi-sandbox"),
324
- path.join(agentDir, "extensions", "pi-sandbox"),
325
- ];
326
- const errors: Error[] = [];
327
- let foundPackage = false;
328
- for (const extDir of candidates) {
329
- if (!fs.existsSync(extDir)) continue;
330
- foundPackage = true;
331
- const pkgPath = path.join(extDir, "package.json");
332
- if (!fs.existsSync(pkgPath)) {
333
- errors.push(new Error(`Sandbox package manifest is missing at ${pkgPath}.`));
334
- continue;
335
- }
336
- try {
337
- const parsed: unknown = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
338
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
339
- throw new Error("manifest root must be an object");
340
- }
341
- const manifest = parsed as { name?: unknown; pi?: { extensions?: unknown } };
342
- if (manifest.name !== "@xzzpig/pi-sandbox" && manifest.name !== "pi-sandbox") {
343
- throw new Error(`Sandbox package manifest at ${pkgPath} must declare name '@xzzpig/pi-sandbox' or 'pi-sandbox'.`);
344
- }
345
- const extensions = manifest.pi?.extensions;
346
- const entry = Array.isArray(extensions) ? extensions[0] : undefined;
347
- if (typeof entry !== "string" || !entry.trim()) {
348
- throw new Error(`Sandbox package manifest at ${pkgPath} must declare pi.extensions[0] as a non-empty string.`);
349
- }
350
- if (path.isAbsolute(entry)) {
351
- throw new Error(`Sandbox extension entry ${JSON.stringify(entry)} in ${pkgPath} must be relative to the package directory.`);
352
- }
353
- const resolved = path.resolve(extDir, entry);
354
- const relative = path.relative(extDir, resolved);
355
- if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
356
- throw new Error(`Sandbox extension entry ${JSON.stringify(entry)} in ${pkgPath} must remain inside ${extDir}.`);
357
- }
358
- if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
359
- throw new Error(`Sandbox extension entry ${JSON.stringify(entry)} in ${pkgPath} does not resolve to a file at ${resolved}.`);
360
- }
361
- const realPackageRoot = fs.realpathSync(extDir);
362
- const realEntry = fs.realpathSync(resolved);
363
- const realRelative = path.relative(realPackageRoot, realEntry);
364
- if (!realRelative || realRelative === ".." || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)) {
365
- throw new Error(`Sandbox extension entry ${JSON.stringify(entry)} in ${pkgPath} resolves outside ${extDir}.`);
366
- }
367
- return resolved;
368
- } catch (error) {
369
- const message = error instanceof Error ? error.message : String(error);
370
- errors.push(message.startsWith("Sandbox") ? new Error(message) : new Error(`Cannot read sandbox package manifest at ${pkgPath}: ${message}`));
371
- }
372
- }
373
- if (errors.length > 0) throw errors[0]!;
374
- if (!foundPackage) {
375
- throw new Error(`pi-sandbox is not installed; cannot launch a child with sandbox profile.`);
364
+ /**
365
+ * Extract the names of builtin tools the host provides. Use this to pass
366
+ * `hostAvailableBuiltins` to `resolvePiLaunchToolPlan` so child tool plans
367
+ * intersect known core slots with what the host actually supports. Wrapped
368
+ * core slots count regardless of source; host-specific builtins count too.
369
+ *
370
+ * Returns `undefined` when builtin tool discovery fails or yields nothing,
371
+ * so callers skip the intersection (fail-safe to allowing all declared tools).
372
+ * This handles test mocks without proper tool registration and hosts whose
373
+ * getAllTools() throws before extensions load.
374
+ */
375
+ export function getHostBuiltinToolNames(pi: Pick<ExtensionAPI, "getAllTools">): string[] | undefined {
376
+ try {
377
+ const builtins = pi
378
+ .getAllTools()
379
+ .filter((tool) => {
380
+ const source = (tool.sourceInfo as { source?: string } | undefined)?.source;
381
+ return source === "builtin" || PI_BUILTIN_TOOL_NAMES.has(tool.name);
382
+ })
383
+ .map((tool) => tool.name);
384
+ return builtins.length > 0 ? builtins : undefined;
385
+ } catch {
386
+ return undefined;
376
387
  }
377
- throw new Error(`No usable pi-sandbox extension manifest was found under '${agentDir}'.`);
378
388
  }
379
389
 
380
390
  export function resolvePiLaunchToolPlan(
@@ -384,21 +394,35 @@ export function resolvePiLaunchToolPlan(
384
394
  input.capabilityCeiling,
385
395
  input.inheritedCapabilityCeiling,
386
396
  );
397
+ const requiredExtensions = snapshotRequiredChildExtensions(input.requiredExtensions ?? []);
398
+ if (requiredExtensions.length > 0 && capabilityCeiling?.denyExtensions) {
399
+ throw new Error(`Capability ceiling from ${capabilityCeiling.sources.join(", ") || "unknown source"} denies extensions but this host requires: ${requiredExtensions.map(({ id }) => id).join(", ")}.`);
400
+ }
387
401
  const allowedToolSet =
388
402
  capabilityCeiling?.allowedTools === undefined
389
403
  ? undefined
390
404
  : new Set(capabilityCeiling.allowedTools);
405
+ const hostAvailableSet =
406
+ input.hostAvailableBuiltins === undefined
407
+ ? undefined
408
+ : new Set(input.hostAvailableBuiltins);
391
409
  const requestedBuiltinTools =
392
410
  input.tools?.filter(
393
411
  (tool) =>
394
412
  !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")),
395
413
  ) ?? [];
414
+ if (input.requireReadTool && hostAvailableSet && !hostAvailableSet.has("read")) {
415
+ const agentLabel = input.agentName ? ` for agent '${input.agentName}'` : "";
416
+ throw new Error(
417
+ `Host runtime does not provide required tool 'read'${agentLabel} for lazy skill loading.`,
418
+ );
419
+ }
396
420
  if (input.requireReadTool && allowedToolSet && !allowedToolSet.has("read")) {
397
421
  throw new Error(
398
422
  `Capability ceiling from ${capabilityCeiling?.sources.join(", ") || "unknown source"} excludes required tool 'read' for lazy skill loading.`,
399
423
  );
400
424
  }
401
- const declaredBuiltinTools =
425
+ const ceilingFilteredBuiltinTools =
402
426
  input.tools === undefined
403
427
  ? allowedToolSet
404
428
  ? [...allowedToolSet]
@@ -410,6 +434,12 @@ export function resolvePiLaunchToolPlan(
410
434
  ? ["read", ...requestedBuiltinTools]
411
435
  : requestedBuiltinTools
412
436
  ).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
437
+ const declaredBuiltinTools = hostAvailableSet
438
+ ? ceilingFilteredBuiltinTools.filter((tool) => !PI_BUILTIN_TOOL_NAMES.has(tool) || hostAvailableSet.has(tool))
439
+ : ceilingFilteredBuiltinTools;
440
+ const unavailableHostBuiltins = hostAvailableSet
441
+ ? ceilingFilteredBuiltinTools.filter((tool) => PI_BUILTIN_TOOL_NAMES.has(tool) && !hostAvailableSet.has(tool))
442
+ : [];
413
443
  const excludeTools = [...new Set((input.excludeTools ?? []).map((tool) => tool.trim()).filter(Boolean))];
414
444
  const excludedToolSet = new Set(excludeTools);
415
445
  const effectiveDeclaredBuiltinTools = declaredBuiltinTools.filter((tool) => !excludedToolSet.has(tool));
@@ -418,6 +448,9 @@ export function resolvePiLaunchToolPlan(
418
448
  !excludedToolSet.has("subagent") &&
419
449
  (!allowedToolSet || allowedToolSet.has("subagent"))
420
450
  );
451
+ if (effectiveDeclaredBuiltinTools.includes("subagent_supervisor") && !fanoutAuthorized) {
452
+ throw new Error("Tool 'subagent_supervisor' requires fanout authorization: include 'subagent' in the effective tools allowlist or enable allowNestedSubagents.");
453
+ }
421
454
  const toolExtensionPaths: string[] = capabilityCeiling?.denyExtensions
422
455
  ? []
423
456
  : (input.tools ?? []).filter(
@@ -458,8 +491,8 @@ export function resolvePiLaunchToolPlan(
458
491
  ...internalTools,
459
492
  ]),
460
493
  ];
461
- // Supervisor-coordination names stay in the --tools allowlist but are never
462
- // strict requirements: children register contact_supervisor at runtime through
494
+ // Upward contact stays in the --tools allowlist but is not a strict
495
+ // requirement: children register contact_supervisor at runtime through
463
496
  // the native supervisor channel (or pi-intercom). The pre-0.50 bridge always
464
497
  // appended intercom alongside contact_supervisor, so that exact pairing is
465
498
  // legacy plumbing, not a user demand for an external intercom provider;
@@ -479,41 +512,14 @@ export function resolvePiLaunchToolPlan(
479
512
  : hasPermissionRules(input.permissionRules)
480
513
  ? resolvePermissionSystemExtension()
481
514
  : undefined;
482
- const sandboxProfile = input.sandbox === undefined
483
- ? undefined
484
- : validateSandboxProfileName(input.sandbox, "sandbox profile");
485
- if (sandboxProfile && capabilityCeiling?.denyExtensions) {
486
- throw new Error(`Sandbox profile '${sandboxProfile}' requires the pi-sandbox child extension, but this launch denies child extensions.`);
487
- }
488
- const permissionProfile = input.permissionProfile === undefined
489
- ? undefined
490
- : validatePermissionProfileName(input.permissionProfile, "permission profile");
491
- if (permissionProfile && capabilityCeiling?.denyExtensions) {
492
- throw new Error(`Permission profile '${permissionProfile}' requires the pi-permission-system child extension, but this launch denies child extensions.`);
493
- }
494
- // A permission-profile-only agent has no native `permissionRules` yet still
495
- // needs the permission system in the child to resolve the profile: without
496
- // it the selection would silently degrade to no policy at all. Resolve the
497
- // extension eagerly for this path and fail the launch when the package is
498
- // missing (the rules-only path keeps its soft resolution as before).
499
- const permSystemExtForProfile = permissionProfile !== undefined && permSystemExt === undefined
500
- ? resolvePermissionSystemExtension()
501
- : undefined;
502
- if (permissionProfile !== undefined && permSystemExt === undefined && permSystemExtForProfile === undefined) {
503
- throw new Error(`Permission profile '${permissionProfile}' cannot be enabled: pi-permission-system is not installed; cannot launch a child with a permission profile.`);
504
- }
505
- const effectivePermSystemExt = permSystemExt ?? permSystemExtForProfile;
506
- let sandboxExtension: string | undefined;
507
- if (sandboxProfile) {
508
- try {
509
- sandboxExtension = resolveSandboxExtensionForProfile(sandboxProfile);
510
- } catch (error) {
511
- const message = error instanceof Error ? error.message : String(error);
512
- throw new Error(`Sandbox profile '${sandboxProfile}' cannot be enabled: ${message}`);
513
- }
514
- }
515
+ const { sandboxExtension, effectivePermSystemExt } = resolveProfileExtensions({
516
+ sandbox: input.sandbox,
517
+ permissionProfile: input.permissionProfile,
518
+ capabilityCeiling,
519
+ permSystemExt,
520
+ });
515
521
  if (input.fast && capabilityCeiling?.denyExtensions) throw new Error("fast mode requires a child runtime extension, but this launch denies extensions.");
516
- const fastModeExtensions = resolveFastModeExtension({ fast: input.fast, model: input.model, modelCandidates: input.modelCandidates, agentName: input.agentName });
522
+ const fastModeExtensions = resolveFastModeExtension({ fast: input.fast, model: input.model, agentName: input.agentName });
517
523
  const runtimeExtensions = [
518
524
  PROMPT_RUNTIME_EXTENSION_PATH,
519
525
  ...fastModeExtensions,
@@ -541,7 +547,7 @@ export function resolvePiLaunchToolPlan(
541
547
  ...(input.extensions ?? []),
542
548
  ...(input.subagentOnlyExtensions ?? []),
543
549
  ];
544
- const extensionArgs = disableAmbientExtensions
550
+ const ordinaryExtensionArgs = disableAmbientExtensions
545
551
  ? [...new Set([...runtimeExtensions, ...configuredExtensions])]
546
552
  : [
547
553
  ...new Set([
@@ -550,6 +556,8 @@ export function resolvePiLaunchToolPlan(
550
556
  ...(input.subagentOnlyExtensions ?? []),
551
557
  ]),
552
558
  ];
559
+ // Host-required paths have final precedence and cannot be removed by agent defaults or overrides.
560
+ const extensionArgs = [...new Set([...ordinaryExtensionArgs, ...requiredExtensions.map(({ path }) => path)])];
553
561
  const requestedToolNames =
554
562
  input.tools !== undefined
555
563
  ? [
@@ -559,6 +567,32 @@ export function resolvePiLaunchToolPlan(
559
567
  ]),
560
568
  ]
561
569
  : undefined;
570
+ const missingPermittedRepositoryTools = input.tools !== undefined
571
+ ? missingPermittedRepositoryInspectionTools(unavailableHostBuiltins, excludeTools)
572
+ : [];
573
+ if (missingPermittedRepositoryTools.length > 0 && isReviewOrScoutLaneAgent(input.agentName)) {
574
+ throw new Error(formatReviewLaneToolContractFailure({
575
+ agentName: input.agentName,
576
+ missingTools: missingPermittedRepositoryTools,
577
+ requestedTools: requestedToolNames,
578
+ effectiveTools: effectiveToolAllowlist,
579
+ ceilingSources: capabilityCeiling?.sources,
580
+ excludeTools,
581
+ }));
582
+ }
583
+ // Host pruning also happens without a ceiling (and therefore without an
584
+ // audit). Use the existing non-fatal launch warnings rather than inventing
585
+ // a ceiling or treating the requested allowlist as a minimum requirement.
586
+ if (unavailableHostBuiltins.length > 0) {
587
+ const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
588
+ warnings.push(
589
+ `${subject}: host runtime tool availability omitted [${unavailableHostBuiltins.join(", ")}]. `
590
+ + `Requested tool names: ${requestedToolNames ? `[${requestedToolNames.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${effectiveToolAllowlist.join(", ")}]. `
591
+ + (capabilityCeiling ? `Active capability ceiling sources: [${capabilityCeiling.sources.join(", ") || "unknown source"}]. ` : "")
592
+ + (excludeTools.length > 0 ? `Explicit excludeTools: [${excludeTools.join(", ")}]. ` : "")
593
+ + "This is a non-fatal tool-plan diagnostic, not verification of the child's runtime tool menu.",
594
+ );
595
+ }
562
596
  const capabilityAudit = capabilityCeiling
563
597
  ? ({
564
598
  ceiling: capabilityCeiling,
@@ -596,6 +630,7 @@ export function resolvePiLaunchToolPlan(
596
630
  capabilityCeilingAgentRestrictionSources(capabilityCeiling),
597
631
  }
598
632
  : {}),
633
+ ...(unavailableHostBuiltins.length > 0 ? { unavailableHostBuiltins } : {}),
599
634
  } satisfies SubagentCapabilityAudit)
600
635
  : undefined;
601
636
  return {
@@ -615,9 +650,11 @@ export function resolvePiLaunchToolPlan(
615
650
  ...(sandboxExtension ? { sandboxExtension } : {}),
616
651
  runtimeExtensions,
617
652
  configuredExtensions,
653
+ requiredExtensions,
618
654
  extensionArgs,
619
655
  disableAmbientExtensions,
620
656
  warnings,
657
+ unavailableHostBuiltins,
621
658
  ...(capabilityAudit ? { capabilityAudit } : {}),
622
659
  };
623
660
  }
@@ -26,7 +26,7 @@ export function planCompletionEvidence(input: {
26
26
  mutationAttemptObserved: boolean;
27
27
  mutationEvidence?: TrackedMutationEvidence;
28
28
  arbiterRescued?: boolean;
29
- agentContractV1: boolean;
29
+ agentContractEnabled: boolean;
30
30
  }): CompletionEvidencePlan {
31
31
  const guardBlocked = input.guard?.blocked === true;
32
32
  const guardTriggered = input.guardTriggered
@@ -59,7 +59,7 @@ export function planCompletionEvidence(input: {
59
59
  mutationExpected,
60
60
  mutationAttempted,
61
61
  fileMutation,
62
- legacyFailureError: guardTriggered && !input.agentContractV1
62
+ legacyFailureError: guardTriggered && !input.agentContractEnabled
63
63
  ? MISSING_IMPLEMENTATION_MUTATION_ERROR
64
64
  : undefined,
65
65
  };
@@ -13,6 +13,7 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
13
13
  "web_search",
14
14
  "fetch_content",
15
15
  "get_search_content",
16
+ "source_check",
16
17
  "intercom",
17
18
  "contact_supervisor",
18
19
  "structured_output",
@@ -97,10 +98,12 @@ export function validateImplementationToolContract(input: {
97
98
  const declaredMutationToolsWereRemoved = requestedMutationTools.length > 0 && !hasBuiltinMutationTool(input.tools);
98
99
  const configuredExtensionCapability = (input.configuredExtensions?.length ?? 0) > 0 && !declaredMutationToolsWereRemoved;
99
100
  if (hasMutationToolCapability(input.tools, input.mcpDirectTools) || configuredExtensionCapability) return undefined;
100
- const intent = classifyTaskMutationIntent(input.agent, input.task);
101
+ const intent = classifyTaskMutationIntent(input.acceptanceRole === "writer" ? "worker" : input.agent, input.task);
101
102
  if (intent.kind === "read-only") return undefined;
102
- const writerTaskMayMutate = isWriterRole(input.agent, input.acceptanceRole)
103
- && (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
103
+ const writerTaskMayMutate = input.acceptanceRole === "writer"
104
+ ? true
105
+ : isWriterRole(input.agent, input.acceptanceRole)
106
+ && (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
104
107
  if (intent.kind !== "implementation" && !writerTaskMayMutate && !declaredMutationToolsWereRemoved) return undefined;
105
108
  return `Agent '${input.agent}' was given an implementation task, but its tool allowlist has no mutation-capable tools. Add bash, edit, write, or another mutation-capable tool to the agent, or use a read-only task/agent.`;
106
109
  }
@@ -46,12 +46,12 @@ const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency
46
46
  const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
47
47
  const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
48
48
  const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
49
- const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
49
+ const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "machine", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
50
50
  const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
51
51
  ...DYNAMIC_PARALLEL_KEYS,
52
52
  "outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
53
53
  "structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
54
- "systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
54
+ "systemPromptMode", "thinking", "requestedModel", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "requiredExtensions", "launchResolvedExtensions", "requestedCwd", "machineEnv",
55
55
  ]);
56
56
  const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
57
57
 
@@ -0,0 +1,33 @@
1
+ import type { AgentConfig } from "../../agents/agents.ts";
2
+ import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
3
+ import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
4
+ import { buildSkillInjection } from "../../agents/skills.ts";
5
+ import { injectOutputPathSystemPrompt } from "./single-output.ts";
6
+
7
+ export interface EffectiveSystemPromptInput {
8
+ /** Agent as handed to the child, including runtime-declared overlays such as the Intercom bridge. */
9
+ agent: AgentConfig;
10
+ resolvedSkills: Parameters<typeof buildSkillInjection>[0];
11
+ /** Directory that scopes memory and refinement lookups. */
12
+ cwd: string;
13
+ /** Omit when the caller injects the output path through another channel. */
14
+ outputPath?: string;
15
+ }
16
+
17
+ function appendSection(prompt: string, section: string): string {
18
+ return prompt ? `${prompt}\n\n${section}` : section;
19
+ }
20
+
21
+ /**
22
+ * Child system prompt in the order preflight and every execution path hash:
23
+ * base prompt, skills, memory, refinement overlay, output path. Runtime
24
+ * acceptance prose is appended later and stays outside launch identity.
25
+ */
26
+ export function buildEffectiveSystemPrompt(input: EffectiveSystemPromptInput): string {
27
+ let prompt = input.agent.systemPrompt?.trim() ?? "";
28
+ if (input.resolvedSkills.length > 0) prompt = appendSection(prompt, buildSkillInjection(input.resolvedSkills));
29
+ const memoryInjection = buildAgentMemoryInjection(input.agent, input.cwd);
30
+ if (memoryInjection) prompt = appendSection(prompt, memoryInjection);
31
+ prompt = appendAgentRefinementOverlay(prompt, { cwd: input.cwd, agentName: input.agent.name });
32
+ return injectOutputPathSystemPrompt(prompt, input.outputPath, input.agent);
33
+ }
@@ -2,7 +2,9 @@ import type {
2
2
  ExternalCliReceiptMetadata,
3
3
  ExternalCliCapabilityNarrowing,
4
4
  ExternalCliRunnerStatus,
5
+ ExternalCliMachineStatus,
5
6
  ExternalProcessStatus,
7
+ HerdrMachineReference,
6
8
  } from "../../shared/types.ts";
7
9
 
8
10
  const UNSUPPORTED = {
@@ -80,6 +82,7 @@ export function resolveExternalCliRunnerStatus(input: {
80
82
  args?: string[];
81
83
  promptDelivery?: "stdin";
82
84
  capabilities?: ExternalCliCapabilityNarrowing;
85
+ machine?: HerdrMachineReference;
83
86
  }): ExternalCliRunnerStatus {
84
87
  const codexExec = input.adapter === "codex-exec";
85
88
  const codexExecWriter = input.adapter === "codex-exec-writer";
@@ -101,6 +104,7 @@ export function resolveExternalCliRunnerStatus(input: {
101
104
  ...(claudeCodeWriter ? { safety: { access: "workspace-write" as const, authentication: "existing-cli-required" as const, permissionMode: "acceptEdits" as const, tools: "Read,Write,Edit,Glob,Grep" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
102
105
  ...(cursorAgent ? { safety: { access: "read-only" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "ask" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
103
106
  ...(cursorAgentWriter ? { safety: { access: "workspace-write" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "print" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
107
+ ...(input.machine ? { machine: input.machine } : {}),
104
108
  capabilities: {
105
109
  stop: true,
106
110
  steer: false,
@@ -124,6 +128,9 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
124
128
  ? input.args
125
129
  : undefined;
126
130
  const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
131
+ const machine = input.machine && typeof input.machine === "object" && !Array.isArray(input.machine)
132
+ ? input.machine as HerdrMachineReference
133
+ : undefined;
127
134
  const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter)
128
135
  ? (input.adapter as Record<string, unknown>).id
129
136
  : undefined;
@@ -131,6 +138,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
131
138
  return {
132
139
  type: "external-cli",
133
140
  command: input.command,
141
+ ...(machine ? { machine } : {}),
134
142
  args: args ?? [],
135
143
  promptDelivery: "prompt-file",
136
144
  adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
@@ -140,7 +148,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
140
148
  };
141
149
  }
142
150
  const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
143
- return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}) });
151
+ return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}), ...(machine ? { machine } : {}) });
144
152
  }
145
153
 
146
154
  export function externalCliReceiptMetadata(input: {
@@ -149,9 +157,11 @@ export function externalCliReceiptMetadata(input: {
149
157
  outputReference?: string;
150
158
  }): ExternalCliReceiptMetadata {
151
159
  const { runner } = input;
160
+ const machine: ExternalCliMachineStatus | undefined = input.externalProcess?.machine ?? runner.machine;
152
161
  return {
153
162
  adapter: { ...runner.adapter },
154
163
  capabilities: { ...runner.capabilities },
164
+ ...(machine ? { machine: { ...machine, ...(machine.remoteGit ? { remoteGit: { ...machine.remoteGit } } : {}) } } : {}),
155
165
  ...(runner.safety ? { safety: { ...runner.safety } } : {}),
156
166
  ...(input.externalProcess ? {
157
167
  outputArtifacts: {
@@ -4,6 +4,7 @@ import * as path from "node:path";
4
4
 
5
5
  const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
6
6
  const MAX_PROBE_TIMEOUT_MS = 5_000;
7
+ const MAX_REMOTE_PROBE_TIMEOUT_MS = 15_000;
7
8
  const MAX_CACHE_ENTRIES = 64;
8
9
  const MAX_AVAILABILITY_REASON_LENGTH = 256;
9
10
 
@@ -16,6 +17,8 @@ export interface ExternalCliPreflightSpec {
16
17
  evidenceArgs?: readonly string[];
17
18
  evidenceLabel?: string;
18
19
  probeTimeoutMs?: number;
20
+ /** Remote probes include SSH handshakes; values may only narrow the code-owned remote ceiling. */
21
+ remote?: boolean;
19
22
  validate?: (result: ExternalCliPreflightResult) => void;
20
23
  }
21
24
 
@@ -90,7 +93,7 @@ function narrowPositiveInteger(value: number | undefined, ceiling: number, label
90
93
  }
91
94
 
92
95
  function specKey(spec: ExternalCliPreflightSpec): string {
93
- return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
96
+ return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs, spec.remote === true]);
94
97
  }
95
98
 
96
99
  export function preflightExternalCli(command: string, spec: ExternalCliPreflightSpec, env: NodeJS.ProcessEnv, cwd?: string): ExternalCliPreflightResult {
@@ -99,7 +102,8 @@ export function preflightExternalCli(command: string, spec: ExternalCliPreflight
99
102
  const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
100
103
  const cachedKey = lookup.get(lookupKey);
101
104
  const cached = cachedKey ? cache.get(cachedKey) : undefined;
102
- const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
105
+ const ceiling = spec.remote === true ? MAX_REMOTE_PROBE_TIMEOUT_MS : MAX_PROBE_TIMEOUT_MS;
106
+ const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, ceiling, "probeTimeoutMs");
103
107
  const base = cached ?? {
104
108
  binaryPath,
105
109
  binaryMtimeMs,