agent-sh 0.9.0 → 0.10.1

package/dist/shell/input-handler.js

@@ -4,7 +4,7 @@ import { visibleLen } from "../utils/ansi.js";
 import { palette as p } from "../utils/palette.js";
 import { LineEditor } from "../utils/line-editor.js";
 import { CONFIG_DIR, getSettings } from "../settings.js";
-const HISTORY_FILE = path.join(CONFIG_DIR, "history");
+const HISTORY_FILE = path.join(CONFIG_DIR, "input-history");
 export class InputHandler {
     ctx;
     lineBuffer = "";
@@ -20,7 +20,8 @@ export class InputHandler {
     history = [];
     historyIndex = -1; // -1 = not browsing history
     savedBuffer = ""; // buffer saved when entering history
-    promptWrappedLines = 0; // extra lines from terminal wrapping
+    cursorRowsBelow = 0; // rows from prompt top to cursor row
+    cursorTermCol = 1; // 1-indexed terminal column of cursor
     escapeTimer = null;
     bus;
     onShowAgentInfo;
@@ -72,9 +73,10 @@ export class InputHandler {
     /** Write the mode prompt line with cursor at the correct position. */
     writeModePromptLine(showBuffer = true) {
         const termW = process.stdout.columns || 80;
-        // Move cursor to the start of the prompt area (first line of wrapped content)
-        if (this.promptWrappedLines > 0) {
-            process.stdout.write(`\x1b[${this.promptWrappedLines}A`);
+        // Move cursor to the start of the prompt area.
+        // We know exactly how many rows below the top the cursor currently sits.
+        if (this.cursorRowsBelow > 0) {
+            process.stdout.write(`\x1b[${this.cursorRowsBelow}A`);
         }
         // Clear from here to end of screen — removes current + all wrapped lines below
         process.stdout.write("\r\x1b[J");
@@ -88,37 +90,36 @@ export class InputHandler {
         const promptVisLen = visibleLen(infoPrefix) + visibleLen(icon) + 1; // icon + space
         const display = showBuffer ? this.editor.displayText : "";
         const dCursor = showBuffer ? this.editor.displayCursor : 0;
-        if (!showBuffer || !display.includes("\n")) {
-            // Single-line: simple rendering
-            const bufferText = showBuffer ? p.accent + display + p.reset : "";
-            process.stdout.write(promptPrefix + bufferText);
-            const bufferVisLen = display.length;
-            const totalVisLen = promptVisLen + bufferVisLen;
-            this.promptWrappedLines = totalVisLen > 0 ? Math.floor((totalVisLen - 1) / termW) : 0;
-            // Position cursor within the buffer
-            if (showBuffer && dCursor < display.length) {
-                const charsAfterCursor = display.length - dCursor;
-                process.stdout.write(`\x1b[${charsAfterCursor}D`);
-            }
+        if (!showBuffer) {
+            // No buffer — just write the prompt prefix, cursor stays at end
+            process.stdout.write(promptPrefix);
+            const N = promptVisLen;
+            this.cursorRowsBelow = N > 0 ? Math.ceil(N / termW) - 1 : 0;
+            this.cursorTermCol = N === 0 ? 1 : (N % termW === 0 ? termW : (N % termW) + 1);
+        }
+        else if (!display.includes("\n")) {
+            // Single-line: write up to cursor, save, write rest, restore.
+            // The terminal handles all wrapping — no manual row/col math needed.
+            const before = display.slice(0, dCursor);
+            const after = display.slice(dCursor);
+            process.stdout.write(promptPrefix + p.accent + before + p.reset +
+                "\x1b7" + // DECSC — save cursor position
+                p.accent + after + p.reset +
+                "\x1b8" // DECRC — restore cursor position
+            );
+            // 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 {
-            // Multi-line: render each line with continuation indent
+            // Multi-line: render each line with continuation indent.
+            // Same save/restore strategy — cursor position is never computed.
             const lines = display.split("\n");
             const indent = " ".repeat(promptVisLen);
-            let totalTermLines = 0;
-            for (let li = 0; li < lines.length; li++) {
-                const prefix = li === 0 ? promptPrefix : indent;
-                const prefixVisLen = li === 0 ? promptVisLen : promptVisLen;
-                const lineText = lines[li];
-                process.stdout.write(prefix + p.accent + lineText + p.reset);
-                if (li < lines.length - 1)
-                    process.stdout.write("\n");
-                // Count terminal lines this logical line occupies
-                const lineVisLen = prefixVisLen + lineText.length;
-                totalTermLines += lineVisLen > 0 ? Math.ceil(lineVisLen / termW) : 1;
-            }
-            this.promptWrappedLines = totalTermLines - 1;
-            // Position cursor: find which display line and column the cursor is on
+            // Locate cursor: which logical line and offset within it.
             let charsRemaining = dCursor;
             let cursorLine = 0;
             for (let li = 0; li < lines.length; li++) {
@@ -129,31 +130,37 @@ export class InputHandler {
                 charsRemaining -= lines[li].length + 1; // +1 for \n
                 cursorLine = li + 1;
             }
-            // Compute terminal rows for cursor positioning (not logical lines)
-            // Each logical line may wrap across multiple terminal rows.
-            const cursorColAbs = promptVisLen + charsRemaining;
-            const cursorTermRow = Math.floor(cursorColAbs / termW);
-            // Count terminal rows occupied by lines after cursor's logical line
-            let termRowsAfterCursor = 0;
-            for (let li = cursorLine + 1; li < lines.length; li++) {
-                const lineVisLen = promptVisLen + lines[li].length;
-                termRowsAfterCursor += lineVisLen > 0 ? Math.ceil(lineVisLen / termW) : 1;
-            }
-            // Also count remaining terminal rows on cursor's own logical line
-            const cursorLineVisLen = promptVisLen + lines[cursorLine].length;
-            const cursorLineTotalRows = cursorLineVisLen > 0 ? Math.ceil(cursorLineVisLen / termW) : 1;
-            const rowsAfterCursorInLine = cursorLineTotalRows - 1 - cursorTermRow;
-            const totalRowsFromEnd = termRowsAfterCursor + rowsAfterCursorInLine;
-            if (totalRowsFromEnd > 0) {
-                process.stdout.write(`\x1b[${totalRowsFromEnd}A`);
-            }
-            const cursorCol = cursorColAbs % termW;
-            if (cursorCol > 0) {
-                process.stdout.write(`\r\x1b[${cursorCol}C`);
-            }
-            else {
-                process.stdout.write(`\r`);
+            let output = "";
+            let cursorRowFromTop = 0;
+            let rowsSoFar = 0;
+            for (let li = 0; li < lines.length; li++) {
+                const prefix = li === 0 ? promptPrefix : indent;
+                const lineText = lines[li];
+                const lineVisLen = promptVisLen + visibleLen(lineText);
+                const lineTermRows = lineVisLen > 0 ? Math.ceil(lineVisLen / termW) : 1;
+                if (li === cursorLine) {
+                    // Split this line at the cursor.
+                    const before = lineText.slice(0, charsRemaining);
+                    const after = lineText.slice(charsRemaining);
+                    output += prefix + p.accent + before + p.reset;
+                    output += "\x1b7"; // DECSC — save cursor position
+                    output += p.accent + after + p.reset;
+                    const beforeVisCol = promptVisLen + visibleLen(before);
+                    cursorRowFromTop = rowsSoFar + (beforeVisCol > 0 ? Math.ceil(beforeVisCol / termW) - 1 : 0);
+                    this.cursorTermCol = beforeVisCol === 0 ? 1 : (beforeVisCol % termW === 0 ? termW : (beforeVisCol % termW) + 1);
+                }
+                else {
+                    output += prefix + p.accent + lineText + p.reset;
+                }
+                if (li < lines.length - 1)
+                    output += "\n";
+                rowsSoFar += lineTermRows;
             }
+            process.stdout.write(output + "\x1b8"); // DECRC — restore cursor position
+            // 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) {
@@ -281,15 +288,17 @@ export class InputHandler {
         // Disable kitty keyboard protocol and bracket paste mode
         process.stdout.write("\x1b[<u\x1b[?2004l");
         this.clearPromptArea();
+        this.cursorRowsBelow = 0;
+        this.cursorTermCol = 1;
         this.printPrompt();
     }
     /** Move to the start of the prompt area and clear everything below. */
     clearPromptArea() {
-        if (this.promptWrappedLines > 0) {
-            process.stdout.write(`\x1b[${this.promptWrappedLines}A`);
+        if (this.cursorRowsBelow > 0) {
+            process.stdout.write(`\x1b[${this.cursorRowsBelow}A`);
         }
         process.stdout.write("\r\x1b[J");
-        this.promptWrappedLines = 0;
+        this.cursorRowsBelow = 0;
     }
     printPrompt() {
         this.ctx.redrawPrompt();
@@ -363,16 +372,10 @@ export class InputHandler {
         if (this.autocompleteLines > 0) {
             process.stdout.write(`\x1b[${this.autocompleteLines}A`);
         }
-        // Reposition cursor: must match the layout in writeModePromptLine()
-        const agentInfo = this.onShowAgentInfo();
-        const indicator = this.activeMode?.indicator ?? "●";
-        const infoPrefix = agentInfo.info
-            ? `${agentInfo.info} ${indicator} `
-            : `${indicator} `;
-        const icon = this.activeMode?.promptIcon ?? "❯";
-        const promptVisLen = visibleLen(infoPrefix) + visibleLen(icon) + 1;
-        const col = promptVisLen + this.editor.displayCursor;
-        process.stdout.write(`\r\x1b[${col}C`);
+        // Restore cursor column — use explicit column set instead of DECRC
+        // because writing \n above may have scrolled the terminal, which
+        // invalidates the absolute position saved by DECSC.
+        process.stdout.write(`\x1b[${this.cursorTermCol}G`);
     }
     applyAutocomplete() {
         if (!this.autocompleteActive || this.autocompleteItems.length === 0)
@@ -407,11 +410,12 @@ export class InputHandler {
     clearAutocompleteLines() {
         if (this.autocompleteLines <= 0)
             return;
-        process.stdout.write("\x1b7"); // save cursor
+        // Use CSI B (cursor down, bounded) instead of \n to avoid scroll
         for (let i = 0; i < this.autocompleteLines; i++) {
-            process.stdout.write("\n\x1b[2K"); // move down, clear line
+            process.stdout.write("\x1b[B\x1b[2K"); // move down, clear line
         }
-        process.stdout.write("\x1b8"); // restore cursor
+        // Move back up and restore column with relative movement (scroll-safe)
+        process.stdout.write(`\x1b[${this.autocompleteLines}A\x1b[${this.cursorTermCol}G`);
         this.autocompleteLines = 0;
     }
     handleModeInput(data) {
@@ -475,13 +479,20 @@ export class InputHandler {
                     const currentMode = this.activeMode;
                     this.activeMode = null;
                     this.editor.clear();
+                    this.cursorRowsBelow = 0;
+                    this.cursorTermCol = 1;
                     this.dismissAutocomplete();
                     if (query && query.startsWith("/")) {
                         const spaceIdx = query.indexOf(" ");
                         const name = spaceIdx === -1 ? query : query.slice(0, spaceIdx);
                         const args = spaceIdx === -1 ? "" : query.slice(spaceIdx + 1).trim();
                         this.bus.emit("command:execute", { name, args });
-                        this.ctx.freshPrompt();
+                        if (currentMode.returnToSelf) {
+                            this.enterMode(currentMode);
+                        }
+                        else {
+                            this.ctx.freshPrompt();
+                        }
                     }
                     else if (query) {
                         this.pendingReturnMode = currentMode.returnToSelf ? currentMode.id : null;
@@ -510,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/shell/shell.js

@@ -197,6 +197,11 @@ export class Shell {
      * For bash, falls back to sending \n for a fresh prompt cycle.
      */
     redrawPrompt() {
+        // A stale echoSkip or paused flag (left over from handleProcessingDone
+        // re-entering a mode) would swallow the redrawn prompt and make the
+        // terminal appear frozen. Reset both before emitting.
+        this.echoSkip = false;
+        this.paused = false;
         const result = this.bus.emitPipe("shell:redraw-prompt", {
             cwd: this.outputParser.getCwd(),
             handled: false,
@@ -277,9 +282,13 @@ export class Shell {
             this.paused = true;
         });
         this.handlers.define("shell:on-processing-done", () => {
-            this.paused = false;
             this.agentActive = false;
+            // If handleProcessingDone re-entered a mode, leave stdout paused so
+            // stale PTY output doesn't overwrite the mode prompt (exitMode →
+            // redrawPrompt will unpause). Setting echoSkip here would swallow
+            // that PTY output since no \n was sent.
             if (!this.inputHandler.handleProcessingDone()) {
+                this.paused = false;
                 if (this.freshPrompt()) {
                     this.echoSkip = true;
                 }
@@ -317,11 +326,19 @@ export class Shell {
                 const handler = (e) => {
                     clearTimeout(timeout);
                     this.bus.off("shell:command-done", handler);
+                    // Re-pause stdout so the prompt text following the marker doesn't
+                    // leak to the terminal while the agent is still processing.
+                    this.paused = true;
                     resolve({ output: e.output, cwd: e.cwd, exitCode: e.exitCode });
                 };
                 this.bus.on("shell:command-done", handler);
                 this.outputParser.onCommandEntered(payload.command, this.outputParser.getCwd());
-                this.ptyProcess.write(payload.command + "\r");
+                // Collapse literal newlines to spaces so the PTY receives a single-line
+                // command. Multi-line commands (e.g. git commit -m "...\n...") would
+                // cause the shell to execute prematurely, producing garbled output from
+                // syntax highlighting plugins (zsh syntax highlighting, etc).
+                const oneLine = payload.command.replace(/\n/g, " ");
+                this.ptyProcess.write(oneLine + "\r");
             });
             this.paused = true;
             this.echoSkip = false;

package/dist/types.d.ts

@@ -80,6 +80,12 @@ export interface ExtensionContext {
     createFencedBlockTransform: (opts: FencedBlockTransformOptions) => void;
     /** Read extension-namespaced settings from ~/.agent-sh/settings.json. */
     getExtensionSettings: <T extends Record<string, unknown>>(namespace: string, defaults: T) => T;
+    /**
+     * Get (and lazily create) a per-extension storage directory under
+     * ~/.agent-sh/<namespace>/. Returns the absolute path. Lets extensions
+     * persist state without each one re-deriving the location.
+     */
+    getStoragePath: (namespace: string) => string;
     /** Register a slash command available in any input mode. */
     registerCommand: (name: string, description: string, handler: (args: string) => Promise<void> | void) => void;
     /** Register a tool for the built-in agent. No-op when using bridge backends. */
@@ -92,12 +98,18 @@ export interface ExtensionContext {
     registerInstruction: (name: string, text: string) => void;
     /** Remove a named instruction block from the system prompt. */
     removeInstruction: (name: string) => void;
+    /** Register a skill (on-demand reference material) for the agent. */
+    registerSkill: (name: string, description: string, filePath: string) => void;
+    /** Remove a registered skill by name. */
+    removeSkill: (name: string) => void;
     /** Register a named handler. */
     define: (name: string, fn: (...args: any[]) => any) => void;
     /** Wrap a named handler. Receives `next` (original) + args. Returns an unadvise function. */
     advise: (name: string, wrapper: (next: (...args: any[]) => any, ...args: any[]) => any) => () => void;
     /** Call a named handler. */
     call: (name: string, ...args: any[]) => any;
+    /** Names of all registered handlers — for diagnostic / introspection use. */
+    list: () => string[];
     /**
      * Shared headless terminal buffer mirroring PTY output.
      * Lazily created on first access. Returns null if @xterm/headless is not installed.
@@ -146,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

@@ -6,6 +6,13 @@ export declare const RED = "\u001B[31m";
 export declare const GRAY = "\u001B[90m";
 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, 0 for combining chars.
+ *
+ * Based on East Asian Width and Unicode categories.
+ */
+export declare function charWidth(codePoint: number): number;
 /**
  * Measure visible string length in terminal columns.
  * Excludes SGR (color/style) sequences and accounts for CJK double-width chars.

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.
  */
-function charWidth(codePoint) {
+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 @@ 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/compositor.d.ts

@@ -24,6 +24,7 @@
  *   compositor.redirect("agent:diff", diffPanelSurface);
  *   // "agent:text", "agent:tool" etc. still go to stdout
  */
+import type { EventBus } from "../event-bus.js";
 /**
  * A surface accepts rendered output.  Stdout is a surface.
  * A floating panel's content area is a surface.  A test buffer is a surface.
@@ -56,7 +57,11 @@ export declare class StdoutSurface implements RenderSurface {
 export declare class DefaultCompositor implements Compositor {
     private defaults;
     private overrides;
+    private readonly bus?;
+    constructor(bus?: EventBus);
     surface(stream: string): RenderSurface;
     redirect(stream: string, target: RenderSurface): () => void;
     setDefault(stream: string, target: RenderSurface): void;
+    /** Wrap a surface so writes emit `compositor:write` before delegating. */
+    private wrap;
 }

package/dist/utils/compositor.js

@@ -50,6 +50,10 @@ export class StdoutSurface {
 export class DefaultCompositor {
     defaults = new Map();
     overrides = new Map();
+    bus;
+    constructor(bus) {
+        this.bus = bus;
+    }
     surface(stream) {
         const stack = this.overrides.get(stream);
         if (stack && stack.length > 0)
@@ -63,12 +67,13 @@ export class DefaultCompositor {
         return nullSurface;
     }
     redirect(stream, target) {
+        const wrapped = this.wrap(stream, target);
         let stack = this.overrides.get(stream);
         if (!stack) {
             stack = [];
             this.overrides.set(stream, stack);
         }
-        stack.push(target);
+        stack.push(wrapped);
         let restored = false;
         return () => {
             if (restored)
@@ -77,12 +82,35 @@ export class DefaultCompositor {
             const s = this.overrides.get(stream);
             if (!s)
                 return;
-            const idx = s.indexOf(target);
+            const idx = s.indexOf(wrapped);
             if (idx !== -1)
                 s.splice(idx, 1);
         };
     }
     setDefault(stream, target) {
-        this.defaults.set(stream, target);
+        this.defaults.set(stream, this.wrap(stream, target));
+    }
+    /** Wrap a surface so writes emit `compositor:write` before delegating. */
+    wrap(stream, target) {
+        const bus = this.bus;
+        if (!bus)
+            return target;
+        return {
+            write: (text) => {
+                try {
+                    bus.emit("compositor:write", { stream, text });
+                }
+                catch { }
+                target.write(text);
+            },
+            writeLine: (line) => {
+                try {
+                    bus.emit("compositor:write", { stream, text: line + "\n" });
+                }
+                catch { }
+                target.writeLine(line);
+            },
+            get columns() { return target.columns; },
+        };
     }
 }

package/dist/utils/diff-renderer.d.ts

@@ -18,3 +18,12 @@ export interface DiffRenderOptions {
 export declare function selectMode(width: number): DiffDisplayMode;
 /** Render a diff result as an array of ANSI-formatted terminal lines. */
 export declare function renderDiff(diff: DiffResult, opts: DiffRenderOptions): string[];
+/**
+ * Async variant of renderDiff that yields to the event loop between hunks.
+ * Use when rendering in a context where a spinner or other UI needs to stay
+ * responsive (e.g. showing a large diff during a permission prompt).
+ *
+ * @param onLines - Callback invoked with each batch of rendered lines as they
+ *                  are produced. Allows progressive/streaming display.
+ */
+export declare function renderDiffAsync(diff: DiffResult, opts: DiffRenderOptions, onLines: (lines: string[]) => void): Promise<void>;