pi-subagents 0.66.0 → 0.68.0

package/src/runs/shared/worktree-setup-command.ts

@@ -2,6 +2,26 @@ import { spawn } from "node:child_process";
 import { createOwnedProcessTreeController } from "../background/owned-process-tree.ts";
 import type { ProcessTreeTerminal } from "../../shared/types.ts";
 
+function terminateCommandTree(pid: number, controller: ReturnType<typeof createOwnedProcessTreeController>): Promise<ProcessTreeTerminal> {
+	if (process.platform !== "win32") return controller.terminate();
+	return new Promise((resolve) => {
+		let settled = false;
+		const fallback = () => {
+			if (settled) return;
+			settled = true;
+			void controller.terminate().then(resolve);
+		};
+		const cleanup = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+		cleanup.once("error", fallback);
+		cleanup.once("close", (status) => {
+			if (settled) return;
+			if (status !== 0) return fallback();
+			settled = true;
+			resolve({ state: "observed", mechanism: "windows-taskkill", pid, verifiedAt: Date.now() });
+		});
+	});
+}
+
 export interface SetupCommandOptions {
 	cwd?: string;
 	env?: NodeJS.ProcessEnv;
@@ -19,6 +39,7 @@ export interface SetupCommandOptions {
 
 export interface SetupCommandResult {
 	stdout: string;
+	stdoutBuffer: Buffer;
 	stderr: string;
 	status: number | null;
 	signal: NodeJS.Signals | null;
@@ -46,7 +67,7 @@ export async function runSetupCommand(
 	options: SetupCommandOptions,
 ): Promise<SetupCommandResult> {
 	const result: SetupCommandResult = {
-		stdout: "", stderr: "", status: null, signal: null, outputIncomplete: false,
+		stdout: "", stdoutBuffer: Buffer.alloc(0), stderr: "", status: null, signal: null, outputIncomplete: false,
 	};
 	const maxBuffer = options.maxBuffer ?? 1024 * 1024;
 	if (!Number.isSafeInteger(maxBuffer) || maxBuffer <= 0) throw new Error("Invalid setup command maxBuffer");
@@ -84,7 +105,8 @@ export async function runSetupCommand(
 	let directSettled = false;
 	const releaseUnknownIO = () => {
 		if (!directSettled || result.processTree?.state !== "unknown") return;
-		result.error ??= commandError("Worktree setup process tree settlement is unverified", "PROCESS_TREE_UNVERIFIED");
+		const detail = result.processTree.diagnostic ? `: ${result.processTree.diagnostic}` : "";
+		result.error = commandError(`Worktree setup process tree settlement is unverified${detail}`, "PROCESS_TREE_UNVERIFIED");
 		result.outputIncomplete = true;
 		// Only local I/O is released; unknown descendant ownership remains retained.
 		child.stdin.destroy();
@@ -101,7 +123,7 @@ export async function runSetupCommand(
 			releaseUnknownIO();
 			return;
 		}
-		termination = tree.terminate().then((proof) => {
+		termination = terminateCommandTree(result.pid!, tree).then((proof) => {
 			result.processTree = proof;
 			releaseUnknownIO();
 			return proof;
@@ -177,7 +199,8 @@ export async function runSetupCommand(
 		if (termination) result.processTree = await termination;
 		const cancelled = cancellation();
 		if (cancelled) fail(cancelled);
-		result.stdout = Buffer.concat(stdout).toString("utf8");
+		result.stdoutBuffer = Buffer.concat(stdout);
+		result.stdout = result.stdoutBuffer.toString("utf8");
 		result.stderr = Buffer.concat(stderr).toString("utf8");
 		return result;
 	} finally {

package/src/runs/shared/worktree.ts

@@ -18,6 +18,8 @@ const WORKTREE_NAMING_COMPONENT_MAX_BYTES = 96;
 const WORKTREE_NAMING_LABEL_MAX_BYTES = 256;
 const WORKTREE_NAMING_BRANCH_MAX_BYTES = 256;
 const WORKTREE_COMMAND_OUTPUT_MAX_BYTES = 128 * 1024;
+const WORKTRUNK_COMMAND = process.platform === "win32" ? "git" : "wt";
+const WORKTRUNK_ARG_PREFIX = process.platform === "win32" ? ["wt"] : [];
 export const MACHINE_DIFF_OPTIONS = ["--no-color", "--no-ext-diff", "--no-textconv", "--default-prefix", "--line-prefix=", "--no-relative"] as const;
 const MACHINE_PATCH_OPTIONS = [...MACHINE_DIFF_OPTIONS, "--binary"] as const;
 const PATCH_VALIDATION_OPTIONS = ["apply", "--check", "--cached", "--reverse", "--binary", "--whitespace=nowarn"] as const;
@@ -178,7 +180,7 @@ export interface WorktreeSetupProgress {
 	setup: WorktreeSetup;
 	attempts: Array<{ index: number; branch: string; path?: string; validated: boolean; command?: WorktreeSetupProgress["command"]; hookCommand?: WorktreeSetupProgress["command"] }>;
 	phase: string;
-	command?: { command: string; args: string[]; pid?: number; processGroupId?: number; result?: Omit<SetupCommandResult, "stdout" | "stderr"> };
+	command?: { command: string; args: string[]; pid?: number; processGroupId?: number; result?: Omit<SetupCommandResult, "stdout" | "stdoutBuffer" | "stderr"> };
 	unknown?: string;
 	cleanup?: WorktreeCleanupReport;
 }
@@ -243,7 +245,7 @@ class SetupTransaction {
 			...options, signal: this.options.signal, deadlineAt: this.options.deadlineAt,
 			onSpawn: (process) => { Object.assign(this.progress.command!, process); this.publish(); },
 		});
-		const { stdout: _stdout, stderr: _stderr, ...metadata } = result;
+		const { stdout: _stdout, stdoutBuffer: _stdoutBuffer, stderr: _stderr, ...metadata } = result;
 		this.progress.command.result = metadata;
 		if (result.processTree?.state === "unknown") this.unknown(result.error ?? "Command tree settlement unverified");
 		this.publish();
@@ -339,11 +341,9 @@ export function validateWorktreePatchRepresentsCurrentWorktree(worktreePath: str
 	return undefined;
 }
 
-async function resolveRepoState(tx: SetupTransaction, cwd: string, requestedBaseRef: string | undefined): Promise<RepoState> {
+async function probeWorktreeSource(tx: Pick<SetupTransaction, "git" | "gitChecked">, cwd: string): Promise<string> {
 	const repoCheck = await tx.git(cwd, ["rev-parse", "--is-inside-work-tree"], [0, 128]);
 	if (repoCheck.status !== 0 || repoCheck.stdout.trim() !== "true") throw new Error("worktree isolation requires a git repository");
-	const rawPrefix = (await tx.gitChecked(cwd, ["rev-parse", "--show-prefix"])).trim();
-	const cwdRelative = rawPrefix ? path.normalize(rawPrefix.replace(/[\\/]+$/, "")) : "";
 	const toplevel = (await tx.gitChecked(cwd, ["rev-parse", "--show-toplevel"])).trim();
 
 	// pi-subagents writes durable runtime state under .pi/subagents/ by default;
@@ -352,6 +352,26 @@ async function resolveRepoState(tx: SetupTransaction, cwd: string, requestedBase
 	if (status.trim().length > 0) {
 		throw new Error("worktree isolation requires a clean git working tree. Commit or stash changes first.");
 	}
+	return toplevel;
+}
+
+/** Read-only admission check; allocation repeats it because source state can change. */
+export async function preflightWorktreeSource(cwd: string, options: Pick<SetupCommandOptions, "signal" | "deadlineAt"> = {}): Promise<void> {
+	const git = async (cwd: string, args: string[], acceptedExitCodes: readonly number[] = [0]): Promise<SetupCommandResult> => {
+		const result = await runSetupCommand("git", ["-C", cwd, ...args], { ...options, acceptedExitCodes });
+		if (result.error) throw result.error;
+		if (result.outputIncomplete || result.status === null || !acceptedExitCodes.includes(result.status)) {
+			throw new Error(result.stderr.trim().slice(0, 2000) || "Worktree source probe failed");
+		}
+		return result;
+	};
+	await probeWorktreeSource({ git, gitChecked: async (cwd, args) => (await git(cwd, args)).stdout }, cwd);
+}
+
+async function resolveRepoState(tx: SetupTransaction, cwd: string, requestedBaseRef: string | undefined): Promise<RepoState> {
+	const toplevel = await probeWorktreeSource(tx, cwd);
+	const rawPrefix = (await tx.gitChecked(cwd, ["rev-parse", "--show-prefix"])).trim();
+	const cwdRelative = rawPrefix ? path.normalize(rawPrefix.replace(/[\\/]+$/, "")) : "";
 
 	const baseRef = normalizeWorktreeBaseRef(requestedBaseRef) ?? DEFAULT_WORKTREE_BASE_REF;
 	let baseCommit: string;
@@ -526,6 +546,11 @@ function hasConfiguredWorktreeBaseDir(baseDir: string | undefined): boolean {
 		: (process.env.PI_SUBAGENTS_WORKTREE_DIR?.trim().length ?? 0) > 0;
 }
 
+function isInsidePiExtensionsDirectory(targetPath: string): boolean {
+	const extensionsDir = normalizeComparableCwd(path.join(getAgentDir(), "extensions"));
+	return isPathInside(extensionsDir, normalizeComparableCwd(targetPath));
+}
+
 interface WorktrunkCapability {
 	available: boolean;
 	reason?: string;
@@ -533,7 +558,7 @@ interface WorktrunkCapability {
 
 function runWorktrunk(args: string[], cwd?: string): WorktreeCommandResult {
 	try {
-		const result = spawnSync("wt", args, {
+		const result = spawnSync(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, ...args], {
 			cwd,
 			encoding: "utf-8",
 			windowsHide: true,
@@ -578,7 +603,7 @@ export function resolveWorktreeProvider(requested: WorktreeProvider | undefined,
 	return "native";
 }
 
-async function resolveSetupProvider(tx: SetupTransaction, requested: WorktreeProvider | undefined, baseDir?: string): Promise<ManagedWorktreeProvider> {
+async function resolveSetupProvider(tx: SetupTransaction, requested: WorktreeProvider | undefined, baseDir: string | undefined, repoRoot: string): Promise<ManagedWorktreeProvider> {
 	const selection = requested ?? DEFAULT_WORKTREE_PROVIDER;
 	if (selection !== "auto" && selection !== "native" && selection !== "worktrunk") throw new Error('worktree provider must be "auto", "native", or "worktrunk"');
 	if (selection === "native") return "native";
@@ -586,13 +611,14 @@ async function resolveSetupProvider(tx: SetupTransaction, requested: WorktreePro
 		if (selection === "worktrunk") throw new Error("worktreeProvider='worktrunk' cannot be combined with worktreeBaseDir or PI_SUBAGENTS_WORKTREE_DIR");
 		return "native";
 	}
+	if (selection === "auto" && isInsidePiExtensionsDirectory(repoRoot)) return "native";
 	let reason: string | undefined;
 	try {
 		const probeExitCodes = Array.from({ length: 256 }, (_, code) => code);
-		const version = await tx.command("wt", ["--version"], { maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES, acceptedExitCodes: probeExitCodes });
+		const version = await tx.command(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, "--version"], { maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES, acceptedExitCodes: probeExitCodes });
 		if (version.status !== 0 || !/\b(?:wt\s+)?v?(\d+\.\d+(?:\.\d+)?)\b/i.test(version.stdout.trim())) reason = "Worktrunk is unavailable or returned an invalid version";
 		else {
-			const help = await tx.command("wt", ["switch", "--help"], { maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES, acceptedExitCodes: probeExitCodes });
+			const help = await tx.command(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, "switch", "--help"], { maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES, acceptedExitCodes: probeExitCodes });
 			const missing = ["--create", "--base", "--no-cd", "--no-hooks", "--format"].filter((flag) => !`${help.stdout}\n${help.stderr}`.includes(flag));
 			if (help.status !== 0 || missing.length) reason = `Worktrunk switch capability unavailable: ${missing.join(", ")}`;
 		}
@@ -616,11 +642,13 @@ export function shouldDeferWorktreeCwd(requested: WorktreeProvider | undefined,
  * to the repository. Managed leaves always nest one level deeper under the
  * project folder (`basename(repoRoot)`).
  */
-function resolveWorktreeDedicatedRoot(configuredBaseDir: string | undefined, repoRoot: string): string {
+function resolveWorktreeDedicatedRoot(configuredBaseDir: string | undefined, repoRoot: string, relocateExtensionRepo = true): string {
 	const rawBaseDir = configuredBaseDir ?? process.env.PI_SUBAGENTS_WORKTREE_DIR;
 	let expanded: string;
 	if (rawBaseDir === undefined || (configuredBaseDir === undefined && !rawBaseDir.trim())) {
-		expanded = path.join(path.dirname(repoRoot), "worktrees");
+		expanded = relocateExtensionRepo && isInsidePiExtensionsDirectory(repoRoot)
+			? path.join(getAgentDir(), "worktrees")
+			: path.join(path.dirname(repoRoot), "worktrees");
 	} else {
 		const trimmed = rawBaseDir.trim();
 		if (!trimmed) throw new Error("worktree base directory cannot be empty");
@@ -942,7 +970,7 @@ async function createWorktrunkWorktree(
 	const naming = buildWorktreeNaming({ runId, index, agent: agents?.[index], label: labels?.[index], task: tasks?.[index], branchPrefix });
 	const args = ["-C", toplevel, "switch", "--create", naming.requestedBranch, "--base", baseCommit, "--no-cd", "--no-hooks", "--format", "json"];
 	tx.attempt(index, naming.requestedBranch);
-	const result = await tx.command("wt", args, { cwd: toplevel, maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES });
+	const result = await tx.command(WORKTRUNK_COMMAND, [...WORKTRUNK_ARG_PREFIX, ...args], { cwd: toplevel, maxBuffer: WORKTREE_COMMAND_OUTPUT_MAX_BYTES });
 	tx.progress.phase = "validation";
 	try {
 		const output = parseWorktrunkSwitchOutput(result.stdout);
@@ -1267,7 +1295,7 @@ async function compensateSetup(tx: SetupTransaction): Promise<WorktreeCleanupRep
 			deadlineAt: tx.options.deadlineAt, acceptedExitCodes,
 			onSpawn: (process) => { Object.assign(tx.progress.command!, process); tx.publish(); },
 		});
-		const { stdout: _stdout, stderr: _stderr, ...metadata } = result;
+		const { stdout: _stdout, stdoutBuffer: _stdoutBuffer, stderr: _stderr, ...metadata } = result;
 		tx.progress.command.result = metadata;
 		if (result.processTree?.state === "unknown") tx.unknown(result.error ?? "Rollback command settlement unverified");
 		tx.publish();
@@ -1331,9 +1359,11 @@ async function allocateWorktrees(tx: SetupTransaction, cwd: string, runId: strin
 	tx.progress.setup.cwd = repo.toplevel;
 	tx.progress.setup.baseCommit = repo.baseCommit;
 	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
-	const provider = await resolveSetupProvider(tx, options?.provider, options?.baseDir);
+	const provider = await resolveSetupProvider(tx, options?.provider, options?.baseDir, repo.toplevel);
 	const branchPrefix = normalizeWorktreeBranchPrefix(options?.branchPrefix);
-	const dedicatedRoot = provider === "native" ? resolveWorktreeDedicatedRoot(options?.baseDir, repo.toplevel) : undefined;
+	const dedicatedRoot = provider === "native"
+		? resolveWorktreeDedicatedRoot(options?.baseDir, repo.toplevel, (options?.provider ?? DEFAULT_WORKTREE_PROVIDER) === "auto")
+		: undefined;
 	const worktrees = tx.progress.setup.worktrees;
 
 	try {

package/src/shared/child-cache-retention.ts

@@ -0,0 +1,43 @@
+import type { StreamFn } from "@earendil-works/pi-agent-core";
+
+/**
+ * Anthropic prices a cache write by the TTL it is asked for: 1.25x base input
+ * for the 5m window, 2x for the 1h one. Child sessions are short-lived and
+ * rarely idle, so a 1h window they never claim is a flat surcharge on every
+ * write. Setting this to `short` keeps that surcharge off children while the
+ * parent keeps `long`, the same split Claude Code makes between its main
+ * conversation and its subagents.
+ *
+ * Unset means children inherit the parent's retention, which is the behaviour
+ * before this setting existed.
+ */
+export function childCacheRetention(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	return env.PI_SUBAGENT_CACHE_RETENTION || undefined;
+}
+
+/**
+ * Launch-environment form for spawned children. Empty when unset, so the child
+ * inherits the parent's `PI_CACHE_RETENTION` rather than having it cleared.
+ */
+export function childCacheRetentionEnv(env?: NodeJS.ProcessEnv): { PI_CACHE_RETENTION?: string } {
+	const retention = childCacheRetention(env);
+	return retention ? { PI_CACHE_RETENTION: retention } : {};
+}
+
+/**
+ * Pi resolves retention per request as `options.env?.[name] || process.env[name]`,
+ * so a per-call env beats the process-wide one. Wrapping the session's own
+ * stream function keeps this scoped to one child, with no shared-state race
+ * against a parent turn streaming concurrently.
+ */
+export function pinChildCacheRetention(agent: { streamFunction: StreamFn } | undefined, env?: NodeJS.ProcessEnv): void {
+	if (!agent?.streamFunction) return;
+	const retention = childCacheRetention(env);
+	if (!retention) return;
+	const base = agent.streamFunction;
+	agent.streamFunction = (model, context, options) =>
+		base(model, context, {
+			...options,
+			env: { ...(options?.env ?? {}), PI_CACHE_RETENTION: retention },
+		});
+}

package/src/shared/fork-context.ts

@@ -1,8 +1,12 @@
-import { randomUUID } from "node:crypto";
+// Forking a parent transcript into a child must drop Anthropic's signed and redacted
+// thinking blocks: a thinking signature is bound to the session that produced it and
+// cannot be replayed into a branch. Stripping them is required; disabling the child's
+// thinking is not. Pi >= 0.85.0 recovers from signed-thinking mismatches on the
+// transport, so a sanitized transcript is safe to resume with thinking enabled and the
+// child keeps the level it asked for, reasoning fresh from its first turn.
 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";
 
@@ -19,7 +23,6 @@ interface BranchSessionEntry {
 		api?: string;
 		model?: string;
 	};
-	thinkingLevel?: string;
 }
 
 interface BranchSessionManager {
@@ -39,20 +42,11 @@ 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 {
@@ -101,20 +95,6 @@ export function canPreferForkFromSnapshot(input: PreferredForkSnapshot): boolean
 	}
 }
 
-/** 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() : "";
@@ -128,28 +108,6 @@ function isUnsafeAnthropicThinkingBlock(message: BranchSessionEntry["message"],
 	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) {
@@ -183,7 +141,6 @@ export function createForkContextResolver(
 		return {
 			prepareSessionForIndex: async () => {},
 			sessionFileForIndex: () => undefined,
-			thinkingOverrideForIndex: () => undefined,
 		};
 	}
 
@@ -217,12 +174,12 @@ export function createForkContextResolver(
 		path.basename(parentSessionFile, ".jsonl"),
 		"forks",
 	);
-	const cachedResolutions = new Map<number, ForkContextResolution>();
+	const cachedSessionFiles = new Map<number, string>();
 	const preparedIndexes = new Set<number>();
 	const preparationPromises = new Map<number, Promise<void>>();
 
-	const resolveFork = (index = 0): ForkContextResolution => {
-		const cached = cachedResolutions.get(index);
+	const resolveFork = (index = 0): string => {
+		const cached = cachedSessionFiles.get(index);
 		if (cached) return cached;
 		try {
 			if (!fs.existsSync(parentSessionFile)) {
@@ -233,34 +190,23 @@ export function createForkContextResolver(
 			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";
-				}
+				sanitizeUnsafeThinkingBlocks(entries);
 				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;
+			cachedSessionFiles.set(index, sessionFile);
+			return sessionFile;
 		} catch (error) {
 			const cause = error instanceof Error ? error : new Error(String(error));
 			throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
@@ -269,11 +215,11 @@ export function createForkContextResolver(
 
 	return {
 		async prepareSessionForIndex(index = 0): Promise<void> {
-			const resolution = resolveFork(index);
+			const sessionFile = resolveFork(index);
 			if (!options.pruneSession || preparedIndexes.has(index)) return;
 			let preparation = preparationPromises.get(index);
 			if (!preparation) {
-				preparation = options.pruneSession(resolution.sessionFile).then(() => {
+				preparation = options.pruneSession(sessionFile).then(() => {
 					preparedIndexes.add(index);
 				});
 				preparationPromises.set(index, preparation);
@@ -284,10 +230,7 @@ export function createForkContextResolver(
 			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;
+			return resolveFork(index);
 		},
 	};
 }

package/src/shared/launch-contract.ts

@@ -1,10 +1,13 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import type { AgentConfig } from "../agents/agents.ts";
+import type { PiLaunchToolPlan } from "../runs/shared/child-tool-plan.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;
+export const AGENT_DEFINITION_PROJECTION_VERSION = 2 as const;
+// v2: the Intercom bridge prompt and tools are part of the binding on every
+// path, and the bridge text no longer names the parent session.
+export const LAUNCH_BINDING_PROJECTION_VERSION = 2 as const;
 
 function stableJson(value: unknown): string {
 	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
@@ -47,7 +50,6 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 		inheritSkills: agent.inheritSkills,
 		model: agent.model,
 		modelProvider: agent.modelProvider,
-		fallbackModels: agent.fallbackModels,
 		fast: agent.fast,
 		thinking: agent.thinking,
 		tools: agent.tools,
@@ -60,6 +62,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 		skills: agent.skills,
 		skillPath: agent.skillPath,
 		output: agent.output,
+		outputSchema: agent.outputSchema,
 		defaultReads: agent.defaultReads,
 		defaultProgress: agent.defaultProgress,
 		defaultContext: agent.defaultContext,
@@ -75,8 +78,9 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 	};
 }
 
+/** Digest of the parsed definition; a runtime overlay that already captured it wins over re-hashing the overlaid copy. */
 export function agentDefinitionDigest(agent: AgentConfig): string {
-	return stableJsonDigest(projectAgentDefinition(agent));
+	return agent.definitionDigest ?? stableJsonDigest(projectAgentDefinition(agent));
 }
 
 export interface LaunchBindingInput {
@@ -84,7 +88,6 @@ export interface LaunchBindingInput {
 	/** 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;
@@ -110,9 +113,7 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
 		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,
+		model: input.model,
 		fast: input.fast,
 		thinking: input.thinking,
 		systemPromptDigest: input.systemPrompt === undefined || input.systemPrompt === null ? undefined : stableJsonDigest(input.systemPrompt),
@@ -136,3 +137,62 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
 export function launchBindingDigest(input: LaunchBindingInput): string {
 	return stableJsonDigest(projectLaunchBinding(input));
 }
+
+type LaunchBindingPromptMode = Pick<LaunchBindingInput, "systemPromptMode" | "inheritProjectContext" | "inheritGlobalContext" | "inheritSkills">;
+
+/**
+ * Who the child is: the launched agent, or the identity a persisted step
+ * already captured when a runner recomputes the binding per model attempt.
+ */
+export type LaunchBindingIdentity =
+	| { agent: AgentConfig }
+	| ({ definitionDigest: string } & LaunchBindingPromptMode);
+
+export type LaunchBindingSource = LaunchBindingIdentity
+	& Pick<LaunchBindingInput, "fast" | "thinking" | "skills" | "outputPath" | "outputMode" | "structuredOutputSchema" | "extensionBindings">
+	& {
+		task: string;
+		model?: string;
+		/** Effective child system prompt before runtime acceptance prose. */
+		systemPrompt: string;
+		toolPlan: Pick<PiLaunchToolPlan, "effectiveToolAllowlist" | "excludeTools" | "extensionArgs" | "effectiveMcpTools">;
+	};
+
+export interface LaunchBinding {
+	definitionDigest: string;
+	launchContractDigest: string;
+}
+
+/**
+ * Assemble launch identity from resolved preflight or execution inputs.
+ * The stable projection omits undefined optional fields.
+ */
+export function resolveLaunchBinding(source: LaunchBindingSource): LaunchBinding {
+	const identity = "agent" in source ? {
+		definitionDigest: agentDefinitionDigest(source.agent),
+		systemPromptMode: source.agent.systemPromptMode,
+		inheritProjectContext: source.agent.inheritProjectContext,
+		inheritGlobalContext: source.agent.inheritGlobalContext,
+		inheritSkills: source.agent.inheritSkills,
+	} : source;
+	return {
+		definitionDigest: identity.definitionDigest,
+		launchContractDigest: launchBindingDigest({
+			...identity,
+			task: source.task,
+			model: source.model,
+			fast: source.fast,
+			thinking: source.thinking || undefined,
+			systemPrompt: source.systemPrompt,
+			skills: source.skills,
+			tools: source.toolPlan.effectiveToolAllowlist,
+			excludeTools: source.toolPlan.excludeTools.length > 0 ? source.toolPlan.excludeTools : undefined,
+			extensions: source.toolPlan.extensionArgs,
+			mcpDirectTools: source.toolPlan.effectiveMcpTools,
+			outputPath: source.outputPath || undefined,
+			outputMode: source.outputMode,
+			structuredOutputSchema: source.structuredOutputSchema,
+			extensionBindings: source.extensionBindings || undefined,
+		}),
+	};
+}

package/src/shared/opencode-session-headers.ts

@@ -0,0 +1,30 @@
+import type { Api, Model, ProviderHeaders } from "@earendil-works/pi-ai";
+
+const OPENCODE_HOST = "opencode.ai";
+
+function matchesOpenCodeHost(baseUrl: string): boolean {
+	try {
+		return new URL(baseUrl).hostname === OPENCODE_HOST;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * OpenCode session-routing headers for internal subagent model calls.
+ *
+ * Pi's own session path emits these from coding-agent's provider-attribution
+ * merge, but subagent-internal calls (watchdog review, permission arbiter,
+ * task-mutation arbiter, prompt audit) stream through bare Agents that bypass
+ * that path. Without them OpenCode falls back to client-IP affinity and loses
+ * prompt-cache routing (see pi issue #4847). Returns undefined for every other
+ * provider so non-OpenCode requests stay byte-identical.
+ */
+export function opencodeSessionHeaders(
+	model: Pick<Model<Api>, "provider" | "baseUrl">,
+	sessionId: string | undefined,
+): ProviderHeaders | undefined {
+	if (!sessionId) return undefined;
+	if (model.provider !== "opencode" && model.provider !== "opencode-go" && !matchesOpenCodeHost(model.baseUrl)) return undefined;
+	return { "x-opencode-session": sessionId, "x-opencode-client": "pi" };
+}

package/src/shared/pruned-fork.ts

@@ -5,7 +5,7 @@ import * as path from "node:path";
 import type { TextContent } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resolveModelCandidate } from "../runs/shared/model-fallback.ts";
+import { resolveModelCandidate } from "../runs/shared/model-resolution.ts";
 import { splitKnownThinkingSuffix, toModelInfo } from "./model-info.ts";
 import type { ForkContextConfig } from "./types.ts";