@gajae-code/coding-agent 0.4.5 → 0.5.0

package/src/task/executor.ts

@@ -13,7 +13,7 @@ import { type JsonSchemaValidationIssue, validateJsonSchemaValue } from "@gajae-
 import { logger, prompt, untilAborted } from "@gajae-code/utils";
 import { AsyncJobManager } from "../async";
 import { ModelRegistry } from "../config/model-registry";
-import { resolveModelOverrideWithAuthFallback } from "../config/model-resolver";
+import { formatModelString, resolveModelOverrideWithAuthFallback } from "../config/model-resolver";
 import type { PromptTemplate } from "../config/prompt-templates";
 import { Settings } from "../config/settings";
 import { SETTINGS_SCHEMA, type SettingPath } from "../config/settings-schema";
@@ -38,7 +38,7 @@ import { jtdToJsonSchema, normalizeSchema } from "../tools/jtd-to-json-schema";
 import { type ReportFindingDetails, toReviewFinding } from "../tools/review";
 import { ToolAbortError } from "../tools/tool-errors";
 import type { EventBus } from "../utils/event-bus";
-import { buildNamedToolChoice } from "../utils/tool-choice";
+import { buildNamedToolChoiceResult } from "../utils/tool-choice";
 import type { WorkspaceTree } from "../workspace-tree";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
 import {
@@ -46,6 +46,7 @@ import {
 	type AgentProgress,
 	MAX_OUTPUT_BYTES,
 	MAX_OUTPUT_LINES,
+	type ModelSubstitutionWarning,
 	type ReviewFinding,
 	type SingleResult,
 	TASK_SUBAGENT_EVENT_CHANNEL,
@@ -627,6 +628,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	let yieldCalled = false;
 	let pauseRequested = false;
 	let paused = false;
+	let modelSubstitutionWarning: ModelSubstitutionWarning | undefined;
+	let resolvedModelString: string | undefined;
+	let lastAssistantModelString: string | undefined;
+	let effectiveThinkingLevelForWarning: ThinkingLevel | undefined;
 
 	// Accumulate usage incrementally from message_end events (no memory for streaming events)
 	const accumulatedUsage = {
@@ -762,6 +767,14 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		return undefined;
 	};
 
+	const getMessageModelString = (message: unknown): string | undefined => {
+		if (!message || typeof message !== "object") return undefined;
+		const record = message as { provider?: unknown; model?: unknown };
+		return typeof record.provider === "string" && typeof record.model === "string"
+			? `${record.provider}/${record.model}`
+			: undefined;
+	};
+
 	const updateRecentOutputLines = () => {
 		const lines = recentOutputTail.split("\n").filter(line => line.trim());
 		progress.recentOutput = lines.slice(-8).reverse();
@@ -964,6 +977,29 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 							}
 						}
 					}
+					const assistantModel = getMessageModelString(event.message);
+					if (assistantModel) {
+						lastAssistantModelString = assistantModel;
+						if (resolvedModelString && assistantModel !== resolvedModelString && !modelSubstitutionWarning) {
+							modelSubstitutionWarning = {
+								requested: resolvedModelString,
+								effective: assistantModel,
+								reason: "assistant_model_mismatch",
+							};
+							progress.modelSubstitutionWarning = modelSubstitutionWarning;
+							activeSession?.sessionManager.appendModelChange(assistantModel, undefined, {
+								previousModel: resolvedModelString,
+								reason: modelSubstitutionWarning.reason,
+								thinkingLevel: effectiveThinkingLevelForWarning ?? null,
+							});
+							logger.warn("Subagent assistant response reported a substituted effective model", {
+								requested: resolvedModelString,
+								effective: assistantModel,
+								agent: agent.name,
+								id,
+							});
+						}
+					}
 				}
 				// Extract and accumulate usage (prefer message.usage, fallback to event.usage)
 				const messageUsage = getMessageUsage(event.message) || (event as AgentEvent & { usage?: unknown }).usage;
@@ -1090,6 +1126,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				thinkingLevel: resolvedThinkingLevel,
 				explicitThinkingLevel,
 				authFallbackUsed,
