@signalridge/pi-subagents 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 1.3.0
+### Minor Changes
+
+- 1860def: Name your model tiers, and stop the orchestrator choosing models by hand.
+  
+  A tier is one name for a (model, thinking) pair, defined in `subagents.json`:
+  
+  ```json
+  {
+    "agentTiers": {
+      "defaultTier": "medium",
+      "profiles": {
+        "small":    { "description": "Fast, cheap exploration", "model": "deepseek/deepseek-v4-flash", "thinking": "max" },
+        "research": { "description": "Long-context research",   "model": "kimi/k3",                    "thinking": "max" }
+      }
+    }
+  }
+  ```
+  
+  Keys are arbitrary — `small`/`medium`/`large` are an example, not a vocabulary.
+  A profile requires both `model` and `thinking` (either may be `"inherit"`);
+  `description` is optional and is what the host reads when choosing.
+  
+  Resolution order: the `tier` on the call, then `tier:` in the agent's
+  frontmatter, then `agentTiers.defaultTier`, then the agent's legacy
+  `model:`/`thinking:`, then the parent session. A tier that applies decides both
+  fields outright, and an agent carrying both a tier and legacy pins logs a warning
+  naming the file. Unknown keys, malformed profiles and unavailable models refuse
+  the spawn before it starts, naming the tier and where it came from — none of them
+  quietly substitutes another model.
+  
+  The catalogue is rendered into the `Agent` tool description at registration, so
+  the host knows the vocabulary before its first call rather than having to
+  remember a lookup tool. Custom descriptions gain `{{tierList}}`,
+  `{{compactTierList}}` and `{{defaultTier}}`.
+  
+  Resolution happens once, in `agent-runner.ts`, so the top-level `Agent` tool,
+  nested delegation, the scheduler and cross-extension RPC share one precedence and
+  one set of refusals.
+  
+  `pi-workflows` is untouched: its tiers stay the fixed `small | medium | large` of
+  the cross-package protocol, which is what keeps a workflow definition validatable
+  at parse time and portable between machines. The two systems share no fields.
+  
+  The agent conversation overlay now marks its own edges with a rule at the top
+  and the bottom. It floats over the transcript and previously drew no border at
+  all — two variables named `hrTop` and `hrMid` were a bold title row and a blank
+  line — so there was no telling where the agent's conversation ended and the
+  parent's resumed. Two rules, none in between: an inner rule competes with the
+  pair that marks the boundary, and a four-sided box would cost two columns on
+  every row for the same job.
+  
+  The LLM-facing `Agent` and nested-`Agent` schemas no longer accept `model` or
+  `thinking` — a caller picks a tier instead. This is a minor, not a major: a tool
+  schema is read by a model at runtime rather than compiled against, so no import,
+  settings key or RPC payload changes shape. Programmatic callers and the legacy
+  RPC still accept both fields, and agents with no tier configured behave exactly
+  as before. The migration is: define the profiles once, then replace each agent's
+  `model:`/`thinking:` with `tier: <name>`.
+
 ## 1.0.0
 ### Major Changes
 

package/README.md

@@ -230,8 +230,9 @@ All fields are optional — sensible defaults for everything.
 | `memory` | — | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents |
 | `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
 | `isolation` | — | Set to `worktree` to run in an isolated git worktree |
-| `model` | inherit parent | 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 |
-| `thinking` | inherit | off, minimal, low, medium, high, xhigh, max — actual availability depends on your pi version and model; pi clamps unsupported levels down |
+| `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 |
 | `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:` |
@@ -317,8 +318,7 @@ Launch a sub-agent.
 | `prompt` | string | yes | The task for the agent |
 | `description` | string | yes | Short 3-5 word summary (shown in UI) |
 | `subagent_type` | string | yes | Agent type (built-in or custom) |
