pi-subagents 0.55.0 → 0.56.0

package/src/runs/shared/mutation-evidence.ts

@@ -0,0 +1,145 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ArtifactPaths, TimeoutRecoverySummary, TrackedMutationEvidence, TrackedMutationFingerprint, TrackedMutationSnapshot } from "../../shared/types.ts";
+
+const MAX_TRACKED_PATHS = 500;
+const MAX_HASH_BYTES = 1024 * 1024;
+const MAX_TIMEOUT_FILES = 20;
+
+function gitOutput(cwd: string, args: string[], maxBuffer = MAX_HASH_BYTES): string {
+	return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer });
+}
+
+function splitNul(output: string): string[] {
+	return output.split("\0").filter((part) => part.length > 0);
+}
+
+function hashLargeDiff(cwd: string, relativePath: string): string {
+	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tracked-diff-"));
+	const diffPath = path.join(tempDir, "diff.patch");
+	try {
+		execFileSync("git", ["diff", "--no-ext-diff", "--binary", `--output=${diffPath}`, "HEAD", "--", relativePath], { cwd, stdio: "ignore" });
+		const hash = createHash("sha256");
+		const buffer = Buffer.allocUnsafe(64 * 1024);
+		const fd = fs.openSync(diffPath, "r");
+		try {
+			for (;;) {
+				const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+				if (bytesRead === 0) break;
+				hash.update(buffer.subarray(0, bytesRead));
+			}
+		} finally {
+			fs.closeSync(fd);
+		}
+		return hash.digest("hex");
+	} finally {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
+function listChangedTrackedFiles(cwd: string): { paths: string[]; truncated: boolean } {
+	const paths = splitNul(gitOutput(cwd, ["diff", "--no-ext-diff", "--name-only", "-z", "HEAD", "--"], MAX_HASH_BYTES));
+	return { paths: paths.slice(0, MAX_TRACKED_PATHS), truncated: paths.length > MAX_TRACKED_PATHS };
+}
+
+function fingerprintPath(cwd: string, relativePath: string): TrackedMutationFingerprint {
+	try {
+		const diff = gitOutput(cwd, ["diff", "--no-ext-diff", "--binary", "HEAD", "--", relativePath], MAX_HASH_BYTES);
+		return { kind: "diff", digest: createHash("sha256").update(diff).digest("hex") };
+	} catch {
+		return { kind: "diff", digest: hashLargeDiff(cwd, relativePath) };
+	}
+}
+
+function sameFingerprint(left: TrackedMutationFingerprint | undefined, right: TrackedMutationFingerprint): boolean {
+	if (!left || left.kind !== "diff" || right.kind !== "diff") return false;
+	return left.digest === right.digest;
+}
+
+export function snapshotTrackedMutations(cwd: string): TrackedMutationSnapshot {
+	try {
+		const changed = listChangedTrackedFiles(cwd);
+		const fingerprints: Record<string, TrackedMutationFingerprint> = {};
+		for (const file of changed.paths) fingerprints[file] = fingerprintPath(cwd, file);
+		return { source: "tracked-files", trackedOnly: true, cwd, dirtyFiles: changed.paths, fingerprints, truncated: changed.truncated };
+	} catch (error) {
+		return { source: "tracked-files", trackedOnly: true, cwd, dirtyFiles: [], fingerprints: {}, unavailable: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+export function collectTrackedMutationEvidence(snapshot: TrackedMutationSnapshot, cwd = snapshot.cwd): TrackedMutationEvidence {
+	if (snapshot.unavailable) {
+		return { source: "tracked-files", trackedOnly: true, changedFiles: [], attemptedMutation: false, unavailable: snapshot.unavailable };
+	}
+	try {
+		const current = listChangedTrackedFiles(cwd);
+		const startDirty = new Set(snapshot.dirtyFiles);
+		const candidates = new Set([...snapshot.dirtyFiles, ...current.paths]);
+		const changedFiles: string[] = [];
+		for (const file of candidates) {
+			if (!startDirty.has(file)) {
+				if (!snapshot.truncated) changedFiles.push(file);
+				continue;
+			}
+			if (!sameFingerprint(snapshot.fingerprints[file], fingerprintPath(cwd, file))) changedFiles.push(file);
+		}
+		changedFiles.sort();
+		return {
+			source: "tracked-files",
+			trackedOnly: true,
+			changedFiles,
+			attemptedMutation: changedFiles.length > 0,
+			truncated: snapshot.truncated || current.truncated || undefined,
+		};
+	} catch (error) {
+		return { source: "tracked-files", trackedOnly: true, changedFiles: [], attemptedMutation: false, unavailable: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function formatPathList(paths: string[]): string {
+	if (paths.length === 0) return "none";
+	const shown = paths.slice(0, MAX_TIMEOUT_FILES).join(", ");
+	return paths.length > MAX_TIMEOUT_FILES ? `${shown}, ... (${paths.length - MAX_TIMEOUT_FILES} more)` : shown;
+}
+
+export function buildTimeoutRecoverySummary(input: {
+	termination: "timed-out" | "stopped";
+	evidence: TrackedMutationEvidence;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentPath?: string;
+	sessionFile?: string;
+	transcriptPath?: string;
+	artifactPaths?: ArtifactPaths;
+}): TimeoutRecoverySummary {
+	const warning = "Inspect partial changes before retrying or resuming the child.";
+	const changedFiles = input.evidence.changedFiles.slice(0, MAX_TIMEOUT_FILES);
+	const lines = [
+		"Recovery summary:",
+		`- termination: ${input.termination}`,
+		`- changed tracked files: ${input.evidence.unavailable ? `unavailable (${input.evidence.unavailable})` : formatPathList(input.evidence.changedFiles)}`,
+	];
+	if (input.currentTool) lines.push(`- active tool: ${input.currentTool}${input.currentToolArgs ? ` — ${input.currentToolArgs}` : ""}`);
+	if (input.currentPath) lines.push(`- active path: ${input.currentPath}`);
+	if (input.sessionFile) lines.push(`- session file: ${input.sessionFile}`);
+	if (input.transcriptPath) lines.push(`- transcript: ${input.transcriptPath}`);
+	if (input.artifactPaths?.outputPath) lines.push(`- output artifact: ${input.artifactPaths.outputPath}`);
+	if (input.artifactPaths?.metadataPath) lines.push(`- metadata artifact: ${input.artifactPaths.metadataPath}`);
+	lines.push(`Warning: ${warning}`);
+	return {
+		termination: input.termination,
+		changedFiles,
+		truncated: input.evidence.changedFiles.length > changedFiles.length || input.evidence.truncated || undefined,
+		currentTool: input.currentTool,
+		currentToolArgs: input.currentToolArgs,
+		currentPath: input.currentPath,
+		sessionFile: input.sessionFile,
+		transcriptPath: input.transcriptPath,
+		artifactPaths: input.artifactPaths,
+		warning,
+		message: lines.join("\n"),
+	};
+}

package/src/runs/shared/parallel-utils.ts

@@ -29,6 +29,7 @@ export interface RunnerSubagentStep {
 	structured?: boolean;
 	cwd?: string;
 	model?: string;
+	fast?: boolean;
 	thinking?: string;
 	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
 	modelCandidates?: string[];
@@ -59,12 +60,14 @@ export interface RunnerSubagentStep {
 		schema: import("../../shared/types.ts").JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
+		acceptanceReportPath?: string;
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
 	agentContract?: import("../../shared/types.ts").AgentContract;
 	definitionDigest?: string;
 	launchBindingTask?: string;
 	launchContractDigest?: string;
+	extensionBindings?: import("./extension-bindings.ts").ExtensionBindings;
 	launchResolvedExtensions?: import("../../shared/types.ts").LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: import("../../shared/types.ts").RuntimeAcknowledgedChildExtensionsV1;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;

package/src/runs/shared/pi-args.ts

@@ -13,8 +13,10 @@ import {
 	type ResolvedMcpDirectToolSelection,
 } from "./mcp-direct-tool-allowlist.ts";
 import { resolvePiPackageRoot } from "./pi-spawn.ts";
+import { encodeExtensionBindings, PI_SUBAGENT_EXTENSION_BINDINGS_ENV, type ExtensionBindings } from "./extension-bindings.ts";
 import { RUNTIME_EXTENSION_ACK_PATH_ENV } from "./runtime-acknowledged-extensions.ts";
 import {
+	STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV,
 	STRUCTURED_OUTPUT_CAPTURE_ENV,
 	STRUCTURED_OUTPUT_SCHEMA_ENV,
 } from "./structured-output.ts";
@@ -104,6 +106,14 @@ const FANOUT_CHILD_EXTENSION_PATH = path.join(
 	"extension",
 	"fanout-child.ts",
 );
+const FAST_MODE_EXTENSION_PATH = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"fast-mode-extension.ts",
+);
+const FAST_MODE_ALLOWED_MODELS = new Set([
+	"openai-codex/gpt-5.6-luna",
+	"openai-codex/gpt-5.6-sol",
+]);
 export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 export const SUBAGENT_ORCHESTRATOR_TARGET_ENV =
 	"PI_SUBAGENT_ORCHESTRATOR_TARGET";
@@ -173,7 +183,10 @@ export interface BuildPiArgsInput {
 		schema: JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
+		acceptanceReportPath?: string;
 	};
+	fast?: boolean;
+	modelCandidates?: readonly string[];
 	toolBudget?: ResolvedToolBudget;
 	allowZeroToolBudget?: boolean;
 	permissionRules?: PermissionRules;
@@ -188,6 +201,7 @@ export interface BuildPiArgsInput {
 	waitToolEnabled?: boolean;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
+	extensionBindings?: ExtensionBindings;
 }
 
 export interface BuildPiArgsResult {
@@ -237,6 +251,28 @@ export function applyThinkingSuffix(
 	return `${model}:${thinking}`;
 }
 
+function stripThinkingSuffix(model: string): string {
+	const colonIdx = model.lastIndexOf(":");
+	if (colonIdx === -1) return model;
+	return THINKING_LEVELS.some((level) => level === model.substring(colonIdx + 1))
+		? model.slice(0, colonIdx)
+		: model;
+}
+
+function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fast" | "model" | "modelCandidates" | "agentName">): string[] {
+	if (!input.fast) return [];
+	const candidates = (input.modelCandidates?.length ? input.modelCandidates : input.model ? [input.model] : [])
+		.map(stripThinkingSuffix);
+	if (candidates.length === 0) {
+		throw new Error(`fast mode requires an explicit supported native OpenAI-Codex model${input.agentName ? ` for agent '${input.agentName}'` : ""}.`);
+	}
+	const unsupported = candidates.filter((model) => !FAST_MODE_ALLOWED_MODELS.has(model));
+	if (unsupported.length > 0) {
+		throw new Error(`fast mode supports only ${[...FAST_MODE_ALLOWED_MODELS].join(", ")}; unsupported model${unsupported.length === 1 ? "" : "s"}: ${unsupported.join(", ")}.`);
+	}
+	return [FAST_MODE_EXTENSION_PATH];
+}
+
 export interface ResolvePiLaunchToolPlanInput {
 	tools?: string[];
 	extensions?: string[];
@@ -251,6 +287,9 @@ export interface ResolvePiLaunchToolPlanInput {
 				schemaPath: string;
 				outputPath: string;
 		  };
+	fast?: boolean;
+	model?: string;
+	modelCandidates?: readonly string[];
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	agentName?: string;
@@ -464,8 +503,11 @@ export function resolvePiLaunchToolPlan(
 		: hasPermissionRules(input.permissionRules)
 			? resolvePermissionSystemExtension()
 			: undefined;
+	if (input.fast && capabilityCeiling?.denyExtensions) throw new Error("fast mode requires a child runtime extension, but this launch denies extensions.");
+	const fastModeExtensions = resolveFastModeExtension({ fast: input.fast, model: input.model, modelCandidates: input.modelCandidates, agentName: input.agentName });
 	const runtimeExtensions = [
 		PROMPT_RUNTIME_EXTENSION_PATH,
+		...fastModeExtensions,
 		...(fanoutAuthorized ? [FANOUT_CHILD_EXTENSION_PATH] : []),
 		...(permSystemExt ? [permSystemExt] : []),
 	];
@@ -605,6 +647,9 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		cwd: input.cwd,
 		requireReadTool: input.requireReadTool,
 		structuredOutput: input.structuredOutput,
+		fast: input.fast,
+		model: modelArg,
+		modelCandidates: input.modelCandidates,
 		capabilityCeiling: input.capabilityCeiling,
 		inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(
 			process.env[SUBAGENT_CAPABILITY_CEILING_ENV],
@@ -668,6 +713,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	}
 
 	const env: Record<string, string | undefined> = {};
+	env[PI_SUBAGENT_EXTENSION_BINDINGS_ENV] = encodeExtensionBindings(input.extensionBindings);
 	const piPackageRoot =
 		process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV] ?? resolvePiPackageRoot();
 	if (piPackageRoot) env[PI_CODING_AGENT_PACKAGE_ROOT_ENV] = piPackageRoot;
@@ -838,6 +884,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.structuredOutput) {
 		env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput.outputPath;
 		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
+		if (input.structuredOutput.acceptanceReportPath) env[STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV] = input.structuredOutput.acceptanceReportPath;
 	}
 	if (input.steerInboxDir) {
 		env[SUBAGENT_STEER_INBOX_ENV] = input.steerInboxDir;

package/src/runs/shared/structured-output.ts

@@ -8,12 +8,14 @@ import type { JsonSchemaObject } from "../../shared/types.ts";
 
 export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
 export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
+export const STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE";
 export const MISSING_STRUCTURED_OUTPUT_CALL_ERROR = "Missing structured_output call; this step has outputSchema and must finish by calling structured_output.";
 
 export interface StructuredOutputRuntime {
 	schema: JsonSchemaObject;
 	schemaPath: string;
 	outputPath: string;
+	acceptanceReportPath?: string;
 }
 
 const SCHEMA_MAP_KEYWORDS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"] as const;
@@ -59,10 +61,13 @@ function rewriteLocalJsonPointerRefs(schema: unknown, pointerPrefix: string, inh
 	return rewritten;
 }
 
-export function createStructuredOutputToolParameters(schema: JsonSchemaObject): JsonSchemaObject {
+export function createStructuredOutputToolParameters(schema: JsonSchemaObject, options: { acceptanceReport?: boolean } = {}): JsonSchemaObject {
 	return {
 		type: "object",
-		properties: { value: rewriteLocalJsonPointerRefs(schema, "#/properties/value") },
+		properties: {
+			value: rewriteLocalJsonPointerRefs(schema, "#/properties/value"),
+			...(options.acceptanceReport ? { acceptanceReport: { type: "object" } } : {}),
+		},
 		required: ["value"],
 		additionalProperties: false,
 	};
@@ -124,7 +129,7 @@ export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"):
 	}
 }
 
-export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string): StructuredOutputRuntime {
+export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string, options: { captureAcceptanceReport?: boolean } = {}): StructuredOutputRuntime {
 	assertJsonSchemaObject(schema);
 	const rootDir = baseDir ?? os.tmpdir();
 	fs.mkdirSync(rootDir, { recursive: true });
@@ -132,7 +137,7 @@ export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?
 	const schemaPath = path.join(dir, "schema.json");
 	const outputPath = path.join(dir, "output.json");
 	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
-	return { schema, schemaPath, outputPath };
+	return { schema, schemaPath, outputPath, ...(options.captureAcceptanceReport ? { acceptanceReportPath: path.join(dir, "acceptance-report.json") } : {}) };
 }
 
 export async function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): Promise<{ status: "valid" } | { status: "invalid"; message: string }> {
@@ -172,6 +177,15 @@ export async function readStructuredOutput(runtime: StructuredOutputRuntime): Pr
 	return { value };
 }
 
+export function readStructuredOutputAcceptanceReport(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
+	if (!runtime.acceptanceReportPath || !fs.existsSync(runtime.acceptanceReportPath)) return {};
+	try {
+		return { value: JSON.parse(fs.readFileSync(runtime.acceptanceReportPath, "utf-8")) };
+	} catch (error) {
+		return { error: `Failed to read structured output acceptance report: ${error instanceof Error ? error.message : String(error)}` };
+	}
+}
+
 export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime | undefined): void {
 	if (!runtime) return;
 	try {

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -8,7 +8,7 @@ import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, P
 import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerDeliveryStatus, type SteerRequest } from "../background/control-channel.ts";
 import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV, isRuntimeAcknowledgedExtensionId, writeRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
-import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
+import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
 import {
 	CHILD_TOOL_DIAGNOSTIC_PATH_ENV,
 	formatChildToolDiagnostic,
@@ -634,29 +634,33 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		await drainOutstandingWork({ state: waitState, events: pi.events });
 	});
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
+	const structuredAcceptanceReportPath = process.env[STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV];
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {
 		const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8")) as JsonSchemaObject;
-		const parameters = createStructuredOutputToolParameters(schema);
+		const parameters = createStructuredOutputToolParameters(schema, { acceptanceReport: Boolean(structuredAcceptanceReportPath) });
 		const registerTool = pi.registerTool as unknown as (tool: {
 			name: string;
 			label: string;
 			description: string;
 			parameters: unknown;
-			execute: (_id: string, params: { value: unknown }) => Promise<unknown>;
+			execute: (_id: string, params: { value: unknown; acceptanceReport?: unknown }) => Promise<unknown>;
 		}) => void;
 		registerTool({
 			name: "structured_output",
 			label: "Structured Output",
 			description: "Submit the required final structured output for this subagent step. This terminates the step.",
-			parameters: parameters as never,
-			async execute(_id: string, params: { value: unknown }) {
+			parameters,
+			async execute(_id: string, params: { value: unknown; acceptanceReport?: unknown }) {
 				const validation = await validateStructuredOutputValue(schema, params.value);
 				if (validation.status === "invalid") {
 					throw new Error(`Structured output validation failed: ${validation.message}`);
 				}
 				fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
 				fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
+				if (structuredAcceptanceReportPath && params.acceptanceReport !== undefined) {
+					fs.writeFileSync(structuredAcceptanceReportPath, JSON.stringify(params.acceptanceReport), { mode: 0o600 });
+				}
 				return {
 					content: [{ type: "text", text: "Structured output captured." }],
 					details: { path: structuredOutputPath },

package/src/shared/launch-contract.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import type { AgentConfig } from "../agents/agents.ts";
+import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
 
 export const AGENT_DEFINITION_PROJECTION_VERSION = 1 as const;
 export const LAUNCH_BINDING_PROJECTION_VERSION = 1 as const;
@@ -46,6 +47,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 		model: agent.model,
 		modelProvider: agent.modelProvider,
 		fallbackModels: agent.fallbackModels,
+		fast: agent.fast,
 		thinking: agent.thinking,
 		tools: agent.tools,
 		mcpDirectTools: agent.mcpDirectTools,
@@ -80,6 +82,7 @@ export interface LaunchBindingInput {
 	task?: string;
 	model?: string;
 	modelCandidates?: string[];
+	fast?: boolean;
 	thinking?: string;
 	systemPrompt?: string | null;
 	systemPromptMode?: AgentConfig["systemPromptMode"];
@@ -93,6 +96,7 @@ export interface LaunchBindingInput {
 	outputPath?: string;
 	outputMode?: string;
 	structuredOutputSchema?: unknown;
+	extensionBindings?: ExtensionBindings;
 }
 
 /** Canonical projection of the resolved inputs handed to the child. */
@@ -104,6 +108,7 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
 		// The ordered candidate set already contains each attempted model; keeping only
 		// this set makes retries correlate to the same preflight binding.
 		modelCandidates: input.modelCandidates,
+		fast: input.fast,
 		thinking: input.thinking,
 		systemPromptDigest: input.systemPrompt === undefined || input.systemPrompt === null ? undefined : stableJsonDigest(input.systemPrompt),
 		systemPromptMode: input.systemPromptMode,
@@ -117,6 +122,7 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
 		outputPath: input.outputPath,
 		outputMode: input.outputMode,
 		structuredOutputSchema: input.structuredOutputSchema,
+		extensionBindings: input.extensionBindings,
 	};
 }
 

package/src/shared/settings.ts

@@ -22,6 +22,7 @@ export interface ResolvedStepBehavior {
 	progress: boolean;
 	skills: string[] | false;
 	model?: string;
+	fast?: boolean;
 }
 
 export type OutputOverrideInput = string | boolean;
@@ -33,6 +34,7 @@ export interface StepOverrides {
 	progress?: boolean;
 	skills?: string[] | false;
 	model?: string;
+	fast?: boolean;
 }
 
 function normalizeOutputOverride(output: unknown): string | false | undefined {
@@ -60,6 +62,7 @@ export interface SequentialStep {
 	progress?: boolean;
 	skill?: string | string[] | false;
 	model?: string;
+	fast?: boolean;
 	toolBudget?: ToolBudgetConfig;
 	acceptance?: AcceptanceInput;
 	agentContract?: AgentContract;
@@ -84,6 +87,7 @@ export interface ParallelTaskItem {
 	progress?: boolean;
 	skill?: string | string[] | false;
 	model?: string;
+	fast?: boolean;
 	toolBudget?: ToolBudgetConfig;
 	acceptance?: AcceptanceInput;
 	agentContract?: AgentContract;
@@ -284,7 +288,8 @@ export function resolveStepBehavior(
 
 	const outputMode = stepOverrides.outputMode ?? agentConfig.outputMode ?? "inline";
 	const model = stepOverrides.model ?? agentConfig.model;
-	return { output, outputMode, reads, progress, skills, model };
+	const fast = stepOverrides.fast ?? agentConfig.fast;
+	return { output, outputMode, reads, progress, skills, model, fast };
 }
 
 export function resolveTaskTextForFileUpdatePolicy(task: string | undefined, originalTask?: string): string | undefined {

package/src/shared/types.ts

@@ -13,6 +13,7 @@ import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from
 import type { AuthorityPolicyConfig } from "../policy/authority.ts";
 import type { ThinkingLevel } from "./model-info.ts";
 import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
+import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
 
 // ============================================================================
 // Basic Types
@@ -348,12 +349,49 @@ export interface FileMutationEffect {
 	attempted: boolean;
 	message?: string;
 	resolvedBy?: "llm-intent-arbiter";
+	evidence?: TrackedMutationEvidence;
 }
 
 export interface EffectsProjection {
 	fileMutation?: FileMutationEffect;
 }
 
+export interface TrackedMutationSnapshot {
+	source: "tracked-files";
+	trackedOnly: true;
+	cwd: string;
+	gitRoot?: string;
+	dirtyFiles: string[];
+	fingerprints: Record<string, TrackedMutationFingerprint>;
+	truncated?: boolean;
+	unavailable?: string;
+}
+
+export type TrackedMutationFingerprint = { kind: "diff"; digest: string };
+
+export interface TrackedMutationEvidence {
+	source: "tracked-files";
+	trackedOnly: true;
+	changedFiles: string[];
+	attemptedMutation: boolean;
+	truncated?: boolean;
+	unavailable?: string;
+}
+
+export interface TimeoutRecoverySummary {
+	termination: "timed-out" | "stopped";
+	changedFiles: string[];
+	truncated?: boolean;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentPath?: string;
+	sessionFile?: string;
+	transcriptPath?: string;
+	artifactPaths?: ArtifactPaths;
+	warning: string;
+	message: string;
+}
+
 export const SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 3;
 export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFACT_VERSION;
 
@@ -526,6 +564,7 @@ export interface RunFanoutRejection extends RunFanoutBudgetSnapshot {
 export interface SteeringRecoveryDescriptor {
 	version: 1;
 	launchContractDigest?: string;
+	extensionBindings?: ExtensionBindings;
 	runFanoutBudget: RunFanoutBudgetDescriptor;
 	sourceRunId: string;
 	agentContract?: AgentContract;
@@ -536,6 +575,7 @@ export interface SteeringRecoveryDescriptor {
 	modelProvider?: string;
 	modelOverrideFromParent?: boolean;
 	fallbackModels?: string[];
+	fast?: boolean;
 	thinking?: string;
 	thinkingCeiling?: ThinkingLevel;
 	tools?: string[];
@@ -941,6 +981,7 @@ export interface SingleResult {
 	context?: "fresh" | "fork";
 	exitCode: number;
 	processSignal?: string | null;
+	timeoutRecovery?: TimeoutRecoverySummary;
 	detached?: boolean;
 	detachedReason?: string;
 	interrupted?: boolean;
@@ -1505,6 +1546,7 @@ export interface AsyncStatus {
 		durationMs?: number;
 		exitCode?: number | null;
 		timedOut?: boolean;
+		timeoutRecovery?: TimeoutRecoverySummary;
 		stopped?: boolean;
 		turnBudget?: TurnBudgetState;
 		turnBudgetExceeded?: boolean;
@@ -1644,6 +1686,8 @@ export interface ForegroundResumeChild {
 	acceptance?: AcceptanceLedger;
 	agentContract?: AgentContract;
 	launchContractDigest?: string;
+	/** Private retained launch authority. Never project into status or result output. */
+	extensionBindings?: ExtensionBindings;
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	execution?: ExecutionProjection;
@@ -1944,6 +1988,8 @@ export interface RunSyncOptions {
 	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
+	/** Opt into priority service tier for supported native OpenAI-Codex launches. */
+	fast?: boolean;
 	/** The override came from the running parent session, not configuration. */
 	modelOverrideFromParent?: boolean;
 	/** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
@@ -1951,6 +1997,7 @@ export interface RunSyncOptions {
 	/** Override the agent's default thinking level for this run */
 	thinkingOverride?: AgentConfig["thinking"];
 	thinkingCeiling?: ThinkingLevel;
+	extensionBindings?: ExtensionBindings;
 	/** Registry models available for heuristic bare-model resolution */
 	availableModels?: Array<{ provider: string; id: string; fullId: string }>;
 	/** Current parent-session provider to prefer for ambiguous bare model ids */
@@ -1963,6 +2010,7 @@ export interface RunSyncOptions {
 		schema: JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
+		acceptanceReportPath?: string;
 	};
 	agentContract?: AgentContract;
 	acceptance?: AcceptanceInput;