agent-sh 0.12.22 → 0.12.23

package/dist/core.js

@@ -204,9 +204,11 @@ export function createCore(config) {
                     cleanups.push(compositor.redirect("agent", surface));
                     cleanups.push(compositor.redirect("query", surface));
                     cleanups.push(compositor.redirect("status", surface));
-                    // Keep shell interactive
+                    // Suppress the host shell's mute lifecycle and post-turn
+                    // redraw nudge. on-processing-done is intentionally not advised
+                    // — its scope cleanup must always run.
                     cleanups.push(handlers.advise("shell:on-processing-start", (next) => active ? undefined : next()));
-                    cleanups.push(handlers.advise("shell:on-processing-done", (next) => active ? undefined : next()));
+                    cleanups.push(handlers.advise("shell:on-processing-redraw", (next) => active ? undefined : next()));
                     // Suppress chrome
                     if (opts.suppressBorders !== false) {
                         cleanups.push(handlers.advise("tui:response-border", (next, ...a) => active ? null : next(...a)));

package/dist/event-bus.d.ts

@@ -214,6 +214,7 @@ export interface ShellEvents {
     };
     "shell:redraw-prompt": {
         cwd: string;
+        kind: "fresh" | "redraw";
         handled: boolean;
     };
     "shell:exec-request": {

package/dist/executor.js

@@ -1,5 +1,13 @@
 import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { stripAnsi } from "./utils/ansi.js";
+// Node reports a missing cwd as `spawn <binary> ENOENT` — disambiguate.
+function explainSpawnError(err, cwd) {
+    if (err.code === "ENOENT" && !existsSync(cwd)) {
+        return `cwd no longer exists: ${cwd} (${err.message})`;
+    }
+    return err.message;
+}
 let cachedBashPath;
 /** Resolve a usable bash binary, or null if none is on PATH.
  *  Unix: `/bin/bash` (canonical, present on every Linux/macOS install).
@@ -60,7 +68,10 @@ export function executeCommand(opts) {
     catch (err) {
         session.exitCode = -1;
         session.spawnFailed = true;
-        session.output = `Failed to spawn: ${err instanceof Error ? err.message : String(err)}`;
+        const msg = err instanceof Error
+            ? explainSpawnError(err, opts.cwd)
+            : String(err);
+        session.output = `Failed to spawn: ${msg}`;
         session.done = true;
         session.resolve?.();
         return { session, done };
@@ -103,7 +114,7 @@ export function executeCommand(opts) {
             const code = err.code;
             if (code === "ENOENT" || code === "EACCES")
                 session.spawnFailed = true;
-            session.output += `\nProcess error: ${err.message}`;
+            session.output += `\nProcess error: ${explainSpawnError(err, opts.cwd)}`;
             session.done = true;
             session.process = null;
             session.resolve?.();
@@ -149,7 +160,10 @@ export function executeArgv(opts) {
     catch (err) {
         session.exitCode = -1;
         session.spawnFailed = true;
-        session.output = `Failed to spawn ${opts.file}: ${err instanceof Error ? err.message : String(err)}`;
+        const msg = err instanceof Error
+            ? explainSpawnError(err, opts.cwd)
+            : String(err);
+        session.output = `Failed to spawn ${opts.file}: ${msg}`;
         session.done = true;
         session.resolve?.();
         return { session, done };
@@ -197,7 +211,7 @@ export function executeArgv(opts) {
             const code = err.code;
             if (code === "ENOENT" || code === "EACCES")
                 session.spawnFailed = true;
-            session.output += `\nProcess error: ${err.message}`;
+            session.output += `\nProcess error: ${explainSpawnError(err, opts.cwd)}`;
             session.done = true;
             session.process = null;
             session.resolve?.();

package/dist/shell/shell.d.ts

@@ -4,16 +4,25 @@ export interface ShellHandlers {
     define: (name: string, fn: (...args: any[]) => any) => void;
     call: (name: string, ...args: any[]) => any;
 }
+/**
+ * A claim on the shell's stdout-mute state. Acquire from shell.acquire*,
+ * pair with release() in a try/finally. Token-shape forces symmetry —
+ * the only way to influence the gate is to hold and release a scope.
+ */
+export interface ShellScope {
+    readonly reason: string;
+    release(): void;
+}
 export declare class Shell implements InputContext {
     private ptyProcess;
     private bus;
     private handlers;
     private inputHandler;
     private outputParser;
-    private paused;
-    private stdoutHold;
-    private stdoutShow;
-    private echoSkip;
+    private hardMuteScopes;
+    private softMuteScopes;
+    private unmuteScopes;
+    private pendingEchoSkips;
     private agentActive;
     private isZsh;
     private tmpDir?;
@@ -30,6 +39,15 @@ export declare class Shell implements InputContext {
         cwd: string;
         instanceId: string;
     });
+    /** Compositing-layer claim — overrides any unmute. */
+    acquireHardMute(reason: string): ShellScope;
+    /** Agent-turn / exec-style mute — overridable by unmute. */
+    acquireMute(reason: string): ShellScope;
+    /** Force visible while held; overrides soft mutes only. */
+    acquireUnmute(reason: string): ShellScope;
+    /** Swallow the next \n-terminated chunk from PTY (one per call). */
+    skipNextLine(): void;
+    private isHostMuted;
     isForegroundBusy(): boolean;
     getCwd(): string;
     isAgentActive(): boolean;
@@ -52,9 +70,10 @@ export declare class Shell implements InputContext {
     private setupOutput;
     private setupInput;
     /**
-     * React to agent lifecycle events — Shell manages its own state
-     * rather than being driven by AcpClient. This means AcpClient has
-     * zero frontend knowledge; any frontend can subscribe to the same events.
+     * shell:on-processing-done splits into unconditional state cleanup
+     * (release agent-turn scope) and an advisable redraw (freshPrompt).
+     * RemoteSession suppresses the redraw, never the cleanup, so soft-mute
+     * can't leak past the end of a turn even when overlays are involved.
      */
     private setupAgentLifecycle;
     /** Temp directory used for shell config and sockets. */

package/dist/shell/shell.js

@@ -5,17 +5,19 @@ import * as pty from "node-pty";
 import { InputHandler } from "./input-handler.js";
 import { OutputParser } from "./output-parser.js";
 import { getSettings } from "../settings.js";
-import { RefCounter } from "../utils/ref-counter.js";
 export class Shell {
     ptyProcess;
     bus;
     handlers;
     inputHandler;
     outputParser;
-    paused = false;
-    stdoutHold = new RefCounter();
-    stdoutShow = new RefCounter();
-    echoSkip = false;
+    // hardMute is unconditional (overlay compositing); softMute is overridable
+    // by unmute (terminal_keys, permission UI). Gate: hard wins; otherwise
+    // muted iff softMute held without an unmute.
+    hardMuteScopes = new Set();
+    softMuteScopes = new Set();
+    unmuteScopes = new Set();
+    pendingEchoSkips = 0;
     agentActive = false;
     isZsh = false;
     tmpDir;
@@ -186,12 +188,75 @@ export class Shell {
         this.bus.on("shell:pty-resize", ({ cols, rows }) => {
             this.ptyProcess.resize(cols, rows);
         });
-        // Ref-counted stdout hold — overlay extensions suppress PTY output
-        this.bus.on("shell:stdout-hold", () => { this.stdoutHold.increment(); });
-        this.bus.on("shell:stdout-release", () => { this.stdoutHold.decrement(); });
-        // Ref-counted stdout show — tools temporarily force output visible during agent processing
-        this.bus.on("shell:stdout-show", () => { this.stdoutShow.increment(); });
-        this.bus.on("shell:stdout-hide", () => { this.stdoutShow.decrement(); });
+        // Compat shims for the bus-event API. shell:stdout-hold maps to hard
+        // mute so terminal_keys' stdout-show can't paint through the overlay.
+        let holdRefcount = 0;
+        let holdScope = null;
+        this.bus.on("shell:stdout-hold", () => {
+            if (holdRefcount === 0)
+                holdScope = this.acquireHardMute("bus:stdout-hold");
+            holdRefcount++;
+        });
+        this.bus.on("shell:stdout-release", () => {
+            if (holdRefcount === 0)
+                return;
+            holdRefcount--;
+            if (holdRefcount === 0) {
+                holdScope?.release();
+                holdScope = null;
+            }
+        });
+        let showRefcount = 0;
+        let showScope = null;
+        this.bus.on("shell:stdout-show", () => {
+            if (showRefcount === 0)
+                showScope = this.acquireUnmute("bus:stdout-show");
+            showRefcount++;
+        });
+        this.bus.on("shell:stdout-hide", () => {
+            if (showRefcount === 0)
+                return;
+            showRefcount--;
+            if (showRefcount === 0) {
+                showScope?.release();
+                showScope = null;
+            }
+        });
+    }
+    // ── Scope-based gating ─────────────────────────────────────
+    /** Compositing-layer claim — overrides any unmute. */
+    acquireHardMute(reason) {
+        const scope = {
+            reason,
+            release: () => { this.hardMuteScopes.delete(scope); },
+        };
+        this.hardMuteScopes.add(scope);
+        return scope;
+    }
+    /** Agent-turn / exec-style mute — overridable by unmute. */
+    acquireMute(reason) {
+        const scope = {
+            reason,
+            release: () => { this.softMuteScopes.delete(scope); },
+        };
+        this.softMuteScopes.add(scope);
+        return scope;
+    }
+    /** Force visible while held; overrides soft mutes only. */
+    acquireUnmute(reason) {
+        const scope = {
+            reason,
+            release: () => { this.unmuteScopes.delete(scope); },
+        };
+        this.unmuteScopes.add(scope);
+        return scope;
+    }
+    /** Swallow the next \n-terminated chunk from PTY (one per call). */
+    skipNextLine() { this.pendingEchoSkips++; }
+    isHostMuted() {
+        if (this.hardMuteScopes.size > 0)
+            return true;
+        return this.softMuteScopes.size > 0 && this.unmuteScopes.size === 0;
     }
     // ── InputContext implementation (delegates to OutputParser) ──
     isForegroundBusy() {
@@ -211,12 +276,9 @@ export class Shell {
      * zsh (ZLE widget) and bash (readline redraw-current-line) bind to repaint.
      */
     redrawPrompt() {
-        // Stale echoSkip/paused from handleProcessingDone re-entering a mode
-        // would swallow the redraw and freeze the terminal visually.
-        this.echoSkip = false;
-        this.paused = false;
         const result = this.bus.emitPipe("shell:redraw-prompt", {
             cwd: this.outputParser.getCwd(),
+            kind: "redraw",
             handled: false,
         });
         if (!result.handled) {
@@ -234,6 +296,7 @@ export class Shell {
     freshPrompt() {
         const result = this.bus.emitPipe("shell:redraw-prompt", {
             cwd: this.outputParser.getCwd(),
+            kind: "fresh",
             handled: false,
         });
         if (!result.handled) {
@@ -250,16 +313,13 @@ export class Shell {
         this.ptyProcess.onData((data) => {
             this.bus.emit("shell:pty-data", { raw: data });
             this.outputParser.processData(data);
-            if (this.stdoutHold.active)
-                return;
-            if (this.paused && !this.stdoutShow.active)
+            if (this.isHostMuted())
                 return;
-            // During user_shell exec, skip the command echo (first line)
-            if (this.echoSkip) {
+            if (this.pendingEchoSkips > 0) {
                 const nlIdx = data.indexOf("\n");
                 if (nlIdx === -1)
                     return;
-                this.echoSkip = false;
+                this.pendingEchoSkips--;
                 const rest = data.slice(nlIdx + 1);
                 if (rest)
                     process.stdout.write(rest);
@@ -275,81 +335,80 @@ export class Shell {
         });
     }
     /**
-     * React to agent lifecycle events — Shell manages its own state
-     * rather than being driven by AcpClient. This means AcpClient has
-     * zero frontend knowledge; any frontend can subscribe to the same events.
+     * shell:on-processing-done splits into unconditional state cleanup
+     * (release agent-turn scope) and an advisable redraw (freshPrompt).
+     * RemoteSession suppresses the redraw, never the cleanup, so soft-mute
+     * can't leak past the end of a turn even when overlays are involved.
      */
     setupAgentLifecycle() {
-        // Default agent lifecycle: pause the shell while the agent works,
-        // then redraw the prompt when done. Extensions advise these handlers
-        // to change behavior (e.g. tmux split keeps the shell interactive).
+        let agentTurnScope = null;
         this.handlers.define("shell:on-processing-start", () => {
             this.agentActive = true;
-            this.paused = true;
+            agentTurnScope = this.acquireMute("agent-turn");
         });
-        this.handlers.define("shell:on-processing-done", () => {
-            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.
+        this.handlers.define("shell:on-processing-redraw", () => {
             if (!this.inputHandler.handleProcessingDone()) {
-                this.paused = false;
-                if (this.freshPrompt()) {
-                    this.echoSkip = true;
-                }
+                if (this.freshPrompt())
+                    this.skipNextLine();
             }
         });
+        this.handlers.define("shell:on-processing-done", () => {
+            this.agentActive = false;
+            agentTurnScope?.release();
+            agentTurnScope = null;
+            this.handlers.call("shell:on-processing-redraw");
+        });
         this.bus.on("agent:processing-start", () => {
             this.handlers.call("shell:on-processing-start");
         });
         this.bus.on("agent:processing-done", () => {
             this.handlers.call("shell:on-processing-done");
         });
-        // Permission prompts need stdout unpaused so the interactive UI renders,
-        // then re-paused after the decision.
+        // Permission UI is briefly visible during the prompt; an unmute scope
+        // overrides whatever mute is currently held, then releases cleanly.
+        // Doesn't touch agent-turn state, so suppressed handlers can't leak.
+        let permissionVisible = null;
         this.bus.on("permission:request", () => {
-            this.paused = false;
+            permissionVisible?.release();
+            permissionVisible = this.acquireUnmute("permission-ui");
         });
         this.bus.onPipeAsync("permission:request", async (payload) => {
-            this.paused = true;
+            permissionVisible?.release();
+            permissionVisible = null;
             return payload;
         });
-        // Shell exec: write a command to the live PTY and capture its output.
-        // stdout is paused during agent processing, so PTY output flows through
-        // OutputParser (for OSC detection) but never reaches the terminal.
         this.bus.onPipeAsync("shell:exec-request", async (payload) => {
-            this.echoSkip = true;
-            this.paused = false;
+            const visible = this.acquireUnmute("exec-request");
+            this.skipNextLine();
             process.stdout.write("\n");
             this.bus.emit("shell:agent-exec-start", {});
-            const output = await new Promise((resolve, reject) => {
-                const timeout = setTimeout(() => {
-                    this.bus.off("shell:command-done", handler);
-                    this.ptyProcess.write("\x03");
-                    reject(new Error("Shell exec timed out after 30s"));
-                }, 30_000);
-                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());
-                // 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;
-            this.bus.emit("shell:agent-exec-done", {});
-            return { ...payload, output: output.output, cwd: output.cwd, exitCode: output.exitCode, done: true };
+            try {
+                const output = await new Promise((resolve, reject) => {
+                    const timeout = setTimeout(() => {
+                        this.bus.off("shell:command-done", handler);
+                        this.ptyProcess.write("\x03");
+                        reject(new Error("Shell exec timed out after 30s"));
+                    }, 30_000);
+                    const handler = (e) => {
+                        clearTimeout(timeout);
+                        this.bus.off("shell:command-done", handler);
+                        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());
+                    // 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");
+                });
+                return { ...payload, output: output.output, cwd: output.cwd, exitCode: output.exitCode, done: true };
+            }
+            finally {
+                visible.release();
+                this.bus.emit("shell:agent-exec-done", {});
+            }
         });
     }
     // ── Public API (used by index.ts) ──

package/dist/utils/floating-panel.d.ts

@@ -172,7 +172,6 @@ export declare class FloatingPanel {
     private prevFrame;
     private suppressNextRedraw;
     private autoDismissTimer;
-    private ptyBuffer;
     private usedAltScreen;
     private wrapCache;
     private wrapCacheWidth;
@@ -204,6 +203,7 @@ export declare class FloatingPanel {
     appendText(text: string): void;
     appendLine(line: string): void;
     updateLastLine(fn: (line: string) => string): void;
+    popLastLine(): void;
     clearContent(): void;
     setTitle(title: string): void;
     setFooter(footer: string): void;
@@ -222,7 +222,6 @@ export declare class FloatingPanel {
     private buildFrame;
     private scheduleRender;
     private render;
-    /** Full screen teardown: exit alt screen, release stdout, force redraw. */
     private teardownScreen;
     /** Start rendering TerminalBuffer directly (no overlay box). */
     private startPassthrough;

package/dist/utils/floating-panel.js

@@ -118,7 +118,6 @@ export class FloatingPanel {
     prevFrame = [];
     suppressNextRedraw = false;
     autoDismissTimer = null;
-    ptyBuffer = ""; // PTY output accumulated while overlay is open
     usedAltScreen = false; // whether we entered our own alt screen
     wrapCache = new Map(); // line → wrapped lines (invalidated on width change)
     wrapCacheWidth = 0;
@@ -287,20 +286,14 @@ export class FloatingPanel {
     }
     // ── Bus event wiring ───────────────────────────────────────
     wireEvents() {
-        // Buffer PTY output while overlay is visible (alt screen discards it).
-        // Don't buffer when hidden — PTY flows to terminal directly via stdout-show.
-        this.bus.on("shell:pty-data", ({ raw }) => {
-            if (this._visible)
-                this.ptyBuffer += raw;
-        });
         this.bus.onPipe("input:intercept", (payload) => this.handleIntercept(payload));
         this.bus.onPipe("shell:redraw-prompt", (payload) => {
             if (this._visible || this._passthrough) {
                 return { ...payload, handled: true };
             }
-            // After dismiss, suppress one redraw — restoreScreen already
-            // restored the terminal content, so freshPrompt's \n is unwanted.
-            if (this.suppressNextRedraw) {
+            // Suppress only freshPrompt's \n — an in-place redraw must not
+            // consume the slot, or unrelated mode-exit redraws go missing.
+            if (this.suppressNextRedraw && payload.kind === "fresh") {
                 this.suppressNextRedraw = false;
                 return { ...payload, handled: true };
             }
@@ -374,7 +367,6 @@ export class FloatingPanel {
             // so the background program's screen stays correct without
             // handing rendering control back to ncurses.
             this._passthrough = true;
-            this.ptyBuffer = "";
             this.startPassthrough();
         }
         else {
@@ -435,7 +427,6 @@ export class FloatingPanel {
     /** Common screen enter logic shared by open() and show(). */
     enterScreen() {
         this._visible = true;
-        this.ptyBuffer = "";
         this.bus.emit("shell:stdout-hold", {});
         this.usedAltScreen = !(this.buffer?.altScreen);
         if (this.usedAltScreen) {
@@ -471,6 +462,15 @@ export class FloatingPanel {
         }
         this.scheduleRender();
     }
+    popLastLine() {
+        if (this.currentPartialLine) {
+            this.currentPartialLine = "";
+        }
+        else if (this.contentLines.length > 0) {
+            this.contentLines.pop();
+        }
+        this.scheduleRender();
+    }
     clearContent() {
         this.contentLines = [];
         this.currentPartialLine = "";
@@ -751,39 +751,38 @@ export class FloatingPanel {
         this.prevFrame = frame;
     }
     // ── Screen helpers ────────────────────────────────────────
-    /** Full screen teardown: exit alt screen, release stdout, force redraw. */
     teardownScreen() {
         this.resizeUnsub?.();
         this.resizeUnsub = null;
         this.suppressNextRedraw = true;
-        // Re-check alt screen state: the program we overlaid may have exited
-        // (e.g. agent quit vim via terminal_keys) while the panel was active.
-        const stillInAltScreen = !this.usedAltScreen && !!this.buffer?.altScreen;
-        const programExited = !this.usedAltScreen && !stillInAltScreen;
-        if (this.usedAltScreen) {
-            this.surface.write("\x1b[?1049l");
-        }
-        // Replay PTY output that arrived while the overlay was active.
-        // Without this, commands run by the agent (e.g. user_shell ls)
-        // would vanish — the alt screen exit restores the saved screen
-        // from before the overlay opened, losing any shell output produced
-        // during the session.
-        if (this.ptyBuffer) {
-            this.surface.write(this.ptyBuffer);
-        }
-        this.ptyBuffer = "";
-        this.bus.emit("shell:stdout-release", {});
-        if (stillInAltScreen || programExited) {
-            // Either a TUI app is still running and needs SIGWINCH to repaint,
-            // or the overlaid program exited (e.g. agent quit vim) and we
-            // discarded its stale buffer — SIGWINCH makes the shell redraw
-            // its prompt cleanly.
+        this.buffer?.flush();
+        const programInAlt = !!this.buffer?.altScreen;
+        if (!this.usedAltScreen && programInAlt) {
+            // Program still in its own alt-screen — SIGWINCH so it redraws
+            // and re-asserts its modes; replaying from the mirror would
+            // freeze modes serialize() doesn't track (modifyOtherKeys, kitty
+            // kbd) and leave ctrl-c arriving as \x1b[27;5;99~.
+            this.bus.emit("shell:stdout-release", {});
             const cols = this.surface.columns;
             const rows = this.surface.rows;
             this.bus.emit("shell:pty-resize", { cols, rows: rows - 1 });
             setTimeout(() => {
                 this.bus.emit("shell:pty-resize", { cols, rows });
             }, 50);
+            return;
+        }
+        this.surface.write("\x1b[?1049l");
+        if (!this.usedAltScreen) {
+            // Program exited mid-overlay; its reset bytes were eaten by
+            // stdout-hold. Reset modes serialize() doesn't track or the
+            // host stays in vim's modifyOtherKeys mode.
+            this.surface.write("\x1b[>4;0m\x1b[<u\x1b[?2004l\x1b[?1004l" +
+                "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l");
+        }
+        this.bus.emit("shell:stdout-release", {});
+        const serialized = this.buffer?.serialize();
+        if (serialized) {
+            this.surface.write(`${SYNC_START}\x1b[2J\x1b[H${serialized}${SYNC_END}`);
         }
     }
     // ── Passthrough rendering ─────────────────────────────────
@@ -808,7 +807,7 @@ export class FloatingPanel {
         const serialized = this.buffer.serialize();
         if (serialized && serialized !== this.prevSerialized) {
             this.prevSerialized = serialized;
-            this.surface.write(`${SYNC_START}\x1b[H${serialized}${SYNC_END}`);
+            this.surface.write(`${SYNC_START}\x1b[2J\x1b[H${serialized}${SYNC_END}`);
         }
     }
     resolveSize(spec, available) {

package/dist/utils/markdown.js

@@ -364,6 +364,8 @@ export class MarkdownRenderer {
         return this.renderInline(line);
     }
     renderInline(text) {
+        // Links first — later subs inject `\x1b[…m` whose `[` would be eaten here.
+        text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, `$1 ${p.muted}${p.underline}($2)${p.reset}`);
         // Inline code
         text = text.replace(/`([^`]+)`/g, `${p.accent}$1${p.reset}`);
         // Bold + italic
@@ -376,8 +378,6 @@ export class MarkdownRenderer {
         text = text.replace(/(?<!\w)_(.+?)_(?!\w)/g, `${p.italic}$1${p.reset}`);
         // Strikethrough
         text = text.replace(/~~(.+?)~~/g, `${p.dim}$1${p.reset}`);
-        // Links
-        text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, `$1 ${p.muted}${p.underline}($2)${p.reset}`);
         return text;
     }
     /**

package/examples/extensions/overlay-agent.ts

@@ -1,41 +1,49 @@
 /**
  * Overlay agent extension.
  *
- * Provides a hotkey (Ctrl+\) to summon the agent from anywhere — even
- * inside vim, htop, or ssh. Composites a floating response box on top
- * of the current terminal content.
+ * Press Ctrl+\ from anywhere — a shell prompt, vim, ssh, htop, a REPL — to
+ * summon the agent in a floating panel composited over the current terminal.
+ * The agent sees the live screen as `<terminal_buffer>` context (when a TUI
+ * is active) or `<shell_events>` (at a shell prompt), so screen-aware
+ * questions answer without a tool round-trip.
  *
- * Uses createRemoteSession() to route the full tui-renderer pipeline
- * (markdown, tool grouping, spinner, diffs) into the floating panel.
+ * Install (from an npm install of agent-sh):
+ *   mkdir -p ~/.agent-sh/extensions
+ *   cp "$(npm root -g)/agent-sh/examples/extensions/overlay-agent.ts" \
+ *      ~/.agent-sh/extensions/
  *
- * Install:
- *   cp examples/extensions/overlay-agent.ts ~/.agent-sh/extensions/
+ * Or load ad-hoc without copying:
+ *   agent-sh -e "$(npm root -g)/agent-sh/examples/extensions/overlay-agent.ts"
  *
- * Or load directly:
- *   agent-sh -e ./examples/extensions/overlay-agent.ts
- *
- * Requires: npm install @xterm/headless@5.5.0 @xterm/addon-serialize@0.13.0
+ * Optional companion extensions (copy the same way) — without them the
+ * overlay can read the screen but cannot interact with it:
+ *   - terminal-buffer.ts → terminal_read / terminal_keys tools
+ *   - user-shell.ts      → user_shell tool (run new shell commands)
  */
 import type { ExtensionContext, RemoteSession } from "agent-sh/types";
 import type { RenderSurface } from "agent-sh/utils/compositor";
 import { FloatingPanel } from "agent-sh/utils/floating-panel";
+import { formatScreenContext, type TerminalBuffer } from "agent-sh/utils/terminal-buffer";
 
 /** Adapt a FloatingPanel to the RenderSurface interface. */
 function createPanelSurface(panel: FloatingPanel): RenderSurface {
+  // Track the spinner row so a stop-clear ("\r\x1b[2K") removes it
+  // instead of leaving an orphan blank line in the panel.
+  let spinnerLine = false;
   return {
     write(text: string): void {
-      // Handle \r (carriage return) — overwrite the current line.
-      // The spinner uses "\r  <content>\x1b[K" to update in-place.
       if (text.startsWith("\r")) {
-        // Strip \r and any erase-line sequences
         const cleaned = text.replace(/^\r/, "").replace(/\x1b\[\d*K/g, "");
         if (cleaned.trim()) {
-          panel.updateLastLine(() => cleaned);
+          if (spinnerLine) panel.updateLastLine(() => cleaned);
+          else { panel.appendLine(cleaned); spinnerLine = true; }
+        } else if (spinnerLine) {
+          panel.popLastLine();
+          spinnerLine = false;
         }
         return;
       }
-
-      // Regular text — may contain newlines
+      if (spinnerLine) { panel.popLastLine(); spinnerLine = false; }
       panel.appendText(text);
     },
     writeLine(line: string): void {
@@ -44,12 +52,23 @@ function createPanelSurface(panel: FloatingPanel): RenderSurface {
     get columns(): number {
       return panel.computeGeometry().contentW;
     },
+    get rows(): number {
+      return panel.computeGeometry().contentH;
+    },
+    onResize(cb: (cols: number, rows: number) => void): () => void {
+      const handler = () => {
+        const g = panel.computeGeometry();
+        cb(g.contentW, g.contentH);
+      };
+      process.stdout.on("resize", handler);
+      return () => { process.stdout.off("resize", handler); };
+    },
   };
 }
 
 export default function activate(ctx: ExtensionContext): void {
   const { bus, registerInstruction, createRemoteSession } = ctx;
-  const terminalBuffer = ctx.call("terminal-buffer");
+  const terminalBuffer: TerminalBuffer | null = ctx.call("terminal-buffer");
 
   const panel = new FloatingPanel(bus, {
     trigger: "\x1c", // Ctrl+\
@@ -60,22 +79,21 @@ export default function activate(ctx: ExtensionContext): void {
   const panelSurface = createPanelSurface(panel);
   let session: RemoteSession | null = null;
 
-  // Tell the LLM it's running inside an overlay session. The matching
-  // system-prompt block (registered via registerInstruction below) describes
-  // how to behave in this mode.
   ctx.registerContextProducer("interactive-session", () =>
     session?.active ? "interactive-session: true" : null,
   );
 
+  // Inject the live screen for TUI / REPL programs. At a plain shell prompt
+  // `<shell_events>` already covers the visible scrollback — skip to dedupe.
+  ctx.registerContextProducer("terminal-screen", () => {
+    if (!session?.active || !terminalBuffer?.altScreen) return null;
+    return formatScreenContext(terminalBuffer.readScreen(), 80);
+  });
+
   registerInstruction("Interactive Overlay Sessions", [
-    "When the dynamic context includes `interactive-session: true`, the user has summoned you",
-    "via a hotkey overlay from inside their live terminal. They may be in the middle of using",
-    "a program (vim, ssh, a REPL, etc.) or at a shell prompt. In this mode:",
-    "- Start with terminal_read if you need to understand what's on screen.",
-    "- Prefer terminal_keys to interact with whatever is currently running.",
-    "- Use user_shell only for running new, standalone commands — not for interacting with",
-    "  what's already on screen.",
-    "- Keep responses concise — the user is in the middle of a workflow.",
+    "When dynamic context includes `interactive-session: true`, the user summoned you via a",
+    "hotkey overlay from their live terminal. They're mid-workflow (shell prompt, vim, ssh, a",
+    "REPL, etc.) — keep responses concise and prefer reading what's on screen over asking.",
   ].join("\n"));
 
   // ── Panel lifecycle ────────────────────────────────────────────
@@ -84,7 +102,6 @@ export default function activate(ctx: ExtensionContext): void {
     if (!session) {
       session = createRemoteSession({
         surface: panelSurface,
-        suppressQueryBox: true,
       });
     }
     panel.setActive();
@@ -92,18 +109,13 @@ export default function activate(ctx: ExtensionContext): void {
   });
 
   panel.handlers.advise("panel:show", (_next) => {
-    // Re-establish session if panel is shown while agent is still working
     if (panel.active && !session) {
-      session = createRemoteSession({
-        surface: panelSurface,
-        suppressQueryBox: true,
-      });
+      session = createRemoteSession({ surface: panelSurface });
     }
   });
 
-  // On dismiss: close session only if agent is not actively processing.
-  // If agent is still working (phase="active"), keep session alive so
-  // output buffers in the panel and agent can keep executing tools.
+  // Keep the session alive while the agent is still working, even after
+  // dismiss — so output keeps buffering and tools keep executing.
   panel.handlers.advise("panel:dismiss", (next) => {
     next();
     if (session && !panel.processing) {
@@ -113,10 +125,6 @@ export default function activate(ctx: ExtensionContext): void {
   });
 
   bus.on("agent:processing-done", () => {
-    if (!panel.active) return;
-    panel.setDone();
-    // If panel was hidden while processing (passthrough), setDone()
-    // triggers dismiss() which closes the session above.
-    // If panel is still visible, session stays for the follow-up prompt.
+    if (panel.active) panel.setDone();
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.12.22",
+  "version": "0.12.23",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",