@signalridge/pi-subagents 1.4.0 → 1.6.1

package/src/agent-tiers.ts

@@ -25,7 +25,7 @@
 
 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 AgentTierProfile, type AgentTiersSettings, TIER_THINKING_LEVELS, type TierThinking } from "./settings.js";
 import type { AgentConfig, ThinkingLevel } from "./types.js";
 
 /** `provider/id`, or undefined when no model was selected. */
@@ -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;
 }
 
 /**
@@ -111,15 +179,128 @@ export class AgentTierError extends Error {
   }
 }
 
-function knownTierKeys(settings: AgentTiersSettings): string[] {
+/** Every defined tier key, sorted — the catalogue as the UI and the host see it. */
+export function listAgentTierKeys(settings: AgentTiersSettings): string[] {
   return Object.keys(settings.profiles ?? {}).sort((a, b) => a.localeCompare(b));
 }
 
 function tierKeyList(settings: AgentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   return keys.length > 0 ? keys.join(", ") : "(none configured)";
 }
 
+/**
+ * Tier edits, as pure settings-to-settings functions.
+ *
+ * The `/agents → Model tiers` menu is the only caller, but the rules it has to
+ * obey are policy, not presentation — retiring a tombstone, not leaving
+ * `defaultTier` pointing at a tier that no longer exists — so they live here
+ * with the resolver that enforces the other half of the same invariants.
+ *
+ * Each returns a fresh object and omits empty containers, so a catalogue edited
+ * back down to nothing serializes as nothing rather than as empty braces.
+ */
+function withoutBlocked(blocked: string[] | undefined, key: string): string[] | undefined {
+  const rest = (blocked ?? []).filter((k) => k !== key);
+  return rest.length > 0 ? rest : undefined;
+}
+
+function compactTierSettings(settings: AgentTiersSettings): AgentTiersSettings {
+  const out: AgentTiersSettings = {};
+  if (settings.defaultTier !== undefined) out.defaultTier = settings.defaultTier;
+  if (settings.profiles && Object.keys(settings.profiles).length > 0) out.profiles = settings.profiles;
+  if (settings.blockedProfiles && settings.blockedProfiles.length > 0) {
+    out.blockedProfiles = settings.blockedProfiles;
+  }
+  if (settings.blockedDefaultTier) out.blockedDefaultTier = true;
+  return out;
+}
+
+/**
+ * Define or replace one tier.
+ *
+ * Writing a valid profile retires that key's tombstone: the tombstone exists to
+ * stop a malformed entry from silently resolving to some other model, and an
+ * explicit definition is the fix it was waiting for.
+ */
+export function upsertAgentTierProfile(
+  settings: AgentTiersSettings,
+  key: string,
+  profile: AgentTierProfile,
+): AgentTiersSettings {
+  return compactTierSettings({
+    ...settings,
+    profiles: { ...settings.profiles, [key]: profile },
+    blockedProfiles: withoutBlocked(settings.blockedProfiles, key),
+  });
+}
+
+/**
+ * Delete one tier.
+ *
+ * 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: blocked,
+    ...(settings.defaultTier === key ? { defaultTier: undefined } : {}),
+  });
+}
+
+/**
+ * The thinking values a tier may usefully store for one model reference.
+ *
+ * Asked of the model rather than read off a fixed list, because `resolveAgentTier`
+ * clamps an unsupported level at spawn time: a menu offering a level destined to
+ * be silently lowered would be a menu that lies. `inherit` is always offerable —
+ * it defers to the parent session, which this model has no say over.
+ *
+ * A reference of `inherit`, or one this machine cannot resolve, yields the full
+ * static list: the model is not knowable here, and refusing to let the user
+ * configure a tier for a provider they have not authed yet would make the menu
+ * weaker than hand-editing the file.
+ */
+export function offerableTierThinking(
+  modelRef: string,
+  registry: ModelRegistry<Model<Api>>,
+): TierThinking[] {
+  if (modelRef === "inherit") return [...TIER_THINKING_LEVELS];
+  const resolved = resolveModel(modelRef, registry);
+  if (typeof resolved === "string") return [...TIER_THINKING_LEVELS];
+  const supported = new Set<string>(getSupportedThinkingLevels(resolved));
+  return TIER_THINKING_LEVELS.filter(level => level === "inherit" || supported.has(level));
+}
+
+/**
+ * Set or clear the default tier.
+ *
+ * Always clears `blockedDefaultTier`: that tombstone describes the malformed
+ * value this call is replacing, and keeping it would make the resolver refuse
+ * the choice the user just made explicitly.
+ */
+export function setDefaultAgentTier(
+  settings: AgentTiersSettings,
+  key: string | undefined,
+): AgentTiersSettings {
+  return compactTierSettings({ ...settings, defaultTier: key, blockedDefaultTier: false });
+}
+
 /**
  * Which tier applies, and where it came from.
  *
@@ -285,7 +466,7 @@ export function findUnknownAgentTierReferences(
  * models and thinking levels appear — nothing here reads credentials.
  */
 export function buildAgentTierListText(settings: AgentTiersSettings = agentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   if (keys.length === 0) return "";
 
   const entries = keys.map((key) => {
@@ -304,7 +485,7 @@ export function buildAgentTierListText(settings: AgentTiersSettings = agentTiers
 
 /** One line per tier, for the compact tool description. */
 export function buildCompactAgentTierListText(settings: AgentTiersSettings = agentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   if (keys.length === 0) return "";
 
   const entries = keys.map((key) => {
@@ -323,7 +504,7 @@ export function getDefaultAgentTierText(settings: AgentTiersSettings = agentTier
 
 /** Description for the `tier` parameter, naming the keys this workspace defines. */
 export function buildAgentTierParameterDescription(settings: AgentTiersSettings = agentTiersSettings): string {
-  const keys = knownTierKeys(settings);
+  const keys = listAgentTierKeys(settings);
   const available = keys.length > 0 ? keys.join(", ") : "none configured";
   const fallback =
     settings.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,

package/src/ask-tools.ts

@@ -0,0 +1,114 @@
+/**
+ * ask-tools.ts — `ask_tools:`, the third answer between allow and deny.
+ *
+ * `tools:` and `disallowed_tools:` are static: a tool is available for the whole
+ * run or never. That forces a bad choice for the tools that are usually fine and
+ * occasionally not — grant `bash` and hope, or withhold it and cripple the
+ * agent. `ask_tools:` names the tools whose every call needs a person to agree.
+ *
+ * The approver is the HUMAN, deliberately. Upstream projects put an LLM in this
+ * seat because their subagents run headless in another process and cannot reach
+ * a person; ours share the parent's `ExtensionContext`, so a real approver is
+ * one dialog away. Asking a model whether a model should be allowed to do
+ * something is a security regression wherever a person is reachable, so this
+ * module contains no arbitrator — only the rule vocabulary and a prompt.
+ */
+
+import { sanitizeDisplayText, truncateCodePoints } from "./ui/safe-text.js";
+
+/** Longest tool-argument preview shown in the approval prompt. */
+const MAX_PREVIEW = 300;
+
+export interface AskGateDecision {
+  block: true;
+  reason: string;
+}
+
+export interface AskGateContext {
+  /** Tool names requiring approval. Matched case-insensitively. */
+  askTools: readonly string[];
+  /** Prompt the human. Omitted when no human can be reached. */
+  confirm?: (title: string, message: string) => Promise<boolean>;
+  /** Display name of the agent asking, for the prompt. */
+  agentLabel: string;
+}
+
+/**
+ * Build the per-call approval gate, or `undefined` when nothing needs asking.
+ *
+ * Returns a function that resolves to a block decision when the call must not
+ * proceed, and `undefined` when it may.
+ */
+export function createAskGate(
+  context: AskGateContext,
+): ((toolName: string, input: unknown) => Promise<AskGateDecision | undefined>) | undefined {
+  const gated = new Set(context.askTools.map((name) => name.trim().toLowerCase()).filter(Boolean));
+  if (gated.size === 0) return undefined;
+
+  /** Tools the user has approved for the rest of this run. */
+  const approvedForRun = new Set<string>();
+
+  return async (toolName, input) => {
+    const key = toolName.toLowerCase();
+    if (!gated.has(key)) return undefined;
+    if (approvedForRun.has(key)) return undefined;
+
+    // No approver, no approval. Failing OPEN here would silently delete the
+    // rule the user wrote — the one case where it matters most is the one where
+    // nobody is watching. A headless run of an agent with `ask_tools:` is
+    // therefore refused, with a reason that says how to fix it.
+    if (!context.confirm) {
+      return {
+        block: true,
+        reason:
+          `Tool "${toolName}" requires approval (ask_tools), and there is no interactive session to approve it. ` +
+          "Run this agent interactively, or move the tool to `tools:`/`disallowed_tools:` to decide it statically.",
+      };
+    }
+
+    let approved: boolean;
+    try {
+      approved = await context.confirm(
+        `${context.agentLabel} wants to use ${toolName}`,
+        `${describeInput(input)}\n\nAllow this call?`,
+      );
+    } catch {
+      // A prompt that cannot be shown is not an approval.
+      return {
+        block: true,
+        reason: `Tool "${toolName}" requires approval (ask_tools) and the prompt could not be shown.`,
+      };
+    }
+
+    if (!approved) {
+      return {
+        block: true,
+        reason: `The user declined the "${toolName}" call. Do not retry it; continue without that tool or explain what you cannot do.`,
+      };
+    }
+    // Approved for the remainder of the run rather than for this call alone:
+    // re-asking on every call of a tool the user just allowed trains them to
+    // approve without reading, which is how an approval prompt stops working.
+    approvedForRun.add(key);
+    return undefined;
+  };
+}
+
+/**
+ * One-line, bounded, inert rendering of a tool call's arguments.
+ *
+ * The user is being asked to approve a specific call, so the arguments are the
+ * whole point — but they are model-authored and about to be drawn into a
+ * terminal, so they are sanitized before truncation, never after.
+ */
+function describeInput(input: unknown): string {
+  if (input === undefined || input === null) return "(no arguments)";
+  let rendered: string;
+  try {
+    rendered = typeof input === "string" ? input : JSON.stringify(input);
+  } catch {
+    return "(arguments could not be displayed)";
+  }
+  if (!rendered) return "(no arguments)";
+  return truncateCodePoints(sanitizeDisplayText(rendered).replace(/\s+/g, " ").trim(), MAX_PREVIEW, "…");
+}

package/src/cross-extension-rpc.ts

@@ -41,6 +41,7 @@ export interface SpawnCapable {
   abort(id: string): boolean;
   abortOwned?(id: string, owner: AgentOwner): boolean;
   quiesceOwned?(runId: string, agentIds: string[], timeoutMs: number, owners?: AgentOwner[]): Promise<{ settled: boolean; pending: string[] }>;
+  reconcileManaged?(spawnKey: string, owner: AgentOwner): ManagedSpawnResult | undefined;
 }
 
 export interface RpcDeps {
@@ -56,6 +57,7 @@ export interface RpcHandle {
   unsubStop: () => void;
   unsubStopOwned: () => void;
   unsubSpawnManaged: () => void;
+  unsubReconcile: () => void;
   unsubQuiesce: () => void;
 }
 
@@ -157,7 +159,7 @@ function handleRpc(
 }
 
 /**
- * Register ping, legacy spawn/stop, and managed workflow spawn handlers.
+ * Register ping, legacy spawn/stop, and managed workflow spawn/reconciliation handlers.
  * Returns unsubscribe functions for cleanup.
  */
 export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
@@ -204,9 +206,8 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     if (!ctx) throw new Error("No active session");
     if (!manager.spawnManaged) throw new Error("Managed spawn is unavailable");
     const request = validateManagedSpawnRequest(params);
-    // The wire request deliberately carries no execution policy. The production
-    // wrapper resolves it from the agent configuration; direct fixtures receive
-    // an explicit empty policy so the manager seam remains total.
+    // Policy hints are validated at the protocol boundary, then resolved by the
+    // production wrapper and AgentManager so the peer never bypasses local policy.
     const result = manager.spawnManaged(pi, ctx, request, {}) as ManagedSpawnResult | string;
     // Keep the additive handler tolerant of an older in-process manager fixture
     // while protocol-v3 managers return the richer state snapshot.
@@ -214,6 +215,16 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     return result;
   });
 
+  const unsubReconcile = handleRpc(events, "subagents:rpc:reconcile-managed", (params) => {
+    if (!manager.reconcileManaged) throw new Error("Managed reconciliation is unavailable");
+    rejectUnknownKeys(params, new Set(["requestId", "spawnKey", "owner"]), "managed reconciliation request");
+    const spawnKey = boundedString(params.spawnKey, "spawnKey", 256);
+    const owner = validateManagedOwner(params.owner, true);
+    const result = manager.reconcileManaged(spawnKey, owner);
+    if (!result) throw new Error("Managed spawn key not found or owner mismatch");
+    return result;
+  });
+
   const unsubStop = handleRpc(events, "subagents:rpc:stop", (params) => {
     const agentId = boundedString(params.agentId, "agentId", 128);
     if (!manager.abort(agentId)) throw new Error("Agent not found");
@@ -254,5 +265,5 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     return manager.quiesceOwned(runId, agentIds, rawTimeout, owners);
   });
 
-  return { unsubPing, unsubSpawn, unsubStop, unsubStopOwned, unsubSpawnManaged, unsubQuiesce };
+  return { unsubPing, unsubSpawn, unsubStop, unsubStopOwned, unsubSpawnManaged, unsubQuiesce, unsubReconcile };
 }

package/src/custom-agents.ts

@@ -26,6 +26,12 @@ import { sanitizeDisplayText } from "./ui/safe-text.js";
 type WarningSink = (message: string, key?: string) => void;
 type SkippedAgent = { name: string; priority: number };
 
+/**
+ * Colon is reserved for plugin-scoped identifiers (extension-owned agent
+ * types). A file may not claim one; see the `name:` guard in `loadFromDir`.
+ */
+const RESERVED_IN_TYPE = ":";
+
 /** Normalize a discovery root so aliases and symlinked worktree paths share state. */
 function normalizeDiscoveryRoot(cwd: string): string {
   const absolute = resolve(cwd);
@@ -71,6 +77,27 @@ function warningReasonKey(reason: string): string {
   return reason.split(":", 1)[0] ?? reason;
 }
 
+/** Best-effort extraction of `name:` from raw frontmatter when strict parsing failed. */
+function peekDeclaredName(path: string): string | undefined {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const fmMatch = /^---\s*\n([\s\S]*?)\n---/m.exec(raw);
+    if (!fmMatch) return undefined;
+    const block = fmMatch[1];
+    // Match `name:` with optional quotes, trimming inline comments.
+    const nameMatch = /^\s*name\s*:\s*["']?([^"'\n#]+?)["']?\s*(?:#.*)?$/m.exec(block);
+    if (!nameMatch) return undefined;
+    const declared = nameMatch[1].trim();
+    // Guard `||` semantics: empty/whitespace falls back to filename.
+    if (!declared) return undefined;
+    // Colon is plugin-scope reserved; such files never enter skip override logic.
+    if (declared.includes(RESERVED_IN_TYPE)) return undefined;
+    return declared;
+  } catch {
+    return undefined;
+  }
+}
+
 const MAX_WARNING_ROOTS = 64;
 const warningCache = new Map<string, Set<string>>();
 
@@ -154,30 +181,68 @@ function loadFromDir(
   }
 
   for (const file of files) {
-    const name = basename(file, ".md");
+    const filenameType = basename(file, ".md");
+
     const path = join(dir, file);
+
     const parsed = readAgentFile(path, strict, warn);
     if (!parsed) {
-      skipped.push({ name, priority });
+      // Even a malformed file may have declared `name:`; when it does, the
+      // skip must be filed under that name, not the filename, so a higher-
+      // priority higher file declaring the same name still suppresses the
+      // warning (B1#1). Best-effort regex — the authoritative parse already
+      // failed, so this is only for the override warning key.
+      const peeked = peekDeclaredName(path);
+      const skipName = peeked !== undefined ? peeked : filenameType;
+      skipped.push({ name: skipName, priority });
       continue;
     }
     const { frontmatter: fm, body } = parsed;
 
+    // Claude Code's rule: `name:` IS the agent type, and the filename need not
+    // match. Absent, the filename stands in — Claude Code requires the field,
+    // but most files here predate it and must keep loading.
+    const declared = str(fm.name)?.trim();
+    if (declared?.includes(RESERVED_IN_TYPE)) {
+      // Refusing beats silently substituting: the file would otherwise load
+      // under its filename, so `Agent({subagent_type})` would succeed against
+      // an agent whose declared identity nothing honoured.
+      warn(
+        `Agent file ${path} declares name "${declared}", which contains "${RESERVED_IN_TYPE}" — reserved for `
+        + "plugin-scoped identifiers. Rename it, or move the label to `display_name:`. Skipping.",
+        `reserved-name:${warningIdentity(path)}`,
+      );
+      // No skipped entry: this file would have registered under its *declared*
+      // name, which nothing else can hold (a colon keeps it out of the
+      // registry), so it shadowed nothing. Reporting the filename instead
+      // would claim a substitution of an unrelated agent that never happened.
+      continue;
+    }
+    // `||`, not `??`: a quoted empty or all-whitespace `name:` would otherwise
+    // register the agent under the empty type — unspawnable, and it takes the
+    // filename-derived one down with it.
+    const name = declared || filenameType;
+
     const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
     warnLegacyModelFields(fm, path, warn);
 
     agents.set(name, {
       name,
       displayName: label(fm.display_name),
+      color: str(fm.color)?.trim(),
       description: label(fm.description) ?? sanitizeDisplayText(name),
       builtinToolNames,
       extSelectors,
       disallowedTools: csvListOptional(fm.disallowed_tools),
+      askTools: csvListOptional(fm.ask_tools),
+      gate: str(fm.gate)?.trim(),
       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),
       maxTurns: nonNegativeInt(fm.max_turns),
+      maxTokens: nonNegativeInt(fm.max_tokens),
+      maxToolCalls: nonNegativeInt(fm.max_tool_calls),
       persistSession: fm.persist_session != null ? fm.persist_session === true : undefined,
       outputTranscript: fm.output_transcript != null ? fm.output_transcript !== false : undefined,
       sessionDir: str(fm.session_dir),

package/src/default-agents.ts

@@ -34,11 +34,12 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       builtinToolNames: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,
-      // 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.
+      // Runs on the shipped `fast` agent tier (model inherit, low thinking) so
+      // read-only search does not inherit the parent session's most expensive
+      // model on machines that never configured agentTiers. The tier is the
+      // policy: point `fast` at a cheap model in subagents.json and Explore
+      // follows without touching agent files.
+      agentTier: "fast",
       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.