@halfwhey/claudraband 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,153 @@
+<div align="center">
+
+# claudraband
+
+Claude Code for the power user
+
+> Experimental: this project is still evolving and parts of it may break as Claude Code and ACP clients change.
+
+[Quick start](#quick-start) •
+[CLI](docs/cli.md) •
+[Library](docs/library.md) •
+[Examples](#examples) •
+[Troubleshooting](#troubleshooting)
+
+</div>
+
+`claudraband` wraps a Claude Code TUI in a controlled terminal to enable extended workflows. This project provides:
+
+- Resumable non-interactive workflows. Essentially `claude -p` with session support: `cband continue <session-id> 'what was the result of the research?'`
+- HTTP server to remotely control a Claude Code session: `cband serve --port 1234`
+- ACP server to use with alternative frontends such as Zed or Toad (https://github.com/batrachianai/toad): `cband acp --model haiku`
+- TypeScript library so you can integrate these workflows into your own application.
+
+## Caveats
+
+- This is not a replacement for the Claude SDK. It is geared toward personal, ad-hoc usage.
+- We do not touch OAuth and we do not bypass the Claude Code TUI. You must authenticate through Claude Code, and every interaction runs through a real Claude Code session.
+
+## Requirements
+
+- Node.js or Bun
+- An already authenticated Claude Code
+- `tmux` if you want visible persistent local sessions
+
+## Install
+
+```sh
+# run without installing globally
+npx @halfwhey/claudraband "review the staged diff"
+
+# or install it once
+npm install -g @halfwhey/claudraband
+```
+
+If you prefer Bun:
+
+```sh
+bunx @halfwhey/claudraband "review the staged diff"
+```
+
+`claudraband` installs a pinned Claude Code version, `@anthropic-ai/claude-code@2.1.96`, as a dependency for compatibility. It will be bumped over time. If you need to point at a different Claude binary for debugging or compatibility work, set `CLAUDRABAND_CLAUDE_PATH`.
+
+
+## Quick start
+
+The package installs both `cband` and `claudraband`. The shorter `cband` binary is the recommended CLI. The two first-class ways to use `cband` are:
+
+- local persistent sessions with `tmux`
+- headless persistent sessions with `serve`
+
+### Visible persistent sessions with `tmux`
+
+```sh
+cband "audit the last commit and tell me what looks risky"
+
+cband sessions
+
+cband continue <session-id> "keep going"
+
+# if Claude is waiting on a choice
+cband continue <session-id> --select 2
+cband continue <session-id> --select 3 "xyz"
+```
+
+### Headless persistent sessions with `serve`
+
+```sh
+cband serve --host 127.0.0.1 --port 7842
+cband --connect localhost:7842 "start a migration plan"
+cband attach <session-id>
+cband continue <session-id> --select 2
+```
+
+The daemon now defaults to `tmux`, just like the local first-class path. Use `--connect` only when starting a new daemon-backed session. After that, `continue`, `attach`, and `sessions` route through the tracked session automatically.
+
+`--backend xterm` still exists, but it is experimental while we improve it.
+
+### Using the CLI without tmux or server (experimental)
+
+If you run `cband "..."` without `tmux` and without `--connect`, `cband` falls back to a local headless `xterm.js` session. This backend is **experimental** and slower than tmux. It is useful for one-off runs, but it is not a good default for interactive follow-up because the session is not kept alive between commands.
+
+The xterm backend cannot handle Claude Code's initial startup prompts (trust folder, bypass permissions confirmation). You must disable these before using it:
+
+- `-c "--dangerously-skip-permissions"`
+- `--permission-mode bypassPermissions`
+
+Without `tmux` or server mode, `cband` shuts down Claude Code after each command finishes and starts it again on the next one. If the last output was a question for the user, that question will not survive well across the next resume. Interactive question flows work best with persistent sessions.
+
+### ACP and editor integration
+
+Use ACP when another tool wants to drive Claude through `claudraband`.
+
+```sh
+cband acp --model opus
+
+# for example with toad
+uvx --from batrachian-toad toad acp 'cband acp -c "--model haiku"'
+```
+
+Some ACP clients still have limitations around resuming existing sessions. `claudraband` itself supports session follow and resume as part of the ACP protocol, but the frontend you put on top may not expose all of that yet.
+
+## Session model
+
+Live sessions are tracked in `~/.claudraband/`.
+
+- `cband sessions` shows only live tracked sessions, either hosted by tmux directly or by the daemon.
+- `continue` can resume an existing Claude Code session even when it is no longer live, but `attach` only works on live sessions.
+- `sessions close ...` closes live sessions hosted by tmux directly or by the daemon
+- `sessions close --all` will close all live sessions controlled by Claudraband
+
+## Examples
+
+### Self-interrogation
+
+I have a Claude Code hook that saves the session id that was involved in a commit so I can ask it questions about the commit later. In this workflow, Claude can use `claudraband` to interrogate that older session and justify the choices it made.
+
+![Claude interrogating an older Claude session through claudraband](assets/self-interrogate.png)
+
+### Toad via ACP
+
+Toad can use `claudraband acp` to be an alternative frontend for Claude Code.
+
+![Toad using claudraband ACP as an alternative frontend](assets/toad-acp.png)
+
+That UI is backed by a real Claude Code pane underneath.
+
+![Backing Claude Code pane for the Toad ACP session](assets/toad-claude-pane.png)
+
+### Zed via ACP
+
+Zed can also use `claudraband acp` to be an alternative frontend.
+
+![Zed using claudraband ACP as an alternative frontend](assets/zed-acp.png)
+
+## Library use
+
+Runnable TypeScript examples live in [`examples/`](examples):
+
+- [`examples/code-review.ts`](examples/code-review.ts) starts a session, asks for a review, and prints the result
+- [`examples/multi-session.ts`](examples/multi-session.ts) runs multiple Claude sessions in parallel
+- [`examples/session-journal.ts`](examples/session-journal.ts) resumes a session and writes a simple journal
+
+For the full TypeScript API, see [docs/library.md](docs/library.md).

package/dist/bin.js

@@ -5443,6 +5443,9 @@ class ClaudeWrapper {
         if (pane.includes("INSERT") || pane.includes("NORMAL")) {
           return;
         }
+        if (pane.includes("Yes, I trust this folder") && pane.includes("No, exit") || pane.includes("Bypass Permissions mode") && pane.includes("Yes, I accept")) {
+          return;
+        }
       } catch {}
       await new Promise((r) => setTimeout(r, POLL_MS));
     }
@@ -5531,6 +5534,9 @@ var init_claude = __esm(() => {
 
 // ../claudraband-core/src/claude/inspect.ts
 import { readFile } from "node:fs/promises";
+function normalizeCapturedPane(paneText) {
+  return paneText.replace(/\r/g, "").replace(/\x1b\[(\d+)C/g, (_match, count) => " ".repeat(Number.parseInt(count, 10) || 0)).replace(/\x1b\[[0-9;]*[ABDHJKf]/g, "").replace(/\x1b\[\?[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
 async function hasPendingQuestion(jsonlPath) {
   let data;
   try {
@@ -5564,10 +5570,20 @@ async function hasPendingQuestion(jsonlPath) {
   return pendingIds.size > 0;
 }
 function parseNativePermissionPrompt(paneText) {
-  const questionMatch = paneText.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  const normalizedPane = normalizeCapturedPane(paneText);
+  const isTrustPrompt = normalizedPane.includes("Yes, I trust this folder") && normalizedPane.includes("No, exit");
+  const isBypassPrompt = normalizedPane.includes("Bypass Permissions mode") && normalizedPane.includes("Yes, I accept");
+  let questionMatch;
+  if (isTrustPrompt) {
+    questionMatch = normalizedPane.match(/(Is this a project you created[^\n]*)/);
+  } else if (isBypassPrompt) {
+    questionMatch = normalizedPane.match(/(you accept all responsibility[^\n]*)/);
+  } else {
+    questionMatch = normalizedPane.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  }
   if (!questionMatch)
     return null;
-  const afterQuestion = paneText.slice(paneText.indexOf(questionMatch[1]) + questionMatch[1].length);
+  const afterQuestion = normalizedPane.slice(normalizedPane.indexOf(questionMatch[1]) + questionMatch[1].length);
   const optionRegex = /(?:❯\s*)?(\d+)\.\s+(.+)/g;
   const options = [];
   let match;
@@ -5699,6 +5715,10 @@ var init_session_registry = () => {};
 // ../claudraband-core/src/index.ts
 import { open as open2, readFile as readFile3, stat as stat2 } from "node:fs/promises";
 import { request as httpRequest } from "node:http";
+function isRejectingNativeOption(label) {
+  const normalized = label.trim().toLowerCase();
+  return normalized.startsWith("no") || normalized.startsWith("reject");
+}
 function makeDefaultLogger() {
   const noop = () => {};
   return {
@@ -5820,6 +5840,8 @@ class ClaudrabandSessionImpl {
   _permissionMode;
   allowTextResponses;
   sessionOwner;
+  lastNativePermissionFingerprint = null;
+  lastNativePermissionOutcome = "none";
   constructor(wrapper, sessionId, cwd, backend, model, permissionMode, allowTextResponses, logger, onPermissionRequest, lifetime, sessionOwner) {
     this.sessionId = sessionId;
     this.cwd = cwd;
@@ -5854,7 +5876,20 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter(text);
     this.activePrompt = prompt;
     this.logger.info("prompt received", "sid", this.sessionId, "length", text.length);
-    await this.wrapper.send(text);
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState !== "consumed") {
+      await this.wrapper.send(text);
+    }
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
       this.logger.info("prompt completed", "sid", this.sessionId, "stop_reason", stopReason);
@@ -5877,6 +5912,17 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(null);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
     this.logger.info("awaitTurn", "sid", this.sessionId);
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
@@ -5900,6 +5946,26 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState === "consumed") {
+      if (this.activePrompt === prompt) {
+        this.activePrompt = null;
+      }
+      if (this.promptAbortController === controller) {
+        this.promptAbortController = null;
+      }
+      return { stopReason: "end_turn" };
+    }
     this.logger.info("sendAndAwaitTurn", "sid", this.sessionId, "length", text.length);
     await this.wrapper.send(text);
     try {
@@ -5918,6 +5984,21 @@ class ClaudrabandSessionImpl {
   send(text) {
     return this.wrapper.send(text);
   }
+  async prepareForInput(intendedText) {
+    const handled = await this.pollNativePermission(null, intendedText);
+    if (handled === "handled" || handled === "consumed" || handled === "pending_clear") {
+      const ready = await this.waitForInsertMode();
+      if (!ready) {
+        return this.wrapper.isProcessAlive() ? "blocked" : "cancelled";
+      }
+      return handled === "consumed" ? "consumed" : "ready";
+    }
+    const stillBlocking = hasPendingNativePrompt(await this.wrapper.capturePane().catch(() => ""));
+    if (stillBlocking) {
+      return "blocked";
+    }
+    return "ready";
+  }
   async interrupt() {
     this.promptAbortController?.abort();
     await this.wrapper.interrupt();
@@ -6237,7 +6318,7 @@ class ClaudrabandSessionImpl {
         }
         if (prompt.pendingTools > 0) {
           const handled = await this.pollNativePermission(prompt.lastPendingTool);
-          if (handled) {
+          if (handled === "handled" || handled === "consumed") {
             prompt.pendingTools = Math.max(0, prompt.pendingTools - 1);
             prompt.gotResponse = true;
             prompt.lastPendingTool = null;
@@ -6252,16 +6333,28 @@ class ClaudrabandSessionImpl {
       }
     }
   }
-  async pollNativePermission(pendingTool) {
+  async pollNativePermission(pendingTool, intendedText = null) {
     let paneText;
     try {
       paneText = await this.wrapper.capturePane();
     } catch {
-      return false;
+      return "none";
     }
     const prompt = parseNativePermissionPrompt(paneText);
-    if (!prompt)
-      return false;
+    if (!prompt) {
+      this.lastNativePermissionFingerprint = null;
+      this.lastNativePermissionOutcome = "none";
+      return "none";
+    }
+    const fingerprint = `${prompt.question}
+${prompt.options.map((option) => `${option.number}:${option.label}`).join(`
+`)}`;
+    if (this.lastNativePermissionFingerprint === fingerprint) {
+      if (this.lastNativePermissionOutcome === "handled" || this.lastNativePermissionOutcome === "consumed") {
+        return "pending_clear";
+      }
+      return this.lastNativePermissionOutcome;
+    }
     const decision = await this.resolvePermission({
       source: "native_prompt",
       sessionId: this.sessionId,
@@ -6281,19 +6374,62 @@ class ClaudrabandSessionImpl {
         name: opt.label
       }))
     });
+    let outcome;
     if (decision.outcome === "deferred") {
-      return false;
+      outcome = "deferred";
+    } else if (decision.outcome === "cancelled") {
+      await this.safeInterruptNativePermission();
+      outcome = "handled";
+    } else if (decision.outcome === "text") {
+      await this.safeSendNativePermission(decision.text, false);
+      outcome = decision.text === intendedText ? "consumed" : "handled";
+    } else {
+      const selected = prompt.options.find((option) => option.number === decision.optionId);
+      const tolerateExit = selected ? isRejectingNativeOption(selected.label) : false;
+      await this.safeSendNativePermission(decision.optionId, tolerateExit);
+      outcome = decision.optionId === intendedText ? "consumed" : "handled";
     }
-    if (decision.outcome === "cancelled") {
+    this.lastNativePermissionFingerprint = fingerprint;
+    this.lastNativePermissionOutcome = outcome;
+    return outcome;
+  }
+  async safeSendNativePermission(input, tolerateExit) {
+    try {
+      await this.wrapper.send(input);
+    } catch (error) {
+      if (tolerateExit && !this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission send ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
+    }
+  }
+  async safeInterruptNativePermission() {
+    try {
       await this.wrapper.interrupt();
-      return true;
+    } catch (error) {
+      if (!this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission interrupt ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
     }
-    if (decision.outcome === "text") {
-      await this.wrapper.send(decision.text);
-      return true;
+  }
+  async waitForInsertMode(timeoutMs = 15000) {
+    const POLL_MS = 300;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (!this.wrapper.isProcessAlive()) {
+        return false;
+      }
+      try {
+        const pane = await this.wrapper.capturePane();
+        if (pane.includes("INSERT") || pane.includes("NORMAL"))
+          return true;
+      } catch {}
+      await new Promise((r) => setTimeout(r, POLL_MS));
     }
-    await this.wrapper.send(decision.optionId);
-    return true;
+    return false;
   }
   async handleUserQuestion(ev) {
     const parsed = parseAskUserQuestion(ev.toolInput);
@@ -6812,16 +6948,21 @@ var init_src = __esm(() => {
 
 // src/client.ts
 import { createInterface } from "node:readline/promises";
+function formatOptionLabel(name, kind) {
+  const suffix = `(${kind})`;
+  return name.trim().endsWith(suffix) ? name.trim() : `${name} (${kind})`;
+}
 async function requestPermission(renderer, config, params) {
   renderer.ensureNewline();
   process.stderr.write(`\x1B[33mPermission: ${params.title}\x1B[0m
 `);
-  for (const block of params.content) {
+  const contentBlocks = params.content.length === 1 && params.content[0]?.text.trim() === params.title.trim() ? [] : params.content;
+  for (const block of contentBlocks) {
     process.stderr.write(`${block.text}
 `);
   }
   for (const option of params.options) {
-    process.stderr.write(`  ${option.optionId}. ${option.name} (${option.kind})
+    process.stderr.write(`  ${option.optionId}. ${formatOptionLabel(option.name, option.kind)}
 `);
   }
   if (config.answerChoice) {
@@ -6887,7 +7028,7 @@ function shouldReuseSession(ds) {
   return ds !== null && ds.session.isProcessAlive();
 }
 function resolveServerTerminalBackend(config) {
-  return config.hasExplicitTerminalBackend ? config.terminalBackend : "xterm";
+  return config.hasExplicitTerminalBackend ? config.terminalBackend : "tmux";
 }
 function formatHostForUrl(host) {
   return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
@@ -6982,19 +7123,29 @@ function createDaemonServer(config, runtime, logger) {
       if (method === "POST" && path === "/sessions") {
         const body = JSON.parse(await readBody(req));
         const sessionConfig = resolveSessionConfig(config, body);
-        const session = await runtime.startSession({
+        const sessionOwner = {
+          kind: "daemon",
+          serverUrl,
+          serverPid: process.pid,
+          serverInstanceId
+        };
+        const session = body.sessionId ? await runtime.resumeSession(body.sessionId, {
           cwd: sessionConfig.cwd,
           claudeArgs: sessionConfig.claudeArgs,
           model: sessionConfig.model,
           permissionMode: sessionConfig.permissionMode,
           allowTextResponses: true,
           logger,
-          sessionOwner: {
-            kind: "daemon",
-            serverUrl,
-            serverPid: process.pid,
-            serverInstanceId
-          },
+          sessionOwner,
+          onPermissionRequest: (request) => handlePermission(ds2, request)
+        }) : await runtime.startSession({
+          cwd: sessionConfig.cwd,
+          claudeArgs: sessionConfig.claudeArgs,
+          model: sessionConfig.model,
+          permissionMode: sessionConfig.permissionMode,
+          allowTextResponses: true,
+          logger,
+          sessionOwner,
           onPermissionRequest: (request) => handlePermission(ds2, request)
         });
         const ds2 = {
@@ -7302,6 +7453,7 @@ __export(exports_daemon_client, {
   __test: () => __test2
 });
 import { request as httpRequest2 } from "node:http";
+import { randomUUID as randomUUID3 } from "node:crypto";
 function daemonUrl(server, path) {
   const base = server.startsWith("http") ? server : `http://${server}`;
   return `${base}${path}`;
@@ -7352,6 +7504,7 @@ async function daemonRequest2(server, method, path, body) {
 }
 function buildSessionRequestBody(config, options = {}) {
   return {
+    ...options.sessionId ? { sessionId: options.sessionId } : {},
     cwd: config.cwd,
     ...config.hasExplicitClaudeArgs ? { claudeArgs: config.claudeArgs } : {},
     ...config.hasExplicitModel ? { model: config.model } : {},
@@ -7603,13 +7756,14 @@ async function runWithDaemon(config, renderer, _logger) {
     sessionId = config.sessionId;
     sessionBackend = result.backend;
   } else {
+    sessionId = randomUUID3();
+    process.stderr.write(`session: ${sessionId}
+`);
     const result = await daemonPost(config.connect, "/sessions", {
-      ...buildSessionRequestBody(config)
+      ...buildSessionRequestBody(config, { sessionId })
     });
     sessionId = result.sessionId;
     sessionBackend = result.backend;
-    process.stderr.write(`session: ${sessionId}
-`);
   }
   const session = new DaemonSessionProxy(config.connect, sessionId, config.cwd, sessionBackend, config.model, config.permissionMode, permissionHandler);
   await session.startEventStream();

package/dist/claude/claude.d.ts

@@ -41,6 +41,9 @@ export declare class ClaudeWrapper implements Wrapper {
     /**
      * Poll the terminal until Claude Code is ready to accept input.
      * Looks for "INSERT" in the status bar, which indicates the TUI has loaded.
+     *
+     * Also handles the "trust this folder" prompt that appears before any JSONL
+     * is written when Claude Code runs in a directory for the first time.
      */
     private waitForReady;
     stop(): Promise<void>;

package/dist/index.js

@@ -5455,6 +5455,9 @@ class ClaudeWrapper {
         if (pane.includes("INSERT") || pane.includes("NORMAL")) {
           return;
         }
+        if (pane.includes("Yes, I trust this folder") && pane.includes("No, exit") || pane.includes("Bypass Permissions mode") && pane.includes("Yes, I accept")) {
+          return;
+        }
       } catch {}
       await new Promise((r) => setTimeout(r, POLL_MS));
     }
@@ -5537,6 +5540,9 @@ function parseClaudeArgs(args) {
 }
 // ../claudraband-core/src/claude/inspect.ts
 import { readFile } from "node:fs/promises";
+function normalizeCapturedPane(paneText) {
+  return paneText.replace(/\r/g, "").replace(/\x1b\[(\d+)C/g, (_match, count) => " ".repeat(Number.parseInt(count, 10) || 0)).replace(/\x1b\[[0-9;]*[ABDHJKf]/g, "").replace(/\x1b\[\?[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\[[0-9;]*m/g, "").replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
 async function hasPendingQuestion(jsonlPath) {
   let data;
   try {
@@ -5570,10 +5576,20 @@ async function hasPendingQuestion(jsonlPath) {
   return pendingIds.size > 0;
 }
 function parseNativePermissionPrompt(paneText) {
-  const questionMatch = paneText.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  const normalizedPane = normalizeCapturedPane(paneText);
+  const isTrustPrompt = normalizedPane.includes("Yes, I trust this folder") && normalizedPane.includes("No, exit");
+  const isBypassPrompt = normalizedPane.includes("Bypass Permissions mode") && normalizedPane.includes("Yes, I accept");
+  let questionMatch;
+  if (isTrustPrompt) {
+    questionMatch = normalizedPane.match(/(Is this a project you created[^\n]*)/);
+  } else if (isBypassPrompt) {
+    questionMatch = normalizedPane.match(/(you accept all responsibility[^\n]*)/);
+  } else {
+    questionMatch = normalizedPane.match(/(?:^|\n)\s*(Do you want to [^\n]+\?)/);
+  }
   if (!questionMatch)
     return null;
-  const afterQuestion = paneText.slice(paneText.indexOf(questionMatch[1]) + questionMatch[1].length);
+  const afterQuestion = normalizedPane.slice(normalizedPane.indexOf(questionMatch[1]) + questionMatch[1].length);
   const optionRegex = /(?:❯\s*)?(\d+)\.\s+(.+)/g;
   const options = [];
   let match;
@@ -5748,6 +5764,10 @@ var TERMINAL_BACKENDS = [
     description: "Run Claude Code in a headless xterm-backed PTY"
   }
 ];
+function isRejectingNativeOption(label) {
+  const normalized = label.trim().toLowerCase();
+  return normalized.startsWith("no") || normalized.startsWith("reject");
+}
 function makeDefaultLogger() {
   const noop = () => {};
   return {
@@ -5869,6 +5889,8 @@ class ClaudrabandSessionImpl {
   _permissionMode;
   allowTextResponses;
   sessionOwner;
+  lastNativePermissionFingerprint = null;
+  lastNativePermissionOutcome = "none";
   constructor(wrapper, sessionId, cwd, backend, model, permissionMode, allowTextResponses, logger, onPermissionRequest, lifetime, sessionOwner) {
     this.sessionId = sessionId;
     this.cwd = cwd;
@@ -5903,7 +5925,20 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter(text);
     this.activePrompt = prompt;
     this.logger.info("prompt received", "sid", this.sessionId, "length", text.length);
-    await this.wrapper.send(text);
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState !== "consumed") {
+      await this.wrapper.send(text);
+    }
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
       this.logger.info("prompt completed", "sid", this.sessionId, "stop_reason", stopReason);
@@ -5926,6 +5961,17 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(null);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
     this.logger.info("awaitTurn", "sid", this.sessionId);
     try {
       const stopReason = await this.waitForPromptCompletion(prompt, controller.signal);
@@ -5949,6 +5995,26 @@ class ClaudrabandSessionImpl {
     const prompt = this.newPromptWaiter("");
     prompt.matchedUserEcho = true;
     this.activePrompt = prompt;
+    const startupState = await this.prepareForInput(text);
+    if (startupState === "blocked") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "end_turn" };
+    }
+    if (startupState === "cancelled") {
+      this.activePrompt = null;
+      this.promptAbortController = null;
+      return { stopReason: "cancelled" };
+    }
+    if (startupState === "consumed") {
+      if (this.activePrompt === prompt) {
+        this.activePrompt = null;
+      }
+      if (this.promptAbortController === controller) {
+        this.promptAbortController = null;
+      }
+      return { stopReason: "end_turn" };
+    }
     this.logger.info("sendAndAwaitTurn", "sid", this.sessionId, "length", text.length);
     await this.wrapper.send(text);
     try {
@@ -5967,6 +6033,21 @@ class ClaudrabandSessionImpl {
   send(text) {
     return this.wrapper.send(text);
   }
+  async prepareForInput(intendedText) {
+    const handled = await this.pollNativePermission(null, intendedText);
+    if (handled === "handled" || handled === "consumed" || handled === "pending_clear") {
+      const ready = await this.waitForInsertMode();
+      if (!ready) {
+        return this.wrapper.isProcessAlive() ? "blocked" : "cancelled";
+      }
+      return handled === "consumed" ? "consumed" : "ready";
+    }
+    const stillBlocking = hasPendingNativePrompt(await this.wrapper.capturePane().catch(() => ""));
+    if (stillBlocking) {
+      return "blocked";
+    }
+    return "ready";
+  }
   async interrupt() {
     this.promptAbortController?.abort();
     await this.wrapper.interrupt();
@@ -6286,7 +6367,7 @@ class ClaudrabandSessionImpl {
         }
         if (prompt.pendingTools > 0) {
           const handled = await this.pollNativePermission(prompt.lastPendingTool);
-          if (handled) {
+          if (handled === "handled" || handled === "consumed") {
             prompt.pendingTools = Math.max(0, prompt.pendingTools - 1);
             prompt.gotResponse = true;
             prompt.lastPendingTool = null;
@@ -6301,16 +6382,28 @@ class ClaudrabandSessionImpl {
       }
     }
   }
-  async pollNativePermission(pendingTool) {
+  async pollNativePermission(pendingTool, intendedText = null) {
     let paneText;
     try {
       paneText = await this.wrapper.capturePane();
     } catch {
-      return false;
+      return "none";
     }
     const prompt = parseNativePermissionPrompt(paneText);
-    if (!prompt)
-      return false;
+    if (!prompt) {
+      this.lastNativePermissionFingerprint = null;
+      this.lastNativePermissionOutcome = "none";
+      return "none";
+    }
+    const fingerprint = `${prompt.question}
+${prompt.options.map((option) => `${option.number}:${option.label}`).join(`
+`)}`;
+    if (this.lastNativePermissionFingerprint === fingerprint) {
+      if (this.lastNativePermissionOutcome === "handled" || this.lastNativePermissionOutcome === "consumed") {
+        return "pending_clear";
+      }
+      return this.lastNativePermissionOutcome;
+    }
     const decision = await this.resolvePermission({
       source: "native_prompt",
       sessionId: this.sessionId,
@@ -6330,19 +6423,62 @@ class ClaudrabandSessionImpl {
         name: opt.label
       }))
     });
+    let outcome;
     if (decision.outcome === "deferred") {
-      return false;
+      outcome = "deferred";
+    } else if (decision.outcome === "cancelled") {
+      await this.safeInterruptNativePermission();
+      outcome = "handled";
+    } else if (decision.outcome === "text") {
+      await this.safeSendNativePermission(decision.text, false);
+      outcome = decision.text === intendedText ? "consumed" : "handled";
+    } else {
+      const selected = prompt.options.find((option) => option.number === decision.optionId);
+      const tolerateExit = selected ? isRejectingNativeOption(selected.label) : false;
+      await this.safeSendNativePermission(decision.optionId, tolerateExit);
+      outcome = decision.optionId === intendedText ? "consumed" : "handled";
+    }
+    this.lastNativePermissionFingerprint = fingerprint;
+    this.lastNativePermissionOutcome = outcome;
+    return outcome;
+  }
+  async safeSendNativePermission(input, tolerateExit) {
+    try {
+      await this.wrapper.send(input);
+    } catch (error) {
+      if (tolerateExit && !this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission send ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
     }
-    if (decision.outcome === "cancelled") {
+  }
+  async safeInterruptNativePermission() {
+    try {
       await this.wrapper.interrupt();
-      return true;
+    } catch (error) {
+      if (!this.wrapper.isProcessAlive()) {
+        this.logger.debug("native permission interrupt ignored after pane exit", "sid", this.sessionId);
+        return;
+      }
+      throw error;
     }
-    if (decision.outcome === "text") {
-      await this.wrapper.send(decision.text);
-      return true;
+  }
+  async waitForInsertMode(timeoutMs = 15000) {
+    const POLL_MS = 300;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (!this.wrapper.isProcessAlive()) {
+        return false;
+      }
+      try {
+        const pane = await this.wrapper.capturePane();
+        if (pane.includes("INSERT") || pane.includes("NORMAL"))
+          return true;
+      } catch {}
+      await new Promise((r) => setTimeout(r, POLL_MS));
     }
-    await this.wrapper.send(decision.optionId);
-    return true;
+    return false;
   }
   async handleUserQuestion(ev) {
     const parsed = parseAskUserQuestion(ev.toolInput);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halfwhey/claudraband",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Control the official Claude Code CLI programmatically. Use as a library, a direct CLI, an ACP server, or a persistent session daemon.",
   "type": "module",
   "main": "./dist/index.js",