@tintinweb/pi-subagents 0.8.0 → 0.9.0

package/src/enabled-models.ts

@@ -0,0 +1,180 @@
+/**
+ * Reads `enabledModels` from pi's settings (global `<agentDir>/settings.json`
+ * + project-local `<cwd>/.pi/settings.json`, project wins) and resolves
+ * entries to concrete `provider/modelId` keys for scope validation.
+ *
+ * **Project overrides global**, mirroring pi's own `SettingsManager`
+ * deep-merge behavior and matching the precedence we use for our own
+ * `subagents.json` settings (see `src/settings.ts:loadSettings`). If
+ * project file has `enabledModels` set, it wholly replaces global's
+ * (array fields are replaced, not concatenated).
+ *
+ * **Limited subset of upstream's resolveModelScope.** We support exact
+ * `provider/modelId` matching only. Upstream (pi-coding-agent's
+ * `core/model-resolver.ts`) additionally supports glob patterns
+ * (`*sonnet*`, `anthropic/*`), bare model IDs without provider, and
+ * thinking-level suffixes (`provider/*:high`). Those forms are silently
+ * ignored here.
+ *
+ * In practice, pi's `/scoped-models` picker writes exact `provider/modelId`
+ * entries, so the limitation is invisible for users who configure scope
+ * through pi's UI. Hand-edited settings using globs or bare IDs will
+ * produce an empty allowed set (scope check becomes a no-op).
+ *
+ * Example:
+ *   enabledModels = ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"]
+ *   → resolves to { "anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6" }
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelEntry } from "./model-resolver.js";
+
+/** Minimal registry shape — only the methods resolveEnabledModels actually calls. */
+export interface ModelRegistryRef {
+  getAll(): unknown[];
+  getAvailable?(): unknown[];
+}
+
+/** Paths to pi's settings.json files: [project, global] (project takes precedence). */
+function settingsPaths(cwd: string): [project: string, global: string] {
+  return [
+    join(cwd, ".pi", "settings.json"),
+    join(getAgentDir(), "settings.json"),
+  ];
+}
+
+/** Read `enabledModels` from a single settings.json file. Undefined when missing or absent. */
+function readField(path: string): string[] | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8"));
+    if (Array.isArray(raw?.enabledModels)) return raw.enabledModels as string[];
+  } catch {
+    /* corrupt file — silent */
+  }
+  return undefined;
+}
+
+/**
+ * Read enabledModels from pi's settings — project-local overrides global.
+ * Mirrors pi's SettingsManager deep-merge for the `enabledModels` field
+ * (and matches our own loadSettings precedence in src/settings.ts).
+ * Returns undefined when neither file has the field.
+ */
+export function readEnabledModels(cwd: string): string[] | undefined {
+  const [project, global] = settingsPaths(cwd);
+  return readField(project) ?? readField(global);
+}
+
+/**
+ * Resolve enabledModels patterns → Set<"provider/modelId"> (lowercase keys).
+ *
+ * Only exact `provider/modelId` patterns are matched (case-insensitive).
+ * Patterns without a slash, with glob characters, or with a `:thinking`
+ * suffix are silently dropped. See module-level docstring for rationale.
+ *
+ * Cache: keyed on JSON.stringify(patterns) + mtime/size of *both*
+ * project and global settings.json files. Re-resolves when either file
+ * changes or the patterns argument differs.
+ *
+ * Returns undefined when no patterns are provided or no patterns match
+ * (scope check becomes a no-op at the call site).
+ */
+
+// Module-level cache — invalidated when either settings.json changes or patterns differ.
+let cachedAllowed: Set<string> | undefined;
+let cachedHash = "";
+let cachedPatternsKey = "";
+
+/** mtime+size hash of one file, or "missing" if absent. */
+function hashOf(path: string): string {
+  try {
+    const s = statSync(path);
+    return `${s.mtimeMs}-${s.size}`;
+  } catch {
+    return "missing";
+  }
+}
+
+export function resolveEnabledModels(
+  patterns: string[] | undefined,
+  registry: ModelRegistryRef,
+  cwd: string = process.cwd(),
+): Set<string> | undefined {
+  // Fast path: check cache (stat both project and global settings.json files)
+  const patternsKey = JSON.stringify(patterns);
+  const [project, global] = settingsPaths(cwd);
+  const fileHash = `${hashOf(project)};${hashOf(global)}`;
+
+  if (fileHash === cachedHash && patternsKey === cachedPatternsKey) {
+    return cachedAllowed;
+  }
+
+  // Cache miss — resolve
+  if (!patterns || patterns.length === 0) {
+    cachedHash = fileHash;
+    cachedPatternsKey = patternsKey;
+    cachedAllowed = undefined;
+    return undefined;
+  }
+
+  const available = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
+  const allowed = new Set<string>();
+
+  for (const pattern of patterns) {
+    const trimmed = pattern.trim();
+    if (!trimmed) continue;  // skip empty/whitespace
+    resolveExact(trimmed, available, allowed);
+  }
+
+  const result = allowed.size > 0 ? allowed : undefined;
+  cachedHash = fileHash;
+  cachedPatternsKey = patternsKey;
+  cachedAllowed = result;
+  return result;
+}
+
+
+
+/**
+ * True when `model` is in the allowed set. Centralizes the key format
+ * (`provider/id` lowercase) so callers don't have to reproduce it —
+ * both set-building (resolveExact) and lookup go through `modelKey`.
+ */
+export function isModelInScope(
+  model: { provider: string; id: string },
+  allowed: Set<string>,
+): boolean {
+  return allowed.has(modelKey(model));
+}
+
+/** Canonical lowercase `provider/id` key for the allowed set. */
+function modelKey(model: { provider: string; id: string }): string {
+  return `${model.provider}/${model.id}`.toLowerCase();
+}
+
+/**
+ * Resolve exact model pattern. Example: "google/gemma-4-31b-it".
+ */
+function resolveExact(
+  pattern: string,
+  available: ModelEntry[],
+  allowed: Set<string>,
+): void {
+  // "provider/modelId" — exact (colon is part of id, not split)
+  const slashIdx = pattern.indexOf("/");
+  if (slashIdx === -1) return; // bare modelId not supported
+
+  const provider = pattern.slice(0, slashIdx).toLowerCase();
+  const modelId = pattern.slice(slashIdx + 1).toLowerCase();
+  const exact = available.find(
+    m => m.provider.toLowerCase() === provider && m.id.toLowerCase() === modelId,
+  );
+  if (exact) {
+    allowed.add(modelKey(exact));
+  }
+}
+
+