+				requestedModel,
+				fallbackReason,
 			} = await awaitAbortable(
 				resolveModelOverrideWithAuthFallback(
 					modelPatterns,
@@ -1099,9 +1137,18 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					options.parentSessionId,
 				),
 			);
-			if (authFallbackUsed && model) {
+			if (model) {
+				resolvedModelString = formatModelString(model);
+			}
+			if (authFallbackUsed && model && requestedModel) {
+				modelSubstitutionWarning = {
+					requested: formatModelString(requestedModel),
+					effective: formatModelString(model),
+					reason: fallbackReason ?? "auth_unavailable",
+				};
+				progress.modelSubstitutionWarning = modelSubstitutionWarning;
 				logger.warn("Subagent model has no working credentials; falling back to parent session model", {
-					requested: modelPatterns,
+					requested: modelSubstitutionWarning.requested,
 					parentModel: options.parentActiveModelPattern,
 					resolvedProvider: model.provider,
 					resolvedModel: model.id,
@@ -1113,6 +1160,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			const effectiveThinkingLevel = explicitThinkingLevel
 				? resolvedThinkingLevel
 				: (thinkingLevel ?? resolvedThinkingLevel);
+			effectiveThinkingLevelForWarning = effectiveThinkingLevel;
 
 			const sessionManager = sessionFile
 				? await awaitAbortable(SessionManager.open(sessionFile))
@@ -1174,6 +1222,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					settings: subagentSettings,
 					model,
 					thinkingLevel: effectiveThinkingLevel,
+					modelSubstitution:
+						modelSubstitutionWarning?.reason === "auth_unavailable" && requestedModel
+							? { requestedModel, reason: modelSubstitutionWarning.reason }
+							: undefined,
 					toolNames,
 					outputSchema,
 					requireYieldTool: true,
@@ -1412,7 +1464,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				await awaitAbortable(session.waitForIdle());
 			}
 
-			const reminderToolChoice = buildNamedToolChoice("yield", session.model);
+			const reminderToolChoiceResult = buildNamedToolChoiceResult("yield", session.model);
 
 			let retryCount = 0;
 			while (!paused && !yieldCalled && retryCount < MAX_YIELD_RETRIES && !abortSignal.aborted) {
@@ -1433,7 +1485,9 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					await awaitAbortable(
 						session.prompt(reminder, {
 							attribution: "agent",
-							...(isFinalRetry && reminderToolChoice ? { toolChoice: reminderToolChoice } : {}),
+							...(isFinalRetry && reminderToolChoiceResult.exactNamed && reminderToolChoiceResult.choice
+								? { toolChoice: reminderToolChoiceResult.choice }
+								: {}),
 						}),
 					);
 					await awaitAbortable(session.waitForIdle());
@@ -1466,6 +1520,14 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					error = undefined;
 				}
 			}
+			if (lastAssistantModelString && resolvedModelString && lastAssistantModelString !== resolvedModelString) {
+				modelSubstitutionWarning ??= {
+					requested: resolvedModelString,
+					effective: lastAssistantModelString,
+					reason: "assistant_model_mismatch",
+				};
+				progress.modelSubstitutionWarning = modelSubstitutionWarning;
+			}
 		} catch (err) {
 			exitCode = 1;
 			if (!abortSignal.aborted) {
@@ -1642,6 +1704,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		contextTokens: progress.contextTokens,
 		contextWindow: progress.contextWindow,
 		modelOverride,
+		modelSubstitutionWarning,
 		error: exitCode !== 0 && stderr ? stderr : undefined,
 		aborted: wasAborted,
 		abortReason: finalAbortReason,

package/src/task/receipt.ts

@@ -29,6 +29,7 @@ export interface TaskResultReceipt {
 	contextTokens?: number;
 	contextWindow?: number;
 	modelOverride?: string | string[];
+	modelSubstitutionWarning?: SingleResult["modelSubstitutionWarning"];
 	usage?: SingleResult["usage"];
 	cost?: number;
 	branchName?: string;
@@ -78,6 +79,9 @@ function truncateText(value: string | undefined, maxChars: number): string | und
 
 function buildSafeSynopsis(raw: SingleResult, outputRef: TaskResultReceipt["outputRef"]): string {
 	const status = getStatus(raw);
+	if (raw.modelSubstitutionWarning) {
+		return `Task ${status}; requested model substituted from ${raw.modelSubstitutionWarning.requested} to ${raw.modelSubstitutionWarning.effective}.`;
+	}
 	if (raw.retryFailure) {
 		return `Task ${status}; retry stopped after attempt ${raw.retryFailure.attempt}.`;
 	}
@@ -220,6 +224,7 @@ export function buildTaskReceipt(raw: SingleResult): TaskResultReceipt {
 		contextTokens: raw.contextTokens,
 		contextWindow: raw.contextWindow,
 		modelOverride: raw.modelOverride,
+		modelSubstitutionWarning: raw.modelSubstitutionWarning,
 		usage: raw.usage,
 		cost: raw.usage?.cost.total,
 		branchName: raw.branchName,

package/src/task/render.ts

@@ -119,6 +119,10 @@ function normalizeReportFindings(value: unknown): ReportFindingDetails[] {
 	return findings;
 }
 
+function formatModelSubstitutionWarning(warning: { requested: string; effective: string }): string {
+	return `Requested model substituted: ${warning.requested} -> ${warning.effective}`;
+}
+
 function formatJsonScalar(value: unknown, _theme: Theme): string {
 	if (value === null) return "null";
 	if (typeof value === "string") {
@@ -566,6 +570,14 @@ function renderAgentProgress(
 	lines.push(statusLine);
 
 	lines.push(...renderTaskSection(progress.assignment ?? progress.task, continuePrefix, expanded, theme));
+	if (progress.modelSubstitutionWarning) {
+		lines.push(
+			`${continuePrefix}${theme.fg(
+				"warning",
+				truncateToWidth(replaceTabs(formatModelSubstitutionWarning(progress.modelSubstitutionWarning)), 90),
+			)}`,
+		);
+	}
 
 	// Current tool (if running) or most recent completed tool
 	if (progress.status === "running") {
@@ -862,9 +874,17 @@ function renderAgentResult(result: TaskResultReceipt, isLast: boolean, expanded:
 				}
 			}
 		}
-	} else {
+	} else if (!result.modelSubstitutionWarning) {
 		lines.push(...renderOutputSection(result.preview, continuePrefix, expanded, theme, 3, 12));
 	}
+	if (result.modelSubstitutionWarning) {
+		lines.push(
+			`${continuePrefix}${theme.fg(
+				"warning",
+				truncateToWidth(replaceTabs(formatModelSubstitutionWarning(result.modelSubstitutionWarning)), 90),
+			)}`,
+		);
+	}
 	if (result.roi?.lowRoi) {
 		lines.push(`${continuePrefix}${theme.fg("warning", "low ROI: produced no material contribution")}`);
 	}

package/src/task/types.ts

@@ -215,6 +215,12 @@ export interface AgentDefinition {
 	filePath?: string;
 }
 
+export interface ModelSubstitutionWarning {
+	requested: string;
+	effective: string;
+	reason: "auth_unavailable" | "assistant_model_mismatch";
+}
+
 /** Progress tracking for a single agent */
 export interface AgentProgress {
 	index: number;
@@ -247,6 +253,7 @@ export interface AgentProgress {
 	cost: number;
 	durationMs: number;
 	modelOverride?: string | string[];
+	modelSubstitutionWarning?: ModelSubstitutionWarning;
 	/** Data extracted by registered subprocess tool handlers (keyed by tool name) */
 	extractedToolData?: Record<string, unknown[]>;
 	/**
@@ -306,6 +313,7 @@ export interface SingleResult {
 	/** Model's context window in tokens, when known. */
 	contextWindow?: number;
 	modelOverride?: string | string[];
+	modelSubstitutionWarning?: ModelSubstitutionWarning;
 	error?: string;
 	aborted?: boolean;
 	abortReason?: string;

package/src/thinking-metadata.ts

@@ -0,0 +1,51 @@
+export type ThinkingLevelValue = "inherit" | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/**
+ * Metadata used to render thinking selector values in the coding-agent UI.
+ *
+ * This module is intentionally provider/native-free so schema generation can
+ * import settings metadata before native addons have been built in CI.
+ */
+export interface ThinkingLevelMetadata {
+	value: ThinkingLevelValue;
+	label: string;
+	description: string;
+}
+
+const THINKING_LEVEL_METADATA: Record<ThinkingLevelValue, ThinkingLevelMetadata> = {
+	inherit: {
+		value: "inherit",
+		label: "inherit",
+		description: "Inherit session default",
+	},
+	off: { value: "off", label: "off", description: "No reasoning" },
+	minimal: {
+		value: "minimal",
+		label: "min",
+		description: "Very brief reasoning (~1k tokens)",
+	},
+	low: { value: "low", label: "low", description: "Light reasoning (~2k tokens)" },
+	medium: {
+		value: "medium",
+		label: "medium",
+		description: "Moderate reasoning (~8k tokens)",
+	},
+	high: { value: "high", label: "high", description: "Deep reasoning (~16k tokens)" },
+	xhigh: {
+		value: "xhigh",
+		label: "xhigh",
+		description: "Maximum reasoning (~32k tokens)",
+	},
+	max: {
+		value: "max",
+		label: "max",
+		description: "Opus maximum reasoning",
+	},
+};
+
+/**
+ * Returns display metadata for a thinking selector.
+ */
+export function getThinkingLevelMetadata(level: ThinkingLevelValue): ThinkingLevelMetadata {
+	return THINKING_LEVEL_METADATA[level];
+}

package/src/thinking.ts

@@ -2,45 +2,7 @@ import { type ResolvedThinkingLevel, ThinkingLevel } from "@gajae-code/agent-cor
 import { clampThinkingLevelForModel, type Effort, THINKING_EFFORTS } from "@gajae-code/ai/model-thinking";
 import type { Model } from "@gajae-code/ai/types";
 
-/**
- * Metadata used to render thinking selector values in the coding-agent UI.
- */
-export interface ThinkingLevelMetadata {
-	value: ThinkingLevel;
-	label: string;
-	description: string;
-}
-
-const THINKING_LEVEL_METADATA: Record<ThinkingLevel, ThinkingLevelMetadata> = {
-	[ThinkingLevel.Inherit]: {
-		value: ThinkingLevel.Inherit,
-		label: "inherit",
-		description: "Inherit session default",
-	},
-	[ThinkingLevel.Off]: { value: ThinkingLevel.Off, label: "off", description: "No reasoning" },
-	[ThinkingLevel.Minimal]: {
-		value: ThinkingLevel.Minimal,
-		label: "min",
-		description: "Very brief reasoning (~1k tokens)",
-	},
-	[ThinkingLevel.Low]: { value: ThinkingLevel.Low, label: "low", description: "Light reasoning (~2k tokens)" },
-	[ThinkingLevel.Medium]: {
-		value: ThinkingLevel.Medium,
-		label: "medium",
-		description: "Moderate reasoning (~8k tokens)",
-	},
-	[ThinkingLevel.High]: { value: ThinkingLevel.High, label: "high", description: "Deep reasoning (~16k tokens)" },
-	[ThinkingLevel.XHigh]: {
-		value: ThinkingLevel.XHigh,
-		label: "xhigh",
-		description: "Maximum reasoning (~32k tokens)",
-	},
-	[ThinkingLevel.Max]: {
-		value: ThinkingLevel.Max,
-		label: "max",
-		description: "Opus maximum reasoning",
-	},
-};
+export { getThinkingLevelMetadata, type ThinkingLevelMetadata } from "./thinking-metadata";
 
 const THINKING_LEVELS = new Set<string>([ThinkingLevel.Inherit, ThinkingLevel.Off, ...THINKING_EFFORTS]);
 const EFFORT_LEVELS = new Set<string>(THINKING_EFFORTS);
@@ -59,13 +21,6 @@ export function parseThinkingLevel(value: string | null | undefined): ThinkingLe
 	return value !== undefined && value !== null && THINKING_LEVELS.has(value) ? (value as ThinkingLevel) : undefined;
 }
 
-/**
- * Returns display metadata for a thinking selector.
- */
-export function getThinkingLevelMetadata(level: ThinkingLevel): ThinkingLevelMetadata {
-	return THINKING_LEVEL_METADATA[level];
-}
-
 /**
  * Converts an agent-local selector into the effort sent to providers.
  */
@@ -91,3 +46,28 @@ export function resolveThinkingLevelForModel(
 	}
 	return clampThinkingLevelForModel(model, level);
 }
+
+export function clampExplicitThinkingLevelForModel(
+	model: Model | undefined,
+	level: ThinkingLevel | undefined,
+): ThinkingLevel | undefined {
+	if (level === undefined || level === ThinkingLevel.Inherit || level === ThinkingLevel.Off) {
+		return level;
+	}
+	return clampThinkingLevelForModel(model, level);
+}
+
+export function formatClampedModelSelector(selector: string, model: Model | undefined): string {
+	const slashIdx = selector.indexOf("/");
+	if (slashIdx <= 0) return selector;
+	const id = selector.slice(slashIdx + 1);
+	const colonIdx = id.lastIndexOf(":");
+	if (colonIdx === -1) return selector;
+	const suffix = id.slice(colonIdx + 1);
+	const thinkingLevel = parseThinkingLevel(suffix);
+	if (!thinkingLevel) return selector;
+	const clamped = clampExplicitThinkingLevelForModel(model, thinkingLevel);
+	return clamped && clamped !== ThinkingLevel.Inherit
+		? `${selector.slice(0, slashIdx + 1)}${id.slice(0, colonIdx)}:${clamped}`
+		: selector.slice(0, slashIdx + 1) + id.slice(0, colonIdx);
+}

package/src/tools/bash.ts

@@ -51,7 +51,7 @@ async function saveBashOriginalArtifact(session: ToolSession, originalText: stri
 const bashSchemaBase = z.object({
 	command: z.string().describe("command to execute"),
 	env: z.record(z.string().regex(BASH_ENV_NAME_PATTERN), z.string()).optional().describe("extra env vars"),
-	timeout: z.number().default(300).describe("timeout in seconds").optional(),
+	timeout: z.number().default(300).describe("timeout in seconds, NOT milliseconds (30 = 30s)").optional(),
 	cwd: z.string().describe("working directory").optional(),
 	pty: z.boolean().describe("run in pty mode").optional(),
 });

package/src/tools/index.ts

@@ -240,6 +240,8 @@ export interface ToolSession {
 	getToolChoiceQueue?(): ToolChoiceQueue;
 	/** Build a model-provider-specific ToolChoice that targets the named tool, or undefined if unsupported. */
 	buildToolChoice?(toolName: string): ToolChoice | undefined;
+	/** Build a named tool-choice decision, preserving whether exact named forcing survived capability degradation. */
+	buildToolChoiceResult?(toolName: string): import("../utils/tool-choice").NamedToolChoiceResult;
 	/** Steer a hidden custom message into the conversation (e.g. a preview reminder). */
 	steer?(message: { customType: string; content: string; details?: unknown }): void;
 	/** Peek the currently in-flight tool-choice queue directive's invocation handler. Used by the `resolve` tool to dispatch to the pending action. */

package/src/tools/resolve.ts

@@ -1,4 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import type { ToolChoice } from "@gajae-code/ai";
 import type { Component } from "@gajae-code/tui";
 import { Text } from "@gajae-code/tui";
 import { prompt, untilAborted } from "@gajae-code/utils";
@@ -38,6 +39,21 @@ export interface ResolveToolDetails {
  * semantics. No session-level abstraction is needed: callers pass their
  * apply/reject functions directly.
  */
+/**
+ * Tags preview-fallback handlers installed in the session's standing-resolve
+ * slot so newer previews can replace older ones (latest-preview-wins) without
+ * ever displacing a mode-owned handler such as plan mode's approval handler.
+ */
+const previewResolveFallbacks = new WeakSet<object>();
+
+function markPreviewResolveFallback(handler: (input: unknown) => Promise<unknown> | unknown): void {
+	previewResolveFallbacks.add(handler);
+}
+
+function isPreviewResolveFallback(handler: (input: unknown) => Promise<unknown> | unknown): boolean {
+	return previewResolveFallbacks.has(handler);
+}
+
 export function queueResolveHandler(
 	session: ToolSession,
 	options: {
@@ -48,8 +64,6 @@ export function queueResolveHandler(
 	},
 ): void {
 	const queue = session.getToolChoiceQueue?.();
-	const forced = session.buildToolChoice?.("resolve");
-	if (!queue || !forced || typeof forced === "string") return;
 
 	const steerReminder = (): void => {
 		session.steer?.({
@@ -63,27 +77,88 @@ export function queueResolveHandler(
 		});
 	};
 
-	const pushDirective = (): void => {
+	// Re-evaluated on every push (including apply-error re-pushes) so a runtime
+	// incapability discovered mid-turn degrades the NEXT push instead of
+	// replaying a stale forced choice the model can never satisfy.
+	const resolveForcedChoice = (): { forced: ToolChoice | undefined; exactNamed: boolean } => {
+		const toolChoiceResult = session.buildToolChoiceResult?.("resolve");
+		if (toolChoiceResult !== undefined) {
+			return { forced: toolChoiceResult.choice, exactNamed: toolChoiceResult.exactNamed };
+		}
+		// Legacy bridge fallback: sessions that only provide buildToolChoice
+		// (older SDK embedders, test harnesses) keep the previous behavior — a
+		// named object choice is treated as exact named forcing.
+		const legacyChoice = session.buildToolChoice?.("resolve");
+		const isNamedObject = typeof legacyChoice === "object" && legacyChoice !== null;
+		return { forced: isNamedObject ? legacyChoice : undefined, exactNamed: isNamedObject };
+	};
+
+	const clearFallback = (): void => {
+		// Identity-aware: only clear the shared standing slot when it still holds
+		// THIS preview's fallback. Plan mode (or a newer preview) may have
+		// replaced it in the meantime — leave theirs untouched.
+		if (session.peekStandingResolveHandler?.() === invoke) {
+			session.setStandingResolveHandler?.(null);
+		}
+	};
+
+	const invoke = async (input: unknown): Promise<AgentToolResult<unknown>> => {
+		const result = await runResolveInvocation(input as ResolveParams, {
+			sourceToolName: options.sourceToolName,
+			label: options.label,
+			apply: options.apply,
+			reject: options.reject,
+			onApplyError: () => {
+				// Apply threw (e.g. ast_edit overlapping replacements). Re-push the
+				// same directive so the preview remains pending and the model can
+				// `discard` or fix-and-retry on the next turn instead of being
+				// stranded with no pending action to address. The re-push goes
+				// through the exactNamed gate again — degraded models fall back
+				// to the reminder alone. The standing fallback stays installed so
+				// a voluntary resolve can still reach the pending action.
+				pushDirective();
+				steerReminder();
+			},
+		});
+		// Apply succeeded or the preview was discarded: the pending action is
+		// finished, so the voluntary-dispatch fallback must not linger.
+		clearFallback();
+		return result;
+	};
+	markPreviewResolveFallback(invoke);
+
+	// Voluntary-dispatch fallback: when forcing is unavailable (statically
+	// degraded) or later removed (runtime degradeInFlight drops the queue
+	// directive that owns the invoker), the model can still call `resolve`.
+	// ResolveTool.execute consults the queue invoker first, so the standing
+	// handler only serves degraded paths. Latest preview wins (mirroring the
+	// queue's pushOnce now:true semantics): a newer preview's fallback replaces
+	// an older preview's, but NEVER clobbers a non-preview standing handler
+	// (e.g. plan mode's approval handler).
+	const installFallback = (): void => {
+		if (!session.setStandingResolveHandler) return;
+		const existing = session.peekStandingResolveHandler?.();
+		if (existing === invoke) return;
+		if (existing !== undefined && !isPreviewResolveFallback(existing)) return;
+		session.setStandingResolveHandler(invoke);
+	};
+
+	const pushDirective = (): boolean => {
+		const { forced, exactNamed } = resolveForcedChoice();
+		if (!queue || !forced || !exactNamed) {
+			installFallback();
+			return false;
+		}
 		queue.pushOnce(forced, {
 			label: `pending-action:${options.sourceToolName}`,
 			now: true,
 			onRejected: () => "requeue",
-			onInvoked: async (input: unknown) =>
-				runResolveInvocation(input as ResolveParams, {
-					sourceToolName: options.sourceToolName,
-					label: options.label,
-					apply: options.apply,
-					reject: options.reject,
-					onApplyError: () => {
-						// Apply threw (e.g. ast_edit overlapping replacements). Re-push the
-						// same directive so the preview remains pending and the model can
-						// `discard` or fix-and-retry on the next turn instead of being
-						// stranded with no pending action to address.
-						pushDirective();
-						steerReminder();
-					},
-				}),
+			onInvoked: invoke,
 		});
+		// Forced directive may still be degraded mid-turn by a runtime
+		// incapability discovery; keep the fallback armed for that case.
+		installFallback();
+		return true;
 	};
 
 	pushDirective();

package/src/utils/edit-mode.ts

@@ -1,4 +1,4 @@
-import { $env } from "@gajae-code/utils/env";
+import { $env } from "../../../utils/src/env";
 
 export type EditMode = "replace" | "patch" | "hashline" | "vim" | "apply_patch";
 

package/src/utils/tool-choice.ts

@@ -1,33 +1,62 @@
-import type { Api, Model, ToolChoice } from "@gajae-code/ai";
+import type { Api, Model, ResolveToolChoiceResult, ToolChoice } from "@gajae-code/ai";
+import { resolveToolChoice } from "@gajae-code/ai";
 
 /**
  * Build a provider-aware tool choice that targets one specific tool when supported.
  * Providers that only expose required/any forcing may still honor named choices by
  * narrowing their request tool list before transport.
  */
-export function buildNamedToolChoice(toolName: string, model?: Model<Api>): ToolChoice | undefined {
-	if (!model) return undefined;
+export interface NamedToolChoiceResult {
+	choice: ToolChoice | undefined;
+	exactNamed: boolean;
+	resolved?: ResolveToolChoiceResult;
+}
 
-	if (model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") {
-		return { type: "tool", name: toolName };
-	}
+export function buildNamedToolChoiceResult(toolName: string, model?: Model<Api>): NamedToolChoiceResult {
+	if (!model) return { choice: undefined, exactNamed: false };
 
-	if (
+	let namedChoice: ToolChoice | undefined;
+	let namedShape = false;
+
+	if (model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") {
+		namedChoice = { type: "tool", name: toolName };
+		namedShape = true;
+	} else if (
 		model.api === "openai-codex-responses" ||
 		model.api === "openai-responses" ||
 		model.api === "openai-completions" ||
-		model.api === "azure-openai-responses"
+		model.api === "azure-openai-responses" ||
+		model.api === "ollama-chat"
+	) {
+		namedChoice = { type: "function", name: toolName };
+		namedShape = true;
+	} else if (
+		model.api === "google-generative-ai" ||
+		model.api === "google-gemini-cli" ||
+		model.api === "google-vertex"
 	) {
-		return { type: "function", name: toolName };
+		namedChoice = "required";
 	}
 
-	if (model.api === "ollama-chat") {
-		return { type: "function", name: toolName };
-	}
+	if (!namedChoice) return { choice: undefined, exactNamed: false };
 
-	if (model.api === "google-generative-ai" || model.api === "google-gemini-cli" || model.api === "google-vertex") {
-		return "required";
-	}
+	const resolved = resolveToolChoice(model, namedChoice);
+	const exactNamed = namedShape && resolved.resolvedLevel === "named" && resolved.targetToolName === toolName;
+	return {
+		choice: exactNamed ? resolved.resolvedChoice : undefined,
+		exactNamed,
+		resolved,
+	};
+}
 
-	return undefined;
+/**
+ * Legacy capability-aware wrapper. May return a lossy `"required"` when named
+ * forcing degrades (e.g. Google APIs, or compat `toolChoiceSupport: "required"`),
+ * which forces *some* tool rather than `toolName` specifically. Queue directives
+ * that need exact tool identity (resolve / todo_write / yield) MUST use
+ * `buildNamedToolChoiceResult` and gate on `exactNamed` instead.
+ */
+export function buildNamedToolChoice(toolName: string, model?: Model<Api>): ToolChoice | undefined {
+	const result = buildNamedToolChoiceResult(toolName, model);
+	return result.choice ?? result.resolved?.resolvedChoice;
 }