@gajae-code/coding-agent 0.4.5 → 0.5.1

package/src/skill-state/workflow-hud.ts

@@ -21,6 +21,8 @@ interface RalplanHudState extends WorkflowGateHudState {
 	stage?: string;
 	waiting?: string;
 	iteration?: number;
+	iterationFromIndex?: number;
+	stages?: string;
 	verdict?: string;
 	latestSummary?: string;
 	pendingApproval?: boolean;
@@ -100,6 +102,95 @@ export function buildDeepInterviewHudSummary(state: DeepInterviewHudState): Work
 	};
 }
 
+export interface DeepInterviewHudDeriveOptions {
+	phase?: string;
+	specStatus?: string;
+	updatedAt?: string;
+}
+
+function diIsPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function latestScoredAmbiguity(rounds: unknown): number | undefined {
+	if (!Array.isArray(rounds)) return undefined;
+	for (let index = rounds.length - 1; index >= 0; index--) {
+		const round = rounds[index];
+		if (diIsPlainObject(round) && round.lifecycle === "scored" && typeof round.ambiguity === "number") {
+			return round.ambiguity;
+		}
+	}
+	return undefined;
+}
+
+function weakestDimensionFromTopology(
+	topology: Record<string, unknown>,
+	targetComponent: string | undefined,
+): string | undefined {
+	if (!Array.isArray(topology.components)) return undefined;
+	const components = topology.components.filter(diIsPlainObject);
+	const dimensionOf = (component: Record<string, unknown>): string | undefined =>
+		typeof component.weakest_dimension === "string" && component.weakest_dimension.trim()
+			? component.weakest_dimension
+			: undefined;
+	if (targetComponent) {
+		const targeted = components.find(component => component.id === targetComponent && dimensionOf(component));
+		if (targeted) return dimensionOf(targeted);
+	}
+	const active = components.find(component => component.status !== "deferred" && dimensionOf(component));
+	if (active) return dimensionOf(active);
+	const any = components.find(component => dimensionOf(component));
+	return any ? dimensionOf(any) : undefined;
+}
+
+/**
+ * Single source of deep-interview HUD derivation. Reads a complete (normalized)
+ * mode-state envelope so recorder, `gjc state write`, reconcile, seed, and handoff
+ * all produce identical chips. Topology-aware `target`/`weakest` come from
+ * `state.topology`; `legacy_missing` topology omits those chips (no synthetic values).
+ */
+export function deriveDeepInterviewHud(
+	payload: Record<string, unknown>,
+	options: DeepInterviewHudDeriveOptions = {},
+): WorkflowHudSummary {
+	const stateField = diIsPlainObject(payload.state) ? payload.state : {};
+	const isNumber = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+	const isArray = (value: unknown): value is unknown[] => Array.isArray(value);
+	const pick = <T>(key: string, guard: (value: unknown) => value is T): T | undefined => {
+		const value = stateField[key] ?? payload[key];
+		return guard(value) ? value : undefined;
+	};
+
+	const phase = options.phase ?? (typeof payload.current_phase === "string" ? payload.current_phase : undefined);
+	const rounds = pick("rounds", isArray);
+	const ambiguity = pick("current_ambiguity", isNumber) ?? latestScoredAmbiguity(rounds);
+	const threshold = pick("threshold", isNumber);
+	const rawTopology = diIsPlainObject(stateField.topology)
+		? stateField.topology
+		: diIsPlainObject(payload.topology)
+			? payload.topology
+			: undefined;
+	// `legacy_missing` topology was never confirmed: omit target/weakest even if stale fields linger.
+	const topology = rawTopology && rawTopology.status !== "legacy_missing" ? rawTopology : undefined;
+	const targetComponent =
+		topology && typeof topology.last_targeted_component_id === "string"
+			? topology.last_targeted_component_id
+			: undefined;
+	const weakestDimension = topology ? weakestDimensionFromTopology(topology, targetComponent) : undefined;
+	const specStatus = options.specStatus ?? (typeof payload.spec_status === "string" ? payload.spec_status : undefined);
+
+	return buildDeepInterviewHudSummary({
+		phase,
+		ambiguity,
+		threshold,
+		roundCount: rounds?.length,
+		targetComponent,
+		weakestDimension,
+		specStatus,
+		updatedAt: options.updatedAt ?? new Date().toISOString(),
+	});
+}
+
 export function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSummary {
 	const verdict = state.verdict?.toUpperCase();
 	const verdictSeverity =
@@ -118,7 +209,14 @@ export function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSumma
 			...gateChips(state, 6),
 			chip("stage", state.stage, 10),
 			chip("waiting", state.waiting, 20),
-			chip("iter", state.iteration === undefined ? undefined : String(state.iteration), 30),
+			chip(
+				"iter",
+				(state.iterationFromIndex ?? state.iteration) === undefined
+					? undefined
+					: String(state.iterationFromIndex ?? state.iteration),
+				30,
+			),
+			chip("stages", state.stages, 35),
 			chip("verdict", verdict, 40, verdictSeverity),
 		]),
 		...(state.updatedAt ? { updated_at: state.updatedAt } : {}),