package/src/index.ts

@@ -12,14 +12,15 @@
 
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Key, matchesKey, type SettingItem, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
 import { GroupJoinManager } from "./group-join.js";
 import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
@@ -518,6 +519,17 @@ export default function (pi: ExtensionAPI) {
   function isSchedulingEnabled(): boolean { return schedulingEnabled; }
   function setSchedulingEnabled(b: boolean) { schedulingEnabled = b; }
 
+  // ---- Scope models configuration ----
+  // When enabled, subagent model choices are validated against `enabledModels`
+  // from pi's settings — both global `<agentDir>/settings.json` and
+  // project-local `<cwd>/.pi/settings.json` (project overrides global).
+  // Off by default; opt-in via `/agents → Settings`. See docstring on
+  // SubagentsSettings.scopeModels for the hard-error vs warn-and-proceed
+  // policy and its rationale.
+  let scopeModelsEnabled = false;
+  function isScopeModelsEnabled(): boolean { return scopeModelsEnabled; }
+  function setScopeModelsEnabled(enabled: boolean): void { scopeModelsEnabled = enabled; }
+
   // ---- Batch tracking for smart join mode ----
   // Collects background agent IDs spawned in the current turn for smart grouping.
   // Uses a debounced timer: each new agent resets the 100ms window so that all
@@ -567,29 +579,26 @@ export default function (pi: ExtensionAPI) {
     widget.onTurnStart();
   });
 
