pi-subagents 0.65.1 → 0.67.0

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,
@@ -16,7 +17,7 @@ import {
 import {
 	TEMP_ROOT_DIR,
 	type JsonSchemaObject,
-	type LaunchResolvedChildExtensionsV1,
+	type LaunchResolvedChildExtensions,
 } from "../../shared/types.ts";
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
 import { getAgentDir } from "../../shared/utils.ts";
@@ -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 {
@@ -214,7 +261,7 @@ export function projectLaunchResolvedChildExtensions(
 		| "extensionArgs"
 		| "disableAmbientExtensions"
 	>,
-): LaunchResolvedChildExtensionsV1 {
+): LaunchResolvedChildExtensions {
 	const runtime = boundedExtensionIdentifiers(toolPlan.runtimeExtensions);
 	const configured = boundedExtensionIdentifiers(toolPlan.configuredExtensions);
 	const effective = boundedExtensionIdentifiers(toolPlan.extensionArgs);
@@ -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-evidence.ts

@@ -26,7 +26,7 @@ export function planCompletionEvidence(input: {
 	mutationAttemptObserved: boolean;
 	mutationEvidence?: TrackedMutationEvidence;
 	arbiterRescued?: boolean;
-	agentContractV1: boolean;
+	agentContractEnabled: boolean;
 }): CompletionEvidencePlan {
 	const guardBlocked = input.guard?.blocked === true;
 	const guardTriggered = input.guardTriggered
@@ -59,7 +59,7 @@ export function planCompletionEvidence(input: {
 		mutationExpected,
 		mutationAttempted,
 		fileMutation,
-		legacyFailureError: guardTriggered && !input.agentContractV1
+		legacyFailureError: guardTriggered && !input.agentContractEnabled
 			? MISSING_IMPLEMENTATION_MUTATION_ERROR
 			: undefined,
 	};

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

@@ -13,6 +13,7 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 	"web_search",
 	"fetch_content",
 	"get_search_content",
+	"source_check",
 	"intercom",
 	"contact_supervisor",
 	"structured_output",
@@ -97,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/host-step-status.ts

@@ -1,6 +1,6 @@
 import type {
 	AsyncStatus,
-	HostStepNodeV1,
+	HostStepNode,
 	HostStepState,
 	HostStepVerdict,
 	WorkflowGraphNode,
@@ -57,7 +57,7 @@ function assertTimestamp(value: unknown, field: string, source: string, required
 	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`Invalid host step '${source}': ${field} must be a non-negative safe integer.`);
 }
 
-function assertFreshness(value: unknown, source: string): asserts value is HostStepNodeV1["freshness"] {
+function assertFreshness(value: unknown, source: string): asserts value is HostStepNode["freshness"] {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': freshness must be an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !FRESHNESS_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': freshness has unsupported fields: ${unknownFields.join(", ")}.`);
@@ -70,7 +70,7 @@ function assertFreshness(value: unknown, source: string): asserts value is HostS
  * Validate the persisted host-step contract. This deliberately rejects unknown
  * fields and unbounded values so status and receipt loaders fail closed.
  */
-export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNodeV1 {
+export function assertHostStepNode(value: unknown, source = "status"): asserts value is HostStepNode {
 	if (!isRecord(value)) throw new Error(`Invalid host step '${source}': expected an object.`);
 	const unknownFields = Object.keys(value).filter((field) => !HOST_STEP_FIELDS.has(field));
 	if (unknownFields.length > 0) throw new Error(`Invalid host step '${source}': unsupported fields: ${unknownFields.join(", ")}.`);
@@ -105,7 +105,7 @@ export function assertHostStepNode(value: unknown, source = "status"): asserts v
 	assertTimestamp(value.deadlineAt, "deadlineAt", source);
 }
 
-export function parseHostStepNode(value: unknown, source = "status"): HostStepNodeV1 {
+export function parseHostStepNode(value: unknown, source = "status"): HostStepNode {
 	assertHostStepNode(value, source);
 	return {
 		...value,
@@ -113,7 +113,7 @@ export function parseHostStepNode(value: unknown, source = "status"): HostStepNo
 	};
 }
 
-export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], source = "status"): void {
+export function assertUniqueHostStepIds(hostSteps: readonly HostStepNode[], source = "status"): void {
 	const ids = new Set<string>();
 	for (const hostStep of hostSteps) {
 		if (ids.has(hostStep.id)) throw new Error(`Invalid host step '${source}': duplicate host step id '${hostStep.id}'.`);
@@ -122,11 +122,11 @@ export function assertUniqueHostStepIds(hostSteps: readonly HostStepNodeV1[], so
 }
 
 /** Return only valid host nodes so an untrusted in-memory projection fails closed. */
-export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNodeV1[] {
+export function validHostStepNodes(graph: WorkflowGraphSnapshot | undefined): HostStepNode[] {
 	const nodes = graph?.nodes ?? [];
 	const nodeIdCounts = new Map<string, number>();
 	for (const node of nodes) nodeIdCounts.set(node.id, (nodeIdCounts.get(node.id) ?? 0) + 1);
-	const hostSteps: HostStepNodeV1[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		try {
@@ -147,7 +147,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	if (!Array.isArray(graph.nodes)) throw new Error(`Invalid host step '${source}.workflowGraph': nodes must be an array.`);
 	const hostStepCount = graph.nodes.filter((node) => node.kind === "host-step").length;
 	if (hostStepCount > HOST_STEP_MAX_COUNT) throw new Error(`Invalid host step '${source}': workflowGraph contains more than ${HOST_STEP_MAX_COUNT} host steps.`);
-	const hostSteps: HostStepNodeV1[] = [];
+	const hostSteps: HostStepNode[] = [];
 	for (const [index, node] of graph.nodes.entries()) {
 		if (node.kind !== "host-step") continue;
 		const hostStep = parseHostStepNode(node.hostStep, `${source}.workflowGraph.nodes[${index}].hostStep`);
@@ -161,7 +161,7 @@ export function assertWorkflowGraphHostSteps(graph: WorkflowGraphSnapshot | unde
 	}
 }
 
-export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNode {
+export function hostStepWorkflowNode(hostStep: HostStepNode): WorkflowGraphNode {
 	assertHostStepNode(hostStep, hostStep.id);
 	return {
 		id: hostStep.id,
@@ -172,7 +172,7 @@ export function hostStepWorkflowNode(hostStep: HostStepNodeV1): WorkflowGraphNod
 	};
 }
 
-function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
+function workflowNodeStatus(hostStep: HostStepNode): WorkflowNodeStatus {
 	if (hostStep.state === "pending") return "pending";
 	if (hostStep.state === "running") return "running";
 	if (hostStep.state === "cancelled") return "stopped";
@@ -187,7 +187,7 @@ function workflowNodeStatus(hostStep: HostStepNodeV1): WorkflowNodeStatus {
  */
 export function upsertHostStep(input: {
 	status: AsyncStatus;
-	hostStep: HostStepNodeV1;
+	hostStep: HostStepNode;
 	persist: (status: AsyncStatus) => void;
 }): AsyncStatus {
 	const hostStep = parseHostStepNode(input.hostStep, input.hostStep.id);

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,9 +79,14 @@ export interface TaskMutationArbiterOptions {
 const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
 
 type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
+/** 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: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): NonNullable<RegistryModel> | null {
 	const registry = ctx.modelRegistry as {
@@ -98,7 +106,7 @@ function resolveArbiterModel(
 }
 
 function resolveArbiterRuntime(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): ArbiterRuntime | null {
 	const model = resolveArbiterModel(ctx, options);
@@ -112,14 +120,15 @@ function resolveArbiterRuntime(
 		explicitStreamFn: options?.streamFn,
 		registeredStreamFn: registered?.streamSimple,
 		registeredApi: registered?.api,
+		sessionId: ctx.sessionId,
 		timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS,
 	};
 }
 
 async function resolveArbiterAuth(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	model: RegistryModel,
-): Promise<ArbiterAuth> {
+): Promise<ArbiterAuth | undefined> {
 	const registry = ctx.modelRegistry as {
 		getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
 			ok: boolean;
@@ -135,14 +144,14 @@ async function resolveArbiterAuth(
 	if (!registry.getApiKeyAndHeaders) return {};
 	try {
 		const auth = await registry.getApiKeyAndHeaders(model);
-		if (auth.ok === false) return {};
+		if (auth.ok === false) return undefined;
 		return {
 			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
 			...(auth.headers ? { headers: auth.headers } : {}),
 			...(auth.env ? { env: auth.env } : {}),
 		};
 	} catch {
-		return {};
+		return undefined;
 	}
 }
 
@@ -150,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 ?? {}) },
 	});
 }
 
@@ -199,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 }) =>
@@ -230,9 +240,9 @@ async function runArbitration(
 	}
 }
 
-/** Create a memoized arbiter bound to the parent session's model, or undefined when disabled/unavailable. */
+/** Create a memoized arbiter bound to the supplied model services, or undefined when disabled/unavailable. */
 export function createTaskMutationArbiter(
-	ctx: ExtensionContext,
+	ctx: ArbiterModelContext,
 	options?: TaskMutationArbiterOptions,
 ): TaskMutationArbiter | undefined {
 	if (process.env.PI_SUBAGENTS_LLM_INTENT_ARBITER === "0") return undefined;
@@ -244,7 +254,7 @@ export function createTaskMutationArbiter(
 		const cached = cache.get(key);
 		if (cached) return cached;
 		const auth = await resolveArbiterAuth(ctx, runtime.model);
-		const verdict = await runArbitration(runtime, auth, task);
+		const verdict = auth ? await runArbitration(runtime, auth, task) : "unavailable";
 		if (cache.size > 200) cache.clear();
 		cache.set(key, verdict);
 		return verdict;

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

@@ -1,4 +1,4 @@
-import { splitKnownThinkingSuffix, type ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
+import { splitKnownThinkingSuffix as splitThinkingSuffix, type ModelInfo as AvailableModelInfo } from "../../shared/model-info.ts";
 import type { Usage } from "../../shared/types.ts";
 import { filterFallbackCandidates, findModelExclusion, parseModelKey, recordModelFailure } from "./model-exclusions.ts";
 import { checkModelScope, type ModelScopeCheckRule, type ModelScopeViolation, type ModelSource } from "./model-scope.ts";
@@ -14,9 +14,7 @@ interface ModelAttemptSummary {
 	usage?: Usage;
 }
 
-export function splitThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
-	return splitKnownThinkingSuffix(model);
-}
+export { splitThinkingSuffix };
 
 /** Aliases apply only to the resolved launch candidate (without its thinking suffix) and the exact raw response ID. */
 export function formatSubagentModelVerificationError(
@@ -38,7 +36,7 @@ export function formatSubagentModelVerificationError(
 		const expectedFullIdLeaf = expectedEntry.fullId.slice(expectedEntry.fullId.lastIndexOf("/") + 1);
 		if (expectedIdLeaf === observedBase || expectedFullIdLeaf === observedBase) return undefined;
 	}
-	return `model_verification_failed: child reported a different model than the launch candidate. Expected '${expectedModel}' but observed '${observedModel}'.`;
+	return `model_verification_failed: native Pi child reported a different model than the launch candidate. Expected '${expectedModel}' but observed '${observedModel}'. If you have independently verified this response ID identifies the requested model, declare the exact mapping in modelResponseAliases in ~/.pi/agent/extensions/subagent/config.json (see docs/configuration.md#modelresponsealiases). Use the resolved provider/model ID without its thinking suffix as the key. This leaves the outgoing request unchanged. Configuration changes affect new independent native runs; resumed native runs retain their launch-time declaration. External CLI adapters do not use this setting.`;
 }
 
 /** Sentinel model value requesting that a subagent inherit the parent session's model. */
@@ -537,6 +535,7 @@ export function buildModelCandidates(
 }
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [
+	/^REQUEST_LIMIT_EXCEEDED$/,
 	/rate\s*limit/i,
 	/usage\s*limit/i,
 	/too many requests/i,
@@ -544,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,
@@ -608,8 +609,13 @@ export function isRetryableModelFailureAttempt(input: { error: string | undefine
 	return Boolean(error && input.messages?.some((message) => messageError(message)?.trim() === error));
 }
 
+// Request-shape failures can match broad fallback signals such as "upstream",
+// but do not establish that the model is unhealthy for subsequent requests.
+const REQUEST_SHAPE_FAILURE_PATTERN = /\b(?:bad[ _]request|invalid[ _]argument|invalid_request_error)\b/i;
+
 export function recordRetryableModelFailure(model: string | undefined, error: string | undefined): void {
-	if (!model || !isRetryableModelFailure(error)) return;
+	if (!model || !error || !isRetryableModelFailure(error) || isContextOverflow(error)) return;
+	if (REQUEST_SHAPE_FAILURE_PATTERN.test(error)) return;
 	const { provider, modelId } = parseModelKey(model);
 	recordModelFailure({ modelId, reason: error, ...(provider ? { provider } : {}) });
 }