@signalridge/pi-subagents 1.2.0 → 1.4.0

package/src/agent-tiers.ts

@@ -0,0 +1,336 @@
+/**
+ * agent-tiers.ts — user-named model tiers for ordinary subagent spawns.
+ *
+ * A tier is one name for a (model, thinking) pair. The host agent picks a tier
+ * key and nothing else: the LLM-facing `Agent` tool exposes `tier` and does not
+ * expose `model` or `thinking`, so the choice of which model runs stays with
+ * whoever writes `subagents.json` rather than with the model deciding per call.
+ *
+ * Deliberately separate from `workflow-tiers.ts`. Workflow tiers are the fixed
+ * `small | medium | large` vocabulary of the `pi-workflows` protocol and are
+ * typed as that union; agent tiers are arbitrary user-chosen names. Sharing one
+ * field between them would force `WorkflowTier` open to `string` and take the
+ * protocol's exhaustiveness with it, so the two keep separate settings, separate
+ * snapshot types, and separate fields on `AgentInvocation`. The mechanics they
+ * both use — resolving a model reference, clamping thinking — are short enough
+ * to state twice; `workflow-tiers.ts` keeps its own copy so this change cannot
+ * alter the protocol-facing resolver's behavior.
+ *
+ * The two also disagree on precedence, which is why they are not one function:
+ * a workflow tier only fills what agent frontmatter left blank, while an agent
+ * tier overrides frontmatter's legacy `model:`/`thinking:`. That is the point of
+ * agent tiers — the tier is the policy, and a per-agent pin is the older, weaker
+ * statement of the same thing.
+ */
+
+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 { AgentConfig, ThinkingLevel } from "./types.js";
+
+/** `provider/id`, or undefined when no model was selected. */
+function effectiveModelId(model: Model<Api> | undefined): string | undefined {
+  return model ? `${model.provider}/${model.id}` : undefined;
+}
+
+/** Longest accepted tier key. Long enough for any real name, short enough to render. */
+export const MAX_AGENT_TIER_KEY_LENGTH = 64;
+
+let agentTiersSettings: AgentTiersSettings = {};
+
+export function getAgentTiersSettings(): AgentTiersSettings {
+  return structuredClone(agentTiersSettings);
+}
+
+export function setAgentTiersSettings(settings: AgentTiersSettings): void {
+  agentTiersSettings = structuredClone(settings);
+}
+
+/**
+ * A key is usable when it is a bounded, non-blank, whitespace-free string.
+ *
+ * Whitespace is excluded because the key appears in tool descriptions and error
+ * messages as a bare token; a key with a space in it reads as two keys.
+ */
+export function isValidAgentTierKey(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= MAX_AGENT_TIER_KEY_LENGTH &&
+    value.trim() === value &&
+    !/\s/u.test(value)
+  );
+}
+
+/** Where the tier that was used came from; recorded for audit. */
+export type AgentTierSource = "call" | "frontmatter" | "default";
+
+/** Durable, JSON-safe record of how one spawn's model and thinking were chosen. */
+export interface AgentTierResolutionSnapshot {
+  /** The tier key that was applied. */
+  tier: string;
+  source: AgentTierSource;
+  /** Effective provider/model id after resolution. */
+  model?: string;
+  /** Effective thinking level; omitted when the model supports none. */
+  thinking?: ThinkingLevel;
+  /** The profile's model reference, before resolution. */
+  configuredModel: string;
+  /** The profile's thinking value, before clamping. */
+  configuredThinking: TierThinking;
+  /** Level asked for after `inherit` resolved against the parent. */
+  requestedThinking?: ThinkingLevel;
+  /** True when pi-ai lowered the requested level for this model. */
+  clamped?: boolean;
+  diagnostic?: string;
+}
+
+export interface AgentTierResolution {
+  model?: Model<Api>;
+  thinkingLevel?: ThinkingLevel;
+  snapshot?: AgentTierResolutionSnapshot;
+}
+
+export interface ResolveAgentTierInput {
+  /** Tier key from the spawn call. Highest precedence. */
+  requestedTier?: string;
+  /** The agent's own config; supplies its default tier and legacy model/thinking. */
+  agentConfig?: AgentConfig;
+  /** Overrides the module-level settings; tests and callers with their own load. */
+  settings?: AgentTiersSettings;
+  parentModel?: Model<Api>;
+  parentThinking?: ThinkingLevel;
+  modelRegistry: ModelRegistry<Model<Api>>;
+}
+
+/** Thrown for every fail-closed tier condition so callers can report it verbatim. */
+export class AgentTierError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentTierError";
+  }
+}
+
+function knownTierKeys(settings: AgentTiersSettings): string[] {
+  return Object.keys(settings.profiles ?? {}).sort((a, b) => a.localeCompare(b));
+}
+
+function tierKeyList(settings: AgentTiersSettings): string {
+  const keys = knownTierKeys(settings);
+  return keys.length > 0 ? keys.join(", ") : "(none configured)";
+}
+
+/**
+ * Which tier applies, and where it came from.
+ *
+ * An explicitly requested tier that does not exist is an error rather than a
+ * fallback: the host asked for a specific policy, and quietly running a
+ * different model than the one it selected is worse than refusing.
+ */
+function selectTier(
+  input: ResolveAgentTierInput,
+  settings: AgentTiersSettings,
+): { tier: string; source: AgentTierSource } | undefined {
+  const requested = input.requestedTier;
+  if (requested !== undefined) {
+    if (!isValidAgentTierKey(requested)) {
+      throw new AgentTierError(
+        `Invalid agent tier key. Keys are non-empty, contain no whitespace, and are at most ` +
+          `${MAX_AGENT_TIER_KEY_LENGTH} characters. Available tiers: ${tierKeyList(settings)}`,
+      );
+    }
+    return { tier: requested, source: "call" };
+  }
+
+  const frontmatter = input.agentConfig?.agentTier;
+  if (frontmatter !== undefined) return { tier: frontmatter, source: "frontmatter" };
+
+  if (settings.blockedDefaultTier) {
+    throw new AgentTierError("agentTiers.defaultTier is blocked by malformed configuration");
+  }
+  if (settings.defaultTier !== undefined) return { tier: settings.defaultTier, source: "default" };
+  return undefined;
+}
+
+function describeSource(source: AgentTierSource, agentName: string | undefined): string {
+  switch (source) {
+    case "call":
+      return "requested by the caller";
+    case "frontmatter":
+      return `set by agent "${agentName ?? "unknown"}"`;
+    case "default":
+      return "the configured agentTiers.defaultTier";
+  }
+}
+
+/**
+ * Resolve a spawn's model and thinking from its tier.
+ *
+ * Returns `undefined` fields and no snapshot when no tier applies at all, which
+ * is how a workspace that has configured none keeps its previous behavior: the
+ * caller then falls back to the agent's legacy `model:`/`thinking:` frontmatter
+ * and finally to the parent session.
+ */
+export function resolveAgentTier(input: ResolveAgentTierInput): AgentTierResolution {
+  const settings = input.settings ?? agentTiersSettings;
+  const selected = selectTier(input, settings);
+  if (!selected) return {};
+
+  const { tier, source } = selected;
+  const origin = describeSource(source, input.agentConfig?.name);
+
+  if (settings.blockedProfiles?.includes(tier)) {
+    throw new AgentTierError(
+      `Agent tier "${tier}" (${origin}) is blocked by a malformed profile in subagents.json. ` +
+        `Fix or remove it; a tier is never silently replaced by another model.`,
+    );
+  }
+
+  const profile: AgentTierProfile | undefined = settings.profiles?.[tier];
+  if (!profile) {
+    throw new AgentTierError(
+      `Unknown agent tier "${tier}" (${origin}). Available tiers: ${tierKeyList(settings)}`,
+    );
+  }
+
+  // A tier owns its model outright, so an unresolvable reference fails the spawn
+  // instead of degrading into whatever the parent happens to be running — the
+  // caller asked for this policy by name.
+  let model = input.parentModel;
+  if (profile.model !== "inherit") {
+    const resolved = resolveModel(profile.model, input.modelRegistry);
+    if (typeof resolved === "string") {
+      throw new AgentTierError(`Agent tier "${tier}" (${origin}) has an unavailable model: ${resolved}`);
+    }
+    model = resolved;
+  }
+
+  const requestedThinking = profile.thinking === "inherit" ? input.parentThinking : profile.thinking;
+  let thinkingLevel = requestedThinking;
+  let clamped = false;
+  let diagnostic: string | undefined;
+  if (model && requestedThinking) {
+    const clampedLevel = clampThinkingLevel(model, requestedThinking);
+    if (clampedLevel !== requestedThinking) {
+      clamped = true;
+      diagnostic =
+        `Thinking level "${requestedThinking}" is not supported by ${effectiveModelId(model) ?? "the selected model"}; ` +
+        `using "${clampedLevel}" (supported: ${getSupportedThinkingLevels(model).join(", ")}).`;
+    }
+    // "off" is a ModelThinkingLevel sentinel, not a ThinkingLevel an AgentSession
+    // accepts. Omitting the option leaves the provider's own off behavior alone.
+    thinkingLevel = clampedLevel === "off" ? undefined : (clampedLevel as ThinkingLevel);
+  }
+
+  const snapshot: AgentTierResolutionSnapshot = {
+    tier,
+    source,
+    ...(effectiveModelId(model) ? { model: effectiveModelId(model) } : {}),
+    ...(thinkingLevel ? { thinking: thinkingLevel } : {}),
+    configuredModel: profile.model,
+    configuredThinking: profile.thinking,
+    ...(requestedThinking !== undefined ? { requestedThinking } : {}),
+    ...(clamped ? { clamped: true } : {}),
+    ...(diagnostic ? { diagnostic } : {}),
+  };
+
+  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.
+ *
+ * The host has to know the vocabulary before its first call, so this is injected
+ * into the tool description at registration rather than exposed through a lookup
+ * tool the model would have to remember to call. Only names, descriptions,
+ * models and thinking levels appear — nothing here reads credentials.
+ */
+export function buildAgentTierListText(settings: AgentTiersSettings = agentTiersSettings): string {
+  const keys = knownTierKeys(settings);
+  if (keys.length === 0) return "";
+
+  const entries = keys.map((key) => {
+    const profile = settings.profiles?.[key];
+    if (!profile) return `- ${key}`;
+    // A profile without its own description is still worth listing; the key is
+    // the description in that case, which is what a terse config intends.
+    const summary = profile.description ?? key;
+    return `- ${key}: ${summary}\n  model: ${profile.model}\n  thinking: ${profile.thinking}`;
+  });
+
+  const defaultLine =
+    settings.defaultTier !== undefined ? `\n\nDefault tier: ${settings.defaultTier}` : "";
+  return `Available agent tiers:\n\n${entries.join("\n\n")}${defaultLine}\n\nThe caller may pass only a tier key. Do not pass model or thinking directly.`;
+}
+
+/** One line per tier, for the compact tool description. */
+export function buildCompactAgentTierListText(settings: AgentTiersSettings = agentTiersSettings): string {
+  const keys = knownTierKeys(settings);
+  if (keys.length === 0) return "";
+
+  const entries = keys.map((key) => {
+    const profile = settings.profiles?.[key];
+    if (!profile) return `- ${key}`;
+    return `- ${key}: ${profile.description ?? key} (${profile.model}, thinking ${profile.thinking})`;
+  });
+  const defaultSuffix = settings.defaultTier !== undefined ? ` Default: ${settings.defaultTier}.` : "";
+  return `Agent tiers (pass \`tier\`, never model/thinking):\n${entries.join("\n")}${defaultSuffix}`;
+}
+
+/** The configured default tier key, or "" when none is set. */
+export function getDefaultAgentTierText(settings: AgentTiersSettings = agentTiersSettings): string {
+  return settings.defaultTier ?? "";
+}
+
+/** Description for the `tier` parameter, naming the keys this workspace defines. */
+export function buildAgentTierParameterDescription(settings: AgentTiersSettings = agentTiersSettings): string {
+  const keys = knownTierKeys(settings);
+  const available = keys.length > 0 ? keys.join(", ") : "none configured";
+  const fallback =
+    settings.defaultTier !== undefined
+      ? ` Omit to use the agent's own tier, or "${settings.defaultTier}".`
+      : " Omit to use the agent's own tier.";
+  return (
+    `Model tier for this spawn, chosen by name. Available: ${available}.${fallback}` +
+    " A tier overrides the agent's default. Unknown tiers are rejected rather than substituted."
+  );
+}

package/src/custom-agents.ts

@@ -5,9 +5,10 @@
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 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";
 
 /**
@@ -163,6 +164,7 @@ function loadFromDir(
     const { frontmatter: fm, body } = parsed;
 
     const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
+    warnLegacyModelFields(fm, path, warn);
 
     agents.set(name, {
       name,
@@ -174,8 +176,7 @@ function loadFromDir(
       extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
       excludeExtensions: csvListOptional(fm.exclude_extensions),
       skills: inheritField(fm.skills ?? fm.inherit_skills),
-      model: str(fm.model),
-      thinking: str(fm.thinking) as ThinkingLevel | undefined,
+      agentTier: parseTier(fm.tier, path, warn),
       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,
@@ -195,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,
@@ -266,6 +286,28 @@ function label(val: unknown): string | undefined {
   return raw === undefined ? undefined : sanitizeDisplayText(raw);
 }
 
+/**
+ * Parse the agent's default model tier.
+ *
+ * Only the shape is checked here; whether the key names a configured profile is
+ * decided at spawn time, because the catalogue lives in `subagents.json` and may
+ * legitimately change after this file was read. A malformed key is dropped with
+ * a warning rather than failing the load: the rest of the agent is still usable,
+ * and a spawn without a tier falls back to the configured default.
+ */
+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`,
+    `tier:${warningIdentity(path)}`,
+  );
+  return undefined;
+}
+
 /** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
 function nonNegativeInt(val: unknown): number | undefined {
   return typeof val === "number" && val >= 0 ? val : undefined;

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

@@ -27,6 +27,15 @@ import {
   type ManagedSpawnTombstone,
 } from "./agent-manager.js";
 import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import {
+  buildAgentTierListText,
+  buildAgentTierParameterDescription,
+  buildCompactAgentTierListText,
+  findUnknownAgentTierReferences,
+  getAgentTiersSettings,
+  getDefaultAgentTierText,
+  setAgentTiersSettings,
+} 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";
 import {
@@ -1000,7 +1009,7 @@ function activateRootRuntime(
       ...(effectiveTier === undefined ? {} : { tier: effectiveTier }),
     };
     const customConfig = getAgentConfig(dispatch.type);
-    const resolvedConfig = resolveAgentInvocationConfig(customConfig, { tier: effectiveTier });
+    const resolvedConfig = resolveAgentInvocationConfig(customConfig, { workflowTier: effectiveTier });
     // A managed request cannot carry a model override, but an agent's frontmatter
     // model still needs the same scope validation as a normal Agent call when no
     // workflow tier is active. Tiered runs validate their effective policy inside
@@ -1183,7 +1192,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");
@@ -1227,9 +1236,25 @@ function activateRootRuntime(
     setMaxSubagentDepth,
     setFallbackSubagent,
     setWorkflow: setWorkflowSettings,
+    setAgentTiers: setAgentTiersSettings,
   });
   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
@@ -1257,8 +1282,16 @@ function activateRootRuntime(
   // Compact Agent tool description (#91, `toolDescriptionMode: "compact"`) —
   // the same load-bearing facts as the full version at ~75% fewer tokens, for
   // small/local models. Per-option details live in the param descriptions.
+  // The catalogue is injected into the description rather than left to a lookup
+  // tool: the host has to pick a tier on its first call, and a tool it must
+  // remember to call first is a tool it will skip.
+  const tierListText = buildAgentTierListText();
+  const compactTierListText = buildCompactAgentTierListText();
+  const tierSection = tierListText ? `\n\n${tierListText}` : "";
+  const compactTierSection = compactTierListText ? `\n\n${compactTierListText}` : "";
+
   const compactAgentToolDescription = `Launch an autonomous agent for complex, multi-step tasks. Agent types:
-${buildCompactTypeListText()}
+${buildCompactTypeListText()}${compactTierSection}
 
 Custom agents: .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global).
 
