pi-subagents 0.55.0 → 0.57.0

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

@@ -13,7 +13,9 @@ import {
 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 { readWorkflowReceipt, workflowReceiptPath, writeWorkflowReceipt, type WorkflowReceipt } from "../../workflows/workflow-receipt.ts";
+import { workflowChildSummary } from "../../workflows/workflow-child-summary.ts";
 
 function cloneWorkflowStatus(status: AsyncStatus): AsyncStatus {
 	return {
@@ -23,13 +25,16 @@ function cloneWorkflowStatus(status: AsyncStatus): AsyncStatus {
 	};
 }
 
-function childSucceeded(result: Pick<SingleResult, "exitCode" | "error">): boolean {
-	return result.exitCode === 0 && !result.error;
+function childSucceeded(result: Pick<SingleResult, "exitCode" | "error" | "interrupted">): boolean {
+	return result.exitCode === 0 && !result.error && !result.interrupted;
 }
 
+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.";
+
 export function applyDetachedChildToPausedWorkflow(
 	status: AsyncStatus,
-	input: { childRunId: string; result: Pick<SingleResult, "exitCode" | "error" | "sessionFile">; workflowKey?: string },
+	input: { childRunId: string; result: Pick<SingleResult, "exitCode" | "error" | "interrupted" | "sessionFile">; workflowKey?: string },
 ): AsyncStatus | undefined {
 	if (status.mode !== "workflow" || status.state !== "paused") return undefined;
 	const next = cloneWorkflowStatus(status);
@@ -37,6 +42,7 @@ export function applyDetachedChildToPausedWorkflow(
 		?? (input.workflowKey ? next.steps?.find((candidate) => candidate.workflowKey === input.workflowKey) : undefined);
 	if (!step) return undefined;
 	const succeeded = childSucceeded(input.result);
+	const failedSiblingError = next.steps?.find((candidate) => candidate !== step && candidate.status === "failed" && candidate.error)?.error;
 	const updatedAt = Date.now();
 	step.status = succeeded ? "completed" : "failed";
 	step.endedAt = updatedAt;
@@ -45,11 +51,16 @@ export function applyDetachedChildToPausedWorkflow(
 	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;
 	next.lastUpdate = updatedAt;
 	const promoted = promotePausedWorkflowIfSettled(next);
-	if (promoted?.state === "failed" && input.result.error) promoted.error = input.result.error;
-	return promoted ?? next;
+	if (promoted?.state === "failed" && input.result.interrupted && !failedSiblingError) promoted.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
+	else if (promoted?.state === "failed" && input.result.error) promoted.error = input.result.error;
+	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 {
@@ -63,10 +74,11 @@ export function promotePausedWorkflowIfSettled(status: AsyncStatus): AsyncStatus
 	const failed = next.steps.some((candidate) => candidate.status === "failed");
 	const updatedAt = Date.now();
 	next.lastUpdate = updatedAt;
-	next.state = failed ? "failed" : "complete";
+	next.state = "failed";
 	next.endedAt = updatedAt;
 	delete next.activityState;
-	if (!failed) delete next.error;
+	if (failed) return next;
+	next.error = UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION;
 	return next;
 }
 
@@ -83,6 +95,7 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
 				output,
 				outputState: output.trim() ? "present" : "absent",
 				detached: undefined,
+				...(result.interrupted ? { interrupted: true } : {}),
 				...(result.error ? { error: result.error } : {}),
 			};
 		});
@@ -94,6 +107,7 @@ function workflowResultChildren(status: AsyncStatus, childRunId: string, result:
 		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.error ? { error: step.error } : {}),
 	}));
 }
