pi-subagents 0.56.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 {
@@ -55,7 +57,10 @@ export function applyDetachedChildToPausedWorkflow(
 	const promoted = promotePausedWorkflowIfSettled(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;
-	return promoted ?? next;
+	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 {
@@ -128,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,
@@ -154,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,
@@ -162,6 +174,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			latestRunId: entry.latestRunId ?? childRunId,
 			resumability,
 			...(outputReference ? { outputReference } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
 		}
 		: {
 			...entry,
@@ -169,6 +182,7 @@ function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, resul
 			...(step.context ? { resolvedContext: step.context } : {}),
 			resumability,
 			...(outputReference ? { outputReference } : {}),
+			...(externalAdapter ? { externalAdapter } : {}),
 		};
 	const next: WorkflowReceipt = {
 		...receipt,
@@ -177,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/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/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/external-cli-contract.ts

@@ -0,0 +1,167 @@
+import type {
+	ExternalCliReceiptMetadata,
+	ExternalCliCapabilityNarrowing,
+	ExternalCliRunnerStatus,
+	ExternalProcessStatus,
+} from "../../shared/types.ts";
+
+const UNSUPPORTED = {
+	steer: "The one-shot stdin adapter closes input after launch and cannot accept live steer messages.",
+	resume: "The one-shot stdin adapter has no durable external session identity.",
+	structuredOutput: "The generic external CLI adapter does not parse a trusted structured result.",
+	toolEvents: "The generic external CLI adapter treats stdout as untrusted text, not native Pi tool events.",
+	supervisor: "The generic external CLI adapter has no trusted supervisor event transport.",
+	forkContext: "Native Pi fork context is not available without an adapter-owned handoff artifact.",
+	extensionBindings: "Native Pi extension bindings are never passed to external runners.",
+} as const;
+
+const CAPABILITY_KEYS = new Set(Object.keys(UNSUPPORTED));
+const PROMPT_FILE_UNSUPPORTED = {
+	...UNSUPPORTED,
+	steer: "The one-shot prompt-file adapter closes input after launch and cannot accept live steer messages.",
+	resume: "The one-shot prompt-file adapter does not retain a durable external session identity.",
+} as const;
+
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS = [
+	"codex-exec",
+	"codex-exec-writer",
+	"claude-code",
+	"claude-code-writer",
+	"cursor-agent",
+	"cursor-agent-writer",
+] as const;
+export type CodeOwnedExternalCliAdapterId = typeof CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS[number];
+
+const CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET = new Set<string>(CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS);
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL = CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS.map((id) => `'${id}'`).join(", ");
+
+export function isCodeOwnedExternalCliAdapterId(value: unknown): value is CodeOwnedExternalCliAdapterId {
+	return typeof value === "string" && CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET.has(value);
+}
+
+const RESERVED_READ_ONLY_ADAPTERS = [
+	{ name: "claude-code", writer: "claude-code-writer", access: "file-write" },
+	{ name: "codex-exec", writer: "codex-exec-writer", access: "workspace-write" },
+	{ name: "cursor-agent", writer: "cursor-agent-writer", access: "workspace-write" },
+] as const;
+
+export function validateCodeOwnedProfileRunner(
+	agent: {
+		name: string;
+		localName?: string;
+		aliases?: readonly string[];
+		runner?: { type: string; adapter?: string };
+	},
+): string | undefined {
+	const selectionNames = [agent.name, ...(agent.localName ? [agent.localName] : []), ...(agent.aliases ?? [])];
+	for (const adapter of RESERVED_READ_ONLY_ADAPTERS) {
+		if (selectionNames.includes(adapter.name) && !(agent.runner?.type === "external-cli" && agent.runner.adapter === adapter.name)) {
+			return `Selection name '${adapter.name}' is reserved for the read-only '${adapter.name}' adapter. Use '${adapter.writer}' for explicit ${adapter.access} access.`;
+		}
+	}
+	return undefined;
+}
+
+export function parseExternalCliCapabilityNarrowing(value: unknown, label: string): ExternalCliCapabilityNarrowing | undefined {
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+	const input = value as Record<string, unknown>;
+	const unknown = Object.keys(input).filter((key) => !CAPABILITY_KEYS.has(key));
+	if (unknown.length > 0) throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
+	for (const [key, setting] of Object.entries(input)) {
+		if (setting !== false) throw new Error(`${label}.${key} may only be false; user config cannot widen code-owned external adapter capabilities.`);
+	}
+	return input as ExternalCliCapabilityNarrowing;
+}
+
+export function resolveExternalCliRunnerStatus(input: {
+	adapter?: CodeOwnedExternalCliAdapterId;
+	command: string;
+	args?: string[];
+	promptDelivery?: "stdin";
+	capabilities?: ExternalCliCapabilityNarrowing;
+}): ExternalCliRunnerStatus {
+	const codexExec = input.adapter === "codex-exec";
+	const codexExecWriter = input.adapter === "codex-exec-writer";
+	const claudeCode = input.adapter === "claude-code";
+	const claudeCodeWriter = input.adapter === "claude-code-writer";
+	const cursorAgent = input.adapter === "cursor-agent";
+	const cursorAgentWriter = input.adapter === "cursor-agent-writer";
+	const cursor = cursorAgent || cursorAgentWriter;
+	const unsupported = cursor ? PROMPT_FILE_UNSUPPORTED : UNSUPPORTED;
+	return {
+		type: "external-cli",
+		command: input.command,
+		args: input.args ?? [],
+		promptDelivery: cursor ? "prompt-file" : input.promptDelivery ?? "stdin",
+		adapter: { id: input.adapter ?? "external-cli", version: 1, executionMode: cursor ? "one-shot-prompt-file" : "one-shot-stdin" },
+		...(codexExec ? { safety: { sandbox: "read-only" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
+		...(codexExecWriter ? { safety: { access: "workspace-write" as const, sandbox: "workspace-write" as const, approvalPolicy: "never" as const, ephemeral: true as const } } : {}),
+		...(claudeCode ? { safety: { access: "read-only" as const, authentication: "existing-cli-required" as const, permissionMode: "plan" as const, tools: "none" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
+		...(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 } } : {}),
+		capabilities: {
+			stop: true,
+			steer: false,
+			resume: false,
+			structuredOutput: false,
+			toolEvents: false,
+			supervisor: "unsupported",
+			forkContext: false,
+			extensionBindings: false,
+		},
+		unsupportedReasons: unsupported,
+		nonResumableReason: unsupported.resume,
+	};
+}
+
+export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRunnerStatus | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Record<string, unknown>;
+	if (input.type !== "external-cli" || typeof input.command !== "string" || !input.command.trim()) return undefined;
+	const args = Array.isArray(input.args) && input.args.every((arg) => typeof arg === "string")
+		? input.args
+		: undefined;
+	const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
+	const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter)
+		? (input.adapter as Record<string, unknown>).id
+		: undefined;
+	if (adapterId === "grok-build") {
+		return {
+			type: "external-cli",
+			command: input.command,
+			args: args ?? [],
+			promptDelivery: "prompt-file",
+			adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
+			capabilities: { stop: true, steer: false, resume: false, structuredOutput: false, toolEvents: false, supervisor: "unsupported", forkContext: false, extensionBindings: false },
+			unsupportedReasons: PROMPT_FILE_UNSUPPORTED,
+			nonResumableReason: PROMPT_FILE_UNSUPPORTED.resume,
+		};
+	}
+	const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
+	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}) });
+}
+
+export function externalCliReceiptMetadata(input: {
+	runner: ExternalCliRunnerStatus;
+	externalProcess?: ExternalProcessStatus;
+	outputReference?: string;
+}): ExternalCliReceiptMetadata {
+	const { runner } = input;
+	return {
+		adapter: { ...runner.adapter },
+		capabilities: { ...runner.capabilities },
+		...(runner.safety ? { safety: { ...runner.safety } } : {}),
+		...(input.externalProcess ? {
+			outputArtifacts: {
+				stdoutPath: input.externalProcess.stdoutPath,
+				stderrPath: input.externalProcess.stderrPath,
+				...(input.outputReference || input.externalProcess.finalOutputPath ? { finalOutputPath: input.outputReference ?? input.externalProcess.finalOutputPath } : {}),
+			},
+		} : input.outputReference ? { outputArtifacts: { finalOutputPath: input.outputReference } } : {}),
+		handoff: { mode: "fresh" },
+		supervisor: { mode: "unsupported", reason: runner.unsupportedReasons.supervisor },
+		nonResumableReason: runner.nonResumableReason,
+	};
+}