@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.10

package/src/model-call.ts

@@ -0,0 +1,83 @@
+/**
+ * model-call.ts -- what an agent's in-flight model call is doing right now.
+ *
+ * A single model call can sit silent for minutes (long thinking, a slow
+ * provider), and the widget used to say `thinking…` for all of it with nothing
+ * to tell a busy agent from a dead stream. This tracks the call from the
+ * session's streaming events so every surface can say how long it has been
+ * thinking, how much it has written, or that it has gone quiet.
+ */
+
+/** One streaming event from an assistant message, as the runner reports it. */
+export type ModelCallEvent =
+  | { type: "start" }
+  | { type: "delta"; kind: "thinking" | "writing"; chars: number }
+  /** A stream event that carries no text (block boundaries): proof of life only. */
+  | { type: "beat" }
+  | { type: "end" };
+
+export interface ModelCallState {
+  startedAt: number;
+  /** The last stream event of any kind, which is what `stalled?` is measured from. */
+  lastEventAt: number;
+  kind: "thinking" | "writing";
+  /** Characters streamed as text or tool-call arguments this call. */
+  writtenChars: number;
+}
+
+/** Silence this long mid-call reads as stalled. */
+export const STALL_MS = 2 * 60_000;
+
+/** Rough characters per token, for a figure shown before the provider reports usage. */
+const CHARS_PER_TOKEN = 4;
+
+/** Fold one event into `current`; `undefined` means no call is in flight. */
+export function applyModelCallEvent(
+  current: ModelCallState | undefined,
+  event: ModelCallEvent,
+  now: number,
+): ModelCallState | undefined {
+  switch (event.type) {
+    case "start":
+      return { startedAt: now, lastEventAt: now, kind: "thinking", writtenChars: 0 };
+    case "end":
+      return undefined;
+    case "beat":
+      return current ? { ...current, lastEventAt: now } : current;
+    case "delta": {
+      const base = current ?? { startedAt: now, lastEventAt: now, kind: "thinking" as const, writtenChars: 0 };
+      return {
+        ...base,
+        lastEventAt: now,
+        // Once it has started writing, a late thinking block does not flip it back.
+        kind: event.kind === "writing" ? "writing" : base.kind,
+        writtenChars: base.writtenChars + (event.kind === "writing" ? event.chars : 0),
+      };
+    }
+  }
+}
+
+/** `41s`, `2m41s`, `1h05m`. */
+export function formatClock(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  if (total < 60) return `${total}s`;
+  const minutes = Math.floor(total / 60);
+  if (minutes < 60) return `${minutes}m${String(total % 60).padStart(2, "0")}s`;
+  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+/**
+ * `thinking · 2m41s`, `writing · 3.2k tok`, or `stalled? · 2m41s`; undefined
+ * when no call is in flight.
+ */
+export function describeModelCall(state: ModelCallState | undefined, now: number): string | undefined {
+  if (!state) return undefined;
+  const silent = now - state.lastEventAt;
+  if (silent >= STALL_MS) return `stalled? · ${formatClock(silent)}`;
+  if (state.kind === "writing") {
+    // `950`, `3.2k`.
+    const tokens = Math.round(state.writtenChars / CHARS_PER_TOKEN);
+    return `writing · ${tokens < 1_000 ? `${tokens}` : `${(tokens / 1_000).toFixed(1).replace(/\.0$/, "")}k`} tok`;
+  }
+  return `thinking · ${formatClock(now - state.startedAt)}`;
+}

package/src/model-resolver.ts

@@ -0,0 +1,333 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback for tool inputs.
+ */
+import { exactTierModel } from "./model-tiers.js";
+
+export interface ModelEntry {
+  id: string;
+  name: string;
+  provider: string;
+}
+
+export interface ModelRegistry {
+  find(provider: string, modelId: string): any;
+  getAll(): any[];
+  getAvailable?(): any[];
+}
+
+/** Logical model aliases supplied only by trusted global machine configuration. */
+let modelAliases = new Map<string, string[]>();
+
+/**
+ * Replace the configured logical aliases. Alias keys are case-insensitive;
+ * candidates are canonical provider/model IDs and are resolved against the
+ * available registry at dispatch time.
+ */
+export function setModelAliases(aliases: Record<string, string[]> | undefined): void {
+  modelAliases = new Map(
+    Object.entries(aliases ?? {}).map(([alias, candidates]) => [alias.toLowerCase(), [...candidates]]),
+  );
+}
+
+/**
+ * Per-agent model overrides from trusted global configuration: agent `type`
+ * (or `"*"`) -> model input. Resolved through `resolveModel`, so a value may be
+ * an alias, an exact `provider/id`, or a fuzzy name.
+ */
+let agentModels = new Map<string, string>();
+
+/** Replace the configured per-agent model map. Keys are matched case-insensitively. */
+export function setAgentModels(models: Record<string, string> | undefined): void {
+  agentModels = new Map(Object.entries(models ?? {}).map(([type, model]) => [type.toLowerCase(), model]));
+}
+
+/** A snapshot for the shared selection policy; callers cannot mutate configuration. */
+export function getAgentModels(): ReadonlyMap<string, string> {
+  return new Map(agentModels);
+}
+
+/**
+ * Narrows fuzzy candidates to the models the user enabled (pi's `enabledModels`),
+ * as lowercase `provider/id` keys. Injected rather than imported so this module
+ * stays free of settings I/O; `undefined` means no scope is configured. An
+ * unresolved dispatch passes its config root only for its diagnostic.
+ */
+export type ModelScopeProvider = (
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+) => ReadonlySet<string> | undefined;
+
+let modelScopeProvider: ModelScopeProvider | undefined;
+
+/** Install (or clear) the enabled-model scope used to rank fuzzy matches. */
+export function setModelScopeProvider(provider: ModelScopeProvider | undefined): void {
+  modelScopeProvider = provider;
+}
+
+/** A copy for diagnostics and tests; callers cannot mutate resolver state. */
+export function getModelAliases(): ReadonlyMap<string, readonly string[]> {
+  return new Map([...modelAliases].map(([alias, candidates]) => [alias, [...candidates]]));
+}
+
+/**
+ * Both display forms of a model. The short one goes on tight rows (the widget,
+ * the Agent tool result), the canonical one where there is room to disambiguate
+ * two providers serving a similarly-named model (the conversation viewer).
+ *
+ * One function, because `index.ts` labels the model it resolved before the run
+ * and `agent-manager.ts` relabels it from the live session afterwards — the two
+ * must agree or the label would visibly change the moment the session starts.
+ */
+export function describeModel(
+  model: { provider: string; id: string; name?: string },
+): { modelName: string; modelId: string } {
+  return {
+    modelName: (model.name ?? model.id).replace(/^Claude\s+/i, "").toLowerCase(),
+    modelId: `${model.provider}/${model.id}`,
+  };
+}
+
+/**
+ * A CONFIG model (`agentModels`, an agent's `model:`, a stored job's model) that
+ * did not resolve, so the spawn ran on the parent model instead. Recorded once on
+ * the `AgentRecord` by the shared spawn path; every surface reads it from there.
+ */
+export interface ModelFallback {
+  /** The configured input that failed to resolve. */
+  input: string;
+  /** Further configured inputs that also failed (e.g. a stored job model AND an `agentModels` override). */
+  also?: string[];
+  /** `provider/id` of the model actually used; absent when the session default (a parent with no model) ran. */
+  used?: string;
+  /** Whose model `used` is: the parent's (default) or the agent's own configured model (`agentModels` / definition `model:`), which took over from an unresolved stored model. */
+  via?: "parent" | "agent";
+}
+
+/** The fallback outcome for `input` when the spawn ran on `parent`. */
+export function modelFallbackTo(input: string, parent: { provider: string; id: string } | undefined): ModelFallback {
+  return parent ? { input, used: `${parent.provider}/${parent.id}` } : { input };
+}
+
+/**
+ * The disclosure line for a fallback: same `Note:` prefix as the unknown-agent-type
+ * note. Empty string when there was none, so callers can concatenate it blindly.
+ */
+export function modelFallbackNote(fallback: ModelFallback | undefined): string {
+  if (!fallback) return "";
+  const whose = fallback.via === "agent" ? "the agent's own model" : "parent model";
+  const used = fallback.used ? `${whose} ${fallback.used}` : "the session default model";
+  const inputs = [fallback.input, ...(fallback.also ?? [])];
+  const named = inputs.length === 1 ? `model "${inputs[0]}" did` : `models ${inputs.map(i => `"${i}"`).join(", ")} did`;
+  return `Note: configured ${named} not resolve; running on ${used}.`;
+}
+
+/** API id pi gives virtual catalog entries such as `router/default`; they never reach a provider. */
+const VIRTUAL_MODEL_API = "pi-virtual";
+
+/** Whether `model` is a virtual (router) selection rather than a physical model. */
+export function isVirtualModel(model: { api?: string } | undefined): boolean {
+  return model?.api === VIRTUAL_MODEL_API;
+}
+
+/** The pre-response label of a virtual selection: no physical model has answered yet. */
+export function describeVirtualModel(model: { provider: string; id: string; name?: string }): {
+  modelName: string;
+  modelId: string;
+} {
+  const described = describeModel(model);
+  return { ...described, modelName: `${described.modelName} (routing)` };
+}
+
+/**
+ * The physical model behind an assistant message, or `undefined` when the
+ * message names none (an error from failed routing carries the virtual model).
+ *
+ * With a virtual selection (`agentModels["*"] = "router/default"`) the session
+ * model is the router; only responses record where a request actually went, so
+ * rows must be relabelled from them. `registry` supplies the display name, and
+ * is optional: without it the id stands in.
+ */
+export function describePhysicalModel(
+  message: { api?: string; provider?: string; model?: string } | undefined,
+  registry?: { find?(provider: string, modelId: string): { name?: string } | undefined },
+): { modelName: string; modelId: string } | undefined {
+  if (!message?.provider || !message.model || isVirtualModel(message)) return undefined;
+  const found = registry?.find?.(message.provider, message.model);
+  return describeModel({ provider: message.provider, id: message.model, name: found?.name });
+}
+
+/** Parsed `[major, minor]` of a model id, or undefined when the family has no known scheme. */
+export type ModelVersion = readonly [major: number, minor: number];
+
+/**
+ * Pull a version out of a model id (provider prefix ignored):
+ *   - `claude-<family>-<n>[-<n>]`, e.g. `claude-opus-4-6`, `claude-opus-5`
+ *   - `claude-<n>[-<n>]-<family>`, e.g. `claude-3-5-sonnet-20241022`
+ *   - `gpt-<n>[.<n>]-<variant>`, e.g. `gpt-6.1-sol`
+ * A minor is one or two digits, so a trailing `-20250514` date stamp is never
+ * read as one. Dots and dashes are interchangeable between the parts.
+ */
+export function parseModelVersion(id: string): ModelVersion | undefined {
+  const bare = id.slice(id.lastIndexOf("/") + 1).toLowerCase();
+  const claude = /^claude-[a-z]+-(\d{1,2})(?:[-.](\d{1,2})(?!\d))?(?:-|$)/.exec(bare)
+    ?? /^claude-(\d{1,2})(?:[-.](\d{1,2})(?!\d))?-[a-z]/.exec(bare);
+  const match = claude ?? /^gpt-(\d+)(?:[.-](\d{1,2})(?!\d))?(?:-|$)/.exec(bare);
+  if (!match) return undefined;
+  return [Number(match[1]), Number(match[2] ?? 0)];
+}
+
+/** Descending version order; an unversioned model sorts after every versioned one. */
+function compareVersionsDesc(a: ModelVersion | undefined, b: ModelVersion | undefined): number {
+  if (a && b) return b[0] - a[0] || b[1] - a[1];
+  return a ? -1 : b ? 1 : 0;
+}
+
+/**
+ * Resolve a model string to a Model instance.
+ * Tries exact match first ("provider/modelId"), then fuzzy match against all available models.
+ * Returns the Model on success, or an error message string on failure.
+ */
+export function resolveModel(
+  input: string,
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+): any | string {
+  const aliasCandidates = modelAliases.get(input.trim().toLowerCase());
+  if (aliasCandidates) {
+    for (const candidate of aliasCandidates) {
+      const resolved = exactTierModel(candidate, registry);
+      if (resolved) return resolved;
+    }
+    return `Model alias "${input}" has no available candidate.\n\nCandidates:\n${aliasCandidates.map(candidate => `  ${candidate}`).join("\n")}`;
+  }
+  return resolveCanonicalModel(input, registry, context);
+}
+
+/**
+ * Pick among fuzzy candidates. Restricted to the enabled model scope when one is
+ * configured and any candidate is in it, then newest parsed version first, then
+ * match score. A bare family name like "opus" therefore means the newest opus
+ * the user has enabled, not whichever id happens to be shortest.
+ */
+function scopedCandidates<T extends { entry: ModelEntry }>(
+  candidates: T[],
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+): T[] {
+  const scope = modelScopeProvider?.(registry, context);
+  const scoped = scope ? candidates.filter(candidate => scope.has(`${candidate.entry.provider}/${candidate.entry.id}`.toLowerCase())) : [];
+  return scoped.length > 0 ? scoped : candidates;
+}
+
+/** Stable tie-breaker independent of registry insertion order and locale. */
+function compareModelIdentity(a: ModelEntry, b: ModelEntry): number {
+  const left = `${a.provider}/${a.id}`;
+  const right = `${b.provider}/${b.id}`;
+  return Number(left > right) - Number(left < right);
+}
+
+function rankFuzzy(
+  matches: { entry: ModelEntry; score: number }[],
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+): ModelEntry | undefined {
+  const ranked = scopedCandidates(matches, registry, context)
+    .map(c => ({ ...c, version: parseModelVersion(c.entry.id) }))
+    .sort((a, b) => compareVersionsDesc(a.version, b.version) || b.score - a.score || compareModelIdentity(a.entry, b.entry));
+  return ranked[0]?.entry;
+}
+
+/** Numeric runs stay ordered and contiguous: `5-5` cannot reuse the `5` in `4-5`. */
+function versionRuns(value: string): string[] {
+  return [...value.replace(/-\d{8}$/, "").matchAll(/(?:^|[\s-])(\d+(?:[\s-]+\d+)*)(?=$|[\s-])/g)].map(match => match[1]!.replace(/\s+/g, "-"));
+}
+
+/** Resolve an exact or fuzzy provider/model request without consulting aliases. */
+function resolveCanonicalModel(
+  input: string,
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+): any | string {
+  // Available models (those with auth configured)
+  const all = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
+  const availableSet = new Set(all.map(m => `${m.provider}/${m.id}`.toLowerCase()));
+
+  // 1. Exact match: "provider/modelId" — only if available (has auth)
+  const slashIdx = input.indexOf("/");
+  if (slashIdx !== -1) {
+    const provider = input.slice(0, slashIdx);
+    const modelId = input.slice(slashIdx + 1);
+    if (availableSet.has(input.toLowerCase())) {
+      const found = registry.find(provider, modelId);
+      if (found) return found;
+    }
+  }
+
+  // 2. Fuzzy match against available models. Normalize separators so cosmetic
+  // punctuation differences still match — e.g. "claude-haiku-4.5" and
+  // "claude-haiku-4-5" (dot vs dash in the version) resolve to the same model.
+  const normalize = (s: string) => s.toLowerCase().replace(/\./g, "-");
+  const query = normalize(input);
+  const requestedVersions = versionRuns(query.slice(slashIdx + 1));
+
+  // Score each model: prefer exact id match > id contains > name contains > provider+id contains
+  const matches: { entry: ModelEntry; score: number }[] = [];
+
+  for (const m of all) {
+    const id = normalize(m.id);
+    const name = normalize(m.name);
+    const full = normalize(`${m.provider}/${m.id}`);
+    const idVersions = versionRuns(id);
+    const versions = idVersions.length > 0 ? idVersions : versionRuns(name);
+    // Filter before scope/ranking, including substring and name matches. A
+    // major-only input can select a newer minor, but never another major or
+    // a minor token masquerading as the requested major.
+    if (!requestedVersions.every(requested => versions.some(version => version === requested || version.startsWith(`${requested}-`)))) continue;
+
+    let score = 0;
+    if (id === query || full === query) {
+      score = 100; // exact
+    } else if (id.includes(query) || full.includes(query)) {
+      score = 60 + (query.length / id.length) * 30; // substring, prefer tighter matches
+    } else if (name.includes(query)) {
+      score = 40 + (query.length / name.length) * 20;
+    } else if (
+      // A trailing date-stamp token (e.g. "20251001") is optional, so a
+      // date-pinned config like "claude-haiku-4-5-20251001" still matches an
+      // undated registry id like "claude-haiku-4-5".
+      query
+        .split(/[\s\-/]+/)
+        .every(part => /^\d{8}$/.test(part) || id.includes(part) || name.includes(part) || m.provider.toLowerCase().includes(part))
+    ) {
+      score = 20; // all parts present somewhere
+    }
+
+    if (score >= 20) matches.push({ entry: m, score });
+  }
+
+  // An exact id (or provider/id) is the caller naming a model, not describing
+  // one: it wins outright, whatever the scope or any newer sibling.
+  const exact = matches.filter(c => c.score === 100);
+  const exactBest = exact.sort((a, b) => compareModelIdentity(a.entry, b.entry))[0];
+  const bestMatch = exactBest ? exactBest.entry : rankFuzzy(matches, registry, context);
+  if (bestMatch) {
+    const found = registry.find(bestMatch.provider, bestMatch.id);
+    if (found) return found;
+  }
+
+  // 3. Provider fallback: a "provider/modelId" query that didn't match under the
+  // named provider (exact or fuzzy above) retries against all providers. The
+  // named provider is preferred when present; this only kicks in when it isn't,
+  // so the same model from another provider beats falling back to "inherit".
+  if (slashIdx !== -1) {
+    const bare = resolveCanonicalModel(input.slice(slashIdx + 1), registry, context);
+    if (typeof bare !== "string") return bare;
+  }
+
+  // 4. No match — list available models
+  const modelList = scopedCandidates(all.map(entry => ({ entry })), registry, context)
+    .map(({ entry }) => `  ${entry.provider}/${entry.id}`)
+    .sort()
+    .join("\n");
+  return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}

package/src/model-scope.ts

@@ -0,0 +1,71 @@
+/**
+ * model-scope.ts — `scopeModels` policy, shared by the top-level Agent tool and
+ * the nested delegation tools so a nested spawn can't escape the allowlist the
+ * top-level path enforces.
+ *
+ * State lives here (rather than in an index.ts closure) for the same reason
+ * `disableDefaults` lives in agent-types.ts: both entry points need it.
+ */
+
+import { isModelInScope, type ModelRegistryRef, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
+
+/**
+ * When enabled, subagent model choices are validated against `enabledModels`
+ * from pi's settings — both global `<agentDir>/settings.json` and project-local
+ * `<cwd>/.pi/settings.json` (project overrides global). Off by default; opt-in
+ * via `/agents → Settings`. See the SubagentsSettings.scopeModels docstring for
+ * the hard-error vs warn-and-proceed policy and its rationale.
+ */
+let scopeModelsEnabled = false;
+
+export function isScopeModelsEnabled(): boolean { return scopeModelsEnabled; }
+export function setScopeModelsEnabled(enabled: boolean): void { scopeModelsEnabled = enabled; }
+
+export type ModelScopeVerdict =
+  /** In scope, or nothing to validate against (feature off / no allowlist). */
+  | { kind: "ok" }
+  /** Caller-supplied out-of-scope choice — refuse the spawn with this message. */
+  | { kind: "error"; message: string }
+  /** Frontmatter-pinned or parent-inherited — proceed, but tell the user. */
+  | { kind: "warn"; message: string };
+
+/**
+ * Check the effective resolved model against the user's enabledModels list.
+ *
+ * scopeModels guards against *runtime* LLM choices, not user-level config:
+ *   - Caller-supplied out-of-scope → hard error (the orchestrator made an explicit
+ *     out-of-scope choice; surface it so it picks differently).
+ *   - Frontmatter-pinned or parent-inherited out-of-scope → warn but proceed (the
+ *     user authored/installed this agent or chose the parent's model; trust it).
+ */
+export function checkModelScope(args: {
+  homeDir?: string;
+  model: { provider: string; id: string } | undefined;
+  cwd: string;
+  modelRegistry: ModelRegistryRef;
+  /** True when the model came from the tool call rather than frontmatter. */
+  callerSupplied: boolean;
+  /** Display name used in the warning toast. */
+  agentLabel: string;
+  /** The raw `model:` input, when there was one. */
+  modelInput?: string;
+}): ModelScopeVerdict {
+  const { model, cwd, modelRegistry, callerSupplied, agentLabel, modelInput } = args;
+  if (!scopeModelsEnabled || !model) return { kind: "ok" };
+
+  const allowed = resolveEnabledModels(readEnabledModels(cwd, args.homeDir), modelRegistry, cwd, args.homeDir);
+  if (!allowed || isModelInScope(model, allowed)) return { kind: "ok" };
+
+  if (callerSupplied) {
+    const list = [...allowed].sort().map(m => `  ${m}`).join("\n");
+    return {
+      kind: "error",
+      message: `Model not in scope: "${modelInput}".\n\nAllowed models (from enabledModels):\n${list}`,
+    };
+  }
+  const modelLabel = modelInput ?? `${model.provider}/${model.id}`;
+  return {
+    kind: "warn",
+    message: `Agent "${agentLabel}" using out-of-scope model "${modelLabel}"`,
+  };
+}

package/src/model-selection.ts

@@ -0,0 +1,170 @@
+/** One selection policy for every dispatch, independent of its transport. */
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { type Clock, realClock } from "./clock.js";
+import { describeModel, describeVirtualModel, getAgentModels, getModelAliases, isVirtualModel, type ModelFallback, type ModelRegistry, modelFallbackNote, modelFallbackTo, resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
+import { exactTierModel, getModelResolution, parseTierBinding, resolveTier, type TierBinding, type TierDisclosure, type TierOutcome, tierBinding, tierNote } from "./model-tiers.js";
+import { type AdmissionEvents, admissionOutcome, type QuotaBlock } from "./quota-admission.js";
+
+/** Exact compatibility pins for user-defined legacy Explore definitions. User aliases win. */
+const LEGACY_MODEL_PINS = new Map([
+  ["claude-haiku-4-5", "anthropic/claude-haiku-4-5"],
+]);
+
+/** The winning precedence level, before resolution or fallback. */
+export type ModelSource = "param" | "agentModels:type" | "agentModels:*" | "definition" | "parent";
+
+/** Keep the original request even when it could not be resolved. */
+export interface ModelSelection {
+  requested?: string;
+  source: ModelSource;
+  model: Model<Api> | undefined;
+  outcome: "resolved" | "inherited" | "fallback";
+  fallback?: ModelFallback;
+  scopeWarning?: string;
+  /** Serializable tier provenance, retained when the answering model changes. */
+  tier?: TierOutcome;
+  /** A prepared binding is resolved with admission before starting the child. */
+  tierBinding?: TierBinding;
+  tierAdmitted?: boolean;
+  /** Startup-only parent floor if credentials/profile disappear between preflight and admission. */
+  tierParent?: Model<Api>;
+}
+
+/** Choose the input once: explicit parameter > type > wildcard > definition; blank strings are unset. */
+export function modelRequest(type: string, definitionModel?: string, paramModel?: string | Model<Api> | null): {
+  requested?: string;
+  source: ModelSource;
+} {
+  if (paramModel != null && (typeof paramModel !== "string" || paramModel.trim() !== "")) {
+    return { requested: typeof paramModel === "string" ? paramModel : `${paramModel.provider}/${paramModel.id}`, source: "param" };
+  }
+  const overrides = getAgentModels();
+  const typed = overrides.get(type.toLowerCase());
+  if (typed?.trim()) return { requested: typed, source: "agentModels:type" };
+  const wildcard = overrides.get("*");
+  if (wildcard?.trim()) return { requested: wildcard, source: "agentModels:*" };
+  if (definitionModel?.trim()) return { requested: definitionModel, source: "definition" };
+  return { source: "parent" };
+}
+
+/**
+ * Choose an exact configured input or tier binding before record creation.
+ * Only explicit non-tier tool inputs retain fuzzy matching. Tier admission is
+ * asynchronous and completes through admitModelSelection before startup; this
+ * synchronous preflight preserves spawn's immediate-id and validation contract.
+ * An already-open resume keeps the record and does not select again.
+ */
+export function selectModel(request: {
+  homeDir?: string;
+  agentType: string;
+  definitionModel?: string;
+  paramModel?: string | Model<Api> | null;
+  parentModel: Model<Api> | undefined;
+  registry: ModelRegistry;
+  cwd: string;
+  agentLabel?: string;
+}): ModelSelection | string {
+  const input = modelRequest(request.agentType, request.definitionModel, request.paramModel);
+  let selection: ModelSelection = { ...input, model: request.parentModel, outcome: "inherited" };
+  if (input.requested) {
+    const requested = input.requested.trim();
+    const legacy = getModelAliases().get(requested.toLowerCase());
+    const legacyBinding = legacy ? parseTierBinding("legacy", legacy) : undefined;
+    // Preserve existing enterprise manifests during the built-in Explore migration.
+    // An explicit cheap binding always wins, even when it is unavailable.
+    const cheapCompatibility = requested === "@cheap" && request.agentType === "Explore"
+      && input.source === "definition"
+      ? parseTierBinding("cheap", getModelAliases().get("claude-haiku-4-5")) : undefined;
+    const binding = requested.startsWith("@") ? tierBinding(requested.slice(1)) ?? cheapCompatibility
+      : legacyBinding ? { ...legacyBinding, tier: requested } : undefined;
+    if (requested.startsWith("@") || legacy) {
+      const tier = requested.startsWith("@") ? requested.slice(1) : requested;
+      const refs = binding?.kind === "routed" ? [binding.profile] : binding?.members ?? [];
+      const model = refs.map(ref => exactTierModel(ref, request.registry)).find(Boolean);
+      if (!binding || !model) {
+        const outcome: TierOutcome = binding ? { kind: "unavailable", tier, tried: refs } : { kind: "unmapped", tier };
+        const mode = outcome.kind === "unmapped" ? getModelResolution().onUnmapped : getModelResolution().onUnavailable;
+        if (mode === "error") return `Model tier @${tier} is ${outcome.kind}.`;
+        selection = { ...selection, tier: outcome, outcome: "fallback", fallback: modelFallbackTo(input.requested, request.parentModel) };
+      } else {
+        selection = { ...input, model, outcome: "resolved", tierBinding: binding, tierParent: request.parentModel };
+      }
+    } else {
+      const compatibilityPin = input.source === "definition" && request.agentType === "Explore"
+        ? LEGACY_MODEL_PINS.get(requested) : undefined;
+      const resolved = request.paramModel != null && typeof request.paramModel === "object"
+        ? request.paramModel : input.source === "param" ? resolveModel(requested, request.registry, { cwd: request.cwd, homeDir: request.homeDir })
+        : exactTierModel(compatibilityPin ?? requested, request.registry) ?? `Model not found: "${requested}".`;
+      if (typeof resolved !== "string") selection = { ...input, model: resolved, outcome: "resolved" };
+      else if (compatibilityPin) {
+        const tier: TierOutcome = { kind: "unavailable", tier: requested, tried: [compatibilityPin] };
+        if (getModelResolution().onUnavailable === "error") return `Model tier @${requested} is unavailable.`;
+        selection = { ...selection, tier, outcome: "fallback", fallback: modelFallbackTo(input.requested, request.parentModel) };
+      } else {
+        if (input.source === "param" || getModelResolution().onUnavailable === "error") return resolved;
+        selection = { ...selection, outcome: "fallback", fallback: modelFallbackTo(input.requested, request.parentModel) };
+      }
+    }
+  }
+  const scope = checkModelScope({
+    model: selection.model, cwd: request.cwd, modelRegistry: request.registry,
+    callerSupplied: input.source === "param" && !selection.tierBinding && !selection.tier, agentLabel: request.agentLabel ?? request.agentType,
+    modelInput: input.requested, homeDir: request.homeDir,
+  });
+  if (scope.kind === "error") return scope.message;
+  if (scope.kind === "warn") selection.scopeWarning = scope.message;
+  return selection;
+}
+
+/** Label an admitted physical model before any response, without replacing the virtual selection. */
+export function describeSelection(selection: ModelSelection | undefined, registry: ModelRegistry): { modelName?: string; modelId?: string } {
+  const admitted = selection?.tier?.kind === "routed" ? selection.tier.admitted : undefined;
+  if (admitted) {
+    const slash = admitted.indexOf("/");
+    const provider = admitted.slice(0, slash);
+    const id = admitted.slice(slash + 1);
+    return describeModel(registry.find(provider, id) ?? { provider, id });
+  }
+  const model = selection?.model;
+  return model ? isVirtualModel(model) ? describeVirtualModel(model) : describeModel(model) : {};
+}
+
+/** Resolved selection identity for model-facing text, not an actionable fallback warning. */
+export function modelIdentityNote(carrier: { modelSelection?: ModelSelection; modelTier?: TierDisclosure } | undefined): string {
+  const selected = carrier?.modelSelection?.model;
+  // Tier notes already carry admission/answer provenance. Literal virtual
+  // selections have no such evidence, so never claim their alias is a leaf.
+  return selected && !carrier?.modelTier
+    ? `Resolved model: ${selected.provider}/${selected.id}${isVirtualModel(selected) ? " (routing alias; physical response model: unknown)" : ""}.`
+    : "";
+}
+
+/** One disclosure for records, persisted details, workflows and notices. */
+export function modelSelectionNote(carrier: { modelTier?: TierDisclosure; modelFallback?: ModelFallback; invocation?: { modelId?: string } } | undefined): string {
+  const tier = carrier?.modelTier;
+  const fallback = carrier?.modelFallback;
+  const sameRequest = tier && (fallback?.input === tier.tier || fallback?.input === `@${tier.tier}`);
+  return [tierNote(tier, carrier?.invocation?.modelId), sameRequest ? "" : modelFallbackNote(fallback)].filter(Boolean).join("\n");
+}
+
+/** Admission for tiers is made once and is shared by every transport. */
+export async function admitModelSelection(selection: ModelSelection, registry: ModelRegistry, events: AdmissionEvents, clock: Clock = realClock, signal?: AbortSignal): Promise<QuotaBlock | undefined> {
+  if (!selection.tierBinding || selection.tierAdmitted) return selection.tier?.kind === "exhausted" ? selection.tier.block : undefined;
+  selection.tier = await resolveTier(selection.tierBinding.tier, {
+    registry, binding: selection.tierBinding, admit: ref => admissionOutcome(events, ref, undefined, clock, signal),
+  });
+  selection.tierAdmitted = true;
+  if (selection.tier.kind === "routed" || selection.tier.kind === "static") selection.model = selection.tier.model;
+  if (selection.tier.kind === "exhausted") return selection.tier.block;
+  // The binding is handed to `resolveTier`, so it is never `unmapped` here.
+  if (selection.tier.kind === "unavailable") {
+    if (getModelResolution().onUnavailable === "error") throw new Error(`Model tier @${selection.tier.tier} is unavailable.`);
+    selection.model = selection.tierParent;
+    selection.outcome = "fallback";
+    selection.fallback = modelFallbackTo(selection.requested ?? `@${selection.tier.tier}`, selection.tierParent);
+    delete selection.tierBinding;
+  }
+  delete selection.tierParent;
+  return undefined;
+}