@@ -136,17 +234,15 @@ export function buildUltragoalHudSummary(state: UltragoalHudState): WorkflowHudS
 			chip("goals", `${complete}/${total}`, 10),
 			chip("current", state.currentGoal ? `${state.currentGoal.id}:${state.currentGoal.title}` : state.status, 20),
 			chip("status", state.status, 30, state.status === "complete" ? "success" : undefined),
+			chip(
+				"ledger",
+				state.latestLedgerEvent?.event
+					? [state.latestLedgerEvent.event, state.latestLedgerEvent.goalId].filter(Boolean).join(":")
+					: undefined,
+				35,
+			),
 			...gateChips(state, 40),
 		]),
-		details: state.latestLedgerEvent
-			? compactChips([
-					chip(
-						"ledger",
-						[state.latestLedgerEvent.event, state.latestLedgerEvent.goalId].filter(Boolean).join(":"),
-						100,
-					),
-				])
-			: undefined,
 		...(state.updatedAt ? { updated_at: state.updatedAt } : {}),
 	};
 }

package/src/slash-commands/builtin-registry.ts

@@ -4,6 +4,7 @@ import type { ThinkingLevel } from "@gajae-code/agent-core";
 import { type Model, modelsAreEqual } from "@gajae-code/ai";
 import { getOAuthProviders } from "@gajae-code/ai/utils/oauth";
 import { setProjectDir } from "@gajae-code/utils";
+import { jobElapsedMs } from "../async";
 import {
 	GJC_MODEL_ASSIGNMENT_TARGET_IDS,
 	GJC_MODEL_ASSIGNMENT_TARGETS,
@@ -506,14 +507,14 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			if (snapshot.running.length > 0) {
 				lines.push("", "Running Jobs");
 				for (const job of snapshot.running) {
-					lines.push(`  [${job.id}] ${job.type} (${job.status}) — ${formatDuration(now - job.startTime)}`);
+					lines.push(`  [${job.id}] ${job.type} (${job.status}) — ${formatDuration(jobElapsedMs(job, now))}`);
 					lines.push(`    ${job.label}`);
 				}
 			}
 			if (snapshot.recent.length > 0) {
 				lines.push("", "Recent Jobs");
 				for (const job of snapshot.recent) {
-					lines.push(`  [${job.id}] ${job.type} (${job.status}) — ${formatDuration(now - job.startTime)}`);
+					lines.push(`  [${job.id}] ${job.type} (${job.status}) — ${formatDuration(jobElapsedMs(job, now))}`);
 					lines.push(`    ${job.label}`);
 				}
 			}

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,20 +1137,39 @@ 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,
 				});
 			}
+			// Record which model the subagent actually runs on (and any auth fallback,
+			// see #985) so the subagent panel can surface it to the user.
+			if (model) {
+				AsyncJobManager.instance()?.updateSubagentModel?.(options.subagentId ?? id, {
+					requestedModel: modelSubstitutionWarning?.requested ?? resolvedModelString,
+					effectiveModel: resolvedModelString,
+					modelFellBack: authFallbackUsed === true,
+				});
+			}
 			if (model?.contextWindow && model.contextWindow > 0) {
 				progress.contextWindow = model.contextWindow;
 			}
 			const effectiveThinkingLevel = explicitThinkingLevel
 				? resolvedThinkingLevel
 				: (thinkingLevel ?? resolvedThinkingLevel);
+			effectiveThinkingLevelForWarning = effectiveThinkingLevel;
 
 			const sessionManager = sessionFile
 				? await awaitAbortable(SessionManager.open(sessionFile))
@@ -1174,6 +1231,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 +1473,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 +1494,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 +1529,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 +1713,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);
+}