+  /** Format an agent's tool scope: "*" when it has all built-ins, else a comma-separated list. */
+  const formatToolsSuffix = (cfg: AgentConfig | undefined): string => {
+    const tools = cfg?.builtinToolNames;
+    if (!tools || tools.length === 0) return "*";
+    const isFullSet =
+      tools.length === BUILTIN_TOOL_NAMES.length
+      && BUILTIN_TOOL_NAMES.every((t) => tools.includes(t));
+    return isFullSet ? "*" : tools.join(", ");
+  };
+
   /** Build the full type list text dynamically from the unified registry. */
   const buildTypeListText = () => {
-    const defaultNames = getDefaultAgentNames();
-    const userNames = getUserAgentNames();
+    const allNames = [...getDefaultAgentNames(), ...getUserAgentNames()];
 
-    const defaultDescs = defaultNames.map((name) => {
+    return allNames.map((name) => {
       const cfg = getAgentConfig(name);
       const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
-      return `- ${name}: ${cfg?.description ?? name}${modelSuffix}`;
-    });
-
-    const customDescs = userNames.map((name) => {
-      const cfg = getAgentConfig(name);
-      return `- ${name}: ${cfg?.description ?? name}`;
-    });
-
-    return [
-      "Default agents:",
-      ...defaultDescs,
-      ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
-      "",
-      `Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
-    ].join("\n");
+      const toolsSuffix = ` (Tools: ${formatToolsSuffix(cfg)})`;
+      return `- ${name}: ${cfg?.description ?? name}${modelSuffix}${toolsSuffix}`;
+    }).join("\n");
   };
 
   /** Derive a short model label from a model string. */
@@ -612,6 +621,7 @@ export default function (pi: ExtensionAPI) {
       setGraceTurns,
       setDefaultJoinMode,
       setSchedulingEnabled,
+      setScopeModels: setScopeModelsEnabled,
     },
     (event, payload) => pi.events.emit(event, payload),
   );
@@ -643,27 +653,48 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool(defineTool({
     name: "Agent",
     label: "Agent",
-    description: `Launch a new agent to handle complex, multi-step tasks autonomously.
-
-The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+    description: `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
-Available agent types:
+Available agent types and the tools they have access to:
 ${typeListText}
 
-Guidelines:
-- For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.
-- Use Explore for codebase searches and code understanding.
-- Use Plan for architecture and implementation planning.
-- Use general-purpose for complex tasks that need file editing.
-- Provide clear, detailed prompts so the agent can work autonomously.
-- Agent results are returned as text — summarize them for the user.
-- Use run_in_background for work you don't need immediately. You will be notified when it completes.
-- Use resume with an agent ID to continue a previous agent's work.
+Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.
+
+When using the Agent tool, specify a subagent_type parameter to select which agent type to use.
+
+## When not to use
+
+If the target is already known, use a direct tool — \`read\` for a known path, \`grep\`/\`find\` for a specific symbol or string. Reserve this tool for open-ended questions that span the codebase, or tasks that match an available agent type.
+
+## Usage notes
+
+- Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
+- When you launch multiple agents for independent work, send them in a single message with multiple tool uses, with run_in_background: true on each, so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls. Foreground calls run sequentially — only one executes at a time.
+- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
+- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
+- Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
+- Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
+- Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
 - 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 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).${scheduleGuideline}`,
+- 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}
+
+## Writing the prompt
+
+Provide clear, detailed prompts so the agent can work autonomously. Brief it like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- If you need a short response, say so ("report in under 200 words").
+- Lookups: hand over the exact command. Investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
+
+Terse command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.`,
     parameters: Type.Object({
       prompt: Type.String({
         description: "The task for the agent to perform.",
@@ -842,6 +873,35 @@ Guidelines:
         }
       }
 
+      // Scope validation: the effective resolved model is checked against the
+      // user's enabledModels list (read in `enabled-models.ts`).
+      //
+      // Design: scopeModels guards against *runtime* LLM choices, not user-level config.
+      //   - Caller-supplied out-of-scope → hard error (the orchestrator made an explicit
+      //     out-of-scope choice; surface it so it picks differently).
+      //   - Frontmatter-pinned or parent-inherited out-of-scope → warn but proceed (the
+      //     user authored/installed this agent or chose the parent's model; trust it).
+      // See SubagentsSettings.scopeModels docstring for the full policy.
+      if (isScopeModelsEnabled() && model) {
+        const allowed = resolveEnabledModels(readEnabledModels(ctx.cwd), ctx.modelRegistry, ctx.cwd);
+        if (allowed && !isModelInScope(model, allowed)) {
+          if (resolvedConfig.modelFromParams) {
+            const list = [...allowed].sort().map(m => `  ${m}`).join("\n");
+            return textResult(
+              `Model not in scope: "${resolvedConfig.modelInput}".\n\n` +
+              `Allowed models (from enabledModels):\n${list}`,
+            );
+          }
+          // Frontmatter-pinned or parent-inherited: warn + proceed.
+          const agentLabel = customConfig?.displayName ?? subagentType;
+          const modelLabel = resolvedConfig.modelInput ?? `${model.provider}/${model.id}`;
+          ctx.ui.notify(
+            `Agent "${agentLabel}" using out-of-scope model "${modelLabel}"`,
+            "warning",
+          );
+        }
+      }
+
       const thinking = resolvedConfig.thinking;
       const inheritContext = resolvedConfig.inheritContext;
       const runInBackground = resolvedConfig.runInBackground;
@@ -1515,7 +1575,7 @@ Guidelines:
 
     // Build the .md file content
     const fmFields: string[] = [];
-    fmFields.push(`description: ${cfg.description}`);
+    fmFields.push(`description: ${JSON.stringify(cfg.description)}`);
     if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`);
     fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") || "all"}`);
     if (cfg.model) fmFields.push(`model: ${cfg.model}`);
@@ -1790,76 +1850,91 @@ ${systemPrompt}
       graceTurns: getGraceTurns(),
       defaultJoinMode: getDefaultJoinMode(),
       schedulingEnabled: isSchedulingEnabled(),
+      scopeModels: isScopeModelsEnabled(),
     };
   }
 
