pi-subagents 0.50.0 → 0.52.0

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

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ExternalJobProviderError, type ExternalJobHandle, type ExternalJobResult, type ExternalJobState } from "../../api/external-job-provider.ts";
+import type { ExternalJobStatus } from "../../shared/types.ts";
+import { requestExternalJobOperation } from "./external-job-bridge.ts";
+
+const STATUS_POLL_INTERVAL_MS = 1_000;
+
+export interface ExternalJobRunResult {
+	output: string;
+	exitCode: number;
+	error?: string;
+	timedOut?: boolean;
+	stopped?: boolean;
+	externalJob: ExternalJobStatus;
+}
+
+export function externalJobPromptDigest(prompt: string): string {
+	return createHash("sha256").update(prompt).digest("hex");
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function terminal(state: ExternalJobState): boolean {
+	return state === "completed" || state === "failed" || state === "stopped" || state === "blocked";
+}
+
+function formatError(error: ExternalJobProviderError, provider: string): string {
+	const blocking = error.blockingJobId ? ` Blocking provider job: ${error.blockingJobId}.` : "";
+	return `External-job provider '${provider}' failed closed (${error.code}): ${error.message}.${blocking}`;
+}
+
+function isNotFound(error: unknown): boolean {
+	return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function malformedStatus(statusPath: string): ExternalJobProviderError {
+	return new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable" });
+}
+
+function parseExternalJobStatus(value: unknown, statusPath: string): ExternalJobStatus {
+	if (!isRecord(value)) throw malformedStatus(statusPath);
+	const provider = value.provider;
+	const promptDigest = value.promptDigest;
+	const state = value.state;
+	if (typeof provider !== "string" || provider.length === 0) throw malformedStatus(statusPath);
+	if (typeof promptDigest !== "string" || promptDigest.length === 0) throw malformedStatus(statusPath);
+	if (state !== "queued" && state !== "running" && state !== "completed" && state !== "failed" && state !== "stopped" && state !== "blocked") throw malformedStatus(statusPath);
+	if (value.options !== undefined && !isRecord(value.options)) throw malformedStatus(statusPath);
+	const providerJobId = value.providerJobId;
+	const handleUrl = value.handleUrl;
+	const conversationUrl = value.conversationUrl;
+	const resultArtifactPath = value.resultArtifactPath;
+	const failureCode = value.failureCode;
+	const failureMessage = value.failureMessage;
+	const blockingJobId = value.blockingJobId;
+	const startedAt = value.startedAt;
+	const updatedAt = value.updatedAt;
+	if (providerJobId !== undefined && (typeof providerJobId !== "string" || providerJobId.length === 0)) throw malformedStatus(statusPath);
+	if (handleUrl !== undefined && typeof handleUrl !== "string") throw malformedStatus(statusPath);
+	if (conversationUrl !== undefined && typeof conversationUrl !== "string") throw malformedStatus(statusPath);
+	if (resultArtifactPath !== undefined && typeof resultArtifactPath !== "string") throw malformedStatus(statusPath);
+	if (failureCode !== undefined && typeof failureCode !== "string") throw malformedStatus(statusPath);
+	if (failureMessage !== undefined && typeof failureMessage !== "string") throw malformedStatus(statusPath);
+	if (blockingJobId !== undefined && typeof blockingJobId !== "string") throw malformedStatus(statusPath);
+	if (startedAt !== undefined && typeof startedAt !== "number") throw malformedStatus(statusPath);
+	if (updatedAt !== undefined && typeof updatedAt !== "number") throw malformedStatus(statusPath);
+	return {
+		provider,
+		promptDigest,
+		options: value.options ?? {},
+		state,
+		...(providerJobId ? { providerJobId } : {}),
+		...(handleUrl ? { handleUrl } : {}),
+		...(conversationUrl ? { conversationUrl } : {}),
+		...(resultArtifactPath ? { resultArtifactPath } : {}),
+		...(failureCode ? { failureCode } : {}),
+		...(failureMessage ? { failureMessage } : {}),
+		...(blockingJobId ? { blockingJobId } : {}),
+		...(startedAt !== undefined ? { startedAt } : {}),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+	};
+}
+
+function readExistingExternalJob(asyncDir: string, stepIndex: number): ExternalJobStatus | undefined {
+	const statusPath = path.join(asyncDir, "status.json");
+	let raw: string;
+	try {
+		raw = fs.readFileSync(statusPath, "utf-8");
+	} catch (error) {
+		if (isNotFound(error)) return undefined;
+		throw new ExternalJobProviderError(`Unreadable external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+	}
+	if (!isRecord(parsed) || !Array.isArray(parsed.steps)) throw malformedStatus(statusPath);
+	const step = parsed.steps[stepIndex];
+	if (step === undefined || !isRecord(step)) throw malformedStatus(statusPath);
+	if (step.externalJob === undefined) return undefined;
+	return parseExternalJobStatus(step.externalJob, statusPath);
+}
+
+function statusFromHandle(input: {
+	provider: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	startedAt?: number;
+	previous?: ExternalJobStatus;
+	handle: ExternalJobHandle;
+	resultArtifactPath?: string;
+}): ExternalJobStatus {
+	return {
+		provider: input.provider,
+		providerJobId: input.handle.providerJobId,
+		promptDigest: input.promptDigest,
+		options: input.options,
+		handleUrl: input.handle.handleUrl ?? input.previous?.handleUrl,
+		conversationUrl: input.handle.conversationUrl ?? input.previous?.conversationUrl,
+		resultArtifactPath: input.resultArtifactPath ?? input.previous?.resultArtifactPath,
+		state: input.handle.state,
+		failureCode: input.handle.failureCode,
+		failureMessage: input.handle.failureMessage,
+		blockingJobId: input.handle.blockingJobId,
+		startedAt: input.previous?.startedAt ?? input.startedAt,
+		updatedAt: Date.now(),
+	};
+}
+
+function failureStatus(input: {
+	provider: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	previous?: ExternalJobStatus;
+	code: string;
+	message: string;
+	blockingJobId?: string;
+}): ExternalJobStatus {
+	return {
+		provider: input.provider,
+		providerJobId: input.previous?.providerJobId,
+		promptDigest: input.promptDigest,
+		options: input.options,
+		handleUrl: input.previous?.handleUrl,
+		conversationUrl: input.previous?.conversationUrl,
+		resultArtifactPath: input.previous?.resultArtifactPath,
+		state: input.blockingJobId ? "blocked" : "failed",
+		failureCode: input.code,
+		failureMessage: input.message,
+		blockingJobId: input.blockingJobId,
+		startedAt: input.previous?.startedAt,
+		updatedAt: Date.now(),
+	};
+}
+
+function resultOutput(result: ExternalJobResult, artifactPath: string | undefined): string {
+	if (result.output?.trim()) return result.output.trim();
+	if (artifactPath) return `External job finished. Result artifact: ${artifactPath}`;
+	return "External job finished without text output.";
+}
+
+function blocksStartRedispatch(status: ExternalJobStatus, provider: string, promptDigest: string): boolean {
+	return status.provider === provider
+		&& status.promptDigest === promptDigest
+		&& !status.providerJobId
+		&& status.failureCode !== "provider-unavailable";
+}
+
+export async function runExternalJob(input: {
+	provider: string;
+	options?: Record<string, unknown>;
+	cwd: string;
+	prompt: string;
+	asyncDir: string;
+	stepIndex: number;
+	runId: string;
+	agent: string;
+	sessionId?: string;
+	registerTimeout?: (stop: (() => void) | undefined) => void;
+	registerStop?: (stop: (() => void) | undefined) => void;
+	timeoutMessage?: string;
+	stopMessage?: string;
+	onExternalJob?: (status: ExternalJobStatus) => void;
+}): Promise<ExternalJobRunResult> {
+	const provider = input.provider;
+	const options = input.options ?? {};
+	const promptDigest = externalJobPromptDigest(input.prompt);
+	const startedAt = Date.now();
+	let timedOut = false;
+	let stopped = false;
+	let current: ExternalJobStatus | undefined;
+	const timeout = () => { timedOut = true; };
+	const stop = () => { stopped = true; };
+	input.registerTimeout?.(timeout);
+	input.registerStop?.(stop);
+	const publish = (status: ExternalJobStatus) => {
+		current = status;
+		input.onExternalJob?.(status);
+	};
+	const localCancellation = () => {
+		if (!timedOut && !stopped) return undefined;
+		const message = stopped
+			? input.stopMessage ?? `Subagent stopped locally before external provider '${provider}' returned a job id. The provider start may still be running.`
+			: input.timeoutMessage ?? `Subagent timed out locally before external provider '${provider}' returned a job id. The provider start may still be running.`;
+		return new ExternalJobProviderError(message, { code: stopped ? "local-stop" : "local-timeout" });
+	};
+	try {
+		current = readExistingExternalJob(input.asyncDir, input.stepIndex);
+		let handle: ExternalJobHandle;
+		if (current?.providerJobId) {
+			if (current.provider !== provider || current.promptDigest !== promptDigest) {
+				const message = `Existing external job '${current.providerJobId}' does not match provider or prompt digest. Refusing to redispatch prompt.`;
+				const status = failureStatus({ provider, promptDigest, options, previous: current, code: "recovery-mismatch", message });
+				publish(status);
+				return { output: message, exitCode: 1, error: message, externalJob: status };
+			}
+			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "reattach", provider, providerJobId: current.providerJobId });
+		} else {
+			if (current && blocksStartRedispatch(current, provider, promptDigest)) {
+				const message = `External-job start for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
+				const status = failureStatus({ provider, promptDigest, options, previous: current, code: "start-redispatch-blocked", message });
+				publish(status);
+				return { output: message, exitCode: 1, error: message, externalJob: status };
+			}
+			publish({ provider, promptDigest, options, state: "queued", startedAt, updatedAt: Date.now() });
+				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
+				operation: "start",
+				provider,
+				start: {
+					prompt: input.prompt,
+					promptDigest,
+					cwd: input.cwd,
+					runId: input.runId,
+					stepIndex: input.stepIndex,
+					agent: input.agent,
+					options,
+					...(input.sessionId ? { sessionId: input.sessionId } : {}),
+				},
+			}, undefined, localCancellation);
+		}
+		publish(statusFromHandle({ provider, promptDigest, options, startedAt, previous: current, handle }));
+		while (!terminal(handle.state)) {
+			if (timedOut || stopped) {
+				const message = stopped
+					? input.stopMessage ?? `Subagent stopped locally; external provider job '${handle.providerJobId}' may still be running.`
+					: input.timeoutMessage ?? `Subagent timed out locally; external provider job '${handle.providerJobId}' may still be running.`;
+				return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: current! };
+			}
+			await sleep(STATUS_POLL_INTERVAL_MS);
+			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "status", provider, providerJobId: handle.providerJobId });
+			publish(statusFromHandle({ provider, promptDigest, options, previous: current, handle }));
+		}
+		const result = await requestExternalJobOperation<ExternalJobResult>(input.asyncDir, { operation: "result", provider, providerJobId: handle.providerJobId });
+		let artifactPath = result.artifactPath;
+		if (!artifactPath && result.output !== undefined) {
+			artifactPath = path.join(input.asyncDir, `external-job-${input.stepIndex}.result.md`);
+			fs.writeFileSync(artifactPath, result.output, "utf-8");
+		}
+		const finalStatus = statusFromHandle({ provider, promptDigest, options, previous: current, handle: result, resultArtifactPath: artifactPath });
+		publish(finalStatus);
+		const output = resultOutput(result, artifactPath);
+		const error = result.state === "completed" ? undefined : result.failureMessage ?? `External job ${result.state}.`;
+		return { output, exitCode: result.state === "completed" ? 0 : 1, ...(error ? { error } : {}), externalJob: finalStatus };
+	} catch (error) {
+		const providerError = error instanceof ExternalJobProviderError
+			? error
+			: new ExternalJobProviderError(error instanceof Error ? error.message : String(error), { code: "provider-error", cause: error });
+		const message = formatError(providerError, provider);
+		const status = failureStatus({ provider, promptDigest, options, previous: current, code: providerError.code, message, ...(providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {}) });
+		publish(status);
+		return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: status };
+	} finally {
+		input.registerTimeout?.(undefined);
+		input.registerStop?.(undefined);
+	}
+}

