agent-sh 0.10.0 → 0.10.1

package/dist/extensions/index.js

@@ -3,7 +3,6 @@ export const BUILTIN_EXTENSIONS = [
     { name: "tui-renderer", load: () => import("./tui-renderer.js").then(m => m.default) },
     { name: "slash-commands", load: () => import("./slash-commands.js").then(m => m.default) },
     { name: "file-autocomplete", load: () => import("./file-autocomplete.js").then(m => m.default) },
-    { name: "shell-recall", load: () => import("./shell-recall.js").then(m => m.default) },
     { name: "command-suggest", load: () => import("./command-suggest.js").then(m => m.default) },
 ];
 /**

package/dist/extensions/tui-renderer.js

@@ -74,8 +74,11 @@ export default function activate(ctx) {
     bus.on("shell:cwd-change", (e) => { shellCwd = e.cwd; });
     /** Shorthand — get the current agent surface. */
     function out() { return compositor.surface("agent"); }
-    /** Capped width for borders, tool lines, and content — keeps everything aligned. */
-    function cappedW() { return Math.min(MAX_CONTENT_WIDTH + 2, out().columns); }
+    /** Capped width for borders, tool lines, and content — keeps everything aligned.
+     *  MarkdownRenderer.writeLine prepends a 2-char indent ("  ") to every line,
+     *  so available width for actual content is columns - 2.  Subtract an additional
+     *  1 to prevent terminal auto-wrap when a line lands exactly at the right edge. */
+    function cappedW() { return Math.min(MAX_CONTENT_WIDTH + 2, out().columns) - 2 - 1; }
     // Gate: other extensions (e.g. overlay) can advise this to suppress
     // TUI rendering of agent output while they own the display.
     define("tui:should-render-agent", () => true);

package/dist/settings.d.ts

