pi-subagents 0.66.0 → 0.68.0

package/src/runs/shared/{model-fallback.ts → model-resolution.ts}

@@ -1,17 +1,11 @@
 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";
-import { redactSecretValues } from "./permissions.ts";
 
 export type { AvailableModelInfo };
 
-interface ModelAttemptSummary {
-	model: string;
-	success: boolean;
-	exitCode?: number | null;
-	error?: string;
-	usage?: Usage;
+export interface ModelSelectionEvidence {
+	model?: string;
+	requestedModel?: string;
 }
 
 export { splitThinkingSuffix };
@@ -290,57 +284,6 @@ function enforceModelScopes(
 	for (const violation of violations) (onWarn ?? defaultScopeWarn)(violation);
 }
 
-const MODEL_EXCLUSION_DIAGNOSTIC_MAX_LENGTH = 240;
-const MODEL_EXCLUSION_DIAGNOSTIC_MAX_ENTRIES = 20;
-
-function sanitizeModelExclusionDiagnostic(value: string | undefined, fallback: string): string {
-	const normalized = typeof value === "string"
-		? value.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").trim()
-		: "";
-	return redactSecretValues(normalized || fallback).slice(0, MODEL_EXCLUSION_DIAGNOSTIC_MAX_LENGTH);
-}
-
-function formatModelExclusionExpiry(expiresAt: number): string {
-	if (!Number.isFinite(expiresAt)) return "unknown";
-	const date = new Date(expiresAt);
-	return Number.isNaN(date.getTime()) ? "unknown" : date.toISOString();
-}
-
-function formatExcludedCandidateEvidence(candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>): string {
-	const { provider, modelId } = parseModelKey(candidate);
-	const displayCandidate = sanitizeModelExclusionDiagnostic(candidate, "unknown");
-	const displayModel = sanitizeModelExclusionDiagnostic(modelId, "unknown");
-	const displayProvider = sanitizeModelExclusionDiagnostic(provider ?? exclusion.provider, "unspecified");
-	const reason = sanitizeModelExclusionDiagnostic(exclusion.reason, "runtime-failure");
-	return `${displayCandidate} — model: ${displayModel}; provider: ${displayProvider}; reason: ${reason}; expires: ${formatModelExclusionExpiry(exclusion.expiresAt)}`;
-}
-
-const MODEL_UNAVAILABLE_EXCLUSION_PATTERNS = [
-	/model.*not found/i,
-	/unknown model/i,
-	/model.*unavailable/i,
-	/model.*disabled/i,
-];
-
-function isCurrentRegistryModel(candidate: string, availableModels: AvailableModelInfo[] | undefined): boolean {
-	if (!availableModels || availableModels.length === 0) return false;
-	const { baseModel } = splitThinkingSuffix(candidate);
-	return availableModels.some((entry) => entry.fullId === baseModel);
-}
-
-function ignoreStaleModelUnavailableExclusion(candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>, availableModels: AvailableModelInfo[] | undefined): boolean {
-	const reason = exclusion.reason ?? "";
-	return MODEL_UNAVAILABLE_EXCLUSION_PATTERNS.some((pattern) => pattern.test(reason)) && isCurrentRegistryModel(candidate, availableModels);
-}
-
-function throwForExplicitModelExclusion(model: string): void {
-	const exclusion = findModelExclusion(model);
-	if (!exclusion) return;
-	const reason = redactSecretValues((exclusion.reason ?? "runtime-failure").replace(/[\u0000-\u001f\u007f]+/g, " ")).slice(0, 240);
-	const expiry = Number.isFinite(exclusion.expiresAt) ? `; expires: ${new Date(exclusion.expiresAt).toISOString()}` : "";
-	throw new Error(`Requested subagent model '${model}' is excluded and cannot be replaced by a fallback (reason: ${reason}${expiry}).`);
-}
-
 /**
  * Resolve the `--model` override passed to a spawned subagent.
  *
@@ -377,7 +320,6 @@ export function resolveSubagentModelOverride(
 		const candidate = resolveSubagentModelCandidate(explicit, availableModels, preferredProvider);
 		if (options?.source === "explicit") {
 			resolved = candidate ?? resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
-			throwForExplicitModelExclusion(resolved);
 			resolvedFromRegistry = true;
 		} else if (candidate) {
 			resolved = candidate;
@@ -421,19 +363,15 @@ export function resolveEffectiveSubagentModel(
 
 export type ModelOrigin = ModelSource | "configured";
 
-export interface BuildModelCandidatesOptions {
-	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
+export interface ResolveModelSelectionOptions {
 	scope?: ModelScopeCheckRule | ModelScopeCheckRule[];
 	onWarn?: (violation: ModelScopeViolation) => void;
 	/** The primary model came from the running parent session, not configuration. */
 	primaryModelFromParent?: boolean;
-	/** How the primary model was selected. Explicit stays strict and does not rotate to fallbacks. */
+	/** How the model was selected. */
 	origin?: ModelOrigin;
 }
 