+  const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns"]);
+
   async function showSettings(ctx: ExtensionCommandContext) {
-    const choice = await ctx.ui.select("Settings", [
-      `Max concurrency (current: ${manager.getMaxConcurrent()})`,
-      `Default max turns (current: ${getDefaultMaxTurns() ?? "unlimited"})`,
-      `Grace turns (current: ${getGraceTurns()})`,
-      `Join mode (current: ${getDefaultJoinMode()})`,
-      `Scheduling (current: ${isSchedulingEnabled() ? "enabled" : "disabled"})`,
-    ]);
-    if (!choice) return;
+    function buildItems(): SettingItem[] {
+      const mc = manager.getMaxConcurrent();
+      const dmt = getDefaultMaxTurns() ?? 0;
+      const gt = getGraceTurns();
+
+      return [
+        {
+          id: "maxConcurrent",
+          label: "Max concurrency",
+          description: "Max concurrent background agents (Enter to type)",
+          currentValue: String(mc),
+          values: [String(mc)],
+        },
+        {
+          id: "defaultMaxTurns",
+          label: "Default max turns",
+          description: "Default max turns before wrap-up (0 = unlimited, Enter to type)",
+          currentValue: String(dmt),
+          values: [String(dmt)],
+        },
+        {
+          id: "graceTurns",
+          label: "Grace turns",
+          description: "Grace turns after wrap-up steer (Enter to type)",
+          currentValue: String(gt),
+          values: [String(gt)],
+        },
+        {
+          id: "joinMode",
+          label: "Join mode",
+          description: "Default join mode for background agents",
+          currentValue: getDefaultJoinMode(),
+          values: ["smart", "async", "group"],
+        },
+        {
+          id: "schedulingEnabled",
+          label: "Scheduling",
+          description: "Schedule subagent feature (off removes `schedule` param from Agent tool spec on next pi session)",
+          currentValue: isSchedulingEnabled() ? "on" : "off",
+          values: ["on", "off"],
+        },
+        {
+          id: "scopeModels",
+          label: "Scope models",
+          description: "Validate subagent models against scoped models (/scoped-models)",
+          currentValue: isScopeModelsEnabled() ? "on" : "off",
+          values: ["on", "off"],
+        },
+      ];
+    }
 
-    if (choice.startsWith("Max concurrency")) {
-      const val = await ctx.ui.input("Max concurrent background agents", String(manager.getMaxConcurrent()));
-      if (val) {
-        const n = parseInt(val, 10);
+    function applyValue(id: string, value: string) {
+      if (id === "maxConcurrent") {
+        const n = parseInt(value, 10);
         if (n >= 1) {
           manager.setMaxConcurrent(n);
           notifyApplied(ctx, `Max concurrency set to ${n}`);
-        } else {
-          ctx.ui.notify("Must be a positive integer.", "warning");
         }
-      }
-    } else if (choice.startsWith("Default max turns")) {
-      const val = await ctx.ui.input("Default max turns before wrap-up (0 = unlimited)", String(getDefaultMaxTurns() ?? 0));
-      if (val) {
-        const n = parseInt(val, 10);
+      } else if (id === "defaultMaxTurns") {
+        const n = parseInt(value, 10);
         if (n === 0) {
           setDefaultMaxTurns(undefined);
           notifyApplied(ctx, "Default max turns set to unlimited");
         } else if (n >= 1) {
           setDefaultMaxTurns(n);
           notifyApplied(ctx, `Default max turns set to ${n}`);
-        } else {
-          ctx.ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
         }
-      }
-    } else if (choice.startsWith("Grace turns")) {
-      const val = await ctx.ui.input("Grace turns after wrap-up steer", String(getGraceTurns()));
-      if (val) {
-        const n = parseInt(val, 10);
+      } else if (id === "graceTurns") {
+        const n = parseInt(value, 10);
         if (n >= 1) {
           setGraceTurns(n);
           notifyApplied(ctx, `Grace turns set to ${n}`);
-        } else {
-          ctx.ui.notify("Must be a positive integer.", "warning");
         }
-      }
-    } else if (choice.startsWith("Join mode")) {
-      const val = await ctx.ui.select("Default join mode for background agents", [
-        "smart — auto-group 2+ agents in same turn (default)",
-        "async — always notify individually",
-        "group — always group background agents",
-      ]);
-      if (val) {
-        const mode = val.split(" ")[0] as JoinMode;
-        setDefaultJoinMode(mode);
-        notifyApplied(ctx, `Default join mode set to ${mode}`);
-      }
-    } else if (choice.startsWith("Scheduling")) {
-      const val = await ctx.ui.select(
-        "Schedule subagent feature",
-        [
-          "enabled — Agent tool accepts a `schedule` param; /agents → Scheduled jobs visible",
-          "disabled — `schedule` removed from Agent tool spec (no LLM-context cost); menu hidden",
-        ],
-      );
-      if (val) {
-        const enabled = val.startsWith("enabled");
+      } else if (id === "joinMode") {
+        setDefaultJoinMode(value as JoinMode);
+        notifyApplied(ctx, `Default join mode set to ${value}`);
+      } else if (id === "schedulingEnabled") {
+        const enabled = value === "on";
         if (enabled === isSchedulingEnabled()) {
           ctx.ui.notify(`Scheduling already ${enabled ? "enabled" : "disabled"}.`, "info");
         } else {
@@ -1870,6 +1945,84 @@ ${systemPrompt}
             `Scheduling ${enabled ? "enabled" : "disabled"}. Tool spec change takes effect on next pi session.`,
           );
         }
+      } else if (id === "scopeModels") {
+        const enabled = value === "on";
+        setScopeModelsEnabled(enabled);
+        notifyApplied(ctx, `Scope models ${enabled ? "enabled" : "disabled"}`);
+      }
+    }
+
+    let list: SettingsList;
+    // Track current selection index directly (SettingsList doesn't expose it).
+    // Updated on arrow keys so Enter knows which field is selected immediately.
+    let currentIndex = 0;
+
+    const result = await ctx.ui.custom<string | undefined>((_tui, _theme, _kb, done) => {
+      const items = buildItems();
+
+      list = new SettingsList(
+        items,
+        items.length + 2,
+        getSettingsListTheme(),
+        (id, newValue) => {
+          applyValue(id, newValue);
+        },
+        () => done(undefined as undefined),
+      );
+
+      const container = new Container();
+      container.addChild(new Text("⚙  Subagent Settings", 0, 0));
+      container.addChild(new Spacer(1));
+      container.addChild(list);
+
+      return {
+        render: (w: number) => container.render(w),
+        invalidate: () => container.invalidate(),
+        handleInput: (data: string) => {
+          // Track navigation so Enter knows the current field
+          if (matchesKey(data, "up")) {
+            currentIndex = Math.max(0, currentIndex - 1);
+          } else if (matchesKey(data, "down")) {
+            currentIndex = Math.min(items.length - 1, currentIndex + 1);
+          }
+
+          // Enter on numeric field → close and prompt for typed input
+          if (matchesKey(data, Key.enter) && NUMERIC_IDS.has(items[currentIndex].id)) {
+            done(items[currentIndex].id);
+            return;
+          }
+          list.handleInput?.(data);
+        },
+      };
+    });
+
+    // If a numeric field ID was returned, prompt for typed input
+    if (result && NUMERIC_IDS.has(result)) {
+      const current = result === "maxConcurrent"
+        ? String(manager.getMaxConcurrent())
+        : result === "defaultMaxTurns"
+          ? String(getDefaultMaxTurns() ?? 0)
+          : String(getGraceTurns());
+
+      const label = result === "maxConcurrent"
+        ? "Max concurrency (1+)"
+        : result === "defaultMaxTurns"
+          ? "Default max turns (0 = unlimited)"
+          : "Grace turns (1+)";
+
+      // Loop until user enters a valid integer or cancels (Esc / null).
+      // Silently trims whitespace; rejects non-numeric input by re-prompting.
+      let input: string | undefined = await ctx.ui.input(label, current);
+      while (input != null) {
+        const trimmed = input.trim();
+        const n = Number(trimmed);
+        if (trimmed !== "" && Number.isInteger(n)) {
+          applyValue(result, String(n));
+          await showSettings(ctx);
+          return;
+        }
+        // Invalid — re-prompt with the user's last entry so they can edit it
+        input = await ctx.ui.input(label, trimmed);
       }
     }
   }

package/src/settings.ts

@@ -26,6 +26,28 @@ export interface SubagentsSettings {
    * (next pi session); runtime menu/runtime-fire short-circuit is immediate.
    */
   schedulingEnabled?: boolean;
+  /**
+   * When true, the effective model of each subagent spawn is validated
+   * against `enabledModels` from pi's settings — both global
+   * (`<agentDir>/settings.json`) and project-local (`<cwd>/.pi/settings.json`),
+   * with project overriding global (mirrors pi's SettingsManager deep-merge).
+   *
+   * scopeModels guards against runtime LLM choices, not user-level config.
+   * Out-of-scope handling reflects this:
+   *   - Caller-supplied via `Agent({ model: "..." })` (only when frontmatter
+   *     has no `model:`, since frontmatter is authoritative): hard error
+   *     returned to the orchestrator, listing the allowed models. The LLM
+   *     made an explicit out-of-scope choice and gets explicit feedback.
+   *   - Frontmatter-pinned: warning toast + the pinned model runs. The
+   *     agent's author/installer chose this; trust it.
+   *   - Parent-inherited (neither caller nor frontmatter sets a model):
+   *     warning toast + parent's model runs. The user chose the parent's
+   *     model when starting the session; trust it.
+   *
+   * No-op when pi's `enabledModels` is empty or absent — nothing to validate
+   * against. Defaults to false: subagents may use any model.
+   */
+  scopeModels?: boolean;
 }
 
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
@@ -35,6 +57,7 @@ export interface SettingsAppliers {
   setGraceTurns: (n: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
   setSchedulingEnabled: (b: boolean) => void;
+  setScopeModels: (enabled: boolean) => void;
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
@@ -81,6 +104,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.schedulingEnabled === "boolean") {
     out.schedulingEnabled = r.schedulingEnabled;
   }
+  if (typeof r.scopeModels === "boolean") {
+    out.scopeModels = r.scopeModels;
+  }
   return out;
 }
 
@@ -136,6 +162,7 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
   if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
   if (typeof s.schedulingEnabled === "boolean") appliers.setSchedulingEnabled(s.schedulingEnabled);
+  if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels);
 }
 
 /**