magus-cli 0.0.0-placeholder → 7.1.0

package/src/services/models-core.ts

@@ -0,0 +1,969 @@
+/**
+ * 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];
+
+/**
+ * Subagents whose model is a third-party external one, reached through claudish rather than
+ * through Claude Code's own aliases.
+ *
+ * Named for what they are to this tool: someone else's model, helping out. `kangaroo` is
+ * `mate3` — it is a joke, and it is load-bearing only in the sense that nobody mistakes it
+ * for a Claude alias.
+ *
+ * These are NOT routable. `MODEL_ALIASES` is the entire set the Agent tool accepts, and
+ * AMR-1 measured that anything else refuses the spawn (5/5). A mate therefore behaves like
+ * `inherit` at the hook: magus declines to rewrite the call, and whatever claudish or the
+ * agent's own frontmatter decides is what runs.
+ */
+export const MATES = ["mate1", "mate2", "kangaroo"] as const;
+export type Mate = (typeof MATES)[number];
+
+/**
+ * An agent's model: an alias, `inherit` to leave the call alone, or a mate.
+ *
+ * A mate is the second opt-out, and it says something `inherit` does not: `inherit` means the
+ * author declined to decide, a mate means the author sent this agent somewhere magus has
+ * no say over. Both produce the same hook behaviour and different words on screen.
+ */
+export type AgentModel = ModelAlias | "inherit" | Mate;
+
+/**
+ * What a slot is BOUND to: a real external model, and optionally an effort for it.
+ *
+ * A slot is a ROLE — "the first external helper" — and a role is not a model. Until this
+ * existed the screen had nothing else to print in its Model column and printed the slot name
+ * there, so a row read `mate1 mate1 —`: the same word twice, neither of them naming a model.
+ *
+ * `model` is a BARE CATALOG ID (`grok-4.6`), never an `openrouterId` (`moonshotai/kimi-k3`)
+ * and never an Access route (`kc@kimi-k3`). Both of those forms PIN THE PROVIDER, which
+ * bypasses claudish's subscription-aware routing — the committed file should record the
+ * model's IDENTITY and leave the route to the thing that owns routing. The validator rejects
+ * `/` and `@` for exactly that reason, and says so.
+ */
+export interface MateBinding {
+	/** A bare catalog id. No `@`, no `/` — see above. */
+	model: string;
+	/**
+	 * DECLARED, not applied. magus writes it and nothing in magus reads it back:
+	 * effort reaches a Claude subagent through `settings.modelSettings`, which is keyed by
+	 * models Claude Code runs, and an external model has no key there. It is here for
+	 * claudish to read. Every place it is drawn says so — see `effortWord`.
+	 */
+	effort?: Effort;
+}
+
+/** The bindings, by slot. A slot may be absent: unbound is legal, and renders as unset. */
+export type MatesConfig = Partial<Record<Mate, MateBinding>>;
+/**
+ * The main thread may also ask for a long-context variant.
+ *
+ * Deliberately NOT widened to `Mate`. magus writes `main.model` straight into
+ * `settings.model`, which has to name a model Claude Code itself runs — a mate names one it
+ * has never heard of. The validator rejects it and says so; see `validateModelsConfig`.
+ */
+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;
+	/**
+	 * Which external model each slot names. Optional in full: every config written before
+	 * this existed stays valid, and an unbound slot renders as unset rather than erroring.
+	 */
+	mates?: MatesConfig;
+	/**
+	 * The effort every slot runs at unless it names its own.
+	 *
+	 * A PRESET DECISION, like the grades above it. A preset cannot bind a slot to a model —
+	 * it ships in this repo and a catalogue id would go stale — but it can say how hard the
+	 * external work should try, and that is the half of the answer that does not depend on
+	 * which model serves it.
+	 *
+	 * A slot's own `mates[slot].effort` wins where it is set, so a project can raise or lower
+	 * one slot without leaving the preset. `mateEffort()` is the single place that resolution
+	 * happens.
+	 */
+	mateEffort?: Effort;
+}
+
+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 one of the three external-model slots?
+ *
+ * Exact match only, and no prefix rule: `mate1` is a slot, `mate10` is a typo, and near-
+ * matching one into the other would route an agent somewhere its author never named.
+ */
+export function isMate(v: unknown): v is Mate {
+	return typeof v === "string" && (MATES as readonly string[]).includes(v);
+}
+
+/**
+ * The values that own no `modelSettings` KEY: `inherit`, and every mate.
+ *
+ * Effort reaches a subagent through `modelSettings`, which is keyed BY MODEL (AMR-1 rule 5).
+ * `inherit` names none by construction; a mate names one Claude Code has never heard of, so
+ * a key under it could not select anything.
+ *
+ * This is now used by exactly ONE rule — the one-model-one-effort conflict pass — and it
+ * deliberately no longer gates VALIDATION. Those two questions looked identical and are not:
+ *
+ *   - "may this carry an effort at all?"  `inherit` no, a mate YES. A mate's effort is a
+ *     per-call value for claudish, not a settings key, so it is a legitimate thing to write.
+ *   - "can this collide with another effort over a shared key?"  neither, because neither
+ *     has a key to collide over. Two mates bound to the SAME external model may still carry
+ *     different efforts, and that is not a conflict for the same reason.
+ *
+ * Collapsing them back into one predicate is what made an effort on a mate a validation
+ * error in the first place.
+ */
+function namesNoKeyableModel(model: unknown): boolean {
+	return model === "inherit" || isMate(model);
+}
+
+/**
+ * Why a bare catalog id, and not the two forms that also identify a model.
+ *
+ * Both rejected forms name a ROUTE rather than an identity, and a committed file that pins a
+ * route makes every reader of it use that route — including a reader whose subscription
+ * would have served the same model directly. Routing is claudish's to decide; this file
+ * records WHICH MODEL, and nothing about how to reach it.
+ */
+const ROUTE_PINNED =
+	"pins the provider and bypasses claudish's subscription-aware routing — store the model's identity, not a route to it";
+
+/** Shape-check one `mates` entry. Returns the errors, which may be empty. */
+function validateMateBinding(slot: string, value: unknown): ValidationError[] {
+	const out: ValidationError[] = [];
+	const at = `mates.${slot}`;
+	if (!isRec(value)) {
+		return [{ path: at, message: "must be an object with a `model`" }];
+	}
+	const model = value.model;
+	if (typeof model !== "string" || model.length === 0) {
+		out.push({
+			path: `${at}.model`,
+			message:
+				"must be a non-empty string naming a model in claudish's catalogue",
+		});
+	} else if (model.includes("/")) {
+		out.push({
+			path: `${at}.model`,
+			message: `${JSON.stringify(model)} looks like an openrouterId. A provider-prefixed id ${ROUTE_PINNED}. Use the bare catalogue id — \`${model.slice(model.lastIndexOf("/") + 1)}\``,
+		});
+	} else if (model.includes("@")) {
+		out.push({
+			path: `${at}.model`,
+			message: `${JSON.stringify(model)} looks like an Access route. A \`provider@model\` selector ${ROUTE_PINNED}. Use the bare catalogue id — \`${model.slice(model.indexOf("@") + 1)}\``,
+		});
+	}
+	if (value.effort !== undefined && !isEffort(value.effort)) {
+		out.push({
+			path: `${at}.effort`,
+			message: `must be one of ${EFFORTS.join(", ")}`,
+		});
+	}
+	return out;
+}
+
+/**
+ * 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.
+ *
+ * Mates are excluded DELIBERATELY, and widening this to admit them would be the one change
+ * that turns the whole feature into an outage: a mate is a name claudish understands and the
+ * Agent tool does not, so injecting one is exactly the `bogus-model` case measured above.
+ */
+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`:
+ * magus ships no validation dependency, and the errors here are meant to be read by a
+ * person fixing a committed file.
+ *
+ * A MATE IS VALID WHEREVER AN AGENT MODEL IS, whether or not the multimodel plugin is
+ * installed on this machine. Validity is a property of the file, not of the machine reading
+ * it: a `models.json` is committed and shared, so gating `mate1` on a local install would
+ * make the same file valid on one teammate's laptop and invalid on the next one's — and the
+ * failure would land on whoever had not installed the plugin yet, over a routing decision
+ * they did not make. Whether the slots are DRAWN is a UI question, answered in the renderers.
+ */
+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 (isMate(m)) {
+			// The main thread is the one seat a mate can never take. Its model is written to
+			// `settings.model`, which Claude Code reads to start the session itself — a name
+			// only claudish understands would leave the session with no model at all, and
+			// unlike a subagent there is nothing left to fall back to.
+			err(
+				"main.model",
+				`\`${m}\` is for subagents only — magus writes main.model into settings.model, so it has to name a model Claude Code runs (${MODEL_ALIASES.join(", ")}). A mate names an external model reached through claudish, which the main thread cannot use`,
+			);
+		} 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" &&
+				!isMate(spec.model) &&
+				!isModelAlias(spec.model)
+			) {
+				err(
+					`grades.${g}.model`,
+					`must be one of ${MODEL_ALIASES.join(", ")}, "inherit", or a mate (${MATES.join(", ")}), got ${JSON.stringify(spec.model)}`,
+				);
+			}
+			// `inherit` ONLY. An effort on a MATE is valid — declared for claudish rather
+			// than written to modelSettings — so `namesNoKeyableModel` is deliberately not
+			// used here; its comment explains why the two questions are not the same one.
+			if (spec.model === "inherit" && spec.effort !== undefined) {
+				err(
+					`grades.${g}.effort`,
+					"cannot set effort on `inherit` — effort is applied per model through modelSettings, 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" &&
+				!isMate(value.model) &&
+				!isModelAlias(value.model)
+			) {
+				err(
+					`agents.${name}.model`,
+					`must be one of ${MODEL_ALIASES.join(", ")}, "inherit", or a mate (${MATES.join(", ")}), got ${JSON.stringify(value.model)}`,
+				);
+			}
+			if (value.effort !== undefined && !isEffort(value.effort)) {
+				err(`agents.${name}.effort`, `must be one of ${EFFORTS.join(", ")}`);
+			}
+			// `inherit` ONLY — see the identical rule on grades above.
+			if (value.model === "inherit" && value.effort !== undefined) {
+				err(
+					`agents.${name}.effort`,
+					"cannot set effort on `inherit` — effort is applied per model, and inherit names no model",
+				);
+			}
+		}
+	}
+
+	// ── mates ───────────────────────────────────────────────────────────────────────────
+	//
+	// VALIDATION IS OFFLINE AND CONSULTS NO CATALOGUE. Shape only — that `grok-4.6` is a
+	// plausible bare id, never that it exists.
+	//
+	// A `models.json` is committed and shared, so its validity has to be a property of the
+	// FILE. A validator that reached the network would make the same file valid on a
+	// connected laptop and invalid on a plane, and the failure would land on whoever happened
+	// to open it offline, over a routing decision they did not make. Whether a bound id is
+	// still in the live catalogue is a real question, and it is answered separately, as an
+	// ADVISORY note — `services/mate-catalog.ts`, which never blocks anything.
+	if (raw.mates !== undefined && !isRec(raw.mates)) {
+		err("mates", `must be an object keyed by ${MATES.join(", ")}`);
+	} else if (isRec(raw.mates)) {
+		for (const [slot, value] of Object.entries(raw.mates)) {
+			if (!isMate(slot)) {
+				// No near-matching: `mate10` is a typo, not `mate1`, and quietly binding one
+				// to the other would send an agent to a model its author never named.
+				err(
+					`mates.${slot}`,
+					`unknown slot — expected one of ${MATES.join(", ")}`,
+				);
+				continue;
+			}
+			for (const e of validateMateBinding(slot, value)) errors.push(e);
+		}
+	}
+
+	// ── 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) => {
+			// Mates are skipped with `inherit`, and by the same predicate: neither owns a
+			// `modelSettings` key, so neither can collide with anything over one. Two seats
+			// on `mate1` are not a conflict — they are two agents sent to claudish, which is
+			// the normal way to use a slot.
+			//
+			// This exemption now carries real weight. Mates DO carry effort (the rule was
+			// reversed), so without it two agents on `mate1` at different efforts would be
+			// reported as a conflict — and it is not one. Effort on a mate is a per-call
+			// value handed to claudish, not a settings key, so two mates bound to the very
+			// same external model may still legitimately declare different efforts.
+			if (effort === undefined || namesNoKeyableModel(model)) 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;
+}
+
+// ─── Reading a binding ────────────────────────────────────────────────────────────────────
+
+/**
+ * What the Model column shows for an unbound slot.
+ *
+ * NOT the slot name repeated, and not a blank. The slot name in a Model column is what this
+ * whole change exists to remove — it said `mate1 mate1 —` and neither word named a model. A
+ * blank would read as the `—` that means "nothing was decided", which is the opposite: the
+ * author decided to route here and has not yet said where.
+ */
+export const UNBOUND_MATE = "unset";
+
+/** The catalogue id a slot is bound to, or null when it is unbound. */
+export function boundModel(
+	config: Pick<ModelsConfig, "mates">,
+	slot: Mate,
+): string | null {
+	return config.mates?.[slot]?.model ?? null;
+}
+
+/**
+ * The effort a slot runs at: its own if it names one, otherwise the preset's.
+ *
+ * Two rungs and no third. The slot is the specific answer and wins; the preset is the
+ * general one and covers every slot that did not bother. Resolved here rather than at each
+ * call site, so the tier table, the agent table and the CLI cannot disagree about what a
+ * slot with no effort of its own is actually running at.
+ */
+export function mateEffort(
+	config: Pick<ModelsConfig, "mates" | "mateEffort">,
+	slot: Mate,
+): Effort | undefined {
+	return config.mates?.[slot]?.effort ?? config.mateEffort;
+}
+
+/**
+ * The text that names a routing value: a bound slot resolves to its model, everything else
+ * is already a model name.
+ *
+ * One function, because the Model column, its width maths and the CLI all have to print the
+ * SAME string. The renderers measure a column from this and then draw from it; the defect
+ * `modelWidth` exists to prevent — a column measured from a different string than the one
+ * rendered — is exactly what two copies of this rule would reintroduce.
+ */
+export function modelLabel(
+	config: Pick<ModelsConfig, "mates">,
+	model: string,
+): string {
+	if (!isMate(model)) return model;
+	return boundModel(config, model) ?? UNBOUND_MATE;
+}
+
+/**
+ * A config as a canonical string, for comparing two of them.
+ *
+ * Key order is normalised because the two sides come from different places: a built-in preset
+ * is a TypeScript literal and a project's config is parsed from a file, so a plain
+ * `JSON.stringify` comparison would call two identical configs different whenever the file
+ * happened to list `fallback` before `agents`.
+ */
+function canonical(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (value && typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>)
+			// `undefined` members are ABSENT, not present-and-empty: `{effort: undefined}` and
+			// `{}` describe the same routing, and a JSON round-trip turns the first into the
+			// second — so a literal compared against a parsed file would differ over nothing.
+			.filter(([, v]) => v !== undefined)
+			.sort(([a], [b]) => a.localeCompare(b));
+		return `{${entries.map(([k, v]) => `${k}:${canonical(v)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * Do these two configs describe the same routing?
+ *
+ * Exists because "is the project running a built-in" cannot be answered by NAME. `magus
+ * models use opus-lead` writes `preset: "opus-lead"`, and every hand edit afterwards — a
+ * `mates` block, a rebound agent — leaves that name untouched. A name check therefore reports
+ * a diverged config as a built-in, which is how the one config on the machine that can name a
+ * mate became invisible to the TUI.
+ */
+export function sameRouting(a: ModelsConfig, b: ModelsConfig): boolean {
+	return canonical(a) === canonical(b);
+}
+
+/** Every slot a config actually uses — assigned to a grade or to an agent. */
+export function matesInUse(config: ModelsConfig): Mate[] {
+	const seen = new Set<string>();
+	for (const grade of GRADES) seen.add(config.grades[grade].model);
+	for (const assignment of Object.values(config.agents ?? {})) {
+		if (typeof assignment !== "string") seen.add(assignment.model);
+	}
+	return MATES.filter((mate) => seen.has(mate));
+}
+
+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"
+				| "mate"
+				| "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" };
+
+	// A mate's model is claudish's to choose, not ours. Same passthrough as `inherit`, kept as
+	// its own reason so the hook log distinguishes "the author opted out" from "the author sent
+	// this one outside".
+	//
+	// BEFORE the guard below, not after: a mate would fail `isRoutableModel` too, and reporting
+	// it as `unroutable-model` would read as a broken config — the one state the log exists to
+	// make obvious — when it is the config working exactly as written.
+	if (isMate(routing.model)) return { kind: "passthrough", reason: "mate" };
+
+	// Belt and braces over the writer's validation. A hand-edited profile or an older magus
+	// 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);
+		// The `isModelAlias` gate is what keeps a MATE out of `modelSettings`, and it is the
+		// only thing that does. It is now LOAD-BEARING rather than belt-and-braces: an effort
+		// on a mate used to be a validation error, so nothing could reach here carrying one,
+		// and today it is valid and ordinary. `modelSettings` is keyed by models Claude Code
+		// RUNS — a `mate1` key selects nothing, and a `grok-4.6` key selects nothing either.
+		//
+		// A mate's effort is written to the `mates` block and read by claudish. It never
+		// reaches settings, from any path: `add()` is the only writer and this line is the
+		// only gate, so the test that pins it asserts on the whole map (no slot, no external
+		// id, no `undefined` key) rather than on this branch.
+		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: [] };
+}
+
+/**
+ * The four states routing can be in. Each is a fact the reader can act on.
+ *
+ * There is no state for "the settings differ from the config". Differing is what a CUSTOM
+ * config is, and the list says so with a `Custom` row rather than the header saying it with
+ * a warning.
+ */
+export type ModelsState = "off" | "on" | "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,
+		};
+	}
+
+	// A config whose settings differ from a built-in's is CUSTOM, and custom is not a fault.
+	//
+	// There is no comparison here any more, and no state for the result of one. A project may
+	// legitimately run models and efforts no shipped preset names; saying so as a state called
+	// `stale`, with a count of the differences, described a thing you have as a thing that is
+	// wrong with you — and the count was of MESSAGES rather than of differences, so `1 drift`
+	// could mean every setting differed.
+	//
+	// The list carries the fact instead: a config matching no built-in gets its own `Custom`
+	// row holding those settings, with its own tier table and chart. `drift` survives for the
+	// two states that ARE faults — a config that does not validate, and one with no hook to
+	// run it — where the lines name something the reader has to fix.
+	return {
+		state: "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";
+}