agent-sh 0.12.22 → 0.12.24

package/README.md

@@ -19,7 +19,7 @@ So I built agent-sh. Under the hood it's a normal shell on top of node-pty — y
 ~ $ > draft a commit message     # agent reads your diff and shell history
 ```
 
-I still use a proper coding harness for serious work — this doesn't replace that. But for the quick stuff in the terminal, I reach for agent-sh almost every day now. The built-in agent is lightweight and good enough for most of what I throw at it, and when it isn't, you can swap in [pi](examples/extensions/pi-bridge/) as the backend via a bridge extension.
+I still use a proper coding harness for serious work — this doesn't replace that. But for the quick stuff in the terminal, I reach for agent-sh almost every day now. The built-in agent is lightweight and good enough for most of what I throw at it, and when it isn't, you can swap in [pi](examples/extensions/pi-bridge/) as the backend — `agent-sh install pi-bridge` followed by `agent-sh --backend pi`.
 
 ## Quick Start
 
@@ -95,7 +95,7 @@ Requires Node.js 18+. Currently supports **bash** and **zsh**; other shells (fis
 
 **Context that just works.** Every query includes your cwd, recent commands, and their output. Run a failing test, type `> fix this`, and agent-sh knows exactly what happened. Context management works like shell history — continuous, persistent across restarts, no sessions to manage. See [Context Management](docs/context-management.md).
 
-**Any LLM, any backend.** agent-sh works with any OpenAI-compatible API out of the box. Define multiple providers in settings and switch models at runtime with `/model <name>`. Or swap in a completely different agent — [pi](examples/extensions/pi-bridge/) runs as a drop-in backend extension.
+**Any LLM, any backend.** agent-sh works with any OpenAI-compatible API out of the box. Define multiple providers in settings and switch models at runtime with `/model <name>`. Or swap in a completely different agent — `agent-sh install pi-bridge && agent-sh --backend pi` runs [pi](examples/extensions/pi-bridge/) as a drop-in backend.
 
 **Extensible by design.** The entire system is built on a typed event bus. Extensions can add custom input modes, content transforms (render LaTeX as images, Mermaid as diagrams), themes, slash commands, or replace the agent backend entirely. The built-in TUI renderer is itself just an extension.
 

package/dist/core.d.ts

@@ -37,7 +37,7 @@ export interface AgentShellCore {
     /** Unique id for this agent process; used for shell-marker tagging and lineage tracking. */
     instanceId: string;
     /** Activate the agent backend (call after extensions load). */
-    activateBackend(): Promise<void>;
+    activateBackend(override?: string): Promise<void>;
     /** Convenience: emit agent:submit and await the response. */
     query(text: string): Promise<string>;
     /** Convenience: emit agent:cancel-request. */

package/dist/core.js

@@ -102,10 +102,10 @@ export function createCore(config) {
         bus,
         handlers,
         instanceId,
-        async activateBackend() {
+        async activateBackend(override) {
             if (backends.size === 0)
                 return;
-            const preferred = settings.defaultBackend;
+            const preferred = override ?? settings.defaultBackend;
             const name = preferred && backends.has(preferred) ? preferred : backends.keys().next().value;
             await activateByName(name);
         },
@@ -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": {
@@ -366,6 +367,8 @@ export interface ShellEvents {
             label: string;
             items: string[];
         }>;
+        /** Name of the backend being launched. Extensions should gate per-backend sections on this rather than settings.defaultBackend. */
+        activeBackend?: string;
     };
     "autocomplete:request": {
         buffer: string;

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/extensions/agent-backend.js

@@ -293,8 +293,7 @@ export default function agentBackend(ctx) {
         bus.emit("config:changed", {});
     });
     bus.onPipe("banner:collect", (e) => {
-        const settings = getSettings();
-        if (settings.defaultBackend && settings.defaultBackend !== "ash")
+        if (e.activeBackend && e.activeBackend !== "ash")
             return e;
         if (loadedExtensionNames.length > 0) {
             e.sections.push({ label: "Extensions", items: [...loadedExtensionNames] });

package/dist/index.js

@@ -8,6 +8,7 @@ import { loadBuiltinExtensions } from "./extensions/index.js";
 import { loadExtensions } from "./extension-loader.js";
 import { getSettings } from "./settings.js";
 import { runInit } from "./init.js";
+import { runInstall, runUninstall, runList, suggestBridgeFor } from "./install.js";
 import { PACKAGE_VERSION } from "./utils/package-version.js";
 /**
  * Capture the user's full shell environment.
@@ -78,7 +79,8 @@ function parseArgs(argv) {
     let model;
     let extensions;
     let provider;
-    const shell = process.env.SHELL || "/bin/bash";
+    let backend;
+    let shell = process.env.SHELL || "/bin/bash";
     let apiKey = process.env.OPENAI_API_KEY;
     let baseURL = process.env.OPENAI_BASE_URL;
     for (let i = 0; i < argv.length; i++) {
@@ -95,8 +97,11 @@ function parseArgs(argv) {
         else if (arg === "--provider" && argv[i + 1]) {
             provider = argv[++i];
         }
+        else if (arg === "--backend" && argv[i + 1]) {
+            backend = argv[++i];
+        }
         else if (arg === "--shell" && argv[i + 1]) {
-            return { shell: argv[++i], model, extensions, apiKey, baseURL, provider };
+            shell = argv[++i];
         }
         else if ((arg === "--extensions" || arg === "-e") && argv[i + 1]) {
             const exts = argv[++i].split(",").map(s => s.trim());
@@ -110,7 +115,10 @@ function parseArgs(argv) {
             console.log(`agent-sh — a shell-first terminal where AI is one keystroke away
 
 Usage: agent-sh [options]
