@agentclientprotocol/claude-agent-acp 0.45.1 → 0.46.0

package/dist/acp-agent.d.ts

@@ -31,10 +31,54 @@ type SessionModelState = {
     }>;
     currentModelId: string;
 };
+/** One in-flight `prompt()` call. A persistent per-session consumer (see
+ *  `runConsumer`) drains the SDK query stream for the whole session and settles
+ *  each Turn's deferred when that turn's outcome is known, so `prompt()` itself
+ *  holds no loop. Turns are processed FIFO: the SDK echoes queued user messages
+ *  back in submission order, so `turnQueue[0]` is the turn currently running. */
+type Turn = {
+    /** uuid stamped on the pushed `SDKUserMessage`; the SDK echoes it back so the
+     *  consumer can match the replayed user message to this turn. */
+    promptUuid: string;
+    /** Local-only slash commands (e.g. `/clear`) return a result without an echo,
+     *  so the consumer can't promote them via the replay; it falls back to
+     *  promoting the queue head when the result arrives. */
+    isLocalOnlyCommand: boolean;
+    /** Set once the deferred has been resolved/rejected, so the consumer never
+     *  settles a turn twice (idle + handoff + stream-end can all race). */
+    settled: boolean;
+    resolve: (response: PromptResponse) => void;
+    reject: (error: unknown) => void;
+};
 type Session = {
     query: Query;
     input: Pushable<SDKUserMessage>;
     cancelled: boolean;
+    /** FIFO of in-flight prompts. The head is the turn the SDK is currently
+     *  processing; later entries are queued and will be echoed in order. */
+    turnQueue?: Turn[];
+    /** The turn whose messages the consumer is currently attributing output to
+     *  (the head of `turnQueue` once its user message has been echoed). */
+    activeTurn?: Turn | null;
+    /** Count of result messages the consumer should treat as orphans and skip
+     *  (not promote/attribute to the current head). When cancel() settles+removes
+     *  a queued turn, that turn's user message was already pushed to the SDK, so
+     *  the SDK still runs it and emits a result with no uuid we can match. Because
+     *  the SDK processes input FIFO, those orphan results arrive (in submission
+     *  order) before the next live turn's, so skipping exactly this many leaves
+     *  the genuine head untouched. Reset to 0 on every activation as a backstop
+     *  against an SDK that drops queued input on interrupt (no orphan emitted). */
+    pendingOrphanResults?: number;
+    /** The long-lived consumer task. Lazily started on the first `prompt()` and
+     *  kept alive for the session so between-turn/background messages are still
+     *  drained and forwarded. */
+    consumer?: Promise<void>;
+    /** Set once the SDK query stream has terminated (it ran to `done` or threw a
+     *  non-process error). The query iterator is not reusable afterward, so a
+     *  later `prompt()` rejects instead of enqueueing onto a dead stream and
+     *  hanging (or silently restarting a consumer that resolves `end_turn`
+     *  without ever reaching the model). */
+    queryClosed?: boolean;
     cwd: string;
     /** Serialized snapshot of session-defining params (cwd, mcpServers) used to
      *  detect when loadSession/resumeSession is called with changed values. */
@@ -45,22 +89,16 @@ type Session = {
     models: SessionModelState;
     modelInfos: ModelInfo[];
     configOptions: SessionConfigOption[];
-    promptRunning: boolean;
-    pendingMessages: Map<string, {
-        resolve: (cancelled: boolean) => void;
-        order: number;
-    }>;
-    nextPendingOrder: number;
     abortController: AbortController;
-    /** Per-turn signal the active prompt loop races `query.next()` against.
-     *  Aborted by cancel() (after a grace period) to force the loop to return
-     *  "cancelled" when the SDK is wedged and `query.next()` never yields again
-     *  (issue #680). Distinct from `abortController`: this only wakes the loop;
-     *  it does NOT touch the SDK query/subprocess. Undefined when no prompt is
-     *  actively consuming the query. */
+    /** Signal the consumer races `query.next()` against. Aborted by cancel()
+     *  (after a grace period) to force the active turn to settle "cancelled" when
+     *  the SDK is wedged and `query.next()` never yields again (issue #680).
+     *  Distinct from `abortController`: this only wakes the consumer; it does NOT
+     *  touch the SDK query/subprocess. The consumer re-arms it after each fire.
+     *  Undefined until the consumer is started by the first prompt. */
     cancelController?: AbortController;
-    /** Pending grace-period timer that aborts `cancelController`. Cleared when
-     *  the loop returns normally so the backstop never fires after a clean
+    /** Pending grace-period timer that aborts `cancelController`. Cleared when the
+     *  active turn settles normally so the backstop never fires after a clean
      *  cancel. */
     forceCancelTimer?: ReturnType<typeof setTimeout>;
     emitRawSDKMessages: boolean | SDKMessageFilter[];
@@ -220,9 +258,38 @@ export declare class ClaudeAcpAgent implements Agent {
     listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse>;
     authenticate(_params: AuthenticateRequest): Promise<void>;
     prompt(params: PromptRequest): Promise<PromptResponse>;
+    /** 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. */
+    private ensureConsumer;
+    /** 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`. */
+    private runConsumer;
     cancel(params: CancelNotification): Promise<void>;
-    /** 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. */
+    private closeQueryStream;
+    /** Cleanly tear down a session: cancel in-flight work, release stream
+     *  resources, and remove it from the session map. */
     private teardownSession;
     /** Tear down all active sessions. Called when the ACP connection closes. */
     dispose(): Promise<void>;

package/dist/acp-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acp-agent.d.ts","sourceRoot":"","sources":["../src/acp-agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"acp-agent.d.ts","sourceRoot":"","sources":["../src/acp-agent.ts"],"names":[],"mappings":"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"}

package/dist/acp-agent.js

@@ -93,6 +93,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;
@@ -460,112 +464,273 @@ export class ClaudeAcpAgent {
         if (!session) {
             throw new Error("Session not found");
         }
-        session.cancelled = false;
-        session.accumulatedUsage = {
-            inputTokens: 0,
-            outputTokens: 0,
-            cachedReadTokens: 0,
-            cachedWriteTokens: 0,
+        // 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;
         // When a streaming classifier refuses a turn, the assistant message carries
         // stop_reason "refusal" and structured stop_details. We capture the
-        // human-readable explanation here so the terminal `result` can surface it
-        // to the user (the refused assistant message itself usually has no content)
-        // and report ACP's dedicated `refusal` stop reason.
+        // 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. A fresh
-        // `compacting` status sets it again, so every distinct compaction (e.g.
-        // repeated auto-compactions in a long turn) is still shown.
+        // outcome only while a compaction is in progress, then clear this.
         let compactionInProgress = false;
-        // Holds the Anthropic API message id of the assistant message currently
-        // being streamed, captured from `message_start` so every streamed chunk can
-        // be tagged with it. We use the API message id rather than the
-        // per-`stream_event` uuid because the same id is also present on the
-        // consolidated assistant message and in the persisted transcript — so a turn
-        // keeps the same ACP `messageId` whether it is streamed live or replayed
-        // from history. The per-event uuid is unique per event and never persisted.
-        // A single value suffices because every streaming partial arrives with
-        // `parent_tool_use_id === null` (subagent work is folded into tool-result
-        // messages, never surfaced as partial streams).
+        // 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;
-        // Per-message-id record of which assistant content actually streamed live via
-        // `stream_event` deltas, split by block type. The `assistant` case below
-        // normally drops `text`/`thinking` blocks on the assumption they already
-        // reached the client as `agent_message_chunk`/`agent_thought_chunk`. That
-        // breaks behind Anthropic-protocol gateways that return a turn as a single
-        // non-streamed block (common with OpenAI-compatible proxies): no
-        // `content_block_delta` fires, so the assembled block is the only copy the
-        // client will ever see. We keep the filter per (id, block type) for content
-        // that did stream, and fall back to forwarding what did not. Split by type so
-        // a gateway that streams text but not thinking (or vice versa) doesn't lose
-        // the un-streamed block. Only top-level (`parent_tool_use_id === null`)
-        // streams are recorded — subagent text is never streamed and must stay
-        // filtered, as it is internal to the tool call.
-        const streamedTextIds = new Set();
-        const streamedThinkingIds = new Set();
-        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" };
-            }
-        }
-        else {
-            session.input.push(userMessage);
-        }
-        session.promptRunning = true;
-        let handedOff = false;
-        let errored = false;
+        // Per-message-id record of which assistant content actually streamed live
+        // via `stream_event` deltas, split by block type, so the consolidated
+        // `assistant` message can drop the duplicate blocks that already reached the
+        // client as chunks while still forwarding any that a non-streaming gateway
+        // delivered only as an assembled block.
+        let streamedTextIds = new Set();
+        let streamedThinkingIds = new Set();
+        // 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";
-        // Wake-up channel so cancel() can force this loop to return "cancelled"
-        // even when query.next() is wedged and never yields again (issue #680).
-        const cancelController = new AbortController();
-        session.cancelController = cancelController;
-        const cancelled = new Promise((resolve) => {
-            cancelController.signal.addEventListener("abort", () => resolve(), { once: true });
-        });
+        const resetTurnScratch = () => {
+            lastAssistantTotalUsage = null;
+            lastAssistantUsage = null;
+            lastAssistantModel = null;
+            lastAssistantError = undefined;
+            lastRefusalExplanation = null;
+            compactionInProgress = false;
+            currentStreamMessageId = undefined;
+            streamedTextIds = new Set();
+            streamedThinkingIds = new Set();
+            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;
+            }
+            const head = (session.turnQueue ?? []).find((t) => !t.settled);
+            if (!head) {
+                return;
+            }
+            if ((session.pendingOrphanResults ?? 0) > 0) {
+                session.pendingOrphanResults--;
+                return;
+            }
+            activateTurn(head);
+        };
+        /** 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 nextMessage = session.query.next();
-                const next = await Promise.race([nextMessage, cancelled]);
-                if (cancelController.signal.aborted) {
-                    // The SDK never yielded after interrupt() (e.g. a wedged TaskOutput
-                    // block). Abandon the in-flight next() — swallowing any later
-                    // rejection so it can't surface as an unhandled rejection — and
-                    // honor the cancel per the ACP contract.
+                // 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(() => { });
-                    return { stopReason: "cancelled" };
+                    settleActive({ stopReason: "cancelled" });
+                    if (!this.sessions[params.sessionId]) {
+                        return;
+                    }
+                    cancelController = new AbortController();
+                    session.cancelController = cancelController;
+                    continue;
                 }
-                const { value: message, done } = next;
+                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)) {
@@ -663,10 +828,20 @@ 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) };
                                 }
                                 break;
                             }
@@ -764,6 +939,24 @@ export class ClaudeAcpAgent {
                                 });
                                 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":
@@ -773,6 +966,11 @@ export class ClaudeAcpAgent {
                             case "task_progress":
                             case "task_updated":
                                 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
@@ -802,11 +1000,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;
@@ -817,11 +1036,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({
@@ -863,12 +1077,14 @@ export class ClaudeAcpAgent {
                                 });
                             }
                             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) {
@@ -877,13 +1093,14 @@ 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) {
+                                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);
                                     }
@@ -898,7 +1115,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";
@@ -909,7 +1127,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";
@@ -919,6 +1138,16 @@ 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": {
@@ -1002,36 +1231,49 @@ export class ClaudeAcpAgent {
                     }
                     case "user":
                     case "assistant": {
-                        if (session.cancelled) {
-                            break;
-                        }
-                        // Record the ACP messageId -> SDK uuid mapping for this message. The
-                        // consolidated message carries both ids, so this is where we learn
-                        // the uuid that the SDK's rewind/resume APIs key on for the id we
-                        // hand clients. Not read yet (see Session.messageIdToUuid).
+                        // 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
@@ -1096,7 +1338,8 @@ export class ClaudeAcpAgent {
                             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) {
@@ -1189,83 +1432,36 @@ export class ClaudeAcpAgent {
                         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 {
-            // The loop is returning — interrupt() succeeded or the prompt finished
-            // — so disarm the force-cancel backstop and release the wake-up channel
-            // (only if we still own it; a handoff installs the next prompt's).
-            if (session.forceCancelTimer) {
-                clearTimeout(session.forceCancelTimer);
-                session.forceCancelTimer = undefined;
-            }
-            if (session.cancelController === cancelController) {
-                session.cancelController = undefined;
-            }
-            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);
             }
         }
     }
@@ -1274,23 +1470,46 @@ 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);
-        }
-        session.pendingMessages.clear();
-        // Arm a backstop before interrupting: if a prompt is actively consuming
-        // the query and interrupt() doesn't make the SDK yield (e.g. a wedged
-        // TaskOutput block — issue #680), force the loop to return "cancelled"
-        // after the floor elapses so the pending session/prompt still resolves per
-        // the ACP cancellation contract instead of hanging forever. The loop's
-        // `finally` clears this timer when interrupt() works and it returns through
+        // 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
+        // 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.promptRunning &&
+        if (session.activeTurn &&
             session.cancelController &&
             !session.cancelController.signal.aborted &&
             !session.forceCancelTimer) {
@@ -1302,8 +1521,37 @@ export class ClaudeAcpAgent {
         }
         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) {
@@ -1311,20 +1559,23 @@ export class ClaudeAcpAgent {
         }
         await this.cancel({ sessionId });
         // cancel() arms the force-cancel floor and interrupts gracefully, but a
-        // wedged prompt loop only wakes when `cancelController` aborts — closing
-        // the query/abortController below doesn't touch it. Since we're tearing the
-        // session down anyway, wake the loop 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).
+        // 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();
-        session.settingsManager.dispose();
+        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. */
@@ -1348,9 +1599,16 @@ export class ClaudeAcpAgent {
         return {};
     }
     async setSessionMode(params) {
-        if (!this.sessions[params.sessionId]) {
+        const session = this.sessions[params.sessionId];
+        if (!session) {
             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);
         return {};
@@ -1360,6 +1618,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}`);
         }
@@ -2163,9 +2428,6 @@ export class ClaudeAcpAgent {
             models,
             modelInfos: allowedModels,
             configOptions,
-            promptRunning: false,
-            pendingMessages: new Map(),
-            nextPendingOrder: 0,
             abortController,
             emitRawSDKMessages: sessionMeta?.claudeCode?.emitRawSDKMessages ?? false,
             contextWindowSize: inferContextWindowFromModel(models.currentModelId) ?? DEFAULT_CONTEXT_WINDOW,

package/dist/elicitation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"elicitation.d.ts","sourceRoot":"","sources":["../src/elicitation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAI1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAC5F,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,6CAA6C,CAAC;AAErD;;;;;;;;;;;;;GAaG;AAEH,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,wBAAwB,GAAG,IAAI,CAyBjC;AAED;;;GAGG;AACH,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,yBAAyB,GAClC,iBAAiB,CAUnB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,IAAI,CAUhG;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,eAAe,EAAE,EAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,wBAAwB,CAyC1B;AAED,+EAA+E;AAC/E,MAAM,MAAM,sBAAsB,GAC9B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEzB;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,yBAAyB,EACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,SAAS,EAAE,eAAe,EAAE,GAC3B,sBAAsB,CAkCxB"}
+{"version":3,"file":"elicitation.d.ts","sourceRoot":"","sources":["../src/elicitation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,wBAAwB,EACxB,yBAAyB,EAI1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAC5F,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,6CAA6C,CAAC;AAErD;;;;;;;;;;;;;GAaG;AAEH,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,wBAAwB,GAAG,IAAI,CAyBjC;AAED;;;GAGG;AACH,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,yBAAyB,GAClC,iBAAiB,CAUnB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,GAAG,IAAI,CAUhG;AA4CD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,eAAe,EAAE,EAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,wBAAwB,CAwD1B;AAED,+EAA+E;AAC/E,MAAM,MAAM,sBAAsB,GAC9B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEzB;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,yBAAyB,EACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,SAAS,EAAE,eAAe,EAAE,GAC3B,sBAAsB,CAkCxB"}

package/dist/elicitation.js

@@ -70,6 +70,27 @@ function questionFieldKey(index) {
 function questionCustomFieldKey(index) {
     return `question_${index}_custom`;
 }
+/**
+ * `_meta` key under which a bridged enum option carries its structured
+ * `description`/`preview`, since ACP's `EnumOption` has no field for either.
+ * Namespaced like the agent's other `_meta` extensions (`_claude/...`).
+ */
+const OPTION_META_KEY = "_claude/askUserQuestionOption";
+/**
+ * Build the `_meta` payload that carries an option's structured `description`
+ * and optional `preview` for clients that can render them as distinct fields.
+ * Returns `undefined` when neither is present, so we don't emit an empty `_meta`.
+ */
+function askUserQuestionOptionMeta(option) {
+    const detail = {};
+    if (option.description) {
+        detail.description = option.description;
+    }
+    if (option.preview) {
+        detail.preview = option.preview;
+    }
+    return Object.keys(detail).length > 0 ? { [OPTION_META_KEY]: detail } : undefined;
+}
 /**
  * Render the AskUserQuestion tool's questions as an ACP form elicitation.
  *
@@ -89,10 +110,25 @@ export function askUserQuestionsToCreateRequest(questions, sessionId, toolCallId
     const single = questions.length === 1;
     const properties = {};
     questions.forEach((question, index) => {
-        const options = question.options.map((option) => ({
-            const: option.label,
-            title: option.description ? `${option.label} — ${option.description}` : option.label,
-        }));
+        const options = question.options.map((option) => {
+            const enumOption = {
+                const: option.label,
+                // `title` stays a flattened "label — description" string so clients that
+                // only read `const`/`title` still surface the description. Clients that
+                // understand the `_meta` below should prefer its structured fields (and
+                // treat `const` as the clean label) rather than parsing this title.
+                title: option.description ? `${option.label} — ${option.description}` : option.label,
+            };
+            // The SDK option carries a `description` (secondary text) and an optional
+            // `preview` (mockups, code snippets, comparisons shown on focus). Neither
+            // has a structural slot in `EnumOption`, so forward them under ACP's
+            // reserved `_meta` extension point for clients that can render them.
+            const meta = askUserQuestionOptionMeta(option);
+            if (meta) {
+                enumOption._meta = meta;
+            }
+            return enumOption;
+        });
         // For a single question the prompt is carried by `message`, so we don't
         // repeat it in the field description. With multiple questions each field
         // needs its own question text.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.45.1",
+  "version": "0.46.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -60,16 +60,16 @@
   "author": "Zed Industries",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.25.1",
-    "@anthropic-ai/claude-agent-sdk": "0.3.177",
+    "@agentclientprotocol/sdk": "0.26.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.178",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.104.1",
+    "@anthropic-ai/sdk": "0.104.2",
     "@eslint/js": "10.0.1",
     "@types/node": "25.9.3",
-    "@typescript-eslint/eslint-plugin": "8.61.0",
-    "@typescript-eslint/parser": "8.61.0",
+    "@typescript-eslint/eslint-plugin": "8.61.1",
+    "@typescript-eslint/parser": "8.61.1",
     "eslint": "10.5.0",
     "eslint-config-prettier": "10.1.8",
     "globals": "17.6.0",