@@ -119,6 +133,7 @@ function publishedWorkflowResult(status: AsyncStatus, childRunId: string, result
 		timestamp: Date.now(),
 		results: workflowResultChildren(status, childRunId, result, existing?.results),
 		workflow: status.workflow,
+		workflowChildren: status.workflowChildren,
 		reconciledFromDetachedChild: childRunId,
 		...(receipt ? { workflowReceipt: { path: path.join(asyncDir, "workflow-receipt.json"), receipt } } : {}),
 		asyncDir,
@@ -145,6 +160,12 @@ 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;
+	if (externalAdapter) resumability = { state: "not-resumable", reason: externalAdapter.nonResumableReason };
 	const updatedEntry: WorkflowReceipt["entries"][string] = resumability.state === "resumable"
 		? {
 			...entry,
@@ -153,6 +174,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			latestRunId: entry.latestRunId ?? childRunId,
 			resumability,
 			...(outputReference ? { outputReference } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
 		}
 		: {
 			...entry,
@@ -160,6 +182,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			...(step.context ? { resolvedContext: step.context } : {}),
 			resumability,
 			...(outputReference ? { outputReference } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
 		};
 	const next: WorkflowReceipt = {
 		...receipt,
@@ -168,6 +191,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			...receipt.entries,
 			[key]: updatedEntry,
 		},
+		workflowChildren: status.workflowChildren,
 	};
 	writeWorkflowReceipt(asyncDir, next);
 	return next;

package/src/runs/shared/acceptance.ts

@@ -404,7 +404,7 @@ function acceptanceRequiresChildReport(acceptance: ResolvedAcceptanceConfig): bo
 	return acceptance.criteria.length > 0 || acceptance.evidence.length > 0;
 }
 
-export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, options: { reportOptional?: boolean } = {}): string {
+export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, options: { reportOptional?: boolean; structuredOutput?: boolean } = {}): string {
 	if (acceptance.level === "none") return "";
 	if (options.reportOptional && !acceptanceRequiresChildReport(acceptance)) return "";
 	const lines = [
@@ -431,13 +431,15 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
 	}
 	lines.push(
 		"",
-		"Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
+		options.structuredOutput
+			? "Include an `acceptanceReport` object in your final `structured_output` tool call in this shape:"
+			: "Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
 		"Use empty arrays when no items apply; array fields contain strings unless object entries are shown.",
 		"Empty-string entries (`[\"\"]`) are ignored; use `[]` when nothing applies.",
 		"`criteriaSatisfied[].status` must be exactly one of: satisfied, not-satisfied, not-applicable.",
 		"`commandsRun[].result` must be exactly one of: passed, failed, not-run.",
 		"`manualNotes` and `notes` are optional strings; an empty string means no note and does not satisfy `manual-notes` evidence.",
-		"```acceptance-report",
+		...(options.structuredOutput ? [] : ["```acceptance-report"]),
 		JSON.stringify({
 			criteriaSatisfied: acceptance.criteria
 				.filter((criterion) => criterion.severity !== "recommended")
@@ -452,7 +454,7 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
 			reviewFindings: ["blocker: file.ts:12 - issue found, or no blockers"],
 			manualNotes: "anything else the parent should know",
 		}, null, 2),
-		"```",
+		...(options.structuredOutput ? [] : ["```"]),
 	);
 	return lines.join("\n");
 }
