pi-subagents 0.56.0 → 0.58.0

package/src/runs/foreground/workflow-detach-reconcile.ts

@@ -9,11 +9,17 @@ import {
 	type IntercomEventBus,
 	type SingleResult,
 	type SubagentState,
+	type WorkflowRecoveryAction,
+	type WorkflowTerminalOutcome,
+	type WorkflowTerminalResolution,
 } from "../../shared/types.ts";
 import { updateActiveRunIndex } from "../background/active-run-index.ts";
 import { resultFilePath, writeAsyncResultFile } from "../background/result-files.ts";
 import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
+import { externalCliReceiptMetadata, normalizeExternalCliRunnerStatus } from "../shared/external-cli-contract.ts";
+import { outputPathMappingFromTask } from "../shared/single-output.ts";
 import { readWorkflowReceipt, workflowReceiptPath, writeWorkflowReceipt, type WorkflowReceipt } from "../../workflows/workflow-receipt.ts";
+import { workflowChildSummary } from "../../workflows/workflow-child-summary.ts";
 
 function cloneWorkflowStatus(status: AsyncStatus): AsyncStatus {
 	return {
@@ -29,18 +35,33 @@ function childSucceeded(result: Pick<SingleResult, "exitCode" | "error" | "inter
 
 const UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION = "unsupported-continuation: detached workflow child settled, but JavaScript workflow continuation was not persisted. Resume the workflow explicitly instead of treating the completed child as top-level workflow completion.";
 const INTERRUPTED_DETACHED_CHILD = "Interrupted. Waiting for explicit next action.";
+type WorkflowStatusStep = NonNullable<AsyncStatus["steps"]>[number] & {
+	outputPathMapping?: { requestedPath: string; savedPath: string };
+	interrupted?: boolean;
+};
+
+function findWorkflowStep(status: AsyncStatus, childRunId: string, workflowKey?: string): WorkflowStatusStep | undefined {
+	return status.steps?.find((candidate) => candidate.runId === childRunId)
+		?? (workflowKey ? status.steps?.find((candidate) => candidate.workflowKey === workflowKey) : undefined) as WorkflowStatusStep | undefined;
+}
 
 export function applyDetachedChildToPausedWorkflow(
 	status: AsyncStatus,
-	input: { childRunId: string; result: Pick<SingleResult, "exitCode" | "error" | "interrupted" | "sessionFile">; workflowKey?: string },
+	input: { childRunId: string; result: Pick<SingleResult, "exitCode" | "error" | "interrupted" | "sessionFile" | "stopped">; workflowKey?: string },
 ): AsyncStatus | undefined {
 	if (status.mode !== "workflow" || status.state !== "paused") return undefined;
 	const next = cloneWorkflowStatus(status);
-	const step = next.steps?.find((candidate) => candidate.runId === input.childRunId)
-		?? (input.workflowKey ? next.steps?.find((candidate) => candidate.workflowKey === input.workflowKey) : undefined);
+	const step = findWorkflowStep(next, input.childRunId, input.workflowKey);
 	if (!step) return undefined;
 	const succeeded = childSucceeded(input.result);
-	const failedSiblingError = next.steps?.find((candidate) => candidate !== step && candidate.status === "failed" && candidate.error)?.error;
+	const failedSiblingError = next.steps?.find((candidate) => {
+		const candidateStep = candidate as WorkflowStatusStep;
+		return candidateStep !== step && candidateStep.status === "failed" && !candidateStep.interrupted && candidateStep.error;
+	})?.error;
+	const interruptedChildError = next.steps?.find((candidate) => {
+		const candidateStep = candidate as WorkflowStatusStep;
+		return candidateStep.status === "failed" && candidateStep.interrupted && candidateStep.error;
+	})?.error;
 	const updatedAt = Date.now();
 	step.status = succeeded ? "completed" : "failed";
 	step.endedAt = updatedAt;
@@ -48,14 +69,28 @@ export function applyDetachedChildToPausedWorkflow(
 	delete step.currentTool;
 	delete step.currentToolStartedAt;
 	if (input.result.sessionFile) step.sessionFile = input.result.sessionFile;
-	if (succeeded) delete step.error;
-	else if (input.result.interrupted) step.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
-	else if (input.result.error) step.error = input.result.error;
+	if (succeeded) {
+		delete step.error;
+		delete step.interrupted;
+	} else if (input.result.interrupted || input.result.stopped) {
+		step.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
+		step.interrupted = true;
+		if (input.result.stopped) step.stopped = true;
+	} else {
+		delete step.interrupted;
+		delete step.stopped;
+		if (input.result.error) step.error = input.result.error;
+	}
 	next.lastUpdate = updatedAt;
 	const promoted = promotePausedWorkflowIfSettled(next);
-	if (promoted?.state === "failed" && input.result.interrupted && !failedSiblingError) promoted.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
+	if (promoted?.state === "failed" && failedSiblingError) promoted.error = failedSiblingError;
+	else if (promoted?.state === "failed" && (input.result.interrupted || input.result.stopped)) promoted.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
 	else if (promoted?.state === "failed" && input.result.error) promoted.error = input.result.error;
-	return promoted ?? next;
+	else if (promoted?.state === "failed" && interruptedChildError) promoted.error = interruptedChildError;
+	const resolved = promoted ?? next;
+	const workflowState = resolved.state === "complete" ? "completed" : resolved.state === "paused" ? "paused" : resolved.state === "stopped" ? "stopped" : "failed";
+	resolved.workflowChildren = workflowChildSummary({ parentToolCallId: resolved.toolCallId ?? resolved.runId, workflowRunId: resolved.runId, workflowState, inventoryComplete: true, trace: resolved.workflow?.trace, steps: resolved.steps });
+	return resolved;
 }
 
 export function promotePausedWorkflowIfSettled(status: AsyncStatus): AsyncStatus | undefined {
@@ -77,8 +112,37 @@ export function promotePausedWorkflowIfSettled(status: AsyncStatus): AsyncStatus
 	return next;
 }
 
-function workflowResultChildren(status: AsyncStatus, childRunId: string, result: SingleResult, existingResults: unknown): unknown {
+function workflowResolution(status: AsyncStatus, result: Pick<SingleResult, "interrupted">): WorkflowTerminalResolution | undefined {
+	if (status.state !== "complete" && status.state !== "failed") return undefined;
+	if (status.steps?.some((step) => {
+		const candidate = step as WorkflowStatusStep;
+		return candidate.status === "failed" && !candidate.interrupted;
+	})) return "failed-child";
+	if (result.interrupted || status.steps?.some((step) => {
+		const candidate = step as WorkflowStatusStep;
+		return candidate.status === "stopped" || candidate.stopped || candidate.interrupted || candidate.error === INTERRUPTED_DETACHED_CHILD;
+	})) return "interrupted-child";
+	return "settled-awaiting-resume";
+}
+
+function workflowRecovery(receipt: WorkflowReceipt | undefined): WorkflowRecoveryAction[] {
+	if (!receipt) return [];
+	return Object.values(receipt.entries).flatMap((entry) => entry.resumability.state === "resumable"
+		? [{ key: entry.key, call: "runs.run" as const, resume: { workflowRunId: receipt.workflowRunId, key: entry.key, latest: true as const }, taskRequired: true as const }]
+		: []);
+}
+
+function resultTerminalOutcome(result: Pick<SingleResult, "timedOut" | "turnBudgetExceeded" | "toolBudgetBlocked">): WorkflowTerminalOutcome | undefined {
+	if (result.timedOut) return { state: "partial", reason: "timeout" };
+	if (result.turnBudgetExceeded || result.toolBudgetBlocked) return { state: "partial", reason: "budget_exhausted" };
+	return undefined;
+}
+
+function workflowResultChildren(status: AsyncStatus, childRunId: string, result: SingleResult, existingResults: unknown, receipt?: WorkflowReceipt): unknown {
 	const output = getSingleResultOutput(result);
+	const outputReference = result.savedOutputPath ?? result.outputReference?.path;
+	const outputPathMapping = outputPathMappingFromTask(result.task, outputReference);
+	const terminalOutcome = resultTerminalOutcome(result);
 	if (Array.isArray(existingResults)) {
 		return existingResults.map((entry) => {
 			if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
@@ -90,28 +154,56 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
 				output,
 				outputState: output.trim() ? "present" : "absent",
 				detached: undefined,
-				...(result.interrupted ? { interrupted: true } : {}),
+				...(outputReference ? { outputReference } : {}),
+				...(outputPathMapping ? { outputPathMapping } : {}),
+				...(result.interrupted || result.stopped ? { interrupted: true } : {}),
+				...(result.stopped ? { stopped: true } : {}),
+				...(terminalOutcome ? { terminalOutcome } : {}),
 				...(result.error ? { error: result.error } : {}),
 			};
 		});
 	}
-	return status.steps?.map((step) => ({
+	return status.steps?.map((step: WorkflowStatusStep) => ({
 		workflowKey: step.workflowKey,
 		agent: step.agent,
 		runId: step.runId,
 		success: step.status === "completed" || step.status === "complete",
 		output: step.runId === childRunId ? output : "",
 		outputState: step.runId === childRunId && output.trim() ? "present" : "absent",
-		...(step.runId === childRunId && result.interrupted ? { interrupted: true } : {}),
+		...(step.runId === childRunId && outputReference ? { outputReference } : step.workflowKey && receipt?.entries[step.workflowKey]?.outputReference ? { outputReference: receipt.entries[step.workflowKey]!.outputReference } : {}),
+		...(step.runId === childRunId && outputPathMapping ? { outputPathMapping } : step.outputPathMapping ? { outputPathMapping: step.outputPathMapping } : {}),
+		...(step.interrupted ? { interrupted: true } : {}),
+		...(step.runId === childRunId && terminalOutcome ? { terminalOutcome } : step.workflowKey && receipt?.entries[step.workflowKey]?.terminalOutcome ? { terminalOutcome: receipt.entries[step.workflowKey]!.terminalOutcome } : {}),
+		...(step.stopped ? { stopped: true } : {}),
 		...(step.error ? { error: step.error } : {}),
 	}));
 }
 
+function workflowResultOutputPathMappingSummary(results: unknown): string {
+	if (!Array.isArray(results)) return "";
+	const mappings = results.flatMap((entry) => {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+		const child = entry as Record<string, unknown>;
+		const mapping = child.outputPathMapping;
+		if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) return [];
+		const { requestedPath, savedPath } = mapping as Record<string, unknown>;
+		if (typeof requestedPath !== "string" || typeof savedPath !== "string") return [];
+		const key = typeof child.workflowKey === "string" ? child.workflowKey : "child";
+		return [`'${key}': requested ${requestedPath} -> saved ${savedPath}`];
+	});
+	return mappings.length > 0 ? ` Output path mappings: ${mappings.join("; ")}.` : "";
+}
+
 function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, existing?: Record<string, unknown>, receipt?: WorkflowReceipt): Record<string, unknown> {
 	const sessionId = status.sessionId ?? (typeof existing?.sessionId === "string" ? existing.sessionId : undefined);
-	const summary = status.state === "complete"
+	const resolution = workflowResolution(status, result);
+	const recovery = workflowRecovery(receipt);
+	const results = workflowResultChildren(status, childRunId, result, existing?.results, receipt);
+	const summary = `${resolution === "settled-awaiting-resume"
+		? `Workflow lanes settled after detached child ${childRunId} finished. JavaScript workflow continuation was not persisted.${recovery.length ? " Use the listed keyed recovery action to continue a child." : " No retained child is resumable."}`
+		: status.state === "complete"
 		? `Workflow completed after detached child ${childRunId} finished.`
-		: status.error ?? (typeof existing?.summary === "string" ? existing.summary : undefined);
+		: status.error ?? (typeof existing?.summary === "string" ? existing.summary : "Workflow failed.")}${workflowResultOutputPathMappingSummary(results)}`;
 	return {
 		...(existing ?? {}),
 		id: status.runId,
@@ -126,8 +218,11 @@ function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result
 		activityState: status.activityState,
 		endedAt: status.endedAt,
 		timestamp: Date.now(),
-		results: workflowResultChildren(status, childRunId, result, existing?.results),
+		results,
 		workflow: status.workflow,
+		workflowChildren: status.workflowChildren,
+		...(receipt?.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
+		...(resolution ? { workflowResolution: resolution, recovery } : {}),
 		reconciledFromDetachedChild: childRunId,
 		...(receipt ? { workflowReceipt: { path: path.join(asyncDir, "workflow-receipt.json"), receipt } } : {}),
 		asyncDir,
@@ -137,7 +232,7 @@ function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result
 	};
 }
 
-function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string): WorkflowReceipt | undefined {
+function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, resolution: WorkflowTerminalResolution | undefined): WorkflowReceipt | undefined {
 	const receiptPath = workflowReceiptPath(DIRS.async, status.runId);
 	if (!fs.existsSync(receiptPath)) return undefined;
 	const receipt = readWorkflowReceipt(DIRS.async, status.runId);
@@ -154,6 +249,13 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 		resumability = { state: "not-resumable", reason: error instanceof Error ? error.message : String(error) };
 	}
 	const outputReference = result.savedOutputPath ?? result.outputReference?.path ?? entry.outputReference;
+	const childStatus = readStatus(path.join(DIRS.async, childRunId));
+	const externalStep = childStatus?.steps?.length === 1 && childStatus.steps[0]?.runner?.type === "external-cli" ? childStatus.steps[0] : undefined;
+	const externalRunner = normalizeExternalCliRunnerStatus(result.runner?.type === "external-cli" ? result.runner : externalStep?.runner);
+	const externalProcess = result.externalProcess ?? externalStep?.externalProcess;
+	const externalAdapter = externalRunner ? externalCliReceiptMetadata({ runner: externalRunner, externalProcess, outputReference }) : entry.externalAdapter;
+	const childTerminalOutcome = resultTerminalOutcome(result) ?? entry.terminalOutcome;
+	if (externalAdapter) resumability = { state: "not-resumable", reason: externalAdapter.nonResumableReason };
 	const updatedEntry: WorkflowReceipt["entries"][string] = resumability.state === "resumable"
 		? {
 			...entry,
@@ -162,6 +264,8 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			latestRunId: entry.latestRunId ?? childRunId,
 			resumability,
 			...(outputReference ? { outputReference } : {}),
+			...(childTerminalOutcome ? { terminalOutcome: childTerminalOutcome } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
 		}
 		: {
 			...entry,
@@ -169,6 +273,8 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			...(step.context ? { resolvedContext: step.context } : {}),
 			resumability,
 			...(outputReference ? { outputReference } : {}),
+			...(childTerminalOutcome ? { terminalOutcome: childTerminalOutcome } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
 		};
 	const next: WorkflowReceipt = {
 		...receipt,
@@ -177,7 +283,15 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			...receipt.entries,
 			[key]: updatedEntry,
 		},
+		workflowChildren: status.workflowChildren,
+		...(receipt.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
+		...(resolution ? { workflowResolution: resolution } : {}),
 	};
+	if (resolution) next.recovery = workflowRecovery(next);
+	else {
+		delete next.workflowResolution;
+		delete next.recovery;
+	}
 	writeWorkflowReceipt(asyncDir, next);
 	return next;
 }
@@ -209,6 +323,10 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 		workflowKey: input.workflowKey,
 	});
 	if (!next) return false;
+	const outputReference = input.result.savedOutputPath ?? input.result.outputReference?.path;
+	const outputPathMapping = outputPathMappingFromTask(input.result.task, outputReference);
+	const settledStep = findWorkflowStep(next, input.childRunId, input.workflowKey);
+	if (settledStep && outputPathMapping) settledStep.outputPathMapping = outputPathMapping;
 	writeAtomicJson(path.join(asyncDir, "status.json"), next);
 	updateActiveRunIndex(asyncDir, next.state, next.toolCallId);
 	if (job) {
@@ -228,8 +346,9 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 	}
 	let receipt: WorkflowReceipt | undefined;
 	let receiptError: string | undefined;
+	const resolution = workflowResolution(next, input.result);
 	try {
-		receipt = reconcileWorkflowReceipt(next, input.childRunId, input.result, asyncDir);
+		receipt = reconcileWorkflowReceipt(next, input.childRunId, input.result, asyncDir, resolution);
 	} catch (error) {
 		receiptError = `Failed to reconcile async workflow receipt: ${error instanceof Error ? error.message : String(error)}`;
 	}
@@ -245,11 +364,15 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 		});
 	}
 	if (next.state === "complete" || next.state === "failed") {
+		if (!resolution) throw new Error(`Terminal detached workflow '${input.workflowRunId}' has no resolution classification.`);
 		appendDetachedWorkflowEvent(asyncDir, {
 			ts: Date.now(),
 			runId: input.workflowRunId,
 			type: "subagent.workflow.completed",
 			state: next.state,
+			workflowResolution: resolution,
+			...(receipt?.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
+			recovery: workflowRecovery(receipt),
 			...(next.error ? { error: next.error } : {}),
 			reconciledFromDetachedChild: input.childRunId,
 		});
@@ -261,6 +384,9 @@ export function reconcileDetachedWorkflowChildCompletion(input: {
 			agent: "workflow",
 			success: next.state === "complete",
 			state: next.state,
+			workflowResolution: resolution,
+			...(receipt?.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
+			recovery: workflowRecovery(receipt),
 			summary: typeof published.summary === "string" ? published.summary : (next.state === "complete" ? "Workflow completed." : next.error),
 			reconciledFromDetachedChild: input.childRunId,
 			...(Array.isArray(published.results) ? { results: published.results } : {}),

package/src/runs/shared/child-protocol.ts

@@ -218,6 +218,7 @@ function createPiAggregateProjection(): OversizedLineProjection {
 			if (!valid || token || stack.length !== 0 || rootState !== "end") return undefined;
 			if (eventType === "turn_end") return '{"type":"turn_end"}';
 			if (eventType === "agent_end" && typeof willRetry === "boolean") return JSON.stringify({ type: "agent_end", willRetry });
+			if (eventType === "compaction_end" && typeof willRetry === "boolean") return JSON.stringify({ type: "compaction_end", willRetry });
 			return undefined;
 		},
 	};
@@ -225,14 +226,15 @@ function createPiAggregateProjection(): OversizedLineProjection {
 
 /**
  * Pi JSON mode emits granular message/tool events followed by aggregate
- * `turn_end` and `agent_end` events that duplicate those payloads. Parallel
- * image reads can make one aggregate record exceed the child line limit even
- * though every granular event was valid. Replace only syntactically valid,
- * redundant records with the lifecycle fields the runners consume.
+ * `turn_end`, `agent_end`, and `compaction_end` events that can duplicate
+ * large payloads. Parallel image reads can make one aggregate record exceed
+ * the child line limit even though every granular event was valid. Replace
+ * only syntactically valid, redundant records with the lifecycle fields the
+ * runners consume.
  */
 export const PI_AGGREGATE_EVENT_PROJECTOR: OversizedLineProjector = {
 	accepts(prefix) {
-		return prefix.startsWith('{"type":"turn_end"') || prefix.startsWith('{"type":"agent_end"');
+		return prefix.startsWith('{"type":"turn_end"') || prefix.startsWith('{"type":"agent_end"') || prefix.startsWith('{"type":"compaction_end"');
 	},
 	create: createPiAggregateProjection,
 };
@@ -393,9 +395,21 @@ export function createBoundedByteTail(maxBytes = MAX_CHILD_STDERR_BYTES): {
 
 export type ChildLifecycleAction = "start-drain" | "cancel-drain" | "none";
 
-export function projectChildLifecycle(event: { type?: string; willRetry?: unknown }, terminalAssistantStop = false): ChildLifecycleAction {
+export interface ChildLifecycleState {
+	compactionRetryActive: boolean;
+}
+
+export function projectChildLifecycle(event: { type?: string; willRetry?: unknown }, terminalAssistantStop = false, state?: ChildLifecycleState): ChildLifecycleAction {
+	if (event.type === "compaction_end") {
+		if (state) state.compactionRetryActive = event.willRetry === true;
+		return event.willRetry === true ? "cancel-drain" : "none";
+	}
+	if (event.type === "agent_start" || event.type === "auto_retry_start") {
+		if (state) state.compactionRetryActive = false;
+	}
 	if (event.type === "agent_end" && event.willRetry === true) return "cancel-drain";
-	if (event.type === "agent_settled") return "start-drain";
+	if (event.type === "agent_end" && state) state.compactionRetryActive = false;
+	if (event.type === "agent_settled") return state?.compactionRetryActive ? "none" : "start-drain";
 	if (terminalAssistantStop) return "start-drain";
 	return "none";
 }

package/src/runs/shared/claude-code-adapter.ts

@@ -0,0 +1,129 @@
+import { parseExternalCliJsonlEvent, type ExternalCliParser, type ExternalCliParserProgress, type ExternalCliParserTerminal } from "./external-cli-runner.ts";
+import type { ExternalCliPreflightSpec } from "./external-cli-preflight.ts";
+
+const MAX_EVENT_TYPE_LENGTH = 128;
+const MAX_ERROR_LENGTH = 4_096;
+
+export const CLAUDE_CODE_ADAPTER_ID = "claude-code" as const;
+export const CLAUDE_CODE_WRITER_ADAPTER_ID = "claude-code-writer" as const;
+export const CLAUDE_CODE_WRITER_TOOLS = "Read,Write,Edit,Glob,Grep" as const;
+export const CLAUDE_CODE_ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"USERPROFILE",
+	"USER",
+	"LOGNAME",
+	"TMPDIR",
+	"CLAUDE_CONFIG_DIR",
+	"ANTHROPIC_API_KEY",
+	"ANTHROPIC_AUTH_TOKEN",
+	"ANTHROPIC_BASE_URL",
+	"CLAUDE_CODE_OAUTH_TOKEN",
+	"CLAUDE_CODE_USE_BEDROCK",
+	"CLAUDE_CODE_USE_VERTEX",
+	"CLAUDE_CODE_USE_FOUNDRY",
+	"AWS_PROFILE",
+	"AWS_REGION",
+	"AWS_DEFAULT_REGION",
+	"AWS_ACCESS_KEY_ID",
+	"AWS_SECRET_ACCESS_KEY",
+	"AWS_SESSION_TOKEN",
+	"AWS_BEARER_TOKEN_BEDROCK",
+	"GOOGLE_APPLICATION_CREDENTIALS",
+	"CLOUD_ML_REGION",
+	"ANTHROPIC_VERTEX_PROJECT_ID",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy",
+	"SSL_CERT_FILE",
+	"SSL_CERT_DIR",
+] as const;
+
+function terminalError(event: Record<string, unknown>): string {
+	for (const value of [event.error, event.result]) {
+		if (typeof value === "string" && value.trim()) return value.trim().slice(0, MAX_ERROR_LENGTH);
+	}
+	if (Array.isArray(event.errors)) {
+		const messages = event.errors.filter((value): value is string => typeof value === "string" && Boolean(value.trim()));
+		if (messages.length > 0) return messages.join("; ").slice(0, MAX_ERROR_LENGTH);
+	}
+	const subtype = typeof event.subtype === "string" && event.subtype ? event.subtype : "unknown";
+	return `Claude Code reported terminal result ${subtype}.`;
+}
+
+export function createClaudeCodeJsonlParser(): ExternalCliParser {
+	let eventCount = 0;
+	let terminal: ExternalCliParserTerminal | undefined;
+	return {
+		parseLine(line): ExternalCliParserProgress {
+			const event = parseExternalCliJsonlEvent(line, "Claude Code", MAX_EVENT_TYPE_LENGTH);
+			if (terminal && event.type === "result") throw new Error("Claude Code emitted a duplicate terminal result.");
+			eventCount += 1;
+			if (!terminal && event.type === "result") {
+				if (event.subtype === "success" && event.is_error === false && typeof event.result === "string" && event.result.trim()) {
+					terminal = { state: "completed", output: event.result.trim() };
+				} else {
+					terminal = { state: "failed", error: terminalError(event) };
+				}
+			}
+			return { phase: terminal ? terminal.state : "streaming", eventCount };
+		},
+		finish(): ExternalCliParserTerminal | undefined {
+			return terminal;
+		},
+	};
+}
+
+export function resolveClaudeCodeLaunch(input: {
+	adapter: typeof CLAUDE_CODE_ADAPTER_ID | typeof CLAUDE_CODE_WRITER_ADAPTER_ID;
+	command: string;
+	/** Test-only executable prefix for a fake Claude Code process. */
+	commandPrefixArgs?: readonly string[];
+}): {
+	command: string;
+	args: string[];
+	finalOutputPath?: undefined;
+	promptFilePath?: undefined;
+	temporaryDirectories?: undefined;
+	environment: { allowlist: readonly string[] };
+	preflight: ExternalCliPreflightSpec;
+	parser: ExternalCliParser;
+} {
+	const writer = input.adapter === CLAUDE_CODE_WRITER_ADAPTER_ID;
+	const prefix = [...(input.commandPrefixArgs ?? [])];
+	const args = [
+		...prefix,
+		"-p",
+		"--input-format", "text",
+		"--output-format", "stream-json",
+		"--verbose",
+		"--permission-mode", writer ? "acceptEdits" : "plan",
+		"--tools", writer ? CLAUDE_CODE_WRITER_TOOLS : "",
+		"--strict-mcp-config",
+		"--mcp-config", '{"mcpServers":{}}',
+		"--setting-sources", "user",
+		"--no-session-persistence",
+		"--disable-slash-commands",
+		"--no-chrome",
+	];
+	return {
+		command: input.command,
+		args,
+		environment: { allowlist: CLAUDE_CODE_ENV_ALLOWLIST },
+		preflight: {
+			id: input.adapter,
+			versionArgs: [...prefix, "--version"],
+			helpArgs: [...prefix, "--help"],
+			validate(result) {
+				if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)? \(Claude Code\)$/.test(result.version)) throw new Error(`Unsupported Claude Code version response: ${JSON.stringify(result.version)}.`);
+				for (const required of ["Claude Code - starts an interactive session", "--print", "--input-format", "stream-json", "--verbose", "--permission-mode", writer ? "acceptEdits" : "plan", "--tools", "--strict-mcp-config", "--mcp-config", "--setting-sources", "--no-session-persistence", "--disable-slash-commands", "--no-chrome"]) {
+					if (!result.help.includes(required)) throw new Error(`Claude Code help does not document required option ${JSON.stringify(required)}.`);
+				}
+			},
+		},
+		parser: createClaudeCodeJsonlParser(),
+	};
+}

package/src/runs/shared/codex-exec-adapter.ts

@@ -0,0 +1,129 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseExternalCliJsonlEvent, type ExternalCliParser, type ExternalCliParserProgress, type ExternalCliParserTerminal } from "./external-cli-runner.ts";
+import type { ExternalCliPreflightSpec } from "./external-cli-preflight.ts";
+
+const MAX_FINAL_MESSAGE_BYTES = 1024 * 1024;
+const MAX_EVENT_TYPE_LENGTH = 128;
+
+export const CODEX_EXEC_ADAPTER_ID = "codex-exec" as const;
+export const CODEX_EXEC_WRITER_ADAPTER_ID = "codex-exec-writer" as const;
+export const CODEX_EXEC_ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"USERPROFILE",
+	"CODEX_HOME",
+	"CODEX_API_KEY",
+	"OPENAI_API_KEY",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy",
+	"SSL_CERT_FILE",
+	"SSL_CERT_DIR",
+] as const;
+
+function eventError(event: Record<string, unknown>, fallback: string): string {
+	const error = event.error;
+	if (typeof error === "string" && error.trim()) return error.trim().slice(0, 4_096);
+	if (error && typeof error === "object" && !Array.isArray(error)) {
+		const message = (error as Record<string, unknown>).message;
+		if (typeof message === "string" && message.trim()) return message.trim().slice(0, 4_096);
+	}
+	const message = event.message;
+	return typeof message === "string" && message.trim() ? message.trim().slice(0, 4_096) : fallback;
+}
+
+export function createCodexExecJsonlParser(finalMessagePath: string): ExternalCliParser {
+	let eventCount = 0;
+	let terminal: ExternalCliParserTerminal | undefined;
+	return {
+		parseLine(line): ExternalCliParserProgress {
+			const event = parseExternalCliJsonlEvent(line, "Codex exec", MAX_EVENT_TYPE_LENGTH);
+			if (terminal) throw new Error("Codex exec emitted an event after its terminal state.");
+			eventCount += 1;
+			if (event.type === "turn.completed") terminal = { state: "completed" };
+			else if (event.type === "turn.failed") terminal = { state: "failed", error: eventError(event, "Codex exec reported turn.failed.") };
+			else if (event.type === "error") terminal = { state: "failed", error: eventError(event, "Codex exec reported an error event.") };
+			return { phase: terminal ? terminal.state : "streaming", eventCount };
+		},
+		finish(): ExternalCliParserTerminal | undefined {
+			if (!terminal || terminal.state === "failed") return terminal;
+			let descriptor: number;
+			try { descriptor = fs.openSync(finalMessagePath, "r"); }
+			catch (error) { throw new Error(`Codex exec did not write its final-message artifact: ${error instanceof Error ? error.message : String(error)}`); }
+			try {
+				const stat = fs.fstatSync(descriptor);
+				if (!stat.isFile()) throw new Error("Codex exec final-message artifact is not a file.");
+				if (stat.size > MAX_FINAL_MESSAGE_BYTES) throw new Error("Codex exec final-message artifact exceeded its byte limit.");
+				const content = Buffer.alloc(stat.size);
+				let bytesRead = 0;
+				while (bytesRead < content.length) {
+					const count = fs.readSync(descriptor, content, bytesRead, content.length - bytesRead, bytesRead);
+					if (count === 0) break;
+					bytesRead += count;
+				}
+				const output = content.subarray(0, bytesRead).toString("utf-8").trim();
+				if (!output) throw new Error("Codex exec final-message artifact is empty.");
+				return { state: "completed", output };
+			} finally { fs.closeSync(descriptor); }
+		},
+	};
+}
+
+export function resolveCodexExecLaunch(input: {
+	adapter: typeof CODEX_EXEC_ADAPTER_ID | typeof CODEX_EXEC_WRITER_ADAPTER_ID;
+	command: string;
+	asyncDir: string;
+	stepIndex: number;
+	/** Test-only executable prefix for a fake Codex process. */
+	commandPrefixArgs?: readonly string[];
+}): {
+	command: string;
+	args: string[];
+	finalOutputPath: string;
+	promptFilePath?: undefined;
+	temporaryDirectories?: undefined;
+	environment: { allowlist: readonly string[] };
+	preflight: ExternalCliPreflightSpec;
+	parser: ExternalCliParser;
+} {
+	const writer = input.adapter === CODEX_EXEC_WRITER_ADAPTER_ID;
+	const finalMessagePath = path.join(input.asyncDir, `external-${input.stepIndex}.final-message.txt`);
+	fs.rmSync(finalMessagePath, { force: true });
+	const prefix = [...(input.commandPrefixArgs ?? [])];
+	const args = [
+		...prefix,
+		"exec",
+		"--json",
+		"--color", "never",
+		"--ephemeral",
+		"--ignore-user-config",
+		"--ignore-rules",
+		"--skip-git-repo-check",
+		"-s", writer ? "workspace-write" : "read-only",
+		"-c", 'approval_policy="never"',
+		"--output-last-message", finalMessagePath,
+		"-",
+	];
+	return {
+		command: input.command,
+		args,
+		finalOutputPath: finalMessagePath,
+		environment: { allowlist: CODEX_EXEC_ENV_ALLOWLIST },
+		preflight: {
+			id: input.adapter,
+			versionArgs: [...prefix, "--version"],
+			helpArgs: [...prefix, "exec", "--help"],
+			validate(result) {
+				if (!/^codex-cli \d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(result.version)) throw new Error(`Unsupported Codex version response: ${JSON.stringify(result.version)}.`);
+				for (const required of ["Run Codex non-interactively", "--json", "--output-last-message", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--skip-git-repo-check", "--sandbox", writer ? "workspace-write" : "read-only", "--config"]) {
+					if (!result.help.includes(required)) throw new Error(`Codex exec help does not document required option ${JSON.stringify(required)}.`);
+				}
+			},
+		},
+		parser: createCodexExecJsonlParser(finalMessagePath),
+	};
+}

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

@@ -47,6 +47,7 @@ interface CompletionMutationGuardInput {
 	messages: Message[];
 	tools?: string[];
 	mcpDirectTools?: string[];
+	mutationTools?: string[];
 	toolAvailabilityError?: string;
 	mutationEvidence?: TrackedMutationEvidence;
 }
@@ -128,7 +129,7 @@ function hasCheckpointMutationEvidence(message: Message): boolean {
 		&& data.beforeCommit !== data.afterCommit;
 }
 
-export function hasMutationToolCall(messages: Message[]): boolean {
+export function hasMutationToolCall(messages: Message[], mutationTools?: readonly string[]): boolean {
 	for (const message of messages) {
 		if (hasCheckpointMutationEvidence(message)) return true;
 		if (message.role !== "assistant") continue;
@@ -138,7 +139,7 @@ export function hasMutationToolCall(messages: Message[]): boolean {
 			const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments)
 				? part.arguments as Record<string, unknown>
 				: {};
-			if (isMutatingTool(part.name, args)) return true;
+			if (isMutatingTool(part.name, args, mutationTools)) return true;
 		}
 	}
 	return false;
@@ -239,7 +240,7 @@ export function evaluateCompletionMutationGuard(input: CompletionMutationGuardIn
 	const expectedMutation = hasMutationToolCapability(input.tools, input.mcpDirectTools)
 		? expectsImplementationMutation(input.agent, input.task)
 		: false;
-	const attemptedMutation = hasMutationToolCall(input.messages) || input.mutationEvidence?.attemptedMutation === true;
+	const attemptedMutation = hasMutationToolCall(input.messages, input.mutationTools) || input.mutationEvidence?.attemptedMutation === true;
 	const noEditChallengeComplete = isImplementationChallengeTask(input.task)
 		&& reportsNoBetterChallengeChange(input.messages);
 	return {