-const ZERO_USABLE_MODEL_CANDIDATES_ERROR =
-	"No usable subagent models remain after registry, scope, and cached-exclusion filtering.";
-
 export function resolveModelOrigin(input: {
 	explicitModel?: string | boolean;
 	agentModel?: string | boolean;
@@ -458,174 +396,30 @@ export function inheritsParentModel(
 	return Boolean(parentModel && (!trimmed || trimmed === INHERIT_MODEL));
 }
 
-export function buildModelCandidates(
-	primaryModel: string | undefined,
-	fallbackModels: string[] | undefined,
+export function resolveModelSelection(
+	model: string | undefined,
 	availableModels: AvailableModelInfo[] | undefined,
 	preferredProvider?: string,
-	options?: BuildModelCandidatesOptions,
-): string[] {
-	if (!primaryModel) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
+	options?: ResolveModelSelectionOptions,
+): ModelSelectionEvidence {
+	if (!model) throwForUnresolvedEnforcedInheritScope(options?.scope, true);
 	const origin = options?.origin ?? (options?.primaryModelFromParent ? "inherited" : "configured");
+	const requestedModel = origin === "inherited" ? undefined : model;
 	const scopes = configuredScopes(options?.scope);
-	type ExcludedCandidate = { candidate: string; exclusion: NonNullable<ReturnType<typeof findModelExclusion>> };
-	const excludedCandidates: ExcludedCandidate[] = [];
-	let excludedCandidateCount = 0;
-	const warnCachedExclusion = (candidate: string, exclusion: NonNullable<ReturnType<typeof findModelExclusion>>) => {
-		excludedCandidateCount++;
-		if (excludedCandidates.length < MODEL_EXCLUSION_DIAGNOSTIC_MAX_ENTRIES) excludedCandidates.push({ candidate, exclusion });
-		const displayCandidate = sanitizeModelExclusionDiagnostic(candidate, "unknown");
-		const reason = sanitizeModelExclusionDiagnostic(exclusion.reason, "runtime-failure");
-		console.warn(`[pi-subagents] Skipping model '${displayCandidate}' due to a cached exclusion (reason: ${reason}; expires: ${formatModelExclusionExpiry(exclusion.expiresAt)}).`);
-	};
-	if (origin === "explicit" && primaryModel) {
-		const normalized = resolveRequiredSubagentModelCandidate(primaryModel.trim(), availableModels, preferredProvider);
-		throwForExplicitModelExclusion(normalized);
+	if (origin === "explicit" && model) {
+		const normalized = resolveRequiredSubagentModelCandidate(model.trim(), availableModels, preferredProvider);
 		enforceModelScopes(normalized, scopes, "explicit", options?.onWarn);
-		primaryModel = normalized;
-	}
-	const seen = new Set<string>();
-	const candidates: string[] = [];
-	const rawCandidates = [primaryModel, ...(fallbackModels ?? [])];
-	let skippedPrimary: string | undefined;
-	let skippedFallback: string | undefined;
-	for (let index = 0; index < rawCandidates.length; index++) {
-		const raw = rawCandidates[index];
-		if (!raw) continue;
-		const model = raw.trim();
-		const normalized = index === 0 && (origin === "inherited" || origin === "explicit" || options?.primaryModelFromParent)
-			? model
-			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
-		if (!normalized) {
-			if (index === 0) skippedPrimary = model;
-			else {
-				skippedFallback ??= model;
-				console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
-			}
-			continue;
-		}
-		if (seen.has(normalized)) continue;
-		if (index > 0 || scopes.some((scope) => scope.enforce === true && scope.strict === true)) {
-			enforceModelScopes(normalized, scopes, "inherited", options?.onWarn);
-		}
-		seen.add(normalized);
-		candidates.push(normalized);
-	}
-	const resolved = filterFallbackCandidates(candidates, {
-		onExcluded: warnCachedExclusion,
-		ignoreExclusion: (candidate, exclusion) => ignoreStaleModelUnavailableExclusion(candidate, exclusion, availableModels),
-	});
-	if (resolved.length === 0) {
-		if (skippedPrimary) resolveRequiredSubagentModelCandidate(skippedPrimary, availableModels, preferredProvider);
-		if (candidates.length === 0 && skippedFallback) resolveRequiredSubagentModelCandidate(skippedFallback, availableModels, preferredProvider);
-		if (candidates.length > 0) {
-			const shownExclusions = excludedCandidates;
-			const omittedExclusions = excludedCandidateCount - shownExclusions.length;
-			const evidence = shownExclusions.length > 0
-				? ` (excluded: ${shownExclusions.map(({ candidate, exclusion }) => formatExcludedCandidateEvidence(candidate, exclusion)).join("; ")}${omittedExclusions > 0 ? `; ... and ${omittedExclusions} more` : ""})`
-				: "";
-			throw new Error(`${ZERO_USABLE_MODEL_CANDIDATES_ERROR}${evidence}`);
-		}
-		return resolved;
+		model = normalized;
 	}
-	if (skippedPrimary) {
-		console.warn(`[pi-subagents] Skipping primary model '${skippedPrimary}' because it is unavailable in this environment.`);
+	const resolved = model && (origin === "inherited" || origin === "explicit" || options?.primaryModelFromParent)
+		? model.trim()
+		: model ? resolveRequiredSubagentModelCandidate(model.trim(), availableModels, preferredProvider) : undefined;
+	if (resolved && scopes.some((scope) => scope.enforce === true && scope.strict === true)) {
+		enforceModelScopes(resolved, scopes, "inherited", options?.onWarn);
 	}
-	return resolved;
-}
-
-const RETRYABLE_MODEL_FAILURE_PATTERNS = [
-	/^REQUEST_LIMIT_EXCEEDED$/,
-	/rate\s*limit/i,
-	/usage\s*limit/i,
-	/too many requests/i,
-	/\b429\b/,
-	/quota/i,
-	/billing/i,
-	/credit/i,
-	/auth(?:entication)?/i,
-	/unauthori[sz]ed/i,
-	/forbidden/i,
-	/api key/i,
-	/token expired/i,
-	/invalid key/i,
-	/provider.*unavailable/i,
-	/model.*unavailable/i,
-	/model.*disabled/i,
-	/model.*not found/i,
-	/unknown model/i,
-	/overloaded/i,
-	/service unavailable/i,
-	/temporar(?:ily)? unavailable/i,
-	/connection\s+(?:error|reset|closed|aborted)/i,
-	/connection refused/i,
-	/fetch failed/i,
-	/network error/i,
-	/socket hang up/i,
-	/stream ended without finish_reason/i,
-	/upstream/i,
-	/timed? out/i,
-	/timeout/i,
-	/\b500\b/,
-	/\b502\b/,
-	/\b503\b/,
-	/\b504\b/,
-	/internal server error/i,
-	/cold.?start/i,
-	/empty response/i,
-	/no output/i,
-	/model.*(?:load|fail|error)/i,
-];
-
-/**
- * Failures reported as `<tool> failed (exit N): ...` or `<tool> failed with
- * exit code N` come from a tool call inside the child's task, not from the
- * provider/model, however network-flavored their details read. Retrying a
- * different model cannot fix them and would rerun the whole task. Tool names
- * include namespaced forms like `mcp.server/write`.
- */
-const TOOL_FAILURE_PREFIX = /^[\w.:@/-]+ failed (?:(?:\(exit \d+\):)|(?:with exit code \d+))(?:\s|$)/i;
-
-export function isRetryableModelFailure(error: string | undefined): boolean {
-	if (!error) return false;
-	if (TOOL_FAILURE_PREFIX.test(error.trim())) return false;
-	return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
-}
-
-function messageError(message: unknown): string | undefined {
-	if (!message || typeof message !== "object") return undefined;
-	const value = (message as { errorMessage?: unknown }).errorMessage;
-	return typeof value === "string" ? value : undefined;
-}
-
-export function isRetryableModelFailureAttempt(input: { error: string | undefined; messages?: readonly unknown[]; toolCount?: number }): boolean {
-	if (!isRetryableModelFailure(input.error)) return false;
-	if ((input.toolCount ?? 0) > 0) return false;
-	if (input.error === "Subagent produced no output (possible model cold-start or empty response)." || /^Subagent produced no output after terminal assistant stopReason "[^"]+"\.$/.test(input.error ?? "")) return true;
-	if ((input.toolCount ?? 0) === 0 && (input.messages?.length ?? 0) === 0) return true;
-	const error = input.error?.trim();
-	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 || !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 } : {}) });
+	return { ...(resolved ? { model: resolved } : {}), ...(requestedModel ? { requestedModel } : {}) };
 }
-
-/**
- * Context-overflow signals. These are deliberately NOT part of
- * {@link RETRYABLE_MODEL_FAILURE_PATTERNS}: an overflow means the input was too
- * large for the model's context window, so retrying the same input on another
- * model (or the same model again) cannot succeed. Callers should treat overflow
- * as a terminal, non-retryable failure and surface a clear "input too large"
- * error instead of burning fallback attempts on a guaranteed failure.
- */
+/** Context-overflow signals used to surface a clear input-too-large error. */
 const CONTEXT_OVERFLOW_PATTERNS = [
 	/context(?: length| window| limit)? (?:exceed|overflow|too long)/i,
 	/maximum context length/i,
@@ -642,13 +436,6 @@ const CONTEXT_OVERFLOW_PATTERNS = [
 
 export function isContextOverflow(error: string | undefined): boolean {
 	if (!error) return false;
-	if (TOOL_FAILURE_PREFIX.test(error.trim())) return false;
+	if (/^[\w.:@/-]+ failed (?:(?:\(exit \d+\):)|(?:with exit code \d+))(?:\s|$)/i.test(error.trim())) return false;
 	return CONTEXT_OVERFLOW_PATTERNS.some((pattern) => pattern.test(error));
 }
-
-export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
-	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
-	return nextModel
-		? `[fallback] ${attempt.model} failed: ${failure}. Retrying with ${nextModel}.`
-		: `[fallback] ${attempt.model} failed: ${failure}.`;
-}

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

@@ -17,7 +17,7 @@ import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 
 export interface ModelScopeRule {
 	enforce?: boolean;
-	/** Reject inherited and fallback models outside the allowlist instead of warning. */
+	/** Reject inherited models outside the allowlist instead of warning. */
 	strict?: boolean;
 	/** Glob-style allow patterns (only `*` is special), matched against `provider/id`. */
 	allow?: string[];

package/src/runs/shared/nested-events.ts

@@ -232,10 +232,12 @@ function sanitizeLaunchResolvedExtensions(value: unknown): LaunchResolvedChildEx
 		disableAmbientExtensions: raw.disableAmbientExtensions,
 		runtime: stringList(raw.runtime),
 		configured: stringList(raw.configured),
+		required: Array.isArray(raw.required) ? raw.required.filter((item): item is string => typeof item === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(item)).slice(0, 32) : [],
 		effective: stringList(raw.effective),
 		omitted: {
 			runtime: omittedCount("runtime"),
 			configured: omittedCount("configured"),
+			required: omittedCount("required"),
 			effective: omittedCount("effective"),
 		},
 	};
@@ -1063,8 +1065,15 @@ export function isTopLevelAsyncDir(asyncDir: string): boolean {
 	return containedPath(DIRS.async, resolved) && !containedPath(path.join(TEMP_ROOT_DIR, "nested-subagent-runs"), resolved);
 }
 
-export function nestedResultsPath(rootRunId: string, id: string): string {
+export function nestedRunScope(rootRunId: string) {
 	assertSafeId("rootRunId", rootRunId);
+	return {
+		asyncDirRoot: path.join(TEMP_ROOT_DIR, "nested-subagent-runs", rootRunId),
+		resultsDir: path.join(DIRS.results, "nested", rootRunId),
+	};
+}
+
+export function nestedResultsPath(rootRunId: string, id: string): string {
 	assertSafeId("id", id);
-	return path.join(DIRS.results, "nested", rootRunId, `${id}.json`);
+	return path.join(nestedRunScope(rootRunId).resultsDir, `${id}.json`);
 }

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/parallel-utils.ts

@@ -10,6 +10,10 @@ export interface RunnerSubagentStep {
 	sessionName?: string;
 	task: string;
 	runner?: ResolvedRunnerConfig;
+	/** Herdr saved machine this external-cli step runs on; `cwd` is then the directory on that machine. */
+	machine?: import("../../shared/types.ts").HerdrMachineReference;
+	remoteReads?: string[] | false;
+	machineEnv?: Record<string, string>;
 	externalJobFollowUp?: {
 		sourceRunId: string;
 		sourceStepIndex: number;
@@ -37,7 +41,7 @@ export interface RunnerSubagentStep {
 	fast?: boolean;
 	thinking?: string;
 	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
-	modelCandidates?: string[];
+	requestedModel?: string;
 	/** The primary model is inherited from the parent session and should not be verified against the child-reported active registry model. */
 	skipPrimaryModelVerification?: boolean;
 	modelVerificationRegistry?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
@@ -47,6 +51,8 @@ export interface RunnerSubagentStep {
 	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
+	/** Private immutable host policy snapshot serialized to the native runner. */
+	requiredExtensions?: import("../../shared/required-child-extensions.ts").RequiredChildExtensionSnapshot;
 	mcpDirectTools?: string[];
 	mutationTools?: string[];
 	completionGuard?: boolean;
@@ -237,7 +243,6 @@ export interface ParallelTaskResult {
 	error?: string;
 	timedOut?: boolean;
 	model?: string;
-	attemptedModels?: string[];
 	outputTargetPath?: string;
 	outputTargetExists?: boolean;
 }

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 || !/^(?:\/\$bunfs\/|B:[\\/]~BUN[\\/])/.test(entry)) 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

@@ -17,6 +17,7 @@ import { registerChildWatchdog } from "../../watchdog/register-child.ts";
 import type { ChildWatchdogConfig } from "../../watchdog/child-status.ts";
 import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
 import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
+import { inheritedNestedRouteOf } from "./nested-events.ts";
 import { registerWaitTool } from "../background/wait-tool.ts";
 import { drainOutstandingWork } from "../background/auto-drain.ts";
 import {
@@ -451,10 +452,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(),
@@ -465,7 +467,8 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
 		watcherRestartTimer: null,
 		resultFileCoalescer: { schedule: () => false, clear: () => {} },
 	} as unknown as SubagentState;
-	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs);
+	const nestedRootRunId = inheritedNestedRouteOf(config)?.rootRunId;
+	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, config.waitTool.enabled, undefined, config.waitTool.defaultTimeoutMs, { nestedRootRunId });
 	const supervisorMetadata = childSupervisorMetadata(config);
 	let nativeSupervisorClientRegistered = false;
 	const registerNativeSupervisorClientOnce = (): void => {
@@ -486,13 +489,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, nestedRootRunId, hasPendingSupervisorRequest: config.hasPendingSupervisorRequest }, drainObservation);
+		} finally {
+			config.holdFinalDrain?.(false);
+		}
 	});
 	if (config.structuredOutput) registerStructuredOutputTool(pi, config.structuredOutput);
 

