agent-sh 0.2.0 → 0.3.1

package/README.md

@@ -77,6 +77,7 @@ See the [Usage Guide](docs/usage.md) for all options, model configuration, and e
 | `Ctrl-C` | Standard signal to shell, or cancels active agent response |
 | `Ctrl-O` | Expand/collapse truncated diff preview |
 | `Ctrl-T` | Toggle thinking/reasoning text display |
+| `Shift-Tab` | Cycle thinking level (off → minimal → low → medium → high → xhigh) |
 | `Escape` | Exit agent input mode (when typing after `>`) |
 
 ### Agent Input Keybindings
@@ -85,6 +86,10 @@ When typing after `>`, full readline-style keybindings are available:
 
 | Key | Action |
 |---|---|
+| `↑` / `↓` | Browse query history (persisted across sessions) |
+| `Shift-Enter` | Insert newline (multiline input) |
+| `Shift-Tab` | Cycle thinking level |
+| `Ctrl-D` | Exit agent input mode (on empty line) |
 | `Ctrl-A` / `Home` | Move to start of line |
 | `Ctrl-E` / `End` | Move to end of line |
 | `Ctrl-B` / `←` | Move back one character |
@@ -96,6 +101,16 @@ When typing after `>`, full readline-style keybindings are available:
 | `Ctrl-W` / `Option-Backspace` | Delete word backward |
 | `Option-D` | Delete word forward |
 
+### Thinking Level
+
+The agent prompt shows the current thinking level next to the model name:
+
+```
+pi (claude-3.5-sonnet) [medium] ● ❯
+```
+
+Press **Shift-Tab** in agent input mode to cycle through levels. The levels are advertised by the agent via ACP session modes — different agents may offer different options. The spinner label reflects the mode: "Thinking" when thinking is enabled, "Working" when it's off.
+
 ### Slash Commands
 
 | Command | Description |
@@ -106,6 +121,12 @@ When typing after `>`, full readline-style keybindings are available:
 | `/compact` | Ask agent to summarize the conversation |
 | `/quit` | Exit agent-sh |
 
+## Configuration
+
+agent-sh stores settings and history in `~/.agent-sh/`. Behavior is configurable via `~/.agent-sh/settings.json` — context window size, truncation thresholds, display limits, and more. All fields are optional with sensible defaults.
+
+See the [Usage Guide](docs/usage.md#configuration) for the full settings reference.
+
 ## Development
 
 ```bash

package/dist/acp-client.d.ts

@@ -16,8 +16,11 @@ export declare class AcpClient {
     private terminalCounter;
     private fileWatcher;
     private pendingToolCalls;
+    private autoCancelled;
     private pendingToolCounter;
     private agentInfo;
+    private modes;
+    private currentModeId;
     constructor(opts: {
         bus: EventBus;
         contextManager: ContextManager;
@@ -28,6 +31,12 @@ export declare class AcpClient {
      * Send a user query to the agent.
      */
     sendPrompt(query: string): Promise<void>;
+    /**
+     * Silently cancel the prompt after a shell tool completes.
+     * Unlike user-initiated cancel(), this doesn't show "(cancelled)" —
+     * the tool already ran, we just skip the unnecessary LLM follow-up.
+     */
+    private autoCancel;
     /**
      * Cancel the current prompt and force-recover shell mode.
      */
@@ -48,10 +57,25 @@ export declare class AcpClient {
         version: string;
     } | null;
     getModel(): string | undefined;
+    /**
+     * Get the current mode (e.g. thinking level).
+     */
+    getCurrentMode(): {
+        id: string;
+        name: string;
+    } | null;
     /**
      * Check if agent is connected.
      */
     isConnected(): boolean;
+    /**
+     * Parse modes from a session response and notify listeners.
+     */
+    private updateModes;
+    /**
+     * Cycle to the next session mode.
+     */
+    private cycleMode;
     private log;
     /**
      * Create the Client handler that responds to agent requests.

package/dist/acp-client.js

@@ -22,8 +22,11 @@ export class AcpClient {
     terminalCounter = 0;
     fileWatcher;
     pendingToolCalls = new Map();
+    autoCancelled = false;
     pendingToolCounter = 0;
     agentInfo = null;
+    modes = [];
+    currentModeId = null;
     constructor(opts) {
         this.bus = opts.bus;
         this.contextManager = opts.contextManager;
@@ -33,8 +36,16 @@ export class AcpClient {
     async start() {
         this.log(`Starting agent: ${this.config.agentCommand} ${this.config.agentArgs.join(" ")}`);
         // Spawn the agent subprocess with the user's full shell environment
-        // (includes vars from .zshrc/.bashrc that process.env may not have)
-        const agentEnv = this.config.shellEnv ?? process.env;
+        // (includes vars from .zshrc/.bashrc that process.env may not have).
+        // Merge in any runtime env vars set by extensions (e.g. AGENT_SH_SOCKET)
+        // that weren't present when shellEnv was captured at startup.
+        const baseEnv = this.config.shellEnv ?? process.env;
+        const agentEnv = { ...baseEnv };
+        for (const [k, v] of Object.entries(process.env)) {
+            if (v !== undefined && !(k in agentEnv)) {
+                agentEnv[k] = v;
+            }
+        }
         this.agentProcess = spawn(this.config.agentCommand, this.config.agentArgs, {
             stdio: ["pipe", "pipe", process.env.DEBUG ? "inherit" : "ignore"],
             env: agentEnv,
@@ -67,19 +78,23 @@ export class AcpClient {
         this.log("Creating ACP connection");
         // Create the client-side connection, providing our Client handler
         this.connection = new acp.ClientSideConnection((_agent) => this.createClientHandler(), stream);
-        // Initialize the connection
+        // Initialize the connection with timeout
         this.log("Sending initialize request");
-        const initResponse = await this.connection.initialize({
-            protocolVersion: acp.PROTOCOL_VERSION,
-            clientInfo: { name: "agent-sh", version: "0.1.0" },
-            clientCapabilities: {
-                terminal: true,
-                fs: {
-                    readTextFile: true,
-                    writeTextFile: true,
+        const initTimeoutMs = 30000; // 30 seconds
+        const initResponse = await Promise.race([
+            this.connection.initialize({
+                protocolVersion: acp.PROTOCOL_VERSION,
+                clientInfo: { name: "agent-sh", version: "0.1.0" },
+                clientCapabilities: {
+                    terminal: true,
+                    fs: {
+                        readTextFile: true,
+                        writeTextFile: true,
+                    },
                 },
-            },
-        });
+            }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Initialize timeout after ${initTimeoutMs}ms`)), initTimeoutMs)),
+        ]);
         this.log("Initialize successful");
         // Store agent info for display
         if (initResponse.agentInfo) {
@@ -96,12 +111,20 @@ export class AcpClient {
             cwd,
             mcpServers: [],
         });
-        const sessionResponse = await this.connection.newSession({
-            cwd: sessionConfig.cwd,
-            mcpServers: sessionConfig.mcpServers,
-        });
+        const sessionTimeoutMs = 30000; // 30 seconds
+        const sessionResponse = await Promise.race([
+            this.connection.newSession({
+                cwd: sessionConfig.cwd,
+                mcpServers: sessionConfig.mcpServers,
+            }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`newSession timeout after ${sessionTimeoutMs}ms`)), sessionTimeoutMs)),
+        ]);
         this.sessionId = sessionResponse.sessionId;
         this.log(`Session created: ${this.sessionId}`);
+        // Parse session modes (thinking level, etc.)
+        this.updateModes(sessionResponse);
+        // Listen for mode cycle requests from input handler
+        this.bus.on("config:cycle", () => this.cycleMode());
     }
     /**
      * Send a user query to the agent.
@@ -115,6 +138,7 @@ export class AcpClient {
         this.bus.emit("agent:processing-start", {});
         await this.fileWatcher.snapshot();
         this.currentResponseText = "";
+        this.autoCancelled = false;
         let cancelled = false;
         // Emit agent query event (TUI renders echo+spinner, ContextManager records it)
         this.bus.emit("agent:query", { query });
@@ -134,7 +158,9 @@ export class AcpClient {
             this.log(`prompt resolved: stopReason=${response.stopReason}`);
             if (response.stopReason === "cancelled") {
                 cancelled = true;
-                this.bus.emit("agent:cancelled", {});
+                if (!this.autoCancelled) {
+                    this.bus.emit("agent:cancelled", {});
+                }
             }
         }
         catch (err) {
@@ -146,7 +172,7 @@ export class AcpClient {
         finally {
             this.log("restoring shell mode");
             if (!cancelled) {
-                this.bus.emit("agent:response-done", {
+                this.bus.emitTransform("agent:response-done", {
                     response: this.currentResponseText,
                 });
             }
@@ -160,6 +186,18 @@ export class AcpClient {
             this.promptInProgress = false;
         }
     }
+    /**
+     * Silently cancel the prompt after a shell tool completes.
+     * Unlike user-initiated cancel(), this doesn't show "(cancelled)" —
+     * the tool already ran, we just skip the unnecessary LLM follow-up.
+     */
+    autoCancel() {
+        if (!this.connection || !this.sessionId || !this.promptInProgress)
+            return;
+        this.log("auto-cancel: shell tool completed, skipping LLM follow-up");
+        this.autoCancelled = true;
+        this.connection.cancel({ sessionId: this.sessionId }).catch(() => { });
+    }
     /**
      * Cancel the current prompt and force-recover shell mode.
      */
@@ -202,6 +240,7 @@ export class AcpClient {
         this.sessionId = sessionResponse.sessionId;
         this.lastResponseText = "";
         this.currentResponseText = "";
+        this.updateModes(sessionResponse);
     }
     /**
      * Get the text of the last agent response (for /copy).
@@ -218,6 +257,14 @@ export class AcpClient {
     getModel() {
         return this.config.model;
     }
+    /**
+     * Get the current mode (e.g. thinking level).
+     */
+    getCurrentMode() {
+        if (!this.currentModeId)
+            return null;
+        return this.modes.find((m) => m.id === this.currentModeId) ?? null;
+    }
     /**
      * Check if agent is connected.
      */
@@ -226,6 +273,45 @@ export class AcpClient {
         // Session ID may not be set yet if we're still initializing
         return this.connection !== null && this.agentInfo !== null;
     }
