@signalridge/pi-subagents 1.5.0 → 1.7.0

package/src/agent-runner.ts

@@ -21,10 +21,12 @@ import {
 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 { createAskGate } from "./ask-tools.js";
 import { runInChildSessionContext } from "./child-context.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
+import { formatGateVerdict, type GateExec, runGate, workspaceFingerprint } from "./gate.js";
 import {
   INTERNAL_AGENT_CONFIG_OVERRIDE,
   type InternalAgentConfigOverride,
@@ -36,6 +38,7 @@ import { createNestedSubagentTools, getMaxSubagentDepth, type NestedAgentManager
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { shutdownAndDisposeSession } from "./session-lifecycle.js";
 import { preloadSkills } from "./skill-loader.js";
+import { createSupervisorTool } from "./supervisor.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 import type { WorkflowTierResolutionSnapshot } from "./workflow-tiers.js";
 import { resolveWorkflowTier } from "./workflow-tiers.js";
@@ -246,9 +249,11 @@ export function installExtensionToolScope(
     narrowing: Map<string, Set<string>>;
     /** Opt-in nested-delegation tool names to keep active despite the EXCLUDED strip. */
     nestedToolNames: Set<string>;
+    /** Per-call approval gate from `ask_tools:`, when the agent declares any. */
+    askGate?: (toolName: string, input: unknown) => Promise<{ block: true; reason: string } | undefined>;
   },
 ): void {
-  const { loader, toolNames, disallowedSet, extNames, narrowing, nestedToolNames } = ctx;
+  const { loader, toolNames, disallowedSet, extNames, narrowing, nestedToolNames, askGate } = ctx;
 
   // The names allowed right now. Mirrors the `ext:` opt-in flip: when any `ext:`
   // selector is present, extension tools become an explicit allowlist — a loaded
@@ -300,16 +305,53 @@ export function installExtensionToolScope(
 
   const priorBeforeToolCall = session.agent.beforeToolCall;
   session.agent.beforeToolCall = async (context, signal) => {
-    if (!inScope().has(context.toolCall.name)) {
-      return {
-        block: true,
-        reason: `Tool "${context.toolCall.name}" is not available to this subagent.`,
-      };
+    const run = async () => {
+      if (!inScope().has(context.toolCall.name)) {
+        return {
+          block: true,
+          reason: `Tool "${context.toolCall.name}" is not available to this subagent.`,
+        } as const;
+      }
+      // Scope first, then approval: a tool this agent may not use at all is
+      // refused without troubling the user about it.
+      const gated = await askGate?.(context.toolCall.name, (context.toolCall as { input?: unknown }).input);
+      if (gated) return gated;
+      return priorBeforeToolCall?.(context, signal);
+    };
+    // Default per-tool timeout prevents a hung beforeToolCall (slow extension,
+    // stuck LLM arbitrator) from stalling the subagent forever. Approval
+    // dialogs are wrapped too — a tool that cannot be approved in time is
+    // blocked fail-closed rather than left hanging.
+    if (defaultToolTimeoutMs > 0) {
+      try {
+        return await withTimeout(run(), defaultToolTimeoutMs, `beforeToolCall for "${context.toolCall.name}"`);
+      } catch (err) {
+        return { block: true, reason: (err as Error).message };
+      }
     }
-    return priorBeforeToolCall?.(context, signal);
+    return run();
   };
 }
 
+/**
+ * Run an agent's `gate:` command and format its verdict for the result text.
+ *
+ * Failures here are contained: a gate that cannot be fingerprinted simply runs
+ * uncached, and one that cannot run at all reports as failed rather than taking
+ * the agent's whole result down with it.
+ */
+async function runConfiguredGate(command: string, cwd: string, pi: ExtensionAPI): Promise<string> {
+  const exec: GateExec = (file, args, execOptions) =>
+    pi.exec(file, args, execOptions as Parameters<ExtensionAPI["exec"]>[2]);
+  try {
+    const fingerprint = await workspaceFingerprint(cwd, exec);
+    const verdict = await runGate({ command, cwd, exec, ...(fingerprint ? { fingerprint } : {}) });
+    return formatGateVerdict(command, verdict);
+  } catch (error: unknown) {
+    return `\n\n---\nAcceptance gate \`${command}\`: could not run (${error instanceof Error ? error.message : String(error)})`;
+  }
+}
+
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined;
 
@@ -325,6 +367,48 @@ export function getDefaultMaxTurns(): number | undefined { return defaultMaxTurn
 export function setDefaultMaxTurns(n: number | undefined): void { defaultMaxTurns = normalizeMaxTurns(n); }
 
 /** Additional turns allowed after the soft limit steer message. */
+/**
+ * Fraction of a resource budget at which the wrap-up steer is sent.
+ *
+ * Not 1.0: an agent told to produce its final answer needs allowance left to
+ * produce it, so the steer has to arrive while there is still budget to spend
+ * on the response.
+ */
+const SOFT_BUDGET_FRACTION = 0.8;
+
+/** Project defaults for the per-agent resource budgets. `0` = unlimited. */
+let defaultMaxTokens = 0;
+let defaultMaxToolCalls = 0;
+
+/** Token budget for one agent run, from settings. `0` disables the cap. */
+export function getDefaultMaxTokens(): number { return defaultMaxTokens; }
+export function setDefaultMaxTokens(n: number): void { defaultMaxTokens = Math.max(0, Math.floor(n)); }
+
+/** Tool-call budget for one agent run, from settings. `0` disables the cap. */
+export function getDefaultMaxToolCalls(): number { return defaultMaxToolCalls; }
+export function setDefaultMaxToolCalls(n: number): void { defaultMaxToolCalls = Math.max(0, Math.floor(n)); }
+
+/** Default per-tool timeout; `0` disables (no timeout). Mirrors tintinweb — no per-tool timeout by default; hung tools are reclaimed via session abort/quiescence, not a hard tool cut. Set via settings defaultToolTimeoutMs when needed. */
+const DEFAULT_TOOL_TIMEOUT_MS = 0;
+const TOOL_TIMEOUT_CEILING_MS = 600_000;
+let defaultToolTimeoutMs = DEFAULT_TOOL_TIMEOUT_MS;
+export function getDefaultToolTimeoutMs(): number { return defaultToolTimeoutMs; }
+export function setDefaultToolTimeoutMs(n: number): void {
+  defaultToolTimeoutMs = Math.max(0, Math.min(Math.floor(n), TOOL_TIMEOUT_CEILING_MS));
+}
+/** Race a promise against a timeout that rejects with `label timed out after ms`. */
+export function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  if (ms <= 0) return promise;
+  let handle: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    handle = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    handle.unref?.();
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (handle) clearTimeout(handle);
+  });
+}
+
 let graceTurns = 5;
 
 /** Get the grace turns value. */
@@ -431,6 +515,12 @@ export interface RunOptions {
    * the same precedence and the same fail-closed errors from one place.
    */
   agentTier?: string;
+  /** Optional toolset hint forwarded by managed workflow callers. */
+  toolset?: string;
+  /** Additional tool names denied by the caller, merged with agent frontmatter. */
+  excludeTools?: string[];
+  /** Named sequential-thread hint; used for stable session naming. */
+  thread?: string;
   /** Parent thinking level used only when a tier profile omits thinking. */
   parentThinking?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
@@ -478,6 +568,27 @@ export interface RunOptions {
    * JSON/public spawn field; the generation wizard is the only issuer.
    */
   readonly [INTERNAL_AGENT_CONFIG_OVERRIDE]?: InternalAgentConfigOverride;
+  /**
+   * Reopen an existing conversation from this session file instead of starting
+   * a new one. Package-internal: the only issuer is the `@handle` mention
+   * dispatcher, replaying a path this extension itself wrote to the resumable
+   * index. A caller-supplied value would let a spawn read any session on disk,
+   * so no public spawn surface forwards it.
+   */
+  resumeSessionFile?: string;
+  /**
+   * Project default for persisting a top-level agent's conversation to disk,
+   * from the `rememberAgents` setting. Frontmatter `persist_session:` still
+   * wins; nested agents never persist. Without this, only agents that opted in
+   * by frontmatter leave a transcript, and `@handle` has nothing to reopen.
+   */
+  rememberAgents?: boolean;
+  /**
+   * Whether this agent may ask its human a question with `contact_supervisor`.
+   * Defaults to on wherever there is a UI to ask through; `false` withholds the
+   * tool entirely rather than injecting one that always refuses.
+   */
+  supervisorQuestions?: boolean;
   /** Runtime bridge for opt-in child-safe nested delegation. */
   nestedRuntime?: {
     manager: NestedAgentManager;
@@ -951,9 +1062,10 @@ export async function runAgent(
     if (scopeVerdict.kind === "error") throw new Error(scopeVerdict.message);
     if (scopeVerdict.kind === "warn" && ctx.hasUI) ctx.ui.notify(scopeVerdict.message, "warning");
   }
-  const disallowedSet = agentConfig?.disallowedTools
-    ? new Set(agentConfig.disallowedTools)
-    : undefined;
+  const disallowedSet = (() => {
+    const names = [...(agentConfig?.disallowedTools ?? []), ...(options.excludeTools ?? [])];
+    return names.length > 0 ? new Set(names) : undefined;
+  })();
 
   // Nested delegation tools (opt-in, ownership-scoped). Empty unless the agent
   // set `allowed_subagents` and a nestedRuntime was provided — and never when
@@ -978,7 +1090,26 @@ export async function runAgent(
         configCwd,
       })
     : [];
-  const nestedToolNames = new Set(nestedTools.map(tool => tool.name));
+  // `contact_supervisor` is injected separately from the nested tools and under
+  // a different condition. Nesting is gated on `allowedSubagents`, but the agent
+  // that most needs to ask a question is a LEAF one that cannot delegate — so
+  // gating them together would withhold it from exactly those agents. It needs
+  // only a human to answer, which `hasUI` decides. Isolation still suppresses
+  // it: an `isolated: true` agent is defined as built-in tools only.
+  const supervisorTools =
+    ctx.hasUI && !isolated && options.supervisorQuestions !== false
+      ? createSupervisorTool({
+          agentLabel: agentConfig?.displayName ?? type,
+          ask: {
+            input: (title, placeholder) => ctx.ui.input(title, placeholder),
+            select: (title, choices) => ctx.ui.select(title, choices),
+          },
+        })
+      : [];
+  // One list from here on: both sets are custom tools this package injects, and
+  // the scoping pass below keeps exactly the names it is given.
+  const injectedTools = [...nestedTools, ...supervisorTools];
+  const nestedToolNames = new Set(injectedTools.map(tool => tool.name));
 
   // ─── Tool scoping ───────────────────────────────────────────────────────
   //
@@ -1035,17 +1166,33 @@ export async function runAgent(
       for (const name of disallowedSet) denyTools.add(name);
     }
     sessionExcludeTools = [...denyTools];
+    // Named toolsets are advisory labels; they never widen the configured
+    // allowlist. Concrete tool availability remains owned by the agent config.
   }
 
   const settingsManager = SettingsManager.create(configCwd, agentDir);
   const configuredSessionDir = resolveConfiguredSessionDir(agentConfig?.sessionDir, effectiveCwd);
   const defaultSessionDir = process.env.PI_CODING_AGENT_SESSION_DIR ?? settingsManager.getSessionDir?.();
-  const parentSession = agentConfig?.persistSession ? ctx.sessionManager.getSessionFile?.() : undefined;
-  const sessionManager = agentConfig?.persistSession
-    ? parentSession
-      ? SessionManager.create(effectiveCwd, configuredSessionDir ?? defaultSessionDir, { parentSession })
-      : SessionManager.create(effectiveCwd, configuredSessionDir ?? defaultSessionDir)
-    : SessionManager.inMemory(effectiveCwd);
+  // Frontmatter wins when it says anything; otherwise the project default,
+  // which `rememberAgents` supplies for top-level agents only. A nested agent
+  // is an implementation detail of its parent and is never addressable by
+  // `@handle`, so it has nothing to gain from a transcript on disk.
+  const persistSession = agentConfig?.persistSession ?? (options.nestedRuntime ? false : options.rememberAgents === true);
+  // Optional metadata — it only nests the subagent under its spawner in
+  // `/resume`. Now that `rememberAgents` persists every top-level spawn, a
+  // context without a session manager (a bare programmatic ctx) must still
+  // persist rather than take the whole spawn down.
+  const parentSession = persistSession ? ctx.sessionManager?.getSessionFile?.() : undefined;
+  const sessionManager = options.resumeSessionFile
+    ? // Reopening an existing conversation: the file already carries its own
+      // header (cwd, parent) and history, so none of the create-time options
+      // apply. `sessionDir` still matters for a later /new or /branch off it.
+      SessionManager.open(options.resumeSessionFile, configuredSessionDir ?? defaultSessionDir)
+    : persistSession
+      ? parentSession
+        ? SessionManager.create(effectiveCwd, configuredSessionDir ?? defaultSessionDir, { parentSession })
+        : SessionManager.create(effectiveCwd, configuredSessionDir ?? defaultSessionDir)
+      : SessionManager.inMemory(effectiveCwd);
 
   // Pi 0.80.8 replaced createAgentSession's modelRegistry option with
   // modelRuntime, but ExtensionContext still exposes only the registry facade.
@@ -1063,7 +1210,7 @@ export async function runAgent(
     ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime }),
     model,
     tools: sessionTools,
-    customTools: nestedTools,
+    customTools: injectedTools,
     resourceLoader: loader,
   };
   if (sessionExcludeTools) {
@@ -1083,9 +1230,9 @@ export async function runAgent(
   try {
     throwIfAborted(options.signal);
 
-  const baseSessionName = agentConfig?.name ?? type;
+  const baseSessionName = options.thread ? `workflow-thread:${options.thread}` : (agentConfig?.name ?? type);
   session.setSessionName(
-    options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName,
+    options.agentId && !options.thread ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName,
   );
 
   // Bind extensions so that session_start fires and extensions can initialize
@@ -1108,6 +1255,15 @@ export async function runAgent(
   // (we can't deny the name of a tool that hasn't registered yet). Both are
   // handled below by re-deriving scope from the loader's live extension maps —
   // `registerTool` writes into those same maps, so late arrivals are judged too.
+  // `ask_tools:` gates individual CALLS, which is orthogonal to which tools
+  // exist — so it applies to isolated agents too, where the scope installer
+  // below never runs because the registry is already statically allowlisted.
+  const askGate = createAskGate({
+    askTools: agentConfig?.askTools ?? [],
+    agentLabel: agentConfig?.displayName ?? type,
+    ...(ctx.hasUI ? { confirm: (title: string, message: string) => ctx.ui.confirm(title, message) } : {}),
+  });
+
   if (!noExtensions) {
     installExtensionToolScope(session, {
       loader,
@@ -1116,7 +1272,26 @@ export async function runAgent(
       extNames,
       narrowing,
       nestedToolNames,
+      ...(askGate ? { askGate } : {}),
     });
+  } else if (askGate) {
+    // Same hook, without the scope check the allowlist already performed.
+    const priorBeforeToolCall = session.agent.beforeToolCall;
+    session.agent.beforeToolCall = async (context, signal) => {
+      const run = async () => {
+        const gated = await askGate(context.toolCall.name, (context.toolCall as { input?: unknown }).input);
+        if (gated) return gated;
+        return priorBeforeToolCall?.(context, signal);
+      };
+      if (defaultToolTimeoutMs > 0) {
+        try {
+          return await withTimeout(run(), defaultToolTimeoutMs, `beforeToolCall for "${context.toolCall.name}"`);
+        } catch (err) {
+          return { block: true, reason: (err as Error).message };
+        }
+      }
+      return run();
+    };
   }
 
   if (options.onSessionCreated) {
@@ -1133,7 +1308,76 @@ export async function runAgent(
   let softLimitReached = false;
   let aborted = false;
 
+  // Resource budgets, in the same shape as max_turns: a wrap-up steer at the
+  // soft threshold, an abort at the hard one. They bound what a single agent
+  // can spend on its own, which turn count does not — one turn can burn an
+  // arbitrary number of tokens or tool calls.
+  //
+  // `0` means unlimited here, matching this package's existing convention for
+  // `maxTurns`. That is the opposite of `maxSubagentSpawnsPerBranch`, and
+  // deliberately: these are opt-in resource caps that ship off, while the
+  // branch spawn budget is a safety valve that ships on.
+  const tokenBudget = normalizeMaxTurns(agentConfig?.maxTokens ?? defaultMaxTokens);
+  const toolCallBudget = normalizeMaxTurns(agentConfig?.maxToolCalls ?? defaultMaxToolCalls);
+  let budgetTokens = 0;
+  let budgetToolCalls = 0;
+  let tokenSoftReached = false;
+  let toolSoftReached = false;
+
+  /**
+   * Apply one budget, returning the next soft-limit state.
+   *
+   * The soft threshold is `SOFT_BUDGET_FRACTION` of the budget so the agent has
+   * room left to actually write its answer after being told to wrap up — a
+   * steer sent at 100% would be asking for a final response with no allowance
+   * to produce it.
+   */
+  const applyBudget = (used: number, budget: number | undefined, softReached: boolean, label: string): boolean => {
+    if (budget == null) return softReached;
+    // The hard limit is checked FIRST. One message can consume more than the
+    // whole budget, and testing the soft threshold first would answer that with
+    // a wrap-up steer and no abort — leaving an agent already over budget to
+    // run on until its next event.
+    if (used >= budget) {
+      aborted = true;
+      session.abort();
+      return true;
+    }
+    if (!softReached && used >= budget * SOFT_BUDGET_FRACTION) {
+      session.steer(
+        `You are near your ${label} budget for this task. Wrap up immediately — provide your final answer now.`,
+      );
+      return true;
+    }
+    return softReached;
+  };
+
   let currentMessageText = "";
+  // Per-tool timeout: a hung bash/MCP call must not stall the subagent forever.
+  // Each tool_execution_start arms a timer; the matching end clears it. On
+  // timeout the session is aborted — which propagates via the tool's
+  // AbortSignal into the hanging execute() and surfaces as an error result.
+  // `contact_supervisor` is excluded: it intentionally waits for a human.
+  const pendingToolTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+  const clearToolTimeout = (toolCallId: string): void => {
+    const handle = pendingToolTimeouts.get(toolCallId);
+    if (handle) {
+      clearTimeout(handle);
+      pendingToolTimeouts.delete(toolCallId);
+    }
+  };
+  const armToolTimeout = (toolCallId: string, toolName: string): void => {
+    if (defaultToolTimeoutMs <= 0) return;
+    if (toolName === "contact_supervisor") return;
+    const handle = setTimeout(() => {
+      pendingToolTimeouts.delete(toolCallId);
+      try {
+        session.abort();
+      } catch {}
+    }, defaultToolTimeoutMs);
+    handle.unref?.();
+    pendingToolTimeouts.set(toolCallId, handle);
+  };
   const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
     if (event.type === "turn_end") {
       turnCount++;
@@ -1157,9 +1401,13 @@ export async function runAgent(
     }
     if (event.type === "tool_execution_start") {
       options.onToolActivity?.({ type: "start", toolName: event.toolName });
+      armToolTimeout((event as { toolCallId: string }).toolCallId, event.toolName);
     }
     if (event.type === "tool_execution_end") {
+      clearToolTimeout((event as { toolCallId: string }).toolCallId);
       options.onToolActivity?.({ type: "end", toolName: event.toolName });
+      budgetToolCalls++;
+      toolSoftReached = applyBudget(budgetToolCalls, toolCallBudget, toolSoftReached, "tool call");
     }
     if (event.type === "message_end" && event.message.role === "assistant") {
       const u = (event.message as any).usage;
@@ -1168,6 +1416,12 @@ export async function runAgent(
         output: u.output ?? 0,
         cacheWrite: u.cacheWrite ?? 0,
       });
+      if (u) {
+        // Same total as `getLifetimeTotal`: input + output + cacheWrite, with
+        // cacheRead deliberately excluded.
+        budgetTokens += (u.input ?? 0) + (u.output ?? 0) + (u.cacheWrite ?? 0);
+        tokenSoftReached = applyBudget(budgetTokens, tokenBudget, tokenSoftReached, "token");
+      }
     }
     if (event.type === "compaction_end" && !event.aborted && event.result) {
       options.onCompaction?.({ reason: event.reason, tokensBefore: event.result.tokensBefore });
@@ -1195,9 +1449,18 @@ export async function runAgent(
   } finally {
     unsubTurns();
     collector.unsubscribe();
+    for (const handle of pendingToolTimeouts.values()) clearTimeout(handle);
+    pendingToolTimeouts.clear();
   }
 
-  const responseText = collector.getText().trim() || getLastAssistantText(session, startLen);
+  const baseText = collector.getText().trim() || getLastAssistantText(session, startLen);
+  // The acceptance gate runs AFTER the agent is done and its verdict is
+  // appended to the result, so the parent reads the check and the claim it is
+  // checking side by side. It deliberately does not steer the agent to fix
+  // what failed: the gate is evidence for the caller, not another turn.
+  const responseText = agentConfig?.gate
+    ? `${baseText}${await runConfiguredGate(agentConfig.gate, effectiveCwd, options.pi)}`
+    : baseText;
   completed = true;
   return { responseText, session, aborted, steered: softLimitReached, failure: finalTurnError(session, startLen) };
   } finally {
@@ -1253,6 +1516,32 @@ export async function resumeAgent(
         }
       })
     : () => {};
+  // Per-tool timeout for resume as well — same stuck-command fix as runAgent.
+  const resumePendingTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+  const unsubResumeTimeout =
+    defaultToolTimeoutMs > 0
+      ? session.subscribe((event: AgentSessionEvent) => {
+          if (event.type === "tool_execution_start") {
+            const id = (event as { toolCallId: string }).toolCallId;
+            if (event.toolName === "contact_supervisor") return;
+            const handle = setTimeout(() => {
+              resumePendingTimeouts.delete(id);
+              try {
+                session.abort();
+              } catch {}
+            }, defaultToolTimeoutMs);
+            handle.unref?.();
+            resumePendingTimeouts.set(id, handle);
+          } else if (event.type === "tool_execution_end") {
+            const id = (event as { toolCallId: string }).toolCallId;
+            const handle = resumePendingTimeouts.get(id);
+            if (handle) {
+              clearTimeout(handle);
+              resumePendingTimeouts.delete(id);
+            }
+          }
+        })
+      : () => {};
 
   try {
     throwIfAborted(options.signal);
@@ -1260,6 +1549,9 @@ export async function resumeAgent(
   } finally {
     collector.unsubscribe();
     unsubEvents();
+    unsubResumeTimeout();
+    for (const handle of resumePendingTimeouts.values()) clearTimeout(handle);
+    resumePendingTimeouts.clear();
     cleanupAbort();
   }
 

package/src/agent-tiers.ts

@@ -36,14 +36,82 @@ function effectiveModelId(model: Model<Api> | undefined): string | 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 = {};
+/**
+ * The tier every fresh install gets: a cheap, low-thinking tier named `fast`.
+ *
+ * Explore — the highest-frequency built-in spawn — points its `tier:` at it, so
+ * read-only search does not silently inherit the parent session's most
+ * expensive model on a machine that never configured `agentTiers`. This is the
+ * tier strategy, not a per-agent vendor pin: the shipped profile is
+ * provider-neutral (`inherit` model, low thinking), and any user who defines
+ * `fast` in `subagents.json` replaces it wholesale.
+ *
+ * It is not shown as an available tier until settings are loaded; the merge in
+ * `setAgentTiersSettings` is where a worktree that explicitly disables/renames
+ * `fast` can win.
+ */
+const SHIPPED_FAST_PROFILE: AgentTierProfile = {
+  model: "inherit",
+  thinking: "low",
+  description: "Fast, low-cost tier for cheap read-only work (shipped default)",
+};
+
+export const SHIPPED_AGENT_TIER_PROFILES: Readonly<Record<string, AgentTierProfile>> = {
+  fast: SHIPPED_FAST_PROFILE,
+};
 
+let agentTiersSettings: AgentTiersSettings = {}; // effective view (shipped tiers merged)
+let agentTiersConfigured: AgentTiersSettings = {}; // exactly what the user configured
+
+/** Effective catalogue: shipped tiers merged under any user configuration. */
 export function getAgentTiersSettings(): AgentTiersSettings {
   return structuredClone(agentTiersSettings);
 }
 
+/** The raw user configuration, without shipped tiers — what snapshotSettings writes back. */
+export function getAgentTiersConfiguredSettings(): AgentTiersSettings {
+  return structuredClone(agentTiersConfigured);
+}
+
+/** Exactly-equal profile? Used to strip untouched shipped tiers from the configured view. */
+function sameProfile(a: AgentTierProfile, b: AgentTierProfile): boolean {
+  return a.model === b.model && a.thinking === b.thinking && (a.description ?? "") === (b.description ?? "");
+}
+
+/**
+ * Install the effective tier catalogue.
+ *
+ * The shipped `fast` tier is merged in unless the caller already defined it or
+ * explicitly blocked it — a user catalogue wins over the shipped default, and a
+ * tombstone means "do not substitute", which applies to shipped defaults too.
+ *
+ * The configured view is derived from the same input by stripping profiles that
+ * exactly equal a shipped default, so the UI can operate on the effective view
+ * and send it back without materializing untouched shipped tiers into
+ * `subagents.json`. Editing a shipped tier (changing its model, thinking, or
+ * description) makes it a user-owned profile and it is then persisted; deleting
+ * one leaves its tombstone, which persists.
+ */
 export function setAgentTiersSettings(settings: AgentTiersSettings): void {
-  agentTiersSettings = structuredClone(settings);
+  const effective = structuredClone(settings);
+  const profiles = { ...(effective.profiles ?? {}) };
+  const blocked = new Set<string>(effective.blockedProfiles ?? []);
+
+  const configuredProfiles: Record<string, AgentTierProfile> = {};
+  for (const [key, profile] of Object.entries(profiles)) {
+    const shipped = SHIPPED_AGENT_TIER_PROFILES[key];
+    if (!blocked.has(key) && shipped !== undefined && sameProfile(profile, shipped)) continue;
+    configuredProfiles[key] = profile;
+  }
+  for (const [key, profile] of Object.entries(SHIPPED_AGENT_TIER_PROFILES)) {
+    if (!blocked.has(key) && profiles[key] === undefined) profiles[key] = profile;
+  }
+
+  agentTiersSettings = { ...effective, profiles };
+  const configured: AgentTiersSettings = { ...effective };
+  if (Object.keys(configuredProfiles).length > 0) configured.profiles = configuredProfiles;
+  else delete configured.profiles;
+  agentTiersConfigured = configured;
 }
 
 /**
@@ -173,13 +241,24 @@ export function upsertAgentTierProfile(
  * A `defaultTier` pointing at it is cleared in the same step. Leaving it would
  * turn every later spawn that names no tier into a hard refusal, which is a
  * strange thing to get from deleting a tier you had stopped using.
+ *
+ * Deleting a shipped tier (the default `fast`) tombstones it instead of just
+ * dropping it: the shipped merge in `setAgentTiersSettings` would otherwise
+ * silently re-add it on the next load, and a user who deletes it means it. The
+ * tombstone says "do not substitute", which is exactly the semantics the load
+ * path already honors for malformed profiles. Explore still names `fast` in its
+ * frontmatter, so the spawn refusal then says so loudly until the agent file or
+ * the tier is fixed.
  */
 export function removeAgentTierProfile(settings: AgentTiersSettings, key: string): AgentTiersSettings {
   const { [key]: _removed, ...profiles } = settings.profiles ?? {};
+  const shipped = Object.hasOwn(SHIPPED_AGENT_TIER_PROFILES, key);
+  let blocked = withoutBlocked(settings.blockedProfiles, key);
+  if (shipped) blocked = [...(blocked ?? []), key];
   return compactTierSettings({
     ...settings,
     profiles,
-    blockedProfiles: withoutBlocked(settings.blockedProfiles, key),
+    blockedProfiles: blocked,
     ...(settings.defaultTier === key ? { defaultTier: undefined } : {}),
   });
 }

package/src/agent-types.ts

@@ -295,6 +295,7 @@ export function getToolNamesForType(type: string): string[] {
 /** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
 export function getConfig(type: string): {
   displayName: string;
+  color?: string;
   description: string;
   builtinToolNames: string[];
   extensions: true | string[] | false;
@@ -307,6 +308,7 @@ export function getConfig(type: string): {
   if (config && config.enabled !== false) {
     return {
       displayName: config.displayName ?? config.name,
+      color: config.color,
       description: config.description,
       builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: config.extensions,
@@ -321,6 +323,7 @@ export function getConfig(type: string): {
   if (gp && gp.enabled !== false) {
     return {
       displayName: gp.displayName ?? gp.name,
+      color: gp.color,
       description: gp.description,
       builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
       extensions: gp.extensions,