@signalridge/pi-subagents 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 1.5.0
+### Minor Changes
+
+- a6cf423: Add a settings interface for the subagent default model and tier. Both were
+  previously reachable only by hand-editing `subagents.json`.
+  
+  `/agents → Settings` gains two rows. **Default model** writes a new
+  `defaultModel` key: the model a subagent runs when no tier picked one, slotting
+  in ahead of the parent session at the end of resolution, so a workspace can say
+  "subagents run on the cheap model" without first defining a tier catalogue. It
+  decides only the model — thinking still comes from the parent, since a level
+  nobody chose for a specific model is what a tier exists to express — and any
+  tier that applies overrides it. **Default tier** selects `agentTiers.defaultTier`
+  from the defined tier keys.
+  
+  `/agents → Model tiers` is a new menu for the catalogue itself: create a tier,
+  change its model, thinking or description, or delete it. The model picker
+  enumerates pi's own registry (narrowed to your scope when Scope models is on)
+  plus `inherit` and a typed escape hatch for a provider this machine has not
+  authed. The thinking picker offers only the levels the chosen model reports as
+  supported, rather than a fixed list whose extra entries `clampThinkingLevel`
+  would silently lower at spawn. A tier dropped as malformed stays listed as
+  `blocked` so redefining it retires the tombstone in one step, and deleting the
+  tier that `defaultTier` names clears the default in the same write rather than
+  leaving every untiered spawn to fail.
+  
+  Unlike a tier, an unresolvable `defaultModel` falls back to the parent model
+  instead of failing the spawn — a tier is refused because someone named that
+  policy at the call site, while `defaultModel` is the value nobody named, so one
+  unauthed provider must not take every spawn on the machine down with it. The
+  Settings row flags it as `(unavailable, fallback: inherit)`. `defaultModel`
+  accepts the literal `"inherit"`, which is how a project cancels a global default;
+  omitting the key still inherits whatever the global file set.
+
+## 1.4.0
+### Minor Changes
+
+- 72be09a: An agent no longer picks its own model.
+  
+  `model:` and `thinking:` in agent frontmatter are no longer read. Which model a
+  subagent runs is the tier catalogue's decision, and a per-file pin was a way
+  around it — silently, since nothing warned unless the file also named a tier. A
+  file that still carries them loads and runs exactly as before; the two lines
+  have no effect, and a warning names the file so the migration can be finished
+  one agent at a time.
+  
+  The built-in agents drop their own pin for the same reason: `Explore` named
+  `anthropic/claude-haiku-4-5`, which is both an end-run around the catalogue and
+  a vendor the machine may not have.
+  
+  The resulting fallback is simple and worth stating: with no tier passed, none in
+  the agent, and no `agentTiers.defaultTier`, a subagent runs on the parent
+  session's model.
+  
+  A `defaultTier` — or an agent's `tier:` — that names no defined profile is now
+  reported at startup with the available keys, rather than waiting for the first
+  spawn that needs it. `/agents` no longer advertises a pinned model in the type
+  list and writes `tier:` instead of `model:` when it regenerates an agent file.
+  
+  Programmatic callers and the legacy RPC still accept `model`/`thinking`. That is
+  an escape hatch for code, not a way to configure an agent.
+
 ## 1.3.0
 ### Minor Changes
 

package/README.md

@@ -28,6 +28,7 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
 - **Cross-extension RPC** — other pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Protocol v3 adds policy-free managed spawning plus owner-scoped stop/quiescence; workflow callers require the advertised `ownedStop` capability and never fall back to unowned stop. Standardized reply envelopes provide versioning. Emits `subagents:ready` on session start
 - **Schedule subagents** — pass `schedule` to the `Agent` tool to fire on cron / interval / one-shot. Session-scoped jobs with PID-locked persistence; results land via the same `subagent-notification` followUp path as manual background completions; manage via `/agents → Scheduled jobs`
+- **Model tiers** — name a (model, thinking) pair once and let the orchestrator pick it by name; the `Agent` tool exposes `tier` and never `model`/`thinking`, so which model runs stays a config decision. Manage the catalogue in `/agents → Model tiers`, pick the default in `/agents → Settings → Default tier`, or set a plain `defaultModel` when one line beats a catalogue
 - **Model scope enforcement** — opt-in validation that subagent model choices stay within your pi `enabledModels` allowlist (sourced from `/scoped-models`, with both global and project-local pi settings honored). Caller-supplied out-of-scope → hard error to orchestrator; frontmatter-pinned out-of-scope → warning + runs anyway (frontmatter authoritative). Toggle via `/agents → Settings → Scope models`
 - **Resilient agent files** — malformed custom `.md` files are skipped with a path-qualified warning so one bad file cannot prevent startup; enable `/agents → Settings → Strict agent files` when startup should fail closed instead
 
@@ -231,8 +232,8 @@ All fields are optional — sensible defaults for everything.
 | `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
 | `isolation` | — | Set to `worktree` to run in an isolated git worktree |
 | `tier` | none | This agent's default model tier, by name, from `agentTiers.profiles`. A tier passed at the call site overrides it. When set, it wins over `model`/`thinking` below — see [Model tiers](#model-tiers) |
-| `model` | inherit parent | **Legacy.** Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp are interchangeable) and falls back to the same model under another provider if the named one doesn't have it. Ignored when a tier applies |
-| `thinking` | inherit | **Legacy.** off, minimal, low, medium, high, xhigh, max — actual availability depends on your pi version and model; pi clamps unsupported levels down. Ignored when a tier applies |
+| ~~`model`~~ | — | **Removed.** An agent no longer chooses its own model; use `tier`. A file that still has it loads normally, with a warning naming it — the line simply has no effect |
+| ~~`thinking`~~ | — | **Removed**, same as `model` above |
 | `max_turns` | unlimited | Max agentic turns before graceful shutdown. `0` or omit for unlimited |
 | `persist_session` | `false` | Persist this subagent as a normal pi session instead of keeping the session in memory only. The subagent's `.output` transcript is still written either way unless `output_transcript: false` |
 | `output_transcript` | `true` (or `subagents.json` `outputTranscript`) | Write this subagent's `.output` transcript; when set, overrides the `subagents.json` `outputTranscript` default. Set `false` to write no transcript file or path. Governs only the transcript — independent of `persist_session`, `isolation: worktree`, and `memory:` |
@@ -358,6 +359,7 @@ The `/agents` command opens an interactive menu:
 ```
 Agent runs (2) · 1 running · 0 queued · 1 completed · 0 wrapped up · 0 stopped · 0 aborted · 0 failed
 Agent types (6) · unified list of defaults and custom agents
