@tintinweb/pi-subagents 0.8.0 → 0.9.0

package/dist/index.js

@@ -11,14 +11,15 @@
  */
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { defineTool, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { defineTool, getAgentDir, getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Key, matchesKey, 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 { resolveModel } from "./model-resolver.js";
@@ -459,6 +460,16 @@ export default function (pi) {
     let schedulingEnabled = true;
     function isSchedulingEnabled() { return schedulingEnabled; }
     function setSchedulingEnabled(b) { 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() { return scopeModelsEnabled; }
+    function setScopeModelsEnabled(enabled) { 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
@@ -506,26 +517,24 @@ export default function (pi) {
         widget.setUICtx(ctx.ui);
         widget.onTurnStart();
     });
+    /** Format an agent's tool scope: "*" when it has all built-ins, else a comma-separated list. */
+    const formatToolsSuffix = (cfg) => {
+        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 defaultDescs = defaultNames.map((name) => {
+        const allNames = [...getDefaultAgentNames(), ...getUserAgentNames()];
+        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. */
     function getModelLabelFromConfig(model) {
@@ -544,6 +553,7 @@ export default function (pi) {
         setGraceTurns,
         setDefaultJoinMode,
         setSchedulingEnabled,
+        setScopeModels: setScopeModelsEnabled,
     }, (event, payload) => pi.events.emit(event, payload));
     // ---- Agent tool ----
     // Schedule param + its guideline are gated on `schedulingEnabled` (read once
@@ -565,27 +575,48 @@ export default function (pi) {
     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.",
@@ -734,6 +765,29 @@ Guidelines:
                     model = resolved;
                 }
             }
+            // 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;
@@ -1352,7 +1406,7 @@ Guidelines:
         }
         // Build the .md file content
         const fmFields = [];
-        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"}`);
@@ -1630,35 +1684,70 @@ ${systemPrompt}
             graceTurns: getGraceTurns(),
             defaultJoinMode: getDefaultJoinMode(),
             schedulingEnabled: isSchedulingEnabled(),
+            scopeModels: isScopeModelsEnabled(),
         };
     }
+    const NUMERIC_IDS = new Set(["maxConcurrent", "defaultMaxTurns", "graceTurns"]);
     async function showSettings(ctx) {
-        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;
-        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 buildItems() {
+            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"],
+                },
+            ];
+        }
+        function applyValue(id, value) {
+            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");
@@ -1667,43 +1756,20 @@ ${systemPrompt}
                     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];
-                setDefaultJoinMode(mode);
-                notifyApplied(ctx, `Default join mode set to ${mode}`);
+            else if (id === "joinMode") {
+                setDefaultJoinMode(value);
+                notifyApplied(ctx, `Default join mode set to ${value}`);
             }
-        }
-        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 === "schedulingEnabled") {
+                const enabled = value === "on";
                 if (enabled === isSchedulingEnabled()) {
                     ctx.ui.notify(`Scheduling already ${enabled ? "enabled" : "disabled"}.`, "info");
                 }
@@ -1714,6 +1780,71 @@ ${systemPrompt}
                     notifyApplied(ctx, `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;
+        // 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((_tui, _theme, _kb, done) => {
+            const items = buildItems();
+            list = new SettingsList(items, items.length + 2, getSettingsListTheme(), (id, newValue) => {
+                applyValue(id, newValue);
+            }, () => done(undefined));
+            const container = new Container();
+            container.addChild(new Text("⚙  Subagent Settings", 0, 0));
+            container.addChild(new Spacer(1));
+            container.addChild(list);
+            return {
+                render: (w) => container.render(w),
+                invalidate: () => container.invalidate(),
+                handleInput: (data) => {
+                    // 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 = 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);
+            }
         }
     }
     // Persist the current snapshot, emit `subagents:settings_changed`, and surface

package/dist/settings.d.ts

@@ -18,6 +18,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. */
 export interface SettingsAppliers {
@@ -26,6 +48,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. */
 export type SettingsEmit = (event: string, payload: unknown) => void;

package/dist/settings.js

@@ -38,6 +38,9 @@ function sanitize(raw) {
     if (typeof r.schedulingEnabled === "boolean") {
         out.schedulingEnabled = r.schedulingEnabled;
     }
+    if (typeof r.scopeModels === "boolean") {
+        out.scopeModels = r.scopeModels;
+    }
     return out;
 }
 function globalPath() {
@@ -95,6 +98,8 @@ export function applySettings(s, appliers) {
         appliers.setDefaultJoinMode(s.defaultJoinMode);
     if (typeof s.schedulingEnabled === "boolean")
         appliers.setSchedulingEnabled(s.schedulingEnabled);
+    if (typeof s.scopeModels === "boolean")
+        appliers.setScopeModels(s.scopeModels);
 }
 /**
  * Format the user-facing toast for a settings mutation. Pure function —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/default-agents.ts

@@ -14,7 +14,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
     {
       name: "general-purpose",
       displayName: "Agent",
-      description: "General-purpose agent for complex, multi-step tasks",
+      description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
       // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
       // inheritContext / runInBackground / isolated omitted — strategy fields, callers decide per-call.
       // Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
@@ -30,7 +30,7 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
     {
       name: "Explore",
       displayName: "Explore",
-      description: "Fast codebase exploration agent (read-only)",
+      description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.",
       builtinToolNames: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,
@@ -72,7 +72,7 @@ Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find,
     {
       name: "Plan",
       displayName: "Plan",
-      description: "Software architect for implementation planning (read-only)",
+      description: "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
       builtinToolNames: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,