@signalridge/pi-subagents 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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

@@ -231,8 +231,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:` |
@@ -464,15 +464,21 @@ 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
-5. the parent session's model and thinking
+4. 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.
+There is no fifth step: an agent cannot pin its own model. `model:`/`thinking:`
+in frontmatter are read only to warn that they are stale, and the built-in
+agents pin nothing either. With no tier anywhere — none passed, none in the
+agent, no `defaultTier` — a subagent runs on the parent session's model, which
+is what a workspace that has configured no tiers gets.
 
 ### 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 +507,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.3.0",
+  "version": "1.4.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

@@ -644,15 +644,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

@@ -237,6 +237,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.
  *

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

@@ -31,6 +31,7 @@ import {
   buildAgentTierListText,
   buildAgentTierParameterDescription,
   buildCompactAgentTierListText,
+  findUnknownAgentTierReferences,
   getAgentTiersSettings,
   getDefaultAgentTierText,
   setAgentTiersSettings,
@@ -1191,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");
@@ -1239,6 +1240,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

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. */