@@ -1274,7 +1307,7 @@ Notes:
 Available agent types and the tools they have access to:
 ${buildTypeListText()}
 
-Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.
+Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.${tierSection}
 
 When using the Agent tool, specify a subagent_type parameter to select which agent type to use.
 
@@ -1294,8 +1327,7 @@ If the target is already known, use a direct tool — \`read\` for a known path,
 - Use steer_subagent to send mid-run messages to a running background agent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
 - If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
-- Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
-- Use thinking to control extended thinking level.
+- Use tier to pick the model profile for this spawn, by name. A tier overrides the agent's own default tier. Model and thinking are not callable parameters — they are what a tier resolves to.
 - Use inherit_context if the agent needs the parent conversation history.
 - Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.${scheduleGuideline}
 
@@ -1320,6 +1352,12 @@ Terse command-style prompts produce shallow, generic work.
     const vars: Record<string, () => string> = {
       typeList: buildTypeListText,
       compactTypeList: buildCompactTypeListText,
+      // Both carry their own leading blank line, so a template that drops the
+      // placeholder inline renders byte-identically to the built-in description
+      // whether or not any tier is configured.
+      tierList: () => tierSection,
+      compactTierList: () => compactTierSection,
+      defaultTier: getDefaultAgentTierText,
       agentDir: getAgentDir,
       scheduleGuideline: () => scheduleGuideline,
     };
@@ -1380,15 +1418,9 @@ Terse command-style prompts produce shallow, generic work.
       subagent_type: Type.String({
         description: `The type of specialized agent to use. Available types: ${getAvailableTypes().join(", ")}. Custom agents from .pi/agents/*.md (project) or ${getAgentDir()}/agents/*.md (global) are also available.`,
       }),
-      model: Type.Optional(
+      tier: Type.Optional(
         Type.String({
-          description:
-            'Optional model override. Accepts "provider/modelId" or fuzzy name (e.g. "haiku", "sonnet"). Omit to use the agent type\'s default.',
-        }),
-      ),
-      thinking: Type.Optional(
-        Type.String({
-          description: `Thinking level: ${THINKING_LEVELS.join(", ")}. Overrides agent default.`,
+          description: buildAgentTierParameterDescription(),
         }),
       ),
       max_turns: Type.Optional(
@@ -1746,6 +1778,7 @@ Terse command-style prompts produce shallow, generic work.
           isolated,
           inheritContext,
           thinkingLevel: thinking,
+          agentTier: resolvedConfig.requestedAgentTier,
           isBackground: true,
           isolation,
           invocation: agentInvocation,
@@ -1875,6 +1908,7 @@ Terse command-style prompts produce shallow, generic work.
           isolated,
           inheritContext,
           thinkingLevel: thinking,
+          agentTier: resolvedConfig.requestedAgentTier,
           isolation,
           invocation: agentInvocation,
           signal,
@@ -2763,6 +2797,15 @@ Do not wrap the response in a markdown code fence. Return only the file contents
       (getWorkflowSettings().blockedTiers?.length ?? 0) > 0
         ? { workflow: getWorkflowSettings() }
         : {}),
+      // Same shape as the workflow block above: written back only when the user
+      // actually configured tiers, so the snapshot never materializes an empty
+      // catalogue into the project settings file.
+      ...(Object.keys(getAgentTiersSettings().profiles ?? {}).length > 0 ||
+      getAgentTiersSettings().defaultTier !== undefined ||
+      getAgentTiersSettings().blockedDefaultTier === true ||
+      (getAgentTiersSettings().blockedProfiles?.length ?? 0) > 0
+        ? { agentTiers: getAgentTiersSettings() }
+        : {}),
       // Deliberately NOT `?? "general-purpose"`: every settings change writes the
       // whole snapshot, and materializing the implicit default would turn it into
       // explicit configuration — which then fails loudly if general-purpose later

package/src/invocation-config.ts

@@ -1,7 +1,23 @@
 import type { WorkflowTier } from "@signalridge/pi-subagents-protocol";
-import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
+import type {
+  AgentConfig,
+  IsolationMode,
+  JoinMode,
+  ThinkingLevel,
+} from "./types.js";
 
 interface AgentInvocationParams {
+  /**
+   * User-named model tier requested at the call site. This is the only model
+   * control the LLM-facing `Agent` tool exposes; `model` and `thinking` below
+   * are reachable only from programmatic callers and the legacy RPC.
+   */
+  tier?: string;
+  /**
+   * Workflow protocol tier (`small | medium | large`), set only by the managed
+   * spawn path. Kept apart from `tier` so the protocol's union stays closed.
+   */
+  workflowTier?: WorkflowTier;
   model?: string;
   thinking?: string;
   max_turns?: number;
