@gajae-code/coding-agent 0.4.5 → 0.5.1

package/src/tools/ask.ts

@@ -34,6 +34,8 @@ import {
 	renderDeepInterviewAskQuestion,
 } from "../deep-interview/render-middleware";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { appendOrMergeDeepInterviewRound } from "../gjc-runtime/deep-interview-recorder";
+import { deepInterviewStatePath } from "../gjc-runtime/deep-interview-runtime";
 import { gateAnswerToResult, questionToGate } from "../modes/shared/agent-wire/deep-interview-gate";
 import { getMarkdownTheme, type Theme, theme } from "../modes/theme/theme";
 import askDescription from "../prompts/tools/ask.md" with { type: "text" };
@@ -50,15 +52,25 @@ const OptionItem = z.object({
 	label: z.string().describe("display label"),
 });
 
+/** Optional structured deep-interview round metadata; when present the round is recorded automatically. */
+const DeepInterviewMeta = z.object({
+	round_id: z.string().describe("stable optional round identity").optional(),
+	round: z.number().int().nonnegative().describe("round number"),
+	component: z.string().min(1).describe("targeted topology component"),
+	dimension: z.string().min(1).describe("targeted clarity dimension"),
+	ambiguity: z.number().min(0).max(1).describe("ambiguity at ask time (0..1)"),
+});
+
 const QuestionItem = z.object({
 	id: z.string().describe("question id"),
 	question: z.string().describe("question text"),
 	options: z.array(OptionItem).describe("available options"),
 	multi: z.boolean().describe("allow multiple selections").optional(),
 	recommended: z.number().describe("recommended option index").optional(),
+	deepInterview: DeepInterviewMeta.describe("optional deep-interview round metadata").optional(),
 });
 
