pi-subagents 0.66.0 → 0.67.0

package/src/runs/shared/child-launch.ts

@@ -6,7 +6,6 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ChildWatchdogConfig, ChildWatchdogStatusEvent } from "../../watchdog/child-status.ts";
 import type { ThinkingLevel } from "../../shared/model-info.ts";
 import { intersectThinkingCeilings } from "../../shared/thinking-ceiling.ts";
@@ -35,6 +34,7 @@ import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
 import { createCapturedChildHooks, withChildSessionErrorReporting } from "./child-hooks.ts";
 import type { ChildTranscriptWriter } from "../../shared/child-transcript.ts";
 import type { ChildSessionLaunch, ChildSessionStorage } from "./child-session.ts";
+import type { ArbiterModelContext } from "./llm-intent-arbiter.ts";
 
 /** Environment variable pi-mcp-adapter reads for the tools a child may expose. */
 export const MCP_DIRECT_TOOLS_ENV = "MCP_DIRECT_TOOLS";
@@ -112,13 +112,21 @@ export interface BuildInProcessChildLaunchInput {
 	 * them and exposes the child environment external extensions read.
 	 */
 	host: "parent" | "runner";
+	/**
+	 * Builtin tool names the host runtime provides. When set, child tool plans
+	 * intersect declared agent tools with this set, omitting tools the host
+	 * cannot provide. Review/scout lanes fail closed when a requested,
+	 * still-permitted repository inspection tool is missing from that set.
+	 */
+	hostAvailableBuiltins?: readonly string[];
 }
 
 export interface InProcessChildCapture {
-	completionIntentContext?(): Pick<ExtensionContext, "model" | "modelRegistry"> | undefined;
+	completionIntentContext?(): ArbiterModelContext | undefined;
 	structuredOutput(): { called: boolean; value?: unknown; acceptanceReport?: unknown; acceptanceReportProvided: boolean };
 	toolDiagnostic(): ChildToolDiagnostic | undefined;
 	runtimeAcknowledgedExtensions(): RuntimeAcknowledgedChildExtensions | undefined;
+	finalDrainHeld(): boolean;
 }
 
 export interface InProcessChildLaunch {
@@ -192,6 +200,7 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 		agentName: input.childAgentName,
 		permissionRules: input.permissionRules,
 		runtimeSnapshotHost: input.runtimeSnapshotHost,
+		hostAvailableBuiltins: input.hostAvailableBuiltins,
 	});
 
 	const inherited = input.inherited;
@@ -311,6 +320,7 @@ export function buildInProcessChildLaunch(input: BuildInProcessChildLaunchInput)
 			structuredOutput: () => ({ called: structuredCalled, value: structuredValue, acceptanceReport: structuredAcceptanceReport, acceptanceReportProvided: structuredAcceptanceProvided }),
 			toolDiagnostic: capturedHooks.toolDiagnostic,
 			runtimeAcknowledgedExtensions: capturedHooks.runtimeAcknowledgedExtensions,
+			finalDrainHeld: capturedHooks.finalDrainHeld,
 		},
 		launchResolvedExtensions,
 		warnings: toolPlan.warnings,

package/src/runs/shared/child-lifecycle.ts

