@signalridge/pi-subagents 1.2.0 → 1.3.0

package/src/agent-tiers.ts

@@ -0,0 +1,297 @@
+/**
+ * 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 };
+}
+
+/**
+ * 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,6 +5,7 @@
 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";
@@ -174,6 +175,7 @@ function loadFromDir(
       extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
       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),
@@ -266,6 +268,25 @@ 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;
+  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/index.ts

@@ -27,6 +27,14 @@ 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,
+  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 +1008,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
@@ -1227,6 +1235,7 @@ function activateRootRuntime(
     setMaxSubagentDepth,
     setFallbackSubagent,
     setWorkflow: setWorkflowSettings,
+    setAgentTiers: setAgentTiersSettings,
   });
   pi.events.emit("subagents:settings_loaded", { settings: startupSettings });
 
@@ -1257,8 +1266,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 +1291,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 +1311,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 +1336,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 +1402,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(
-        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(
+      tier: Type.Optional(
         Type.String({
-          description: `Thinking level: ${THINKING_LEVELS.join(", ")}. Overrides agent default.`,
+          description: buildAgentTierParameterDescription(),
         }),
       ),
       max_turns: Type.Optional(
@@ -1746,6 +1762,7 @@ Terse command-style prompts produce shallow, generic work.
           isolated,
           inheritContext,
           thinkingLevel: thinking,
+          agentTier: resolvedConfig.requestedAgentTier,
           isBackground: true,
           isolation,
           invocation: agentInvocation,
@@ -1875,6 +1892,7 @@ Terse command-style prompts produce shallow, generic work.
           isolated,
           inheritContext,
           thinkingLevel: thinking,
+          agentTier: resolvedConfig.requestedAgentTier,
           isolation,
           invocation: agentInvocation,
           signal,
@@ -2763,6 +2781,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;
 }

package/src/nested-tools.ts

@@ -8,6 +8,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { abortable } from "./abortable.js";
+import { buildAgentTierParameterDescription } from "./agent-tiers.js";
 import {
   buildAgentRegistry,
   getAgentConfigIn,
@@ -50,6 +51,8 @@ const NESTED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"] as
 
 interface NestedSpawnOptions {
   description: string;
+  /** User-named model tier; resolved by the runner like every other spawn path. */
+  agentTier?: string;
   model?: Model<any>;
   maxTurns?: number;
   isolated?: boolean;
@@ -168,8 +171,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       prompt: Type.String({ description: "Self-contained task for the nested agent." }),
       description: Type.String({ description: "Short 3-5 word task description." }),
       subagent_type: Type.String({ description: `Allowed nested agent type. Available: ${availableIn(loadRegistry()).join(", ") || "none"}.` }),
-      model: Type.Optional(Type.String({ description: "Optional provider/model override." })),
-      thinking: Type.Optional(Type.String({ description: "Optional thinking level." })),
+      tier: Type.Optional(Type.String({ description: buildAgentTierParameterDescription() })),
       max_turns: Type.Optional(Type.Number({ minimum: 1 })),
       run_in_background: Type.Optional(Type.Boolean()),
       resume: Type.Optional(Type.String({ description: "Resume a nested agent owned by this parent." })),
@@ -252,6 +254,7 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
       const childDepth = context.depth + 1;
       const options: NestedSpawnOptions = {
         description: params.description,
+        agentTier: invocation.requestedAgentTier,
         model,
         maxTurns: invocation.maxTurns,
         isolated: invocation.isolated,
@@ -259,6 +262,9 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         thinkingLevel: invocation.thinking,
         isolation: invocation.isolation,
         invocation: {
+          ...(invocation.requestedAgentTier === undefined
+            ? {}
+            : { agentTier: invocation.requestedAgentTier }),
           thinking: invocation.thinking,
           maxTurns: invocation.maxTurns,
           isolated: invocation.isolated,

package/src/schedule.ts

@@ -256,6 +256,9 @@ export class SubagentScheduler {
         maxTurns: job.max_turns,
         isolated: job.isolated,
         thinkingLevel: job.thinking,
+        // Resolved at fire time against the catalogue as it is then, not as it
+        // was when the job was created: a schedule outlives config edits.
+        agentTier: job.tier,
         isolation: job.isolation,
       });
     } catch (err) {