pi-improve-interation 0.0.1

package/node_modules/pi-subagents/src/shared/fork-context.ts

@@ -0,0 +1,293 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { findModelInfo, type ModelInfo } from "./model-info.ts";
+
+type SubagentExecutionContext = "fresh" | "fork";
+
+interface BranchSessionEntry {
+	type: string;
+	id?: string;
+	cwd?: string;
+	parentId?: string | null;
+	timestamp?: string;
+	message?: {
+		role?: string;
+		content?: unknown;
+		provider?: string;
+		api?: string;
+		model?: string;
+	};
+	thinkingLevel?: string;
+}
+
+interface BranchSessionManager {
+	createBranchedSession(leafId: string): string | undefined;
+	getHeader?: () => BranchSessionEntry | null;
+	getEntries?: () => BranchSessionEntry[];
+}
+
+interface ForkableSessionManager {
+	getSessionFile(): string | undefined;
+	getLeafId(): string | null;
+	getSessionDir?(): string;
+	openSession?: (path: string, sessionDir?: string) => BranchSessionManager;
+}
+
+interface ForkContextResolverOptions {
+	openSession?: (path: string, sessionDir?: string) => BranchSessionManager;
+	/** Rewrite a created fork before its path can be used to spawn a child. */
+	pruneSession?: (sessionFile: string) => Promise<void>;
+	/** Decide per child index whether a sanitized transcript must also disable the child's
+	 * thinking. Defaults to true (the pre-existing conservative behavior) when omitted. */
+	forceThinkingOffForIndex?: (index: number) => boolean;
+}
+
+interface ForkContextResolution {
+	sessionFile: string;
+	thinkingOverride?: "off";
+}
+
+interface ForkContextResolver {
+	prepareSessionForIndex(index?: number): Promise<void>;
+	sessionFileForIndex(index?: number): string | undefined;
+	thinkingOverrideForIndex(index?: number): "off" | undefined;
+}
+
+export function resolveSubagentContext(value: unknown): SubagentExecutionContext {
+	return value === "fork" ? "fork" : "fresh";
+}
+
+export interface PreferredForkAvailability {
+	getSessionFile(): string | undefined;
+	getLeafId?: () => string | null;
+}
+
+export interface PreferredForkSnapshot {
+	parentSessionFile?: string | null;
+	leafId?: string | null;
+}
+
+export interface SubagentLaunchContextInput {
+	explicitContext?: SubagentExecutionContext;
+	agentDefaultContext?: SubagentExecutionContext;
+	defaultSubagentContext?: SubagentExecutionContext;
+	canUseImplicitFork: boolean;
+}
+
+/** Resolve the actual launch context from explicit, global, and agent preferences. */
+export function resolveSubagentLaunchContext(input: SubagentLaunchContextInput): SubagentExecutionContext {
+	if (input.explicitContext !== undefined) return input.explicitContext;
+	const preferredContext = input.defaultSubagentContext ?? input.agentDefaultContext ?? "fresh";
+	return preferredContext === "fork" && input.canUseImplicitFork ? "fork" : "fresh";
+}
+
+/** True when an implicit `defaultContext: fork` can create a real branch now.
+ * Explicit `context: "fork"` stays strict and does not use this preference. */
+export function canPreferFork(sessionManager: PreferredForkAvailability): boolean {
+	return canPreferForkFromSnapshot({
+		parentSessionFile: sessionManager.getSessionFile(),
+		leafId: sessionManager.getLeafId?.() ?? null,
+	});
+}
+
+export function canPreferForkFromSnapshot(input: PreferredForkSnapshot): boolean {
+	if (!input.parentSessionFile || !input.leafId) return false;
+	try {
+		return fs.existsSync(input.parentSessionFile);
+	} catch {
+		return false;
+	}
+}
+
+/** Decide whether a resolved child model uses Anthropic's provider or message API, which
+ * requires the sanitized fork to disable thinking. Unknown models stay conservative. */
+export function forkedChildRequiresThinkingOff(
+	model: string | undefined,
+	availableModels?: ModelInfo[],
+	preferredProvider?: string,
+): boolean {
+	if (!model) return true;
+	const info = findModelInfo(model, availableModels, preferredProvider);
+	if (!info) return true;
+	return info.provider.toLowerCase() === "anthropic"
+		|| info.api?.toLowerCase() === "anthropic-messages";
+}
+
+function isUnsafeAnthropicThinkingBlock(message: BranchSessionEntry["message"], block: unknown): boolean {
+	if (!message || !block || typeof block !== "object" || !("type" in block)) return false;
+	const provider = typeof message.provider === "string" ? message.provider.toLowerCase() : "";
+	const api = typeof message.api === "string" ? message.api.toLowerCase() : "";
+	const model = typeof message.model === "string" ? message.model.toLowerCase() : "";
+	const isAnthropic = provider === "anthropic" || api === "anthropic-messages" || model.startsWith("anthropic/");
+	if (block.type === "redacted_thinking") return true;
+	if (block.type !== "thinking" || !isAnthropic) return false;
+	const record = block as Record<string, unknown>;
+	const signature = "thinkingSignature" in record ? record.thinkingSignature : "signature" in record ? record.signature : undefined;
+	return record.redacted === true || (typeof signature === "string" && signature.length > 0);
+}
+
+function createEntryId(entries: BranchSessionEntry[]): string {
+	const ids = new Set(entries.map((entry) => entry.id).filter((id): id is string => typeof id === "string"));
+	for (let attempt = 0; attempt < 100; attempt++) {
+		const id = randomUUID().slice(0, 8);
+		if (!ids.has(id)) return id;
+	}
+	return randomUUID();
+}
+
+function appendThinkingOffEntry(entries: BranchSessionEntry[]): void {
+	const last = entries[entries.length - 1];
+	if (last?.type === "thinking_level_change" && last.thinkingLevel === "off") return;
+	const parent = [...entries].reverse().find((entry) => typeof entry.id === "string");
+	entries.push({
+		type: "thinking_level_change",
+		id: createEntryId(entries),
+		parentId: parent?.id ?? null,
+		timestamp: new Date().toISOString(),
+		thinkingLevel: "off",
+	});
+}
+
+function sanitizeUnsafeThinkingBlocks(entries: BranchSessionEntry[]): boolean {
+	let sanitized = false;
+	for (const entry of entries) {
+		if (entry.type !== "message" || entry.message?.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
+		const filtered = entry.message.content.filter((block) => !isUnsafeAnthropicThinkingBlock(entry.message, block));
+		if (filtered.length === entry.message.content.length) continue;
+		entry.message.content = filtered;
+		sanitized = true;
+	}
+	return sanitized;
+}
+
+function readSessionEntries(sessionFile: string): BranchSessionEntry[] {
+	const lines = fs.readFileSync(sessionFile, "utf-8").split("\n").filter((line) => line.trim().length > 0);
+	return lines.map((line, index) => {
+		try {
+			return JSON.parse(line) as BranchSessionEntry;
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			throw new Error(`Unable to inspect forked session ${sessionFile}: invalid JSONL on line ${index + 1}: ${cause.message}`, { cause });
+		}
+	});
+}
+
+export function createForkContextResolver(
+	sessionManager: ForkableSessionManager,
+	requestedContext: unknown,
+	options: ForkContextResolverOptions = {},
+): ForkContextResolver {
+	if (resolveSubagentContext(requestedContext) !== "fork") {
+		return {
+			prepareSessionForIndex: async () => {},
+			sessionFileForIndex: () => undefined,
+			thinkingOverrideForIndex: () => undefined,
+		};
+	}
+
+	const parentSessionFile = sessionManager.getSessionFile();
+	if (!parentSessionFile) {
+		throw new Error("Forked subagent context requires a persisted parent session.");
+	}
+
+	const leafId = sessionManager.getLeafId();
+	if (!leafId) {
+		throw new Error("Forked subagent context requires a current leaf to fork from.");
+	}
+
+	const openSession = options.openSession
+		?? sessionManager.openSession
+		?? ((file: string, dir?: string) => SessionManager.open(file, dir));
+	// Fork files must not land in the parent's top-level session directory.
+	// Pi's recent-session discovery (`pi -c` → findMostRecentSession) is
+	// non-recursive and picks the largest-mtime *.jsonl in that directory, so
+	// a still-running forked subagent — which keeps appending after the parent
+	// went idle — would hijack the next `pi -c` away from the conversation the
+	// user actually left. Nesting fork sessions in a per-parent directory keeps
+	// them invisible to that discovery; the `parentSession` header still
+	// records the tree relationship. The directory mirrors
+	// getSubagentSessionRoot() plus a "forks" level so fork files never sit
+	// loose next to run-N/ result directories. Derived from the file path
+	// rather than getSessionDir() so it also works when the manager cannot
+	// report its directory.
+	const sessionDir = path.join(
+		path.dirname(parentSessionFile),
+		path.basename(parentSessionFile, ".jsonl"),
+		"forks",
+	);
+	const cachedResolutions = new Map<number, ForkContextResolution>();
+	const preparedIndexes = new Set<number>();
+	const preparationPromises = new Map<number, Promise<void>>();
+
+	const resolveFork = (index = 0): ForkContextResolution => {
+		const cached = cachedResolutions.get(index);
+		if (cached) return cached;
+		try {
+			if (!fs.existsSync(parentSessionFile)) {
+				throw new Error(`Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`);
+			}
+			const sourceManager = openSession(parentSessionFile, sessionDir);
+			const sessionFile = sourceManager.createBranchedSession(leafId);
+			if (!sessionFile) {
+				throw new Error("Session manager did not return a forked session file.");
+			}
+			const forceThinkingOff = (sanitized: boolean): boolean =>
+				sanitized && (options.forceThinkingOffForIndex?.(index) ?? true);
+			let thinkingOverride: "off" | undefined;
+			if (!fs.existsSync(sessionFile)) {
+				const header = sourceManager.getHeader?.();
+				const entries = sourceManager.getEntries?.();
+				if (!header || !entries) {
+					throw new Error(`Session manager returned a forked session file that does not exist and cannot be persisted by fallback: ${sessionFile}`);
+				}
+				if (forceThinkingOff(sanitizeUnsafeThinkingBlocks(entries))) {
+					appendThinkingOffEntry(entries);
+					thinkingOverride = "off";
+				}
+				fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
+				fs.writeFileSync(sessionFile, `${[header, ...entries].map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
+			} else {
+				const entries = readSessionEntries(sessionFile);
+				if (sanitizeUnsafeThinkingBlocks(entries)) {
+					if (forceThinkingOff(true)) {
+						appendThinkingOffEntry(entries);
+						thinkingOverride = "off";
+					}
+					fs.writeFileSync(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
+				}
+			}
+			const resolution = { sessionFile, ...(thinkingOverride ? { thinkingOverride } : {}) };
+			cachedResolutions.set(index, resolution);
+			return resolution;
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
+		}
+	};
+
+	return {
+		async prepareSessionForIndex(index = 0): Promise<void> {
+			const resolution = resolveFork(index);
+			if (!options.pruneSession || preparedIndexes.has(index)) return;
+			let preparation = preparationPromises.get(index);
+			if (!preparation) {
+				preparation = options.pruneSession(resolution.sessionFile).then(() => {
+					preparedIndexes.add(index);
+				});
+				preparationPromises.set(index, preparation);
+			}
+			await preparation;
+		},
+		sessionFileForIndex(index = 0): string | undefined {
+			if (options.pruneSession && !preparedIndexes.has(index)) {
+				throw new Error(`Pruned fork session ${index} was used before pruning completed.`);
+			}
+			return resolveFork(index).sessionFile;
+		},
+		thinkingOverrideForIndex(index = 0): "off" | undefined {
+			return resolveFork(index).thinkingOverride;
+		},
+	};
+}

package/node_modules/pi-subagents/src/shared/fork-session-cwd.ts

@@ -0,0 +1,27 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface SessionEntry {
+	type?: string;
+	cwd?: string;
+	[key: string]: unknown;
+}
+
+/** Keep Pi from restoring a forked session into the parent's cwd instead of the child launch cwd. */
+export function alignForkedSessionCwd(sessionFile: string, cwd: string): void {
+	const lines = fs.readFileSync(sessionFile, "utf-8").split("\n").filter((line) => line.trim().length > 0);
+	const entries = lines.map((line, index) => {
+		try {
+			return JSON.parse(line) as SessionEntry;
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			throw new Error(`Unable to inspect forked session ${sessionFile}: invalid JSONL on line ${index + 1}: ${cause.message}`, { cause });
+		}
+	});
+	const header = entries[0];
+	if (header?.type !== "session") throw new Error(`Forked session ${sessionFile} does not start with a session header.`);
+	const effectiveCwd = fs.realpathSync.native(path.resolve(cwd));
+	if (header.cwd === effectiveCwd) return;
+	header.cwd = effectiveCwd;
+	fs.writeFileSync(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
+}

package/node_modules/pi-subagents/src/shared/formatters.ts

@@ -0,0 +1,146 @@
+/**
+ * Formatting utilities for display output
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Usage, SingleResult, TokenUsage } from "./types.ts";
+import type { ChainStep } from "./settings.ts";
+import { isDynamicParallelStep, isParallelStep } from "./settings.ts";
+import { previewDisplayText, sanitizeDisplayText } from "./display-text.ts";
+import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
+
+/**
+ * Format token count for compact display.
+ */
+export function formatTokens(n: number): string {
+	if (n < 1000) return String(n);
+	if (n < 10000) return `${(n / 1000).toFixed(1)}k`;
+	if (n < 999_500) return `${Math.round(n / 1000)}k`;
+	return `${Number((n / 1_000_000).toFixed(1))}M`;
+}
+
+export function formatTokenUsage(usage: TokenUsage, legacyLabel = "tok"): string {
+	return usage.window !== undefined
+		? `${formatTokens(usage.window)} window · ${formatTokens(usage.total)} spent`
+		: `${formatTokens(usage.total)} ${legacyLabel}`;
+}
+export function formatContextUsage(usage: Pick<TokenUsage, "window" | "windowPeak">, contextLimit: number): string | undefined {
+	if (usage.window === undefined || !Number.isFinite(usage.window) || !Number.isFinite(contextLimit) || contextLimit <= 0) return undefined;
+	const peak = usage.windowPeak !== undefined && Number.isFinite(usage.windowPeak) ? usage.windowPeak : usage.window;
+	const used = Math.max(0, usage.window, peak);
+	return `ctx ${formatTokens(used)}/${formatTokens(contextLimit)} (${Math.round((used / contextLimit) * 100)}%)`;
+}
+
+export function formatModelThinking(model?: string, thinking?: string): string {
+	const parsed = model ? splitKnownThinkingSuffix(model) : undefined;
+	let displayModel = parsed?.baseModel ?? model;
+	const explicitThinking = THINKING_LEVELS.find((level) => level === thinking?.trim());
+	const displayThinking = parsed?.thinkingSuffix ? parsed.thinkingSuffix.slice(1) : explicitThinking;
+	if (displayModel) {
+		const slashIdx = displayModel.lastIndexOf("/");
+		if (slashIdx !== -1) displayModel = displayModel.slice(slashIdx + 1);
+	}
+	return [displayModel, displayThinking ? `thinking ${displayThinking}` : undefined].filter(Boolean).join(" · ");
+}
+
+/**
+ * Format usage statistics into a compact string
+ */
+export function formatUsage(u: Usage, model?: string): string {
+	const parts: string[] = [];
+	if (u.turns) parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
+	if (u.input) parts.push(`in:${formatTokens(u.input)}`);
+	if (u.output) parts.push(`out:${formatTokens(u.output)}`);
+	if (u.cacheRead) parts.push(`R${formatTokens(u.cacheRead)}`);
+	if (u.cacheWrite) parts.push(`W${formatTokens(u.cacheWrite)}`);
+	if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+/**
+ * Format duration in human-readable form
+ */
+export function formatDuration(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+	return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
+}
+
+/**
+ * Build a summary string for a completed/failed chain
+ */
+export function buildChainSummary(
+	steps: ChainStep[],
+	results: SingleResult[],
+	chainDir: string,
+	status: "completed" | "failed",
+	failedStep?: { index: number; error: string },
+): string {
+	const stepNames = steps
+		.map((step) => (isParallelStep(step) ? `parallel[${step.parallel.length}]` : isDynamicParallelStep(step) ? `expand:${step.parallel.agent}` : step.agent))
+		.join(" → ");
+
+	const totalDuration = results.reduce((sum, r) => sum + (r.progress?.durationMs || 0), 0);
+	const durationStr = formatDuration(totalDuration);
+
+	const progressPath = path.join(chainDir, "progress.md");
+	const hasProgress = fs.existsSync(progressPath);
+	const allSkills = new Set<string>();
+	for (const r of results) {
+		if (r.skills) r.skills.forEach((s) => allSkills.add(s));
+	}
+	const skillsLine = allSkills.size > 0 ? `🔧 Skills: ${[...allSkills].join(", ")}` : "";
+
+	if (status === "completed") {
+		const stepWord = results.length === 1 ? "step" : "steps";
+		return `✅ Chain completed: ${stepNames} (${results.length} ${stepWord}, ${durationStr})${skillsLine ? `\n${skillsLine}` : ""}
+
+📋 Progress: ${hasProgress ? progressPath : "(none)"}
+📁 Artifacts: ${chainDir}`;
+	} else {
+		const stepInfo = failedStep ? ` at step ${failedStep.index + 1}` : "";
+		const errorInfo = failedStep?.error ? `: ${failedStep.error}` : "";
+		return `❌ Chain failed${stepInfo}${errorInfo}${skillsLine ? `\n${skillsLine}` : ""}
+
+📋 Progress: ${hasProgress ? progressPath : "(none)"}
+📁 Artifacts: ${chainDir}`;
+	}
+}
+
+/**
+ * Format a tool call for display
+ */
+export function formatToolCall(name: string, args: Record<string, unknown>, expanded = false): string {
+	switch (name) {
+		case "bash": {
+			const command = typeof args.command === "string" ? args.command : "";
+			return `$ ${previewDisplayText(command, expanded ? 240 : 60)}`;
+		}
+		case "read":
+		case "write":
+		case "edit": {
+			const target = typeof args.path === "string"
+				? args.path
+				: typeof args.file_path === "string"
+					? args.file_path
+					: "";
+			return `${name} ${sanitizeDisplayText(shortenPath(target))}`;
+		}
+		default: {
+			return `${name} ${previewDisplayText(JSON.stringify(args), expanded ? 160 : 40)}`;
+		}
+	}
+}
+
+/**
+ * Shorten a path by replacing home directory with ~
+ */
+export function shortenPath(p: string): string {
+	const home = process.env.HOME;
+	if (home && p.startsWith(home)) {
+		return `~${p.slice(home.length)}`;
+	}
+	return p;
+}

package/node_modules/pi-subagents/src/shared/jsonl-writer.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+
+export interface DrainableSource {
+	pause(): void;
+	resume(): void;
+}
+
+export interface JsonlWriteStream {
+	write(chunk: string): boolean;
+	once(event: "drain", listener: () => void): JsonlWriteStream;
+	end(callback?: () => void): void;
+}
+
+const DEFAULT_MAX_JSONL_BYTES = 50 * 1024 * 1024;
+
+interface JsonlWriterDeps {
+	createWriteStream?: (filePath: string) => JsonlWriteStream;
+	maxBytes?: number;
+}
+
+interface JsonlWriter {
+	writeLine(line: string): void;
+	close(): Promise<void>;
+}
+
+export function createJsonlWriter(
+	filePath: string | undefined,
+	source: DrainableSource,
+	deps: JsonlWriterDeps = {},
+): JsonlWriter {
+	if (!filePath) {
+		return {
+			writeLine() {},
+			async close() {},
+		};
+	}
+
+	const createWriteStream = deps.createWriteStream ?? ((targetPath: string) => fs.createWriteStream(targetPath, { flags: "a" }));
+	let stream: JsonlWriteStream | undefined;
+	try {
+		stream = createWriteStream(filePath);
+	} catch {
+		return {
+			writeLine() {},
+			async close() {},
+		};
+	}
+
+	let backpressured = false;
+	let closed = false;
+	let bytesWritten = 0;
+	const maxBytes = deps.maxBytes ?? DEFAULT_MAX_JSONL_BYTES;
+
+	return {
+		writeLine(line: string) {
+			if (!stream || closed || !line.trim()) return;
+			const chunk = `${line}\n`;
+			const chunkBytes = Buffer.byteLength(chunk, "utf-8");
+			if (bytesWritten + chunkBytes > maxBytes) return;
+			try {
+				const ok = stream.write(chunk);
+				bytesWritten += chunkBytes;
+				if (!ok && !backpressured) {
+					backpressured = true;
+					source.pause();
+					stream.once("drain", () => {
+						backpressured = false;
+						if (!closed) source.resume();
+					});
+				}
+			} catch {}
+		},
+		async close() {
+			if (!stream || closed) return;
+			closed = true;
+			const current = stream;
+			stream = undefined;
+			await new Promise<void>((resolve) => current.end(() => resolve()));
+		},
+	};
+}

package/node_modules/pi-subagents/src/shared/launch-contract.ts

@@ -0,0 +1,138 @@
+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;
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		return `{${Object.entries(value as Record<string, unknown>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+
+export function stableJsonDigest(value: unknown): string {
+	return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function fileDigest(filePath: string): string | undefined {
+	try {
+		return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Public-safe, deterministic evidence for the parsed launch-affecting agent definition. */
+export function projectAgentDefinition(agent: AgentConfig): Record<string, unknown> {
+	return {
+		version: AGENT_DEFINITION_PROJECTION_VERSION,
+		name: agent.name,
+		localName: agent.localName,
+		packageName: agent.packageName,
+		filePath: agent.filePath,
+		fileContentDigest: fileDigest(agent.filePath),
+		runner: agent.runner,
+		systemPrompt: agent.systemPrompt,
+		systemPromptMode: agent.systemPromptMode,
+		inheritProjectContext: agent.inheritProjectContext,
+		inheritGlobalContext: agent.inheritGlobalContext,
+		inheritSkills: agent.inheritSkills,
+		model: agent.model,
+		modelProvider: agent.modelProvider,
+		fallbackModels: agent.fallbackModels,
+		fast: agent.fast,
+		thinking: agent.thinking,
+		tools: agent.tools,
+		excludeTools: agent.excludeTools,
+		allowNestedSubagents: agent.allowNestedSubagents,
+		mcpDirectTools: agent.mcpDirectTools,
+		extensions: agent.extensions,
+		subagentOnlyExtensions: agent.subagentOnlyExtensions,
+		mutationTools: agent.mutationTools,
+		skills: agent.skills,
+		skillPath: agent.skillPath,
+		output: agent.output,
+		defaultReads: agent.defaultReads,
+		defaultProgress: agent.defaultProgress,
+		defaultContext: agent.defaultContext,
+		defaultAsync: agent.defaultAsync,
+		defaultTimeoutMs: agent.defaultTimeoutMs,
+		defaultAcceptance: agent.defaultAcceptance,
+		acceptanceRole: agent.acceptanceRole,
+		interactive: agent.interactive,
+		maxSubagentDepth: agent.maxSubagentDepth,
+		completionGuard: agent.completionGuard,
+		toolBudget: agent.toolBudget,
+		memory: agent.memory,
+	};
+}
+
+export function agentDefinitionDigest(agent: AgentConfig): string {
+	return stableJsonDigest(projectAgentDefinition(agent));
+}
+
+export interface LaunchBindingInput {
+	definitionDigest: string;
+	/** Caller task; runtime acceptance/output task annotations are explicitly outside the preflight-known subset. */
+	task?: string;
+	model?: string;
+	modelCandidates?: string[];
+	fast?: boolean;
+	thinking?: string;
+	systemPrompt?: string | null;
+	systemPromptMode?: AgentConfig["systemPromptMode"];
+	inheritProjectContext: boolean;
+	inheritGlobalContext: boolean;
+	inheritSkills: boolean;
+	skills?: string[];
+	tools?: string[];
+	excludeTools?: string[];
+	extensions?: string[];
+	subagentOnlyExtensions?: string[];
+	mcpDirectTools?: string[];
+	outputPath?: string;
+	outputMode?: string;
+	structuredOutputSchema?: unknown;
+	extensionBindings?: ExtensionBindings;
+}
+
+/** Canonical projection of the resolved inputs handed to the child. */
+export function projectLaunchBinding(input: LaunchBindingInput): Record<string, unknown> {
+	return {
+		version: LAUNCH_BINDING_PROJECTION_VERSION,
+		definitionDigest: input.definitionDigest,
+		taskDigest: input.task === undefined ? undefined : stableJsonDigest(input.task),
+		// 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,
+		inheritProjectContext: input.inheritProjectContext,
+		inheritGlobalContext: input.inheritGlobalContext,
+		inheritSkills: input.inheritSkills,
+		skills: input.skills,
+		tools: input.tools,
+		excludeTools: input.excludeTools,
+		extensions: input.extensions,
+		subagentOnlyExtensions: input.subagentOnlyExtensions,
+		mcpDirectTools: input.mcpDirectTools,
+		outputPath: input.outputPath,
+		outputMode: input.outputMode,
+		structuredOutputSchema: input.structuredOutputSchema,
+		extensionBindings: input.extensionBindings,
+	};
+}
+
+export function launchBindingDigest(input: LaunchBindingInput): string {
+	return stableJsonDigest(projectLaunchBinding(input));
+}