pi-subagents 0.66.0 → 0.68.0

package/src/runs/shared/child-tool-plan.ts

@@ -7,6 +7,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	formatUnresolvedMcpDirectToolSelectors,
 	resolveMcpDirectToolResolution,
@@ -21,6 +22,7 @@ import {
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
 import { getAgentDir } from "../../shared/utils.ts";
 import type { PermissionRules } from "./permissions.ts";
+import { snapshotRequiredChildExtensions, type RequiredChildExtensionSnapshot } from "../../shared/required-child-extensions.ts";
 import {
 	capabilityCeilingAgentRestrictionSources,
 	intersectSubagentCapabilityCeilings,
@@ -32,18 +34,18 @@ import {
 const MAX_LAUNCH_RESOLVED_EXTENSION_IDS = 32;
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(
 	path.dirname(fileURLToPath(import.meta.url)),
-	"subagent-prompt-runtime.ts",
+	`subagent-prompt-runtime${path.extname(fileURLToPath(import.meta.url))}`,
 );
 const FANOUT_CHILD_EXTENSION_PATH = path.join(
 	path.dirname(fileURLToPath(import.meta.url)),
 	"..",
 	"..",
 	"extension",
-	"fanout-child.ts",
+	`fanout-child${path.extname(fileURLToPath(import.meta.url))}`,
 );
 const FAST_MODE_EXTENSION_PATH = path.join(
 	path.dirname(fileURLToPath(import.meta.url)),
-	"fast-mode-extension.ts",
+	`fast-mode-extension${path.extname(fileURLToPath(import.meta.url))}`,
 );
 const SUBAGENT_RUNTIME_EXTENSION_PATHS = new Set([
 	PROMPT_RUNTIME_EXTENSION_PATH,
@@ -60,6 +62,39 @@ const FAST_MODE_ALLOWED_MODELS = new Set([
 	"openai-codex/gpt-5.6-sol",
 ]);
 const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+const REPOSITORY_INSPECTION_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "powershell"]);
+const REVIEW_OR_SCOUT_AGENT_PATTERN = /\b(?:reviewer|scout)\b/i;
+
+export function isReviewOrScoutLaneAgent(agentName: string | undefined): boolean {
+	return typeof agentName === "string" && REVIEW_OR_SCOUT_AGENT_PATTERN.test(agentName);
+}
+
+export function missingPermittedRepositoryInspectionTools(
+	unavailableHostBuiltins: readonly string[],
+	excludeTools: readonly string[] = [],
+): string[] {
+	const excluded = new Set(excludeTools);
+	return unavailableHostBuiltins.filter((tool) => REPOSITORY_INSPECTION_TOOLS.has(tool) && !excluded.has(tool));
+}
+
+export function formatReviewLaneToolContractFailure(input: {
+	agentName?: string;
+	missingTools: readonly string[];
+	requestedTools?: readonly string[];
+	effectiveTools: readonly string[];
+	ceilingSources?: readonly string[];
+	excludeTools?: readonly string[];
+}): string {
+	const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
+	return [
+		`${subject}: tool contract could not be satisfied; host runtime does not provide permitted required repository tools [${input.missingTools.join(", ")}].`,
+		`Requested tool names: ${input.requestedTools ? `[${input.requestedTools.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${input.effectiveTools.join(", ")}].`,
+		...(input.ceilingSources?.length ? [`Active capability ceiling sources: [${input.ceilingSources.join(", ")}].`] : []),
+		...(input.excludeTools?.length ? [`Explicit excludeTools: [${input.excludeTools.join(", ")}].`] : []),
+		"This is a lane infrastructure failure, not a completed review/scout result.",
+	].join(" ");
+}
 
 export function deriveForkPromptCacheKey(parentSessionId: string | undefined): string | undefined {
 	const parent = parentSessionId?.trim();
@@ -113,9 +148,9 @@ function stripThinkingSuffix(model: string): string {
 		: model;
 }
 
-function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fast" | "model" | "modelCandidates" | "agentName">): string[] {
+function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fast" | "model" | "agentName">): string[] {
 	if (!input.fast) return [];
-	const candidates = (input.modelCandidates?.length ? input.modelCandidates : input.model ? [input.model] : [])
+	const candidates = (input.model ? [input.model] : [])
 		.map(stripThinkingSuffix);
 	if (candidates.length === 0) {
 		throw new Error(`fast mode requires an explicit supported native OpenAI-Codex model${input.agentName ? ` for agent '${input.agentName}'` : ""}.`);
@@ -133,6 +168,7 @@ export interface ResolvePiLaunchToolPlanInput {
 	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
+	requiredExtensions?: RequiredChildExtensionSnapshot;
 	mcpDirectTools?: string[];
 	cwd?: string;
 	requireReadTool?: boolean;
@@ -145,12 +181,21 @@ export interface ResolvePiLaunchToolPlanInput {
 		  };
 	fast?: boolean;
 	model?: string;
-	modelCandidates?: readonly string[];
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	agentName?: string;
 	permissionRules?: PermissionRules;
 	runtimeSnapshotHost?: McpRuntimeSnapshotHost;
+	/**
+	 * When provided, child tool plans intersect known Pi core tool slots with
+	 * this set. Core tools the agent declares but the host does not provide are
+	 * omitted with a non-fatal warning (tracked in `unavailableHostBuiltins`).
+	 * Review/scout lanes fail closed when a requested, still-permitted
+	 * repository inspection tool is among those host omissions. Intentionally
+	 * empty or ceiling-restricted allowlists are not a minimum-tool contract.
+	 * Non-core names remain allowed and are validated in the child's registry.
+	 */
+	hostAvailableBuiltins?: readonly string[];
 }
 
 export interface PiLaunchToolPlan {
@@ -169,11 +214,14 @@ export interface PiLaunchToolPlan {
 	fanoutAuthorized: boolean;
 	runtimeExtensions: string[];
 	configuredExtensions: string[];
+	requiredExtensions: RequiredChildExtensionSnapshot;
 	extensionArgs: string[];
 	disableAmbientExtensions: boolean;
 	capabilityAudit?: SubagentCapabilityAudit;
 	/** Non-fatal launch warnings; they do not change behavior. */
 	warnings: string[];
+	/** Builtin tools the agent declared but the host runtime does not provide. */
+	unavailableHostBuiltins: string[];
 }
 
 function extensionIdentifier(value: string): string {
@@ -211,6 +259,7 @@ export function projectLaunchResolvedChildExtensions(
 		PiLaunchToolPlan,
 		| "runtimeExtensions"
 		| "configuredExtensions"
+		| "requiredExtensions"
 		| "extensionArgs"
 		| "disableAmbientExtensions"
 	>,
@@ -224,10 +273,12 @@ export function projectLaunchResolvedChildExtensions(
 		disableAmbientExtensions: toolPlan.disableAmbientExtensions,
 		runtime: runtime.ids,
 		configured: configured.ids,
+		required: toolPlan.requiredExtensions.map(({ id }) => id),
 		effective: effective.ids,
 		omitted: {
 			runtime: runtime.omitted,
 			configured: configured.omitted,
+			required: 0,
 			effective: effective.omitted,
 		},
 	};
@@ -289,6 +340,32 @@ export function resolvePermissionSystemExtension(): string | undefined {
 	return undefined;
 }
 
+/**
+ * Extract the names of builtin tools the host provides. Use this to pass
+ * `hostAvailableBuiltins` to `resolvePiLaunchToolPlan` so child tool plans
+ * intersect known core slots with what the host actually supports. Wrapped
+ * core slots count regardless of source; host-specific builtins count too.
+ *
+ * Returns `undefined` when builtin tool discovery fails or yields nothing,
+ * so callers skip the intersection (fail-safe to allowing all declared tools).
+ * This handles test mocks without proper tool registration and hosts whose
+ * getAllTools() throws before extensions load.
+ */
+export function getHostBuiltinToolNames(pi: Pick<ExtensionAPI, "getAllTools">): string[] | undefined {
+	try {
+		const builtins = pi
+			.getAllTools()
+			.filter((tool) => {
+				const source = (tool.sourceInfo as { source?: string } | undefined)?.source;
+				return source === "builtin" || PI_BUILTIN_TOOL_NAMES.has(tool.name);
+			})
+			.map((tool) => tool.name);
+		return builtins.length > 0 ? builtins : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 export function resolvePiLaunchToolPlan(
 	input: ResolvePiLaunchToolPlanInput,
 ): PiLaunchToolPlan {
@@ -296,21 +373,35 @@ export function resolvePiLaunchToolPlan(
 		input.capabilityCeiling,
 		input.inheritedCapabilityCeiling,
 	);
+	const requiredExtensions = snapshotRequiredChildExtensions(input.requiredExtensions ?? []);
+	if (requiredExtensions.length > 0 && capabilityCeiling?.denyExtensions) {
+		throw new Error(`Capability ceiling from ${capabilityCeiling.sources.join(", ") || "unknown source"} denies extensions but this host requires: ${requiredExtensions.map(({ id }) => id).join(", ")}.`);
+	}
 	const allowedToolSet =
 		capabilityCeiling?.allowedTools === undefined
 			? undefined
 			: new Set(capabilityCeiling.allowedTools);
+	const hostAvailableSet =
+		input.hostAvailableBuiltins === undefined
+			? undefined
+			: new Set(input.hostAvailableBuiltins);
 	const requestedBuiltinTools =
 		input.tools?.filter(
 			(tool) =>
 				!(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")),
 		) ?? [];
+	if (input.requireReadTool && hostAvailableSet && !hostAvailableSet.has("read")) {
+		const agentLabel = input.agentName ? ` for agent '${input.agentName}'` : "";
+		throw new Error(
+			`Host runtime does not provide required tool 'read'${agentLabel} for lazy skill loading.`,
+		);
+	}
 	if (input.requireReadTool && allowedToolSet && !allowedToolSet.has("read")) {
 		throw new Error(
 			`Capability ceiling from ${capabilityCeiling?.sources.join(", ") || "unknown source"} excludes required tool 'read' for lazy skill loading.`,
 		);
 	}
-	const declaredBuiltinTools =
+	const ceilingFilteredBuiltinTools =
 		input.tools === undefined
 			? allowedToolSet
 				? [...allowedToolSet]
@@ -322,6 +413,12 @@ export function resolvePiLaunchToolPlan(
 					? ["read", ...requestedBuiltinTools]
 					: requestedBuiltinTools
 				).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
+	const declaredBuiltinTools = hostAvailableSet
+		? ceilingFilteredBuiltinTools.filter((tool) => !PI_BUILTIN_TOOL_NAMES.has(tool) || hostAvailableSet.has(tool))
+		: ceilingFilteredBuiltinTools;
+	const unavailableHostBuiltins = hostAvailableSet
+		? ceilingFilteredBuiltinTools.filter((tool) => PI_BUILTIN_TOOL_NAMES.has(tool) && !hostAvailableSet.has(tool))
+		: [];
 	const excludeTools = [...new Set((input.excludeTools ?? []).map((tool) => tool.trim()).filter(Boolean))];
 	const excludedToolSet = new Set(excludeTools);
 	const effectiveDeclaredBuiltinTools = declaredBuiltinTools.filter((tool) => !excludedToolSet.has(tool));
@@ -330,6 +427,9 @@ export function resolvePiLaunchToolPlan(
 		!excludedToolSet.has("subagent") &&
 		(!allowedToolSet || allowedToolSet.has("subagent"))
 	);
+	if (effectiveDeclaredBuiltinTools.includes("subagent_supervisor") && !fanoutAuthorized) {
+		throw new Error("Tool 'subagent_supervisor' requires fanout authorization: include 'subagent' in the effective tools allowlist or enable allowNestedSubagents.");
+	}
 	const toolExtensionPaths: string[] = capabilityCeiling?.denyExtensions
 		? []
 		: (input.tools ?? []).filter(
@@ -370,8 +470,8 @@ export function resolvePiLaunchToolPlan(
 			...internalTools,
 		]),
 	];
-	// Supervisor-coordination names stay in the --tools allowlist but are never
-	// strict requirements: children register contact_supervisor at runtime through
+	// Upward contact stays in the --tools allowlist but is not a strict
+	// requirement: children register contact_supervisor at runtime through
 	// the native supervisor channel (or pi-intercom). The pre-0.50 bridge always
 	// appended intercom alongside contact_supervisor, so that exact pairing is
 	// legacy plumbing, not a user demand for an external intercom provider;
@@ -392,7 +492,7 @@ export function resolvePiLaunchToolPlan(
 			? resolvePermissionSystemExtension()
 			: undefined;
 	if (input.fast && capabilityCeiling?.denyExtensions) throw new Error("fast mode requires a child runtime extension, but this launch denies extensions.");
-	const fastModeExtensions = resolveFastModeExtension({ fast: input.fast, model: input.model, modelCandidates: input.modelCandidates, agentName: input.agentName });
+	const fastModeExtensions = resolveFastModeExtension({ fast: input.fast, model: input.model, agentName: input.agentName });
 	const runtimeExtensions = [
 		PROMPT_RUNTIME_EXTENSION_PATH,
 		...fastModeExtensions,
@@ -419,7 +519,7 @@ export function resolvePiLaunchToolPlan(
 				...(input.extensions ?? []),
 				...(input.subagentOnlyExtensions ?? []),
 			];
-	const extensionArgs = disableAmbientExtensions
+	const ordinaryExtensionArgs = disableAmbientExtensions
 		? [...new Set([...runtimeExtensions, ...configuredExtensions])]
 		: [
 				...new Set([
@@ -428,6 +528,8 @@ export function resolvePiLaunchToolPlan(
 					...(input.subagentOnlyExtensions ?? []),
 				]),
 			];
+	// Host-required paths have final precedence and cannot be removed by agent defaults or overrides.
+	const extensionArgs = [...new Set([...ordinaryExtensionArgs, ...requiredExtensions.map(({ path }) => path)])];
 	const requestedToolNames =
 		input.tools !== undefined
 			? [
@@ -437,6 +539,32 @@ export function resolvePiLaunchToolPlan(
 					]),
 				]
 			: undefined;
+	const missingPermittedRepositoryTools = input.tools !== undefined
+		? missingPermittedRepositoryInspectionTools(unavailableHostBuiltins, excludeTools)
+		: [];
+	if (missingPermittedRepositoryTools.length > 0 && isReviewOrScoutLaneAgent(input.agentName)) {
+		throw new Error(formatReviewLaneToolContractFailure({
+			agentName: input.agentName,
+			missingTools: missingPermittedRepositoryTools,
+			requestedTools: requestedToolNames,
+			effectiveTools: effectiveToolAllowlist,
+			ceilingSources: capabilityCeiling?.sources,
+			excludeTools,
+		}));
+	}
+	// Host pruning also happens without a ceiling (and therefore without an
+	// audit). Use the existing non-fatal launch warnings rather than inventing
+	// a ceiling or treating the requested allowlist as a minimum requirement.
+	if (unavailableHostBuiltins.length > 0) {
+		const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
+		warnings.push(
+			`${subject}: host runtime tool availability omitted [${unavailableHostBuiltins.join(", ")}]. `
+				+ `Requested tool names: ${requestedToolNames ? `[${requestedToolNames.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${effectiveToolAllowlist.join(", ")}]. `
+				+ (capabilityCeiling ? `Active capability ceiling sources: [${capabilityCeiling.sources.join(", ") || "unknown source"}]. ` : "")
+				+ (excludeTools.length > 0 ? `Explicit excludeTools: [${excludeTools.join(", ")}]. ` : "")
+				+ "This is a non-fatal tool-plan diagnostic, not verification of the child's runtime tool menu.",
+		);
+	}
 	const capabilityAudit = capabilityCeiling
 		? ({
 				ceiling: capabilityCeiling,
@@ -474,6 +602,7 @@ export function resolvePiLaunchToolPlan(
 								capabilityCeilingAgentRestrictionSources(capabilityCeiling),
 						}
 					: {}),
+				...(unavailableHostBuiltins.length > 0 ? { unavailableHostBuiltins } : {}),
 			} satisfies SubagentCapabilityAudit)
 		: undefined;
 	return {
@@ -492,9 +621,11 @@ export function resolvePiLaunchToolPlan(
 		fanoutAuthorized,
 		runtimeExtensions,
 		configuredExtensions,
+		requiredExtensions,
 		extensionArgs,
 		disableAmbientExtensions,
 		warnings,
+		unavailableHostBuiltins,
 		...(capabilityAudit ? { capabilityAudit } : {}),
 	};
 }

package/src/runs/shared/completion-guard.ts

@@ -98,10 +98,12 @@ export function validateImplementationToolContract(input: {
 	const declaredMutationToolsWereRemoved = requestedMutationTools.length > 0 && !hasBuiltinMutationTool(input.tools);
 	const configuredExtensionCapability = (input.configuredExtensions?.length ?? 0) > 0 && !declaredMutationToolsWereRemoved;
 	if (hasMutationToolCapability(input.tools, input.mcpDirectTools) || configuredExtensionCapability) return undefined;
-	const intent = classifyTaskMutationIntent(input.agent, input.task);
+	const intent = classifyTaskMutationIntent(input.acceptanceRole === "writer" ? "worker" : input.agent, input.task);
 	if (intent.kind === "read-only") return undefined;
-	const writerTaskMayMutate = isWriterRole(input.agent, input.acceptanceRole)
-		&& (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
+	const writerTaskMayMutate = input.acceptanceRole === "writer"
+		? true
+		: isWriterRole(input.agent, input.acceptanceRole)
+			&& (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
 	if (intent.kind !== "implementation" && !writerTaskMayMutate && !declaredMutationToolsWereRemoved) return undefined;
 	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.`;
 }

package/src/runs/shared/dynamic-fanout.ts

@@ -46,12 +46,12 @@ const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency
 const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
 const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
 const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
-const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "machine", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
 	"structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
-	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
+	"systemPromptMode", "thinking", "requestedModel", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "requiredExtensions", "launchResolvedExtensions", "requestedCwd", "machineEnv",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
 

package/src/runs/shared/effective-system-prompt.ts

@@ -0,0 +1,33 @@
+import type { AgentConfig } from "../../agents/agents.ts";
+import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
+import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
+import { buildSkillInjection } from "../../agents/skills.ts";
+import { injectOutputPathSystemPrompt } from "./single-output.ts";
+
+export interface EffectiveSystemPromptInput {
+	/** Agent as handed to the child, including runtime-declared overlays such as the Intercom bridge. */
+	agent: AgentConfig;
+	resolvedSkills: Parameters<typeof buildSkillInjection>[0];
+	/** Directory that scopes memory and refinement lookups. */
+	cwd: string;
+	/** Omit when the caller injects the output path through another channel. */
+	outputPath?: string;
+}
+
+function appendSection(prompt: string, section: string): string {
+	return prompt ? `${prompt}\n\n${section}` : section;
+}
+
+/**
+ * Child system prompt in the order preflight and every execution path hash:
+ * base prompt, skills, memory, refinement overlay, output path. Runtime
+ * acceptance prose is appended later and stays outside launch identity.
+ */
+export function buildEffectiveSystemPrompt(input: EffectiveSystemPromptInput): string {
+	let prompt = input.agent.systemPrompt?.trim() ?? "";
+	if (input.resolvedSkills.length > 0) prompt = appendSection(prompt, buildSkillInjection(input.resolvedSkills));
+	const memoryInjection = buildAgentMemoryInjection(input.agent, input.cwd);
+	if (memoryInjection) prompt = appendSection(prompt, memoryInjection);
+	prompt = appendAgentRefinementOverlay(prompt, { cwd: input.cwd, agentName: input.agent.name });
+	return injectOutputPathSystemPrompt(prompt, input.outputPath, input.agent);
+}

package/src/runs/shared/external-cli-contract.ts

@@ -2,7 +2,9 @@ import type {
 	ExternalCliReceiptMetadata,
 	ExternalCliCapabilityNarrowing,
 	ExternalCliRunnerStatus,
+	ExternalCliMachineStatus,
 	ExternalProcessStatus,
+	HerdrMachineReference,
 } from "../../shared/types.ts";
 
 const UNSUPPORTED = {
@@ -80,6 +82,7 @@ export function resolveExternalCliRunnerStatus(input: {
 	args?: string[];
 	promptDelivery?: "stdin";
 	capabilities?: ExternalCliCapabilityNarrowing;
+	machine?: HerdrMachineReference;
 }): ExternalCliRunnerStatus {
 	const codexExec = input.adapter === "codex-exec";
 	const codexExecWriter = input.adapter === "codex-exec-writer";
@@ -101,6 +104,7 @@ export function resolveExternalCliRunnerStatus(input: {
 		...(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 } } : {}),
 		...(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 } } : {}),
 		...(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 } } : {}),
+		...(input.machine ? { machine: input.machine } : {}),
 		capabilities: {
 			stop: true,
 			steer: false,
@@ -124,6 +128,9 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		? input.args
 		: undefined;
 	const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
+	const machine = input.machine && typeof input.machine === "object" && !Array.isArray(input.machine)
+		? input.machine as HerdrMachineReference
+		: undefined;
 	const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter)
 		? (input.adapter as Record<string, unknown>).id
 		: undefined;
@@ -131,6 +138,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		return {
 			type: "external-cli",
 			command: input.command,
+			...(machine ? { machine } : {}),
 			args: args ?? [],
 			promptDelivery: "prompt-file",
 			adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
@@ -140,7 +148,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		};
 	}
 	const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
-	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}) });
+	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}), ...(machine ? { machine } : {}) });
 }
 
 export function externalCliReceiptMetadata(input: {
@@ -149,9 +157,11 @@ export function externalCliReceiptMetadata(input: {
 	outputReference?: string;
 }): ExternalCliReceiptMetadata {
 	const { runner } = input;
+	const machine: ExternalCliMachineStatus | undefined = input.externalProcess?.machine ?? runner.machine;
 	return {
 		adapter: { ...runner.adapter },
 		capabilities: { ...runner.capabilities },
+		...(machine ? { machine: { ...machine, ...(machine.remoteGit ? { remoteGit: { ...machine.remoteGit } } : {}) } } : {}),
 		...(runner.safety ? { safety: { ...runner.safety } } : {}),
 		...(input.externalProcess ? {
 			outputArtifacts: {

package/src/runs/shared/external-cli-preflight.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 
 const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
 const MAX_PROBE_TIMEOUT_MS = 5_000;
+const MAX_REMOTE_PROBE_TIMEOUT_MS = 15_000;
 const MAX_CACHE_ENTRIES = 64;
 const MAX_AVAILABILITY_REASON_LENGTH = 256;
 
@@ -16,6 +17,8 @@ export interface ExternalCliPreflightSpec {
 	evidenceArgs?: readonly string[];
 	evidenceLabel?: string;
 	probeTimeoutMs?: number;
+	/** Remote probes include SSH handshakes; values may only narrow the code-owned remote ceiling. */
+	remote?: boolean;
 	validate?: (result: ExternalCliPreflightResult) => void;
 }
 
@@ -90,7 +93,7 @@ function narrowPositiveInteger(value: number | undefined, ceiling: number, label
 }
 
 function specKey(spec: ExternalCliPreflightSpec): string {
-	return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
+	return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs, spec.remote === true]);
 }
 
 export function preflightExternalCli(command: string, spec: ExternalCliPreflightSpec, env: NodeJS.ProcessEnv, cwd?: string): ExternalCliPreflightResult {
@@ -99,7 +102,8 @@ export function preflightExternalCli(command: string, spec: ExternalCliPreflight
 	const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
 	const cachedKey = lookup.get(lookupKey);
 	const cached = cachedKey ? cache.get(cachedKey) : undefined;
-	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
+	const ceiling = spec.remote === true ? MAX_REMOTE_PROBE_TIMEOUT_MS : MAX_PROBE_TIMEOUT_MS;
+	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, ceiling, "probeTimeoutMs");
 	const base = cached ?? {
 		binaryPath,
 		binaryMtimeMs,

package/src/runs/shared/external-cli-runner.ts

@@ -3,7 +3,7 @@ import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { finished } from "node:stream/promises";
-import type { ExternalProcessStatus } from "../../shared/types.ts";
+import type { ExternalProcessStatus, ProcessTreeTerminal } from "../../shared/types.ts";
 import { createOwnedProcessTreeController, type OwnedProcessTreeController } from "../background/owned-process-tree.ts";
 import { omitExtensionBindingsEnv } from "./extension-bindings.ts";
 import {
@@ -141,7 +141,7 @@ function classifyInvalidation(error: string): "auth" | "permission" | "launch" {
 	return "launch";
 }
 
-function terminateExternalProcessTree(pid: number, controller: OwnedProcessTreeController): Promise<unknown> {
+function terminateExternalProcessTree(pid: number, controller: OwnedProcessTreeController): Promise<ProcessTreeTerminal> {
 	if (process.platform !== "win32") return controller.terminate();
 	return new Promise((resolve) => {
 		const cleanup = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
@@ -239,7 +239,7 @@ export function runExternalCli(input: {
 		let settled = false;
 		let processTree: OwnedProcessTreeController | undefined;
 		let processPid: number | undefined;
-		let termination: Promise<unknown> | undefined;
+		let termination: Promise<ProcessTreeTerminal> | undefined;
 		const flushProgress = () => {
 			if (!latestProgress) return;
 			input.onParserProgress?.(latestProgress);
@@ -381,8 +381,7 @@ export function runExternalCli(input: {
 			input.registerTimeout?.(undefined);
 			input.registerStop?.(undefined);
 			void (async () => {
-				if (termination) await termination;
-				else if (processTree) await processTree.finishAfterWriterClose();
+				const treeProof = termination ? await termination : processTree ? await processTree.finishAfterWriterClose() : undefined;
 				const endedAt = Date.now();
 				const externalProcess: ExternalProcessStatus = {
 					...initialProcess,
@@ -398,15 +397,18 @@ export function runExternalCli(input: {
 				input.onProcess?.(externalProcess);
 				const stderr = stderrTail.text().trim();
 				const parserFailure = parserError?.message ?? (parserTerminal?.state === "failed" ? parserTerminal.error ?? "External CLI parser reported terminal failure." : undefined);
+				const treeFailure = process.platform !== "win32" && treeProof?.state === "unknown"
+					? `Process-tree cleanup failed: ${treeProof.reason}.`
+					: undefined;
 				const error = stopped
 					? input.stopMessage ?? "Subagent stopped by user."
 					: timedOut
 						? input.timeoutMessage ?? "Subagent timed out."
-						: spawnError?.message ?? parserFailure ?? (exitCode === 0 ? undefined : stderr || `External CLI exited with code ${exitCode}.`);
+						: spawnError?.message ?? parserFailure ?? treeFailure ?? (exitCode === 0 ? undefined : stderr || `External CLI exited with code ${exitCode}.`);
 				if (error && input.preflight && !parserError) invalidateExternalCliPreflight(input.command, input.preflight, classifyInvalidation(error));
 				const result: ExternalCliRunResult = {
 					output: (!parserError && parserTerminal?.state === "completed" ? parserTerminal.output ?? "" : stdoutTail.text()).trim(),
-					exitCode: timedOut || stopped || spawnError || parserFailure ? 1 : exitCode,
+					exitCode: timedOut || stopped || spawnError || parserFailure || treeFailure ? 1 : exitCode,
 					...(error ? { error } : {}),
 					...(timedOut ? { timedOut: true } : {}),
 					...(stopped ? { stopped: true } : {}),