@@ -1272,6 +1274,7 @@ export async function evaluateAcceptance(input: {
 	 */
 	fileOutput?: { content: string; path: string; authoritative?: boolean };
 	report?: AcceptanceReport;
+	reportError?: string;
 	reviewResult?: AcceptanceReviewResult;
 	signal?: AbortSignal;
 	abortMessage?: string;
@@ -1293,7 +1296,9 @@ export async function evaluateAcceptance(input: {
 	};
 	if (acceptance.level === "none") return ledger;
 
-	const parsed = input.report
+	const parsed = input.reportError
+		? { error: input.reportError }
+		: input.report
 		? (() => {
 			const validation = validateAcceptanceReport(input.report);
 			return validation.report

package/src/runs/shared/agent-contract.ts

@@ -12,7 +12,7 @@ export function buildExecutionProjection(result: Pick<SingleResult, "exitCode" |
 		return { status: "stopped", success: false, exitCode: result.exitCode, stopped: true, ...(result.error ? { error: result.error } : {}) };
 	}
 	if (result.interrupted) {
-		return { status: "paused", success: true, exitCode: result.exitCode, interrupted: true, ...(result.error ? { error: result.error } : {}) };
+		return { status: "paused", success: false, exitCode: result.exitCode, interrupted: true, ...(result.error ? { error: result.error } : {}) };
 	}
 	const success = result.exitCode === 0 && !result.error && !result.timedOut;
 	return {

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

@@ -1,5 +1,5 @@
 import type { Message } from "@earendil-works/pi-ai";
-import type { AcceptanceRole } from "../../shared/types.ts";
+import type { AcceptanceRole, TrackedMutationEvidence } from "../../shared/types.ts";
 import { isMutatingTool } from "./long-running-guard.ts";
 import { classifyTaskMutationIntent, expectsImplementationMutation, taskMayMutate } from "./task-intent.ts";
 
@@ -48,6 +48,7 @@ interface CompletionMutationGuardInput {
 	tools?: string[];
 	mcpDirectTools?: string[];
 	toolAvailabilityError?: string;
+	mutationEvidence?: TrackedMutationEvidence;
 }
 
 interface CompletionMutationGuardResult {
@@ -238,7 +239,7 @@ export function evaluateCompletionMutationGuard(input: CompletionMutationGuardIn
 	const expectedMutation = hasMutationToolCapability(input.tools, input.mcpDirectTools)
 		? expectsImplementationMutation(input.agent, input.task)
 		: false;
-	const attemptedMutation = hasMutationToolCall(input.messages);
+	const attemptedMutation = hasMutationToolCall(input.messages) || input.mutationEvidence?.attemptedMutation === true;
 	const noEditChallengeComplete = isImplementationChallengeTask(input.task)
 		&& reportsNoBetterChallengeChange(input.messages);
 	return {

package/src/runs/shared/cursor-agent-adapter.ts

@@ -0,0 +1,114 @@
+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_EVENT_TYPE_LENGTH = 128;
+const MAX_ERROR_LENGTH = 4_096;
+const MAX_OVERSIZED_TOOL_CALL_BYTES = 1024 * 1024;
+
+export const CURSOR_AGENT_ADAPTER_ID = "cursor-agent" as const;
+export const CURSOR_AGENT_WRITER_ADAPTER_ID = "cursor-agent-writer" as const;
+export const CURSOR_AGENT_ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"USERPROFILE",
+	"CURSOR_API_KEY",
+	"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.result, event.error, event.message]) {
+		if (typeof value === "string" && value.trim()) return value.trim().slice(0, MAX_ERROR_LENGTH);
+	}
+	const subtype = typeof event.subtype === "string" && event.subtype ? event.subtype : "unknown";
+	return `Cursor Agent reported terminal result ${subtype}.`;
+}
+
+export function createCursorAgentJsonlParser(): ExternalCliParser {
+	let eventCount = 0;
+	let terminal: ExternalCliParserTerminal | undefined;
+	return {
+		parseLine(line): ExternalCliParserProgress {
+			const event = parseExternalCliJsonlEvent(line, "Cursor Agent", MAX_EVENT_TYPE_LENGTH);
+			if (terminal) throw new Error("Cursor Agent emitted an event after its terminal state.");
+			eventCount += 1;
+			if (event.type === "error") terminal = { state: "failed", error: terminalError(event) };
+			else if (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 };
+		},
+		skipOversizedLine(prefix, byteLength): ExternalCliParserProgress | undefined {
+			if (terminal || byteLength > MAX_OVERSIZED_TOOL_CALL_BYTES || !/^\s*\{\s*"type"\s*:\s*"tool_call"\s*,/.test(prefix)) return undefined;
+			eventCount += 1;
+			return { phase: "streaming", eventCount };
+		},
+		finish(): ExternalCliParserTerminal | undefined {
+			return terminal;
+		},
+	};
+}
+
+export function resolveCursorAgentLaunch(input: {
+	adapter: typeof CURSOR_AGENT_ADAPTER_ID | typeof CURSOR_AGENT_WRITER_ADAPTER_ID;
+	command: string;
+	cwd: string;
+	asyncDir: string;
+	stepIndex: number;
+	/** Test-only executable prefix for a fake Cursor Agent process. */
+	commandPrefixArgs?: readonly string[];
+}): {
+	command: string;
+	args: string[];
+	finalOutputPath?: undefined;
+	promptFilePath: string;
+	temporaryDirectories: string[];
+	environment: { allowlist: readonly string[] };
+	preflight: ExternalCliPreflightSpec;
+	parser: ExternalCliParser;
+} {
+	const writer = input.adapter === CURSOR_AGENT_WRITER_ADAPTER_ID;
+	const promptDirectory = path.join(input.asyncDir, `external-${input.stepIndex}.cursor-prompt`);
+	const promptFilePath = path.join(promptDirectory, "handoff.txt");
+	const promptRelative = path.relative(input.cwd, promptDirectory);
+	const promptOutsideWorkspace = promptRelative.startsWith("..") || path.isAbsolute(promptRelative);
+	const prefix = [...(input.commandPrefixArgs ?? [])];
+	const args = [
+		...prefix,
+		"-p",
+		"--output-format", "stream-json",
+		...(writer ? [] : ["--mode", "ask"]),
+		"--sandbox", "enabled",
+		"--workspace", input.cwd,
+		...(promptOutsideWorkspace ? ["--add-dir", promptDirectory] : []),
+		`Read the complete handoff from the private file at ${promptFilePath}. Follow it and return only the final answer.`,
+	];
+	return {
+		command: input.command,
+		args,
+		promptFilePath,
+		temporaryDirectories: [promptDirectory],
+		environment: { allowlist: CURSOR_AGENT_ENV_ALLOWLIST },
+		preflight: {
+			id: input.adapter,
+			versionArgs: [...prefix, "--version"],
+			helpArgs: [...prefix, "--help"],
+			validate(result) {
+				if (!/^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/.test(result.version)) throw new Error(`Unsupported Cursor Agent version response: ${JSON.stringify(result.version)}.`);
+				for (const required of ["Start the Cursor Agent", "--print", "stream-json", "--sandbox <mode>", "enabled", "--workspace <path-or-name>", "--add-dir <path>", ...(writer ? ["all tools", "including write and shell"] : ["--mode <mode>", "ask:", "read-only"])]) {
+					if (!result.help.includes(required)) throw new Error(`Cursor Agent help does not document required option ${JSON.stringify(required)}.`);
+				}
+			},
+		},
+		parser: createCursorAgentJsonlParser(),
+	};
+}

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

@@ -46,7 +46,7 @@ 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", "toolBudget", "acceptance", "agentContract", "gateOn"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled",