agent-sh 0.6.0 → 0.8.0

package/dist/extensions/tui-renderer.js

@@ -14,7 +14,7 @@ import { highlight } from "cli-highlight";
 import { MarkdownRenderer, wrapLine } from "../utils/markdown.js";
 import { createFencedBlockTransform } from "../utils/stream-transform.js";
 import { palette as p } from "../utils/palette.js";
-import { renderToolCall, createSpinner, renderSpinnerLine, formatElapsed, } from "../utils/tool-display.js";
+import { renderToolCall, createSpinner, formatElapsed, SPINNER_FRAMES, } from "../utils/tool-display.js";
 import { renderDiff } from "../utils/diff-renderer.js";
 import { renderBoxFrame } from "../utils/box-frame.js";
 import { getSettings } from "../settings.js";
@@ -71,6 +71,72 @@ export default function activate(ctx) {
     const { bus, llmClient, define } = ctx;
     const writer = new StdoutWriter();
     const s = createRenderState();
+    // Suppress all TUI output while stdout is held (overlay extensions)
+    bus.on("shell:stdout-hold", () => { writer.hold(); });
+    bus.on("shell:stdout-release", () => { writer.release(); });
+    // Gate: other extensions (e.g. overlay) can advise this to suppress
+    // TUI rendering of agent output while they own the display.
+    define("tui:should-render-agent", () => true);
+    function shouldRender() { return ctx.call("tui:should-render-agent"); }
+    // ── Advisable rendering handlers ───────────────────────────────
+    // Extensions advise these to customize how the TUI renders content.
+    // Each handler receives data and returns rendered strings.
+    define("tui:response-start", () => { });
+    define("tui:response-end", (_hadToolCalls) => { });
+    define("tui:render-info", (message) => `${p.muted}${message}${p.reset}`);
+    define("tui:render-error", (message) => `${p.error}Error: ${message}${p.reset}`);
+    define("tui:render-usage", (promptTokens, completionTokens, maxTokens) => {
+        const ctxK = (promptTokens / 1000).toFixed(1);
+        const maxK = (maxTokens / 1000).toFixed(0);
+        const pct = Math.min(100, (promptTokens / maxTokens) * 100).toFixed(0);
+        return `${p.dim}⬆ ${promptTokens}  ⬇ ${completionTokens}  ctx: ${ctxK}k/${maxK}k (${pct}%)${p.reset}`;
+    });
+    define("tui:render-content-gap", (fromKind, toKind) => fromKind !== toKind ? "\n" : null);
+    define("tui:render-tool-complete", (exitCode, elapsed, summary) => {
+        const timer = elapsed ? ` ${p.dim}${elapsed}${p.reset}` : "";
+        const summaryStr = summary ? ` ${p.dim}${summary}${p.reset}` : "";
+        if (exitCode === null)
+            return `${p.muted}(timed out)${p.reset}`;
+        if (exitCode === 0)
+            return `${p.success}✓${p.reset}${summaryStr}${timer}`;
+        return `${p.error}✗ exit ${exitCode}${p.reset}${summaryStr}${timer}`;
+    });
+    define("tui:render-tool-group-summary", (count, rendered, allOk, summaries) => {
+        const mark = allOk ? `${p.success}✓${p.reset}` : `${p.error}✗${p.reset}`;
+        const summaryStr = summaries.length > 0 ? ` ${p.dim}${summaries.join(", ")}${p.reset}` : "";
+        const collapsed = count - rendered;
+        if (collapsed > 0) {
+            return `  ${p.muted}└${p.reset} ${p.dim}+${collapsed} more${p.reset} ${mark}${summaryStr}`;
+        }
+        return `  ${p.muted}└${p.reset} ${mark}${summaryStr}`;
+    });
+    define("tui:render-command-output", (line, _kind) => `${p.dim}  ${line}${p.reset}`);
+    define("tui:render-spinner", (label, frame, elapsed, hint) => {
+        const timer = elapsed ? ` ${p.dim}${elapsed}${p.reset}` : "";
+        const hintStr = hint ? ` ${p.dim}${hint}${p.reset}` : "";
+        return `${p.accent}${frame} ${label}...${p.reset}${timer}${hintStr}`;
+    });
+    define("tui:render-user-query", (query, width, modelLabel) => {
+        const contentW = width - 4;
+        let lines = [];
+        for (const raw of query.split("\n")) {
+            for (const wrapped of wrapLine(`${p.accent}${raw}${p.reset}`, contentW)) {
+                lines.push(wrapped);
+            }
+        }
+        const MAX_QUERY_LINES = 20;
+        if (lines.length > MAX_QUERY_LINES) {
+            const overflow = lines.length - MAX_QUERY_LINES;
+            lines = [...lines.slice(0, MAX_QUERY_LINES), `${p.dim}… ${overflow} more lines${p.reset}`];
+        }
+        return renderBoxFrame(lines, {
+            width,
+            style: "rounded",
+            borderColor: p.accent,
+            title: `${p.accent}${p.bold}❯${p.reset}`,
+            titleRight: modelLabel,
+        });
+    });
     // Track backend/model info for display on response border
     let backendInfo = null;
     bus.on("agent:info", (info) => { backendInfo = info; });
@@ -85,12 +151,16 @@ export default function activate(ctx) {
     });
     // ── Event subscriptions ─────────────────────────────────────
     bus.on("agent:query", (e) => {
+        if (!shouldRender())
+            return;
         s.spinnerStartTime = 0;
         showUserQuery(e.query);
         startAgentResponse();
         startThinkingSpinner();
     });
     bus.on("agent:thinking-chunk", (e) => {
+        if (!shouldRender())
+            return;
         s.thinkingPending = true;
         if (!s.isThinking) {
             s.isThinking = true;
@@ -115,6 +185,8 @@ export default function activate(ctx) {
         }
     });
     bus.on("agent:response-chunk", (e) => {
+        if (!shouldRender())
+            return;
         const { blocks } = e;
         // Inject spacing: append \n to text blocks that precede non-text blocks
         for (let i = 0; i < blocks.length; i++) {
@@ -147,17 +219,14 @@ export default function activate(ctx) {
     let pendingUsage = null;
     bus.on("agent:usage", (e) => { pendingUsage = e; });
     bus.on("agent:response-done", () => {
+        if (!shouldRender())
+            return;
         s.isThinking = false;
         if (pendingUsage && s.renderer) {
             const { prompt_tokens, completion_tokens } = pendingUsage;
             const maxTokens = backendInfo?.contextWindow ?? 128_000;
-            // prompt_tokens of the latest call = current context usage
-            // (it includes the full conversation history)
-            const ctxK = (prompt_tokens / 1000).toFixed(1);
-            const maxK = (maxTokens / 1000).toFixed(0);
-            const pct = Math.min(100, (prompt_tokens / maxTokens) * 100).toFixed(0);
             s.renderer.writeLine("");
-            s.renderer.writeLine(`${p.dim}⬆ ${prompt_tokens}  ⬇ ${completion_tokens}  ctx: ${ctxK}k/${maxK}k (${pct}%)${p.reset}`);
+            s.renderer.writeLine(ctx.call("tui:render-usage", prompt_tokens, completion_tokens, maxTokens));
             drain();
             pendingUsage = null;
         }
@@ -170,6 +239,8 @@ export default function activate(ctx) {
     // Batch groups: kind → { total, rendered, headerShown }
     let batchGroups = new Map();
     bus.on("agent:tool-batch", (e) => {
+        if (!shouldRender())
+            return;
         fencedTransform.flush();
         finalizeToolGroup();
         batchGroups = new Map();
@@ -182,6 +253,8 @@ export default function activate(ctx) {
         }
     });
     bus.on("agent:tool-started", (e) => {
+        if (!shouldRender())
+            return;
         fencedTransform.flush();
         stopCurrentSpinner();
         s.currentToolKind = e.kind;
@@ -245,6 +318,8 @@ export default function activate(ctx) {
         }
     });
     bus.on("agent:tool-completed", (e) => {
+        if (!shouldRender())
+            return;
         s.toolExitCode = e.exitCode;
         if (e.exitCode !== 0)
             s.toolGroupAllOk = false;
@@ -262,20 +337,28 @@ export default function activate(ctx) {
             startThinkingSpinner();
         }
     });
-    bus.on("agent:tool-output-chunk", (e) => writeCommandOutput(e.chunk));
-    bus.on("agent:tool-output", () => flushCommandOutput());
+    bus.on("agent:tool-output-chunk", (e) => { if (shouldRender())
+        writeCommandOutput(e.chunk); });
+    bus.on("agent:tool-output", () => { if (shouldRender())
+        flushCommandOutput(); });
     bus.on("agent:cancelled", () => {
+        if (!shouldRender())
+            return;
         s.isThinking = false;
         stopCurrentSpinner();
         showInfo("(cancelled)");
         endAgentResponse();
     });
     bus.on("agent:processing-done", () => {
+        if (!shouldRender())
+            return;
         s.isThinking = false;
         stopCurrentSpinner();
         endAgentResponse();
     });
     bus.on("agent:error", (e) => {
+        if (!shouldRender())
+            return;
         stopCurrentSpinner();
         showCollapsedThinking();
         if (!s.renderer)
@@ -286,6 +369,8 @@ export default function activate(ctx) {
         drain();
     });
     bus.on("permission:request", (e) => {
+        if (!shouldRender())
+            return;
         stopCurrentSpinner();
         flushCommandOutput();
         if (s.renderer) {
@@ -331,9 +416,9 @@ export default function activate(ctx) {
     function startAgentResponse() {
         s.renderer = new MarkdownRenderer(writer.columns);
         s.hadToolCalls = false;
-        // Preserve lastContentKind across responses so text→tool gaps work
         s.renderer.printTopBorder();
         drain();
+        ctx.call("tui:response-start");
     }
     /**
      * Insert an empty line when transitioning between different content kinds
@@ -342,12 +427,15 @@ export default function activate(ctx) {
      */
     let lastEmittedLineBlank = false;
     function contentGap(kind) {
-        if (s.lastContentKind && s.lastContentKind !== kind) {
-            if (s.renderer) {
-                s.renderer.flush();
-                drain();
+        if (s.lastContentKind) {
+            const gap = ctx.call("tui:render-content-gap", s.lastContentKind, kind);
+            if (gap) {
+                if (s.renderer) {
+                    s.renderer.flush();
+                    drain();
+                }
+                writer.write(gap);
             }
-            writer.write("\n");
         }
         s.lastContentKind = kind;
     }
@@ -363,6 +451,7 @@ export default function activate(ctx) {
         closeToolLine();
         stopCurrentSpinner();
         if (s.renderer) {
+            ctx.call("tui:response-end", s.hadToolCalls);
             s.renderer.flush();
             s.renderer.printBottomBorder();
             drain();
@@ -371,39 +460,6 @@ export default function activate(ctx) {
         }
     }
     function showUserQuery(query) {
-        const boxW = writer.columns;
-        const contentW = boxW - 4;
-        let lines = [];
-        for (const raw of query.split("\n")) {
-            if (raw.length <= contentW) {
-                lines.push(`${p.accent}${raw}${p.reset}`);
-            }
-            else {
-                let remaining = raw;
-                while (remaining.length > contentW) {
-                    let breakAt = remaining.lastIndexOf(" ", contentW);
-                    if (breakAt <= 0)
-                        breakAt = contentW;
-                    lines.push(`${p.accent}${remaining.slice(0, breakAt)}${p.reset}`);
-                    remaining = remaining.slice(breakAt).trimStart();
-                }
-                if (remaining)
-                    lines.push(`${p.accent}${remaining}${p.reset}`);
-            }
-        }
-        // Truncate very long queries to keep the response visible
-        const MAX_QUERY_LINES = 20;
-        if (lines.length > MAX_QUERY_LINES) {
-            const overflow = lines.length - MAX_QUERY_LINES;
-            lines = [
-                ...lines.slice(0, MAX_QUERY_LINES),
-                `${p.dim}… ${overflow} more lines${p.reset}`,
-            ];
-        }
-        // Mode-specific border color and title
-        const borderColor = p.accent;
-        const title = `${p.accent}${p.bold}❯${p.reset}`;
-        // Backend/model label on the right (backend/model, highlighted)
         const model = backendInfo?.model ?? llmClient?.model;
         const backend = backendInfo?.name;
         let modelLabel;
@@ -416,13 +472,7 @@ export default function activate(ctx) {
         else if (backend) {
             modelLabel = `${p.bold}${backend}${p.reset}`;
         }
-        const framed = renderBoxFrame(lines, {
-            width: boxW,
-            style: "rounded",
-            borderColor,
-            title,
-            titleRight: modelLabel,
-        });
+        const framed = ctx.call("tui:render-user-query", query, writer.columns, modelLabel);
         writer.write("\n");
         for (const line of framed) {
             writer.write(line + "\n");
@@ -650,13 +700,7 @@ export default function activate(ctx) {
             return;
         stopCurrentSpinner();
         const elapsed = s.toolStartTime ? formatElapsed(Date.now() - s.toolStartTime) : "";
-        const timer = elapsed ? ` ${p.dim}${elapsed}${p.reset}` : "";
-        const summary = resultDisplay?.summary ? ` ${p.dim}${resultDisplay.summary}${p.reset}` : "";
-        const mark = exitCode === null
-            ? `${p.muted}(timed out)${p.reset}`
-            : exitCode === 0
-                ? `${p.success}✓${p.reset}${summary}${timer}`
-                : `${p.error}✗ exit ${exitCode}${p.reset}${summary}${timer}`;
+        const mark = ctx.call("tui:render-tool-complete", exitCode, elapsed, resultDisplay?.summary);
         if (s.toolLineOpen && s.commandOutputLineCount === 0) {
             writer.write(` ${mark}\n`);
             s.toolLineOpen = false;
@@ -700,7 +744,10 @@ export default function activate(ctx) {
         s.spinner = createSpinner({ startTime: s.spinnerStartTime });
         s.spinnerInterval = setInterval(() => {
             if (s.spinner) {
-                const line = renderSpinnerLine(s.spinner, s.spinnerLabel, s.spinnerOpts);
+                const frame = SPINNER_FRAMES[s.spinner.frame % SPINNER_FRAMES.length];
+                s.spinner.frame++;
+                const elapsed = formatElapsed(Date.now() - s.spinner.startTime);
+                const line = ctx.call("tui:render-spinner", s.spinnerLabel, frame, elapsed, s.spinnerOpts.hint);
                 writer.write(`\r  ${line}\x1b[K`);
             }
         }, 80);
@@ -734,20 +781,8 @@ export default function activate(ctx) {
         closeToolLine();
         if (!s.renderer)
             startAgentResponse();
-        const mark = s.toolGroupAllOk
-            ? `${p.success}✓${p.reset}`
-            : `${p.error}✗${p.reset}`;
-        const summary = s.toolGroupSummaries.length > 0
-            ? ` ${p.dim}${s.toolGroupSummaries.join(", ")}${p.reset}`
-            : "";
-        const collapsed = s.toolGroupCount - s.toolGroupRendered;
-        if (collapsed > 0) {
-            s.renderer.writeLine(`  ${p.muted}└${p.reset} ${p.dim}+${collapsed} more${p.reset} ${mark}${summary}`);
-        }
-        else {
-            // All items visible — close the tree with └ mark + summary
-            s.renderer.writeLine(`  ${p.muted}└${p.reset} ${mark}${summary}`);
-        }
+        const groupLine = ctx.call("tui:render-tool-group-summary", s.toolGroupCount, s.toolGroupRendered, s.toolGroupAllOk, s.toolGroupSummaries);
+        s.renderer.writeLine(groupLine);
         drain();
         s.toolGroupKind = undefined;
         s.toolGroupCount = 0;
@@ -755,6 +790,9 @@ export default function activate(ctx) {
         s.toolGroupRendered = 0;
         s.toolGroupSummaries = [];
     }
+    function renderCommandLine(line) {
+        return ctx.call("tui:render-command-output", line, s.currentToolKind);
+    }
     function writeCommandOutput(chunk) {
         if (!s.renderer)
             return;
@@ -767,7 +805,7 @@ export default function activate(ctx) {
         s.commandOutputBuffer = lines.pop();
         for (const line of lines) {
             if (s.commandOutputLineCount < maxLines) {
-                s.renderer.writeLine(`${p.dim}  ${line}${p.reset}`);
+                s.renderer.writeLine(renderCommandLine(line));
                 s.commandOutputLineCount++;
             }
             else {
@@ -787,7 +825,7 @@ export default function activate(ctx) {
             : getSettings().maxCommandOutputLines;
         if (s.commandOutputBuffer) {
             if (s.commandOutputLineCount < maxLines) {
-                s.renderer.writeLine(`${p.dim}  ${s.commandOutputBuffer}${p.reset}`);
+                s.renderer.writeLine(renderCommandLine(s.commandOutputBuffer));
                 s.commandOutputLineCount++;
             }
             else {
@@ -802,14 +840,14 @@ export default function activate(ctx) {
             const tail = s.commandOverflowLines.slice(-FAIL_OVERFLOW_MAX);
             const skipped = s.commandOverflowLines.length - tail.length;
             if (skipped > 0) {
-                s.renderer.writeLine(`${p.dim}  … ${skipped} lines hidden${p.reset}`);
+                s.renderer.writeLine(renderCommandLine(`… ${skipped} lines hidden`));
             }
             for (const line of tail) {
-                s.renderer.writeLine(`${p.dim}  ${line}${p.reset}`);
+                s.renderer.writeLine(renderCommandLine(line));
             }
         }
         else if (s.commandOutputOverflow > 0 && maxLines > 0) {
-            s.renderer.writeLine(`${p.dim}  … ${s.commandOutputOverflow} more lines${p.reset}`);
+            s.renderer.writeLine(renderCommandLine(`… ${s.commandOutputOverflow} more lines`));
         }
         s.commandOutputOverflow = 0;
         s.commandOverflowLines = [];
@@ -911,9 +949,9 @@ export default function activate(ctx) {
         }
     }
     function showError(message) {
-        writer.write(`\n${p.error}Error: ${message}${p.reset}\n`);
+        writer.write("\n" + ctx.call("tui:render-error", message) + "\n");
     }
     function showInfo(message) {
-        writer.write(`${p.muted}${message}${p.reset}\n`);
+        writer.write(ctx.call("tui:render-info", message) + "\n");
     }
 }

package/dist/index.js

@@ -9,6 +9,8 @@ import slashCommands from "./extensions/slash-commands.js";
 import fileAutocomplete from "./extensions/file-autocomplete.js";
 import shellRecall from "./extensions/shell-recall.js";
 import commandSuggest from "./extensions/command-suggest.js";
+import terminalBuffer from "./extensions/terminal-buffer.js";
+import overlayAgent from "./extensions/overlay-agent.js";
 import { loadExtensions } from "./extension-loader.js";
 import { getSettings } from "./settings.js";
 import { discoverSkills } from "./agent/skills.js";
@@ -232,6 +234,8 @@ async function main() {
     fileAutocomplete(extCtx);
     shellRecall(extCtx);
     commandSuggest(extCtx);
+    terminalBuffer(extCtx);
+    overlayAgent(extCtx);
     // Load user extensions (may register alternative agent backends)
     if (process.env.DEBUG) {
         console.error('[agent-sh] Loading extensions...');

package/dist/input-handler.js

@@ -137,6 +137,10 @@ export class InputHandler {
         }
     }
     handleInput(data) {
+        // Allow extensions to capture raw input (e.g. overlay prompt during vim)
+        const intercepted = this.bus.emitPipe("input:intercept", { data, consumed: false });
+        if (intercepted.consumed)
+            return;
         // If agent is running (processing a query), only Ctrl-C and control keys
         if (this.ctx.isAgentActive()) {
             if (data === "\x03") {
@@ -235,7 +239,8 @@ export class InputHandler {
                     this.enterMode(mode);
                     return; // don't process remaining chars
                 }
-                this.lineBuffer += ch;
+                if (!this.ctx.isForegroundBusy())
+                    this.lineBuffer += ch;
                 this.ctx.writeToPty(ch);
             }
         }

package/dist/output-parser.js

@@ -109,7 +109,15 @@ export class OutputParser {
             this.currentOutputCapture = "";
         }
         else {
+            // Cap capture buffer to avoid unbounded growth when a foreground
+            // program (tmux, vim, etc.) produces output without prompt markers.
+            // Keep only the tail — the final output is what matters for
+            // command-done context.
+            const MAX_CAPTURE = 128 * 1024; // 128 KB
             this.currentOutputCapture += data;
+            if (this.currentOutputCapture.length > MAX_CAPTURE) {
+                this.currentOutputCapture = this.currentOutputCapture.slice(-MAX_CAPTURE);
+            }
         }
     }
     /**

package/dist/settings.d.ts

@@ -1,4 +1,13 @@
 export declare const CONFIG_DIR: string;
+/** Per-model capability overrides. */
+export interface ModelCapabilityConfig {
+    /** Model identifier. */
+    id: string;
+    /** Whether the model supports reasoning/thinking tokens. */
+    reasoning?: boolean;
+    /** Context window size in tokens for this specific model. */
+    contextWindow?: number;
+}
 /** Provider profile — a named LLM configuration. */
 export interface ProviderConfig {
     /** API key (supports $ENV_VAR syntax for runtime expansion). */
@@ -7,8 +16,8 @@ export interface ProviderConfig {
     baseURL?: string;
     /** Default model to use. Falls back to first entry in models list. */
     defaultModel?: string;
-    /** Models available for cycling. */
-    models?: string[];
+    /** Models available for cycling. Plain strings or objects with capabilities. */
+    models?: (string | ModelCapabilityConfig)[];
     /** Context window size in tokens (e.g. 128000). Used for usage display. */
     contextWindow?: number;
 }
@@ -35,6 +44,14 @@ export interface Settings {
     shellTailLines?: number;
     /** Max lines for recall expand before requiring line ranges. */
     recallExpandMaxLines?: number;
+    /** Fraction of content budget allocated to shell context (0-1, default 0.35). */
+    shellContextRatio?: number;
+    /** Max history file size in bytes (default: 102400 = 100KB). */
+    historyMaxBytes?: number;
+    /** Number of prior history entries to load on startup (default: 50). */
+    historyStartupEntries?: number;
+    /** Max nuclear entries kept in-context before flushing to history file (default: 200). */
+    nuclearMaxEntries?: number;
     /** Max command output lines shown inline in TUI. */
     maxCommandOutputLines?: number;
     /** Max read tool output lines shown inline in TUI (0 = hide). */

package/dist/settings.js

@@ -21,6 +21,10 @@ const DEFAULTS = {
     shellHeadLines: 5,
     shellTailLines: 5,
     recallExpandMaxLines: 100,
+    shellContextRatio: 0.35,
+    historyMaxBytes: 102400,
+    historyStartupEntries: 50,
+    nuclearMaxEntries: 200,
     maxCommandOutputLines: 3,
     readOutputMaxLines: 10,
     diffMaxLines: 20,
@@ -86,15 +90,29 @@ export function resolveProvider(name) {
     const provider = settings.providers?.[name];
     if (!provider)
         return null;
-    const models = provider.models ?? (provider.defaultModel ? [provider.defaultModel] : []);
-    const defaultModel = provider.defaultModel ?? models[0];
+    const rawModels = provider.models ?? (provider.defaultModel ? [provider.defaultModel] : []);
+    const modelIds = [];
+    const caps = new Map();
+    for (const m of rawModels) {
+        if (typeof m === "string") {
+            modelIds.push(m);
+        }
+        else {
+            modelIds.push(m.id);
+            if (m.reasoning !== undefined || m.contextWindow !== undefined) {
+                caps.set(m.id, { reasoning: m.reasoning, contextWindow: m.contextWindow });
+            }
+        }
+    }
+    const defaultModel = provider.defaultModel ?? modelIds[0];
     return {
         id: name,
         apiKey: provider.apiKey ? expandEnvVars(provider.apiKey) : undefined,
         baseURL: provider.baseURL,
         defaultModel,
-        models: models.length ? models : (defaultModel ? [defaultModel] : []),
+        models: modelIds.length ? modelIds : (defaultModel ? [defaultModel] : []),
         contextWindow: provider.contextWindow,
+        modelCapabilities: caps.size > 0 ? caps : undefined,
     };
 }
 /** Get all configured provider names. */

package/dist/shell.d.ts

@@ -6,6 +6,8 @@ export declare class Shell implements InputContext {
     private inputHandler;
     private outputParser;
     private paused;
+    private stdoutHold;
+    private stdoutShow;
     private echoSkip;
     private agentActive;
     private isZsh;
@@ -37,6 +39,9 @@ export declare class Shell implements InputContext {
      * Heavy redraw: send \n to PTY to trigger a full precmd → prompt cycle.
      * Use this after agent responses where stdout has moved far from where
      * zle expects the cursor. The blank line is acceptable as a separator.
+     *
+     * Routed through shell:redraw-prompt pipe so extensions (e.g. overlay)
+     * can suppress it by setting `handled: true`.
      */
     freshPrompt(): void;
     onCommandEntered(command: string, cwd: string): void;

package/dist/shell.js

@@ -5,12 +5,15 @@ 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/output-writer.js";
 export class Shell {
     ptyProcess;
     bus;
     inputHandler;
     outputParser;
     paused = false;
+    stdoutHold = new RefCounter();
+    stdoutShow = new RefCounter();
     echoSkip = false;
     agentActive = false;
     isZsh = false;
@@ -156,6 +159,20 @@ export class Shell {
         this.setupOutput();
         this.setupInput();
         this.setupAgentLifecycle();
+        // Allow extensions to inject raw keystrokes into the PTY
+        this.bus.on("shell:pty-write", ({ data }) => {
+            this.ptyProcess.write(data);
+        });
+        // Allow extensions to resize the PTY (sends SIGWINCH to child)
+        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(); });
     }
     // ── InputContext implementation (delegates to OutputParser) ──
     isForegroundBusy() {
@@ -197,9 +214,18 @@ export class Shell {
      * Heavy redraw: send \n to PTY to trigger a full precmd → prompt cycle.
      * Use this after agent responses where stdout has moved far from where
      * zle expects the cursor. The blank line is acceptable as a separator.
+     *
+     * Routed through shell:redraw-prompt pipe so extensions (e.g. overlay)
+     * can suppress it by setting `handled: true`.
      */
     freshPrompt() {
-        this.ptyProcess.write("\n");
+        const result = this.bus.emitPipe("shell:redraw-prompt", {
+            cwd: this.outputParser.getCwd(),
+            handled: false,
+        });
+        if (!result.handled) {
+            this.ptyProcess.write("\n");
+        }
     }
     onCommandEntered(command, cwd) {
         this.outputParser.onCommandEntered(command, cwd);
@@ -207,8 +233,11 @@ export class Shell {
     // ── PTY I/O wiring ─────────────────────────────────────────
     setupOutput() {
         this.ptyProcess.onData((data) => {
+            this.bus.emit("shell:pty-data", { raw: data });
             this.outputParser.processData(data);
-            if (this.paused)
+            if (this.stdoutHold.active)
+                return;
+            if (this.paused && !this.stdoutShow.active)
                 return;
             // During user_shell exec, skip the command echo (first line)
             if (this.echoSkip) {

package/dist/token-budget.d.ts

@@ -0,0 +1,13 @@
+export declare class TokenBudget {
+    private contextWindow;
+    private toolCount;
+    constructor(contextWindow?: number, toolCount?: number);
+    /** Update when model or tool set changes. */
+    update(contextWindow?: number, toolCount?: number): void;
+    /** Total tokens available for shell context + conversation content. */
+    get contentBudget(): number;
+    /** Token budget for the shell context stream. */
+    get shellBudgetTokens(): number;
+    /** Token budget for the conversation messages stream. */
+    get conversationBudgetTokens(): number;
+}