-const askSchema = z.object({
+export const askSchema = z.object({
 	questions: z.array(QuestionItem).min(1).describe("questions to ask"),
 });
 
@@ -456,6 +468,45 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 		TERMINAL.sendNotification("Waiting for input");
 	}
 
+	/**
+	 * Record a resolved deep-interview round when the question carries structured
+	 * metadata. The runtime owns durable record/merge semantics; this tool is only the
+	 * caller. Best-effort: a state-write hiccup must not break the user's answer flow.
+	 */
+	async #recordDeepInterviewRound(
+		q: AskParams["questions"][number],
+		selectedOptions: string[],
+		customInput: string | undefined,
+	): Promise<void> {
+		const meta = q.deepInterview;
+		if (!meta) return;
+		try {
+			const cwd = this.session.cwd;
+			const sessionId = this.session.getSessionId?.() ?? undefined;
+			const statePath = deepInterviewStatePath(cwd, sessionId);
+			await appendOrMergeDeepInterviewRound(
+				cwd,
+				statePath,
+				{
+					round: meta.round,
+					round_id: meta.round_id,
+					questionId: q.id,
+					questionText: q.question,
+					component: meta.component,
+					dimension: meta.dimension,
+					ambiguity: meta.ambiguity,
+					selectedOptions,
+					customInput,
+				},
+				{ sessionId },
+			);
+		} catch (error) {
+			console.warn(
+				`ask: deep-interview round recording failed: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
 	async execute(
 		_toolCallId: string,
 		params: AskParams,
@@ -515,6 +566,7 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 					options: q.options,
 					multi: q.multi,
 					recommended: q.recommended,
+					deepInterview: q.deepInterview,
 				};
 				const answer = await gateEmitter.emitGate(questionToGate(gateQuestion));
 				const decoded = gateAnswerToResult(gateQuestion, answer);
@@ -582,6 +634,7 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 				context?.abort();
 				throw new ToolAbortError("Ask tool was cancelled by the user");
 			}
+			await this.#recordDeepInterviewRound(q, selectedOptions, customInput);
 			const details: AskToolDetails = {
 				question: q.question,
 				options: optionLabels,
@@ -644,6 +697,8 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 				customInput,
 			};
 
+			await this.#recordDeepInterviewRound(q, selectedOptions, customInput);
+
 			if (navAction === "back") {
 				questionIndex = Math.max(0, questionIndex - 1);
 				continue;

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/job.ts

@@ -3,7 +3,7 @@ import type { Component } from "@gajae-code/tui";
 import { Text } from "@gajae-code/tui";
 import { prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from "../async";
+import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled, jobElapsedMs } from "../async";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import jobDescription from "../prompts/tools/job.md" with { type: "text" };
@@ -257,6 +257,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			status: string;
 			label: string;
 			startTime: number;
+			endTime?: number;
 			resultText?: string;
 			errorText?: string;
 		}[],
@@ -270,7 +271,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 				type: latest.type,
 				status: latest.status as JobSnapshot["status"],
 				label: latest.label,
-				durationMs: Math.max(0, now - latest.startTime),
+				durationMs: jobElapsedMs(latest, now),
 				...(latest.resultText ? { resultText: latest.resultText } : {}),
 				...(latest.errorText ? { errorText: latest.errorText } : {}),
 			};

package/src/tools/monitor.ts

@@ -3,6 +3,7 @@ import { logger, prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { AsyncJobManager, isBackgroundJobSupportEnabled } from "../async";
 import monitorDescription from "../prompts/tools/monitor.md" with { type: "text" };
+import { truncateTail } from "../session/streaming-output";
 import { BashTool } from "./bash";
 import type { ToolSession } from "./index";
 import { ToolError } from "./tool-errors";
@@ -48,6 +49,8 @@ export interface MonitorToolDetails {
 
 const MONITOR_LABEL_MAX = 120;
 const MAX_PENDING_MONITOR_NOTIFICATIONS = 3;
+const MONITOR_NOTIFICATION_LINE_MAX_BYTES = 16 * 1024;
+const MONITOR_NOTIFICATION_LINE_MAX_LINES = 20;
 
 function buildMonitorLabel(params: MonitorParams): string {
 	const base = `[monitor:${params.kind}] ${params.description}`;
@@ -55,6 +58,34 @@ function buildMonitorLabel(params: MonitorParams): string {
 	return `${base.slice(0, MONITOR_LABEL_MAX - 3)}...`;
 }
 
+function formatMonitorNotificationLine(line: string): {
+	content: string;
+	truncated: boolean;
+	totalBytes: number;
+	outputBytes: number;
+} {
+	const truncation = truncateTail(line, {
+		maxBytes: MONITOR_NOTIFICATION_LINE_MAX_BYTES,
+		maxLines: MONITOR_NOTIFICATION_LINE_MAX_LINES,
+	});
+	const outputBytes = truncation.outputBytes ?? truncation.totalBytes;
+	if (!truncation.truncated) {
+		return {
+			content: truncation.content,
+			truncated: false,
+			totalBytes: truncation.totalBytes,
+			outputBytes,
+		};
+	}
+	const notice = `[Monitor output truncated: showing last ${outputBytes} of ${truncation.totalBytes} bytes]`;
+	return {
+		content: `${truncation.content}\n${notice}`,
+		truncated: true,
+		totalBytes: truncation.totalBytes,
+		outputBytes,
+	};
+}
+
 export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolDetails> {
 	readonly name = "monitor";
 	readonly label = "Monitor";
@@ -130,7 +161,8 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 			if (controller.closed) return;
 			const notificationId = `${jobId}:${sequence}`;
 			const suffix = count > 0 ? `\n(+${count} earlier lines)` : "";
-			const content = `<task-notification>\nMonitor task ${jobId} (${params.kind}: ${params.description}) emitted latest state:\n${line}${suffix}\n</task-notification>`;
+			const notificationLine = formatMonitorNotificationLine(line);
+			const content = `<task-notification>\nMonitor task ${jobId} (${params.kind}: ${params.description}) emitted latest state:\n${notificationLine.content}${suffix}\n</task-notification>`;
 			const details = {
 				taskId: jobId,
 				kind: params.kind,
@@ -139,6 +171,9 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 				notificationId,
 				sequence,
 				coalescedCount: count,
+				outputTruncated: notificationLine.truncated,
+				outputTotalBytes: notificationLine.totalBytes,
+				outputBytes: notificationLine.outputBytes,
 			};
 			pendingNotifications += 1;
 			if (pendingNotifications > MAX_PENDING_MONITOR_NOTIFICATIONS) {

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/tools/subagent-render.ts

@@ -66,6 +66,15 @@ function renderSubagentSnapshot(
 	if (snapshot.agent && snapshot.agent !== "unknown") {
 		lines.push(`  ${theme.fg("dim", `Agent: ${snapshot.agent} (${snapshot.agentSource})`)}`);
 	}
+	if (snapshot.effectiveModel) {
+		if (snapshot.modelFellBack && snapshot.requestedModel) {
+			lines.push(
+				`  ${theme.fg("warning", `Model: ${snapshot.effectiveModel} (requested ${snapshot.requestedModel}, fell back — no credentials)`)}`,
+			);
+		} else {
+			lines.push(`  ${theme.fg("dim", `Model: ${snapshot.effectiveModel}`)}`);
+		}
+	}
 	if (snapshot.description) lines.push(`  ${theme.fg("dim", `Description: ${snapshot.description}`)}`);
 	if (snapshot.outputRef) lines.push(`  ${theme.fg("dim", `Output: ${snapshot.outputRef}`)}`);
 	if (snapshot.assignment) {

package/src/tools/subagent.ts

@@ -2,7 +2,7 @@ import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
 import { prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { type AsyncJob, AsyncJobManager, type SubagentRecord } from "../async";
+import { type AsyncJob, AsyncJobManager, jobElapsedMs, type SubagentRecord } from "../async";
 import subagentDescription from "../prompts/tools/subagent.md" with { type: "text" };
 import type { AgentProgress, AgentSource } from "../task/types";
 import { Ellipsis, truncateToWidth } from "../tui";
@@ -67,6 +67,12 @@ export interface SubagentSnapshot {
 	progress?: AgentProgress;
 	/** True when a live in-session progress producer exists for this subagent. */
 	liveProgressAvailable?: boolean;
+	/** Model the subagent actually runs on (after any auth fallback). */
+	effectiveModel?: string;
+	/** Model originally requested via role/preset mapping; differs from effective on fallback. */
+	requestedModel?: string;
+	/** True when the requested model lacked credentials and fell back to the parent model. */
+	modelFellBack?: boolean;
 }
 
 export interface SubagentToolDetails {
@@ -508,6 +514,13 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			lines.push(`### ${snapshot.id} — ${snapshot.status}`);
 			if (snapshot.jobId !== snapshot.id) lines.push(`Job: ${snapshot.jobId}`);
 			if (snapshot.agent) lines.push(`Agent: ${snapshot.agent} (${snapshot.agentSource})`);
+			if (snapshot.effectiveModel) {
+				lines.push(
+					snapshot.modelFellBack && snapshot.requestedModel
+						? `Model: ${snapshot.effectiveModel} (requested ${snapshot.requestedModel}, fell back — no credentials)`
+						: `Model: ${snapshot.effectiveModel}`,
+				);
+			}
 			if (snapshot.description) lines.push(`Description: ${snapshot.description}`);
 			if (snapshot.outputRef) lines.push(`Output: ${snapshot.outputRef}`);
 			if (snapshot.assignment) lines.push("Assignment:", "```", snapshot.assignment, "```");
@@ -584,9 +597,19 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			durationMs: 0,
 			...(verifiedOutputIds.has(record.subagentId) ? { outputRef: `agent://${record.subagentId}` } : {}),
 			...liveFields,
+			...this.#modelFields(record),
 		};
 	}
 
+	#modelFields(record?: SubagentRecord): Partial<SubagentSnapshot> {
+		if (!record) return {};
+		const fields: Partial<SubagentSnapshot> = {};
+		if (record.effectiveModel) fields.effectiveModel = record.effectiveModel;
+		if (record.requestedModel) fields.requestedModel = record.requestedModel;
+		if (record.modelFellBack) fields.modelFellBack = true;
+		return fields;
+	}
+
 	#snapshot(
 		job: AsyncJob,
 		timedOut = false,
@@ -608,7 +631,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			label: sanitizeText(job.label, RECEIPT_PREVIEW_WIDTH),
 			agent: subagent?.agent ?? "unknown",
 			agentSource: subagent?.agentSource ?? "bundled",
-			durationMs: Math.max(0, Date.now() - job.startTime),
+			durationMs: jobElapsedMs(job),
 			...(subagent?.description ? { description: sanitizeText(subagent.description, RECEIPT_PREVIEW_WIDTH) } : {}),
 			...(verbosity === "full" && subagent?.assignment
 				? { assignment: sanitizeText(subagent.assignment, FULL_PREVIEW_WIDTH) }
@@ -622,6 +645,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 				: {}),
 			...(outputRef ? { outputRef } : {}),
 			...(runningTimeoutGuidance ? { guidance: runningTimeoutGuidance } : {}),
+			...this.#modelFields(record),
 		};
 	}
 

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;
 }