-| `model` | string | no | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp interchangeable) with provider fallback |
-| `thinking` | string | no | Thinking level: off, minimal, low, medium, high, xhigh, max (availability depends on pi version and model) |
+| `tier` | string | no | Model tier for this spawn, by name. Overrides the agent's own default tier. Unknown tiers are rejected, not substituted — see [Model tiers](#model-tiers) |
 | `max_turns` | number | no | Max agentic turns. Omit for unlimited (default) |
 | `run_in_background` | boolean | no | Run without blocking |
 | `resume` | string | no | Agent ID to resume a previous session |
@@ -409,6 +409,104 @@ When background agents complete, they notify the main agent. The **join mode** c
 **Configuration:**
 - Configure join mode in `/agents` → Settings → Join mode
 
+## Model tiers
+
+A **tier** is one name for a (model, thinking) pair. The host agent picks a tier
+by name and nothing else: the `Agent` tool exposes `tier` and does **not** expose
+`model` or `thinking`, so which model runs is decided by whoever writes
+`subagents.json`, not by the orchestrator improvising per call.
+
+Names are yours. `small`/`medium`/`large` below are only an example — `research`,
+`cheap`, `nightly` are equally valid keys.
+
+```json
+{
+  "agentTiers": {
+    "defaultTier": "medium",
+    "profiles": {
+      "small":    { "description": "Fast, cheap exploration",        "model": "deepseek/deepseek-v4-flash", "thinking": "max" },
+      "medium":   { "description": "Ordinary planning and review",   "model": "openai-codex/gpt-5.6-luna",  "thinking": "max" },
+      "large":    { "description": "Architecture and risky review",  "model": "openai-codex/gpt-5.6-sol",   "thinking": "xhigh" },
+      "research": { "description": "Long-context research",          "model": "kimi/k3",                    "thinking": "max" }
+    }
+  }
+}
+```
+
+A profile is all-or-nothing: both `model` and `thinking` are required, and either
+may be the literal `"inherit"` to keep the parent's. `description` is optional and
+defaults to the key; it is what the host reads when choosing between tiers.
+
+### How the host discovers tiers
+
+The catalogue is rendered into the `Agent` tool description at registration, so
+the host knows the vocabulary before its first call — there is no lookup tool to
+remember. It sees:
+
+```
+Available agent tiers:
+
+- small: Fast, cheap exploration
+  model: deepseek/deepseek-v4-flash
+  thinking: max
+...
+Default tier: medium
+
+The caller may pass only a tier key. Do not pass model or thinking directly.
+```
+
+A [custom tool description](#persistent-settings) can place it with
+`{{tierList}}`, `{{compactTierList}}` or `{{defaultTier}}`. Tier changes apply on
+the next pi session, since the description is built once at registration.
+
+### Precedence
+
+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
+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.
+
+### Refusals
+
+These fail **before** the spawn, with the tier key and where it came from named.
+None of them silently substitutes another model:
+
+- a tier key nobody defined (from the call, the agent file, or `defaultTier`)
+- a profile dropped as malformed during settings load
+- a profile whose model is not available on this machine
+- a syntactically invalid key (blank, whitespace, over 64 characters)
+
+### Merging global and project settings
+
+`~/.pi/agent/subagents.json` supplies the catalogue; `<cwd>/.pi/subagents.json`
+edits it. A project profile replaces its global namesake **whole** — never field
+by field, which would let a project change a model while inheriting a thinking
+level nobody chose for that pair. A project profile that fails validation blocks
+its global namesake rather than reviving it, and `defaultTier` is a simple
+project-over-global override.
+
+### Not the same as `workflow.tiers`
+
+`pi-workflows` has its own tiers, and they stay fixed at `small | medium | large`.
+That vocabulary is part of the cross-package protocol: it lets a workflow
+definition be validated at parse time and stay portable between machines, neither
+of which survives arbitrary names. The two systems share no fields — a spawn
+records `agentTier`/`agentTierSnapshot` or `tier`/`tierSnapshot`, never one
+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.
+
 ## Model Scope
 
 **Opt-in:** off by default. Enable via `/agents → Settings → Scope models`.

package/examples/agent-tool-description.md

@@ -3,7 +3,7 @@ Launch a new agent to handle complex, multi-step tasks autonomously. Each agent
 Available agent types and the tools they have access to:
 {{typeList}}
 
-Custom agents can be defined in .pi/agents/<name>.md (project) or {{agentDir}}/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 {{agentDir}}/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.{{tierList}}
 
 When using the Agent tool, specify a subagent_type parameter to select which agent type to use.
 
@@ -23,8 +23,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}}
 