package/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -32,6 +32,12 @@ interface ServerEntry {
 	cwd?: string;
 	url?: string;
 	headers?: Record<string, string>;
+	requestHeadersCommand?: {
+		command: string;
+		args?: string[];
+		env?: Record<string, string>;
+		timeoutMs?: number;
+	};
 	auth?: "oauth" | "bearer" | false;
 	bearerToken?: string;
 	bearerTokenEnv?: string;
@@ -279,6 +285,14 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 		cwd: resolveConfigPath(definition.cwd),
 		url: resolveServerUrl(definition),
 		headers: interpolateEnvRecord(definition.headers),
+		requestHeadersCommand: definition.requestHeadersCommand
+			? {
+				command: interpolateEnvVars(definition.requestHeadersCommand.command),
+				args: definition.requestHeadersCommand.args?.map(interpolateEnvVars),
+				env: interpolateEnvRecord(definition.requestHeadersCommand.env),
+				timeoutMs: definition.requestHeadersCommand.timeoutMs,
+			}
+			: undefined,
 		auth: definition.auth,
 		bearerToken: resolveBearerToken(definition),
 		bearerTokenEnv: definition.bearerTokenEnv,

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

@@ -41,7 +41,7 @@ export function normalizeParentModel(model: unknown): ParentModel | undefined {
 /**
  * Normalize a model id or provider segment for fuzzy comparison: case-fold,
  * treat dots/underscores as dashes (so `4.5` matches `4-5`), and collapse
- * repeated separators. Pure.
+ * repeated separators.
  */
 export function normalizeModelSegment(segment: string): string {
 	return segment
@@ -58,7 +58,7 @@ function isPlausibleDateStamp(year: string, month: string, day: string): boolean
 	return yyyy >= 1900 && yyyy <= 2099 && mm >= 1 && mm <= 12 && dd >= 1 && dd <= 31;
 }
 
-/** Drop a trailing date stamp (`-20251001` or `-2025-10-01`) so dated and undated ids match. Pure. */
+/** Drop a trailing date stamp (`-20251001` or `-2025-10-01`) so dated and undated ids match. */
 function stripTrailingDateStamp(segment: string): string {
 	const dashed = /^(.*)-(\d{4})-(\d{2})-(\d{2})$/.exec(segment);
 	if (dashed && isPlausibleDateStamp(dashed[2]!, dashed[3]!, dashed[4]!)) return dashed[1]!;
@@ -67,21 +67,65 @@ function stripTrailingDateStamp(segment: string): string {
 	return segment;
 }
 
+function isRegisteredProvider(provider: string, availableModels: AvailableModelInfo[]): boolean {
+	const normalized = normalizeModelSegment(provider);
+	return availableModels.some((entry) => normalizeModelSegment(entry.provider) === normalized);
+}
+
+/**
+ * Split `provider/id` only when the first path segment is a registered provider.
+ * Hugging Face-style `owner/name` ids therefore stay intact unless `owner` is
+ * itself a provider in the active registry. `:` and `.` keep the same rule.
+ */
+function splitQualifiedModelQuery(
+	baseModel: string,
+	availableModels: AvailableModelInfo[],
+): { queryProvider?: string; queryIdRaw: string } {
+	const slashIdx = baseModel.indexOf("/");
+	if (slashIdx !== -1) {
+		const providerPart = baseModel.slice(0, slashIdx);
+		if (isRegisteredProvider(providerPart, availableModels)) {
+			return { queryProvider: normalizeModelSegment(providerPart), queryIdRaw: baseModel.slice(slashIdx + 1) };
+		}
+		return { queryIdRaw: baseModel };
+	}
+	const providerSeparators = [":", "."];
+	for (const separator of providerSeparators) {
+		const separatorIdx = baseModel.indexOf(separator);
+		if (separatorIdx <= 0) continue;
+		const providerPart = baseModel.slice(0, separatorIdx);
+		if (!isRegisteredProvider(providerPart, availableModels)) continue;
+		return { queryProvider: normalizeModelSegment(providerPart), queryIdRaw: baseModel.slice(separatorIdx + 1) };
+	}
+	return { queryIdRaw: baseModel };
+}
+
+function resolveExactIdMatches(
+	baseModel: string,
+	availableModels: AvailableModelInfo[],
+	preferredProvider?: string,
+): string | undefined {
+	const exactMatches = availableModels.filter((entry) => entry.id === baseModel);
+	if (preferredProvider) {
+		const preferredMatch = exactMatches.find((entry) => entry.provider === preferredProvider);
+		if (preferredMatch) return preferredMatch.fullId;
+	}
+	if (exactMatches.length === 1) return exactMatches[0]!.fullId;
+	return undefined;
+}
+
 function resolveBaseModelCandidate(
 	baseModel: string,
 	availableModels: AvailableModelInfo[],
 	preferredProvider?: string,
 ): string | undefined {
-	if (baseModel.includes("/")) {
-		const exact = availableModels.find((entry) => entry.fullId === baseModel);
-		if (exact) return exact.fullId;
-	} else {
-		const exactMatches = availableModels.filter((entry) => entry.id === baseModel);
-		if (preferredProvider) {
-			const preferredMatch = exactMatches.find((entry) => entry.provider === preferredProvider);
-			if (preferredMatch) return preferredMatch.fullId;
-		}
-		if (exactMatches.length === 1) return exactMatches[0]!.fullId;
+	const exact = availableModels.find((entry) => entry.fullId === baseModel);
+	if (exact) return exact.fullId;
+
+	const { queryProvider } = splitQualifiedModelQuery(baseModel, availableModels);
+	if (queryProvider === undefined) {
+		const exactId = resolveExactIdMatches(baseModel, availableModels, preferredProvider);
+		if (exactId) return exactId;
 	}
 
 	return fuzzyResolveModel(baseModel, availableModels, preferredProvider);
@@ -90,35 +134,20 @@ function resolveBaseModelCandidate(
 /**
  * Fuzzy-resolve a base model id (thinking suffix already stripped) against the
  * registry, tolerating separator, case, and optional date-stamp differences so
- * users do not have to spell provider/model exactly. A qualified `provider/id`
+ * users do not have to spell provider/model exactly. A slash is a provider
+ * prefix only when that prefix is a registered provider; otherwise the whole
+ * string is the model id (Hugging Face `owner/name`). A qualified provider
  * query only matches within the named provider — this never silently switches
  * providers for security/cost-sensitive configs. Returns the matched `fullId`,
  * or `undefined` when there is no match or the match is ambiguous across
- * providers (and no `preferredProvider` disambiguates). Pure.
+ * providers (and no `preferredProvider` disambiguates).
  */
 export function fuzzyResolveModel(
 	baseModel: string,
 	availableModels: AvailableModelInfo[],
 	preferredProvider?: string,
 ): string | undefined {
-	let queryProvider: string | undefined;
-	let queryIdRaw = baseModel;
-	const slashIdx = baseModel.indexOf("/");
-	if (slashIdx !== -1) {
-		queryProvider = normalizeModelSegment(baseModel.slice(0, slashIdx));
-		queryIdRaw = baseModel.slice(slashIdx + 1);
-	} else {
-		const providerSeparators = [":", "."];
-		for (const separator of providerSeparators) {
-			const separatorIdx = baseModel.indexOf(separator);
-			if (separatorIdx <= 0) continue;
-			const providerPart = normalizeModelSegment(baseModel.slice(0, separatorIdx));
-			if (!availableModels.some((entry) => normalizeModelSegment(entry.provider) === providerPart)) continue;
-			queryProvider = providerPart;
-			queryIdRaw = baseModel.slice(separatorIdx + 1);
-			break;
-		}
-	}
+	const { queryProvider, queryIdRaw } = splitQualifiedModelQuery(baseModel, availableModels);
 	const queryId = normalizeModelSegment(queryIdRaw);
 	const queryIdNoDate = stripTrailingDateStamp(queryId);
 
@@ -143,7 +172,7 @@ export function fuzzyResolveModel(
  * thinking suffix). Exact registry matches win; fuzzy normalization
  * (separator/case/date-stamp via {@link fuzzyResolveModel}) is a fallback so
  * spelling differences still resolve. Never switches providers for a qualified
- * query. Pure.
+ * query.
  */
 export function resolveModelCandidate(
 	model: string | undefined,
@@ -163,17 +192,26 @@ export function resolveModelCandidate(
 	return model;
 }
 
-function resolveRequiredSubagentModelCandidate(
+function resolveSubagentModelCandidate(
 	model: string,
 	availableModels: AvailableModelInfo[] | undefined,
 	preferredProvider?: string,
-): string {
+): string | undefined {
 	if (!availableModels || availableModels.length === 0) return model;
 	const resolvedWhole = resolveBaseModelCandidate(model, availableModels, preferredProvider);
 	if (resolvedWhole) return resolvedWhole;
 	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
 	const resolvedBase = thinkingSuffix ? resolveBaseModelCandidate(baseModel, availableModels, preferredProvider) : undefined;
-	if (resolvedBase) return `${resolvedBase}${thinkingSuffix}`;
+	return resolvedBase ? `${resolvedBase}${thinkingSuffix}` : undefined;
+}
+
+function resolveRequiredSubagentModelCandidate(
+	model: string,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string {
+	const resolved = resolveSubagentModelCandidate(model, availableModels, preferredProvider);
+	if (resolved) return resolved;
 	throw new Error(`Unknown subagent model '${model}' in the active Pi model registry.`);
 }
 
@@ -263,6 +301,18 @@ export interface BuildModelCandidatesOptions {
 	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
 	scope?: ModelScopeConfig;
 	onWarn?: (violation: ModelScopeViolation) => void;
+	/** The primary model came from the running parent session, not configuration. */
+	primaryModelFromParent?: boolean;
+}
+
+export function inheritsParentModel(
+	explicitModel: string | boolean | undefined,
+	agentModel: string | boolean | undefined,
+	parentModel: ParentModel | undefined,
+): boolean {
+	const requestedModel = explicitModel ?? agentModel;
+	const trimmed = typeof requestedModel === "string" ? requestedModel.trim() : "";
+	return Boolean(parentModel && (!trimmed || trimmed === INHERIT_MODEL));
 }
 
 export function buildModelCandidates(
@@ -278,8 +328,17 @@ export function buildModelCandidates(
 	for (let index = 0; index < rawCandidates.length; index++) {
 		const raw = rawCandidates[index];
 		if (!raw) continue;
-		const normalized = resolveRequiredSubagentModelCandidate(raw.trim(), availableModels, preferredProvider);
-		if (!normalized || seen.has(normalized)) continue;
+		const model = raw.trim();
+		const normalized = index === 0
+			? options?.primaryModelFromParent
+				? model
+				: resolveRequiredSubagentModelCandidate(model, availableModels, preferredProvider)
+			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
+		if (!normalized) {
+			console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			continue;
+		}
+		if (seen.has(normalized)) continue;
 		if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
 			const violation = checkModelScope(normalized, options.scope, "inherited");
 			if (violation) {
@@ -295,6 +354,7 @@ export function buildModelCandidates(
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/rate\s*limit/i,
+	/usage\s*limit/i,
 	/too many requests/i,
 	/\b429\b/,
 	/quota/i,