+    /**
+     * Parse modes from a session response and notify listeners.
+     */
+    updateModes(response) {
+        const modes = response.modes;
+        if (!modes)
+            return;
+        if (modes.availableModes) {
+            this.modes = modes.availableModes.map((m) => ({
+                id: m.id,
+                name: m.name || m.id,
+            }));
+        }
+        if (modes.currentModeId) {
+            this.currentModeId = modes.currentModeId;
+        }
+        this.bus.emit("config:changed", {});
+    }
+    /**
+     * Cycle to the next session mode.
+     */
+    async cycleMode() {
+        if (!this.connection || !this.sessionId || this.modes.length === 0)
+            return;
+        const currentIdx = this.modes.findIndex((m) => m.id === this.currentModeId);
+        const nextIdx = (currentIdx + 1) % this.modes.length;
+        const nextMode = this.modes[nextIdx];
+        try {
+            await this.connection.setSessionMode({
+                sessionId: this.sessionId,
+                modeId: nextMode.id,
+            });
+            this.currentModeId = nextMode.id;
+            this.bus.emit("config:changed", {});
+        }
+        catch (err) {
+            this.log(`Failed to set mode: ${err}`);
+        }
+    }
     log(msg) {
         if (process.env.DEBUG) {
             process.stderr.write(`[agent-sh] ${msg}\n`);
@@ -237,8 +323,15 @@ export class AcpClient {
     createClientHandler() {
         return {
             // Required: handle session update notifications (streaming)
+            // Errors must not propagate — the ACP SDK returns them as error
+            // responses to the agent, which can stall the stream.
             sessionUpdate: async (params) => {
-                this.handleSessionUpdate(params);
+                try {
+                    this.handleSessionUpdate(params);
+                }
+                catch (err) {
+                    this.log(`Error in sessionUpdate handler: ${err instanceof Error ? err.stack : err}`);
+                }
             },
             // Required: handle permission requests
             requestPermission: async (params) => {
@@ -280,40 +373,56 @@ export class AcpClient {
                 const content = update.content;
                 if (content.type === "text") {
                     this.currentResponseText += content.text;
-                    this.bus.emit("agent:response-chunk", { text: content.text });
+                    this.bus.emitTransform("agent:response-chunk", { text: content.text });
                 }
                 break;
             }
             case "agent_thought_chunk": {
                 const thought = update.content;
                 if (thought.type === "text" && thought.text) {
-                    this.bus.emit("agent:thinking-chunk", { text: thought.text });
+                    this.bus.emitTransform("agent:thinking-chunk", { text: thought.text });
                 }
                 break;
             }
             case "tool_call": {
                 const toolId = update.toolCallId || `tool-${this.pendingToolCounter++}`;
-                this.pendingToolCalls.set(toolId, true);
-                this.bus.emit("agent:tool-started", {
+                const payload = {
                     title: update.title,
                     toolCallId: toolId,
                     kind: update.kind ?? undefined,
                     locations: update.locations?.map((l) => ({ path: l.path, line: l.line })),
                     rawInput: update.rawInput,
+                };
+                const defer = this.pendingToolCalls.size > 0;
+                this.pendingToolCalls.set(toolId, {
+                    title: update.title ?? "",
+                    deferredPayload: defer ? payload : undefined,
                 });
+                if (!defer) {
+                    this.bus.emit("agent:tool-started", payload);
+                }
                 break;
             }
             case "tool_call_update": {
-                // Stream tool output content (text from pi's internal tool results)
-                if (update.content && Array.isArray(update.content)) {
-                    for (const block of update.content) {
-                        if (block.type === "content" && block.content?.type === "text" && block.content.text) {
-                            this.bus.emit("agent:tool-output-chunk", { chunk: block.content.text });
+                const toolId = update.toolCallId;
+                const toolInfo = toolId ? this.pendingToolCalls.get(toolId) : undefined;
+                const toolTitle = toolInfo?.title;
+                if (update.status === "completed" || update.status === "failed") {
+                    // Emit deferred tool-started before output (parallel tools)
+                    if (toolInfo?.deferredPayload) {
+                        this.bus.emit("agent:tool-started", toolInfo.deferredPayload);
+                        toolInfo.deferredPayload = undefined;
+                    }
+                    // Show content only on final status. Skip tools whose output the
+                    // user already sees (user_shell → PTY) or is agent-only (shell_recall).
+                    const skipOutput = toolTitle === "user_shell" || toolTitle === "shell_recall";
+                    if (!skipOutput && update.content && Array.isArray(update.content)) {
+                        for (const block of update.content) {
+                            if (block.type === "content" && block.content?.type === "text" && block.content.text) {
+                                this.bus.emitTransform("agent:tool-output-chunk", { chunk: block.content.text });
+                            }
                         }
                     }
-                }
-                if (update.status === "completed" || update.status === "failed") {
-                    const toolId = update.toolCallId;
                     const exitCode = update.status === "completed" ? 0 : 1;
                     if (toolId && this.pendingToolCalls.has(toolId)) {
                         this.pendingToolCalls.delete(toolId);
@@ -326,11 +435,24 @@ export class AcpClient {
                     else if (!toolId) {
                         this.bus.emit("agent:tool-completed", { exitCode, rawOutput: update.rawOutput });
                     }
+                    // Auto-cancel after shell tools complete — the command already
+                    // ran in the user's PTY, no need for a second LLM round trip.
+                    // The result is captured in shell context / shell_recall.
+                    if (toolTitle === "user_shell" && update.status === "completed") {
+                        this.autoCancel();
+                    }
+                }
+                break;
+            }
+            case "current_mode_update": {
+                const modeId = update.currentModeId;
+                if (modeId) {
+                    this.currentModeId = modeId;
+                    this.bus.emit("config:changed", {});
                 }
                 break;
             }
             default:
-                // Ignore other update types for now
                 break;
         }
     }

package/dist/context-manager.d.ts

@@ -5,6 +5,8 @@ export declare class ContextManager {
     private currentCwd;
     private sessionStart;
     private pendingToolCalls;
+    private firstPrompt;
+    private agentShellActive;
     constructor(bus: EventBus);
     getCwd(): string;
     /**
@@ -17,9 +19,10 @@ export declare class ContextManager {
      */
     search(query: string): string;
     /**
-     * Return full untruncated content for specific exchange IDs.
+     * Return content for specific exchange IDs.
+     * Optional start/end restrict to a line range (1-indexed).
      */
-    expand(ids: number[]): string;
+    expand(ids: number[], start?: number, end?: number): string;
     /**
      * One-line summaries of last N exchanges.
      */
@@ -37,7 +40,6 @@ export declare class ContextManager {
     private formatContext;
     private addExchange;
     private formatExchangeTruncated;
-    private truncateForRecall;
     private formatExchangeFull;
     private exchangeOneLiner;
     private exchangeSearchText;

package/dist/context-manager.js

@@ -1,21 +1,18 @@
-const DEFAULT_WINDOW_SIZE = 20;
-const DEFAULT_BUDGET = 16384; // ~4K tokens at ~4 chars/token
-// Truncation thresholds (in lines)
-const SHELL_TRUNCATE_THRESHOLD = 30;
-const SHELL_HEAD_LINES = 10;
-const SHELL_TAIL_LINES = 10;
+import { getSettings } from "./settings.js";
+// Non-configurable thresholds (agent response and tool output follow shell settings)
 const AGENT_RESPONSE_TRUNCATE_THRESHOLD = 20;
 const AGENT_RESPONSE_HEAD_LINES = 15;
 const TOOL_TRUNCATE_THRESHOLD = 20;
 const TOOL_HEAD_LINES = 5;
 const TOOL_TAIL_LINES = 5;
-const RECALL_EXPAND_MAX_LINES = 500;
 export class ContextManager {
     exchanges = [];
     nextId = 1;
     currentCwd;
     sessionStart;
     pendingToolCalls = [];
+    firstPrompt = true;
+    agentShellActive = false; // true while user_shell command is executing
     constructor(bus) {
         this.currentCwd = process.cwd();
         this.sessionStart = Date.now();
@@ -30,11 +27,15 @@ export class ContextManager {
                 exitCode: e.exitCode,
                 outputLines: lines.length,
                 outputBytes: e.output.length,
+                source: this.agentShellActive ? "agent" : "user",
             });
         });
         bus.on("shell:cwd-change", (e) => {
             this.currentCwd = e.cwd;
         });
+        // Track agent-initiated shell commands (user_shell tool)
+        bus.on("shell:agent-exec-start", () => { this.agentShellActive = true; });
+        bus.on("shell:agent-exec-done", () => { this.agentShellActive = false; });
         // ── Subscribe to agent events ──
         bus.on("agent:query", (e) => {
             this.pendingToolCalls = [];
@@ -85,7 +86,8 @@ export class ContextManager {
      * Build the <shell_context> block for the agent prompt.
      * Pipeline: window → truncate → format
      */
-    getContext(budget = DEFAULT_BUDGET) {
+    getContext(budget) {
+        budget ??= getSettings().contextBudget;
         let exchanges = this.applyWindow(this.exchanges);
         exchanges = this.applyTruncation(exchanges, budget);
         return this.formatContext(exchanges);
@@ -141,9 +143,10 @@ export class ContextManager {
         return parts.join("\n");
     }
     /**
-     * Return full untruncated content for specific exchange IDs.
+     * Return content for specific exchange IDs.
+     * Optional start/end restrict to a line range (1-indexed).
      */
-    expand(ids) {
+    expand(ids, start, end) {
         const results = [];
         for (const id of ids) {
             const ex = this.exchanges.find((e) => e.id === id);
@@ -151,7 +154,25 @@ export class ContextManager {
                 results.push(`#${id}: not found`);
                 continue;
             }
-            results.push(this.formatExchangeFull(ex));
+            const text = this.formatExchangeFull(ex);
+            const lines = text.split("\n");
+            const total = lines.length;
+            if (start != null || end != null) {
+                // Line range requested
+                const s = Math.max(0, (start ?? 1) - 1);
+                const e = end ?? total;
+                results.push(lines.slice(s, e).join("\n") +
+                    `\n[showing lines ${s + 1}-${Math.min(e, total)} of ${total}]`);
+            }
+            else if (total > getSettings().recallExpandMaxLines) {
+                // Too large — tell the agent to narrow down
+                results.push(`#${ex.id}: output is ${total} lines, too large to expand fully. ` +
+                    `Use start/end params to select a line range (e.g. start=1, end=50), ` +
+                    `or use search with a regex to find specific content.`);
+            }
+            else {
+                results.push(text);
+            }
         }
         return results.join("\n\n");
     }
@@ -205,10 +226,12 @@ export class ContextManager {
     clear() {
         this.exchanges = [];
         this.pendingToolCalls = [];
+        this.firstPrompt = true;
         // Don't reset nextId — IDs should be globally unique within a session
     }
     // ── Pipeline stages ───────────────────────────────────────────
-    applyWindow(exchanges, windowSize = DEFAULT_WINDOW_SIZE) {
+    applyWindow(exchanges, windowSize) {
+        windowSize ??= getSettings().contextWindowSize;
         return exchanges.slice(-windowSize);
     }
     applyTruncation(exchanges, budget) {
@@ -217,7 +240,8 @@ export class ContextManager {
         // Pass 1: per-type truncation
         for (const ex of result) {
             if (ex.type === "shell_command") {
-                ex.output = truncateOutput(ex.output, SHELL_TRUNCATE_THRESHOLD, SHELL_HEAD_LINES, SHELL_TAIL_LINES, ex.id);
+                const s = getSettings();
+                ex.output = truncateOutput(ex.output, s.shellTruncateThreshold, s.shellHeadLines, s.shellTailLines, ex.id);
             }
             else if (ex.type === "agent_response") {
                 ex.response = truncateHead(ex.response, AGENT_RESPONSE_TRUNCATE_THRESHOLD, AGENT_RESPONSE_HEAD_LINES, ex.id);
@@ -248,9 +272,22 @@ export class ContextManager {
         const elapsed = Math.round((Date.now() - this.sessionStart) / 60000);
         const totalCount = this.exchanges.length;
         let out = "<shell_context>\n";
+        if (this.firstPrompt) {
+            out += `You are an AI assistant living inside agent-sh, a shell-first terminal.\n`;
+            out += `The user interacts with a real shell (PTY) and sends you queries inline. You are there to help them with their tasks.\n`;
+            out += `\n`;
+            out += `IMPORTANT tool usage rules:\n`;
+            out += `- user_shell runs commands in the user's live shell (PTY). The user sees output directly — no summary needed.\n`;
+            out += `- Your internal tools (bash, read, write, ls, etc.) run in an isolated subprocess. The user CANNOT see their output.\n`;
+            out += `- When the user asks to see, list, view, or display anything, ALWAYS use user_shell. NEVER use internal tools like ls/read/bash for display — the user won't see it.\n`;
+            out += `- Only use internal tools when YOU need to reason about content silently (e.g. reading a file to answer a question about it).\n`;
+            out += `- After a user_shell command, the user already saw the output. Do NOT repeat or summarize it.\n`;
+            out += `- You can browse or search session history with shell_recall.\n`;
+            out += `\n`;
+            this.firstPrompt = false;
+        }
         out += `cwd: ${this.currentCwd}\n`;
         out += `session: ${totalCount} exchanges, ${elapsed}m elapsed\n`;
-        out += `[hint: use the shell_recall tool to retrieve truncated content — search(query) or expand(ids)]\n`;
         for (const ex of exchanges) {
             out += "\n" + this.formatExchangeTruncated(ex);
         }
@@ -269,7 +306,8 @@ export class ContextManager {
     formatExchangeTruncated(ex) {
         switch (ex.type) {
             case "shell_command": {
-                let s = `#${ex.id} [shell] $ ${ex.command}\n`;
+                const label = ex.source === "agent" ? "agent → shell" : "shell";
+                let s = `#${ex.id} [${label} cwd:${ex.cwd}] $ ${ex.command}\n`;
                 if (ex.output)
                     s += indent(ex.output, "  ") + "\n";
                 if (ex.exitCode !== null)
@@ -299,20 +337,12 @@ export class ContextManager {
             }
         }
     }
-    truncateForRecall(text) {
-        const lines = text.split("\n");
-        if (lines.length <= RECALL_EXPAND_MAX_LINES)
-            return text;
-        const half = RECALL_EXPAND_MAX_LINES / 2;
-        return (lines.slice(0, half).join("\n") +
-            `\n[... ${lines.length - RECALL_EXPAND_MAX_LINES} more lines ...]\n` +
-            lines.slice(-half).join("\n"));
-    }
     formatExchangeFull(ex) {
         switch (ex.type) {
             case "shell_command": {
-                const output = this.truncateForRecall(ex.output);
-                let s = `#${ex.id} [shell] $ ${ex.command} (${ex.outputLines} lines, ${ex.outputBytes} bytes)\n`;
+                const label = ex.source === "agent" ? "agent → shell" : "shell";
+                const output = ex.output;
+                let s = `#${ex.id} [${label}] $ ${ex.command} (${ex.outputLines} lines, ${ex.outputBytes} bytes)\n`;
                 if (output)
                     s += output + "\n";
                 if (ex.exitCode !== null)
@@ -324,10 +354,9 @@ export class ContextManager {
             case "agent_response":
                 return `#${ex.id} [agent]\n${ex.response}`;
             case "tool_execution": {
-                const output = this.truncateForRecall(ex.output);
                 let s = `#${ex.id} [tool] ${ex.tool} (${ex.outputLines} lines, ${ex.outputBytes} bytes)\n`;
-                if (output)
-                    s += output + "\n";
+                if (ex.output)
+                    s += ex.output + "\n";
                 if (ex.exitCode !== null)
                     s += `exit ${ex.exitCode}\n`;
                 return s;
@@ -336,8 +365,10 @@ export class ContextManager {
     }
     exchangeOneLiner(ex) {
         switch (ex.type) {
-            case "shell_command":
-                return `#${ex.id} shell: ${ex.command} (${ex.outputLines} lines, exit ${ex.exitCode ?? "?"})`;
+            case "shell_command": {
+                const label = ex.source === "agent" ? "agent → shell" : "shell";
+                return `#${ex.id} ${label} [cwd:${ex.cwd}]: ${ex.command} (${ex.outputLines} total lines, exit ${ex.exitCode ?? "?"})`;
+            }
             case "agent_query":
                 return `#${ex.id} query: ${ex.query}`;
             case "agent_response": {

package/dist/core.js

@@ -20,11 +20,15 @@ import { EventBus } from "./event-bus.js";
 import { ContextManager } from "./context-manager.js";
 import { AcpClient } from "./acp-client.js";
 import { setPalette } from "./utils/palette.js";
+import * as streamTransform from "./utils/stream-transform.js";
+import * as settingsMod from "./settings.js";
+import { HandlerRegistry } from "./utils/handler-registry.js";
 // Re-export types that library consumers need
 export { EventBus } from "./event-bus.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
 export function createCore(config) {
     const bus = new EventBus();
+    const handlers = new HandlerRegistry();
     const contextManager = new ContextManager(bus);
     const client = new AcpClient({ bus, contextManager, config });
     let connected = false;
@@ -67,6 +71,12 @@ export function createCore(config) {
                 getAcpClient: () => client,
                 quit: opts.quit,
                 setPalette,
+                createBlockTransform: (o) => streamTransform.createBlockTransform(bus, o),
+                createFencedBlockTransform: (o) => streamTransform.createFencedBlockTransform(bus, o),
+                getExtensionSettings: settingsMod.getExtensionSettings,
+                define: (name, fn) => handlers.define(name, fn),
+                advise: (name, wrapper) => handlers.advise(name, wrapper),
+                call: (name, ...args) => handlers.call(name, ...args),
             };
         },
         kill() {