claudeup 6.3.2 → 6.5.0

package/src/services/models-core.ts

@@ -0,0 +1,628 @@
+/**
+ * Per-subagent model routing — the pure core.
+ *
+ * Claude Code has no per-agent model or effort knob that a project can set. Agent frontmatter
+ * is static, settings has one global `model`/`effortLevel`, and `CLAUDE_CODE_SUBAGENT_MODEL`
+ * is one model for every subagent. The one dynamic seam is a `PreToolUse` hook, which may
+ * rewrite the `Agent` tool's input.
+ *
+ * EVERY RULE BELOW IS MEASURED, not inferred. `benches/agent-model-routing/` (AMR-1) ran nine
+ * variants over one scenario on the interactive path, 2026-09-09, Claude Code 2.1.263,
+ * n=5 per run, 50 sessions, every run 5/5 or 0/5:
+ *
+ *   1. Injecting `updatedInput.model` DOES decide the spawned subagent's model.
+ *      `hook-named` 5/5 (subagent on claude-haiku-4-5-20251001) vs `nohook` 0/5 (inherited
+ *      claude-sonnet-5). One-sided Fisher p = 0.004.
+ *   2. `hookEventName` is REQUIRED. The payload without it ran on all five passes and changed
+ *      nothing — so ALWAYS emit it.
+ *   3. `permissionDecision: "allow"` is neither required nor harmful, so it is NOT emitted:
+ *      it would widen permission for the call in exchange for nothing.
+ *   4. The value is SCHEMA-CHECKED. A non-alias string refused the spawn outright on all five
+ *      passes — the session reports a tool error and gets no subagent at all. Hence
+ *      `isRoutableModel` below, and hence the hook re-checks the value even though the writer
+ *      already validated it (see `evaluateAgentHook`).
+ *   5. Per-model effort DOES reach a subagent, and ALIAS keys work:
+ *      `modelSettings: {"opus": {effortLevel: "low"}}` put the opus subagent at `low` while
+ *      the sonnet main thread stayed `high` (5/5), against 0/5 with no modelSettings.
+ *   6. When a full model id and an alias key are BOTH present for one model and disagree, the
+ *      FULL ID WINS (`effort-conflict` came back `xhigh`, the full-id value, 5/5). This is why
+ *      `buildSettingsPatch` emits both forms with the same value rather than picking one:
+ *      whichever the runtime prefers, they agree, and a user whose `/effort` already wrote a
+ *      full-id entry cannot silently override the project's intent.
+ *
+ * This module is PURE: no fs, no process, no network. Everything that touches disk lives in
+ * `models-manager.ts`, and the hook entry point is `cli/hook.ts`. That split is what lets the
+ * hook — which Claude Code spawns on every single Agent call — stay small and fast, and lets
+ * every rule above be tested without a Claude session.
+ */
+
+/** The model aliases Claude Code's Agent tool accepts. Measured: anything else is refused. */
+export const MODEL_ALIASES = ["opus", "sonnet", "haiku", "fable"] as const;
+export type ModelAlias = (typeof MODEL_ALIASES)[number];
+
+/** Effort levels the settings vocabulary accepts. `max` is frontmatter-only; we never write it. */
+export const EFFORTS = ["low", "medium", "high", "xhigh"] as const;
+export type Effort = (typeof EFFORTS)[number];
+
+/**
+ * Grades are named for the ROLE they serve, not for a rank.
+ *
+ * `critical` is the smartest model, and it is deliberately not the orchestrator's: the work
+ * that benefits from the strongest model is architecture, planning and review, while the
+ * thread that dispatches them mostly routes and summarises.
+ */
+export const GRADES = ["smart", "normal", "cheap"] as const;
+export type Grade = (typeof GRADES)[number];
+
+/** An agent's model: an alias, or `inherit` to leave the call alone. */
+export type AgentModel = ModelAlias | "inherit";
+/** The main thread may also ask for a long-context variant. */
+export type MainModel = ModelAlias | `${ModelAlias}[1m]`;
+
+export interface GradeSpec {
+	model: AgentModel;
+	/** Applied through `modelSettings`, keyed by this model. See rule 5 above. */
+	effort?: Effort;
+}
+
+export interface MainSpec {
+	model: MainModel;
+	effort?: Effort;
+}
+
+/** An agent is assigned a grade by name, or overridden with its own model. */
+export type AgentAssignment = Grade | { model: AgentModel; effort?: Effort };
+
+export interface ModelsConfig {
+	version: 1;
+	/** A built-in preset's name, or "custom" once hand-edited. Never load-bearing. */
+	preset: string;
+	main: MainSpec;
+	grades: Record<Grade, GradeSpec>;
+	agents: Record<string, AgentAssignment>;
+	/** Grade for an agent with no assignment. */
+	fallback: Grade;
+}
+
+export interface ValidationError {
+	path: string;
+	message: string;
+}
+
+const isRec = (v: unknown): v is Record<string, unknown> =>
+	typeof v === "object" && v !== null && !Array.isArray(v);
+
+export function isModelAlias(v: unknown): v is ModelAlias {
+	return (
+		typeof v === "string" && (MODEL_ALIASES as readonly string[]).includes(v)
+	);
+}
+
+export function isEffort(v: unknown): v is Effort {
+	return typeof v === "string" && (EFFORTS as readonly string[]).includes(v);
+}
+
+export function isGrade(v: unknown): v is Grade {
+	return typeof v === "string" && (GRADES as readonly string[]).includes(v);
+}
+
+/**
+ * Is this a value the Agent tool will accept as `model`?
+ *
+ * Measured (AMR-1 `bogus-model`, 5/5): a non-alias refuses the spawn, the session reports a
+ * tool error, and the agent cannot work around it. So this is checked in THREE places on
+ * purpose — at write time, at install time, and again in the hook — because the cost of a bad
+ * value is not a bad model, it is every subagent spawn failing for everyone who pulled the
+ * config.
+ */
+export function isRoutableModel(v: unknown): v is ModelAlias {
+	return isModelAlias(v);
+}
+
+/** Strip a `[1m]` (or any bracketed) suffix to get the underlying alias. */
+export function baseAlias(model: string): string {
+	const i = model.indexOf("[");
+	return i === -1 ? model : model.slice(0, i);
+}
+
+/**
+ * Validate a parsed `models.json`. Returns [] when `raw` is a usable ModelsConfig.
+ *
+ * Hand-rolled rather than schema-library-driven, matching `manifest.ts validateManifest`:
+ * claudeup ships no validation dependency, and the errors here are meant to be read by a
+ * person fixing a committed file.
+ */
+export function validateModelsConfig(raw: unknown): ValidationError[] {
+	const errors: ValidationError[] = [];
+	const err = (path: string, message: string) => errors.push({ path, message });
+
+	if (!isRec(raw)) return [{ path: "", message: "must be a JSON object" }];
+
+	if (raw.version !== 1) {
+		err("version", `must be 1, got ${JSON.stringify(raw.version)}`);
+		// Everything below assumes v1's shape; reading on would produce noise, not findings.
+		return errors;
+	}
+
+	if (typeof raw.preset !== "string" || raw.preset.length === 0) {
+		err("preset", 'must be a non-empty string (a built-in name, or "custom")');
+	}
+
+	// ── main ────────────────────────────────────────────────────────────────────────────
+	if (!isRec(raw.main)) {
+		err("main", "must be an object with a `model`");
+	} else {
+		const m = raw.main.model;
+		if (typeof m !== "string") {
+			err("main.model", "must be a string");
+		} else if (m === "inherit") {
+			err(
+				"main.model",
+				"`inherit` is for agents only — the main thread needs a real model",
+			);
+		} else if (!isModelAlias(baseAlias(m))) {
+			err(
+				"main.model",
+				`must be one of ${MODEL_ALIASES.join(", ")} (optionally with a [1m] suffix), got ${JSON.stringify(m)}. Full model ids are rejected: they go stale, and an alias always names the current model`,
+			);
+		} else if (m !== baseAlias(m) && !/^[a-z]+\[1m\]$/.test(m)) {
+			err(
+				"main.model",
+				`only a [1m] suffix is understood, got ${JSON.stringify(m)}`,
+			);
+		}
+		if (raw.main.effort !== undefined && !isEffort(raw.main.effort)) {
+			err("main.effort", `must be one of ${EFFORTS.join(", ")}`);
+		}
+	}
+
+	// ── grades ──────────────────────────────────────────────────────────────────────────
+	if (!isRec(raw.grades)) {
+		err("grades", `must be an object with the keys ${GRADES.join(", ")}`);
+	} else {
+		for (const g of GRADES) {
+			const spec = raw.grades[g];
+			if (!isRec(spec)) {
+				err(`grades.${g}`, "must be an object with a `model`");
+				continue;
+			}
+			if (spec.model !== "inherit" && !isModelAlias(spec.model)) {
+				err(
+					`grades.${g}.model`,
+					`must be one of ${MODEL_ALIASES.join(", ")} or "inherit", got ${JSON.stringify(spec.model)}`,
+				);
+			}
+			if (spec.model === "inherit" && spec.effort !== undefined) {
+				err(
+					`grades.${g}.effort`,
+					"cannot set effort on `inherit` — effort is applied per model, and inherit names no model",
+				);
+			}
+			if (spec.effort !== undefined && !isEffort(spec.effort)) {
+				err(`grades.${g}.effort`, `must be one of ${EFFORTS.join(", ")}`);
+			}
+		}
+		for (const key of Object.keys(raw.grades)) {
+			if (!isGrade(key))
+				err(
+					`grades.${key}`,
+					`unknown grade — expected one of ${GRADES.join(", ")}`,
+				);
+		}
+	}
+
+	// ── fallback ────────────────────────────────────────────────────────────────────────
+	// Named `fallback`, not `default`: it answers a different question from the tiers —
+	// not "how much model", but "what an agent gets when nothing names it at all".
+	if (!isGrade(raw.fallback)) {
+		err("fallback", `must name a tier: ${GRADES.join(", ")}`);
+	}
+
+	// ── agents ──────────────────────────────────────────────────────────────────────────
+	if (raw.agents !== undefined && !isRec(raw.agents)) {
+		err(
+			"agents",
+			"must be an object mapping subagent_type to a grade name or {model}",
+		);
+	} else if (isRec(raw.agents)) {
+		for (const [name, value] of Object.entries(raw.agents)) {
+			if (typeof value === "string") {
+				if (!isGrade(value)) {
+					err(
+						`agents.${name}`,
+						`must name a grade (${GRADES.join(", ")}) or be an object with a model`,
+					);
+				}
+				continue;
+			}
+			if (!isRec(value)) {
+				err(
+					`agents.${name}`,
+					"must be a grade name or an object with a `model`",
+				);
+				continue;
+			}
+			if (value.model !== "inherit" && !isModelAlias(value.model)) {
+				err(
+					`agents.${name}.model`,
+					`must be one of ${MODEL_ALIASES.join(", ")} or "inherit", got ${JSON.stringify(value.model)}`,
+				);
+			}
+			if (value.effort !== undefined && !isEffort(value.effort)) {
+				err(`agents.${name}.effort`, `must be one of ${EFFORTS.join(", ")}`);
+			}
+			if (value.model === "inherit" && value.effort !== undefined) {
+				err(
+					`agents.${name}.effort`,
+					"cannot set effort on `inherit` — effort is applied per model",
+				);
+			}
+		}
+	}
+
+	// ── one model, one effort ───────────────────────────────────────────────────────────
+	// `modelSettings` is keyed by MODEL, so two entries naming the same model cannot carry
+	// different efforts — one would silently lose. The main thread counts: `main.effort` IS
+	// the effort of `main.model`. Reported as a conflict rather than resolved, because there
+	// is no defensible way to pick a winner on the author's behalf.
+	if (errors.length === 0) {
+		const cfg = raw as unknown as ModelsConfig;
+		const claims = new Map<string, { effort: Effort; at: string }>();
+		const claim = (model: string, effort: Effort | undefined, at: string) => {
+			if (effort === undefined || model === "inherit") return;
+			const key = baseAlias(model);
+			const prior = claims.get(key);
+			if (prior && prior.effort !== effort) {
+				err(
+					at,
+					`${key} is already set to effort "${prior.effort}" by ${prior.at}. Effort is applied per model, so one model cannot carry two efforts — give them different models, or use the same effort`,
+				);
+				return;
+			}
+			if (!prior) claims.set(key, { effort, at });
+		};
+		claim(cfg.main.model, cfg.main.effort, "main");
+		for (const g of GRADES)
+			claim(cfg.grades[g].model, cfg.grades[g].effort, `grades.${g}`);
+		for (const [name, value] of Object.entries(cfg.agents ?? {})) {
+			if (typeof value !== "string")
+				claim(value.model, value.effort, `agents.${name}`);
+		}
+	}
+
+	return errors;
+}
+
+export interface Routing {
+	model: AgentModel;
+	effort?: Effort;
+	/** Where the answer came from — surfaced by `models status` and the hook's log. */
+	source: "agent-override" | "agent-grade" | "default-grade";
+	grade?: Grade;
+}
+
+/**
+ * Which model and effort should serve `subagentType`?
+ *
+ * An unknown agent falls to `fallback`, which is why a new plugin agent routes sensibly on the
+ * day it appears rather than silently inheriting the orchestrator's model.
+ */
+export function resolveAgentRouting(
+	config: ModelsConfig,
+	subagentType: string | undefined,
+): Routing {
+	const assignment =
+		subagentType === undefined ? undefined : config.agents?.[subagentType];
+
+	if (assignment !== undefined && typeof assignment !== "string") {
+		const out: Routing = { model: assignment.model, source: "agent-override" };
+		if (assignment.effort !== undefined) out.effort = assignment.effort;
+		return out;
+	}
+	const grade: Grade =
+		typeof assignment === "string" ? assignment : config.fallback;
+	const spec = config.grades[grade];
+	const out: Routing = {
+		model: spec.model,
+		source: typeof assignment === "string" ? "agent-grade" : "default-grade",
+		grade,
+	};
+	if (spec.effort !== undefined) out.effort = spec.effort;
+	return out;
+}
+
+export interface AgentHookPayload {
+	hook_event_name?: string;
+	tool_name?: string;
+	tool_input?: Record<string, unknown>;
+	cwd?: string;
+}
+
+export type AgentHookDecision =
+	| {
+			kind: "passthrough";
+			reason:
+				| "not-agent"
+				| "no-config"
+				| "invalid-config"
+				| "explicit-model"
+				| "inherit"
+				| "unroutable-model";
+	  }
+	| {
+			kind: "update";
+			model: ModelAlias;
+			output: {
+				hookSpecificOutput: {
+					hookEventName: "PreToolUse";
+					updatedInput: Record<string, unknown>;
+				};
+			};
+	  };
+
+/**
+ * Decide what the hook should print. Pure — `cli/hook.ts` supplies the payload and the config.
+ *
+ * FAIL OPEN, ALWAYS. Every branch that is not a confident rewrite is a passthrough, because
+ * this runs on every Agent call in every session on the machine. A hook that blocks or errors
+ * takes the user's subagents with it, and the worst outcome available is a config typo that
+ * makes delegation stop working everywhere with no clue why.
+ *
+ * `hookEventName` is emitted because AMR-1 measured it as required (the payload without it
+ * fired and was ignored, 5/5). `permissionDecision` is NOT emitted: it was measured as
+ * neither required nor harmful, so emitting it would widen permission for nothing.
+ */
+export function evaluateAgentHook(
+	payload: AgentHookPayload,
+	config: ModelsConfig | null,
+): AgentHookDecision {
+	if (payload.tool_name !== "Agent")
+		return { kind: "passthrough", reason: "not-agent" };
+	if (config === null) return { kind: "passthrough", reason: "no-config" };
+
+	const toolInput = payload.tool_input ?? {};
+
+	// A model the caller set wins by Claude Code's own precedence (per-invocation > frontmatter
+	// > env > session). Overriding it would silently discard a deliberate choice.
+	if (typeof toolInput.model === "string" && toolInput.model.length > 0) {
+		return { kind: "passthrough", reason: "explicit-model" };
+	}
+
+	const subagentType =
+		typeof toolInput.subagent_type === "string"
+			? toolInput.subagent_type
+			: undefined;
+	const routing = resolveAgentRouting(config, subagentType);
+
+	// `inherit` is the opt-out: leave the call exactly as it was, so the agent's own
+	// frontmatter (or the session model) decides.
+	if (routing.model === "inherit")
+		return { kind: "passthrough", reason: "inherit" };
+
+	// Belt and braces over the writer's validation. A hand-edited profile or an older claudeup
+	// can put an unroutable value here, and MEASURED (AMR-1 `bogus-model`) that does not
+	// degrade — it refuses the spawn outright. Passing through costs the routing; injecting
+	// costs the user every subagent.
+	if (!isRoutableModel(routing.model))
+		return { kind: "passthrough", reason: "unroutable-model" };
+
+	return {
+		kind: "update",
+		model: routing.model,
+		output: {
+			hookSpecificOutput: {
+				hookEventName: "PreToolUse",
+				// updatedInput REPLACES the tool input wholesale, so it must carry everything
+				// the caller sent, not just the field being changed.
+				updatedInput: { ...toolInput, model: routing.model },
+			},
+		},
+	};
+}
+
+export interface SettingsPatch {
+	/** Keys to set on the settings object. */
+	set: Record<string, unknown>;
+	/** Top-level keys to delete (used by `models off`). */
+	unset: string[];
+}
+
+/**
+ * The settings a config implies: the main thread's model and effort, plus per-model effort for
+ * every distinct model any grade or agent names.
+ *
+ * `resolveFullId` maps an alias to the full model id this machine currently runs (resolved
+ * LIVE by the caller — never a table in this repo, which would go stale). BOTH key forms are
+ * written with the same value, which is the direct consequence of AMR-1's `effort-conflict`
+ * run: when both forms are present and disagree, the full id wins. Writing both means they
+ * cannot disagree, so it does not matter which the runtime prefers, and a full-id entry a user
+ * left behind with `/effort` cannot quietly override the project's intent.
+ */
+export function buildSettingsPatch(
+	config: ModelsConfig,
+	resolveFullId: (alias: ModelAlias) => string | null,
+): SettingsPatch {
+	const set: Record<string, unknown> = {};
+	set.model = config.main.model;
+	if (config.main.effort !== undefined) set.effortLevel = config.main.effort;
+
+	const modelSettings: Record<string, { effortLevel: Effort }> = {};
+	const add = (model: string, effort: Effort | undefined) => {
+		if (effort === undefined || model === "inherit") return;
+		const alias = baseAlias(model);
+		if (!isModelAlias(alias)) return;
+		modelSettings[alias] = { effortLevel: effort };
+		const full = resolveFullId(alias);
+		// A resolver that cannot answer leaves the alias key alone rather than inventing an id.
+		if (full) modelSettings[full] = { effortLevel: effort };
+	};
+	add(config.main.model, config.main.effort);
+	for (const g of GRADES) add(config.grades[g].model, config.grades[g].effort);
+	for (const value of Object.values(config.agents ?? {})) {
+		if (typeof value !== "string") add(value.model, value.effort);
+	}
+
+	if (Object.keys(modelSettings).length > 0) set.modelSettings = modelSettings;
+	return { set, unset: [] };
+}
+
+export type ModelsState = "off" | "on" | "stale" | "invalid" | "unhooked";
+
+export interface ModelsStatus {
+	state: ModelsState;
+	preset: string | null;
+	/** Human-readable differences between what the config asks for and what settings hold. */
+	drift: string[];
+	warnings: string[];
+}
+
+/**
+ * What `models status` and `doctor` report.
+ *
+ * `unhooked` outranks `stale`, deliberately: a config with no hook registered routes NOTHING,
+ * so reporting a drifted effort value first would bury the reason nothing is happening.
+ */
+export function computeModelsStatus(args: {
+	config: ModelsConfig | null;
+	errors: ValidationError[];
+	hookRegistered: boolean;
+	settings: Record<string, unknown>;
+	resolveFullId: (alias: ModelAlias) => string | null;
+	subagentModelEnv?: string | null;
+}): ModelsStatus {
+	const {
+		config,
+		errors,
+		hookRegistered,
+		settings,
+		resolveFullId,
+		subagentModelEnv,
+	} = args;
+	const warnings: string[] = [];
+
+	if (subagentModelEnv) {
+		warnings.push(
+			`CLAUDE_CODE_SUBAGENT_MODEL is set to "${subagentModelEnv}". Per-call routing wins over it, so it now has no effect on routed agents — consider unsetting it.`,
+		);
+	}
+
+	if (errors.length > 0) {
+		return {
+			state: "invalid",
+			preset: null,
+			drift: errors.map((e) => `${e.path || "(root)"}: ${e.message}`),
+			warnings,
+		};
+	}
+	if (config === null)
+		return { state: "off", preset: null, drift: [], warnings };
+	if (!hookRegistered) {
+		return {
+			state: "unhooked",
+			preset: config.preset,
+			drift: ["the agent-model hook is not registered, so nothing is routed"],
+			warnings,
+		};
+	}
+
+	const patch = buildSettingsPatch(config, resolveFullId);
+	const entries = Object.entries(patch.set);
+	const differing = entries.filter(
+		([key, want]) => JSON.stringify(settings[key]) !== JSON.stringify(want),
+	);
+
+	// Nothing written at all is ONE fact, not three. Listing `model`, `effortLevel` and
+	// `modelSettings` separately when every one of them is absent reads as three distinct
+	// problems and buries the only thing that matters: no settings were ever written here.
+	const allMissing =
+		differing.length === entries.length &&
+		differing.every(([key]) => settings[key] === undefined);
+
+	const drift = allMissing
+		? ["settings carry none of the config — none of it is in force"]
+		: differing.map(([key, want]) => describeDrift(key, settings[key], want));
+
+	return {
+		state: drift.length ? "stale" : "on",
+		preset: config.preset,
+		drift,
+		warnings,
+	};
+}
+
+/**
+ * One human-readable drift line.
+ *
+ * Three things this deliberately does NOT do, each a defect it replaced:
+ *
+ *   - `JSON.stringify(undefined)` returns `undefined` — the string, not a value — so an
+ *     absent key printed as `settings has undefined`, leaking a JavaScript value into text
+ *     a person reads. Absent is now said in words.
+ *   - `modelSettings` printed as raw JSON was a 200-character wall nobody parses.
+ *   - Quoting every scalar (`config wants "opus"`) adds noise; a model name is a word.
+ */
+function describeDrift(key: string, have: unknown, want: unknown): string {
+	// `modelSettings` is DIFFED rather than summarised on both sides.
+	//
+	// Summarising it was the wrong shape, and hiding the full-id keys to keep the summary
+	// short made it actively wrong: the patch writes every model twice (alias + live-resolved
+	// full id), and the side that differs is almost always the full id — which is also the
+	// side that WINS at runtime (AMR-1 rule 6 above). So the line could print
+	// `settings has opus xhigh, config wants opus xhigh` — X differs from X — while the key
+	// actually serving subagents at another effort was the one suppressed. That happens with
+	// no hand-editing at all: apply a preset, wait for the next model release, and the stored
+	// full id no longer matches the resolved one.
+	//
+	// Diffing cannot produce that line, because a key only appears when its two sides differ.
+	if (key === "modelSettings" && isRec(have) && isRec(want)) {
+		const changed = modelSettingsDiff(have, want);
+		if (changed.length > 0) return `modelSettings: ${changed.join(", ")}`;
+	}
+	return `${key}: settings ${have === undefined ? "has no value" : `has ${describeValue(have)}`}, config wants ${describeValue(want)}`;
+}
+
+/** A value as a person would say it, never as JSON. */
+function describeValue(v: unknown): string {
+	if (v === undefined) return "nothing";
+	if (typeof v === "string") return v;
+	if (v && typeof v === "object") return describeModelSettings(v);
+	return JSON.stringify(v);
+}
+
+/** The `effortLevel` inside one `modelSettings` entry, or null when there is not one. */
+function effortOf(spec: unknown): string | null {
+	if (!spec || typeof spec !== "object") return null;
+	const level = (spec as { effortLevel?: unknown }).effortLevel;
+	return typeof level === "string" ? level : null;
+}
+
+/**
+ * Every model whose effort differs between the two maps, as `opus xhigh → high`.
+ *
+ * Keys are taken from BOTH sides and sorted, so a model present in only one of them still
+ * appears — an entry `/effort` left behind in settings is exactly the case worth seeing, and
+ * a summary of one side alone can never show it.
+ */
+function modelSettingsDiff(
+	have: Record<string, unknown>,
+	want: Record<string, unknown>,
+): string[] {
+	const models = new Set([...Object.keys(have), ...Object.keys(want)]);
+	const out: string[] = [];
+	for (const model of [...models].sort()) {
+		const h = effortOf(have[model]);
+		const w = effortOf(want[model]);
+		if (h === w) continue;
+		out.push(`${model} ${h ?? "unset"} → ${w ?? "unset"}`);
+	}
+	return out;
+}
+
+/** `modelSettings` as `opus xhigh, fable medium`, for the one-sided case. */
+function describeModelSettings(v: object): string {
+	const parts: string[] = [];
+	for (const [model, spec] of Object.entries(v as Record<string, unknown>)) {
+		parts.push(`${model} ${effortOf(spec) ?? "unset"}`);
+	}
+	return parts.length ? parts.join(", ") : "nothing";
+}