package/src/runs/shared/task-intent.ts

@@ -7,6 +7,7 @@
  * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
  *   task REQUIRE file changes? Consumed by the completion mutation guard,
  *   which blocks completion, so its vocabulary is deliberately narrow.
+ *   Verbs inside filenames and path-like tokens do not count.
  * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
  *   acceptance level inference, which only raises evidence gates, so its
  *   vocabulary is deliberately broad (any bare write verb).
@@ -18,16 +19,20 @@
  */
 
 const REVIEW_ONLY_PATTERNS = [
-	/\breview only\b/i,
+	/\b(?:review|read)[- ]only\b/i,
+	/\bno\s+(?:source\s+)?edits?\b/i,
+	/\bwithout\s+edits?\b/i,
 	/\bsuggest fixes only\b/i,
 	/\bonly return findings\b/i,
 	/\breturn findings only\b/i,
 ];
 
+const NO_EDIT_BOUNDARY_ASSERTION_PATTERN = /\bno\s+(?:source\s+)?edits?\s*,\s*(?:commits?|pushes?|merges?|installs?|changes?|writes?)\b/i;
+
 const REVIEWER_REQUIRED_EDIT_PATTERNS = [
 	/\bmust\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
 	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
-	/(?:^|[.!?\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
+	/(?:^|[.!?:;,\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
 	/\bregardless\s+of\s+findings\b/i,
 	/\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
 	/\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
@@ -40,7 +45,7 @@ const REVIEWER_REQUIRED_EDIT_PATTERNS = [
 // being swallowed as the object.
 // Accept serialized line separators too: workflow prompts can carry literal
 // `\\n`/`\\r\\n` between clauses instead of decoded newlines.
-const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
+const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change|implement)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
 const COORDINATED_NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+((?=(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b)(?:(?!\\(?:r\\n|n))[^.;:!?\n–—-])*?\b(?:and|or)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b(?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
 
 /** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
@@ -85,13 +90,25 @@ const RESEARCH_AGENT_PATTERNS = [
 // CLI flags like "--fix" and genuine clause-level dashes like "branch—fix it"),
 // strip the known severity compounds (must|should|needs + dash + verb) from the
 // task text before matching. Dash coverage: ASCII hyphen + U+2010..U+2015.
-const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[\-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
+const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
 
 function stripSeverityCompounds(task: string): string {
 	return task.replace(SEVERITY_COMPOUND_PATTERN, " ");
 }
 export { stripSeverityCompounds };
 
+// Quoted categories in a finding-classification request describe fixes, not
+// instructions to perform them. Strip only that request, leaving sibling
+// imperatives (including another "must fix") subject to the normal guards.
+const FINDING_CLASSIFICATION_PATTERN = /\b(?:classify|categorize|weigh)\s+(?:(?:the|remaining)\s+)*(?:findings?|items?|issues?)\s+as\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]\s+(?:vs\.?|versus)\s+["“]must\s+fix\s+before\s+[^"”\n]+["”]/gi;
+
+const PATH_LIKE_TOKEN_PATTERN = /[^\s]+[/\\][^\s]+|[^\s/\\]+\.[A-Za-z][A-Za-z0-9]{0,9}\b/g;
+const PATH_INTERNAL_IMPLEMENTATION_VERB = /\b(?:implement|edit|modify|refactor|delete|update|add|remove|replace|create)\b/i;
+
+function stripPathLikeTokens(task: string): string {
+	return task.replace(PATH_LIKE_TOKEN_PATTERN, (token) => (PATH_INTERNAL_IMPLEMENTATION_VERB.test(token) ? " " : token));
+}
+
 const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
 
 const WORKER_IMPLEMENTATION_PATTERNS = [
@@ -103,12 +120,18 @@ const WORKER_IMPLEMENTATION_PATTERNS = [
 	/\bdo those fixes\b/i,
 ];
 
-const GENERAL_IMPLEMENTATION_PATTERNS = [
+const FOLLOW_ON_IMPLEMENTATION_PATTERN = /(?:^|[.!?:;,\n])\s*(?:fix|patch|update|add|remove|replace|create|delete)\s+(?:(?:the|a|an|this|that|these|those|requested|specified|current|existing|approved|your|our)\s+)(?!(?:report|summary|findings?|analysis|recommendations?|answer|response|proposal|plan|issue|bug report)\b)[a-z][\w./-]*/i;
+const ADVISORY_INFINITIVE_PATTERN = /\b(?:explain|recommend|describe)\s+how\s+to\s+(?:fix|patch|update|add|remove|replace|create|delete|implement|edit|modify|refactor)\b/i;
+const EXPLICIT_IMPLEMENTATION_PATTERNS = [
 	/\b(?:implement|edit|modify|refactor)\b/i,
-	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
 	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
 	/\bmake\s+(?:the\s+)?changes\b/i,
 	/\bdo those fixes\b/i,
+];
+
+const GENERAL_IMPLEMENTATION_PATTERNS = [
+	...EXPLICIT_IMPLEMENTATION_PATTERNS,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
 	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
 ];
 
@@ -141,10 +164,13 @@ interface NoEditProhibitionAnalysis {
 }
 
 function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis {
+	const readOnlyBoundary = NO_EDIT_BOUNDARY_ASSERTION_PATTERN.test(taskText);
 	let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
-		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
-	let blanket = present;
-	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
+		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText))
+		|| readOnlyBoundary;
+	let blanket = false;
+	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS, ADVISORY_INFINITIVE_PATTERN]);
+	if (readOnlyBoundary) strippedText = stripPatterns(strippedText, [NO_EDIT_BOUNDARY_ASSERTION_PATTERN]);
 	const stripNoEditProhibition = (match: string, object: string, offset: number, source: string): string => {
 		present = true;
 		if (GENERIC_PROHIBITION_OBJECT.test(object) && !hasScopedProhibitionContinuation(source.slice(offset + match.length))) blanket = true;
@@ -172,16 +198,23 @@ function hasImplementationIntent(agent: string, taskText: string): boolean {
 }
 
 export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
-	const taskText = stripSeverityCompounds(stripFrameworkInstructions(task));
+	const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN]);
 	const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
 	const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
 	if (prohibitions.present) {
 		if (prohibitions.blanket) return { kind: "read-only" };
-		return hasImplementationIntent(agent, prohibitions.strippedText) ? { kind: "implementation" } : { kind: "read-only" };
+		const remaining = stripPathLikeTokens(prohibitions.strippedText);
+		if (isReviewerStyleAgent(agent)) {
+			return hasImplementationIntent(agent, remaining) ? { kind: "implementation" } : { kind: "read-only" };
+		}
+		return EXPLICIT_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(remaining))
+			|| FOLLOW_ON_IMPLEMENTATION_PATTERN.test(remaining)
+			? { kind: "implementation" }
+			: { kind: "read-only" };
 	}
 
 	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
-	if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
+	if (hasImplementationIntent(agent, stripPathLikeTokens(taskText))) return { kind: "implementation" };
 	if (isReviewerStyleAgent(agent)) return { kind: "read-only" };
 	return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
 }
@@ -204,7 +237,7 @@ const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|mig
  * does.
  */
 export function taskMayMutate(task: string): boolean {
-	const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const taskText = stripPatterns(stripSeverityCompounds(stripFrameworkInstructions(task)), [FINDING_CLASSIFICATION_PATTERN, ...SCOPED_NO_EDIT_CONSTRAINT_PATTERNS]);
 	const prohibitions = analyzeNoEditProhibitions(taskText);
 	if (prohibitions.blanket) return false;
 	return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));

package/src/runs/shared/workflow-async-child-guidance.ts

@@ -0,0 +1,18 @@
+import type { AsyncStatus, SubagentState } from "../../shared/types.ts";
+
+/** Projection-only guidance, not a control route or proof of current child liveness. */
+export function workflowAsyncChildSteeringGuidance(status: AsyncStatus, state?: SubagentState): string[] {
+	if (status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")
+		|| !state?.currentSessionId || status.sessionId !== state.currentSessionId
+		|| !state.workflowControllers?.has(status.runId)) return [];
+	const ids = new Set((status.steps ?? []).flatMap((step) =>
+		step.async === true && step.status === "running"
+		&& step.runner?.type !== "external-cli" && step.runner?.type !== "external-job"
+		&& typeof step.runId === "string" && /^[A-Za-z0-9_-]+$/.test(step.runId) && step.runId !== status.runId
+			? [step.runId] : []));
+	if (ids.size === 0) return [];
+	return [
+		"Async children recorded as running; direct steering rechecks controls. Choose an exact child ID (queued does not mean consumed):",
+		...[...ids].map((id) => `  subagent({ action: "steer", id: "${id}", mode: "follow_up", message: "..." })`),
+	];
+}