-       agent-sh init [--force]    Scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
+       agent-sh init [--force]            Scaffold ~/.agent-sh/ (settings, examples, AGENTS.md)
+       agent-sh install <spec> [--force]  Install an extension (bundled name, file:, npm:, github:)
+       agent-sh uninstall <name>          Remove an installed extension
+       agent-sh list                      List installed extensions
 
 Provider Profiles:
   --provider <name>   Use a provider from ~/.agent-sh/settings.json
@@ -121,6 +129,7 @@ Direct LLM API:
   --base-url <url>    Base URL for API (or set OPENAI_BASE_URL)
 
 General Options:
+  --backend <name>    Agent backend to launch (e.g. ash, pi); overrides settings.defaultBackend for this session
   --shell <path>      Shell to use (default: $SHELL or /bin/bash)
   -e, --extensions    Extensions to load (comma-separated, repeatable)
   -h, --help          Show this help
@@ -149,7 +158,7 @@ Inside the shell:
             process.exit(0);
         }
     }
-    return { shell, model, extensions, apiKey, baseURL, provider };
+    return { shell, model, extensions, apiKey, baseURL, provider, backend };
 }
 async function main() {
     // Subcommands — handled before the shell-launch path.
@@ -158,6 +167,18 @@ async function main() {
         runInit({ force: rawArgs.includes("--force") });
         return;
     }
+    if (rawArgs[0] === "install") {
+        await runInstall(rawArgs[1] ?? "", { force: rawArgs.includes("--force") });
+        return;
+    }
+    if (rawArgs[0] === "uninstall") {
+        await runUninstall(rawArgs[1] ?? "");
+        return;
+    }
+    if (rawArgs[0] === "list") {
+        runList();
+        return;
+    }
     if (process.env.AGENT_SH) {
         console.error("agent-sh: already running inside an agent-sh session (nested sessions are not supported).");
         process.exit(1);
@@ -280,24 +301,37 @@ async function main() {
         console.error("\nagent-sh: no agent backend available.\n\n" +
             "  Export OPENROUTER_API_KEY or OPENAI_API_KEY for zero-config launch, or\n" +
             "  pass --api-key on the command line, or\n" +
-            "  run `agent-sh init` for a settings.json template.\n" +
-            "  Alternatively, install a bridge extension (claude-code-bridge, pi-bridge).\n");
+            "  run `agent-sh init` for a settings.json template, or\n" +
+            "  run `agent-sh install <bridge>` (e.g. pi-bridge, claude-code-bridge) to use a non-ash backend.\n");
+        process.exit(1);
+    }
+    if (config.backend && !backendNames.includes(config.backend)) {
+        shell?.kill();
+        const bridge = suggestBridgeFor(config.backend);
+        const hint = bridge
+            ? `  Try: agent-sh install ${bridge}\n`
+            : `  Run \`agent-sh install\` to see bundled bridge extensions.\n`;
+        console.error(`\nagent-sh: backend "${config.backend}" is not available.\n\n` +
+            `  Available backends: ${backendNames.join(", ")}\n` +
+            hint);
         process.exit(1);
     }
     // No await: banner must out-race the shell's PS1 arriving via PTY.
-    core.activateBackend();
+    core.activateBackend(config.backend);
     // ── Startup banner ───────────────────────────────────────────
     const settings = getSettings();
     if (settings.startupBanner !== false) {
         const termW = process.stdout.columns || 80;
         const bannerW = Math.min(termW, 60);
         const productName = `${p.accent}${p.bold}agent-sh${p.reset}`;
-        const backendName = settings.defaultBackend && backendNames.includes(settings.defaultBackend)
-            ? settings.defaultBackend
-            : backendNames[0];
+        const backendName = config.backend && backendNames.includes(config.backend)
+            ? config.backend
+            : settings.defaultBackend && backendNames.includes(settings.defaultBackend)
+                ? settings.defaultBackend
+                : backendNames[0];
         let sections = "";
         sections += `\n\n  ${p.muted}Backend:${p.reset} ${p.dim}${backendName}${p.reset}`;
-        const extSections = bus.emitPipe("banner:collect", { sections: [] }).sections;
+        const extSections = bus.emitPipe("banner:collect", { sections: [], activeBackend: backendName }).sections;
         for (const sec of extSections) {
             sections += `\n\n  ${p.muted}${sec.label}:${p.reset}`;
             for (const item of sec.items) {

package/dist/install.d.ts

@@ -0,0 +1,10 @@
+interface InstallOpts {
+    force?: boolean;
+}
+export declare function listBundled(): string[];
+/** Heuristic: a backend named "pi" is typically provided by an extension called "pi-bridge". */
+export declare function suggestBridgeFor(backend: string): string | null;
+export declare function runInstall(spec: string, opts?: InstallOpts): Promise<void>;
+export declare function runUninstall(name: string): Promise<void>;
+export declare function runList(): void;
+export {};

package/dist/install.js

@@ -0,0 +1,205 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { CONFIG_DIR, getSettings } from "./settings.js";
+// Kept in sync with extension-loader.ts SCRIPT_EXTS.
+const SCRIPT_EXTS = [".js", ".mjs", ".ts", ".tsx", ".mts"];
+function hasIndexFile(dir) {
+    return SCRIPT_EXTS.some((ext) => fs.existsSync(path.join(dir, `index${ext}`)));
+}
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../");
+const BUNDLED_DIR = path.join(PACKAGE_ROOT, "examples/extensions");
+const EXT_DIR = path.join(CONFIG_DIR, "extensions");
+export function listBundled() {
+    if (!fs.existsSync(BUNDLED_DIR))
+        return [];
+    return fs.readdirSync(BUNDLED_DIR).map((n) => n.replace(/\.(ts|js|mjs)$/, ""));
+}
+/** Heuristic: a backend named "pi" is typically provided by an extension called "pi-bridge". */
+export function suggestBridgeFor(backend) {
+    const candidate = `${backend}-bridge`;
+    return listBundled().includes(candidate) ? candidate : null;
+}
+const bundledResolver = {
+    resolve: async (spec) => {
+        const candidates = [
+            { p: path.join(BUNDLED_DIR, spec), name: spec },
+            { p: path.join(BUNDLED_DIR, `${spec}.ts`), name: `${spec}.ts` },
+            { p: path.join(BUNDLED_DIR, `${spec}.js`), name: `${spec}.js` },
+        ];
+        for (const c of candidates) {
+            if (fs.existsSync(c.p)) {
+                const isDirectory = fs.statSync(c.p).isDirectory();
+                return { sourcePath: c.p, name: c.name, isDirectory };
+            }
+        }
+        const available = listBundled();
+        throw new Error(`No bundled extension named "${spec}".\n\n` +
+            `Available:\n${available.map((n) => `  ${n}`).join("\n")}`);
+    },
+};
+const npmResolver = {
+    canHandle: (spec) => spec.startsWith("npm:"),
+    resolve: async () => {
+        throw new Error("npm: source is not yet implemented");
+    },
+};
+const githubResolver = {
+    canHandle: (spec) => spec.startsWith("github:") || spec.startsWith("https://github.com/"),
+    resolve: async () => {
+        throw new Error("github: source is not yet implemented");
+    },
+};
+const fileResolver = {
+    canHandle: (spec) => spec.startsWith("file:") || spec.startsWith("/") || spec.startsWith("./") || spec.startsWith("../"),
+    resolve: async (spec) => {
+        const raw = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+        const abs = path.resolve(raw);
+        if (!fs.existsSync(abs))
+            throw new Error(`Path does not exist: ${abs}`);
+        const isDirectory = fs.statSync(abs).isDirectory();
+        return { sourcePath: abs, name: path.basename(abs), isDirectory };
+    },
+};
+const PREFIX_RESOLVERS = [npmResolver, githubResolver, fileResolver];
+function pickResolver(spec) {
+    for (const r of PREFIX_RESOLVERS)
+        if (r.canHandle?.(spec))
+            return r;
+    return bundledResolver;
+}
+function maybeNpmInstall(target) {
+    const pkgJson = path.join(target, "package.json");
+    if (!fs.existsSync(pkgJson))
+        return;
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf-8"));
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.peerDependencies ?? {}) };
+    if (Object.keys(deps).length === 0)
+        return;
+    if (fs.existsSync(path.join(target, "node_modules")))
+        return;
+    console.log(`Running npm install in ${target}...`);
+    const result = spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
+        cwd: target,
+        stdio: "inherit",
+    });
+    if (result.status !== 0) {
+        throw new Error(`npm install failed in ${target}; run it manually.`);
+    }
+}
+export async function runInstall(spec, opts = {}) {
+    if (!spec) {
+        console.error("Usage: agent-sh install <name|file:|npm:|github:> [--force]\n\n" +
+            "Bundled extensions:\n" +
+            listBundled()
+                .map((n) => `  ${n}`)
+                .join("\n"));
+        process.exit(1);
+    }
+    fs.mkdirSync(EXT_DIR, { recursive: true });
+    let resolved;
+    try {
+        resolved = await pickResolver(spec).resolve(spec);
+    }
+    catch (err) {
+        console.error(`agent-sh: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const target = path.join(EXT_DIR, resolved.name);
+    if (fs.lstatSync(target, { throwIfNoEntry: false })) {
+        if (!opts.force) {
+            console.error(`agent-sh: ${target} already exists (pass --force to overwrite)`);
+            process.exit(1);
+        }
+        fs.rmSync(target, { recursive: true, force: true });
+    }
+    if (resolved.isDirectory) {
+        fs.cpSync(resolved.sourcePath, target, { recursive: true });
+        try {
+            maybeNpmInstall(target);
+        }
+        catch (err) {
+            console.error(`agent-sh: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    }
+    else {
+        fs.copyFileSync(resolved.sourcePath, target);
+    }
+    console.log(`Installed: ${resolved.name} -> ${target}`);
+}
+export async function runUninstall(name) {
+    if (!name) {
+        console.error("Usage: agent-sh uninstall <name>");
+        process.exit(1);
+    }
+    const target = path.join(EXT_DIR, name);
+    // Refuse path-traversal: target must sit directly under EXT_DIR.
+    const resolvedTarget = path.resolve(target);
+    const resolvedExtDir = path.resolve(EXT_DIR);
+    if (!resolvedTarget.startsWith(resolvedExtDir + path.sep)) {
+        console.error(`agent-sh: refusing to uninstall outside ${EXT_DIR}`);
+        process.exit(1);
+    }
+    if (!fs.lstatSync(target, { throwIfNoEntry: false })) {
+        console.error(`agent-sh: not installed: ${name}`);
+        process.exit(1);
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+    console.log(`Uninstalled: ${name}`);
+}
+function listFromExtDir(disabled) {
+    if (!fs.existsSync(EXT_DIR))
+        return [];
+    const dirents = fs.readdirSync(EXT_DIR, { withFileTypes: true });
+    const out = [];
+    for (const d of dirents) {
+        if (d.name.startsWith("."))
+            continue;
+        const nameForDisable = d.name.replace(/\.[^.]+$/, "");
+        if (disabled.has(nameForDisable))
+            continue;
+        const full = path.join(EXT_DIR, d.name);
+        let isDir = d.isDirectory();
+        if (d.isSymbolicLink()) {
+            try {
+                isDir = fs.statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+        }
+        if (isDir) {
+            if (!hasIndexFile(full))
+                continue;
+        }
+        else if (!SCRIPT_EXTS.some((ext) => d.name.endsWith(ext))) {
+            continue;
+        }
+        const detail = d.isSymbolicLink() ? `-> ${fs.readlinkSync(full)}` : undefined;
+        out.push({ name: d.name, source: "extensions dir", detail });
+    }
+    return out;
+}
+function listFromSettings(disabled) {
+    const specs = getSettings().extensions ?? [];
+    return specs
+        .filter((s) => !disabled.has(s.replace(/\.[^.]+$/, "")))
+        .map((s) => ({ name: s, source: "settings.json" }));
+}
+export function runList() {
+    const disabled = new Set(getSettings().disabledExtensions ?? []);
+    const items = [...listFromExtDir(disabled), ...listFromSettings(disabled)];
+    if (items.length === 0) {
+        console.log("No extensions installed.");
+        return;
+    }
+    const nameWidth = Math.max(...items.map((i) => i.name.length));
+    console.log("Installed extensions:");
+    for (const item of items) {
+        const padded = item.name.padEnd(nameWidth);
+        const detail = item.detail ? `  ${item.detail}` : "";
+        console.log(`  ${padded}  (${item.source})${detail}`);
+    }
+}

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/types.d.ts

@@ -100,6 +100,8 @@ export interface AgentShellConfig {
     baseURL?: string;
     /** Named provider to use from settings.json. */
     provider?: string;
+    /** Override settings.defaultBackend for this session only (does not persist). */
+    backend?: string;
     /** Conversation history backend. Defaults to the on-disk HistoryFile. */
     history?: HistoryAdapter;
 }

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.24",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",