claude-code-acp-ts 0.38.2 → 0.52.0

package/dist/acp-agent.js

@@ -1,13 +1,18 @@
-import { AgentSideConnection, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
-import { deleteSession, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
+import { agent as acpAgent, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
+import { deleteSession, getSessionInfo, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
+import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { promisify } from "node:util";
 import packageJson from "../package.json" with { type: "json" };
+import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, mcpElicitationToCreateRequest, } from "./elicitation.js";
 import { SettingsManager } from "./settings.js";
 import { applyTaskCreate, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+const execFileAsync = promisify(execFile);
 const MAX_TITLE_LENGTH = 256;
 function sanitizeTitle(text) {
     // Replace newlines and collapse whitespace
@@ -27,6 +32,16 @@ const ZERO_USAGE = Object.freeze({
     cache_creation_input_tokens: 0,
 });
 const DEFAULT_CONTEXT_WINDOW = 200000;
+/** Floor after `session/cancel` before the adapter forces the active prompt
+ *  loop to return "cancelled". `query.interrupt()` normally makes the SDK
+ *  yield a trailing idle within milliseconds, and the loop returns through its
+ *  usual path — so this timer is armed and cleared, never fired, on healthy
+ *  cancels. It only trips when the SDK is genuinely wedged (e.g. a
+ *  `TaskOutput { block: true }` poll against a hung background task — issue
+ *  #680) and never yields. The value is deliberately loose: it's an
+ *  "obviously stuck" ceiling, not a guess at interrupt latency, so it can't
+ *  pre-empt a slow-but-healthy interrupt. */
+const DEFAULT_FORCE_CANCEL_GRACE_MS = 30_000;
 /** Compute a stable fingerprint of the session-defining params so we can
  *  detect when a loadSession/resumeSession call requires tearing down and
  *  recreating the underlying Query process.  MCP servers are sorted by name
@@ -81,6 +96,10 @@ function isMuslLibc() {
 function shouldHideClaudeAuth() {
     return process.argv.includes("--hide-claude-auth");
 }
+/** Returned to clients when a prompt or cancel targets a session whose SDK
+ *  query stream has already ended (ran to `done` or died). The stream is not
+ *  revivable, so the only recovery is a fresh session. */
+const SESSION_ENDED_MESSAGE = "The Claude Agent session has ended. Please start a new session.";
 // Bypass Permissions doesn't work if we are a root/sudo user
 const IS_ROOT = (process.geteuid?.() ?? process.getuid?.()) === 0;
 const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
@@ -92,9 +111,39 @@ const LOCAL_ONLY_COMMANDS = new Set(["/context", "/heapdump", "/extra-usage"]);
 // payload in these XML-like markers that the CLI uses for its own display.
 // The live prompt loop drops them; replay must strip them too or they leak
 // into the UI on session/load.
-const LOCAL_COMMAND_TAG_PATTERN = /<(command-name|command-message|command-args|local-command-stdout|local-command-stderr)>[\s\S]*?<\/\1>/g;
+const LOCAL_COMMAND_MARKERS = [
+    "command-name",
+    "command-message",
+    "command-args",
+    "local-command-stdout",
+    "local-command-stderr",
+].map((tag) => ({ open: `<${tag}>`, close: `</${tag}>` }));
+// Single-pass scanner that removes each `<tag>…</tag>` marker (matching the
+// nearest closing tag of the same name, like a lazy regex would).
 function stripMarkerTags(text) {
-    return text.replace(LOCAL_COMMAND_TAG_PATTERN, "");
+    const dead = new Set();
+    let result = "";
+    let copiedUpTo = 0;
+    let i = 0;
+    while (i < text.length) {
+        if (text[i] === "<") {
+            const marker = LOCAL_COMMAND_MARKERS.find((m) => !dead.has(m.open) && text.startsWith(m.open, i));
+            if (marker) {
+                const end = text.indexOf(marker.close, i + marker.open.length);
+                if (end !== -1) {
+                    result += text.slice(copiedUpTo, i);
+                    i = copiedUpTo = end + marker.close.length;
+                    continue;
+                }
+                // No closing marker remains anywhere ahead, and `indexOf` only ever
+                // searches forward from here on, so stop treating this tag as an
+                // opener — that avoids rescanning the tail for it on every match.
+                dead.add(marker.open);
+            }
+        }
+        i++;
+    }
+    return result + text.slice(copiedUpTo);
 }
 /**
  * Return user-message content with local-command marker tags removed, or
@@ -200,13 +249,56 @@ export function describeAlwaysAllow(suggestions, toolName) {
     }
     return `Always Allow ${parts.join(" and ")}`;
 }
-// Implement the ACP Agent interface
+/**
+ * Bridges {@link AcpClient} to the connection-scoped {@link AgentContext}
+ * exposed by `AgentApp.connect(...)` as `connection.client`. The peer handle is
+ * valid for the entire connection lifetime, so it is captured once at
+ * construction.
+ */
+class ClientConnection {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    sessionUpdate(params) {
+        return this.ctx.notify(methods.client.session.update, params);
+    }
+    requestPermission(params, signal) {
+        return this.ctx.request(methods.client.session.requestPermission, params, {
+            cancellationSignal: signal,
+        });
+    }
+    readTextFile(params) {
+        return this.ctx.request(methods.client.fs.readTextFile, params);
+    }
+    writeTextFile(params) {
+        return this.ctx.request(methods.client.fs.writeTextFile, params);
+    }
+    unstable_createElicitation(params, signal) {
+        return this.ctx.request(methods.client.elicitation.create, params, {
+            cancellationSignal: signal,
+        });
+    }
+    unstable_completeElicitation(params) {
+        return this.ctx.notify(methods.client.elicitation.complete, params);
+    }
+    extNotification(method, params) {
+        return this.ctx.notify(method, params);
+    }
+}
 export class ClaudeAcpAgent {
+    sessions;
+    client;
+    clientCapabilities;
+    logger;
+    gatewayAuthRequest;
+    /** Grace period before a `session/cancel` forces a wedged prompt loop to
+     *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
+     *  tests can shrink it. */
+    forceCancelGraceMs = DEFAULT_FORCE_CANCEL_GRACE_MS;
     constructor(client, logger) {
-        this.backgroundTerminals = {};
         this.sessions = {};
         this.client = client;
-        this.toolUseCache = {};
         this.logger = logger ?? console;
     }
     async initialize(request) {
@@ -322,6 +414,9 @@ export class ClaudeAcpAgent {
                     http: true,
                     sse: true,
                 },
+                auth: {
+                    logout: {},
+                },
                 loadSession: true,
                 sessionCapabilities: {
                     additionalDirectories: {},
@@ -404,6 +499,40 @@ export class ClaudeAcpAgent {
             sessions,
         };
     }
+    /** Read the SDK-maintained title for a session and, if it changed since the
+     *  last time we looked, notify the client with a `session_info_update`. The
+     *  SDK has no push event for the title it auto-generates in the background, so
+     *  we pull it at turn-end. A missing session file or read error is non-fatal:
+     *  the title is best-effort and another turn will retry. */
+    async maybeUpdateSessionTitle(sessionId, session) {
+        let info;
+        try {
+            info = await getSessionInfo(sessionId, { dir: session.cwd });
+        }
+        catch (error) {
+            this.logger.error(`Session ${sessionId}: failed to read session info: ${error}`);
+            return;
+        }
+        // `customTitle` is a user-set `/rename`; `summary` is the auto-generated
+        // title (or first prompt). Prefer the explicit title when present.
+        const rawTitle = info?.customTitle ?? info?.summary;
+        if (!rawTitle) {
+            return;
+        }
+        const title = sanitizeTitle(rawTitle);
+        if (title === session.lastTitle) {
+            return;
+        }
+        session.lastTitle = title;
+        await this.client.sessionUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "session_info_update",
+                title,
+                updatedAt: new Date(info.lastModified).toISOString(),
+            },
+        });
+    }
     async authenticate(_params) {
         if (_params.methodId === "gateway" || _params.methodId === "gateway-bedrock") {
             this.gatewayAuthRequest = _params;
@@ -411,67 +540,306 @@ export class ClaudeAcpAgent {
         }
         throw new Error("Method not implemented.");
     }
+    async logout(_params) {
+        // Clear in-memory gateway credentials supplied via `authenticate`. The
+        // gateway method never touches the on-disk credential store, so dropping
+        // this reference is the whole logout for that path.
+        this.gatewayAuthRequest = undefined;
+        // For the Claude/Console login methods the credentials live in the native
+        // CLI's store (keychain or config dir), which only the binary can clear.
+        // `claude auth logout` is non-interactive and idempotent.
+        const cliPath = await claudeCliPath();
+        try {
+            await execFileAsync(cliPath, ["auth", "logout"]);
+        }
+        catch (error) {
+            const stderr = typeof error === "object" && error && "stderr" in error
+                ? String(error.stderr).trim()
+                : undefined;
+            throw RequestError.internalError({ stderr: stderr || undefined }, `claude auth logout failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     async prompt(params) {
         const session = this.sessions[params.sessionId];
         if (!session) {
             throw new Error("Session not found");
         }
+        // The SDK query stream already terminated (see `queryClosed`); its iterator
+        // can't be revived, so enqueueing here would hang on a deferred that never
+        // settles. Fail clearly and let the client start a fresh session.
+        if (session.queryClosed) {
+            throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
+        }
+        const userMessage = promptToClaude(params);
+        const promptUuid = randomUUID();
+        userMessage.uuid = promptUuid;
+        // Local-only commands (e.g. `/clear`) return a result without replaying the
+        // user message, so the consumer can't promote the turn from the echo.
+        const firstText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
+        const isLocalOnlyCommand = firstText.startsWith("/") && LOCAL_ONLY_COMMANDS.has(firstText.split(" ", 1)[0]);
+        // Each prompt is a Turn whose deferred the persistent consumer settles once
+        // the turn's outcome is known. `prompt()` owns no loop: it enqueues the
+        // turn, pushes the user message onto the streaming input, makes sure the
+        // consumer is running, and awaits the deferred.
+        const turn = {
+            promptUuid,
+            isLocalOnlyCommand,
+            settled: false,
+            resolve: () => { },
+            reject: () => { },
+        };
+        const response = new Promise((resolve, reject) => {
+            turn.resolve = resolve;
+            turn.reject = reject;
+        });
+        session.turnQueue ??= [];
+        session.turnQueue.push(turn);
+        session.input.push(userMessage);
+        this.ensureConsumer(session, params.sessionId);
+        return response;
+    }
+    /** Lazily start the per-session consumer that drains the SDK query stream for
+     *  the session's whole life. Idempotent: only the first `prompt()` starts it. */
+    ensureConsumer(session, sessionId) {
+        if (session.consumer) {
+            return;
+        }
+        // Wake-up channel so cancel() can force the consumer to settle the active
+        // turn "cancelled" even when query.next() is wedged and never yields again
+        // (issue #680). The consumer re-arms it after each fire.
+        session.cancelController = new AbortController();
+        session.consumer = this.runConsumer(session, { sessionId });
+        session.consumer.catch((error) => {
+            this.logger.error(`Session ${sessionId}: consumer terminated unexpectedly: ${error}`);
+        });
+    }
+    /** The single, long-lived consumer of the SDK query stream for a session. It
+     *  forwards every message as ACP `sessionUpdate`s (so background/between-turn
+     *  output streams live, not just while a prompt is awaiting) and settles each
+     *  Turn's deferred when that turn ends. Replaces the per-prompt message loop;
+     *  `params` only carries the (session-invariant) `sessionId`. */
+    async runConsumer(session, params) {
+        // Per-turn scratch, reset whenever a turn becomes active. Kept as consumer
+        // locals (rather than per-Turn fields) because they describe the message
+        // currently being processed, which is sequential — exactly one turn is
+        // active at a time. Mirrors the locals the old per-prompt loop held.
         let lastAssistantTotalUsage = null;
         let lastAssistantUsage = null;
         let lastAssistantModel = null;
         // When the Claude SDK classifies a turn as failed (e.g. rate limit, auth
         // problem, billing), it sets a categorical `error` field on the
-        // `SDKAssistantMessage` that precedes the final `result` message. We
-        // capture it here so the subsequent `RequestError.internalError` can
-        // forward it to clients as structured `data`, sparing them from
-        // pattern-matching on the human-readable message text.
+        // `SDKAssistantMessage` that precedes the final `result` message. We capture
+        // it here so the subsequent `RequestError.internalError` can forward it to
+        // clients as structured `data`, sparing them from pattern-matching on text.
         let lastAssistantError;
-        const userMessage = promptToClaude(params);
-        const promptUuid = randomUUID();
-        userMessage.uuid = promptUuid;
-        // These local-only commands return a result without replaying the user
-        // message. Mark promptReplayed=true so their result isn't consumed as a
-        // background task result.
-        const firstText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
-        const isLocalOnlyCommand = firstText.startsWith("/") && LOCAL_ONLY_COMMANDS.has(firstText.split(" ", 1)[0]);
-        if (session.promptRunning) {
-            session.input.push(userMessage);
-            const order = session.nextPendingOrder++;
-            const cancelled = await new Promise((resolve) => {
-                session.pendingMessages.set(promptUuid, { resolve, order });
-            });
-            if (cancelled) {
-                return { stopReason: "cancelled" };
+        // When a streaming classifier refuses a turn, the assistant message carries
+        // stop_reason "refusal" and structured stop_details. We capture the
+        // human-readable explanation so the terminal `result` can surface it.
+        let lastRefusalExplanation = null;
+        // Tracks whether we're inside a compaction. The SDK emits the terminal
+        // `status` (compact_result success/failed) twice for a single failed
+        // compaction, and the two messages are indistinguishable — so we report the
+        // outcome only while a compaction is in progress, then clear this.
+        let compactionInProgress = false;
+        // Anthropic API message id of the assistant message currently being
+        // streamed, captured from `message_start` so the streamed chunks that follow
+        // (whose delta events don't carry it) can all be tagged with the same,
+        // replay-stable id.
+        let currentStreamMessageId;
+        // The text/thinking blocks that have actually streamed live as
+        // `stream_event` deltas for the message the next consolidated `assistant`
+        // will repeat, in stream order, each accumulated to its full streamed text.
+        // The consolidated handler diffs each assembled block against these and
+        // forwards only the un-streamed remainder — nothing if it streamed in full
+        // (the common case), the whole block if it never streamed (a non-streaming
+        // gateway), or just the tail if the stream was cut short mid-block. Matching
+        // on content rather than the Anthropic message id makes dedupe robust to
+        // gateways that don't carry a stable/matching id across the stream and the
+        // consolidated message. Reset after each consolidated message consumes it.
+        const streamedBlocks = [];
+        // Stop reason accumulated for the active turn (result subtype, refusal,
+        // max_tokens, …). Reset per turn; read when the turn settles at idle.
+        let stopReason = "end_turn";
+        const resetTurnScratch = () => {
+            lastAssistantTotalUsage = null;
+            lastAssistantUsage = null;
+            lastAssistantModel = null;
+            lastAssistantError = undefined;
+            lastRefusalExplanation = null;
+            compactionInProgress = false;
+            // Do NOT reset currentStreamMessageId or streamedBlocks here. Turn
+            // activation can fire mid-message (the replayed user echo with
+            // --replay-user-messages lands between a message's blocks); clearing the
+            // streamed-content record on activation would drop the blocks that
+            // streamed before the echo, so the consolidated assistant message would
+            // re-emit them as duplicates. streamedBlocks is bounded instead by being
+            // cleared when each consolidated message consumes it. #785 stopped
+            // resetting the streamed-content tracking here but left this line.
+            stopReason = "end_turn";
+            session.accumulatedUsage = {
+                inputTokens: 0,
+                outputTokens: 0,
+                cachedReadTokens: 0,
+                cachedWriteTokens: 0,
+            };
+        };
+        /** Promote a queued turn to active: it becomes the one output is attributed
+         *  to, and its scratch starts fresh. Clears the cancelled flag so a turn
+         *  enqueued after a prior cancel isn't treated as cancelled. Also clears any
+         *  leftover orphan-skip count: since the SDK echoes/runs input FIFO, every
+         *  orphan from a prior cancel has already arrived by the time a live turn
+         *  activates, so a non-zero remainder means the SDK dropped a queued turn on
+         *  interrupt (no orphan emitted) — drop the stale count so a later echo-less
+         *  result isn't wrongly skipped. */
+        const activateTurn = (turn) => {
+            session.activeTurn = turn;
+            session.cancelled = false;
+            session.pendingOrphanResults = 0;
+            resetTurnScratch();
+        };
+        /** Ensure there is an active turn before a user-turn result that carries no
+         *  echo to activate it, by promoting the queue head. Most turns are
+         *  activated by their replayed user message before their result, but some
+         *  legitimately produce a result with no matching echo: local-only commands
+         *  (e.g. `/context`) and compaction (`/compact`, whose only user messages
+         *  are the generated summary and a `<local-command-stdout>` replay — neither
+         *  carries the prompt's uuid). Promoting the head settles those.
+         *
+         *  But an echo-less result can also be an ORPHAN: cancel() settles+removes a
+         *  queued turn whose user message was already pushed, so the SDK still runs
+         *  it and emits a result with no uuid to match. Promoting the head for an
+         *  orphan would misattribute its stop reason/usage to an unrelated later
+         *  prompt. `session.pendingOrphanResults` counts exactly how many such
+         *  orphans are still expected (FIFO, they arrive before any live turn's
+         *  result), so we skip those and only promote once the count is drained. */
+        const ensureActiveTurn = () => {
+            if (session.activeTurn) {
+                return;
             }
-        }
-        else {
-            session.input.push(userMessage);
-        }
-        // Reset session state only when this prompt is about to execute (not
-        // while queued).  Previously this ran before the queue check, which
-        // created a race: a cancel()+new-prompt sequence would reset
-        // `session.cancelled` to false before the in-flight prompt's while-loop
-        // could observe the cancelled flag, causing it to return `end_turn` with
-        // zero usage instead of `cancelled`.
-        session.cancelled = false;
-        session.accumulatedUsage = {
-            inputTokens: 0,
-            outputTokens: 0,
-            cachedReadTokens: 0,
-            cachedWriteTokens: 0,
+            const head = (session.turnQueue ?? []).find((t) => !t.settled);
+            if (!head) {
+                return;
+            }
+            if ((session.pendingOrphanResults ?? 0) > 0) {
+                session.pendingOrphanResults--;
+                return;
+            }
+            activateTurn(head);
         };
-        session.promptRunning = true;
-        let handedOff = false;
-        let errored = false;
-        let stopReason = "end_turn";
+        /** Settle the active turn's deferred exactly once, disarm the force-cancel
+         *  backstop (the turn is over), and drop it from the queue. */
+        const settleActive = (result) => {
+            const turn = session.activeTurn;
+            if (!turn || turn.settled) {
+                return;
+            }
+            turn.settled = true;
+            if (session.forceCancelTimer) {
+                clearTimeout(session.forceCancelTimer);
+                session.forceCancelTimer = undefined;
+            }
+            session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
+            session.activeTurn = null;
+            turn.resolve(result);
+        };
+        /** Reject the active turn (auth required, error result, …) without tearing
+         *  down the consumer: the stream continues to idle and later turns proceed. */
+        const failActive = (error) => {
+            if (session.forceCancelTimer) {
+                clearTimeout(session.forceCancelTimer);
+                session.forceCancelTimer = undefined;
+            }
+            const turn = session.activeTurn;
+            if (!turn || turn.settled) {
+                return;
+            }
+            turn.settled = true;
+            session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
+            session.activeTurn = null;
+            turn.reject(error);
+        };
+        /** Reject every in-flight turn — used when the stream dies. */
+        const failAllTurns = (error) => {
+            if (session.forceCancelTimer) {
+                clearTimeout(session.forceCancelTimer);
+                session.forceCancelTimer = undefined;
+            }
+            const turns = session.activeTurn
+                ? [session.activeTurn, ...(session.turnQueue ?? []).filter((t) => t !== session.activeTurn)]
+                : [...(session.turnQueue ?? [])];
+            session.activeTurn = null;
+            session.turnQueue = [];
+            for (const turn of turns) {
+                if (!turn.settled) {
+                    turn.settled = true;
+                    turn.reject(error);
+                }
+            }
+        };
+        // The wake-up channel cancel()/teardown aborts to force the active turn to
+        // settle "cancelled" even when query.next() is wedged (issue #680). Re-armed
+        // after each fire so the consumer keeps serving later turns.
+        let cancelController = session.cancelController;
         try {
             while (true) {
-                const { value: message, done } = await session.query.next();
+                const nextMessage = session.query.next();
+                // Fresh abort listener per iteration, removed when next() wins, so a
+                // long-lived session doesn't accumulate listeners on one signal.
+                let onAbort;
+                const abortRace = new Promise((resolve) => {
+                    onAbort = () => resolve("abort");
+                    cancelController.signal.addEventListener("abort", onAbort, { once: true });
+                });
+                const raced = await Promise.race([
+                    nextMessage.then((result) => ({ kind: "message", result })),
+                    abortRace,
+                ]);
+                cancelController.signal.removeEventListener("abort", onAbort);
+                if (raced === "abort") {
+                    // cancel()/teardown woke us. Abandon the in-flight next() (swallowing
+                    // any later rejection so it can't surface as unhandled) and settle the
+                    // active turn "cancelled" per the ACP contract. If the session is
+                    // being torn down, stop; otherwise re-arm and keep consuming.
+                    void nextMessage.catch(() => { });
+                    settleActive({ stopReason: "cancelled" });
+                    if (!this.sessions[params.sessionId]) {
+                        return;
+                    }
+                    cancelController = new AbortController();
+                    session.cancelController = cancelController;
+                    continue;
+                }
+                const { value: message, done } = raced.result;
                 if (done || !message) {
-                    if (session.cancelled) {
-                        return { stopReason: "cancelled" };
+                    // The stream ended. Settle the in-flight turns FIRST, then release the
+                    // stream resources — same order as the error paths (failAllTurns before
+                    // closeQueryStream). Settling is the user-facing contract; resource
+                    // release is best-effort cleanup, so a throw there must not pre-empt a
+                    // turn's real outcome.
+                    //
+                    // Settle the turn that was in flight so its prompt() doesn't hang:
+                    // cancelled if a cancel is pending, otherwise the accumulated outcome.
+                    settleActive(session.cancelled
+                        ? { stopReason: "cancelled" }
+                        : { stopReason, usage: sessionUsage(session) });
+                    // Queued turns the SDK never started never ran, so reject them rather
+                    // than reporting a success (end_turn) — or a misleading "cancelled" —
+                    // for a prompt that produced no output. (A cancel already settled the
+                    // turns that were queued at cancel time and removed them, so anything
+                    // still here was enqueued afterward and was not part of the cancel.)
+                    for (const queued of [...(session.turnQueue ?? [])]) {
+                        if (!queued.settled) {
+                            queued.settled = true;
+                            queued.reject(RequestError.internalError(undefined, SESSION_ENDED_MESSAGE));
+                        }
                     }
-                    break;
+                    session.turnQueue = [];
+                    // The query iterator can't be revived, so close the session's stream
+                    // (marks queryClosed, drops the consumer handle, releases the dead
+                    // subprocess/settings resources) — a later prompt() then rejects up
+                    // front rather than restarting a consumer on the exhausted stream.
+                    this.closeQueryStream(session);
+                    return;
                 }
                 if (session.emitRawSDKMessages &&
                     shouldEmitRawMessage(session.emitRawSDKMessages, message)) {
@@ -487,6 +855,7 @@ export class ClaudeAcpAgent {
                                 break;
                             case "status": {
                                 if (message.status === "compacting") {
+                                    compactionInProgress = true;
                                     await this.client.sessionUpdate({
                                         sessionId: message.session_id,
                                         update: {
@@ -495,37 +864,65 @@ export class ClaudeAcpAgent {
                                         },
                                     });
                                 }
+                                else if (message.compact_result === "success" && compactionInProgress) {
+                                    // The SDK signals manual `/compact` completion with a status
+                                    // message carrying `compact_result`, not the `compact_boundary`
+                                    // message (which only fires when there's content to compact).
+                                    compactionInProgress = false;
+                                    await this.client.sessionUpdate({
+                                        sessionId: message.session_id,
+                                        update: {
+                                            sessionUpdate: "agent_message_chunk",
+                                            content: { type: "text", text: "\n\nCompacting completed." },
+                                        },
+                                    });
+                                }
+                                else if (message.compact_result === "failed" && compactionInProgress) {
+                                    compactionInProgress = false;
+                                    const reason = message.compact_error ? `: ${message.compact_error}` : ".";
+                                    await this.client.sessionUpdate({
+                                        sessionId: message.session_id,
+                                        update: {
+                                            sessionUpdate: "agent_message_chunk",
+                                            content: { type: "text", text: `\n\nCompacting failed${reason}` },
+                                        },
+                                    });
+                                }
                                 break;
                             }
                             case "compact_boundary": {
-                                // Send used:0 immediately so the client doesn't keep showing
-                                // the stale pre-compaction context size until the next turn.
+                                // Refresh the displayed usage immediately so the client doesn't
+                                // keep showing the stale pre-compaction size (e.g. "944k/1m")
+                                // right after the user sees "Compacting completed", which is
+                                // confusing and wrong.
                                 //
-                                // This is a deliberate approximation: we don't know the exact
-                                // post-compaction token count (only the SDK's next API call
-                                // reveals that). But used:0 is directionally correct — context
-                                // just dropped dramatically — and the real value replaces it
-                                // within seconds when the next result message arrives.
-                                // The alternative (no update) leaves the client showing e.g.
-                                // "944k/1m" right after the user sees "Compacting completed",
-                                // which is confusing and wrong.
-                                lastAssistantTotalUsage = 0;
+                                // Prefer the SDK's authoritative post-compaction `used` via
+                                // getContextUsage — it reflects the real retained context
+                                // (system prompt + tools + surviving messages), which the
+                                // per-message API usage numbers can't give us until the next
+                                // turn's result. If the control request fails, fall back to the
+                                // used:0 approximation: directionally correct (context just
+                                // dropped dramatically) and replaced within seconds by the next
+                                // result message.
+                                //
+                                // `size` keeps coming from session.contextWindowSize (learned
+                                // from modelUsage / the model heuristic) — getContextUsage's
+                                // window field under-reports extended 1M windows.
+                                //
+                                // The "Compacting completed." text is emitted from the `status`
+                                // handler (keyed on `compact_result`), not here, so the failure
+                                // path gets a message too.
+                                const usedTokens = await fetchContextUsedTokens(session.query, this.logger);
                                 lastAssistantUsage = null;
+                                lastAssistantTotalUsage = usedTokens ?? 0;
                                 await this.client.sessionUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "usage_update",
-                                        used: 0,
+                                        used: lastAssistantTotalUsage,
                                         size: session.contextWindowSize,
                                     },
                                 });
-                                await this.client.sessionUpdate({
-                                    sessionId: message.session_id,
-                                    update: {
-                                        sessionUpdate: "agent_message_chunk",
-                                        content: { type: "text", text: "\n\nCompacting completed." },
-                                    },
-                                });
                                 break;
                             }
                             case "local_command_output": {
@@ -540,10 +937,25 @@ export class ClaudeAcpAgent {
                             }
                             case "session_state_changed": {
                                 if (message.state === "idle") {
+                                    // A non-cancelled turn already settled at its terminal
+                                    // `result` (issue #773), so this trailing `idle` is just
+                                    // absorbed. We must NOT settle `activeTurn` here in that case:
+                                    // `idle` carries no turn identity, and it can lag (the SDK
+                                    // flushes held-back results / drains background agents first),
+                                    // so by the time it arrives the SDK may have echoed the NEXT
+                                    // turn and activated it — settling now would resolve that new
+                                    // turn prematurely with end_turn and ~zero usage, dropping its
+                                    // real result. Only a cancelled turn relies on `idle`: its
+                                    // `result` is dropped at the `session.cancelled` guard, so it
+                                    // never settles at a result and must settle here.
                                     if (session.cancelled) {
-                                        stopReason = "cancelled";
+                                        settleActive({ stopReason: "cancelled" });
                                     }
-                                    return { stopReason, usage: sessionUsage(session) };
+                                    // The SDK generates the session title in a background task and
+                                    // persists it to the session file; `idle` is the turn-over
+                                    // signal, so it's the point at which a new title may have
+                                    // landed. Push it to the client if it changed.
+                                    await this.maybeUpdateSessionTitle(params.sessionId, session);
                                 }
                                 break;
                             }
@@ -584,6 +996,81 @@ export class ClaudeAcpAgent {
                                 });
                                 break;
                             }
+                            case "commands_changed": {
+                                // Push the full slash-command list after a mid-session change
+                                // (e.g. skills discovered dynamically as the agent works in a
+                                // subdirectory). The client should REPLACE its cached command
+                                // list with this payload: supportedCommands() is captured once
+                                // at initialize and never reflects mid-session changes, so we
+                                // forward message.commands directly rather than re-querying.
+                                await this.client.sessionUpdate({
+                                    sessionId: message.session_id,
+                                    update: {
+                                        sessionUpdate: "available_commands_update",
+                                        availableCommands: getAvailableSlashCommands(message.commands),
+                                    },
+                                });
+                                break;
+                            }
+                            case "mirror_error": {
+                                // The SDK failed to persist session history (SessionStore
+                                // append rejected/timed out after retry) — potential data loss
+                                // the user should know about rather than a silent gap on
+                                // resume. Log it and surface a warning in the conversation.
+                                this.logger.error(`Session ${message.session_id}: failed to persist history: ${message.error}`);
+                                break;
+                            }
+                            case "permission_denied": {
+                                // A tool call was auto-denied (by a rule, the classifier,
+                                // dontAsk mode, etc.) before running. The tool_use block was
+                                // already emitted as a `tool_call`, so mark it failed with the
+                                // rejection reason — otherwise the client shows a tool call
+                                // that silently never resolves.
+                                const reason = message.decision_reason ?? message.message;
+                                await this.client.sessionUpdate({
+                                    sessionId: message.session_id,
+                                    update: {
+                                        sessionUpdate: "tool_call_update",
+                                        toolCallId: message.tool_use_id,
+                                        status: "failed",
+                                        content: [
+                                            {
+                                                type: "content",
+                                                content: { type: "text", text: `Permission denied: ${reason}` },
+                                            },
+                                        ],
+                                        _meta: {
+                                            claudeCode: {
+                                                toolName: message.tool_name,
+                                                toolResponse: {
+                                                    decisionReasonType: message.decision_reason_type,
+                                                    decisionReason: message.decision_reason,
+                                                    message: message.message,
+                                                },
+                                            },
+                                        },
+                                    },
+                                });
+                                break;
+                            }
+                            case "informational": {
+                                // Free-form notice from the SDK (e.g. why a UserPromptSubmit/Stop
+                                // hook blocked continuation). Surface the text so the user sees it
+                                // instead of a silent stop. ACP's agent_message_chunk has no
+                                // severity field, so fold the level into the text for the more
+                                // prominent levels ('info' is transcript-only noise — leave plain).
+                                const text = message.level === "info"
+                                    ? message.content
+                                    : `**${message.level[0].toUpperCase()}${message.level.slice(1)}:** ${message.content}`;
+                                await this.client.sessionUpdate({
+                                    sessionId: message.session_id,
+                                    update: {
+                                        sessionUpdate: "agent_message_chunk",
+                                        content: { type: "text", text },
+                                    },
+                                });
+                                break;
+                            }
                             case "hook_started":
                             case "hook_progress":
                             case "hook_response":
@@ -592,12 +1079,33 @@ export class ClaudeAcpAgent {
                             case "task_notification":
                             case "task_progress":
                             case "task_updated":
-                            case "elicitation_complete":
+                                break;
+                            case "worker_shutting_down":
+                                // A Remote Control worker announced a graceful teardown. This is a
+                                // live-tail signal for remote clients to explain why a session went
+                                // away; it's not meaningful for a local stdio ACP session.
+                                break;
+                            case "elicitation_complete": {
+                                // A url-mode MCP elicitation finished server-side. Let the client
+                                // dismiss any UI it opened for it. Only meaningful when the
+                                // client supports url elicitation; ignore failures otherwise.
+                                if (this.clientCapabilities?.elicitation?.url) {
+                                    try {
+                                        await this.client.unstable_completeElicitation({
+                                            elicitationId: message.elicitation_id,
+                                        });
+                                    }
+                                    catch (error) {
+                                        this.logger.error(`Failed to complete elicitation: ${error}`);
+                                    }
+                                }
+                                break;
+                            }
                             case "plugin_install":
                             case "notification":
                             case "api_retry":
-                            case "mirror_error":
-                            case "permission_denied":
+                            case "thinking_tokens":
+                            case "model_refusal_fallback":
                                 // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
                                 break;
                             default:
@@ -606,11 +1114,32 @@ export class ClaudeAcpAgent {
                         }
                         break;
                     case "result": {
-                        // Accumulate usage from this result
-                        session.accumulatedUsage.inputTokens += message.usage.input_tokens;
-                        session.accumulatedUsage.outputTokens += message.usage.output_tokens;
-                        session.accumulatedUsage.cachedReadTokens += message.usage.cache_read_input_tokens;
-                        session.accumulatedUsage.cachedWriteTokens += message.usage.cache_creation_input_tokens;
+                        // Task-notification followups are autonomous work triggered by a
+                        // task-notification system message, not by the user's prompt.
+                        // They should not influence the user-turn lifecycle (stop reason,
+                        // slash-command output forwarding) but their cost is real.
+                        const isTaskNotification = message.origin?.kind === "task-notification";
+                        // A user-turn result needs an active turn so its stop reason is
+                        // attributed and the turn settles at idle. Local-only commands carry
+                        // no user-message echo to promote them, so do it here from the head.
+                        // Promote BEFORE accumulating usage, since activation resets the
+                        // accumulator — promoting after would discard this result's tokens.
+                        if (!isTaskNotification) {
+                            ensureActiveTurn();
+                        }
+                        // Accumulate usage into the user turn's tally. Skip task-notification
+                        // followups: their cost is real but is reported separately via the
+                        // usage_update below, and `session.accumulatedUsage` is only reset on
+                        // turn activation — so folding a task-notification result that lands
+                        // after the next turn is active (but before it settles) would leak
+                        // those tokens into that turn's PromptResponse.usage.
+                        if (!isTaskNotification) {
+                            session.accumulatedUsage.inputTokens += message.usage.input_tokens;
+                            session.accumulatedUsage.outputTokens += message.usage.output_tokens;
+                            session.accumulatedUsage.cachedReadTokens += message.usage.cache_read_input_tokens;
+                            session.accumulatedUsage.cachedWriteTokens +=
+                                message.usage.cache_creation_input_tokens;
+                        }
                         const matchingModelUsage = lastAssistantModel
                             ? getMatchingModelUsage(message.modelUsage, lastAssistantModel)
                             : null;
@@ -621,11 +1150,6 @@ export class ClaudeAcpAgent {
                         if (matchingModelUsage) {
                             session.contextWindowSize = matchingModelUsage.contextWindow;
                         }
-                        // Task-notification followups are autonomous work triggered by a
-                        // task-notification system message, not by the user's prompt.
-                        // They should not influence the user-turn lifecycle (stop reason,
-                        // slash-command output forwarding) but their cost is real.
-                        const isTaskNotification = message.origin?.kind === "task-notification";
                         // Send usage_update notification
                         if (lastAssistantTotalUsage !== null) {
                             await this.client.sessionUpdate({
@@ -650,10 +1174,31 @@ export class ClaudeAcpAgent {
                             }
                             break;
                         }
+                        // A refusal can arrive on any result subtype (and may even set
+                        // is_error), so handle it before the subtype switch — otherwise the
+                        // is_error throw below would surface it as an internal error. The
+                        // refused assistant message carries no visible content, so surface
+                        // the classifier's explanation (when available) and report ACP's
+                        // dedicated `refusal` stop reason.
+                        if (message.stop_reason === "refusal" && !isTaskNotification) {
+                            if (lastRefusalExplanation) {
+                                await this.client.sessionUpdate({
+                                    sessionId: params.sessionId,
+                                    update: {
+                                        sessionUpdate: "agent_message_chunk",
+                                        content: { type: "text", text: lastRefusalExplanation },
+                                    },
+                                });
+                            }
+                            stopReason = "refusal";
+                            settleActive({ stopReason: "refusal", usage: sessionUsage(session) });
+                            break;
+                        }
                         switch (message.subtype) {
                             case "success": {
                                 if (message.result.includes("Please run /login")) {
-                                    throw RequestError.authRequired();
+                                    failActive(RequestError.authRequired());
+                                    break;
                                 }
                                 if (message.stop_reason === "max_tokens") {
                                     if (!isTaskNotification) {
@@ -662,14 +1207,15 @@ export class ClaudeAcpAgent {
                                     break;
                                 }
                                 if (message.is_error) {
-                                    throw RequestError.internalError(errorKindData(lastAssistantError), message.result);
+                                    failActive(RequestError.internalError(errorKindData(lastAssistantError), message.result));
+                                    break;
                                 }
                                 // For local-only commands (no model invocation), the result
                                 // text is the command output — forward it to the client.
                                 // Task-notification followups never originate from a user
                                 // slash command, so skip the forwarding for them.
-                                if (isLocalOnlyCommand && !isTaskNotification) {
-                                    for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, this.toolUseCache, this.client, this.logger)) {
+                                if (session.activeTurn?.isLocalOnlyCommand && !isTaskNotification) {
+                                    for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
                                         await this.client.sessionUpdate(notification);
                                     }
                                 }
@@ -683,7 +1229,8 @@ export class ClaudeAcpAgent {
                                     break;
                                 }
                                 if (message.is_error) {
-                                    throw RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype);
+                                    failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                    break;
                                 }
                                 if (!isTaskNotification) {
                                     stopReason = "end_turn";
@@ -694,7 +1241,8 @@ export class ClaudeAcpAgent {
                             case "error_max_turns":
                             case "error_max_structured_output_retries":
                                 if (message.is_error) {
-                                    throw RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype);
+                                    failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                    break;
                                 }
                                 if (!isTaskNotification) {
                                     stopReason = "max_turn_requests";
@@ -704,9 +1252,70 @@ export class ClaudeAcpAgent {
                                 unreachable(message, this.logger);
                                 break;
                         }
+                        // Settle the user turn at its terminal result so the client unlocks
+                        // as soon as the answer is done, rather than waiting for the SDK's
+                        // trailing `idle` (which can lag while background work runs — issue
+                        // #773). The consumer keeps draining afterward (absorbing idle and
+                        // forwarding any background output). is_error/auth already settled
+                        // via failActive; cancellation is left to the idle/abort path.
+                        // settleActive is idempotent, so a duplicate idle is a no-op.
+                        if (!isTaskNotification && !session.cancelled) {
+                            settleActive({ stopReason, usage: sessionUsage(session) });
+                        }
                         break;
                     }
                     case "stream_event": {
+                        // `message_start` carries the Anthropic API message id; capture it
+                        // so the streamed chunks that follow (whose delta events don't carry
+                        // it) can all be tagged with the same, replay-stable id.
+                        if (message.event.type === "message_start") {
+                            currentStreamMessageId = message.event.message.id || undefined;
+                            // A new top-level message starts: clear any streamed-content
+                            // residue from a prior message that never reached its
+                            // consolidated reset — a cancelled turn breaks out before the
+                            // reset, and the synthetic-auth/system/local-command paths
+                            // `break` early too. Block indices restart at 0 each message, so
+                            // leftover entries would otherwise collide with this message's
+                            // blocks and re-emit (or truncate) already-streamed text. Gated on
+                            // `parent_tool_use_id === null` so a subagent stream can't clear
+                            // the top-level record. Fires once, before any of this message's
+                            // blocks, so it doesn't disturb the mid-message turn-activation
+                            // path the way resetting on turn activation would.
+                            if (message.parent_tool_use_id === null) {
+                                streamedBlocks.length = 0;
+                            }
+                        }
+                        // Accumulate the text/thinking actually streamed live, so the
+                        // `assistant` case below can diff its assembled blocks against what
+                        // already reached the client as chunks and forward only the
+                        // remainder. Gated on `parent_tool_use_id === null` so a subagent
+                        // stream can't attribute its content to the top-level message.
+                        // Contiguous deltas of the same block (same index and type) extend
+                        // the current entry; anything else opens a new one.
+                        if (message.parent_tool_use_id === null &&
+                            message.event.type === "content_block_delta") {
+                            const delta = message.event.delta;
+                            const chunk = delta.type === "text_delta"
+                                ? { type: "text", text: delta.text }
+                                : delta.type === "thinking_delta"
+                                    ? { type: "thinking", text: delta.thinking }
+                                    : undefined;
+                            // Skip empty deltas (some gateways emit empty thinking chunks —
+                            // #793): appending "" is a no-op, but pushing a "" entry would
+                            // create a block the consolidated handler's `text.length > 0`
+                            // guard can never consume, stalling the diff cursor and
+                            // re-emitting the next block as a duplicate.
+                            if (chunk && chunk.text.length > 0) {
+                                const index = message.event.index;
+                                const last = streamedBlocks[streamedBlocks.length - 1];
+                                if (last && last.index === index && last.type === chunk.type) {
+                                    last.text += chunk.text;
+                                }
+                                else {
+                                    streamedBlocks.push({ index, type: chunk.type, text: chunk.text });
+                                }
+                            }
+                        }
                         if (message.parent_tool_use_id === null &&
                             (message.event.type === "message_start" || message.event.type === "message_delta")) {
                             if (message.event.type === "message_start") {
@@ -754,10 +1363,11 @@ export class ClaudeAcpAgent {
                                 });
                             }
                         }
-                        for (const notification of streamEventToAcpNotifications(message, params.sessionId, this.toolUseCache, this.client, this.logger, {
+                        for (const notification of streamEventToAcpNotifications(message, params.sessionId, session.toolUseCache, this.client, this.logger, {
                             clientCapabilities: this.clientCapabilities,
                             cwd: session.cwd,
                             taskState: session.taskState,
+                            messageId: currentStreamMessageId,
                         })) {
                             await this.client.sessionUpdate(notification);
                         }
@@ -765,28 +1375,49 @@ export class ClaudeAcpAgent {
                     }
                     case "user":
                     case "assistant": {
-                        if (session.cancelled) {
-                            break;
+                        // Record the ACP messageId -> SDK uuid mapping for this message
+                        // (including replays). The consolidated message carries both ids, so
+                        // this is where we learn the uuid the SDK's rewind/resume APIs key on
+                        // for the id we hand clients. Not read yet (see messageIdToUuid).
+                        const mappedMessageId = messageIdForGrouping(message);
+                        if (mappedMessageId && typeof message.uuid === "string" && message.uuid.length > 0) {
+                            session.messageIdToUuid.set(mappedMessageId, message.uuid);
                         }
-                        // Check for prompt replay
+                        // A replayed user message echoes a queued turn back in submission
+                        // order. The first echo promotes that turn to active; if a different
+                        // turn is still active, it is handed off (settled end_turn) first.
+                        // Done before the `cancelled` guard so a turn enqueued after a cancel
+                        // is still promoted — activateTurn() clears the flag. The turn's own
+                        // echo is then dropped from the feed (the client already shows it).
                         if (message.type === "user" && "uuid" in message && message.uuid) {
-                            if (message.uuid === promptUuid) {
+                            const queued = (session.turnQueue ?? []).find((t) => t.promptUuid === message.uuid && !t.settled);
+                            if (queued) {
+                                // Only (re)activate if this isn't already the active turn — a
+                                // turn promoted early (e.g. by a result that preceded its echo)
+                                // must not have its accumulated usage reset by its own echo.
+                                if (session.activeTurn !== queued) {
+                                    if (session.activeTurn) {
+                                        // Hand off the previous turn. If a cancel is pending for it
+                                        // (its trailing idle hasn't arrived yet), settle it
+                                        // "cancelled" per the ACP contract rather than "end_turn" —
+                                        // otherwise a cancel followed quickly by the next prompt
+                                        // would report the cancelled turn as a normal completion.
+                                        settleActive(session.cancelled
+                                            ? { stopReason: "cancelled" }
+                                            : { stopReason: "end_turn", usage: sessionUsage(session) });
+                                    }
+                                    activateTurn(queued);
+                                }
                                 break;
                             }
-                            const pending = session.pendingMessages.get(message.uuid);
-                            if (pending) {
-                                pending.resolve(false);
-                                session.pendingMessages.delete(message.uuid);
-                                handedOff = true;
-                                // the current loop stops with end_turn,
-                                // the loop of the next prompt continues running
-                                return { stopReason: "end_turn", usage: sessionUsage(session) };
-                            }
                             if ("isReplay" in message && message.isReplay) {
-                                // not pending or unrelated replay message
+                                // Unrelated replay (e.g. the echo of an already-settled turn).
                                 break;
                             }
                         }
+                        if (session.cancelled) {
+                            break;
+                        }
                         // Snapshot the latest top-level assistant usage and model so the
                         // next `result` can emit a usage_update tied to the right context
                         // window. Subagent messages are excluded to keep the snapshot
@@ -800,21 +1431,26 @@ export class ClaudeAcpAgent {
                             if (message.error) {
                                 lastAssistantError = message.error;
                             }
+                            if (message.message.stop_reason === "refusal") {
+                                lastRefusalExplanation = message.message.stop_details?.explanation ?? null;
+                            }
                         }
                         // Strip <command-*>/<local-command-stdout> markers and render any
                         // remaining prose. Skill bodies and built-in slash commands (e.g.
                         // /usage, /status, /model) arrive wrapped in these tags; pure-marker
                         // payloads (e.g. /compact's malformed output) strip to null and are
                         // skipped. Mirrors the replay path at replaySessionHistory.
-                        if (typeof message.message.content === "string" &&
+                        if (message.message.role !== "system" &&
+                            typeof message.message.content === "string" &&
                             message.message.content.includes("<local-command-stdout>")) {
                             const stripped = stripLocalCommandMetadata(message.message.content);
                             if (typeof stripped === "string") {
-                                for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, this.toolUseCache, this.client, this.logger, {
+                                for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
                                     clientCapabilities: this.clientCapabilities,
                                     parentToolUseId: message.parent_tool_use_id,
                                     cwd: session.cwd,
                                     taskState: session.taskState,
+                                    messageId: messageIdForGrouping(message),
                                 })) {
                                     await this.client.sessionUpdate(notification);
                                 }
@@ -837,106 +1473,171 @@ export class ClaudeAcpAgent {
                                     message.message.content[0].type === "text"))) {
                             break;
                         }
+                        if (message.message.role === "system") {
+                            break;
+                        }
                         if (message.type === "assistant" &&
                             message.message.model === "<synthetic>" &&
                             Array.isArray(message.message.content) &&
                             message.message.content.length === 1 &&
                             message.message.content[0].type === "text" &&
                             message.message.content[0].text.includes("Please run /login")) {
-                            throw RequestError.authRequired();
+                            failActive(RequestError.authRequired());
+                            break;
+                        }
+                        let content;
+                        if (message.type === "assistant" && message.parent_tool_use_id === null) {
+                            // Top-level assistant message: each text/thinking block may have
+                            // already been streamed live as deltas. Diff each against what
+                            // streamed (`streamedBlocks`, in document order) and forward only
+                            // the un-streamed remainder — nothing if it streamed in full (the
+                            // common case), the whole block if it never streamed (a
+                            // non-streaming gateway), or just the tail if the stream was cut
+                            // short mid-block. `streamPos` walks the streamed blocks in step
+                            // with the assembled text/thinking blocks; tool_use and other
+                            // blocks pass through untouched (their own `toolUseCache` collapses
+                            // the streamed/assembled pair) without advancing it.
+                            const blocks = message.message.content;
+                            const kept = [];
+                            let streamPos = 0;
+                            for (const item of blocks) {
+                                if (item.type !== "text" && item.type !== "thinking") {
+                                    kept.push(item);
+                                    continue;
+                                }
+                                const full = item.type === "text" ? item.text : item.thinking;
+                                // Empty assembled blocks carry nothing (some gateways emit an
+                                // empty `thinking` block before the real text) — drop them.
+                                if (full.length === 0) {
+                                    continue;
+                                }
+                                // A streamed block of the same type whose accumulated text is a
+                                // prefix of this one was already (at least partly) delivered as
+                                // chunks; consume it and forward only what's left. A non-empty
+                                // streamed text is required so an empty/aborted streamed block
+                                // doesn't swallow the assembled copy.
+                                const streamed = streamedBlocks[streamPos];
+                                if (streamed &&
+                                    streamed.type === item.type &&
+                                    streamed.text.length > 0 &&
+                                    full.startsWith(streamed.text)) {
+                                    streamPos++;
+                                    const remainder = full.slice(streamed.text.length);
+                                    if (remainder.length === 0) {
+                                        continue;
+                                    }
+                                    // Overwrite in place with just the un-streamed tail (the
+                                    // assembled message isn't read again after this) so the block
+                                    // keeps its exact SDK type.
+                                    if (item.type === "text") {
+                                        item.text = remainder;
+                                    }
+                                    else {
+                                        item.thinking = remainder;
+                                    }
+                                    kept.push(item);
+                                    continue;
+                                }
+                                // Not matched: never streamed (or the stream diverged from the
+                                // assembled text) — forward the block in full.
+                                kept.push(item);
+                            }
+                            content = kept;
+                            // Consumed: reset so the next message's blocks accumulate fresh and
+                            // the record stays bounded to the in-flight message.
+                            streamedBlocks.length = 0;
+                        }
+                        else if (message.type === "assistant") {
+                            // Subagent assistant message (`parent_tool_use_id !== null`). It is
+                            // never streamed live and its text/thinking is internal to the tool
+                            // call — keep dropping it so subagent prose doesn't leak into the
+                            // top-level feed.
+                            content = message.message.content.filter((item) => item.type !== "text" && item.type !== "thinking");
                         }
-                        const content = message.type === "assistant"
-                            ? // Handled by stream events above
-                                message.message.content.filter((item) => !["text", "thinking"].includes(item.type))
-                            : message.message.content;
-                        for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, this.toolUseCache, this.client, this.logger, {
+                        else {
+                            content = message.message.content;
+                        }
+                        for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
                             clientCapabilities: this.clientCapabilities,
                             parentToolUseId: message.parent_tool_use_id,
                             cwd: session.cwd,
                             taskState: session.taskState,
+                            messageId: messageIdForGrouping(message),
                         })) {
                             await this.client.sessionUpdate(notification);
                         }
                         break;
                     }
-                    case "tool_progress":
+                    case "tool_progress": {
+                        await this.client.sessionUpdate({
+                            sessionId: message.session_id,
+                            update: {
+                                sessionUpdate: "tool_call_update",
+                                toolCallId: message.tool_use_id,
+                                status: "in_progress",
+                                _meta: {
+                                    claudeCode: {
+                                        toolName: message.tool_name,
+                                        toolResponse: { elapsedTimeSeconds: message.elapsed_time_seconds },
+                                    },
+                                },
+                            },
+                        });
+                        break;
+                    }
+                    case "rate_limit_event": {
+                        if (lastAssistantTotalUsage !== null) {
+                            await this.client.sessionUpdate({
+                                sessionId: message.session_id,
+                                update: {
+                                    sessionUpdate: "usage_update",
+                                    used: lastAssistantTotalUsage,
+                                    size: session.contextWindowSize,
+                                    _meta: { "_claude/rateLimit": message.rate_limit_info },
+                                },
+                            });
+                        }
+                        break;
+                    }
                     case "tool_use_summary":
                     case "auth_status":
                     case "prompt_suggestion":
-                    case "rate_limit_event":
                         break;
                     default:
                         unreachable(message);
                         break;
                 }
             }
-            throw new Error("Session did not end in result");
+            // `while (true)` only exits via the `done` return above or the catch
+            // below, so there is no normal fall-through here.
         }
         catch (error) {
-            errored = true;
-            // A failed turn typically leaves a trailing `session_state_changed: idle`
-            // (and possibly more) in the query iterator. If we don't drain it here,
-            // the next prompt's first `query.next()` consumes that stale idle and
-            // short-circuits to end_turn with zero usage
-            // Bounded so a misbehaving SDK can't hang the next prompt indefinitely.
-            try {
-                await session.query.interrupt();
-                const MAX_DRAIN = 100;
-                for (let i = 0; i < MAX_DRAIN; i++) {
-                    const { value: m, done } = await session.query.next();
-                    if (done || !m)
-                        break;
-                    if (m.type === "system" && m.subtype === "session_state_changed" && m.state === "idle") {
-                        break;
-                    }
-                    if (i === MAX_DRAIN - 1) {
-                        this.logger.error(`Session ${params.sessionId}: drained ${MAX_DRAIN} messages after error without observing idle`);
-                    }
-                }
-            }
-            catch (drainErr) {
-                this.logger.error(`Session ${params.sessionId}: failed to drain query after prompt error:`, drainErr);
-            }
-            if (error instanceof RequestError || !(error instanceof Error)) {
-                throw error;
-            }
-            const message = error.message;
-            if (message.includes("ProcessTransport") ||
-                message.includes("terminated process") ||
-                message.includes("process exited with") ||
-                message.includes("process terminated by signal") ||
-                message.includes("Failed to write to process stdin")) {
+            // The query stream itself died (a transport/process error surfaced from
+            // query.next()). Turn-level failures (auth, error results) are handled
+            // inline via failActive and never reach here. Reject every in-flight turn;
+            // if the process is gone, tear the session down so the client starts fresh.
+            const message = error instanceof Error ? error.message : String(error);
+            const processDied = error instanceof Error &&
+                (message.includes("ProcessTransport") ||
+                    message.includes("terminated process") ||
+                    message.includes("process exited with") ||
+                    message.includes("process terminated by signal") ||
+                    message.includes("Failed to write to process stdin"));
+            // Either way the query iterator is finished and the consumer is exiting,
+            // so release its resources via closeQueryStream (idempotent). A process
+            // death is unrecoverable, so additionally evict the session so the client
+            // starts fresh; other stream errors keep the session so prompt()/cancel()
+            // can answer with a clear "session ended" error.
+            if (processDied) {
                 this.logger.error(`Session ${params.sessionId}: Claude Agent process died: ${message}`);
-                session.settingsManager.dispose();
-                session.input.end();
+                failAllTurns(RequestError.internalError(undefined, "The Claude Agent process exited unexpectedly. Please start a new session."));
+                this.closeQueryStream(session);
                 delete this.sessions[params.sessionId];
-                throw RequestError.internalError(undefined, "The Claude Agent process exited unexpectedly. Please start a new session.");
             }
-            throw error;
-        }
-        finally {
-            if (!handedOff) {
-                session.promptRunning = false;
-                if (errored) {
-                    // The query stream was just drained — handing pending prompts off
-                    // onto it would let them race with the recovery. Cancel them so
-                    // each waiting prompt() returns stopReason: "cancelled" and the
-                    // client can decide whether to retry.
-                    for (const pending of session.pendingMessages.values()) {
-                        pending.resolve(true);
-                    }
-                    session.pendingMessages.clear();
-                }
-                else if (session.pendingMessages.size > 0) {
-                    // This usually should not happen, but in case the loop finishes
-                    // without claude sending all message replays, we resolve the
-                    // next pending prompt call to ensure no prompts get stuck.
-                    const next = [...session.pendingMessages.entries()].sort((a, b) => a[1].order - b[1].order)[0];
-                    if (next) {
-                        next[1].resolve(false);
-                        session.pendingMessages.delete(next[0]);
-                    }
-                }
+            else {
+                this.logger.error(`Session ${params.sessionId}: query stream error: ${message}`);
+                failAllTurns(error);
+                this.closeQueryStream(session);
             }
         }
     }
@@ -945,24 +1646,112 @@ export class ClaudeAcpAgent {
         if (!session) {
             return;
         }
+        // The stream already ended (see closeQueryStream): every in-flight turn was
+        // settled when it closed, and there is no live query to interrupt. Calling
+        // query.interrupt() on a finished iterator could reject and surface from
+        // this fire-and-forget notification, so there is nothing to do here.
+        if (session.queryClosed) {
+            return;
+        }
         session.cancelled = true;
-        for (const [, pending] of session.pendingMessages) {
-            pending.resolve(true);
+        // Settle queued turns that haven't started yet (no echo seen) right away —
+        // they have no in-flight SDK work to interrupt. The active turn is settled
+        // by the consumer when it observes the interrupt's trailing idle (or via the
+        // backstop below). Mirrors the old pendingMessages cancellation.
+        if (session.turnQueue) {
+            let orphaned = 0;
+            for (const turn of session.turnQueue) {
+                if (turn !== session.activeTurn && !turn.settled) {
+                    turn.settled = true;
+                    turn.resolve({ stopReason: "cancelled" });
+                    orphaned++;
+                }
+            }
+            // Each removed queued turn's user message was already pushed to the SDK,
+            // which processes input FIFO and will still emit a result for it with no
+            // uuid to match. Count those so the consumer skips them (see
+            // ensureActiveTurn) rather than misattributing them to the head.
+            session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + orphaned;
+            session.turnQueue = session.turnQueue.filter((turn) => turn === session.activeTurn && !turn.settled);
+        }
+        // Arm a backstop before interrupting: if a turn is actively consuming the
+        // query and interrupt() doesn't make the SDK yield (e.g. a wedged TaskOutput
+        // block — issue #680), force the consumer to settle the active turn
+        // "cancelled" after the floor elapses so the pending session/prompt still
+        // resolves per the ACP cancellation contract instead of hanging forever. The
+        // consumer clears this timer when interrupt() works and it settles through
+        // the normal idle path, so on healthy cancels it is armed but never fires.
+        //
+        // Arm at most once per turn: the floor is an absolute ceiling from the first
+        // cancel, so a client that re-sends cancel (each call still retries
+        // interrupt() below) can't keep pushing the deadline out.
+        if (session.activeTurn &&
+            session.cancelController &&
+            !session.cancelController.signal.aborted &&
+            !session.forceCancelTimer) {
+            const cancelController = session.cancelController;
+            session.forceCancelTimer = setTimeout(() => {
+                this.logger.error(`Session ${params.sessionId}: cancel floor elapsed without the SDK yielding; forcing "cancelled". The underlying query may still be wedged — a new session may be required.`);
+                cancelController.abort();
+            }, this.forceCancelGraceMs);
         }
-        session.pendingMessages.clear();
         await session.query.interrupt();
     }
-    /** Cleanly tear down a session: cancel in-flight work, dispose resources,
-     *  and remove it from the session map. */
+    /** Mark a session's SDK query stream as permanently ended and release the
+     *  resources tied to it: drop the consumer handle, dispose the settings
+     *  watchers, end the input stream, and close the query (which terminates the
+     *  subprocess). The query iterator is not revivable, so `prompt()`/`cancel()`
+     *  consult `queryClosed` and fail/short-circuit instead of acting on a dead
+     *  stream. Idempotent (guarded by `queryClosed`), so the consumer's done/error
+     *  paths and a later `teardownSession` can all call it without double-releasing.
+     *
+     *  Deliberately does NOT abort `session.abortController`: that controller may be
+     *  CLIENT-supplied (`_meta.claudeCode.options.abortController`) and reused, so
+     *  aborting it on a spontaneous stream end would cancel the client's own work
+     *  or make a sibling session born aborted. `query.close()` already terminates
+     *  the subprocess; aborting the signal belongs in `teardownSession` (explicit
+     *  destroy), not here. Also does NOT remove the session from the map — that is
+     *  `teardownSession`'s job — so prompt() can still answer with a clear "session
+     *  ended" error after an unexpected stream close. The leftover session object
+     *  is a lightweight husk (its heavy resources are released here) and is evicted
+     *  on the next closeSession/deleteSession or when the connection's `dispose()`
+     *  runs. */
+    closeQueryStream(session) {
+        if (session.queryClosed) {
+            return;
+        }
+        session.queryClosed = true;
+        session.consumer = undefined;
+        session.settingsManager.dispose();
+        session.input.end();
+        session.query.close();
+    }
+    /** Cleanly tear down a session: cancel in-flight work, release stream
+     *  resources, and remove it from the session map. */
     async teardownSession(sessionId) {
         const session = this.sessions[sessionId];
         if (!session) {
             return;
         }
         await this.cancel({ sessionId });
-        session.settingsManager.dispose();
+        // cancel() arms the force-cancel floor and interrupts gracefully, but a
+        // wedged consumer only wakes when `cancelController` aborts — closeQueryStream
+        // below doesn't touch it. Since we're tearing the session down anyway, wake
+        // the consumer now so the in-flight prompt() resolves immediately instead of
+        // after the floor, and clear the timer so it can't outlive the deleted
+        // session (it isn't unref'd and would otherwise keep the event loop alive
+        // until it fires).
+        if (session.forceCancelTimer) {
+            clearTimeout(session.forceCancelTimer);
+            session.forceCancelTimer = undefined;
+        }
+        session.cancelController?.abort();
+        this.closeQueryStream(session);
+        // Abort the SDK abort signal only on explicit destroy. closeQueryStream
+        // leaves it alone (it may be a client-owned controller — see its doc), but
+        // here the client has asked us to close the session, so signalling abort is
+        // appropriate; query.close() above has already torn the subprocess down.
         session.abortController.abort();
-        session.query.close();
         delete this.sessions[sessionId];
     }
     /** Tear down all active sessions. Called when the ACP connection closes. */
@@ -976,7 +1765,7 @@ export class ClaudeAcpAgent {
         await this.teardownSession(params.sessionId);
         return {};
     }
-    async unstable_deleteSession(params) {
+    async deleteSession(params) {
         // Tear down any active in-memory state first so the on-disk file isn't
         // recreated by an outstanding query writing to it.
         if (this.sessions[params.sessionId]) {
@@ -985,22 +1774,16 @@ export class ClaudeAcpAgent {
         await deleteSession(params.sessionId);
         return {};
     }
-    async unstable_setSessionModel(params) {
+    async setSessionMode(params) {
         const session = this.sessions[params.sessionId];
         if (!session) {
             throw new Error("Session not found");
         }
-        // Resolve aliases (e.g. "opus", "opus[1m]") to canonical model IDs so
-        // downstream lookups in modelInfos succeed and the effort option isn't
-        // silently dropped.
-        const resolved = resolveModelPreference(session.modelInfos, params.modelId);
-        const modelId = resolved?.value ?? params.modelId;
-        await session.query.setModel(modelId);
-        await this.updateConfigOption(params.sessionId, "model", modelId);
-    }
-    async setSessionMode(params) {
-        if (!this.sessions[params.sessionId]) {
-            throw new Error("Session not found");
+        // The SDK query stream already ended (see closeQueryStream); the session is
+        // a husk and `query.setPermissionMode` below would act on a closed query.
+        // Fail with the same clear message prompt()/cancel() give for a dead stream.
+        if (session.queryClosed) {
+            throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
         }
         await this.applySessionMode(params.sessionId, params.modeId);
         await this.updateConfigOption(params.sessionId, "mode", params.modeId);
@@ -1011,6 +1794,13 @@ export class ClaudeAcpAgent {
         if (!session) {
             throw new Error("Session not found");
         }
+        // The SDK query stream already ended (see closeQueryStream); the session is
+        // a husk and the `query.setModel`/`setPermissionMode`/`applyFlagSettings`
+        // calls this triggers would act on a closed query. Fail with the same clear
+        // message prompt()/cancel() give for a dead stream.
+        if (session.queryClosed) {
+            throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
+        }
         if (typeof params.value !== "string") {
             throw new Error(`Invalid value for config option ${params.configId}: ${params.value}`);
         }
@@ -1100,6 +1890,15 @@ export class ClaudeAcpAgent {
         const toolUseCache = {};
         const messages = await getSessionMessages(sessionId);
         for (const message of messages) {
+            // Backfill the ACP messageId -> SDK uuid mapping for messages we didn't
+            // observe live (resumed/loaded sessions), so rewind/resume can translate
+            // a client-supplied id without an extra getSessionMessages read. Not read
+            // yet (see Session.messageIdToUuid).
+            const replayMessageId = messageIdForGrouping(message);
+            const replaySession = this.sessions[sessionId];
+            if (replaySession && replayMessageId && message.uuid) {
+                replaySession.messageIdToUuid.set(replayMessageId, message.uuid);
+            }
             // @ts-expect-error - untyped in SDK but we handle all of these
             let content = message.message.content;
             // @ts-expect-error - untyped in SDK but we handle all of these
@@ -1117,6 +1916,7 @@ export class ClaudeAcpAgent {
                 clientCapabilities: this.clientCapabilities,
                 cwd: this.sessions[sessionId]?.cwd,
                 taskState: this.sessions[sessionId]?.taskState,
+                messageId: replayMessageId,
             })) {
                 await this.client.sessionUpdate(notification);
             }
@@ -1130,6 +1930,24 @@ export class ClaudeAcpAgent {
         const response = await this.client.writeTextFile(params);
         return response;
     }
+    /** Forward a permission request to the client, wiring the tool call's
+     *  `signal` through as a `cancellationSignal`. When the turn is cancelled
+     *  while the client's prompt is still open the signal aborts, the SDK sends
+     *  `$/cancel_request`, and the client settles the request (a `cancelled`
+     *  outcome or a `requestCancelled` rejection). Either way we surface the same
+     *  "Tool use aborted" the callers already expect, so a cancelled dialog no
+     *  longer leaves the `await` hanging. */
+    async requestPermissionFromClient(params, signal) {
+        try {
+            return await this.client.requestPermission(params, signal);
+        }
+        catch (error) {
+            if (signal.aborted) {
+                throw new Error("Tool use aborted", { cause: error });
+            }
+            throw error;
+        }
+    }
     canUseTool(sessionId) {
         return async (toolName, toolInput, { signal, suggestions, toolUseID }) => {
             const alwaysAllowLabel = describeAlwaysAllow(suggestions, toolName);
@@ -1141,6 +1959,13 @@ export class ClaudeAcpAgent {
                     message: "Session not found",
                 };
             }
+            // AskUserQuestion is surfaced to us as a normal permission check (the SDK
+            // routes it through canUseTool whenever a callback is registered, rather
+            // than the interactive dialog). Present it as an ACP form elicitation and
+            // feed the answers back as updatedInput for the tool's own call() to read.
+            if (toolName === "AskUserQuestion" && this.clientCapabilities?.elicitation?.form) {
+                return this.handleAskUserQuestion(sessionId, toolInput, toolUseID, signal);
+            }
             if (toolName === "ExitPlanMode") {
                 const optionsAll = [
                     { kind: "allow_always", name: 'Yes, and use "auto" mode', optionId: "auto" },
@@ -1165,7 +1990,7 @@ export class ClaudeAcpAgent {
                 // `buildAvailableModes`/`ALLOW_BYPASS`. The `plan` option is a
                 // "keep planning" reject path; it's always present in `availableModes`.
                 const options = optionsAll.filter((o) => session.modes.availableModes.some((m) => m.id === o.optionId));
-                const response = await this.client.requestPermission({
+                const response = await this.requestPermissionFromClient({
                     options,
                     sessionId,
                     toolCall: {
@@ -1173,7 +1998,7 @@ export class ClaudeAcpAgent {
                         rawInput: toolInput,
                         ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
                     },
-                });
+                }, signal);
                 if (signal.aborted || response.outcome?.outcome === "cancelled") {
                     throw new Error("Tool use aborted");
                 }
@@ -1216,7 +2041,7 @@ export class ClaudeAcpAgent {
                     ],
                 };
             }
-            const response = await this.client.requestPermission({
+            const response = await this.requestPermissionFromClient({
                 options: [
                     {
                         kind: "allow_always",
@@ -1232,7 +2057,7 @@ export class ClaudeAcpAgent {
                     rawInput: toolInput,
                     ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
                 },
-            });
+            }, signal);
             if (signal.aborted || response.outcome?.outcome === "cancelled") {
                 throw new Error("Tool use aborted");
             }
@@ -1266,6 +2091,72 @@ export class ClaudeAcpAgent {
             }
         };
     }
+    /**
+     * Handle elicitation requests that originate from MCP servers by forwarding
+     * them to the client over ACP. Modes the client did not advertise (or
+     * requests we can't represent) are declined.
+     */
+    handleMcpElicitation(sessionId, support) {
+        return async (request, { signal }) => {
+            const isUrl = request.mode === "url";
+            if ((isUrl && !support.url) || (!isUrl && !support.form)) {
+                return { action: "decline" };
+            }
+            const createRequest = mcpElicitationToCreateRequest(request, sessionId);
+            if (!createRequest) {
+                return { action: "decline" };
+            }
+            try {
+                const response = await this.client.unstable_createElicitation(createRequest, signal);
+                if (signal.aborted) {
+                    return { action: "cancel" };
+                }
+                return createElicitationResponseToElicitResult(response);
+            }
+            catch (error) {
+                // A cancellation we requested (signal aborted) settles as a cancel, not
+                // a hard decline — the elicitation was abandoned, not refused.
+                if (signal.aborted) {
+                    return { action: "cancel" };
+                }
+                this.logger.error(`Failed to forward MCP elicitation: ${error}`);
+                return { action: "decline" };
+            }
+        };
+    }
+    /**
+     * Present the built-in AskUserQuestion tool's questions as an ACP form
+     * elicitation and return the answers as the tool's `updatedInput`. Called from
+     * `canUseTool` since that is where the SDK routes the tool's permission check.
+     */
+    async handleAskUserQuestion(sessionId, toolInput, toolUseID, signal) {
+        const questions = extractAskUserQuestions(toolInput);
+        if (!questions) {
+            return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
+        }
+        const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID);
+        let response;
+        try {
+            response = await this.client.unstable_createElicitation(createRequest, signal);
+        }
+        catch (error) {
+            // A cancellation we requested (signal aborted) settles as an aborted tool
+            // use, matching the post-response check below.
+            if (signal.aborted) {
+                throw new Error("Tool use aborted", { cause: error });
+            }
+            this.logger.error(`Failed to present AskUserQuestion elicitation: ${error}`);
+            return { behavior: "deny", message: "Could not present the question to the user." };
+        }
+        if (signal.aborted) {
+            throw new Error("Tool use aborted");
+        }
+        const outcome = applyAskElicitationResponse(response, toolInput, questions);
+        if (outcome.action === "cancel") {
+            throw new Error("Tool use aborted");
+        }
+        return { behavior: "allow", updatedInput: outcome.updatedInput };
+    }
     async sendAvailableCommandsUpdate(sessionId) {
         const session = this.sessions[sessionId];
         if (!session)
@@ -1298,18 +2189,22 @@ export class ClaudeAcpAgent {
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
         }
         else if (configId === "model") {
+            // `ModelInfo.supportsAutoMode` is the canonical SDK signal for clamping
+            // modes below; its `displayName`/`description` also let us infer the
+            // context window for semantic aliases (e.g. `default`) whose ID alone
+            // carries no "1m" token.
+            const newModelInfo = session.modelInfos.find((m) => m.value === value);
             if (session.models.currentModelId !== value) {
                 // The cached context window was learned for the previous model; reset
                 // to the new model's heuristic so mid-stream updates between now and
                 // the next `result` reflect the user's selection instead of the old
                 // model's window.
-                session.contextWindowSize = inferContextWindowFromModel(value) ?? DEFAULT_CONTEXT_WINDOW;
+                session.contextWindowSize =
+                    inferContextWindowFromModel(value, newModelInfo?.displayName, newModelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW;
             }
             session.models = { ...session.models, currentModelId: value };
             // Recompute availableModes for the new model and clamp the current
             // mode if the SDK no longer offers it (today: "auto" on Haiku).
-            // `ModelInfo.supportsAutoMode` is the canonical SDK signal.
-            const newModelInfo = session.modelInfos.find((m) => m.value === value);
             const newAvailableModes = buildAvailableModes(newModelInfo);
             // Capture BEFORE mutating session.modes so the log message reflects
             // the invalidated mode rather than "default".
@@ -1338,7 +2233,7 @@ export class ClaudeAcpAgent {
             // Rebuild config options since effort levels depend on the selected model
             const effortOpt = session.configOptions.find((o) => o.id === "effort");
             const currentEffort = typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
-            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, currentEffort);
+            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, currentEffort, session.agents, session.currentAgent);
             // Sync effort with the SDK if it changed after the model switch
             const newEffortOpt = session.configOptions.find((o) => o.id === "effort");
             const newEffort = typeof newEffortOpt?.currentValue === "string" ? newEffortOpt.currentValue : undefined;
@@ -1363,6 +2258,18 @@ export class ClaudeAcpAgent {
                 });
             }
         }
+        else if (configId === "agent") {
+            // Live agent switch — no subprocess restart needed. Apply the SDK flag
+            // first so a rejected control request leaves both `currentAgent` and the
+            // config option untouched (no UI/SDK desync). Passing `null` clears the
+            // flag layer back to the standard Claude Code agent; the change takes
+            // effect on the next turn (SDK >= 0.3.161).
+            await session.query.applyFlagSettings({
+                agent: value === DEFAULT_AGENT_ID ? null : value,
+            });
+            session.currentAgent = value;
+            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+        }
         else {
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
             if (configId === "effort") {
@@ -1380,7 +2287,6 @@ export class ClaudeAcpAgent {
                 return {
                     sessionId: params.sessionId,
                     modes: existingSession.modes,
-                    models: existingSession.models,
                     configOptions: existingSession.configOptions,
                 };
             }
@@ -1400,11 +2306,37 @@ export class ClaudeAcpAgent {
         return {
             sessionId: response.sessionId,
             modes: response.modes,
-            models: response.models,
             configOptions: response.configOptions,
         };
     }
+    /**
+     * Ensures the requested `cwd` is an absolute path that points at an existing
+     * directory before we create a session. Throws an `invalidParams` error with
+     * an actionable message so clients (e.g. Zed) can surface it to the user
+     * instead of failing later with an opaque SDK error.
+     */
+    async validateCwd(cwd) {
+        if (!path.isAbsolute(cwd)) {
+            throw RequestError.invalidParams({ cwd }, `\`cwd\` must be an absolute path, but received: ${cwd}`);
+        }
+        let stats;
+        try {
+            stats = await fs.stat(cwd);
+        }
+        catch {
+            throw RequestError.invalidParams({ cwd }, `\`cwd\` does not exist on the machine running the agent: ${cwd}`);
+        }
+        if (!stats.isDirectory()) {
+            throw RequestError.invalidParams({ cwd }, `\`cwd\` is not a directory: ${cwd}`);
+        }
+    }
     async createSession(params, creationOpts = {}) {
+        // Validate `cwd` up front. The ACP spec requires an absolute path, and the
+        // directory must actually exist on the machine running the agent. Without
+        // this check a session is created against a missing directory and the
+        // failure only surfaces later as a confusing "native binary failed to
+        // launch" error from the SDK (see issue #749).
+        await this.validateCwd(params.cwd);
         // We want to create a new session id unless it is resume,
         // but not resume + forkSession.
         let sessionId;
@@ -1470,13 +2402,17 @@ export class ClaudeAcpAgent {
         // Extract options from _meta if provided
         const sessionMeta = params._meta;
         const userProvidedOptions = sessionMeta?.claudeCode?.options;
-        // Configure thinking tokens from environment variable
-        const maxThinkingTokens = process.env.MAX_THINKING_TOKENS
-            ? parseInt(process.env.MAX_THINKING_TOKENS, 10)
-            : undefined;
+        // Configure thinking behavior from environment variable
+        const thinking = resolveThinkingConfig(process.env.MAX_THINKING_TOKENS, this.logger);
         // Parse model configuration from environment (e.g. Bedrock model overrides)
         const modelConfig = parseModelConfig(process.env.CLAUDE_MODEL_CONFIG);
-        // Disable this for now, not a great way to expose this over ACP at the moment (in progress work so we can revisit)
+        // Elicitation modes the connected client advertised. We only forward
+        // elicitations (and only re-enable AskUserQuestion) for modes the client
+        // can actually render.
+        const elicitationSupport = {
+            form: !!this.clientCapabilities?.elicitation?.form,
+            url: !!this.clientCapabilities?.elicitation?.url,
+        };
         const disallowedTools = ["AskUserQuestion", "WebFetch", "WebSearch"];
         // Resolve which built-in tools to expose.
         // Explicit tools array from _meta.claudeCode.options takes precedence.
@@ -1492,7 +2428,7 @@ export class ClaudeAcpAgent {
         const options = {
             systemPrompt,
             settingSources: ["user", "project", "local"],
-            ...(maxThinkingTokens !== undefined && { maxThinkingTokens }),
+            ...(thinking !== undefined && { thinking }),
             ...userProvidedOptions,
             // CLAUDE_MODEL_CONFIG env var is a fallback for model
             // configuration (e.g. Bedrock model ID overrides). When the caller
@@ -1521,6 +2457,13 @@ export class ClaudeAcpAgent {
             allowDangerouslySkipPermissions: ALLOW_BYPASS,
             permissionMode,
             canUseTool: this.canUseTool(sessionId),
+            // Forward MCP elicitation requests onto ACP elicitation. Only attached
+            // when the client advertised support, so non-supporting clients keep the
+            // SDK's default (auto-decline) behavior. (AskUserQuestion is handled in
+            // canUseTool, not here.)
+            ...(elicitationSupport.form || elicitationSupport.url
+                ? { onElicitation: this.handleMcpElicitation(sessionId, elicitationSupport) }
+                : {}),
             pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE ?? (await claudeCliPath()),
             extraArgs: {
                 ...userProvidedOptions?.extraArgs,
@@ -1675,7 +2618,17 @@ export class ClaudeAcpAgent {
             currentModeId: effectiveMode,
             availableModes,
         };
-        const configOptions = buildConfigOptions(modes, models, allowedModels, settingsManager.getSettings().effortLevel);
+        const agents = await discoverCustomAgents(q);
+        // Only adopt the requested agent as the selected value if it's one we
+        // actually surface in the picker. A built-in (filtered out above) or
+        // otherwise-unknown name would leave the config option's `currentValue`
+        // pointing at an entry not in its own `options` list, which clients render
+        // as a blank/invalid selection.
+        const requestedAgent = userProvidedOptions?.agent;
+        const currentAgent = requestedAgent && agents.some((a) => a.name === requestedAgent)
+            ? requestedAgent
+            : DEFAULT_AGENT_ID;
+        const configOptions = buildConfigOptions(modes, models, allowedModels, settingsManager.getSettings().effortLevel, agents, currentAgent);
         // Apply the initial effort level to the SDK so it matches the UI default
         const initialEffort = configOptions.find((o) => o.id === "effort");
         if (initialEffort &&
@@ -1702,17 +2655,17 @@ export class ClaudeAcpAgent {
             models,
             modelInfos: allowedModels,
             configOptions,
-            promptRunning: false,
-            pendingMessages: new Map(),
-            nextPendingOrder: 0,
+            agents,
+            currentAgent,
             abortController,
             emitRawSDKMessages: sessionMeta?.claudeCode?.emitRawSDKMessages ?? false,
-            contextWindowSize: inferContextWindowFromModel(models.currentModelId) ?? DEFAULT_CONTEXT_WINDOW,
+            contextWindowSize: inferContextWindowFromModel(models.currentModelId, currentModelInfo?.displayName, currentModelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW,
             taskState,
+            toolUseCache: {},
+            messageIdToUuid: new Map(),
         };
         return {
             sessionId,
-            models,
             modes,
             configOptions,
         };
@@ -1850,7 +2803,39 @@ function buildAvailableModes(modelInfo) {
 function toSdkEffortLevel(value) {
     return value === undefined || value === "default" ? null : value;
 }
-function buildConfigOptions(modes, models, modelInfos, currentEffortLevel) {
+// `supportedAgents()` always returns Claude Code's built-in subagents — the
+// ones used for Task-tool delegation (Explore, Plan, etc.) — even when the user
+// has configured none of their own. Those aren't meaningful *main-thread*
+// personas, so we filter them out and only surface the Agent picker when the
+// user (or a plugin/project) has configured custom agents. Update this set if
+// the SDK's built-in roster changes.
+export const BUILTIN_AGENT_NAMES = new Set([
+    "claude",
+    "general-purpose",
+    "Explore",
+    "Plan",
+    "statusline-setup",
+]);
+// Value of the synthetic "Default" entry in the agent picker, which maps to the
+// standard Claude Code agent (`applyFlagSettings({ agent: null })`). It is a
+// reserved sentinel: a custom agent named exactly this would collide with it
+// (two options sharing the value, selection silently routing to `null`), so we
+// exclude that name from discovery.
+export const DEFAULT_AGENT_ID = "default";
+/** Discover user/plugin/project-configured main-thread agents, excluding the
+ *  built-in subagents and the reserved "default" sentinel. Returns an empty
+ *  list if discovery fails so a flaky control request never blocks session
+ *  creation. */
+export async function discoverCustomAgents(q) {
+    try {
+        const agents = await q.supportedAgents();
+        return agents.filter((a) => !BUILTIN_AGENT_NAMES.has(a.name) && a.name !== DEFAULT_AGENT_ID);
+    }
+    catch {
+        return [];
+    }
+}
+export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, agents = [], currentAgent = DEFAULT_AGENT_ID) {
     const options = [
         {
             id: "mode",
@@ -1907,6 +2892,27 @@ function buildConfigOptions(modes, models, modelInfos, currentEffortLevel) {
             options: effortOptions,
         });
     }
+    // Only surface the Agent picker when there's a real choice — i.e. the user
+    // has configured at least one custom agent (built-ins are filtered out in
+    // discoverCustomAgents). With none configured, "Default" would be the only
+    // entry, so we omit the option entirely.
+    if (agents.length > 0) {
+        options.push({
+            id: "agent",
+            name: "Agent",
+            description: "Main-thread agent persona",
+            type: "select",
+            currentValue: currentAgent,
+            options: [
+                { value: DEFAULT_AGENT_ID, name: "Default", description: "Standard Claude Code agent" },
+                ...agents.map((a) => ({
+                    value: a.name,
+                    name: a.name,
+                    description: a.description || undefined,
+                })),
+            ],
+        });
+    }
     return options;
 }
 // Claude Code CLI persists display strings like "opus[1m]" in settings,
@@ -1951,11 +2957,16 @@ function tokenizeModelPreference(model) {
 function scoreModelMatch(model, tokens, contextHint) {
     const haystack = `${model.value} ${model.displayName}`.toLowerCase();
     let score = 0;
+    let nonHintMatched = false;
     for (const token of tokens) {
         if (haystack.includes(token)) {
+            if (token !== contextHint)
+                nonHintMatched = true;
             score += token === contextHint ? 3 : 1;
         }
     }
+    if (contextHint && !nonHintMatched)
+        return 0;
     return score;
 }
 function resolveModelPreference(models, preference) {
@@ -2048,6 +3059,20 @@ function applyAvailableModelsAllowlist(sdkModels, allowlist) {
         }
         seen.add(trimmed);
     }
+    // The custom model option (ANTHROPIC_CUSTOM_MODEL_OPTION) is exempt from the
+    // allowlist, the same way Default is. Per the model-config docs it adds an
+    // entry "without replacing the built-in aliases" and "appears at the bottom of
+    // the /model picker", so we append it last and skip the allowlist filter; this
+    // keeps a slim alias allowlist from hiding the custom model row.
+    // https://code.claude.com/docs/en/model-config#add-a-custom-model-option
+    const customModelOption = process.env.ANTHROPIC_CUSTOM_MODEL_OPTION?.trim();
+    if (customModelOption && !seen.has(customModelOption)) {
+        const customModel = sdkModels.find((m) => m.value === customModelOption);
+        if (customModel) {
+            result.push(customModel);
+            seen.add(customModel.value);
+        }
+    }
     return result;
 }
 async function getAvailableModels(query, models, sdkModels, settingsManager, logger) {
@@ -2223,6 +3248,42 @@ export function promptToClaude(prompt) {
         parent_tool_use_id: null,
     };
 }
+/**
+ * Resolves the ACP `messageId` for a Claude SDK message (live) or a persisted
+ * transcript message (replay) so chunk grouping is identical in both views.
+ *
+ * Assistant turns are keyed by the Anthropic API message id (`message.id`),
+ * which is identical at `message_start`, on the consolidated assistant message,
+ * and in the persisted transcript — unlike the per-`stream_event` uuid, which is
+ * unique per event and never persisted. User messages have no API id, but they
+ * are never streamed, so their (stable) SDK uuid is used instead. ACP message
+ * ids are opaque strings, so no particular format is required.
+ */
+export function messageIdForGrouping(message) {
+    if (message.type === "assistant") {
+        const inner = message.message;
+        const apiId = inner && typeof inner === "object" && "id" in inner
+            ? inner.id
+            : undefined;
+        if (typeof apiId === "string" && apiId.length > 0) {
+            return apiId;
+        }
+    }
+    return typeof message.uuid === "string" && message.uuid.length > 0 ? message.uuid : undefined;
+}
+/**
+ * Stamps an ACP `messageId` onto a session update, but only on the message/
+ * thought chunk variants that carry one — tool_call/plan/etc. updates never do.
+ * No-op when `messageId` is falsy, so callers can pass it through unconditionally.
+ */
+function applyMessageId(update, messageId) {
+    if (messageId &&
+        (update.sessionUpdate === "agent_message_chunk" ||
+            update.sessionUpdate === "user_message_chunk" ||
+            update.sessionUpdate === "agent_thought_chunk")) {
+        update.messageId = messageId;
+    }
+}
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
@@ -2239,6 +3300,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 text: content,
             },
         };
+        applyMessageId(update, options?.messageId);
         if (options?.parentToolUseId) {
             update._meta = {
                 ...update._meta,
@@ -2278,13 +3340,17 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 break;
             case "thinking":
             case "thinking_delta":
-                update = {
-                    sessionUpdate: "agent_thought_chunk",
-                    content: {
-                        type: "text",
-                        text: chunk.thinking,
-                    },
-                };
+                // Recent models default `thinking.display` to "omitted", which streams
+                // signature-only thinking blocks whose text is empty.
+                if (chunk.thinking.length > 0) {
+                    update = {
+                        sessionUpdate: "agent_thought_chunk",
+                        content: {
+                            type: "text",
+                            text: chunk.thinking,
+                        },
+                    };
+                }
                 break;
             case "tool_use":
             case "server_tool_use":
@@ -2311,40 +3377,40 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 else {
                     // Only register hooks on first encounter to avoid double-firing
                     if (registerHooks && !alreadyCached) {
+                        // Capture the tool name in the closure rather than re-reading the
+                        // cache when the hook fires. The cache entry is pruned at
+                        // tool_result time, and a PostToolUse hook can fire after that, so
+                        // closing over the name keeps the diff working without depending on
+                        // (or pinning) the cache entry's lifetime.
+                        const toolName = chunk.name;
                         registerHookCallback(chunk.id, {
                             onPostToolUseHook: async (toolUseId, toolInput, toolResponse) => {
-                                const toolUse = toolUseCache[toolUseId];
-                                if (toolUse) {
-                                    // Both `Edit` and `Write` produce a structuredPatch in their
-                                    // PostToolUse tool_response. For Edit the diff replaces the
-                                    // optimistic content built at tool_use time. For Write the
-                                    // optimistic content (built from `input.content` alone with
-                                    // `oldText: null`) shows "creation" semantics regardless of
-                                    // whether the file existed; the structuredPatch from the
-                                    // hook lets us emit the real diff for `type: "update"`. The
-                                    // helper returns `{}` if the response shape isn't usable.
-                                    const editDiff = toolUse.name === "Edit" || toolUse.name === "Write"
-                                        ? toolUpdateFromDiffToolResponse(toolResponse)
-                                        : {};
-                                    const update = {
-                                        _meta: {
-                                            claudeCode: {
-                                                toolResponse,
-                                                toolName: toolUse.name,
-                                            },
+                                // Both `Edit` and `Write` produce a structuredPatch in their
+                                // PostToolUse tool_response. For Edit the diff replaces the
+                                // optimistic content built at tool_use time. For Write the
+                                // optimistic content (built from `input.content` alone with
+                                // `oldText: null`) shows "creation" semantics regardless of
+                                // whether the file existed; the structuredPatch from the
+                                // hook lets us emit the real diff for `type: "update"`. The
+                                // helper returns `{}` if the response shape isn't usable.
+                                const editDiff = toolName === "Edit" || toolName === "Write"
+                                    ? toolUpdateFromDiffToolResponse(toolResponse)
+                                    : {};
+                                const update = {
+                                    _meta: {
+                                        claudeCode: {
+                                            toolResponse,
+                                            toolName,
                                         },
-                                        toolCallId: toolUseId,
-                                        sessionUpdate: "tool_call_update",
-                                        ...editDiff,
-                                    };
-                                    await client.sessionUpdate({
-                                        sessionId,
-                                        update,
-                                    });
-                                }
-                                else {
-                                    logger.error(`[claude-agent-acp] Got a tool response for tool use that wasn't tracked: ${toolUseId}`);
-                                }
+                                    },
+                                    toolCallId: toolUseId,
+                                    sessionUpdate: "tool_call_update",
+                                    ...editDiff,
+                                };
+                                await client.sessionUpdate({
+                                    sessionId,
+                                    update,
+                                });
                             },
                         });
                     }
@@ -2467,6 +3533,11 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                         ...toolUpdate,
                     };
                 }
+                // The tool_use is fully resolved now — drop it so a long session doesn't
+                // retain every tool call. The PostToolUse hook (Edit/Write diffs) closes
+                // over the tool name and no longer reads the cache, so pruning here is
+                // safe regardless of hook/result ordering.
+                delete toolUseCache[chunk.tool_use_id];
                 break;
             }
             case "document":
@@ -2479,6 +3550,8 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "compaction":
             case "compaction_delta":
             case "advisor_tool_result":
+            case "mid_conv_system":
+            case "fallback":
                 break;
             default:
                 unreachable(chunk, logger);
@@ -2494,6 +3567,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     },
                 };
             }
+            applyMessageId(update, options?.messageId);
             output.push({ sessionId, update });
         }
     }
@@ -2508,6 +3582,7 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                 parentToolUseId: message.parent_tool_use_id,
                 cwd: options?.cwd,
                 taskState: options?.taskState,
+                messageId: options?.messageId,
             });
         case "content_block_delta":
             return toAcpNotifications([event.delta], "assistant", sessionId, toolUseCache, client, logger, {
@@ -2515,6 +3590,7 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                 parentToolUseId: message.parent_tool_use_id,
                 cwd: options?.cwd,
                 taskState: options?.taskState,
+                messageId: options?.messageId,
             });
         // No content. `ping` is a Messages-API keep-alive event that the SDK's
         // `BetaRawMessageStreamEvent` union doesn't include even though the
@@ -2531,15 +3607,63 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
             return [];
     }
 }
+/** Run a `session/prompt` while honoring `$/cancel_request` for it. ACP clients
+ *  normally stop a turn with the `session/cancel` notification, but `signal`
+ *  (the prompt request's abort signal) also fires when the client sends the
+ *  generic `$/cancel_request` for this prompt — the protocol's complementary
+ *  cancellation fallback. Route that to the same `agent.cancel` path so a client
+ *  using only the generic mechanism still stops the turn (and the prompt
+ *  resolves "cancelled" instead of running to completion).
+ *
+ *  The listener is scoped to this call: once the prompt settles it is removed,
+ *  so a later teardown-time abort of the (per-request) signal can't cancel a
+ *  subsequent turn. `signal` also aborts on connection close, in which case
+ *  cancelling the in-flight turn is the desired behavior anyway. */
+export async function runPromptWithCancellation(agent, params, signal) {
+    const onAbort = () => {
+        // Fire-and-forget: nothing awaits this listener, so swallow (and log) any
+        // rejection rather than surfacing it as an unhandled rejection.
+        agent.cancel({ sessionId: params.sessionId }).catch((error) => {
+            agent.logger.error(`Failed to cancel prompt via $/cancel_request: ${error}`);
+        });
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        return await agent.prompt(params);
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+    }
+}
 export function runAcp() {
     const input = nodeToWebWritable(process.stdout);
     const output = nodeToWebReadable(process.stdin);
     const stream = ndJsonStream(input, output);
+    // `connect(...)` returns a connection-scoped peer handle (`connection.client`)
+    // that stays valid for the whole connection, so the agent captures it once.
+    // Handlers close over `agent`, which is assigned synchronously right after
+    // `connect()` returns — before the connection processes any inbound message.
+    // It cannot be `const`: its value depends on `connection.client`, which does
+    // not exist until `connect()` has been called.
+    // eslint-disable-next-line prefer-const
     let agent;
-    const connection = new AgentSideConnection((client) => {
-        agent = new ClaudeAcpAgent(client);
-        return agent;
-    }, stream);
+    const connection = acpAgent({ name: "claude-code-acp" })
+        .onRequest(methods.agent.initialize, (ctx) => agent.initialize(ctx.params))
+        .onRequest(methods.agent.session.new, (ctx) => agent.newSession(ctx.params))
+        .onRequest(methods.agent.session.load, (ctx) => agent.loadSession(ctx.params))
+        .onRequest(methods.agent.session.fork, (ctx) => agent.unstable_forkSession(ctx.params))
+        .onRequest(methods.agent.session.list, (ctx) => agent.listSessions(ctx.params))
+        .onRequest(methods.agent.session.delete, (ctx) => agent.deleteSession(ctx.params))
+        .onRequest(methods.agent.session.resume, (ctx) => agent.resumeSession(ctx.params))
+        .onRequest(methods.agent.session.close, (ctx) => agent.closeSession(ctx.params))
+        .onRequest(methods.agent.session.setMode, (ctx) => agent.setSessionMode(ctx.params))
+        .onRequest(methods.agent.session.setConfigOption, (ctx) => agent.setSessionConfigOption(ctx.params))
+        .onRequest(methods.agent.authenticate, (ctx) => agent.authenticate(ctx.params))
+        .onRequest(methods.agent.logout, (ctx) => agent.logout(ctx.params))
+        .onRequest(methods.agent.session.prompt, (ctx) => runPromptWithCancellation(agent, ctx.params, ctx.signal))
+        .onNotification(methods.agent.session.cancel, (ctx) => agent.cancel(ctx.params))
+        .connect(stream);
+    agent = new ClaudeAcpAgent(new ClientConnection(connection.client));
     return { connection, agent };
 }
 function commonPrefixLength(a, b) {
@@ -2549,16 +3673,60 @@ function commonPrefixLength(a, b) {
     }
     return i;
 }
-/** Best-effort first guess of a model's context window from its ID, used only
- *  until a `result` message arrives with the authoritative `modelUsage` value.
+/** Best-effort first guess of a model's context window, used only as a
+ *  fallback when the SDK's authoritative `getContextUsage` is unavailable (and
+ *  until a `result` message arrives with the `modelUsage` value).
+ *
  *  Anthropic 1M-context variants encode "1m" as a distinct token in the SDK
  *  model ID (e.g., "claude-opus-4-6-1m"), which `\b1m\b` catches without also
- *  matching things like "10m" or embedded substrings. */
-function inferContextWindowFromModel(model) {
-    if (/\b1m\b/i.test(model))
+ *  matching things like "10m" or embedded substrings. Semantic aliases like
+ *  `default` carry no such token in the ID, but the SDK's human-facing
+ *  `displayName`/`description` do (e.g. "Opus 4.7 (1M context)"), so callers
+ *  pass those too — the same `\b1m\b` token appears in "1M context". The SDK's
+ *  `ModelInfo` exposes no structured context-window field, so this text scan is
+ *  the only pre-`result` signal available. A miss falls back to the default
+ *  window and is corrected by `result.modelUsage` within one turn. */
+function inferContextWindowFromModel(...texts) {
+    if (texts.some((text) => text != null && /\b1m\b/i.test(text)))
         return 1_000_000;
     return null;
 }
+/** Fetch the SDK's authoritative context-window occupancy via the
+ *  `getContextUsage` control request. Unlike the per-message API usage numbers
+ *  (which only count message tokens), this `totalTokens` includes the system
+ *  prompt, tool schemas, MCP tools, and memory-file overhead — the real
+ *  occupancy the user sees. Returns `null` on any control-request failure.
+ *
+ *  Note: we deliberately do NOT use this response's window fields for `size`.
+ *  They have been observed to under-report extended (1M) context windows, so
+ *  the window keeps coming from `modelUsage` / `inferContextWindowFromModel`,
+ *  which handle the 1M variants correctly. */
+async function fetchContextUsedTokens(query, logger) {
+    try {
+        const usage = await query.getContextUsage();
+        return usage.totalTokens;
+    }
+    catch (error) {
+        logger.error("Failed to fetch context usage from SDK:", error);
+        return null;
+    }
+}
+/** Translate the legacy `MAX_THINKING_TOKENS` env var into the SDK's `thinking`
+ *  option. The `maxThinkingTokens` option it used to feed is deprecated and
+ *  reduced to on/off on current models, so map the value to explicit thinking
+ *  config instead: unset → `undefined` (SDK default, adaptive on models that
+ *  support it); `0` → disabled; a positive integer → a fixed token budget.
+ *  Anything else is ignored with a warning. */
+function resolveThinkingConfig(raw, logger) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isNaN(parsed) || parsed < 0) {
+        logger.error(`Ignoring MAX_THINKING_TOKENS: expected a non-negative integer, got '${raw}'.`);
+        return undefined;
+    }
+    return parsed === 0 ? { type: "disabled" } : { type: "enabled", budgetTokens: parsed };
+}
 function parseModelConfig(raw) {
     if (!raw)
         return undefined;