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

package/src/mention.ts

@@ -0,0 +1,141 @@
+/**
+ * mention.ts — the `@handle` grammar for messaging a subagent from the prompt.
+ *
+ * Claude Code lets you type `@code-review take another look` at the prompt and
+ * routes the message to that agent instead of the main model. Its grammar is
+ * reproduced here so the two behave identically:
+ *
+ *   - suggestions fire on `@` at the start of the input or after whitespace,
+ *     followed by `[\w-]*` (so `@src/foo.ts` is a file, never an agent);
+ *   - a send is recognized only at the START of the input, and only with a
+ *     non-empty message after the handle. That is why a bare `@code-review`
+ *     goes to the main model rather than anywhere near the agent.
+ *
+ * A record's own identity is a UUID plus a deliberately non-unique description,
+ * neither of which is typeable, so the handle is derived from the agent type.
+ * Colliding handles are numbered (`explore`, `explore-2`), which is also what
+ * Claude Code's `allocateName` does — it recycles a name only once the task
+ * behind it is gone. Its SendMessage prompt describes the *registry* as
+ * latest-wins, which is a different thing and not how names are allocated.
+ */
+
+/**
+ * Suggestion trigger: `@` at a token boundary plus the partial handle typed so
+ * far. Ported from Claude Code, including the CJK sentence-ending punctuation
+ * it accepts as a boundary.
+ */
+export const MENTION_TRIGGER = /(^|[\s。、？！])@([\w-]*)$/;
+
+/** Send grammar: leading `@handle`, then a non-empty message. */
+const MENTION_SEND = /^@([\w-]+)\s+([\s\S]+)$/;
+
+/**
+ * Upper bound on a handle, matching Claude Code's `dSS`. Nothing here generates
+ * a name this long, but an agent type or a model-supplied name can be arbitrary
+ * text, and an unbounded handle would wrap the suggestion popup.
+ */
+const MAX_HANDLE_LENGTH = 64;
+
+/**
+ * Handles that address something other than a subagent, and so can never be
+ * allocated to one. Claude Code reserves exactly this name (`Vq = "main"`),
+ * refusing it at spawn and routing it to the main conversation instead.
+ */
+const RESERVED_HANDLES: ReadonlySet<string> = new Set(["main"]);
+
+/** Whether `@handle` names the main conversation rather than any subagent. */
+export function isReservedHandle(handle: string): boolean {
+  return RESERVED_HANDLES.has(handle.toLowerCase());
+}
+
+/** Slug of an agent type or name, restricted to the `[\w-]` the grammar allows. */
+export function handleBase(type: string): string {
+  const slug = type.toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_HANDLE_LENGTH)
+    // The slice can land mid-run and leave the trailing hyphen back.
+    .replace(/-+$/, "");
+  return slug || "agent";
+}
+
+/**
+ * `base`, else `base-2`, `base-3`, … — the first form that is neither `taken`
+ * nor reserved. Callers pass one shared `taken` set covering type-derived
+ * handles and model-supplied aliases alike, so the two can never collide.
+ */
+export function assignHandle(base: string, taken: ReadonlySet<string>): string {
+  let candidate = base;
+  let n = 1;
+  while (taken.has(candidate) || RESERVED_HANDLES.has(candidate)) {
+    n++;
+    candidate = `${base}-${n}`;
+  }
+  return candidate;
+}
+
+/**
+ * Map a typed handle back to a registered agent type, so `@explore fix it`
+ * reaches the Explore agent even when no instance has ever run. `handleBase` is
+ * the single source of truth in both directions, so a type is addressable by
+ * exactly the handle its instances would be given.
+ */
+export function resolveHandleToType(handle: string, types: readonly string[]): string | undefined {
+  const wanted = handle.toLowerCase();
+  // A type slugging to a reserved name is unaddressable rather than shadowing
+  // it — `assignHandle` refuses that name too, so its instances never hold one.
+  if (RESERVED_HANDLES.has(wanted)) return undefined;
+  return types.find(type => handleBase(type) === wanted);
+}
+
+/**
+ * Claude Code documents `@agent-<name>` as the form you type by hand when the
+ * picker isn't involved. Accepted here as an exact synonym: the caller tries the
+ * handle as written first, so an agent genuinely called `agent-foo` still wins
+ * over `@agent-` + `foo`, and only falls back to this when that finds nothing.
+ * Returns undefined when the prefix is absent or is the whole handle.
+ */
+export function stripAgentPrefix(handle: string): string | undefined {
+  const rest = /^agent-(.+)$/i.exec(handle)?.[1];
+  return rest || undefined;
+}
+
+/**
+ * A spawn needs the short description every agent surface renders. A mention
+ * carries no separate label, so the message itself becomes one: first line,
+ * whitespace collapsed, clipped to roughly the 3-5 words the Agent tool asks of
+ * the model.
+ */
+export function describeMention(message: string): string {
+  const oneLine = message.split("\n", 1)[0].replace(/\s+/g, " ").trim();
+  return oneLine.length > 40 ? `${oneLine.slice(0, 39).trimEnd()}…` : oneLine;
+}
+
+/**
+ * What Claude Code sends the main model when a mention names an agent it could
+ * start. Its `@agent-<type>` mention is not a spawn at all: it becomes an
+ * `agent_mention` attachment, which renders to a synthetic `isMeta` user
+ * message placed after the user's own untouched text — no tool forcing, no
+ * allowed-tools narrowing, and the Task tool is not even named. The model reads
+ * this and calls the tool itself.
+ *
+ * Ported verbatim from the 2.1.233 bundle's attachment renderer, trailing space
+ * before the closing newline included, so the wording the model was trained
+ * against is the wording it gets. The one substitution is ours: pi's equivalent
+ * of Task is the `Agent` tool, and the agent listing that teaches valid
+ * `subagent_type` values is the tool spec rather than a separate attachment.
+ */
+export function agentMentionReminder(type: string): string {
+  return `<system-reminder>\nThe user has expressed a desire to invoke the agent "${type}". Please invoke the agent appropriately, passing in the required context to it. \n</system-reminder>`;
+}
+
+/**
+ * Split `@handle message` into its parts, or null when the text isn't a send —
+ * a bare handle, a leading file path, or a mention that isn't at the start.
+ */
+export function parseMention(text: string): { handle: string; message: string } | null {
+  const match = MENTION_SEND.exec(text);
+  if (!match) return null;
+  const message = match[2].trim();
+  return message ? { handle: match[1], message } : null;
+}

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,266 @@
+/**
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ */
+
+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]));
+}
+
+/**
+ * The model input a spawn of `type` should use when the caller named none:
+ * `agentModels[type]`, then `agentModels["*"]`, then the agent definition's own
+ * `model:` (`definitionModel`). The parent model is the floor, applied by the
+ * caller when this returns `undefined`.
+ */
+export function configuredAgentModel(type: string, definitionModel: string | undefined): string | undefined {
+  return agentModels.get(type.toLowerCase()) ?? agentModels.get("*") ?? definitionModel;
+}
+
+/**
+ * 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.
+ */
+export type ModelScopeProvider = (registry: ModelRegistry) => 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}`,
+  };
+}
+
+/** 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,
+): any | string {
+  const aliasCandidates = modelAliases.get(input.trim().toLowerCase());
+  if (aliasCandidates) {
+    for (const candidate of aliasCandidates) {
+      const resolved = resolveCanonicalModel(candidate, registry);
+      if (typeof resolved !== "string") return resolved;
+    }
+    return `Model alias "${input}" has no available candidate.\n\nCandidates:\n${aliasCandidates.map(candidate => `  ${candidate}`).join("\n")}`;
+  }
+  return resolveCanonicalModel(input, registry);
+}
+
+/**
+ * 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 rankFuzzy(matches: { entry: ModelEntry; score: number }[], registry: ModelRegistry): ModelEntry | undefined {
+  const scope = modelScopeProvider?.(registry);
+  const scoped = scope ? matches.filter(c => scope.has(`${c.entry.provider}/${c.entry.id}`.toLowerCase())) : [];
+  const pool = scoped.length > 0 ? scoped : matches;
+  const ranked = pool
+    .map(c => ({ ...c, version: parseModelVersion(c.entry.id) }))
+    .sort((a, b) => compareVersionsDesc(a.version, b.version) || b.score - a.score);
+  return ranked[0]?.entry;
+}
+
+/** Resolve an exact or fuzzy provider/model request without consulting aliases. */
+function resolveCanonicalModel(
+  input: string,
+  registry: ModelRegistry,
+): 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);
+
+  // 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}`);
+
+    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.find(c => c.score === 100);
+  const bestMatch = exact?.entry ?? rankFuzzy(matches, registry);
+  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);
+    if (typeof bare !== "string") return bare;
+  }
+
+  // 4. No match — list available models
+  const modelList = all
+    .map(m => `  ${m.provider}/${m.id}`)
+    .sort()
+    .join("\n");
+  return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;
+}

package/src/model-scope.ts

@@ -0,0 +1,70 @@
+/**
+ * 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: {
+  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), modelRegistry, cwd);
+  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}"`,
+  };
+}