@selesai/code 0.12.0 → 0.13.1

package/dist/extensions/pi-subagents/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/dist/extensions/pi-subagents/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/dist/extensions/pi-subagents/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/dist/extensions/pi-subagents/src/runs/shared/completion-evidence.ts

@@ -0,0 +1,89 @@
+import type {
+	FileMutationEffect,
+	SettlementDiagnostic,
+	TrackedMutationEvidence,
+} from "../../shared/types.ts";
+import type { CompletionMutationGuardResult } from "./completion-guard.ts";
+
+export const MISSING_IMPLEMENTATION_MUTATION_MESSAGE = "Subagent completed without making edits for an implementation task.";
+export const MISSING_IMPLEMENTATION_MUTATION_ERROR = `${MISSING_IMPLEMENTATION_MUTATION_MESSAGE}\nIt appears to have returned planning or scratchpad output instead of applying changes.`;
+
+export interface CompletionEvidencePlan {
+	guardTriggered: boolean;
+	guardBlocked: boolean;
+	mutationExpected: boolean;
+	mutationAttempted: boolean;
+	fileMutation?: FileMutationEffect;
+	legacyFailureError?: string;
+}
+
+export function planCompletionEvidence(input: {
+	guard?: CompletionMutationGuardResult;
+	guardTriggered?: boolean;
+	completionGuardEnabled: boolean;
+	mutationCapable: boolean;
+	implementationMutationExpected: boolean;
+	mutationAttemptObserved: boolean;
+	mutationEvidence?: TrackedMutationEvidence;
+	arbiterRescued?: boolean;
+	agentContractV1: boolean;
+}): CompletionEvidencePlan {
+	const guardBlocked = input.guard?.blocked === true;
+	const guardTriggered = input.guardTriggered
+		?? (input.guard?.triggered === true && !input.mutationAttemptObserved);
+	const mutationExpected = input.guard?.expectedMutation
+		?? (input.completionGuardEnabled && input.mutationCapable && input.implementationMutationExpected);
+	const mutationAttempted = input.guard?.attemptedMutation === true || input.mutationAttemptObserved;
+	const fileMutation = input.guard
+		? {
+			status: guardBlocked
+				? "blocked" as const
+				: input.guard.expectedMutation
+					? guardTriggered
+						? "missing" as const
+						: input.arbiterRescued
+							? "not-applicable" as const
+							: "observed" as const
+					: "not-applicable" as const,
+			expected: input.guard.expectedMutation,
+			attempted: guardBlocked ? false : mutationAttempted,
+			...(input.mutationEvidence ? { evidence: input.mutationEvidence } : {}),
+			...(guardBlocked && input.guard.message ? { message: input.guard.message } : {}),
+			...(guardTriggered ? { message: MISSING_IMPLEMENTATION_MUTATION_MESSAGE } : {}),
+			...(input.arbiterRescued ? { resolvedBy: "llm-intent-arbiter" as const } : {}),
+		}
+		: undefined;
+	return {
+		guardTriggered,
+		guardBlocked,
+		mutationExpected,
+		mutationAttempted,
+		fileMutation,
+		legacyFailureError: guardTriggered && !input.agentContractV1
+			? MISSING_IMPLEMENTATION_MUTATION_ERROR
+			: undefined,
+	};
+}
+
+export function projectSettlementDiagnostic(
+	plan: Pick<CompletionEvidencePlan, "guardTriggered" | "guardBlocked" | "mutationExpected" | "mutationAttempted">,
+	input: {
+		terminalFailed: boolean;
+		finalTextPresent: boolean;
+		mutationObserved: boolean;
+		requiredOutput?: SettlementDiagnostic["requiredOutput"];
+		afterCompactionSettlement?: boolean;
+	},
+): SettlementDiagnostic | undefined {
+	if (!input.terminalFailed && !plan.guardTriggered && !plan.guardBlocked) return undefined;
+	return {
+		finalTextPresent: input.finalTextPresent,
+		mutation: {
+			expected: plan.mutationExpected,
+			attempted: plan.mutationAttempted,
+			observed: input.mutationObserved,
+		},
+		...(input.requiredOutput ? { requiredOutput: input.requiredOutput } : {}),
+		afterCompactionSettlement: input.afterCompactionSettlement === true,
+	};
+}

package/dist/extensions/pi-subagents/src/runs/shared/completion-guard.ts

@@ -47,11 +47,12 @@ interface CompletionMutationGuardInput {
 	messages: Message[];
 	tools?: string[];
 	mcpDirectTools?: string[];
+	mutationTools?: string[];
 	toolAvailabilityError?: string;
 	mutationEvidence?: TrackedMutationEvidence;
 }
 
-interface CompletionMutationGuardResult {
+export interface CompletionMutationGuardResult {
 	expectedMutation: boolean;
 	attemptedMutation: boolean;
 	triggered: boolean;
@@ -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 {

package/dist/extensions/pi-subagents/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/dist/extensions/pi-subagents/src/runs/shared/dynamic-fanout.ts

@@ -49,9 +49,9 @@ const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
 const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
-	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled",
-	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "capabilityCeiling", "completionGuard", "systemPrompt",
-	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions",
+	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
+	"structuredOutput", "structuredOutputSchema", "tools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
+	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);