package/package.json

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

package/src/agent-manager.ts

@@ -15,6 +15,7 @@ import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-wor
 import type { ManagedSpawnRequest as ProtocolManagedSpawnRequest, WorkflowTier } from "@signalridge/pi-subagents-protocol";
 import { isWorkflowTier, parseManagedSpawnRequest } from "@signalridge/pi-subagents-protocol";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { AgentTierResolutionSnapshot } from "./agent-tiers.js";
 import {
   INTERNAL_AGENT_CONFIG_OVERRIDE,
   type InternalAgentConfigOverride,
@@ -523,6 +524,8 @@ export interface SpawnOptions {
   thinkingLevel?: ThinkingLevel;
   /** Semantic workflow tier resolved by pi-subagents at session start. */
   tier?: WorkflowTier;
+  /** User-named model tier; resolved by pi-subagents at session start. */
+  agentTier?: string;
   isBackground?: boolean;
   /**
    * Skip the maxConcurrent queue check for this spawn — start immediately even
@@ -553,6 +556,8 @@ export interface SpawnOptions {
   onSessionCreated?: (session: AgentSession) => void;
   /** Called after pi-subagents resolves a semantic workflow tier. */
   onTierResolved?: (snapshot: WorkflowTierResolutionSnapshot) => void;
+  /** Called after pi-subagents resolves a user-named agent tier. */
+  onAgentTierResolved?: (snapshot: AgentTierResolutionSnapshot) => void;
   /** Called synchronously after a new record is allocated, before session creation. */
   onSpawned?: (id: string) => void;
   /** Called at the end of each agentic turn with the cumulative count. */
@@ -1270,6 +1275,7 @@ export class AgentManager {
       ...(internalOverride ? { [INTERNAL_AGENT_CONFIG_OVERRIDE]: internalOverride } : {}),
       thinkingLevel: options.thinkingLevel,
       tier: options.tier,
+      agentTier: options.agentTier,
       // Worktree wins for the working dir (the agent must run in the copy —
       // which, with a custom cwd, was created from that target). Config stays
       // with the parent project when a caller-supplied cwd is in play; it must
@@ -1323,6 +1329,21 @@ export class AgentManager {
           options.onTierResolved?.(snapshot);
         }
       },
+      // Recorded on the same record as the workflow snapshot but under its own
+      // field, so a run can carry both without either overwriting the other's
+      // account of how its model was chosen.
+      onAgentTierResolved: (snapshot) => {
+        if (!record.detached) {
+          record.invocation = {
+            ...(record.invocation ?? {}),
+            agentTier: snapshot.tier,
+            thinking: snapshot.thinking,
+            agentTierSnapshot: { ...snapshot },
+          };
+          this.syncManagedRecord(record, true);
+          options.onAgentTierResolved?.(snapshot);
+        }
+      },
       onSessionCreated: (session) => {
         if (record.detached) {
           this.trackRecordSessionTeardown(id, session);

package/src/agent-runner.ts

@@ -19,6 +19,7 @@ import {
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { WorkflowTier } from "@signalridge/pi-subagents-protocol";
+import { type AgentTierResolutionSnapshot, resolveAgentTier } from "./agent-tiers.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { runInChildSessionContext } from "./child-context.js";
 import { buildParentContext, extractText } from "./context.js";
@@ -380,6 +381,12 @@ export interface RunOptions {
   thinkingLevel?: ThinkingLevel;
   /** Semantic workflow tier; resolved here rather than by workflow callers. */
   tier?: WorkflowTier;
+  /**
+   * User-named model tier for an ordinary spawn. Resolved here so the top-level
+   * Agent tool, nested delegation, the scheduler and cross-extension RPC all get
+   * the same precedence and the same fail-closed errors from one place.
+   */
+  agentTier?: string;
   /** Parent thinking level used only when a tier profile omits thinking. */
   parentThinking?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
@@ -407,6 +414,8 @@ export interface RunOptions {
   onSessionCreated?: (session: AgentSession) => void;
   /** Called after pi-subagents resolves a semantic workflow tier. */
   onTierResolved?: (snapshot: WorkflowTierResolutionSnapshot) => void;
+  /** Called after pi-subagents resolves a user-named agent tier. */
+  onAgentTierResolved?: (snapshot: AgentTierResolutionSnapshot) => void;
   /** Called at the end of each agentic turn with the cumulative count. */
   onTurnEnd?: (turnCount: number) => void;
   /**
@@ -622,6 +631,29 @@ export async function runAgent(
     : undefined;
   if (tierResolution?.snapshot) options.onTierResolved?.(tierResolution.snapshot);
 
+  // Agent tiers resolve in the same place and before the same await, so every
+  // spawn path shares one precedence and one set of fail-closed errors. A tier
+  // that applies decides model and thinking outright: it is current policy,
+  // while an agent's legacy `model:`/`thinking:` frontmatter is the older, weaker
+  // statement of the same thing. Throwing here refuses the spawn rather than
+  // quietly running a model the caller did not choose.
+  const agentTierResolution = resolveAgentTier({
+    requestedTier: options.agentTier,
+    agentConfig,
+    parentModel: ctx.model,
+    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.`,
+      );
+    }
+  }
+
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
   // Filesystem work happens in effectiveCwd; config discovery in configCwd.
@@ -842,12 +874,33 @@ export async function runAgent(
     }
   }
 
-  const model = options.model ?? tierResolution?.model ?? resolveDefaultModel(
+  // `options.model` stays highest: it is a resolved Model handed over by a
+  // programmatic caller, which is a more explicit act than naming a tier.
+  const model = options.model ?? agentTierResolution.model ?? tierResolution?.model ?? resolveDefaultModel(
     ctx.model, ctx.modelRegistry, agentConfig?.model,
   );
-  const thinkingLevel = options.tier !== undefined
-    ? tierResolution?.thinkingLevel
-    : options.thinkingLevel ?? agentConfig?.thinking;
+  const thinkingLevel = agentTierResolution.snapshot
+    ? agentTierResolution.thinkingLevel
+    : options.tier !== undefined
+      ? tierResolution?.thinkingLevel
+      : options.thinkingLevel ?? agentConfig?.thinking;
+
+  if (agentTierResolution.snapshot) {
+    const { configuredModel, source } = agentTierResolution.snapshot;
+    const scopeVerdict = checkModelScope({
+      model,
+      cwd: ctx.cwd,
+      modelRegistry: ctx.modelRegistry,
+      // A tier the caller named is a runtime choice by the model, which is what
+      // scopeModels exists to police; a tier that came from the agent file or
+      // the configured default is the user's own config and only warns.
+      callerSupplied: source === "call",
+      agentLabel: agentConfig?.displayName ?? type,
+      modelInput: configuredModel === "inherit" ? undefined : configuredModel,
+    });
+    if (scopeVerdict.kind === "error") throw new Error(scopeVerdict.message);
+    if (scopeVerdict.kind === "warn" && ctx.hasUI) ctx.ui.notify(scopeVerdict.message, "warning");
+  }
 
   if (options.tier) {
     const configuredModel = tierResolution?.snapshot?.configuredModel;