agent-sh 0.3.1 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 
 Not a shell that lives in an agent — an agent that lives in a shell.
 
-agent-sh is a real terminal first. Every keystroke goes to a real PTY. `cd`, pipes, vim, job control — they all just work. But type `>` at the start of a line, and you're talking to an AI agent that has full context of what you've been doing: your working directory, recent commands, their output.
+agent-sh is a real terminal first. Every keystroke goes to a real PTY. `cd`, pipes, vim, job control — they all just work. But type `?` or `>` at the start of a line, and you're talking to an AI agent that has full context of what you've been doing: your working directory, recent commands, their output.
 
 The agent connects via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), so you can plug in **any** ACP-compatible agent: [pi](https://github.com/svkozak/pi-acp), claude-code, codex, gemini-cli, goose, etc.
 
@@ -13,15 +13,17 @@ The agent connects via the [Agent Client Protocol (ACP)](https://agentclientprot
 ⚡ src $ ls -la                          # real shell command
 ⚡ src $ cd ../tests && npm test          # real cd, env, aliases — all just work
 ⚡ src $ vim file.ts                      # opens vim in the same PTY
-⚡ src $ > refactor the auth middleware   # → sent to agent via ACP
-⚡ src $ > explain the last error         # agent sees your recent commands + output
+⚡ src $ ? explain the last error         # query mode → agent investigates using its own tools
+⚡ src $ > deploy to staging              # execute mode → agent runs it in your live shell
 ```
 
 ## Why shell-first?
 
-Most AI coding tools are agent-first: the LLM drives the experience and the shell is bolted on. That means no real PTY, no job control, no interactive commands, and fragile `cd` tracking that reimplements what bash gives you for free.
+I live mostly in a terminal. I don't just want an agent that has access to my shell — I want a shell that has access to my agent.
 
-agent-sh starts from the opposite end. The shell is the primary interface — it's your terminal, not the agent's. The agent is a tool you reach for when you need it, not the other way around.
+Most AI coding tools get this backwards: the LLM drives the experience and the shell is bolted on. That means no real PTY, no job control, no interactive commands, and fragile `cd` tracking that reimplements what bash gives you for free.
+
+agent-sh starts from the opposite end. The shell is the primary interface — it's your terminal, not the agent's. The agent is a tool you reach for when you need it, not the other way around. Two modes give you fine-grained control: `?` for questions and tasks (agent uses its own tools), `>` for commands that run directly in your live shell.
 
 ### Why ACP?
 
@@ -40,6 +42,8 @@ The [Agent Client Protocol](https://agentclientprotocol.com/) decouples the shel
 - **Real-time Streaming** — Agent responses stream live with syntax highlighting
 - **Zero Latency** — Direct PTY access, full terminal compatibility
 - **Context Aware** — Agent sees your cwd, recent commands, and their output
+- **Dual Input Modes** — `?` for questions/tasks (agent tools), `>` for live shell execution
+- **Extensible Modes** — Extensions can register custom input modes with their own triggers
 - **Multiple Agents** — Easy switching between pi-acp, claude, and other ACP agents
 - **Inline Diff Preview** — File writes show syntax-highlighted diffs inline (Ctrl+O to expand)
 - **Thinking Display** — Toggle agent thinking/reasoning text with Ctrl+T
@@ -67,22 +71,34 @@ See the [Usage Guide](docs/usage.md) for all options, model configuration, and e
 
 ## Input Modes
 
+agent-sh has two agent input modes, each triggered by a single character at the start of an empty line:
+
+| Trigger | Mode | Behavior |
+|---|---|---|
+| `?` | **Query** | Agent uses its own tools (bash, file read/write, search) to investigate and answer. Stays in query mode after each response. |
+| `>` | **Execute** | Agent runs a command in your live shell via `user_shell`. Your aliases, env vars, and cwd apply. Returns to shell after execution. |
+
+Regular shell input works as before — commands go straight to the PTY:
+
 | Input | Behavior |
 |---|---|
 | `ls -la` | Runs in real shell (PTY), output displayed normally |
 | `cd src && make` | Real shell — cd, env, aliases all just work |
 | `vim file.ts` | Opens vim in the same PTY, no hacks needed |
-| `> refactor this fn` | Sends to agent via ACP, streams response inline |
-| `> /help` | Shows available slash commands |
+| `? refactor this fn` | Query mode — agent investigates and responds |
+| `> restart the server` | Execute mode — agent runs it in your live shell |
+| `? /help` | Shows available slash commands (works in either mode) |
 | `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 `>`) |
+| `Escape` | Exit agent input mode |
+
+Modes are extensible — extensions can register new modes via the `input-mode:register` event (see [Extensions](docs/extensions.md#custom-input-modes)).
 
 ### Agent Input Keybindings
 
-When typing after `>`, full readline-style keybindings are available:
+When typing in either agent mode (`?` or `>`), full readline-style keybindings are available:
 
 | Key | Action |
 |---|---|
@@ -103,10 +119,11 @@ When typing after `>`, full readline-style keybindings are available:
 
 ### Thinking Level
 
-The agent prompt shows the current thinking level next to the model name:
+The agent prompt shows the current thinking level next to the model name, with a mode-specific indicator:
 
 ```
-pi (claude-3.5-sonnet) [medium] ● ❯
+pi (claude-sonnet-4-6) [medium] ❓ ❯    # query mode
+pi (claude-sonnet-4-6) [medium] ● ⟩     # execute mode
 ```
 
 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.

package/dist/acp-client.d.ts

@@ -30,7 +30,12 @@ export declare class AcpClient {
     /**
      * Send a user query to the agent.
      */
-    sendPrompt(query: string): Promise<void>;
+    private firstPromptSent;
+    private static readonly SESSION_ORIENTATION;
+    sendPrompt(query: string, opts?: {
+        modeInstruction?: string;
+        modeLabel?: string;
+    }): Promise<void>;
     /**
      * Silently cancel the prompt after a shell tool completes.
      * Unlike user-initiated cancel(), this doesn't show "(cancelled)" —

package/dist/acp-client.js

@@ -129,7 +129,29 @@ export class AcpClient {
     /**
      * Send a user query to the agent.
      */
-    async sendPrompt(query) {
+    firstPromptSent = false;
+    static SESSION_ORIENTATION = [
+        "You are running inside agent-sh, a terminal wrapper that gives the user two interaction modes:",
+        "",
+        "QUERY mode (triggered by '?'): The user is asking questions or requesting tasks.",
+        "Use your internal tools (bash, file operations, etc.) to accomplish tasks.",
+        "Do NOT use user_shell in this mode.",
+        "",
+        "EXECUTE mode (triggered by '>'): The user wants a command run in their live shell session.",
+        "You may use shell_recall to understand previous context and your own tools to investigate,",
+        "but the final action must be sending the command via user_shell,",
+        "which executes in the user's actual shell (with their aliases, env vars, and cwd).",
+        "Do not explain or ask for confirmation — just run it.",
+        "",
+        "Each prompt includes a per-query mode instruction — follow it.",
+        "",
+        "Available tools:",
+        "- user_shell: Runs commands in the user's live shell session (their PTY). Use in EXECUTE mode.",
+        "- shell_recall: Retrieves recent shell command history and output from the user's session.",
+        "  Use this to understand what the user has been doing before answering questions.",
+        "- Your standard tools (bash, file read/write, etc.): Use in AGENT mode.",
+    ].join("\n");
+    async sendPrompt(query, opts) {
         if (!this.connection || !this.sessionId) {
             this.bus.emit("agent:error", { message: "Not connected to agent" });
             return;
@@ -141,19 +163,24 @@ export class AcpClient {
         this.autoCancelled = false;
         let cancelled = false;
         // Emit agent query event (TUI renders echo+spinner, ContextManager records it)
-        this.bus.emit("agent:query", { query });
+        this.bus.emit("agent:query", { query, modeLabel: opts?.modeLabel });
         // Build structured context from ContextManager
         const contextBlock = this.contextManager.getContext();
         try {
             this.log("sending prompt...");
+            const promptContent = [];
+            // Send session orientation on first prompt
+            if (!this.firstPromptSent) {
+                promptContent.push({ type: "text", text: AcpClient.SESSION_ORIENTATION });
+                this.firstPromptSent = true;
+            }
+            if (opts?.modeInstruction) {
+                promptContent.push({ type: "text", text: opts.modeInstruction });
+            }
+            promptContent.push({ type: "text", text: contextBlock + "\n" + query });
             const response = await this.connection.prompt({
                 sessionId: this.sessionId,
-                prompt: [
-                    {
-                        type: "text",
-                        text: contextBlock + "\n" + query,
-                    },
-                ],
+                prompt: promptContent,
             });
             this.log(`prompt resolved: stopReason=${response.stopReason}`);
             if (response.stopReason === "cancelled") {
@@ -240,6 +267,7 @@ export class AcpClient {
         this.sessionId = sessionResponse.sessionId;
         this.lastResponseText = "";
         this.currentResponseText = "";
+        this.firstPromptSent = false;
         this.updateModes(sessionResponse);
     }
     /**

package/dist/core.js

@@ -34,7 +34,7 @@ export function createCore(config) {
     let connected = false;
     // Route frontend events to the agent — any frontend (Shell, WebSocket,
     // REST handler, test harness) can emit these without knowing about AcpClient.
-    bus.on("agent:submit", ({ query }) => {
+    bus.on("agent:submit", ({ query, modeInstruction, modeLabel }) => {
         (async () => {
             // Wait briefly for agent connection if start() is still in progress
             if (!connected) {
@@ -46,7 +46,7 @@ export function createCore(config) {
                 bus.emit("ui:error", { message: "Agent not connected. Please wait a moment and try again." });
                 return;
             }
-            await client.sendPrompt(query);
+            await client.sendPrompt(query, { modeInstruction, modeLabel });
         })().catch((err) => {
             bus.emit("agent:error", {
                 message: err instanceof Error ? err.message : String(err),

package/dist/event-bus.d.ts

@@ -22,10 +22,14 @@ export interface ShellEvents {
     "shell:agent-exec-done": Record<string, never>;
     "agent:submit": {
         query: string;
+        modeInstruction?: string;
+        modeLabel?: string;
     };
     "agent:cancel-request": Record<string, never>;
+    "input-mode:register": import("./types.js").InputModeConfig;
     "agent:query": {
         query: string;
+        modeLabel?: string;
     };
     "agent:thinking-chunk": {
         text: string;

package/dist/extensions/tui-renderer.js

@@ -75,7 +75,7 @@ export default function activate(ctx) {
     // ── Event subscriptions ─────────────────────────────────────
     bus.on("agent:query", (e) => {
         s.spinnerStartTime = 0;
-        showUserQuery(e.query);
+        showUserQuery(e.query, e.modeLabel);
         startAgentResponse();
         startThinkingSpinner();
     });
@@ -237,7 +237,7 @@ export default function activate(ctx) {
             s.renderer = null;
         }
     }
-    function showUserQuery(query) {
+    function showUserQuery(query, modeLabel) {
         const boxW = Math.min(84, writer.columns);
         const contentW = boxW - 4;
         const lines = [];
@@ -258,11 +258,17 @@ export default function activate(ctx) {
                     lines.push(`${p.accent}${remaining}${p.reset}`);
             }
         }
+        // Mode-specific border color and title
+        const isExecute = modeLabel === "Execute";
+        const borderColor = isExecute ? p.success : p.accent;
+        const title = modeLabel
+            ? `${borderColor}${p.bold} ${modeLabel} ${p.reset}`
+            : `${p.accent}${p.bold}❯${p.reset}`;
         const framed = renderBoxFrame(lines, {
             width: boxW,
             style: "rounded",
-            borderColor: p.accent,
-            title: `${p.accent}${p.bold}❯${p.reset}`,
+            borderColor,
+            title,
         });
         writer.write("\n");
         for (const line of framed) {
@@ -572,7 +578,17 @@ export default function activate(ctx) {
         s.showThinkingText = !s.showThinkingText;
         if (s.spinner) {
             stopCurrentSpinner();
-            startThinkingSpinner();
+            if (s.showThinkingText) {
+                // Expanding: replace spinner with thinking text header
+                if (!s.renderer)
+                    startAgentResponse();
+                s.renderer.writeLine(`${p.dim}Thinking (ctrl+t to collapse)${p.reset}`);
+                drain();
+            }
+            else {
+                // Collapsing: restart spinner with updated hint
+                startThinkingSpinner();
+            }
             return;
         }
         if (!s.isThinking)

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import * as path from "node:path";
 import { Shell } from "./shell.js";
 import { createCore } from "./core.js";
 import { palette as p } from "./utils/palette.js";
@@ -10,16 +11,23 @@ import shellRecall from "./extensions/shell-recall.js";
 import shellExec from "./extensions/shell-exec.js";
 import { loadExtensions } from "./extension-loader.js";
 /**
- * Capture the user's full shell environment asynchronously.
+ * Capture the user's full shell environment.
  * This picks up env vars exported in .zshrc/.bashrc that the
- * Node.js process doesn't have.
+ * Node.js process doesn't have (e.g. when launched from an IDE).
  *
- * Uses -l (login shell) instead of -i to avoid TTY blocking issues.
+ * Uses -l (login shell) to get .zprofile/.bash_profile vars, then
+ * explicitly sources the interactive rc file (.zshrc/.bashrc) which
+ * -l alone doesn't load (that requires -i, which blocks on TTY).
  */
 async function captureShellEnvAsync(shell) {
     return new Promise((resolve) => {
         try {
-            const child = spawn(shell, ["-l", "-c", "env -0"], {
+            const shellName = path.basename(shell);
+            const isZsh = shellName.includes("zsh");
+            const sourceRc = isZsh
+                ? 'source ~/.zshrc 2>/dev/null;'
+                : '[ -f ~/.bashrc ] && source ~/.bashrc 2>/dev/null;';
+            const child = spawn(shell, ["-l", "-c", `${sourceRc} env -0`], {
                 stdio: ["ignore", "pipe", "ignore"],
                 timeout: 5000,
             });
@@ -154,7 +162,7 @@ function formatAgentInfo(agentInfo, model, thoughtLevel) {
         const label = thoughtLevel.replace(/^Thinking:\s*/i, "");
         infoStr += ` ${p.dim}[${label}]${p.reset}`;
     }
-    return `${infoStr} ${p.success}●${p.reset}`;
+    return infoStr;
 }
 async function main() {
     // Set up signal handlers before any terminal operations.
@@ -163,29 +171,26 @@ async function main() {
     // Also ignore SIGTTIN which can occur when reading from terminal while backgrounded.
     process.on("SIGTTIN", () => { });
     const config = parseArgs(process.argv.slice(2));
-    // Start with current process environment (fast, non-blocking)
-    // We'll enrich it with shell env asynchronously in the background
+    // Capture user's full shell environment (from .zshrc/.bashrc etc.)
+    // This must complete before spawning the agent so it sees all env vars.
     const baseEnv = {};
     for (const [k, v] of Object.entries(process.env)) {
         if (v !== undefined)
             baseEnv[k] = v;
     }
     config.shellEnv = baseEnv;
-    // Asynchronously capture full shell environment without blocking startup
     const shellPath = config.shell || process.env.SHELL || "/bin/bash";
-    captureShellEnvAsync(shellPath).then((shellEnv) => {
+    try {
+        const shellEnv = await captureShellEnvAsync(shellPath);
         if (Object.keys(shellEnv).length > 0) {
-            const merged = mergeShellEnv(config.shellEnv, shellEnv);
-            config.shellEnv = merged;
+            config.shellEnv = mergeShellEnv(config.shellEnv, shellEnv);
             if (process.env.DEBUG) {
-                console.error('[agent-sh] Shell environment enriched asynchronously');
+                console.error('[agent-sh] Shell environment captured');
             }
         }
-    }).catch(() => {
+    }
+    catch {
         // Ignore errors, we already have process.env as fallback
-    });
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Using current process environment (async enrichment pending)');
     }
     // ── Core (frontend-agnostic) ──────────────────────────────────
     const core = createCore(config);
@@ -232,6 +237,29 @@ async function main() {
     if (process.env.DEBUG) {
         console.error('[agent-sh] Shell created');
     }
+    // ── Input modes ──────────────────────────────────────────────
+    bus.emit("input-mode:register", {
+        id: "query",
+        trigger: "?",
+        label: "query",
+        promptIcon: "❯",
+        indicator: "❓",
+        onSubmit(query, b) {
+            b.emit("agent:submit", { query, modeLabel: "Query", modeInstruction: "[mode: query]" });
+        },
+        returnToSelf: true,
+    });
+    bus.emit("input-mode:register", {
+        id: "execute",
+        trigger: ">",
+        label: "execute",
+        promptIcon: "⟩",
+        indicator: "●",
+        onSubmit(query, b) {
+            b.emit("agent:submit", { query, modeLabel: "Execute", modeInstruction: "[mode: execute]" });
+        },
+        returnToSelf: false,
+    });
     // ── Extensions ────────────────────────────────────────────────
     if (process.env.DEBUG) {
         console.error('[agent-sh] Setting up extensions...');

package/dist/input-handler.d.ts

@@ -16,7 +16,10 @@ export interface InputContext {
 export declare class InputHandler {
     private ctx;
     private lineBuffer;
-    private agentInputMode;
+    private activeMode;
+    private pendingReturnMode;
+    private modes;
+    private modesById;
     private editor;
     private autocompleteActive;
     private autocompleteIndex;
@@ -37,22 +40,28 @@ export declare class InputHandler {
             model?: string;
         };
     });
+    private registerMode;
     private loadHistory;
     private saveHistory;
-    /** Write the agent prompt line with cursor at the correct position. */
-    private writeAgentPromptLine;
+    /** Write the mode prompt line with cursor at the correct position. */
+    private writeModePromptLine;
     handleInput(data: string): void;
-    private enterAgentInputMode;
-    private exitAgentInputMode;
+    private enterMode;
+    private exitMode;
     /** Move to the start of the prompt area and clear everything below. */
     private clearPromptArea;
     printPrompt(): void;
-    private renderAgentInput;
+    /**
+     * Called when agent processing completes. Returns true if the input
+     * handler re-entered a mode (so caller should skip shell prompt).
+     */
+    handleProcessingDone(): boolean;
+    private renderModeInput;
     private updateAutocomplete;
     private renderAutocomplete;
     private applyAutocomplete;
     private dismissAutocomplete;
     private clearAutocompleteLines;
-    private handleAgentInput;
-    private processAgentActions;
+    private handleModeInput;
+    private processModeActions;
 }

package/dist/input-handler.js

@@ -8,7 +8,10 @@ const HISTORY_FILE = path.join(CONFIG_DIR, "history");
 export class InputHandler {
     ctx;
     lineBuffer = "";
-    agentInputMode = false;
+    activeMode = null;
+    pendingReturnMode = null; // mode id to return to after processing
+    modes = new Map(); // keyed by trigger char
+    modesById = new Map(); // keyed by id
     editor = new LineEditor();
     autocompleteActive = false;
     autocompleteIndex = 0;
@@ -28,9 +31,23 @@ export class InputHandler {
         this.loadHistory();
         // Re-render prompt when config changes (e.g. thinking level cycled)
         this.bus.on("config:changed", () => {
-            if (this.agentInputMode)
-                this.writeAgentPromptLine();
+            if (this.activeMode)
+                this.writeModePromptLine();
         });
+        // Listen for mode registrations from extensions
+        this.bus.on("input-mode:register", (config) => {
+            this.registerMode(config);
+        });
+    }
+    registerMode(config) {
+        if (this.modes.has(config.trigger)) {
+            this.bus.emit("ui:error", {
+                message: `Input mode "${config.id}" cannot register trigger "${config.trigger}" — already taken by "${this.modes.get(config.trigger).id}"`,
+            });
+            return;
+        }
+        this.modes.set(config.trigger, config);
+        this.modesById.set(config.id, config);
     }
     loadHistory() {
         try {
@@ -52,8 +69,8 @@ export class InputHandler {
             // Non-critical — ignore write failures
         }
     }
-    /** Write the agent prompt line with cursor at the correct position. */
-    writeAgentPromptLine(showBuffer = true) {
+    /** Write the mode prompt line with cursor at the correct position. */
+    writeModePromptLine(showBuffer = true) {
         const termW = process.stdout.columns || 80;
         // Move cursor to the start of the prompt area (first line of wrapped content)
         if (this.promptWrappedLines > 0) {
@@ -62,9 +79,13 @@ export class InputHandler {
         // Clear from here to end of screen — removes current + all wrapped lines below
         process.stdout.write("\r\x1b[J");
         const agentInfo = this.onShowAgentInfo();
-        const infoPrefix = agentInfo.info ? `${agentInfo.info} ` : "";
-        const promptPrefix = infoPrefix + p.warning + p.bold + "❯ " + p.reset;
-        const promptVisLen = visibleLen(infoPrefix) + 2; // "❯ "
+        const indicator = this.activeMode?.indicator ?? "●";
+        const infoPrefix = agentInfo.info
+            ? `${agentInfo.info} ${p.success}${indicator}${p.reset} `
+            : `${p.success}${indicator}${p.reset} `;
+        const icon = this.activeMode?.promptIcon ?? "❯";
+        const promptPrefix = infoPrefix + p.warning + p.bold + icon + " " + p.reset;
+        const promptVisLen = visibleLen(infoPrefix) + visibleLen(icon) + 1; // icon + space
         if (!showBuffer || !this.editor.buffer.includes("\n")) {
             // Single-line: simple rendering
             const bufferText = showBuffer ? p.accent + this.editor.buffer + p.reset : "";
@@ -127,7 +148,7 @@ export class InputHandler {
             return;
         }
         // Intercept control chars for TUI (Ctrl+T, Ctrl+O) — don't pass to PTY
-        if (data.length === 1 && data.charCodeAt(0) < 32 && !this.agentInputMode) {
+        if (data.length === 1 && data.charCodeAt(0) < 32 && !this.activeMode) {
             const code = data.charCodeAt(0);
             // Keys consumed by TUI extensions
             if (code === 0x14 || code === 0x0f) { // Ctrl+T, Ctrl+O
@@ -139,9 +160,9 @@ export class InputHandler {
                 this.bus.emit("input:keypress", { key: data });
             }
         }
-        // If in agent input mode (typing a query after ">")
-        if (this.agentInputMode) {
-            this.handleAgentInput(data);
+        // If in an input mode (typing a query)
+        if (this.activeMode) {
+            this.handleModeInput(data);
             return;
         }
         for (let i = 0; i < data.length; i++) {
@@ -171,10 +192,11 @@ export class InputHandler {
                 this.ctx.writeToPty(ch);
             }
             else {
-                // Check if ">" at start of empty line → enter agent input mode
+                // Check if trigger char at start of empty line → enter that mode
                 // But not if a foreground process (ssh, vim, etc.) is running
-                if (this.lineBuffer === "" && ch === ">" && !this.ctx.isForegroundBusy()) {
-                    this.enterAgentInputMode();
+                const mode = this.modes.get(ch);
+                if (this.lineBuffer === "" && mode && !this.ctx.isForegroundBusy()) {
+                    this.enterMode(mode);
                     return; // don't process remaining chars
                 }
                 this.lineBuffer += ch;
@@ -182,17 +204,17 @@ export class InputHandler {
             }
         }
     }
-    enterAgentInputMode() {
-        this.agentInputMode = true;
+    enterMode(mode) {
+        this.activeMode = mode;
         this.editor.clear();
         // Enable kitty keyboard protocol (progressive enhancement flag 1)
         // so Shift+Enter sends \x1b[13;2u instead of plain \r
         process.stdout.write("\x1b[>1u");
-        this.writeAgentPromptLine(false);
+        this.writeModePromptLine(false);
     }
-    exitAgentInputMode() {
+    exitMode() {
         this.dismissAutocomplete();
-        this.agentInputMode = false;
+        this.activeMode = null;
         this.editor.clear();
         // Disable kitty keyboard protocol
         process.stdout.write("\x1b[<u");
@@ -210,9 +232,24 @@ export class InputHandler {
     printPrompt() {
         this.ctx.redrawPrompt();
     }
-    renderAgentInput() {
+    /**
+     * Called when agent processing completes. Returns true if the input
+     * handler re-entered a mode (so caller should skip shell prompt).
+     */
+    handleProcessingDone() {
+        if (this.pendingReturnMode) {
+            const mode = this.modesById.get(this.pendingReturnMode);
+            this.pendingReturnMode = null;
+            if (mode) {
+                this.enterMode(mode);
+                return true;
+            }
+        }
+        return false;
+    }
+    renderModeInput() {
         this.clearAutocompleteLines();
-        this.writeAgentPromptLine();
+        this.writeModePromptLine();
         this.updateAutocomplete();
     }
     updateAutocomplete() {
@@ -254,7 +291,8 @@ export class InputHandler {
         }
         const agentInfo = this.onShowAgentInfo();
         const infoLength = visibleLen(agentInfo.info);
-        const col = infoLength + 2 + this.editor.cursor;
+        const icon = this.activeMode?.promptIcon ?? "❯";
+        const col = infoLength + visibleLen(icon) + 1 + this.editor.cursor;
         process.stdout.write(`\r\x1b[${col}C`);
     }
     applyAutocomplete() {
@@ -279,7 +317,7 @@ export class InputHandler {
         this.autocompleteActive = false;
         this.autocompleteItems = [];
         this.autocompleteIndex = 0;
-        this.writeAgentPromptLine();
+        this.writeModePromptLine();
         if (isFileAc)
             this.updateAutocomplete();
     }
@@ -299,7 +337,7 @@ export class InputHandler {
         process.stdout.write("\x1b8"); // restore cursor
         this.autocompleteLines = 0;
     }
-    handleAgentInput(data) {
+    handleModeInput(data) {
         // Clear any pending escape timer — new data arrived
         if (this.escapeTimer) {
             clearTimeout(this.escapeTimer);
@@ -313,18 +351,18 @@ export class InputHandler {
                 this.escapeTimer = null;
                 const flushed = this.editor.flushPendingEscape();
                 if (flushed.length > 0)
-                    this.processAgentActions(flushed);
+                    this.processModeActions(flushed);
             }, 50);
         }
-        this.processAgentActions(actions);
+        this.processModeActions(actions);
     }
-    processAgentActions(actions) {
+    processModeActions(actions) {
         for (const act of actions) {
             switch (act.action) {
                 case "changed":
                     this.historyIndex = -1;
                     this.autocompleteIndex = 0;
-                    this.renderAgentInput();
+                    this.renderModeInput();
                     break;
                 case "submit": {
                     if (this.autocompleteActive) {
@@ -343,7 +381,8 @@ export class InputHandler {
                     this.clearAutocompleteLines();
                     this.clearPromptArea();
                     process.stdout.write("\x1b[<u"); // disable kitty keyboard protocol
-                    this.agentInputMode = false;
+                    const currentMode = this.activeMode;
+                    this.activeMode = null;
                     this.editor.clear();
                     this.dismissAutocomplete();
                     if (query && query.startsWith("/")) {
@@ -354,25 +393,26 @@ export class InputHandler {
                         this.ctx.redrawPrompt();
                     }
                     else if (query) {
-                        this.bus.emit("agent:submit", { query });
+                        this.pendingReturnMode = currentMode.returnToSelf ? currentMode.id : null;
+                        currentMode.onSubmit(query, this.bus);
                     }
                     else {
-                        this.exitAgentInputMode();
+                        this.exitMode();
                     }
                     return;
                 }
                 case "cancel":
                     if (this.autocompleteActive) {
                         this.dismissAutocomplete();
-                        this.writeAgentPromptLine();
+                        this.writeModePromptLine();
                     }
                     else {
-                        this.exitAgentInputMode();
+                        this.exitMode();
                     }
                     return;
                 case "delete-empty":
                     this.dismissAutocomplete();
-                    this.exitAgentInputMode();
+                    this.exitMode();
                     return;
                 case "tab":
                     if (this.autocompleteActive) {
@@ -389,7 +429,7 @@ export class InputHandler {
                                 ? this.autocompleteItems.length - 1
                                 : this.autocompleteIndex - 1;
                         this.clearAutocompleteLines();
-                        this.writeAgentPromptLine();
+                        this.writeModePromptLine();
                         this.renderAutocomplete();
                     }
                     else if (this.history.length > 0) {
@@ -402,7 +442,7 @@ export class InputHandler {
                         }
                         this.editor.buffer = this.history[this.historyIndex];
                         this.editor.cursor = this.editor.buffer.length;
-                        this.renderAgentInput();
+                        this.renderModeInput();
                     }
                     break;
                 case "arrow-down":
@@ -412,7 +452,7 @@ export class InputHandler {
                                 ? 0
                                 : this.autocompleteIndex + 1;
                         this.clearAutocompleteLines();
-                        this.writeAgentPromptLine();
+                        this.writeModePromptLine();
                         this.renderAutocomplete();
                     }
                     else if (this.historyIndex !== -1) {
@@ -425,7 +465,7 @@ export class InputHandler {
                             this.editor.buffer = this.savedBuffer;
                         }
                         this.editor.cursor = this.editor.buffer.length;
-                        this.renderAgentInput();
+                        this.renderModeInput();
                     }
                     break;
             }

package/dist/shell.js

@@ -239,7 +239,9 @@ export class Shell {
             this.paused = false;
             this.agentActive = false;
             this.echoSkip = true;
-            this.freshPrompt();
+            if (!this.inputHandler.handleProcessingDone()) {
+                this.freshPrompt();
+            }
         });
         // Permission prompts need stdout unpaused so the interactive UI renders,
         // then re-paused after the decision.

package/dist/types.d.ts

@@ -40,6 +40,19 @@ export interface ExtensionContext {
     /** Call a named handler. */
     call: (name: string, ...args: any[]) => any;
 }
+/**
+ * Configuration for a registered input mode.
+ * Extensions emit "input-mode:register" with this shape to add new modes.
+ */
+export interface InputModeConfig {
+    id: string;
+    trigger: string;
+    label: string;
+    promptIcon: string;
+    indicator: string;
+    onSubmit(query: string, bus: EventBus): void;
+    returnToSelf: boolean;
+}
 export interface TerminalSession {
     id: string;
     command: string;

package/dist/utils/line-editor.js

@@ -166,6 +166,10 @@ export class LineEditor {
         "ctrl+u": () => this.deleteRange(0, this.cursor),
         "ctrl+k": () => this.deleteRange(this.cursor, this.buffer.length),
         "ctrl+w": () => this.deleteWordBackward() ? { action: "changed" } : null,
+        "alt+f": () => this.wordForward() ? { action: "changed" } : null,
+        "alt+b": () => this.wordBackward() ? { action: "changed" } : null,
+        "alt+d": () => this.deleteWordForward() ? { action: "changed" } : null,
+        "alt+backspace": () => this.deleteWordBackward() ? { action: "changed" } : null,
         "shift+enter": () => this.insertAt("\n"),
         "shift+tab": () => ({ action: "shift+tab" }),
     };

package/package.json

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