agent-sh 0.9.0 → 0.10.0

package/examples/extensions/claude-code-bridge/index.ts

@@ -2,11 +2,13 @@
  * Claude Code bridge — runs Claude Code Agent SDK in-process as agent-sh's backend.
  *
  * Uses the official @anthropic-ai/claude-agent-sdk to spawn a Claude Code
- * session with a custom user_shell MCP tool for PTY access. Claude Code
+ * session with custom MCP tools for PTY access. Claude Code
  * handles its own model selection, tool execution, and permissions.
  *
- * Setup:
- *   npm install @anthropic-ai/claude-agent-sdk
+ * Setup (from repo root):
+ *   npm run build && npm link                    # register local agent-sh globally
+ *   cd examples/extensions/claude-code-bridge
+ *   npm install && npm link agent-sh             # link local dev copy
  *
  * Usage:
  *   agent-sh -e examples/extensions/claude-code-bridge
@@ -20,8 +22,11 @@ import {
   type Query,
 } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
-import type { ExtensionContext } from "../../src/types.js";
-import type { EventBus } from "../../src/event-bus.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { ExtensionContext } from "agent-sh/types";
+import type { EventBus } from "agent-sh/event-bus";
+import { computeDiff, type DiffResult } from "agent-sh/utils/diff";
 
 // ── Helpers ──────────────────────────────────────────────────────
 function interpretEscapes(str: string): string {
@@ -40,39 +45,6 @@ function settle(ms = 100): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-// ── user_shell MCP tool ───────────────────────────────────────────
-function createUserShellTool(bus: EventBus) {
-  let liveCwd = process.cwd();
-  bus.on("shell:cwd-change", ({ cwd }) => { liveCwd = cwd; });
-
-  return tool(
-    "user_shell",
-    "Run a command with lasting effects in the user's live shell (cd, export, " +
-    "install packages, start servers) or show output the user wants to see. " +
-    "Set return_output=true only if you need to inspect the result.",
-    {
-      command: z.string().describe("Command to execute in user's shell"),
-      return_output: z.boolean().optional().describe(
-        "Whether to return the command output. Default false.",
-      ),
-    },
-    async (args) => {
-      const result = await bus.emitPipeAsync("shell:exec-request", {
-        command: args.command,
-        output: "",
-        cwd: liveCwd,
-        done: false,
-      });
-
-      const text = args.return_output
-        ? result.output || "(no output)"
-        : "Command executed.";
-
-      return { content: [{ type: "text" as const, text }] };
-    },
-  );
-}
-
 // ── terminal_read MCP tool ────────────────────────────────────────
 function createTerminalReadTool(ctx: ExtensionContext) {
   return tool(
@@ -132,18 +104,56 @@ function createTerminalKeysTool(bus: EventBus, ctx: ExtensionContext) {
 export default function activate(ctx: ExtensionContext): void {
   const { bus } = ctx;
 
-  const shellTool = createUserShellTool(bus);
   const termReadTool = createTerminalReadTool(ctx);
   const termKeysTool = createTerminalKeysTool(bus, ctx);
   const shellServer = createSdkMcpServer({
     name: "agent-sh",
     version: "1.0.0",
-    tools: [shellTool, termReadTool, termKeysTool],
+    tools: [termReadTool, termKeysTool],
   });
 
   let activeQuery: Query | null = null;
   const listeners: Array<{ event: string; fn: Function }> = [];
 
+  // ── Tool display helpers ────────────────────────────────────────
+
+  /** Map Claude Code tool names to agent-sh display kinds. */
+  function toolKind(name: string): string {
+    if (name === "Read" || name.includes("terminal_read")) return "read";
+    if (name === "Edit") return "edit";
+    if (name === "Write") return "write";
+    if (name === "Glob" || name === "Grep") return "search";
+    if (name === "Bash" || name.includes("terminal_keys")) return "execute";
+    return "execute";
+  }
+
+  /** Map Claude Code tool names to agent-sh display icons. */
+  function toolIcon(name: string): string | undefined {
+    if (name === "Read") return "◆";
+    if (name === "Edit") return "✎";
+    if (name === "Write") return "✎";
+    if (name === "Glob" || name === "Grep") return "⌕";
+    return undefined;
+  }
+
+  /** Extract file locations from tool input args. */
+  function toolLocations(input: Record<string, unknown>): { path: string; line?: number | null }[] | undefined {
+    const raw = input.file_path ?? input.path;
+    if (typeof raw !== "string") return undefined;
+    const line = (input.line_number ?? input.line ?? input.offset) as number | undefined;
+    return [{ path: raw, line: line ?? null }];
+  }
+
+  /** Format a compact display string for a tool call. */
+  function formatToolCall(name: string, input: Record<string, unknown>): string {
+    const str = (v: unknown) => typeof v === "string" ? v : "";
+    if (name === "Bash") return `$ ${str(input.command)}`;
+    if (name === "Read" || name === "Edit" || name === "Write") return str(input.file_path ?? input.path);
+    if (name === "Grep" || name === "Glob") return `${str(input.pattern)} ${str(input.path)}`.trim();
+    if (name.includes("terminal_keys")) return str(input.keys);
+    return name;
+  }
+
   const wireListeners = () => {
     const onSubmit = async ({ query: userQuery }: any) => {
       bus.emit("agent:query", { query: userQuery });
@@ -151,6 +161,14 @@ export default function activate(ctx: ExtensionContext): void {
 
       let fullResponseText = "";
       let streamed = false;
+      /** Track in-flight tool calls so we can emit tool-completed when results arrive. */
+      const pendingTools = new Map<string, { name: string; kind: string; input?: Record<string, unknown> }>();
+      /** Tool input JSON being streamed via input_json_delta events. */
+      const inputBuffers = new Map<number, string>();
+      /** Tool metadata per content block index (for correlating deltas). */
+      const blockMeta = new Map<number, { name: string; id: string }>();
+      /** Pre-edit file snapshots for diff display (Edit/Write tools). */
+      const fileSnapshots = new Map<string, string | null>();
 
       try {
         activeQuery = query({
@@ -163,12 +181,10 @@ export default function activate(ctx: ExtensionContext): void {
               append:
                 "You are running inside agent-sh, a terminal wrapper.\n" +
                 "Use your standard tools (Read, Edit, Write, Bash, Glob, Grep) for investigation.\n" +
-                "Use mcp__agent-sh__user_shell to run commands in the user's live shell when they ask to see output or need lasting effects (cd, install, start servers).\n" +
-                "Default to standard tools. Use user_shell when the user is the intended audience for the output or the command has real effects.",
+                "Use mcp__agent-sh__terminal_read and mcp__agent-sh__terminal_keys to observe and interact with the user's live terminal.",
             },
             mcpServers: { "agent-sh": shellServer },
             allowedTools: [
-              "mcp__agent-sh__user_shell",
               "mcp__agent-sh__terminal_read",
               "mcp__agent-sh__terminal_keys",
               "Read", "Edit", "Write", "Bash", "Glob", "Grep",
@@ -183,16 +199,56 @@ export default function activate(ctx: ExtensionContext): void {
             case "stream_event": {
               streamed = true;
               const event = message.event;
-              if (event.type === "content_block_delta") {
-                const delta = event.delta as any;
-                if (delta.type === "text_delta" && delta.text) {
+              if (event.type === "content_block_start") {
+                const cb = (event as any).content_block;
+                if (cb?.type === "tool_use") {
+                  blockMeta.set(event.index, { name: cb.name, id: cb.id });
+                  inputBuffers.set(event.index, "");
+                }
+              } else if (event.type === "content_block_delta") {
+                const delta = (event as any).delta;
+                if (delta?.type === "text_delta" && delta.text) {
                   bus.emitTransform("agent:response-chunk", {
                     blocks: [{ type: "text" as const, text: delta.text }],
                   });
                   fullResponseText += delta.text;
-                } else if (delta.type === "thinking_delta" && delta.thinking) {
+                } else if (delta?.type === "thinking_delta" && delta.thinking) {
                   bus.emit("agent:thinking-chunk", { text: delta.thinking });
+                } else if (delta?.type === "input_json_delta" && delta.partial_json != null) {
+                  // Accumulate tool input JSON as it streams in
+                  const buf = inputBuffers.get(event.index) ?? "";
+                  inputBuffers.set(event.index, buf + delta.partial_json);
                 }
+              } else if (event.type === "content_block_stop") {
+                const meta = blockMeta.get(event.index);
+                const inputJson = inputBuffers.get(event.index);
+                if (meta && inputJson != null) {
+                  blockMeta.delete(event.index);
+                  inputBuffers.delete(event.index);
+
+                  let input: Record<string, unknown> = {};
+                  try { input = JSON.parse(inputJson || "{}"); } catch {}
+
+                  const kind = toolKind(meta.name);
+                  bus.emit("agent:tool-started", {
+                    title: meta.name,
+                    toolCallId: meta.id,
+                    kind,
+                    icon: toolIcon(meta.name),
+                    locations: toolLocations(input),
+                    rawInput: input,
+                    displayDetail: formatToolCall(meta.name, input),
+                  });
+                  pendingTools.set(meta.id, { name: meta.name, kind, input });
+
+                  // Snapshot file content before Edit/Write modifies it
+                  if ((meta.name === "Edit" || meta.name === "Write") && typeof (input as any).file_path === "string") {
+                    const absPath = resolve(process.cwd(), (input as any).file_path);
+                    readFile(absPath, "utf-8")
+                      .then(content => fileSnapshots.set(meta.id, content))
+                      .catch(() => fileSnapshots.set(meta.id, null)); // file doesn't exist yet
+                  }
+              }
               }
               break;
             }
@@ -206,24 +262,115 @@ export default function activate(ctx: ExtensionContext): void {
                     blocks: [{ type: "text" as const, text: b.text }],
                   });
                   fullResponseText += b.text;
-                } else if (b.type === "tool_use") {
+                } else if (b.type === "tool_use" && !streamed) {
+                  // Non-streamed fallback: emit tool-started from full message
+                  const input = (b.input ?? {}) as Record<string, unknown>;
+                  const kind = toolKind(b.name);
                   bus.emit("agent:tool-started", {
                     title: b.name,
                     toolCallId: b.id,
-                    kind: b.name.includes("shell") || b.name === "Bash"
-                      ? "execute"
-                      : "read",
+                    kind,
+                    icon: toolIcon(b.name),
+                    locations: toolLocations(input),
+                    rawInput: input,
+                    displayDetail: formatToolCall(b.name, input),
                   });
+                  pendingTools.set(b.id, { name: b.name, kind, input });
+
+                  // Snapshot file content before Edit/Write modifies it
+                  if ((b.name === "Edit" || b.name === "Write") && typeof (input as any).file_path === "string") {
+                    const absPath = resolve(process.cwd(), (input as any).file_path);
+                    readFile(absPath, "utf-8")
+                      .then(content => fileSnapshots.set(b.id, content))
+                      .catch(() => fileSnapshots.set(b.id, null));
+                  }
                 }
               }
               break;
             }
 
+            case "user": {
+              // Tool results come back as user messages with tool_result content blocks
+              const msg = message.message as any;
+              if (msg?.content && Array.isArray(msg.content)) {
+                for (const block of msg.content) {
+                  if (block.type === "tool_result") {
+                    const toolUseId = block.tool_use_id as string;
+                    const pending = pendingTools.get(toolUseId);
+                    if (!pending) continue;
+                    pendingTools.delete(toolUseId);
+
+                    const isError = !!block.is_error;
+                    const content = typeof block.content === "string"
+                      ? block.content
+                      : Array.isArray(block.content)
+                        ? block.content.map((c: any) => c.text ?? JSON.stringify(c)).join("\n")
+                        : "";
+
+                    // Compute diff for Edit/Write tools
+                    let resultDisplay: { summary?: string; body?: { kind: "diff"; diff: DiffResult; filePath: string } } | undefined;
+                    if (!isError && (pending.name === "Edit" || pending.name === "Write")) {
+                      const oldContent = fileSnapshots.get(toolUseId);
+                      fileSnapshots.delete(toolUseId);
+                      const filePath = (pending.input as any)?.file_path as string | undefined;
+                      if (filePath) {
+                        const absPath = resolve(process.cwd(), filePath);
+                        try {
+                          const newContent = await readFile(absPath, "utf-8");
+                          const diff = computeDiff(oldContent, newContent);
+                          if (!diff.isIdentical) {
+                            const summary = diff.isNewFile
+                              ? `+${diff.added}`
+                              : `+${diff.added} -${diff.removed}`;
+                            resultDisplay = {
+                              summary,
+                              body: { kind: "diff", diff, filePath: absPath },
+                            };
+                          }
+                        } catch { /* file may not exist after failed edit */ }
+                      }
+                    } else {
+                      fileSnapshots.delete(toolUseId);
+                    }
+
+                    const exitCode = isError ? 1 : 0;
+                    bus.emitTransform("agent:tool-completed", {
+                      toolCallId: toolUseId,
+                      exitCode,
+                      rawOutput: content,
+                      kind: pending.kind,
+                      resultDisplay,
+                    });
+                    bus.emit("agent:tool-output", {
+                      tool: pending.name,
+                      output: content,
+                      exitCode,
+                    });
+                  }
+                }
+              }
+              break;
+            }
+
+            case "tool_progress":
+              // Tool still running — nothing to do, TUI spinner already active
+              break;
+
             case "result":
               break;
           }
         }
 
+        // Emit completion for any tools still pending (edge case: interrupted query)
+        for (const [id, pending] of pendingTools) {
+          bus.emitTransform("agent:tool-completed", {
+            toolCallId: id,
+            exitCode: 0,
+            rawOutput: "",
+            kind: pending.kind,
+          });
+        }
+
         bus.emitTransform("agent:response-done", {
           response: fullResponseText,
         });

package/examples/extensions/claude-code-bridge/package.json

@@ -6,6 +6,7 @@
   "main": "index.ts",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.0",
+    "agent-sh": "^0.9.0",
     "zod": "^4.0.0"
   }
 }

package/examples/extensions/interactive-prompts.ts

@@ -18,9 +18,44 @@ import { palette as p } from "agent-sh/utils/palette.js";
 import type { ExtensionContext } from "agent-sh/types";
 import type { ToolUI } from "agent-sh/agent/types.js";
 
-export default function activate({ bus }: ExtensionContext) {
+export default function activate(ctx: ExtensionContext) {
   let autoApproveWrites = false;
 
+  // Advise the TUI diff renderer to add permission prompt framing.
+  // This replaces the default plain diff box with one that has a warning
+  // border and key hints, so only one diff box is shown (not two).
+  ctx.advise("tui:render-diff", (next, filePath: string, diff: any, width: number) => {
+    const boxW = Math.min(84, width);
+    const contentW = boxW - 4;
+    const MAX_DISPLAY = 25;
+
+    const stats = diff.isNewFile
+      ? `(+${diff.added} lines)`
+      : `(+${diff.added} / -${diff.removed})`;
+    const title = diff.isNewFile
+      ? `new: ${filePath}  ${stats}`
+      : `${filePath}  ${stats}`;
+
+    const diffLines = renderDiff(diff, {
+      width: contentW,
+      filePath,
+      maxLines: MAX_DISPLAY,
+      trueColor: true,
+      mode: "unified",
+    });
+    const content = ["", ...diffLines.slice(1), ""];
+
+    return renderBoxFrame(content, {
+      width: boxW,
+      style: "rounded",
+      borderColor: p.warning,
+      title,
+      footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
+    });
+  });
+
+  const { bus } = ctx;
+
   bus.onPipeAsync("permission:request", async (payload) => {
     const ui = payload.ui as ToolUI | undefined;
     if (!ui) return payload;
@@ -82,36 +117,15 @@ async function handleToolCall(payload: any, ui: ToolUI) {
 }
 
 async function handleFileWrite(payload: any, ui: ToolUI) {
-  const diff = payload.metadata.diff;
-  const filePath = payload.metadata.path ?? payload.title;
-
   const answer = await ui.custom<"approve" | "approve_all" | "reject">({
     render(width) {
       const boxW = Math.min(84, width);
-      const contentW = boxW - 4;
-      const MAX_DISPLAY = 25;
-
-      const stats = diff.isNewFile
-        ? `(+${diff.added} lines)`
-        : `(+${diff.added} / -${diff.removed})`;
-      const title = diff.isNewFile
-        ? `new: ${filePath}  ${stats}`
-        : `${filePath}  ${stats}`;
-
-      const diffLines = renderDiff(diff, {
-        width: contentW,
-        filePath,
-        maxLines: MAX_DISPLAY,
-        trueColor: true,
-        mode: "unified",
-      });
-      const content = ["", ...diffLines.slice(1), ""];
-
-      return renderBoxFrame(content, {
+      // Just show the prompt actions — the diff itself was already rendered
+      // by our advise on "tui:render-diff".
+      return renderBoxFrame([], {
         width: boxW,
         style: "rounded",
         borderColor: p.warning,
-        title,
         footer: [`  ${p.bold}[y] Apply  [n] Skip  [a] Don't ask again${p.reset}`],
       });
     },

package/examples/extensions/overlay-agent.ts

@@ -16,9 +16,9 @@
  *
  * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
  */
-import type { ExtensionContext, RemoteSession } from "../../src/types.js";
-import type { RenderSurface } from "../../src/utils/compositor.js";
-import { FloatingPanel } from "../../src/utils/floating-panel.js";
+import type { ExtensionContext, RemoteSession } from "agent-sh/types";
+import type { RenderSurface } from "agent-sh/utils/compositor";
+import { FloatingPanel } from "agent-sh/utils/floating-panel";
 
 /** Adapt a FloatingPanel to the RenderSurface interface. */
 function createPanelSurface(panel: FloatingPanel): RenderSurface {

package/examples/extensions/peer-mesh.ts

@@ -268,6 +268,54 @@ export default function activate(ctx: ExtensionContext): void {
   define("peer:context-search", (query: string) => contextManager.search(query));
   server.expose("peer:context-search");
 
+  // ── Inter-peer messaging ───────────────────────────────────
+
+  interface InboxEntry { from: string; text: string; at: number; }
+  const inbox: InboxEntry[] = [];
+  const INBOX_MAX = 100;
+
+  const pending: InboxEntry[] = [];
+
+  define("peer:message", (from: string, text: string) => {
+    if (typeof from !== "string" || typeof text !== "string") {
+      throw new Error("peer:message requires (from: string, text: string)");
+    }
+    const entry: InboxEntry = { from, text, at: Date.now() };
+    inbox.push(entry);
+    if (inbox.length > INBOX_MAX) inbox.splice(0, inbox.length - INBOX_MAX);
+    pending.push(entry);
+    bus.emit("peer:message-received", entry);
+    bus.emit("ui:info", { message: `[peer ${from}] ${text}` });
+    setTimeout(drainPending, 100);
+    return { ok: true };
+  });
+  server.expose("peer:message");
+
+  // Drain pending peer messages by injecting a synthetic user turn.
+  // Only one submission per processing cycle — wait for agent:processing-done
+  // before releasing the next batch.
+  let busy = false;
+
+  function drainPending(): void {
+    if (busy || pending.length === 0) return;
+    const batch = pending.splice(0, pending.length);
+    const lines = batch.map((e) => `[from peer ${e.from}] ${e.text}`);
+    const query = [
+      "You received message(s) from other peer(s) in the mesh:",
+      "",
+      ...lines,
+      "",
+      "Decide whether to reply (via `peer_send`), act on the request, or note and continue.",
+    ].join("\n");
+    busy = true;
+    bus.emit("agent:submit", { query });
+  }
+
+  bus.on("agent:processing-done", () => {
+    busy = false;
+    setTimeout(drainPending, 100);
+  });
+
   // ── Handler registry API (for other extensions) ────────────
 
   define("peer:discover", () => server.discover());
@@ -412,6 +460,71 @@ export default function activate(ctx: ExtensionContext): void {
     }),
   });
 
+  registerTool({
+    name: "peer_send",
+    description: "Send a text message to another running agent-sh peer. The peer will see it in their UI and on their next turn.",
+    input_schema: {
+      type: "object",
+      properties: {
+        peer_id: { type: "string", description: "The instance ID of the peer (from the peers tool)." },
+        text: { type: "string", description: "Message body." },
+      },
+      required: ["peer_id", "text"],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "write" as const }),
+    formatCall: (args) => `peer ${args.peer_id}: "${String(args.text).slice(0, 40)}"`,
+
+    async execute(args) {
+      try {
+        await server.call(args.peer_id as string, "peer:message", ctx.instanceId, args.text as string);
+        return { content: `Sent to peer ${args.peer_id}.`, exitCode: 0, isError: false };
+      } catch (e) {
+        return {
+          content: `Failed to send: ${e instanceof Error ? e.message : String(e)}`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.isError ? "failed" : "sent",
+    }),
+  });
+
+  registerTool({
+    name: "peer_inbox",
+    description: "Read recent messages received from other peers via peer_send.",
+    input_schema: {
+      type: "object",
+      properties: {
+        count: { type: "number", description: "Number of recent messages to return (default: 20)." },
+      },
+      required: [],
+    },
+    showOutput: false,
+    getDisplayInfo: () => ({ kind: "read" as const }),
+    formatCall: () => "reading inbox",
+
+    async execute(args) {
+      const n = (args.count as number) || 20;
+      const recent = inbox.slice(-n);
+      if (recent.length === 0) {
+        return { content: "(inbox empty)", exitCode: 0, isError: false };
+      }
+      const lines = recent.map((e) => {
+        const ago = Math.round((Date.now() - e.at) / 1000);
+        return `[${ago}s ago] ${e.from}: ${e.text}`;
+      });
+      return { content: lines.join("\n"), exitCode: 0, isError: false };
+    },
+
+    formatResult: (_args, result) => ({
+      summary: result.content === "(inbox empty)" ? "empty" : `${result.content.split("\n").length} msg`,
+    }),
+  });
+
   // ── Slash command ──────────────────────────────────────────
 
   registerCommand("peers", "List running agent-sh peer instances", () => {
@@ -435,6 +548,8 @@ export default function activate(ctx: ExtensionContext): void {
     "- `peer_terminal` to see what's on another terminal's screen",
     "- `peer_history` to see what commands they ran recently",
     "- `peer_search` to search their shell context by keyword",
+    "- `peer_send` to deliver a text message to another peer (appears in their UI)",
+    "- `peer_inbox` to read messages other peers have sent you",
     "When the user references 'the other terminal' or 'my other shell', use these tools.",
   ].join("\n"));
 

package/examples/extensions/pi-bridge/index.ts

@@ -23,8 +23,8 @@ import {
   SessionManager,
 } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import type { ExtensionContext } from "../../src/types.js";
-import type { EventBus } from "../../src/event-bus.js";
+import type { ExtensionContext } from "agent-sh/types";
+import type { EventBus } from "agent-sh/event-bus";
 
 // ── Helpers ──────────────────────────────────────────────────────
 function interpretEscapes(str: string): string {

package/examples/extensions/questionnaire.ts

@@ -55,15 +55,26 @@ interface QuestionnaireResult {
 
 // ── Extension ────────────────────────────────────────────────────
 
-export default function activate({ registerTool }: ExtensionContext) {
+export default function activate({ registerTool, registerInstruction }: ExtensionContext) {
+  registerInstruction("questionnaire", [
+    "# When to use the questionnaire tool",
+    "ALWAYS use the `questionnaire` tool instead of asking the user a question in plain text when:",
+    "- You need the user to choose from specific options (e.g. frameworks, approaches, yes/no decisions)",
+    "- You are unsure about a preference and can enumerate reasonable choices",
+    "- The user's answer determines a significant branch in your behavior",
+    "",
+    "Do NOT just list options in your reply prose — call the questionnaire tool so the user can select interactively.",
+    "This applies to single questions too (yes/no, pick-one).",
+  ].join("\n"));
+
   registerTool({
     name: "questionnaire",
     displayName: "questionnaire",
     description:
-      "Ask the user one or more questions with selectable options. " +
-      "Use for clarifying requirements, getting preferences, or confirming decisions. " +
-      "For single questions, shows a simple option list. " +
-      "For multiple questions, shows a tab-based interface.",
+      "Present the user with one or more questions with selectable options and wait for their interactive response. " +
+      "PREFER THIS over asking questions in plain text — it gives the user an interactive picker (arrow keys + enter). " +
+      "Use for: clarifying requirements, getting preferences, confirming decisions, choosing between options. " +
+      "Single question → simple option list. Multiple questions → tab-based multi-page interface.",
     input_schema: {
       type: "object",
       properties: {