@@ -14,11 +14,14 @@ export function projectChildLifecycle(event: { type?: string; willRetry?: unknow
 		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 (event.type === "agent_start" || event.type === "auto_retry_start" || event.type === "turn_start") {
 		if (state) state.compactionRetryActive = false;
+		return "cancel-drain";
+	}
+	if (event.type === "agent_end") {
+		if (event.willRetry !== true && state) state.compactionRetryActive = false;
+		return "cancel-drain";
 	}
-	if (event.type === "agent_end" && event.willRetry === true) return "cancel-drain";
-	if (event.type === "agent_end" && state) state.compactionRetryActive = false;
 	if (event.type === "agent_settled") return state?.compactionRetryActive ? "none" : "start-drain";
 	if (terminalAssistantStop) return "start-drain";
 	return "none";

package/src/runs/shared/child-runtime-config.ts

@@ -1,4 +1,4 @@
-import type { JsonSchemaObject, ResolvedToolBudget, RunFanoutBudgetDescriptor } from "../../shared/types.ts";
+import type { JsonSchemaObject, ResolvedToolBudget, RunFanoutBudgetDescriptor, SubagentState } from "../../shared/types.ts";
 import type { ThinkingLevel } from "../../shared/model-info.ts";
 import type { NestedPathEntry } from "./nested-path.ts";
 import type { PermissionRules } from "./permissions.ts";
@@ -86,6 +86,8 @@ export interface ChildRuntimeConfig {
 	/** Receives child watchdog status events. */
 	watchdogStatus?: (event: ChildWatchdogStatusEvent) => void;
 	waitTool: ResolvedWaitToolConfig;
+	runtimeState?: SubagentState;
+	holdFinalDrain?: (held: boolean) => void;
 	structuredOutput?: ChildStructuredOutput;
 	requiredTools?: string[];
 	mcpDirectTools?: string[];

package/src/runs/shared/child-session.ts

@@ -93,6 +93,8 @@ export interface ChildSession {
 	abort(): Promise<void>;
 	/** Emits `session_shutdown` to the child's extensions and disposes the session; resolves once that shutdown work is done. */
 	dispose(): Promise<void>;
+	/** True while Pi still has steering or follow-up input that has not started a turn. */
+	hasQueuedMessages?(): boolean;
 	readonly messages: readonly AgentMessage[];
 	readonly sessionFile: string | undefined;
 	readonly sessionId: string;
@@ -103,6 +105,14 @@ export interface ChildSession {
 	shutDown?: boolean;
 }
 
+export function childSessionHasQueuedMessages(session: ChildSession | undefined): boolean {
+	try {
+		return session?.hasQueuedMessages?.() === true;
+	} catch {
+		return false;
+	}
+}
+
 export interface ChildSessionFactory {
 	create(launch: ChildSessionLaunch): Promise<ChildSession>;
 	/** Abort and dispose every live attached child; detached children keep running and hold the shared runtime. */
@@ -124,6 +134,21 @@ export interface DefaultChildSessionFactoryOptions {
 
 type ModelRuntimeInstance = Awaited<ReturnType<PiCodingAgentModule["ModelRuntime"]["create"]>>;
 
+const CHILD_PROMPT_RUNTIME_EXTENSION_PATH = "<inline:pi-subagents:prompt-runtime>";
+
+/** The prompt runtime filters parent-only context before ambient extensions inspect
+ *  the child prompt. Other inline hooks keep their normal position after ambient
+ *  extensions, and ambient extension order stays unchanged. */
+function prioritizeChildPromptRuntime<T extends { extensions: Array<{ path: string }> }>(result: T): T {
+	const index = result.extensions.findIndex(({ path }) => path === CHILD_PROMPT_RUNTIME_EXTENSION_PATH);
+	if (index <= 0) return result;
+	const extensions = [...result.extensions];
+	const [promptRuntime] = extensions.splice(index, 1);
+	if (!promptRuntime) return result;
+	extensions.unshift(promptRuntime);
+	return { ...result, extensions };
+}
+
 /** One launch at a time from env application through `session_start`, so parallel launches never observe each other's `processEnv` while their extensions load and start. */
 let loading: Promise<unknown> = Promise.resolve();
 
@@ -198,8 +223,12 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 			const modelRuntime = await sharedRuntime(pi);
 			const agentDir = getAgentDir();
 			const settingsManager = pi.SettingsManager.create(launch.cwd, agentDir);
-			// Headless sessions skip Pi's CLI theme setup; extensions still need ctx.ui.theme.
-			if (typeof pi.initTheme === "function") pi.initTheme(settingsManager.getTheme());
+			// Foreground children share Pi's global theme with the parent, so reinitializing it
+			// would overwrite the parent's active light/dark appearance. Detached runners have
+			// no initialized theme and must initialize one for headless extension renderers.
+			const themeKey = Symbol.for("@earendil-works/pi-coding-agent:theme");
+			const themeInitialized = Boolean((globalThis as Record<symbol, unknown>)[themeKey]);
+			if (!themeInitialized && typeof pi.initTheme === "function") pi.initTheme(settingsManager.getTheme());
 			const loader = new pi.DefaultResourceLoader({
 				cwd: launch.cwd,
 				agentDir,
@@ -211,6 +240,7 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 				noContextFiles: launch.noContextFiles,
 				additionalExtensionPaths: launch.extensionPaths,
 				extensionFactories: launch.hooks,
+				extensionsOverride: prioritizeChildPromptRuntime,
 				...(launch.systemPrompt !== undefined ? { systemPrompt: launch.systemPrompt } : {}),
 				...(launch.appendSystemPrompt !== undefined ? { appendSystemPrompt: [launch.appendSystemPrompt] } : {}),
 			});
@@ -294,6 +324,7 @@ export function createDefaultChildSessionFactory(options: DefaultChildSessionFac
 				steer: (text) => { evidence?.invalidate(); return session.steer(text); },
 				followUp: (text) => { evidence?.invalidate(); return session.followUp(text); },
 				abort: () => { evidence?.invalidate(); return session.abort(); },
+				hasQueuedMessages: () => session.agent?.hasQueuedMessages?.() === true,
 				dispose: () => {
 					if (!pending) {
 						live.delete(child);

package/src/runs/shared/child-tool-plan.ts

@@ -7,6 +7,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	formatUnresolvedMcpDirectToolSelectors,
 	resolveMcpDirectToolResolution,
@@ -60,6 +61,41 @@ const FAST_MODE_ALLOWED_MODELS = new Set([
 	"openai-codex/gpt-5.6-sol",
 ]);
 const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+const REPOSITORY_INSPECTION_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "powershell"]);
+const REVIEW_OR_SCOUT_AGENT_PATTERN = /\b(?:reviewer|scout)\b/i;
+// These providers come from child hooks, not the host's builtin tool registry.
+const NATIVE_COORDINATION_TOOL_NAMES = new Set(["subagent", "contact_supervisor", "subagent_supervisor"]);
+
+export function isReviewOrScoutLaneAgent(agentName: string | undefined): boolean {
+	return typeof agentName === "string" && REVIEW_OR_SCOUT_AGENT_PATTERN.test(agentName);
+}
+
+export function missingPermittedRepositoryInspectionTools(
+	unavailableHostBuiltins: readonly string[],
+	excludeTools: readonly string[] = [],
+): string[] {
+	const excluded = new Set(excludeTools);
+	return unavailableHostBuiltins.filter((tool) => REPOSITORY_INSPECTION_TOOLS.has(tool) && !excluded.has(tool));
+}
+
+export function formatReviewLaneToolContractFailure(input: {
+	agentName?: string;
+	missingTools: readonly string[];
+	requestedTools?: readonly string[];
+	effectiveTools: readonly string[];
+	ceilingSources?: readonly string[];
+	excludeTools?: readonly string[];
+}): string {
+	const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
+	return [
+		`${subject}: tool contract could not be satisfied; host runtime does not provide permitted required repository tools [${input.missingTools.join(", ")}].`,
+		`Requested tool names: ${input.requestedTools ? `[${input.requestedTools.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${input.effectiveTools.join(", ")}].`,
+		...(input.ceilingSources?.length ? [`Active capability ceiling sources: [${input.ceilingSources.join(", ")}].`] : []),
+		...(input.excludeTools?.length ? [`Explicit excludeTools: [${input.excludeTools.join(", ")}].`] : []),
+		"This is a lane infrastructure failure, not a completed review/scout result.",
+	].join(" ");
+}
 
 export function deriveForkPromptCacheKey(parentSessionId: string | undefined): string | undefined {
 	const parent = parentSessionId?.trim();
@@ -151,6 +187,15 @@ export interface ResolvePiLaunchToolPlanInput {
 	agentName?: string;
 	permissionRules?: PermissionRules;
 	runtimeSnapshotHost?: McpRuntimeSnapshotHost;
+	/**
+	 * When provided, child tool plans intersect declared builtin tools with
+	 * this set. Tools the agent declares but the host does not provide are
+	 * omitted with a non-fatal warning (tracked in `unavailableHostBuiltins`).
+	 * Review/scout lanes fail closed when a requested, still-permitted
+	 * repository inspection tool is among those host omissions. Intentionally
+	 * empty or ceiling-restricted allowlists are not a minimum-tool contract.
+	 */
+	hostAvailableBuiltins?: readonly string[];
 }
 
 export interface PiLaunchToolPlan {
@@ -174,6 +219,8 @@ export interface PiLaunchToolPlan {
 	capabilityAudit?: SubagentCapabilityAudit;
 	/** Non-fatal launch warnings; they do not change behavior. */
 	warnings: string[];
+	/** Builtin tools the agent declared but the host runtime does not provide. */
+	unavailableHostBuiltins: string[];
 }
 
 function extensionIdentifier(value: string): string {
@@ -289,6 +336,31 @@ export function resolvePermissionSystemExtension(): string | undefined {
 	return undefined;
 }
 
+/**
+ * Extract the names of builtin tools the host provides. Use this to pass
+ * `hostAvailableBuiltins` to `resolvePiLaunchToolPlan` so child tool plans
+ * intersect declared agent tools with what the host actually supports.
+ *
+ * Returns `undefined` when builtin tool discovery fails or yields nothing,
+ * so callers skip the intersection (fail-safe to allowing all declared tools).
+ * This handles test mocks without proper tool registration and hosts whose
+ * getAllTools() throws before extensions load.
+ */
+export function getHostBuiltinToolNames(pi: Pick<ExtensionAPI, "getAllTools">): string[] | undefined {
+	try {
+		const builtins = pi
+			.getAllTools()
+			.filter((tool) => {
+				const source = (tool.sourceInfo as { source?: string } | undefined)?.source;
+				return source === "builtin" || (source === "auto" && PI_BUILTIN_TOOL_NAMES.has(tool.name));
+			})
+			.map((tool) => tool.name);
+		return builtins.length > 0 ? builtins : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 export function resolvePiLaunchToolPlan(
 	input: ResolvePiLaunchToolPlanInput,
 ): PiLaunchToolPlan {
@@ -300,17 +372,27 @@ export function resolvePiLaunchToolPlan(
 		capabilityCeiling?.allowedTools === undefined
 			? undefined
 			: new Set(capabilityCeiling.allowedTools);
+	const hostAvailableSet =
+		input.hostAvailableBuiltins === undefined
+			? undefined
+			: new Set(input.hostAvailableBuiltins);
 	const requestedBuiltinTools =
 		input.tools?.filter(
 			(tool) =>
 				!(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")),
 		) ?? [];
+	if (input.requireReadTool && hostAvailableSet && !hostAvailableSet.has("read")) {
+		const agentLabel = input.agentName ? ` for agent '${input.agentName}'` : "";
+		throw new Error(
+			`Host runtime does not provide required tool 'read'${agentLabel} for lazy skill loading.`,
+		);
+	}
 	if (input.requireReadTool && allowedToolSet && !allowedToolSet.has("read")) {
 		throw new Error(
 			`Capability ceiling from ${capabilityCeiling?.sources.join(", ") || "unknown source"} excludes required tool 'read' for lazy skill loading.`,
 		);
 	}
-	const declaredBuiltinTools =
+	const ceilingFilteredBuiltinTools =
 		input.tools === undefined
 			? allowedToolSet
 				? [...allowedToolSet]
@@ -322,6 +404,12 @@ export function resolvePiLaunchToolPlan(
 					? ["read", ...requestedBuiltinTools]
 					: requestedBuiltinTools
 				).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
+	const declaredBuiltinTools = hostAvailableSet
+		? ceilingFilteredBuiltinTools.filter((tool) => hostAvailableSet.has(tool) || NATIVE_COORDINATION_TOOL_NAMES.has(tool))
+		: ceilingFilteredBuiltinTools;
+	const unavailableHostBuiltins = hostAvailableSet
+		? ceilingFilteredBuiltinTools.filter((tool) => !hostAvailableSet.has(tool) && !NATIVE_COORDINATION_TOOL_NAMES.has(tool))
+		: [];
 	const excludeTools = [...new Set((input.excludeTools ?? []).map((tool) => tool.trim()).filter(Boolean))];
 	const excludedToolSet = new Set(excludeTools);
 	const effectiveDeclaredBuiltinTools = declaredBuiltinTools.filter((tool) => !excludedToolSet.has(tool));
@@ -330,6 +418,9 @@ export function resolvePiLaunchToolPlan(
 		!excludedToolSet.has("subagent") &&
 		(!allowedToolSet || allowedToolSet.has("subagent"))
 	);
+	if (effectiveDeclaredBuiltinTools.includes("subagent_supervisor") && !fanoutAuthorized) {
+		throw new Error("Tool 'subagent_supervisor' requires fanout authorization: include 'subagent' in the effective tools allowlist or enable allowNestedSubagents.");
+	}
 	const toolExtensionPaths: string[] = capabilityCeiling?.denyExtensions
 		? []
 		: (input.tools ?? []).filter(
@@ -370,8 +461,8 @@ export function resolvePiLaunchToolPlan(
 			...internalTools,
 		]),
 	];
-	// Supervisor-coordination names stay in the --tools allowlist but are never
-	// strict requirements: children register contact_supervisor at runtime through
+	// Upward contact stays in the --tools allowlist but is not a strict
+	// requirement: children register contact_supervisor at runtime through
 	// the native supervisor channel (or pi-intercom). The pre-0.50 bridge always
 	// appended intercom alongside contact_supervisor, so that exact pairing is
 	// legacy plumbing, not a user demand for an external intercom provider;
@@ -437,6 +528,32 @@ export function resolvePiLaunchToolPlan(
 					]),
 				]
 			: undefined;
+	const missingPermittedRepositoryTools = input.tools !== undefined
+		? missingPermittedRepositoryInspectionTools(unavailableHostBuiltins, excludeTools)
+		: [];
+	if (missingPermittedRepositoryTools.length > 0 && isReviewOrScoutLaneAgent(input.agentName)) {
+		throw new Error(formatReviewLaneToolContractFailure({
+			agentName: input.agentName,
+			missingTools: missingPermittedRepositoryTools,
+			requestedTools: requestedToolNames,
+			effectiveTools: effectiveToolAllowlist,
+			ceilingSources: capabilityCeiling?.sources,
+			excludeTools,
+		}));
+	}
+	// Host pruning also happens without a ceiling (and therefore without an
+	// audit). Use the existing non-fatal launch warnings rather than inventing
+	// a ceiling or treating the requested allowlist as a minimum requirement.
+	if (unavailableHostBuiltins.length > 0) {
+		const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
+		warnings.push(
+			`${subject}: host runtime tool availability omitted [${unavailableHostBuiltins.join(", ")}]. `
+				+ `Requested tool names: ${requestedToolNames ? `[${requestedToolNames.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${effectiveToolAllowlist.join(", ")}]. `
+				+ (capabilityCeiling ? `Active capability ceiling sources: [${capabilityCeiling.sources.join(", ") || "unknown source"}]. ` : "")
+				+ (excludeTools.length > 0 ? `Explicit excludeTools: [${excludeTools.join(", ")}]. ` : "")
+				+ "This is a non-fatal tool-plan diagnostic, not verification of the child's runtime tool menu.",
+		);
+	}
 	const capabilityAudit = capabilityCeiling
 		? ({
 				ceiling: capabilityCeiling,
@@ -474,6 +591,7 @@ export function resolvePiLaunchToolPlan(
 								capabilityCeilingAgentRestrictionSources(capabilityCeiling),
 						}
 					: {}),
+				...(unavailableHostBuiltins.length > 0 ? { unavailableHostBuiltins } : {}),
 			} satisfies SubagentCapabilityAudit)
 		: undefined;
 	return {
@@ -495,6 +613,7 @@ export function resolvePiLaunchToolPlan(
 		extensionArgs,
 		disableAmbientExtensions,
 		warnings,
+		unavailableHostBuiltins,
 		...(capabilityAudit ? { capabilityAudit } : {}),
 	};
 }

package/src/runs/shared/completion-guard.ts

@@ -98,10 +98,12 @@ export function validateImplementationToolContract(input: {
 	const declaredMutationToolsWereRemoved = requestedMutationTools.length > 0 && !hasBuiltinMutationTool(input.tools);
 	const configuredExtensionCapability = (input.configuredExtensions?.length ?? 0) > 0 && !declaredMutationToolsWereRemoved;
 	if (hasMutationToolCapability(input.tools, input.mcpDirectTools) || configuredExtensionCapability) return undefined;
-	const intent = classifyTaskMutationIntent(input.agent, input.task);
+	const intent = classifyTaskMutationIntent(input.acceptanceRole === "writer" ? "worker" : input.agent, input.task);
 	if (intent.kind === "read-only") return undefined;
-	const writerTaskMayMutate = isWriterRole(input.agent, input.acceptanceRole)
-		&& (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
+	const writerTaskMayMutate = input.acceptanceRole === "writer"
+		? true
+		: isWriterRole(input.agent, input.acceptanceRole)
+			&& (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
 	if (intent.kind !== "implementation" && !writerTaskMayMutate && !declaredMutationToolsWereRemoved) return undefined;
 	return `Agent '${input.agent}' was given an implementation task, but its tool allowlist has no mutation-capable tools. Add bash, edit, write, or another mutation-capable tool to the agent, or use a read-only task/agent.`;
 }

package/src/runs/shared/effective-system-prompt.ts

@@ -0,0 +1,33 @@
+import type { AgentConfig } from "../../agents/agents.ts";
+import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
+import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
+import { buildSkillInjection } from "../../agents/skills.ts";
+import { injectOutputPathSystemPrompt } from "./single-output.ts";
+
+export interface EffectiveSystemPromptInput {
+	/** Agent as handed to the child, including runtime-declared overlays such as the Intercom bridge. */
+	agent: AgentConfig;
+	resolvedSkills: Parameters<typeof buildSkillInjection>[0];
+	/** Directory that scopes memory and refinement lookups. */
+	cwd: string;
+	/** Omit when the caller injects the output path through another channel. */
+	outputPath?: string;
+}
+
+function appendSection(prompt: string, section: string): string {
+	return prompt ? `${prompt}\n\n${section}` : section;
+}
+
+/**
+ * Child system prompt in the order preflight and every execution path hash:
+ * base prompt, skills, memory, refinement overlay, output path. Runtime
+ * acceptance prose is appended later and stays outside launch identity.
+ */
+export function buildEffectiveSystemPrompt(input: EffectiveSystemPromptInput): string {
+	let prompt = input.agent.systemPrompt?.trim() ?? "";
+	if (input.resolvedSkills.length > 0) prompt = appendSection(prompt, buildSkillInjection(input.resolvedSkills));
+	const memoryInjection = buildAgentMemoryInjection(input.agent, input.cwd);
+	if (memoryInjection) prompt = appendSection(prompt, memoryInjection);
+	prompt = appendAgentRefinementOverlay(prompt, { cwd: input.cwd, agentName: input.agent.name });
+	return injectOutputPathSystemPrompt(prompt, input.outputPath, input.agent);
+}

package/src/runs/shared/external-cli-runner.ts

@@ -3,7 +3,7 @@ import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { finished } from "node:stream/promises";
-import type { ExternalProcessStatus } from "../../shared/types.ts";
+import type { ExternalProcessStatus, ProcessTreeTerminal } from "../../shared/types.ts";
 import { createOwnedProcessTreeController, type OwnedProcessTreeController } from "../background/owned-process-tree.ts";
 import { omitExtensionBindingsEnv } from "./extension-bindings.ts";
 import {
@@ -141,7 +141,7 @@ function classifyInvalidation(error: string): "auth" | "permission" | "launch" {
 	return "launch";
 }
 
-function terminateExternalProcessTree(pid: number, controller: OwnedProcessTreeController): Promise<unknown> {
+function terminateExternalProcessTree(pid: number, controller: OwnedProcessTreeController): Promise<ProcessTreeTerminal> {
 	if (process.platform !== "win32") return controller.terminate();
 	return new Promise((resolve) => {
 		const cleanup = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
@@ -239,7 +239,7 @@ export function runExternalCli(input: {
 		let settled = false;
 		let processTree: OwnedProcessTreeController | undefined;
 		let processPid: number | undefined;
-		let termination: Promise<unknown> | undefined;
+		let termination: Promise<ProcessTreeTerminal> | undefined;
 		const flushProgress = () => {
 			if (!latestProgress) return;
 			input.onParserProgress?.(latestProgress);
@@ -381,8 +381,7 @@ export function runExternalCli(input: {
 			input.registerTimeout?.(undefined);
 			input.registerStop?.(undefined);
 			void (async () => {
-				if (termination) await termination;
-				else if (processTree) await processTree.finishAfterWriterClose();
+				const treeProof = termination ? await termination : processTree ? await processTree.finishAfterWriterClose() : undefined;
 				const endedAt = Date.now();
 				const externalProcess: ExternalProcessStatus = {
 					...initialProcess,
@@ -398,15 +397,18 @@ export function runExternalCli(input: {
 				input.onProcess?.(externalProcess);
 				const stderr = stderrTail.text().trim();
 				const parserFailure = parserError?.message ?? (parserTerminal?.state === "failed" ? parserTerminal.error ?? "External CLI parser reported terminal failure." : undefined);
+				const treeFailure = process.platform !== "win32" && treeProof?.state === "unknown"
+					? `Process-tree cleanup failed: ${treeProof.reason}.`
+					: undefined;
 				const error = stopped
 					? input.stopMessage ?? "Subagent stopped by user."
 					: timedOut
 						? input.timeoutMessage ?? "Subagent timed out."
-						: spawnError?.message ?? parserFailure ?? (exitCode === 0 ? undefined : stderr || `External CLI exited with code ${exitCode}.`);
+						: spawnError?.message ?? parserFailure ?? treeFailure ?? (exitCode === 0 ? undefined : stderr || `External CLI exited with code ${exitCode}.`);
 				if (error && input.preflight && !parserError) invalidateExternalCliPreflight(input.command, input.preflight, classifyInvalidation(error));
 				const result: ExternalCliRunResult = {
 					output: (!parserError && parserTerminal?.state === "completed" ? parserTerminal.output ?? "" : stdoutTail.text()).trim(),
-					exitCode: timedOut || stopped || spawnError || parserFailure ? 1 : exitCode,
+					exitCode: timedOut || stopped || spawnError || parserFailure || treeFailure ? 1 : exitCode,
 					...(error ? { error } : {}),
 					...(timedOut ? { timedOut: true } : {}),
 					...(stopped ? { stopped: true } : {}),

package/src/runs/shared/llm-intent-arbiter.ts

@@ -4,6 +4,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ProviderHeaders } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import { agentStreamOptions } from "../../shared/agent-stream-options.ts";
+import { opencodeSessionHeaders } from "../../shared/opencode-session-headers.ts";
 
 /**
  * LLM intent arbiter for the completion mutation guard.
@@ -56,6 +57,8 @@ interface ArbiterRuntime {
 	/** Registered provider stream, usable only when its api matches the model. */
 	registeredStreamFn?: StreamFn;
 	registeredApi?: string;
+	/** Session id for OpenCode session-routing headers, when the caller has one. */
+	sessionId?: string;
 	timeoutMs: number;
 }
 
@@ -76,7 +79,11 @@ export interface TaskMutationArbiterOptions {
 const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
 
 type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
-type ArbiterModelContext = Pick<ExtensionContext, "model" | "modelRegistry">;
+/** Model services the arbiter needs, plus the caller's session id for OpenCode session-routing headers. */
+export type ArbiterModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> & {
+	/** Session id the headers attach to (the child's, captured by detached runners; the parent's, passed by foreground callers). */
+	sessionId?: string;
+};
 
 function resolveArbiterModel(
 	ctx: ArbiterModelContext,
@@ -113,6 +120,7 @@ function resolveArbiterRuntime(
 		explicitStreamFn: options?.streamFn,
 		registeredStreamFn: registered?.streamSimple,
 		registeredApi: registered?.api,
+		sessionId: ctx.sessionId,
 		timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS,
 	};
 }
@@ -151,12 +159,13 @@ async function resolveArbiterAuth(
 function authWrappedStreamFn(
 	base: StreamFn,
 	auth: ArbiterAuth,
+	sessionId: string | undefined,
 ): StreamFn {
 	return (model, context, streamOptions) => base(model, context, {
 		...(streamOptions ?? {}),
 		...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
 		...(auth.env || streamOptions?.env ? { env: { ...(auth.env ?? {}), ...(streamOptions?.env ?? {}) } } : {}),
-		headers: { ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
+		headers: { ...opencodeSessionHeaders(model, sessionId), ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
 	});
 }
 
@@ -200,7 +209,7 @@ async function runArbitration(
 			tools: [tool],
 		},
 		convertToLlm,
-		...agentStreamOptions(authWrappedStreamFn(streamFn, auth)),
+		...agentStreamOptions(authWrappedStreamFn(streamFn, auth, runtime.sessionId)),
 		getApiKey: (providerName) =>
 			providerName === runtime.model.provider ? auth.apiKey : undefined,
 		beforeToolCall: async ({ toolCall }) =>

package/src/runs/shared/model-fallback.ts

@@ -543,6 +543,8 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/quota/i,
 	/billing/i,
 	/credit/i,
+	// OpenRouter can return only a status-prefixed body, without auth-related prose.
+	/^\s*401\s*:/,
 	/auth(?:entication)?/i,
 	/unauthori[sz]ed/i,
 	/forbidden/i,

package/src/runs/shared/orca-progress-tabs.ts

@@ -29,7 +29,7 @@ const ORCA_CREATE_WATCHDOG_SCRIPT = [
 	"function exists(file){try{return fs.existsSync(file)}catch{return false}}",
 	"function keepQueued(){try{const now=new Date();fs.utimesSync(done,now,now)}catch{}}",
 	"function predecessorReady(){if(previous==='-')return true;if(exists(previous.replace(/\\.pending$/,'.ready')))return true;try{return Date.now()-fs.statSync(previous).mtimeMs>=waitTimeout}catch{return true}}",
-	"function updateManifest(state,stdout=''){if(manifest==='-')return;try{const payload=JSON.parse(fs.readFileSync(manifest,'utf8'));payload.state=state;payload.updatedAt=new Date().toISOString();const raw=stdout.trim().split(/\\r?\\n/).filter(Boolean).at(-1);if(raw){try{payload.orca=JSON.parse(raw)}catch{payload.orcaRaw=raw.slice(0,4096)}}fs.writeFileSync(manifest,JSON.stringify(payload,null,2)+'\\n')}catch{}}",
+	"function updateManifest(state,stdout=''){if(manifest==='-')return;try{const payload=JSON.parse(fs.readFileSync(manifest,'utf8'));payload.state=state;payload.updatedAt=new Date().toISOString();const raw=stdout.trim();if(raw){try{payload.orca=JSON.parse(raw)}catch{payload.orcaRaw=raw.slice(0,4096)}}fs.writeFileSync(manifest,JSON.stringify(payload,null,2)+'\\n')}catch{}}",
 	"function start(){",
 	" try{",
 	"  const child=spawn(command,args,{stdio:['ignore','pipe','ignore'],windowsHide:true});",

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

@@ -49,6 +49,7 @@ export interface PiSpawnDeps {
 	platform?: NodeJS.Platform;
 	execPath?: string;
 	argv1?: string;
+	bunVersion?: string;
 	existsSync?: (filePath: string) => boolean;
 	realpathSync?: (filePath: string) => string;
 	readFileSync?: (filePath: string, encoding: "utf-8") => string;
@@ -58,6 +59,15 @@ export interface PiSpawnDeps {
 	env?: NodeJS.ProcessEnv;
 }
 
+/** Compiled Pi's entrypoint is virtual; execPath is the real (possibly renamed) image. */
+export function resolveBunPiExecutable(deps: PiSpawnDeps = {}): string | undefined {
+	const bunVersion = deps.bunVersion ?? process.versions.bun;
+	const entry = deps.argv1 ?? process.argv[1];
+	if (!bunVersion || !entry?.startsWith("/$bunfs/")) return undefined;
+	const env = deps.env ?? process.env;
+	return env[PI_SUBAGENT_PI_BINARY_ENV]?.trim() || (deps.execPath ?? process.execPath);
+}
+
 interface PiSpawnCommand {
 	command: string;
 	args: string[];

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

@@ -451,10 +451,11 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 	registerPermissionGate(pi, config.permissions, config.childWatchdog);
 	registerToolBudget(pi, config.toolBudget);
 	registerChildWatchdog(pi, config.childWatchdog, config.watchdogStatus);
-	const waitState = {
+	const waitState = config.runtimeState ?? {
 		baseCwd: "",
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
 		cleanupTimers: new Map(),
@@ -486,13 +487,18 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		if (diagnostic) throw new Error(formatChildToolDiagnostic(diagnostic));
 	});
 	onRuntimeEvent("agent_end", async (_event: unknown, ctx: unknown) => {
-		if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) { drainObservation?.deny(); return; }
+		if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) drainObservation?.deny();
 		if (drainObservation) {
 			try {
 				if ((ctx as ExtensionContext)?.sessionManager?.getSessionFile() !== waitState.currentSessionId) drainObservation.deny();
 			} catch { drainObservation.deny(); }
 		}
-		await drainOutstandingWork({ state: waitState, events: pi.events }, drainObservation);
+		config.holdFinalDrain?.(true);
+		try {
+			await drainOutstandingWork({ state: waitState, events: pi.events }, drainObservation);
+		} finally {
+			config.holdFinalDrain?.(false);
+		}
 	});
 	if (config.structuredOutput) registerStructuredOutputTool(pi, config.structuredOutput);