@@ -32,20 +32,12 @@ export interface Settings {
     defaultProvider?: string;
     /** Preferred agent backend (extension name, e.g. "pi", "claude-code"). */
     defaultBackend?: string;
-    /** Recent exchanges included in agent context window. */
-    contextWindowSize?: number;
-    /** Context budget in bytes (~4 chars per token). */
-    contextBudget?: number;
-    /** Shell output lines before truncation kicks in. */
+    /** Shell output lines before spill-to-tempfile kicks in. */
     shellTruncateThreshold?: number;
-    /** Lines kept from start of truncated shell output. */
+    /** Lines kept from start of spilled shell output. */
     shellHeadLines?: number;
-    /** Lines kept from end of truncated shell output. */
+    /** Lines kept from end of spilled shell output. */
     shellTailLines?: number;
-    /** Max lines for recall expand before requiring line ranges. */
-    recallExpandMaxLines?: number;
-    /** Fraction of content budget allocated to shell context (0-1, default 0.35). */
-    shellContextRatio?: number;
     /** Max history file size in bytes (default: 102400 = 100KB). */
     historyMaxBytes?: number;
     /** Number of prior history entries to load on startup (default: 50). */

package/dist/settings.js

@@ -16,13 +16,9 @@ const DEFAULTS = {
     defaultProvider: undefined,
     defaultBackend: "ash",
     toolMode: "api",
-    contextWindowSize: 20,
-    contextBudget: 32768,
     shellTruncateThreshold: 20,
     shellHeadLines: 10,
     shellTailLines: 10,
-    recallExpandMaxLines: 500,
-    shellContextRatio: 0.35,
     historyMaxBytes: 104857600, // 100MB — history is only accessed via search/expand, never loaded wholesale
     historyStartupEntries: 100,
     autoCompactThreshold: 0.5,

package/dist/shell/input-handler.js

@@ -107,11 +107,11 @@ export class InputHandler {
                 p.accent + after + p.reset +
                 "\x1b8" // DECRC — restore cursor position
             );
-            // Clearing on next redraw needs total rows, so measure the full
-            // content width — not just up to the cursor.
-            const totalVisLen = promptVisLen + visibleLen(display);
-            this.cursorRowsBelow = totalVisLen > 0 ? Math.ceil(totalVisLen / termW) - 1 : 0;
+            // cursorRowsBelow is distance from cursor (restored by DECRC, sitting at
+            // the cursor col) back up to the prompt's top row. Next redraw uses it
+            // with \x1b[${n}A then \x1b[J — moving past the top scrolls the screen.
             const cursorVisCol = promptVisLen + visibleLen(before);
+            this.cursorRowsBelow = cursorVisCol > 0 ? Math.ceil(cursorVisCol / termW) - 1 : 0;
             this.cursorTermCol = cursorVisCol === 0 ? 1 : (cursorVisCol % termW === 0 ? termW : (cursorVisCol % termW) + 1);
         }
         else {
@@ -157,8 +157,10 @@ export class InputHandler {
                 rowsSoFar += lineTermRows;
             }
             process.stdout.write(output + "\x1b8"); // DECRC — restore cursor position
-            // Total rows (not cursor row) so next redraw clears the whole area.
-            this.cursorRowsBelow = rowsSoFar - 1 > 0 ? rowsSoFar - 1 : 0;
+            // Distance from cursor (where DECRC lands) back to the top row. Next
+            // redraw moves up by this and clears to end-of-screen — \x1b[J handles
+            // everything below, including rows after the cursor's logical line.
+            this.cursorRowsBelow = cursorRowFromTop;
         }
     }
     handleInput(data) {
@@ -519,9 +521,6 @@ export class InputHandler {
                         this.applyAutocomplete();
                     }
                     break;
-                case "shift+tab":
-                    this.bus.emit("config:cycle", {});
-                    break;
                 case "arrow-up":
                     if (this.autocompleteActive) {
                         this.autocompleteIndex =

package/dist/types.d.ts

@@ -158,12 +158,15 @@ export type Exchange = {
     timestamp: number;
     cwd: string;
     command: string;
+    /** In-context representation: full text if short, head+tail+path stub if spilled. */
     output: string;
     exitCode: number | null;
     outputLines: number;
     outputBytes: number;
     /** Who initiated this command: "user" (typed) or "agent" (via user_shell). */
     source: "user" | "agent";
+    /** Path to the tempfile holding the full captured output, if spilled. */
+    spillPath?: string;
 } | {
     type: "agent_query";
     id: number;

package/dist/utils/ansi.d.ts

@@ -8,7 +8,9 @@ export declare const BOLD = "\u001B[1m";
 export declare const RESET = "\u001B[0m";
 /**
  * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
- * Returns 2 for wide chars, 1 for normal chars.
+ * Returns 2 for wide chars, 1 for normal chars, 0 for combining chars.
+ *
+ * Based on East Asian Width and Unicode categories.
  */
 export declare function charWidth(codePoint: number): number;
 /**

package/dist/utils/ansi.js

@@ -10,9 +10,54 @@ export const RESET = "\x1b[0m";
 // ── ANSI utility functions ───────────────────────────────────
 /**
  * Check if a Unicode code point is a wide character (CJK, fullwidth, emoji, etc.)
- * Returns 2 for wide chars, 1 for normal chars.
+ * Returns 2 for wide chars, 1 for normal chars, 0 for combining chars.
+ *
+ * Based on East Asian Width and Unicode categories.
  */
 export function charWidth(codePoint) {
+    // Combining characters (zero width)
+    if (codePoint >= 0x0300 && codePoint <= 0x036f)
+        return 0; // Combining Diacritical Marks
+    if (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
+        return 0; // Combining Diacritical Marks Extended
+    if (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
+        return 0; // Combining Diacritical Marks Supplement
+    if (codePoint >= 0x20d0 && codePoint <= 0x20ff)
+        return 0; // Combining Diacritical Marks for Symbols
+    if (codePoint >= 0xfe20 && codePoint <= 0xfe2f)
+        return 0; // Combining Half Marks
+    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
+        return 0; // Variation Selectors
+    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+        return 0; // Variation Selectors Supplement
+    // Emoji and symbols that render as wide (2 columns)
+    // Emoji presentation sequences and keycap
+    if (codePoint === 0x20e3)
+        return 2; // Combining Enclosing Keycap
+    // Emoji blocks
+    if (codePoint >= 0x1f600 && codePoint <= 0x1f64f)
+        return 2; // Emoticons
+    if (codePoint >= 0x1f300 && codePoint <= 0x1f5ff)
+        return 2; // Misc Symbols and Pictographs
+    if (codePoint >= 0x1f680 && codePoint <= 0x1f6ff)
+        return 2; // Transport and Map
+    if (codePoint >= 0x1f700 && codePoint <= 0x1f77f)
+        return 2; // Alchemical Symbols
+    if (codePoint >= 0x1f780 && codePoint <= 0x1f7ff)
+        return 2; // Geometric Shapes Extended
+    if (codePoint >= 0x1f800 && codePoint <= 0x1f8ff)
+        return 2; // Supplemental Arrows-C
+    if (codePoint >= 0x1f900 && codePoint <= 0x1f9ff)
+        return 2; // Supplemental Symbols and Pictographs
+    if (codePoint >= 0x1fa00 && codePoint <= 0x1faff)
+        return 2; // Chess Symbols, Symbols and Pictographs Extended-A
+    // NOTE: 0x2300-0x23ff (Misc Technical), 0x2600-0x26ff (Misc Symbols),
+    // and 0x2700-0x27bf (Dingbats) are intentionally NOT width 2 — these ranges
+    // contain mostly "Ambiguous" width characters that render as 1 column in
+    // non-CJK terminal locales (e.g. ❯, ⌘, ★, ♦).
+    // Regional indicator symbols (flag emoji components)
+    if (codePoint >= 0x1f1e6 && codePoint <= 0x1f1ff)
+        return 2;
     // CJK Unified Ideographs
     if (codePoint >= 0x4e00 && codePoint <= 0x9fff)
         return 2;
@@ -28,7 +73,6 @@ export function charWidth(codePoint) {
     // Fullwidth ASCII variants
     if (codePoint >= 0xff01 && codePoint <= 0xff5e)
         return 2;
-    // Halfwidth Katakana (actually narrow, skip)
     // Fullwidth bracket forms
     if (codePoint >= 0xff5f && codePoint <= 0xff60)
         return 2;
@@ -76,18 +120,35 @@ export function visibleLen(str) {
  */
 export function truncateToWidth(str, maxWidth) {
     const clean = str.replace(/\x1b\[[^m]*m/g, "");
+    if (maxWidth <= 0)
+        return "";
+    // First check if the entire string fits
+    let fullWidth = 0;
+    for (const char of clean) {
+        fullWidth += charWidth(char.codePointAt(0) ?? 0);
+    }
+    if (fullWidth <= maxWidth)
+        return clean;
+    // String doesn't fit — truncate with "…"
+    // At maxWidth=1 the ellipsis alone fills the budget.
+    if (maxWidth === 1)
+        return "…";
+    // Reserve 1 column for "…", so target content width is maxWidth - 1
+    const target = maxWidth - 1;
     let width = 0;
     let i = 0;
     for (const char of clean) {
         const cw = charWidth(char.codePointAt(0) ?? 0);
-        if (width + cw > maxWidth - 1) {
-            // Need room for the "…" (1 column wide)
-            return clean.slice(0, i) + "…";
-        }
+        if (width + cw > target)
+            break;
         width += cw;
         i += char.length;
     }
-    return clean;
+    // If nothing fit (first char is wider than target), just show the ellipsis
+    // rather than emit a character that would overflow the budget.
+    if (i === 0)
+        return "…";
+    return clean.slice(0, i) + "…";
 }
 /**
  * Pad a string with spaces to fill `targetWidth` visible columns.

package/dist/utils/box-frame.js

@@ -5,7 +5,7 @@
  * never writes to stdout. Supports multiple border styles and
  * optional title/footer sections with dividers.
  */
-import { visibleLen } from "./ansi.js";
+import { visibleLen, truncateToWidth } from "./ansi.js";
 import { palette as p } from "./palette.js";
 const BORDERS = {
     rounded: { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│", ml: "├", mr: "┤" },
@@ -63,6 +63,12 @@ export function renderBoxFrame(content, opts) {
 }
 // ── Helpers ──────────────────────────────────────────────────────
 function boxLine(text, innerW, v, bc) {
-    const pad = Math.max(0, innerW - visibleLen(text));
+    const textWidth = visibleLen(text);
+    if (textWidth > innerW) {
+        // Content is too wide — truncate to fit exactly
+        const truncated = truncateToWidth(text, innerW);
+        return `${bc}${v}${p.reset} ${truncated} ${bc}${v}${p.reset}`;
+    }
+    const pad = innerW - textWidth;
     return `${bc}${v}${p.reset} ${text}${" ".repeat(pad)} ${bc}${v}${p.reset}`;
 }

package/dist/utils/markdown.js

@@ -1,4 +1,4 @@
-import { visibleLen, truncateToWidth, padEndToWidth } from "./ansi.js";
+import { visibleLen, truncateToWidth, padEndToWidth, charWidth } from "./ansi.js";
 import { palette as p } from "./palette.js";
 export const MAX_CONTENT_WIDTH = 90;
 /**
@@ -33,16 +33,31 @@ export function wrapLine(text, maxWidth) {
         for (const word of words) {
             if (word.length === 0)
                 continue;
-            if (currentWidth + word.length <= maxWidth) {
+            const wordWidth = visibleLen(word);
+            if (currentWidth + wordWidth <= maxWidth) {
                 currentLine += word;
-                currentWidth += word.length;
+                currentWidth += wordWidth;
             }
             else if (currentWidth === 0) {
-                // Single word longer than maxWidth — hard break
+                // Single word longer than maxWidth — hard break by visible width
                 let remaining = word;
                 while (remaining.length > 0) {
-                    const chunk = remaining.slice(0, maxWidth - currentWidth || maxWidth);
-                    remaining = remaining.slice(chunk.length);
+                    // Find the largest prefix that fits
+                    let fitLen = 0;
+                    let fitWidth = 0;
+                    for (const ch of remaining) {
+                        const cw = charWidth(ch.codePointAt(0) ?? 0);
+                        if (fitWidth + cw > maxWidth)
+                            break;
+                        fitWidth += cw;
+                        fitLen += ch.length;
+                    }
+                    if (fitLen === 0) {
+                        // Even one char doesn't fit — force take one char to avoid infinite loop
+                        fitLen = remaining[0]?.length ?? 1;
+                    }
+                    const chunk = remaining.slice(0, fitLen);
+                    remaining = remaining.slice(fitLen);
                     currentLine += chunk;
                     if (remaining.length > 0) {
                         result.push(currentLine + p.reset);
@@ -50,7 +65,7 @@ export function wrapLine(text, maxWidth) {
                         currentWidth = 0;
                     }
                     else {
-                        currentWidth += chunk.length;
+                        currentWidth += fitWidth;
                     }
                 }
             }
@@ -62,7 +77,7 @@ export function wrapLine(text, maxWidth) {
                 // Skip leading spaces on new line
                 const trimmed = word.replace(/^ +/, "");
                 currentLine += trimmed;
-                currentWidth = trimmed.length;
+                currentWidth = visibleLen(trimmed);
             }
         }
     }

package/dist/utils/package-version.d.ts

@@ -0,0 +1 @@
+export declare const PACKAGE_VERSION: string;

package/dist/utils/package-version.js

@@ -0,0 +1,10 @@
+/**
+ * The agent-sh package version, read from package.json at load time.
+ * Emitted on `agent:info` so consumers (TUI, remote peers, logs) see a
+ * version that tracks releases instead of a hand-edited constant.
+ */
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+// dist/utils/package-version.js → ../../package.json (project root)
+const pkg = require("../../package.json");
+export const PACKAGE_VERSION = pkg.version ?? "0.0.0";

package/dist/utils/shell-output-spill.d.ts

@@ -0,0 +1,2 @@
+export declare function getSessionDir(): string;
+export declare function spillOutput(id: number, text: string): string;

package/dist/utils/shell-output-spill.js

@@ -0,0 +1,81 @@
+/**
+ * Spill long shell outputs to per-session tempfiles.
+ *
+ * Captured PTY output that exceeds the truncation threshold is written to
+ * `<tmpdir>/agent-sh-<pid>/<id>.out`. The in-memory exchange keeps only a
+ * head+tail stub pointing at that path, so the agent can fetch the full
+ * text via `read_file` on demand. The session dir is removed on process
+ * exit; stale dirs from dead processes are swept lazily on first use.
+ */
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const DIR_PREFIX = "agent-sh-";
+let sessionDir = null;
+let cleanupRegistered = false;
+export function getSessionDir() {
+    if (sessionDir)
+        return sessionDir;
+    sessionDir = join(tmpdir(), `${DIR_PREFIX}${process.pid}`);
+    mkdirSync(sessionDir, { recursive: true });
+    sweepStaleDirs();
+    if (!cleanupRegistered) {
+        cleanupRegistered = true;
+        const cleanup = () => {
+            if (!sessionDir)
+                return;
+            try {
+                rmSync(sessionDir, { recursive: true, force: true });
+            }
+            catch { }
+            sessionDir = null;
+        };
+        process.on("exit", cleanup);
+        for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+            process.on(sig, () => { cleanup(); process.exit(128); });
+        }
+    }
+    return sessionDir;
+}
+export function spillOutput(id, text) {
+    const path = join(getSessionDir(), `${id}.out`);
+    writeFileSync(path, text);
+    return path;
+}
+function sweepStaleDirs() {
+    const base = tmpdir();
+    let entries;
+    try {
+        entries = readdirSync(base);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!name.startsWith(DIR_PREFIX))
+            continue;
+        const pid = Number(name.slice(DIR_PREFIX.length));
+        if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
+            continue;
+        if (isProcessAlive(pid))
+            continue;
+        const full = join(base, name);
+        try {
+            // Small safety check: only remove directories.
+            if (statSync(full).isDirectory()) {
+                rmSync(full, { recursive: true, force: true });
+            }
+        }
+        catch { }
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // ESRCH = no such process; EPERM = exists but we can't signal it
+        return e.code === "EPERM";
+    }
+}

package/examples/extensions/claude-code-bridge/README.md

@@ -33,3 +33,17 @@ Or switch at runtime:
 
 - `ANTHROPIC_API_KEY` must be set in your environment
 - Claude Code manages its own model selection — no model configuration needed in agent-sh
+
+## What this bridge is
+
+A pure protocol translator between the Claude Agent SDK's event stream and agent-sh's bus events. Claude Code uses its own built-in tools exactly as the SDK ships them (`Read`, `Edit`, `Write`, `Bash`, `Glob`, `Grep`). The bridge adds no tools of its own.
+
+## What this bridge intentionally does NOT bundle
+
+Three PTY-access tools are left out on purpose:
+
+- `terminal_read` — observe the user's live terminal screen
+- `terminal_keys` — send keystrokes to the user's PTY
+- `user_shell` — run commands in the user's live shell with lasting `cd`/`export`/`source` effects
+
+These are opt-in capabilities that belong in their own extensions. If you want any of them with Claude Code, write a companion extension that uses the SDK's `tool()` + `createSdkMcpServer()` to expose them as MCP tools, and extend the bridge (or fork it) to attach that MCP server to the SDK's `query()` options.

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

@@ -2,8 +2,14 @@
  * 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 custom MCP tools for PTY access. Claude Code
- * handles its own model selection, tool execution, and permissions.
+ * session. Claude Code handles its own model selection, tool execution, and
+ * permissions — the bridge is a pure protocol translator between the SDK's
+ * event stream and agent-sh's bus events.
+ *
+ * PTY-access tools (`terminal_read`, `terminal_keys`, `user_shell`) are
+ * intentionally NOT bundled here. If you want Claude Code to observe or
+ * drive the user's live terminal, load a companion extension that
+ * registers those tools as MCP tools the SDK can consume.
  *
  * Setup (from repo root):
  *   npm run build && npm link                    # register local agent-sh globally
@@ -15,103 +21,16 @@
  *
  * Requires: Claude Code CLI installed and authenticated (claude login).
  */
-import {
-  query,
-  tool,
-  createSdkMcpServer,
-  type Query,
-} from "@anthropic-ai/claude-agent-sdk";
-import { z } from "zod";
+import { query, type Query } from "@anthropic-ai/claude-agent-sdk";
 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 {
-  return str.replace(/\\(x[0-9a-fA-F]{2}|r|n|t|\\|0)/g, (_, seq: string) => {
-    if (seq === "r") return "\r";
-    if (seq === "n") return "\n";
-    if (seq === "t") return "\t";
-    if (seq === "\\") return "\\";
-    if (seq === "0") return "\0";
-    if (seq.startsWith("x")) return String.fromCharCode(parseInt(seq.slice(1), 16));
-    return seq;
-  });
-}
-
-function settle(ms = 100): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// ── terminal_read MCP tool ────────────────────────────────────────
-function createTerminalReadTool(ctx: ExtensionContext) {
-  return tool(
-    "terminal_read",
-    "Read the current terminal screen contents. Returns clean text (ANSI stripped) " +
-    "with cursor position and whether an alternate-screen program (vim, htop, less) is active. " +
-    "Use this to see what the user sees before sending keystrokes with terminal_keys.",
-    {},
-    async () => {
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text" as const, text: "terminal buffer not available" }] };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text" as const, text: `[${info}]\n\n${text}` }] };
-    },
-  );
-}
-
-// ── terminal_keys MCP tool ───────────────────────────────────────
-function createTerminalKeysTool(bus: EventBus, ctx: ExtensionContext) {
-  return tool(
-    "terminal_keys",
-    "Send keystrokes to the user's live terminal. The keys are written directly to the PTY " +
-    "as if the user typed them. Use escape sequences for special keys:\n" +
-    "  - Escape: \\x1b  - Enter: \\r  - Tab: \\t\n" +
-    "  - Ctrl+C: \\x03  - Arrow keys: \\x1b[A/B/C/D  - Backspace: \\x7f\n" +
-    "Example: to quit vim without saving, send keys=\"\\x1b:q!\\r\".\n" +
-    "Always call terminal_read after sending keys to verify the result.",
-    {
-      keys: z.string().describe("Keystrokes to send (use \\x1b for Escape, \\r for Enter, etc.)"),
-      settle_ms: z.number().optional().describe("Wait time in ms after sending keys (default: 150)"),
-    },
-    async (args) => {
-      const keys = interpretEscapes(args.keys);
-      const settleMs = args.settle_ms ?? 150;
-      bus.emit("shell:stdout-show", {});
-      process.stdout.write("\n");
-      bus.emit("shell:pty-write", { data: keys });
-      await settle(settleMs);
-
-      const tb = ctx.terminalBuffer;
-      if (!tb) return { content: [{ type: "text" as const, text: "Keys sent." }] };
-      const { text, altScreen, cursorX, cursorY } = tb.readScreen();
-      const info = [
-        altScreen ? "mode: alternate screen" : "mode: normal",
-        `cursor: row=${cursorY} col=${cursorX}`,
-      ].join(", ");
-      return { content: [{ type: "text" as const, text: `Keys sent. Screen after:\n[${info}]\n\n${text}` }] };
-    },
-  );
-}
-
 // ── Extension entry point ─────────────────────────────────────────
 export default function activate(ctx: ExtensionContext): void {
   const { bus } = ctx;
 
-  const termReadTool = createTerminalReadTool(ctx);
-  const termKeysTool = createTerminalKeysTool(bus, ctx);
-  const shellServer = createSdkMcpServer({
-    name: "agent-sh",
-    version: "1.0.0",
-    tools: [termReadTool, termKeysTool],
-  });
-
   let activeQuery: Query | null = null;
   const listeners: Array<{ event: string; fn: Function }> = [];
 
@@ -119,11 +38,11 @@ export default function activate(ctx: ExtensionContext): void {
 
   /** 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 === "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";
+    if (name === "Bash") return "execute";
     return "execute";
   }
 
@@ -150,7 +69,6 @@ export default function activate(ctx: ExtensionContext): void {
     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;
   }
 
@@ -180,15 +98,9 @@ export default function activate(ctx: ExtensionContext): void {
               preset: "claude_code",
               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__terminal_read and mcp__agent-sh__terminal_keys to observe and interact with the user's live terminal.",
+                "Use your standard tools (Read, Edit, Write, Bash, Glob, Grep) for investigation.",
             },
-            mcpServers: { "agent-sh": shellServer },
-            allowedTools: [
-              "mcp__agent-sh__terminal_read",
-              "mcp__agent-sh__terminal_keys",
-              "Read", "Edit", "Write", "Bash", "Glob", "Grep",
-            ],
+            allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
             permissionMode: "acceptEdits",
             includePartialMessages: true,
           },

package/examples/extensions/pi-bridge/README.md

@@ -33,3 +33,19 @@ Or switch at runtime:
 
 - pi must be configured separately (`~/.pi/settings.json`) with API keys and model preferences
 - agent-sh does not override pi's configuration — it uses whatever pi is set up with
+
+## What this bridge is
+
+A pure protocol translator between pi's event stream and agent-sh's bus events. Pi's built-in tools (command execution, file ops, etc.) are used exactly as pi ships them. The bridge adds no tools of its own.
+
+## What this bridge intentionally does NOT bundle
+
+Three PTY-access tools are left out on purpose:
+
+- `terminal_read` — observe the user's live terminal screen
+- `terminal_keys` — send keystrokes to the user's PTY
+- `user_shell` — run commands in the user's live shell with lasting `cd`/`export`/`source` effects
+
+These are opt-in capabilities that belong in their own extensions. If you want any of them with pi, write a small companion extension that registers the tool as a pi `ToolDefinition` (TypeBox schema, wired to the relevant bus event: `shell:pty-write`, `shell:exec-request`, or `ctx.terminalBuffer.readScreen()`) and load it alongside pi-bridge.
+
+Keeping this split means the bridge stays narrow — only translating events — and the capability surface is composable per-backend.