@@ -9,7 +25,6 @@ interface AgentInvocationParams {
   inherit_context?: boolean;
   isolated?: boolean;
   isolation?: IsolationMode;
-  tier?: WorkflowTier;
 }
 
 export function resolveAgentInvocationConfig(
@@ -18,7 +33,9 @@ export function resolveAgentInvocationConfig(
 ): {
   modelInput?: string;
   modelFromParams: boolean;
-  tier?: WorkflowTier;
+  /** Passed to `resolveAgentTier` as the requested tier; precedence lives there. */
+  requestedAgentTier?: string;
+  workflowTier?: WorkflowTier;
   thinking?: ThinkingLevel;
   maxTurns?: number;
   inheritContext: boolean;
@@ -28,17 +45,25 @@ export function resolveAgentInvocationConfig(
 } {
   return {
     modelInput: agentConfig?.model ?? params.model,
-    tier: params.tier,
+    requestedAgentTier: params.tier,
+    workflowTier: params.workflowTier,
     modelFromParams: agentConfig?.model == null && params.model != null,
-    thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+    thinking: (agentConfig?.thinking ?? params.thinking) as
+      | ThinkingLevel
+      | undefined,
     maxTurns: agentConfig?.maxTurns ?? params.max_turns,
-    inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
-    runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
+    inheritContext:
+      agentConfig?.inheritContext ?? params.inherit_context ?? false,
+    runInBackground:
+      agentConfig?.runInBackground ?? params.run_in_background ?? false,
     isolated: agentConfig?.isolated ?? params.isolated ?? false,
     isolation: agentConfig?.isolation ?? params.isolation,
   };
 }
 
-export function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined {
+export function resolveJoinMode(
+  defaultJoinMode: JoinMode,
+  runInBackground: boolean,
+): JoinMode | undefined {
   return runInBackground ? defaultJoinMode : undefined;
 }