+Model tiers (3) · the (model, thinking) catalogue
 Create new agent
 Settings
 ```
@@ -371,7 +373,8 @@ Settings
 - **Eject** — writes the embedded default config as a `.md` file to project or personal location, so you can customize it
 - **Disable/Enable** — toggle agent availability. Disabled agents stay visible in the list with a `disabled` label and can be re-enabled
 - **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do; a sub-agent writes a unique same-directory staging file, and the parent parses and compare-commits it to the target). Any name is allowed, including default agent names (overrides them)
-- **Settings** — configure max concurrency, default max turns, grace turns, and join mode at runtime
+- **Model tiers** — create, edit and delete the [tier](#model-tiers) profiles. Each row shows what the tier resolves to on this machine (`small — claude-haiku-4-5 · thinking max`), and a tier dropped as malformed is listed as `blocked` so it can be fixed rather than staying invisible. The model picker offers this machine's available models (narrowed to your scope when **Scope models** is on) plus `inherit` and a typed escape hatch; the thinking picker offers only the levels the chosen model actually supports, since the rest would be silently clamped at spawn. Deleting the tier that `defaultTier` names clears the default in the same step
+- **Settings** — configure max concurrency, default max turns, grace turns, default model, default tier, and join mode at runtime
 
 ## Graceful Max Turns
 
@@ -464,15 +467,70 @@ the next pi session, since the description is built once at registration.
 1. `tier` passed to the `Agent` call
 2. `tier:` in the agent's frontmatter
 3. `agentTiers.defaultTier`
-4. legacy `model:`/`thinking:` in the agent's frontmatter
+4. `defaultModel` — a model with no tier attached, for workspaces that want one
+   setting rather than a catalogue
 5. the parent session's model and thinking
 
-A tier that applies decides both fields outright — it is current policy, while a
-per-agent `model:` pin is the older, weaker statement of the same thing. An agent
-carrying both logs a warning naming the file to clean up.
+An agent cannot pin its own model at any step. `model:`/`thinking:` in
+frontmatter are read only to warn that they are stale, and the built-in agents
+pin nothing either. With nothing configured at all, a subagent runs on the
+parent session's model.
+
+### `defaultModel`
+
+Steps 1–3 are a catalogue; step 4 is one line. Set it when the whole point is
+"subagents run on the cheap model" and there is no second policy to name:
+
+```json
+{ "defaultModel": "anthropic/claude-haiku-4-5" }
+```
+
+It only decides the model — thinking still comes from the parent, because a
+level nobody chose for a specific model is exactly what a tier exists to
+express. Any tier that applies overrides it outright.
+
+Set it from `/agents → Settings → Default model` (Enter opens the picker), or by
+hand. It accepts the same references a tier's `model` does, plus the literal
+`"inherit"`, which is how a project cancels a global `defaultModel` — omitting
+the key inherits whatever the global file set.
+
+Unlike a tier, an unresolvable `defaultModel` does **not** fail the spawn: it
+falls back to the parent model, and the Settings row shows
+`(unavailable, fallback: inherit)`. A tier is refused because someone named that
+policy at the call site; `defaultModel` is the value nobody named, so one
+unauthed provider must not take every spawn on the machine down with it.
+
+### Editing tiers
+
+`/agents → Model tiers` manages the catalogue — new tier, change a tier's model,
+thinking or description, delete one. `defaultTier` lives with the other defaults
+in `/agents → Settings → Default tier`. Both write the project file; the global
+file is never written from the menu.
+
+Two things the menu knows that a hand-edited file does not: the thinking picker
+offers only levels the chosen model supports (the rest get clamped at spawn
+anyway), and a tier dropped as malformed still appears in the list, marked
+`blocked`, so redefining it is one selection rather than an archaeology
+expedition through `subagents.json`.
+
+The `Agent` tool description is built once at registration, so a tier edit
+reaches the model on the next pi session. Resolution itself is live — a spawn
+right after the edit already uses the new profile.
+
+One thing the file format cannot express: a project *deleting* a tier that only
+the global file defines. The menu writes the merged catalogue back to the
+project file, so deleting one of several works, but deleting the last one — or
+clearing a `defaultTier` that only global sets — leaves no `agentTiers` key
+behind, and the global value is inherited again on the next start. Remove it
+from `~/.pi/agent/subagents.json` instead. The same is true of `workflow.tiers`.
 
 ### Refusals
 
+A `defaultTier`, or an agent's `tier:`, that names no defined profile is
+reported at **startup**, listing the available keys — a typo there would
+otherwise sit quiet until the first spawn that needed it, possibly minutes into
+a session.
+
 These fail **before** the spawn, with the tier key and where it came from named.
 None of them silently substitutes another model:
 
@@ -501,11 +559,14 @@ standing in for the other.
 
 ### Migrating from `model:`/`thinking:`
 
-Existing agents keep working: with no `agentTiers` configured, resolution falls
-through to the legacy fields exactly as before. To migrate, define the profiles
-once and replace the per-agent pins with `tier: <name>`. Programmatic callers and
-the legacy RPC may still pass `model`/`thinking` directly; only the LLM-facing
-`Agent` and nested-Agent schemas dropped them.
+Define the profiles once, then replace each agent's `model:`/`thinking:` with
+`tier: <name>`. Files that still carry the old fields load and run — the fields
+are ignored, with a warning naming the file — so the migration can be done one
+agent at a time. Until an agent names a tier it uses `defaultTier`, or the
+parent's model when none is set.
+
+Programmatic callers and the legacy RPC may still pass `model`/`thinking`
+directly. That is the escape hatch for code, not a way to configure an agent.
 
 ## Model Scope
 
@@ -531,7 +592,7 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, nested depth, fallback agent, default join mode, scheduling on/off, scope models on/off, strict agent files on/off, disable defaults on/off, output transcript on/off, tool description full/compact/custom, fleet view on/off) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, nested depth, fallback agent, default model, default tier, default join mode, scheduling on/off, scope models on/off, strict agent files on/off, disable defaults on/off, output transcript on/off, tool description full/compact/custom, fleet view on/off) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
@@ -555,6 +616,8 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, default m
 
 Profiles are complete `model` + `thinking` tuples. Each field may use `inherit`; a project profile replaces the whole matching global tier entry. Malformed or incomplete entries are retained as durable blocked-tier tombstones and fail closed rather than falling back to a built-in profile or merging field-by-field. An explicit `defaultTier` applies when a workflow task omits its tier. Without a task tier or configured default, the parent model and thinking level are inherited. Agent frontmatter remains authoritative for its explicit `model` and `thinking`; thinking is clamped to the selected model's native supported levels.
 
+**Default model** (`defaultModel`, unset): the model a subagent runs when no tier picked one — see [`defaultModel`](#defaultmodel) for where it sits in precedence, why an unresolvable value falls back instead of failing, and how `"inherit"` lets a project cancel a global default. **Default tier** (`agentTiers.defaultTier`, unset) is the tier applied when neither the caller nor the agent names one; the profiles it selects from live under [`agentTiers`](#model-tiers).
+
 **Strict agent files** (`strictAgentFiles`, default `false`): normal startup skips unreadable or malformed agent definitions with a warning that includes the file path. Enable it to fail closed during the first `session_start`, using that session's `ctx.cwd`, with the path in the error instead of silently running a surviving lower-priority override. A failed validation leaves no root manager or RPC responder behind. Reloads after startup remain lenient, so an accidental edit cannot terminate an active session; the setting applies on the next pi session.
 
 **Nested depth** (`maxSubagentDepth`, default `2`): the hard ceiling on [nested delegation](#nested-subagents), counted from the main session (main = 0, its subagents = 1). `0` or `1` disables nesting project-wide regardless of any agent's `allowed_subagents`. Read when a subagent session is built, so a change applies to agents started after it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",

package/src/agent-file-toggle.ts

@@ -691,8 +691,9 @@ export function serializeAgentFile(cfg: AgentConfig): string {
   fmFields.push(`description: ${JSON.stringify(cfg.description)}`);
   if (cfg.displayName) fmFields.push(`display_name: ${JSON.stringify(cfg.displayName)}`);
   fmFields.push(`tools: ${formatYamlScalar(formatToolsField(cfg))}`);
-  if (cfg.model) fmFields.push(`model: ${JSON.stringify(cfg.model)}`);
-  if (cfg.thinking) fmFields.push(`thinking: ${formatYamlScalar(cfg.thinking)}`);
+  // Never model:/thinking: — the loader ignores them, so writing them back
+  // would recreate a pin that looks effective and is not.
+  if (cfg.agentTier) fmFields.push(`tier: ${formatYamlScalar(cfg.agentTier)}`);
   if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
   if (cfg.persistSession) fmFields.push("persist_session: true");
   if (cfg.sessionDir) fmFields.push(`session_dir: ${JSON.stringify(cfg.sessionDir)}`);

package/src/agent-runner.ts

@@ -30,6 +30,7 @@ import {
   type InternalAgentConfigOverride,
 } from "./internal-run.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { checkModelScope } from "./model-scope.js";
 import { createNestedSubagentTools, getMaxSubagentDepth, type NestedAgentManager } from "./nested-tools.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
@@ -331,13 +332,56 @@ export function getGraceTurns(): number { return graceTurns; }
 /** Set the grace turns value (minimum 1). */
 export function setGraceTurns(n: number): void { graceTurns = Math.max(1, n); }
 
+/**
+ * Model every subagent falls back to when nothing else picked one.
+ *
+ * Held here rather than in settings.ts because this is the one module that
+ * consumes it, and every spawn path already reaches model resolution through
+ * `runAgent`.
+ *
+ * Stored verbatim, `"inherit"` included, rather than normalized to `undefined`:
+ * the two are the same at spawn time but not on disk. A project that must
+ * cancel a global `defaultModel` has to write `"inherit"` into its own settings
+ * file, and a state that had already collapsed it to `undefined` would persist
+ * as an absent key and let the global value win again on the next start.
+ */
+let defaultModel: string | undefined;
+
+/** The configured fallback model reference — a `provider/model`, `"inherit"`, or unset. */
+export function getDefaultModel(): string | undefined { return defaultModel; }
+/** Set the fallback model reference. `undefined` and blank clear it; `"inherit"` is kept. */
+export function setDefaultModel(ref: string | undefined): void {
+  const trimmed = ref?.trim();
+  defaultModel = trimmed ? trimmed : undefined;
+}
+
+/**
+ * The configured default model, resolved against this machine's registry.
+ *
+ * Resolved with the same fuzzy `resolveModel` the tiers use, so a hand-written
+ * `subagents.json` may name a model the way a person would. Unlike a tier it
+ * never throws: it is the value nobody chose at the call site, so an
+ * unavailable one yields to the parent rather than taking every spawn on this
+ * machine down with it.
+ *
+ * Exported because the callers that compute a spawn's model for the scope check
+ * and the UI label have to see the same answer this module will act on.
+ */
+export function resolveConfiguredDefaultModel(
+  registry: ModelRegistry<Model<any>>,
+): Model<any> | undefined {
+  if (!defaultModel || defaultModel === "inherit") return undefined;
+  const resolved = resolveModel(defaultModel, registry);
+  return typeof resolved === "string" ? undefined : resolved;
+}
+
 /**
  * Try to find the right model for an agent type.
- * Priority: explicit option > config.model > parent model.
+ * Priority: explicit option > config.model > configured default model > parent model.
  */
 function resolveDefaultModel(
   parentModel: Model<any> | undefined,
-  registry: { find(provider: string, modelId: string): Model<any> | undefined; getAvailable?(): Model<any>[] },
+  registry: ModelRegistry<Model<any>>,
   configModel?: string,
 ): Model<any> | undefined {
   if (configModel) {
@@ -349,7 +393,7 @@ function resolveDefaultModel(
       // Build a set of available model keys for fast lookup
       const available = registry.getAvailable?.();
       const availableKeys = available
-        ? new Set(available.map((m: any) => `${m.provider}/${m.id}`))
+        ? new Set(available.map((m) => `${m.provider}/${m.id}`))
         : undefined;
       const isAvailable = (p: string, id: string) =>
         !availableKeys || availableKeys.has(`${p}/${id}`);
@@ -359,7 +403,7 @@ function resolveDefaultModel(
     }
   }
 
-  return parentModel;
+  return resolveConfiguredDefaultModel(registry) ?? parentModel;
 }
 
 /** Info about a tool event in the subagent. */
@@ -644,15 +688,7 @@ export async function runAgent(
     parentThinking,
     modelRegistry: ctx.modelRegistry,
   });
-  if (agentTierResolution.snapshot) {
-    options.onAgentTierResolved?.(agentTierResolution.snapshot);
-    if (agentConfig?.model !== undefined || agentConfig?.thinking !== undefined) {
-      console.warn(
-        `[pi-subagents] Agent "${agentConfig.name}" sets both tier "${agentTierResolution.snapshot.tier}" ` +
-          `and legacy model/thinking frontmatter; the tier wins. Remove model:/thinking: from the agent file.`,
-      );
-    }
-  }
+  if (agentTierResolution.snapshot) options.onAgentTierResolved?.(agentTierResolution.snapshot);
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;

package/src/agent-tiers.ts

@@ -25,7 +25,7 @@
 
 import { type Api, clampThinkingLevel, getSupportedThinkingLevels, type Model } from "@earendil-works/pi-ai";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import type { AgentTierProfile, AgentTiersSettings, TierThinking } from "./settings.js";
+import { type AgentTierProfile, type AgentTiersSettings, TIER_THINKING_LEVELS, type TierThinking } from "./settings.js";
 import type { AgentConfig, ThinkingLevel } from "./types.js";
 
 /** `provider/id`, or undefined when no model was selected. */
@@ -111,15 +111,117 @@ export class AgentTierError extends Error {
   }
 }
 
-function knownTierKeys(settings: AgentTiersSettings): string[] {
+/** Every defined tier key, sorted — the catalogue as the UI and the host see it. */
+export function listAgentTierKeys(settings: AgentTiersSettings): string[] {
   return Object.keys(settings.profiles ?? {}).sort((a, b) => a.localeCompare(b));
 }
 
 function tierKeyList(settings: AgentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   return keys.length > 0 ? keys.join(", ") : "(none configured)";
 }
 
+/**
+ * Tier edits, as pure settings-to-settings functions.
+ *
+ * The `/agents → Model tiers` menu is the only caller, but the rules it has to
+ * obey are policy, not presentation — retiring a tombstone, not leaving
+ * `defaultTier` pointing at a tier that no longer exists — so they live here
+ * with the resolver that enforces the other half of the same invariants.
+ *
+ * Each returns a fresh object and omits empty containers, so a catalogue edited
+ * back down to nothing serializes as nothing rather than as empty braces.
+ */
+function withoutBlocked(blocked: string[] | undefined, key: string): string[] | undefined {
+  const rest = (blocked ?? []).filter((k) => k !== key);
+  return rest.length > 0 ? rest : undefined;
+}
+
+function compactTierSettings(settings: AgentTiersSettings): AgentTiersSettings {
+  const out: AgentTiersSettings = {};
+  if (settings.defaultTier !== undefined) out.defaultTier = settings.defaultTier;
+  if (settings.profiles && Object.keys(settings.profiles).length > 0) out.profiles = settings.profiles;
+  if (settings.blockedProfiles && settings.blockedProfiles.length > 0) {
+    out.blockedProfiles = settings.blockedProfiles;
+  }
+  if (settings.blockedDefaultTier) out.blockedDefaultTier = true;
+  return out;
+}
+
+/**
+ * Define or replace one tier.
+ *
+ * Writing a valid profile retires that key's tombstone: the tombstone exists to
+ * stop a malformed entry from silently resolving to some other model, and an
+ * explicit definition is the fix it was waiting for.
+ */
+export function upsertAgentTierProfile(
+  settings: AgentTiersSettings,
+  key: string,
+  profile: AgentTierProfile,
+): AgentTiersSettings {
+  return compactTierSettings({
+    ...settings,
+    profiles: { ...settings.profiles, [key]: profile },
+    blockedProfiles: withoutBlocked(settings.blockedProfiles, key),
+  });
+}
+
+/**
+ * Delete one tier.
+ *
+ * A `defaultTier` pointing at it is cleared in the same step. Leaving it would
+ * turn every later spawn that names no tier into a hard refusal, which is a
+ * strange thing to get from deleting a tier you had stopped using.
+ */
+export function removeAgentTierProfile(settings: AgentTiersSettings, key: string): AgentTiersSettings {
+  const { [key]: _removed, ...profiles } = settings.profiles ?? {};
+  return compactTierSettings({
+    ...settings,
+    profiles,
+    blockedProfiles: withoutBlocked(settings.blockedProfiles, key),
+    ...(settings.defaultTier === key ? { defaultTier: undefined } : {}),
+  });
+}
+
+/**
+ * The thinking values a tier may usefully store for one model reference.
+ *
+ * Asked of the model rather than read off a fixed list, because `resolveAgentTier`
+ * clamps an unsupported level at spawn time: a menu offering a level destined to
+ * be silently lowered would be a menu that lies. `inherit` is always offerable —
+ * it defers to the parent session, which this model has no say over.
+ *
+ * A reference of `inherit`, or one this machine cannot resolve, yields the full
+ * static list: the model is not knowable here, and refusing to let the user
+ * configure a tier for a provider they have not authed yet would make the menu
+ * weaker than hand-editing the file.
+ */
+export function offerableTierThinking(
+  modelRef: string,
+  registry: ModelRegistry<Model<Api>>,
+): TierThinking[] {
+  if (modelRef === "inherit") return [...TIER_THINKING_LEVELS];
+  const resolved = resolveModel(modelRef, registry);
+  if (typeof resolved === "string") return [...TIER_THINKING_LEVELS];
+  const supported = new Set<string>(getSupportedThinkingLevels(resolved));
+  return TIER_THINKING_LEVELS.filter(level => level === "inherit" || supported.has(level));
+}
+
+/**
+ * Set or clear the default tier.
+ *
+ * Always clears `blockedDefaultTier`: that tombstone describes the malformed
+ * value this call is replacing, and keeping it would make the resolver refuse
+ * the choice the user just made explicitly.
+ */
+export function setDefaultAgentTier(
+  settings: AgentTiersSettings,
+  key: string | undefined,
+): AgentTiersSettings {
+  return compactTierSettings({ ...settings, defaultTier: key, blockedDefaultTier: false });
+}
+
 /**
  * Which tier applies, and where it came from.
  *
@@ -237,6 +339,45 @@ export function resolveAgentTier(input: ResolveAgentTierInput): AgentTierResolut
   return { model, thinkingLevel, snapshot };
 }
 
+/**
+ * Every tier name that is referenced but not defined.
+ *
+ * The resolver refuses these at spawn time anyway, but a `defaultTier` typo
+ * would otherwise sit quiet until the first agent that names no tier — which
+ * may be minutes into a session, in the middle of something. Checking the
+ * references once, when settings and agents are loaded, moves that discovery to
+ * where it is cheap and where the fix is obvious.
+ *
+ * `agentNames` maps an agent to the tier its frontmatter asks for, so a typo in
+ * one agent file is reported the same way as one in `defaultTier`.
+ */
+export function findUnknownAgentTierReferences(
+  settings: AgentTiersSettings,
+  agentTiers: ReadonlyMap<string, string> = new Map(),
+): string[] {
+  const defined = new Set(Object.keys(settings.profiles ?? {}));
+  // With nothing configured there is no catalogue to be wrong about; the
+  // resolver simply never applies a tier.
+  if (defined.size === 0 && settings.defaultTier === undefined) return [];
+
+  const problems: string[] = [];
+  if (settings.defaultTier !== undefined && !defined.has(settings.defaultTier)) {
+    problems.push(
+      `agentTiers.defaultTier is "${settings.defaultTier}", which is not a defined tier. ` +
+        `Available: ${tierKeyList(settings)}`,
+    );
+  }
+  for (const [agent, tier] of [...agentTiers].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!defined.has(tier)) {
+      problems.push(
+        `Agent "${agent}" asks for tier "${tier}", which is not a defined tier. ` +
+          `Available: ${tierKeyList(settings)}`,
+      );
+    }
+  }
+  return problems;
+}
+
 /**
  * The tier catalogue, rendered for the `Agent` tool description.
  *
@@ -246,7 +387,7 @@ export function resolveAgentTier(input: ResolveAgentTierInput): AgentTierResolut
  * models and thinking levels appear — nothing here reads credentials.
  */
 export function buildAgentTierListText(settings: AgentTiersSettings = agentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   if (keys.length === 0) return "";
 
   const entries = keys.map((key) => {
@@ -265,7 +406,7 @@ export function buildAgentTierListText(settings: AgentTiersSettings = agentTiers
 
 /** One line per tier, for the compact tool description. */
 export function buildCompactAgentTierListText(settings: AgentTiersSettings = agentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   if (keys.length === 0) return "";
 
   const entries = keys.map((key) => {
@@ -284,7 +425,7 @@ export function getDefaultAgentTierText(settings: AgentTiersSettings = agentTier
 
 /** Description for the `tier` parameter, naming the keys this workspace defines. */
 export function buildAgentTierParameterDescription(settings: AgentTiersSettings = agentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   const available = keys.length > 0 ? keys.join(", ") : "none configured";
   const fallback =
     settings.defaultTier !== undefined

package/src/custom-agents.ts

@@ -8,7 +8,7 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { isValidAgentTierKey } from "./agent-tiers.js";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js";
+import type { AgentConfig, MemoryScope } from "./types.js";
 import { sanitizeDisplayText } from "./ui/safe-text.js";
 
 /**
@@ -164,6 +164,7 @@ function loadFromDir(
     const { frontmatter: fm, body } = parsed;
 
     const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
+    warnLegacyModelFields(fm, path, warn);
 
     agents.set(name, {
       name,
@@ -176,8 +177,6 @@ function loadFromDir(
       excludeExtensions: csvListOptional(fm.exclude_extensions),
       skills: inheritField(fm.skills ?? fm.inherit_skills),
       agentTier: parseTier(fm.tier, path, warn),
-      model: str(fm.model),
-      thinking: str(fm.thinking) as ThinkingLevel | undefined,
       maxTurns: nonNegativeInt(fm.max_turns),
       persistSession: fm.persist_session != null ? fm.persist_session === true : undefined,
       outputTranscript: fm.output_transcript != null ? fm.output_transcript !== false : undefined,
@@ -197,6 +196,25 @@ function loadFromDir(
     priorities.set(name, priority);
   }
 }
+/**
+ * Report a `model:`/`thinking:` pin left over from before tiers.
+ *
+ * An agent file no longer chooses its own model — the tier catalogue in
+ * `subagents.json` does, and a per-file pin would be a way around it. The file
+ * still loads: a stale pin is a migration the author has not done yet, not a
+ * reason to take the agent away mid-session. It simply has no effect, and the
+ * warning names the file so it can be fixed.
+ */
+function warnLegacyModelFields(fm: Record<string, unknown>, path: string, warn: WarningSink): void {
+  const present = ["model", "thinking"].filter((field) => fm[field] != null);
+  if (present.length === 0) return;
+  warn(
+    `Ignoring ${present.join(" and ")} in ${path}: agents pick a model with "tier:" now. ` +
+      `Replace it with a tier from agentTiers.profiles, or remove it to use the default tier.`,
+    `legacy-model:${warningIdentity(path)}`,
+  );
+}
+
 /** Read and parse one agent file, warning or throwing with its path on failure. */
 function readAgentFile(
   path: string,
@@ -279,6 +297,9 @@ function label(val: unknown): string | undefined {
  */
 function parseTier(val: unknown, path: string, warn: WarningSink): string | undefined {
   if (val === undefined || val === null) return undefined;
+  // Deliberately not "no tier means no model": which model an agent runs is
+  // decided by the tier catalogue, so an agent that names no tier falls to
+  // `agentTiers.defaultTier` rather than pinning anything itself.
   if (isValidAgentTierKey(val)) return val;
   warn(
     `Ignoring invalid tier in ${path}: expected a non-empty single-word key`,

package/src/default-agents.ts

@@ -34,10 +34,11 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       builtinToolNames: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,
-      // Fast/cheap model for read-only search. Provider-preferred but resilient:
-      // resolveModel matches this fuzzily (date-stamp optional) and falls back to
-      // the same model under another provider if anthropic doesn't expose it.
-      model: "anthropic/claude-haiku-4-5",
+      // No model pin. Which model a subagent runs is the tier catalogue's
+      // decision; a built-in that pinned one would be the same end-run around it
+      // that agent frontmatter is no longer allowed to make, and it would name a
+      // vendor on a machine that may not have it. With no tier configured this
+      // inherits the parent's model, which is the documented fallback.
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
 Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.

package/src/index.ts

@@ -26,14 +26,22 @@ import {
   type ManagedSpawnResult,
   type ManagedSpawnTombstone,
 } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, getDefaultMaxTurns, getDefaultModel, getGraceTurns, normalizeMaxTurns, resolveConfiguredDefaultModel, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setDefaultModel, setGraceTurns, steerAgent } from "./agent-runner.js";
 import {
   buildAgentTierListText,
   buildAgentTierParameterDescription,
   buildCompactAgentTierListText,
+  findUnknownAgentTierReferences,
   getAgentTiersSettings,
   getDefaultAgentTierText,
+  isValidAgentTierKey,
+  listAgentTierKeys,
+  MAX_AGENT_TIER_KEY_LENGTH,
+  offerableTierThinking,
+  removeAgentTierProfile,
   setAgentTiersSettings,
+  setDefaultAgentTier,
+  upsertAgentTierProfile,
 } from "./agent-tiers.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getFallbackSubagent, isDefaultsDisabled, NO_FALLBACK, registerAgents, resolveSpawnType, resolveType, setDefaultsDisabled, setFallbackSubagent } from "./agent-types.js";
 import { inChildSessionContext } from "./child-context.js";
@@ -55,7 +63,7 @@ import { getMaxSubagentDepth, setMaxSubagentDepth } from "./nested-tools.js";
 import { createOutputFilePath, getOutputTranscriptDefault, setOutputTranscriptDefault, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
-import { applySettings, loadSettings, type SubagentsSettings, saveAndEmitChanged, type ToolDescriptionMode } from "./settings.js";
+import { type AgentTierProfile, applySettings, isModelReference, loadSettings, type SubagentsSettings, saveAndEmitChanged, type TierThinking, type ToolDescriptionMode } from "./settings.js";
 import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
 import { type AgentConfig, type AgentInvocation, type AgentOwner, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
 import {
@@ -1014,7 +1022,7 @@ function activateRootRuntime(
     // workflow tier is active. Tiered runs validate their effective policy inside
     // runAgent after the tier model has been resolved.
     if (effectiveTier === undefined) {
-      let model = ctxRef.model;
+      let model = resolveConfiguredDefaultModel(ctxRef.modelRegistry) ?? ctxRef.model;
       if (resolvedConfig.modelInput) {
         const resolved = resolveModel(resolvedConfig.modelInput, ctxRef.modelRegistry);
         if (typeof resolved === "object") model = resolved;
@@ -1191,7 +1199,7 @@ function activateRootRuntime(
 
     return available.map((name) => {
       const cfg = getAgentConfig(name);
-      const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+      const modelSuffix = cfg?.agentTier ? ` (tier: ${cfg.agentTier})` : "";
       const toolsSuffix = ` (Tools: ${formatToolsSuffix(cfg)})`;
       return `- ${name}: ${cfg?.description ?? name}${modelSuffix}${toolsSuffix}`;
     }).join("\n");
@@ -1225,6 +1233,7 @@ function activateRootRuntime(
     setDefaultMaxTurns,
     setGraceTurns,
     setDefaultJoinMode,
+    setDefaultModel,
     setSchedulingEnabled,
     setScopeModels: setScopeModelsEnabled,
     setStrictAgentFiles: (enabled) => { strictAgentFiles = enabled; },
@@ -1239,6 +1248,21 @@ function activateRootRuntime(
   });
   pi.events.emit("subagents:settings_loaded", { settings: startupSettings });
 
+  // A tier that nothing defines is a typo, and the resolver would only reach it
+  // on the first spawn that needs it — possibly minutes in, mid-task. Report it
+  // now, while the fix is obvious and nothing has run.
+  const tierReferenceProblems = findUnknownAgentTierReferences(
+    getAgentTiersSettings(),
+    new Map(
+      getAvailableTypes()
+        .map((name): [string, string | undefined] => [name, getAgentConfig(name)?.agentTier])
+        .filter((entry): entry is [string, string] => entry[1] !== undefined),
+    ),
+  );
+  for (const problem of tierReferenceProblems) {
+    console.warn(`[pi-subagents] ${problem}`);
+  }
+
   // ---- Agent tool ----
 
   // Schedule param + its guideline are gated on `schedulingEnabled` (read once
@@ -1593,12 +1617,15 @@ Terse command-style prompts produce shallow, generic work.
       const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
 
       // Resolve model from agent config first; tool-call params only fill gaps.
-      let model = ctx.model;
+      // With neither, runAgent falls to the configured `defaultModel` before the
+      // parent, so mirror that here — the scope check below and the model label
+      // must describe the model that will actually run.
+      let model = resolveConfiguredDefaultModel(ctx.modelRegistry) ?? ctx.model;
       if (resolvedConfig.modelInput) {
         const resolved = resolveModel(resolvedConfig.modelInput, ctx.modelRegistry);
         if (typeof resolved === "string") {
           if (resolvedConfig.modelFromParams) return textResult(resolved);
-          // config-specified: silent fallback to parent
+          // config-specified: silent fallback to the default model, then parent
         } else {
           model = resolved;
         }
@@ -2079,24 +2106,34 @@ Terse command-style prompts produce shallow, generic work.
   // Directory resolution and frontmatter edits live in agent-file-toggle.ts so
   // they can be tested independently of this command handler.
 
-  function getModelLabel(type: string, registry?: ModelRegistry): string {
-    const cfg = getAgentConfig(type);
-    if (!cfg?.model) return "inherit"; // no model configured → really inherits parent
-    const label = getModelLabelFromConfig(cfg.model);
+  /**
+   * Render one configured model reference for a menu row.
+   *
+   * Shared by the agent list, the `Default model` setting and the tier editor,
+   * because all three show a value someone typed into a settings file and all
+   * three have to answer the same question about it: does this machine actually
+   * have it? A reference that doesn't resolve falls back at runtime, so the
+   * label says so rather than showing config that isn't in force.
+   */
+  function describeModelReference(ref: string | undefined, registry?: ModelRegistry): string {
+    if (!ref || ref === "inherit") return "inherit"; // no model configured → really inherits parent
+    const label = getModelLabelFromConfig(ref);
     if (!registry) return label;
-    const resolved = resolveModel(cfg.model, registry);
-    // Configured but unresolvable: the runtime silently falls back to the parent
-    // model, so flag it (and the fallback) rather than hiding the config.
+    const resolved = resolveModel(ref, registry);
     if (typeof resolved === "string") return `${label} (unavailable, fallback: inherit)`;
     // Surface what it actually resolved to when that differs from the config —
     // e.g. a provider fallback or a looser version pin. Cosmetic separator/date
     // differences are normalized away so an effectively-identical match stays quiet.
     const resolvedFull = `${resolved.provider}/${resolved.id}`;
     const norm = (s: string) => s.toLowerCase().replace(/\./g, "-").replace(/-\d{8}$/, "");
-    if (norm(cfg.model) === norm(resolvedFull)) return label;
+    if (norm(ref) === norm(resolvedFull)) return label;
     return `${label} (resolved: ${resolvedFull.replace(/-\d{8}$/, "")})`;
   }
 
+  function getModelLabel(type: string, registry?: ModelRegistry): string {
+    return describeModelReference(getAgentConfig(type)?.model, registry);
+  }
+
   async function showAgentsMenu(ctx: ExtensionCommandContext) {
     reloadCustomAgents();
     const allNames = getAllTypes();
@@ -2119,6 +2156,11 @@ Terse command-style prompts produce shallow, generic work.
       options.push(`Scheduled jobs (${jobCount})`);
     }
 
+    // Model tiers entry — always present, since an empty catalogue is exactly
+    // the state where the user needs the way in to create the first tier.
+    const tierCount = listAgentTierKeys(getAgentTiersSettings()).length;
+    options.push(`Model tiers (${tierCount})`);
+
     // Actions
     options.push("Create new agent");
     options.push("Settings");
@@ -2145,6 +2187,9 @@ Terse command-style prompts produce shallow, generic work.
     } else if (choice.startsWith("Scheduled jobs (")) {
       await showSchedulesMenu(ctx, scheduler);
       await showAgentsMenu(ctx);
+    } else if (choice.startsWith("Model tiers (")) {
+      await showModelTiersMenu(ctx);
+      await showAgentsMenu(ctx);
     } else if (choice === "Create new agent") {
       await showCreateWizard(ctx);
     } else if (choice === "Settings") {
@@ -2767,6 +2812,9 @@ Do not wrap the response in a markdown code fence. Return only the file contents
       defaultMaxTurns: getDefaultMaxTurns() ?? 0,
       graceTurns: getGraceTurns(),
       defaultJoinMode: getDefaultJoinMode(),
+      // `"inherit"` is written out verbatim so a project can cancel a global
+      // default; never configured stays undefined, which JSON.stringify drops.
+      defaultModel: getDefaultModel(),
       schedulingEnabled: isSchedulingEnabled(),
       scopeModels: isScopeModelsEnabled(),
       strictAgentFiles,
@@ -2808,6 +2856,69 @@ Do not wrap the response in a markdown code fence. Return only the file contents
   void _settingsSnapshotIsComplete;
 
   const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns", "maxSubagentDepth"]);
+  /**
+   * Settings whose value is chosen in a dialog rather than cycled in place.
+   * Enter closes the list and reopens it once the dialog resolves, the same way
+   * the numeric fields hand off to a text prompt.
+   */
+  const PICKER_IDS = new Set(["defaultModel"]);
+  /** Row value standing in for "no default tier configured". Not a tier key — keys reject whitespace, not words. */
+  const NO_DEFAULT_TIER = "none";
+  /** Menu entry that starts a new tier instead of editing an existing one. */
+  const NEW_TIER_ENTRY = "+ New tier...";
+
+  /**
+   * Ask for a model reference: this machine's models, plus `inherit` and a
+   * typed escape hatch.
+   *
+   * The escape hatch is not decoration — the settings file accepts references
+   * this machine cannot resolve, which is exactly what a shared project config
+   * naming a provider only some teammates have authed looks like. A picker able
+   * to express only what is available here would be weaker than the file it
+   * writes.
+   *
+   * With `scopeModels` on and a scope configured, the list narrows to that
+   * scope: offering a model the same setting would warn about on every spawn is
+   * a menu arguing with itself.
+   */
+  async function pickModelReference(
+    ctx: ExtensionCommandContext,
+    title: string,
+    current: string | undefined,
+  ): Promise<string | undefined> {
+    const CUSTOM = "custom...";
+    const candidates = isScopeModelsEnabled() && ctx.scopedModels.length > 0
+      ? ctx.scopedModels.map(scoped => scoped.model)
+      : ctx.modelRegistry.getAvailable();
+    const refs = [...new Set(candidates.map(m => `${m.provider}/${m.id}`))].sort((a, b) => a.localeCompare(b));
+
+    const choice = await ctx.ui.select(title, ["inherit", ...refs, CUSTOM]);
+    if (!choice) return undefined;
+    if (choice !== CUSTOM) return choice;
+
+    const typed = await ctx.ui.input("Model (provider/modelId, or inherit)", current ?? "");
+    const trimmed = typed?.trim();
+    if (!trimmed) return undefined;
+    if (!isModelReference(trimmed)) {
+      // Refuse here rather than at save: saveSettings drops unrecognized fields
+      // silently, which would show a success toast for a setting that vanished.
+      ctx.ui.notify(`"${trimmed}" is not a model reference. Use provider/modelId, or inherit.`, "warning");
+      return undefined;
+    }
+    return trimmed;
+  }
+
+  async function pickDefaultModel(ctx: ExtensionCommandContext) {
+    const chosen = await pickModelReference(ctx, "Default model", getDefaultModel());
+    if (chosen === undefined) return;
+    setDefaultModel(chosen);
+    notifyApplied(
+      ctx,
+      chosen === "inherit"
+        ? "Default model set to inherit — subagents follow the parent session."
+        : `Default model set to ${chosen}. Applies to spawns where no tier picks a model.`,
+    );
+  }
 
   async function showSettings(ctx: ExtensionCommandContext) {
     function buildItems(): SettingItem[] {
@@ -2822,6 +2933,8 @@ Do not wrap the response in a markdown code fence. Return only the file contents
       // persist a fallback that would hard-error on every dispatch.
       const fallbackValue = getFallbackSubagent() ?? "general-purpose";
       const fallbackValues = [...new Set([...getAvailableTypes(), NO_FALLBACK])];
+      const defaultModelLabel = describeModelReference(getDefaultModel(), ctx.modelRegistry);
+      const tierKeys = listAgentTierKeys(getAgentTiersSettings());
 
       return [
         {
@@ -2852,6 +2965,26 @@ Do not wrap the response in a markdown code fence. Return only the file contents
           currentValue: String(msd),
           values: [String(msd)],
         },
+        {
+          id: "defaultModel",
+          label: "Default model",
+          description:
+            "Model a subagent runs when no tier applies (Enter to choose). \"inherit\" follows the parent session. A tier always wins over this.",
+          currentValue: defaultModelLabel,
+          // Single-value list: the real choice is a picker, opened on Enter,
+          // because cycling a registry of models one keypress at a time is not
+          // a usable way to pick one.
+          values: [defaultModelLabel],
+        },
+        {
+          id: "defaultTier",
+          label: "Default tier",
+          description: tierKeys.length > 0
+            ? "Tier applied when neither the caller nor the agent names one. Edit the tiers themselves in /agents → Model tiers."
+            : "No tiers defined yet — create one in /agents → Model tiers.",
+          currentValue: getAgentTiersSettings().defaultTier ?? NO_DEFAULT_TIER,
+          values: [NO_DEFAULT_TIER, ...tierKeys],
+        },
         {
           id: "joinMode",
           label: "Join mode",
@@ -2951,6 +3084,15 @@ Do not wrap the response in a markdown code fence. Return only the file contents
               : `Nested depth set to ${n}. Applies to agents started from now on.`,
           );
         }
+      } else if (id === "defaultTier") {
+        const tier = value === NO_DEFAULT_TIER ? undefined : value;
+        setAgentTiersSettings(setDefaultAgentTier(getAgentTiersSettings(), tier));
+        notifyApplied(
+          ctx,
+          tier === undefined
+            ? "Default tier cleared. Spawns that name no tier use the default model."
+            : `Default tier set to ${tier}. The tool description updates on the next pi session.`,
+        );
       } else if (id === "joinMode") {
         setDefaultJoinMode(value as JoinMode);
         notifyApplied(ctx, `Default join mode set to ${value}`);
@@ -3034,9 +3176,10 @@ Do not wrap the response in a markdown code fence. Return only the file contents
             currentIndex = Math.min(items.length - 1, currentIndex + 1);
           }
 
-          // Enter on numeric field → close and prompt for typed input
-          if (matchesKey(data, Key.enter) && NUMERIC_IDS.has(items[currentIndex].id)) {
-            done(items[currentIndex].id);
+          // Enter on a numeric or picker field → close and open its dialog
+          const focusedId = items[currentIndex].id;
+          if (matchesKey(data, Key.enter) && (NUMERIC_IDS.has(focusedId) || PICKER_IDS.has(focusedId))) {
+            done(focusedId);
             return;
           }
           list.handleInput?.(data);
@@ -3044,6 +3187,12 @@ Do not wrap the response in a markdown code fence. Return only the file contents
       };
     });
 
+    if (result === "defaultModel") {
+      await pickDefaultModel(ctx);
+      await showSettings(ctx);
+      return;
+    }
+
     // If a numeric field ID was returned, prompt for typed input
     if (result && NUMERIC_IDS.has(result)) {
       const current = result === "maxConcurrent"
@@ -3079,6 +3228,162 @@ Do not wrap the response in a markdown code fence. Return only the file contents
     }
   }
 
+  // ---- /agents → Model tiers ----
+  //
+  // The catalogue only; `defaultTier` stays in Settings next to the other
+  // defaults. Every mutation here goes through the pure helpers in
+  // agent-tiers.ts, so the rules that outlive a menu — retiring a tombstone,
+  // never leaving `defaultTier` pointing at a deleted tier — are tested without
+  // a terminal.
+
+  /** One catalogue row: what the tier resolves to on this machine. */
+  function describeTierRow(key: string, ctx: ExtensionCommandContext): string {
+    const settings = getAgentTiersSettings();
+    const profile = settings.profiles?.[key];
+    if (!profile) return `${key} — blocked (malformed profile in subagents.json)`;
+    const suffix = settings.defaultTier === key ? " (default)" : "";
+    const model = describeModelReference(profile.model, ctx.modelRegistry);
+    return `${key} — ${model} · thinking ${profile.thinking}${suffix}`;
+  }
+
+  /**
+   * Ask for a tier's thinking level, offering only what its model supports.
+   *
+   * A model with no thinking support at all leaves `inherit` as the single
+   * honest answer, so it is stored without a one-item menu to click through.
+   */
+  async function pickTierThinking(
+    ctx: ExtensionCommandContext,
+    modelRef: string,
+    current?: TierThinking,
+  ): Promise<TierThinking | undefined> {
+    const levels = offerableTierThinking(modelRef, ctx.modelRegistry);
+    if (levels.length === 1) {
+      ctx.ui.notify(
+        `${describeModelReference(modelRef, ctx.modelRegistry)} supports no thinking levels — storing "inherit".`,
+        "info",
+      );
+      return "inherit";
+    }
+    const choice = await ctx.ui.select(
+      current ? `Thinking level (now ${current})` : "Thinking level",
+      levels,
+    );
+    return choice as TierThinking | undefined;
+  }
+
+  /** Write one profile and report it, naming the delay the tool description has. */
+  function saveTierProfile(ctx: ExtensionCommandContext, key: string, profile: AgentTierProfile, verb: string) {
+    setAgentTiersSettings(upsertAgentTierProfile(getAgentTiersSettings(), key, profile));
+    notifyApplied(ctx, `Tier "${key}" ${verb}. The Agent tool description updates on the next pi session.`);
+  }
+
+  /**
+   * Define a tier from scratch.
+   *
+   * `presetKey` skips the name prompt: redefining a blocked tier already knows
+   * which name it is fixing, and asking again invites a typo that would leave
+   * the tombstone in place next to a near-miss twin.
+   */
+  async function createTier(ctx: ExtensionCommandContext, presetKey?: string) {
+    const rawKey = presetKey ?? (await ctx.ui.input("Tier name (one word, no spaces)"));
+    if (!rawKey) return;
+    const key = rawKey.trim();
+    if (!isValidAgentTierKey(key)) {
+      ctx.ui.notify(
+        `"${key}" is not a tier name. Use one word, no whitespace, at most ${MAX_AGENT_TIER_KEY_LENGTH} characters.`,
+        "warning",
+      );
+      return;
+    }
+    if (getAgentTiersSettings().profiles?.[key]) {
+      ctx.ui.notify(`Tier "${key}" already exists. Pick it from the list to edit it.`, "warning");
+      return;
+    }
+
+    const model = await pickModelReference(ctx, `Model for "${key}"`, undefined);
+    if (model === undefined) return;
+    const thinking = await pickTierThinking(ctx, model);
+    if (thinking === undefined) return;
+    // Description is what the host agent reads when choosing between tiers, so
+    // it is prose about the job, not about the model. Blank falls back to the key.
+    const description = await ctx.ui.input(`What is "${key}" for? (shown to the model, optional)`);
+
+    const trimmed = description?.trim();
+    saveTierProfile(ctx, key, { model, thinking, ...(trimmed ? { description: trimmed } : {}) }, "created");
+  }
+
+  async function editTier(ctx: ExtensionCommandContext, key: string) {
+    const profile = getAgentTiersSettings().profiles?.[key];
+    if (!profile) {
+      // A blocked key has no profile to edit; redefining it is the documented
+      // fix, and upsert retires the tombstone in the same write.
+      const redefine = await ctx.ui.confirm(
+        "Blocked tier",
+        `"${key}" was dropped as malformed. Define it again to unblock it?`,
+      );
+      if (redefine) await createTier(ctx, key);
+      return;
+    }
+
+    const MODEL = "Model";
+    const THINKING = "Thinking";
+    const DESCRIPTION = "Description";
+    const DELETE = "Delete tier";
+    const choice = await ctx.ui.select(`Tier "${key}"`, [MODEL, THINKING, DESCRIPTION, DELETE]);
+    if (!choice) return;
+
+    if (choice === MODEL) {
+      const model = await pickModelReference(ctx, `Model for "${key}"`, profile.model);
+      if (model === undefined) return;
+      saveTierProfile(ctx, key, { ...profile, model }, `now runs ${model}`);
+    } else if (choice === THINKING) {
+      const thinking = await pickTierThinking(ctx, profile.model, profile.thinking);
+      if (thinking === undefined) return;
+      saveTierProfile(ctx, key, { ...profile, thinking }, `now thinks ${thinking}`);
+    } else if (choice === DESCRIPTION) {
+      const description = await ctx.ui.input(`What is "${key}" for?`, profile.description ?? "");
+      if (description === undefined) return;
+      const trimmed = description.trim();
+      const { description: _dropped, ...rest } = profile;
+      saveTierProfile(ctx, key, { ...rest, ...(trimmed ? { description: trimmed } : {}) }, "description updated");
+    } else if (choice === DELETE) {
+      const wasDefault = getAgentTiersSettings().defaultTier === key;
+      const confirmed = await ctx.ui.confirm(
+        "Delete tier",
+        wasDefault
+          ? `Delete "${key}"? It is the default tier, so the default is cleared too.`
+          : `Delete "${key}"? Agents whose frontmatter names it will fail to spawn until you fix them.`,
+      );
+      if (!confirmed) return;
+      setAgentTiersSettings(removeAgentTierProfile(getAgentTiersSettings(), key));
+      notifyApplied(
+        ctx,
+        wasDefault
+          ? `Tier "${key}" deleted and the default tier cleared.`
+          : `Tier "${key}" deleted.`,
+      );
+    }
+  }
+
+  async function showModelTiersMenu(ctx: ExtensionCommandContext) {
+    const settings = getAgentTiersSettings();
+    // Blocked keys are listed alongside defined ones: they are the entries most
+    // in need of attention, and hiding them would leave a tier that refuses
+    // every spawn invisible in the menu that exists to manage tiers.
+    const keys = [...new Set([...listAgentTierKeys(settings), ...(settings.blockedProfiles ?? [])])]
+      .sort((a, b) => a.localeCompare(b));
+
+    const rows = keys.map(key => describeTierRow(key, ctx));
+    const choice = await ctx.ui.select("Model tiers", [...rows, NEW_TIER_ENTRY]);
+    if (!choice) return;
+
+    if (choice === NEW_TIER_ENTRY) await createTier(ctx);
+    else await editTier(ctx, keys[rows.indexOf(choice)]);
+
+    await showModelTiersMenu(ctx);
+  }
+
   // Persist the current snapshot, emit `subagents:settings_changed`, and surface
   // the right toast. Successful saves show info; persistence failures downgrade
   // to warning so users aren't silently reverted on restart. Event fires regardless

package/src/settings.ts

@@ -82,6 +82,25 @@ export interface SubagentsSettings {
    * these. See `agent-tiers.ts` for resolution and precedence.
    */
   agentTiers?: AgentTiersSettings;
+  /**
+   * The model a subagent runs when nothing else chose one — no tier applied and
+   * no programmatic override. It takes the place of the parent session's model
+   * as the last step of resolution, so a workspace can say "subagents run on the
+   * cheap model" without first defining a tier catalogue.
+   *
+   * A `provider/model` reference, or the literal `"inherit"` to follow the
+   * parent. `"inherit"` is spellable rather than merely omittable because a
+   * project needs a way to undo a global default; omitting the key inherits
+   * whatever global set.
+   *
+   * Deliberately weaker than a tier: a tier naming an unavailable model fails
+   * the spawn, because someone asked for that policy by name, while an
+   * unresolvable default model falls back to the parent. Failing every spawn on
+   * a machine that happens to lack one provider is the wrong trade for a value
+   * nobody named at the call site — the `/agents → Settings` row shows the
+   * fallback instead.
+   */
+  defaultModel?: string;
   maxConcurrent?: number;
   /**
    * 0 = unlimited — the extension's single source of truth for that convention:
@@ -195,6 +214,8 @@ export interface SettingsAppliers {
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
+  /** `undefined` and `"inherit"` both mean "follow the parent session". */
+  setDefaultModel: (ref: string | undefined) => void;
   setSchedulingEnabled: (b: boolean) => void;
   setScopeModels: (enabled: boolean) => void;
   setStrictAgentFiles: (b: boolean) => void;
@@ -215,15 +236,23 @@ export type SettingsEmit = (event: string, payload: unknown) => void;
 
 const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["async", "group", "smart"]);
 const VALID_TOOL_DESCRIPTION_MODES: ReadonlySet<string> = new Set<ToolDescriptionMode>(["full", "compact", "custom"]);
-const VALID_THINKING_LEVELS: ReadonlySet<string> = new Set([
+/**
+ * Thinking values a tier profile accepts, `inherit` first and then ascending.
+ *
+ * Ordered because the `/agents → Model tiers` editor offers them in this order;
+ * note `off` is absent — a profile that wants no thinking says so through the
+ * model it names, and `clampThinkingLevel` handles a model that supports none.
+ */
+export const TIER_THINKING_LEVELS: readonly TierThinking[] = [
+  "inherit",
   "minimal",
   "low",
   "medium",
   "high",
   "xhigh",
   "max",
-  "inherit",
-]);
+];
+const VALID_THINKING_LEVELS: ReadonlySet<string> = new Set(TIER_THINKING_LEVELS);
 const WORKFLOW_TIER_NAMES: readonly WorkflowTier[] = ["small", "medium", "large"];
 const MAX_MODEL_REFERENCE_LENGTH = 512;
 /** Mirrors MAX_AGENT_TIER_KEY_LENGTH in agent-tiers.ts; duplicated to keep settings dependency-free. */
@@ -244,7 +273,15 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function validWorkflowModelReference(value: unknown): value is string {
+/**
+ * `inherit`, or a bounded whitespace-free `provider/model` reference.
+ *
+ * Exported so the `/agents` menus can reject a typed reference at the prompt.
+ * Without that they would hand an invalid value to `saveSettings`, which drops
+ * unrecognized fields silently — a success toast for a setting that never
+ * persisted.
+ */
+export function isModelReference(value: unknown): value is string {
   if (typeof value !== "string") return false;
   const model = value.trim();
   if (model === "inherit") return true;
@@ -267,7 +304,7 @@ function sanitizeWorkflowProfile(raw: unknown): WorkflowTierProfile | undefined
   const keys = Object.keys(raw);
   if (keys.some((key) => key !== "model" && key !== "thinking")) return undefined;
   if (!Object.hasOwn(raw, "model") || !Object.hasOwn(raw, "thinking")) return undefined;
-  if (!validWorkflowModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
+  if (!isModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
   return { model: raw.model.trim(), thinking: raw.thinking };
 }
 
@@ -318,7 +355,7 @@ function sanitizeAgentTierProfile(raw: unknown): AgentTierProfile | undefined {
   const keys = Object.keys(raw);
   if (keys.some((key) => key !== "model" && key !== "thinking" && key !== "description")) return undefined;
   if (!Object.hasOwn(raw, "model") || !Object.hasOwn(raw, "thinking")) return undefined;
-  if (!validWorkflowModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
+  if (!isModelReference(raw.model) || !validThinkingLevel(raw.thinking)) return undefined;
   if (
     Object.hasOwn(raw, "description") &&
     (typeof raw.description !== "string" ||
@@ -397,6 +434,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.maxSubagentDepth = r.maxSubagentDepth as number;
   }
+  if (isModelReference(r.defaultModel)) {
+    out.defaultModel = r.defaultModel.trim();
+  }
   if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
     out.defaultJoinMode = r.defaultJoinMode as JoinMode;
   }
@@ -773,6 +813,9 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
   if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
   if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
+  // Applied whenever the key is present, `"inherit"` included: that spelling is
+  // how a project cancels a global default model, so it has to reach the setter.
+  if (typeof s.defaultModel === "string") appliers.setDefaultModel(s.defaultModel);
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
   if (typeof s.schedulingEnabled === "boolean") appliers.setSchedulingEnabled(s.schedulingEnabled);
   if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels);

package/src/types.ts

@@ -59,7 +59,14 @@ export interface AgentConfig {
    * tiers existed.
    */
   agentTier?: string;
+  /**
+   * Programmatic-only model override. Never populated from an agent file: which
+   * model a subagent runs is the tier catalogue's decision, and `model:` in
+   * frontmatter is read as documentation of an unfinished migration rather than
+   * a pin. Left on the type for callers that construct a config in process.
+   */
   model?: string;
+  /** Programmatic-only, for the same reason as `model` above. */
   thinking?: ThinkingLevel;
   maxTurns?: number;
   /** Persist this subagent as a normal pi session instead of keeping it in memory only. */