@agentclientprotocol/claude-agent-acp 0.40.0 → 0.42.0

package/dist/acp-agent.d.ts

@@ -1,4 +1,4 @@
-import { Agent, AgentSideConnection, AuthenticateRequest, CancelNotification, ClientCapabilities, ForkSessionRequest, ForkSessionResponse, InitializeRequest, InitializeResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, ResumeSessionRequest, ResumeSessionResponse, SessionConfigOption, SessionModeState, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, CloseSessionRequest, CloseSessionResponse, DeleteSessionRequest, DeleteSessionResponse, TerminalHandle, TerminalOutputResponse, WriteTextFileRequest, WriteTextFileResponse } from "@agentclientprotocol/sdk";
+import { Agent, AgentSideConnection, AuthenticateRequest, CancelNotification, ClientCapabilities, ForkSessionRequest, ForkSessionResponse, InitializeRequest, InitializeResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, ResumeSessionRequest, ResumeSessionResponse, SessionConfigOption, SessionModeState, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, CloseSessionRequest, CloseSessionResponse, DeleteSessionRequest, DeleteSessionResponse, WriteTextFileRequest, WriteTextFileResponse } from "@agentclientprotocol/sdk";
 import { CanUseTool, ModelInfo, Options, PermissionMode, PermissionUpdate, Query, SDKMessageOrigin, SDKPartialAssistantMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import { ContentBlockParam } from "@anthropic-ai/sdk/resources";
 import { BetaContentBlock, BetaRawContentBlockDelta } from "@anthropic-ai/sdk/resources/beta.mjs";
@@ -52,6 +52,17 @@ type Session = {
     }>;
     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. */
+    cancelController?: AbortController;
+    /** Pending grace-period timer that aborts `cancelController`. Cleared when
+     *  the loop returns normally so the backstop never fires after a clean
+     *  cancel. */
+    forceCancelTimer?: ReturnType<typeof setTimeout>;
     emitRawSDKMessages: boolean | SDKMessageFilter[];
     /** Context window size of the last top-level assistant model, carried across
      *  prompts so mid-stream usage_update notifications report a correct `size`
@@ -62,14 +73,30 @@ type Session = {
     /** Accumulated task list for the session, keyed by task ID. Task IDs are
      *  per-session, so this state must not be shared across sessions. */
     taskState: TaskState;
-};
-type BackgroundTerminal = {
-    handle: TerminalHandle;
-    status: "started";
-    lastOutput: TerminalOutputResponse | null;
-} | {
-    status: "aborted" | "exited" | "killed" | "timedOut";
-    pendingOutput: TerminalOutputResponse;
+    /** Caches `tool_use` blocks by id so the matching `tool_result` can recover
+     *  the tool name/input when mapping it to a `tool_call_update`. Per-session
+     *  (tool_use ids are only unique within a session) and pruned at
+     *  `tool_result` time so a long-running session doesn't accumulate every
+     *  tool call for its whole lifetime. */
+    toolUseCache: ToolUseCache;
+    /** Maps the ACP `messageId` we expose to clients (see `messageIdForGrouping`)
+     *  to the SDK message uuid that the Agent SDK's rewind/resume APIs key on
+     *  (`Query.rewindFiles` takes a user-message uuid; `resumeSessionAt` takes an
+     *  `SDKAssistantMessage.uuid`). For assistant turns the two differ — the ACP
+     *  id is the Anthropic API message id (`msg_…`), available at `message_start`
+     *  so streamed chunks can carry it, while the uuid only arrives on the
+     *  consolidated message — so a client can only ask to rewind/fork by the id it
+     *  was given, and we need this table to translate it back.
+     *
+     *  Populated as a byproduct of the message loop (the consolidated message
+     *  carries both ids) and of `replaySessionHistory` on load, so no extra
+     *  `getSessionMessages` read is needed at rewind time. Last-write-wins
+     *  naturally yields the turn-boundary uuid when one `msg_…` spans several
+     *  content-block messages.
+     *
+     *  NOT READ YET — recorded now so the mapping exists if/when we wire up
+     *  fork/rewind. */
+    messageIdToUuid: Map<string, string>;
 };
 export type SDKMessageFilter = {
     type: string;
@@ -177,13 +204,13 @@ export declare class ClaudeAcpAgent implements Agent {
         [key: string]: Session;
     };
     client: AgentSideConnection;
-    toolUseCache: ToolUseCache;
-    backgroundTerminals: {
-        [key: string]: BackgroundTerminal;
-    };
     clientCapabilities?: ClientCapabilities;
     logger: Logger;
     gatewayAuthRequest?: 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: number;
     constructor(client: AgentSideConnection, logger?: Logger);
     initialize(request: InitializeRequest): Promise<InitializeResponse>;
     newSession(params: NewSessionRequest): Promise<NewSessionResponse>;
@@ -215,6 +242,22 @@ export declare class ClaudeAcpAgent implements Agent {
     private createSession;
 }
 export declare function promptToClaude(prompt: PromptRequest): SDKUserMessage;
+/**
+ * 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 declare function messageIdForGrouping(message: {
+    type?: string;
+    uuid?: string | null;
+    message?: unknown;
+}): string | undefined;
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
@@ -225,11 +268,13 @@ export declare function toAcpNotifications(content: string | ContentBlockParam[]
     parentToolUseId?: string | null;
     cwd?: string;
     taskState?: TaskState;
+    messageId?: string;
 }): SessionNotification[];
 export declare function streamEventToAcpNotifications(message: SDKPartialAssistantMessage, sessionId: string, toolUseCache: ToolUseCache, client: AgentSideConnection, logger: Logger, options?: {
     clientCapabilities?: ClientCapabilities;
     cwd?: string;
     taskState?: TaskState;
+    messageId?: string;
 }): SessionNotification[];
 export declare function runAcp(): {
     connection: AgentSideConnection;

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

@@ -1 +1 @@
-{"version":3,"file":"acp-agent.d.ts","sourceRoot":"","sources":["../src/acp-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,mBAAmB,EACnB,mBAAmB,EAGnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EAEnB,iBAAiB,EACjB,kBAAkB,EAElB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EAEpB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,EAC7B,8BAA8B,EAC9B,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,UAAU,EAKV,SAAS,EAET,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,KAAK,EAIL,gBAAgB,EAChB,0BAA0B,EAC1B,cAAc,EAEf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAKlG,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EASL,SAAS,EAKV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAwC,QAAQ,EAAe,MAAM,YAAY,CAAC;AAEzF,eAAO,MAAM,iBAAiB,QACuC,CAAC;AAgBtE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CACjC;AAED,KAAK,gBAAgB,GAAG;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAkBF;;;yDAGyD;AACzD,KAAK,iBAAiB,GAAG;IACvB,eAAe,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChF,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,KAAK,OAAO,GAAG;IACb,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ;+EAC2E;IAC3E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,eAAe,CAAC;IACjC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvF,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,eAAe,CAAC;IACjC,kBAAkB,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAAC;IACjD;;;;kEAI8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B;yEACqE;IACrE,SAAS,EAAE,SAAS,CAAC;CACtB,CAAC;AAcF,KAAK,kBAAkB,GACnB;IACE,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAC3C,GACD;IACE,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IACrD,aAAa,EAAE,sBAAsB,CAAC;CACvC,CAAC;AAEN,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE;QACX;;;;;;;;;;;;;;WAcG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB;;;;;;WAMG;QACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAAC;KACnD,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB;;;;;OAKG;IACH,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,CAAC;CACH,CAAC;AAEF,KAAK,kBAAkB,GAAG,mBAAmB,GAAG;IAAE,KAAK,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC;AAE5E;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE;QAEX,QAAQ,EAAE,MAAM,CAAC;QAEjB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC;IAEF,aAAa,CAAC,EAAE;QACd,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,eAAe,CAAC,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,aAAa,CAAC,EAAE;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,IAAI,EAAE,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAAC;QACtD,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;CACH,CAAC;AAEF,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAsCrD;AAkED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CA0B1E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEhE;AAYD,wBAAgB,qBAAqB,CACnC,WAAW,CAAC,EAAE,OAAO,EACrB,MAAM,GAAE,MAAgB,GACvB,cAAc,CA8BhB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC3C,QAAQ,EAAE,MAAM,GACf,MAAM,CAiCR;AAGD,qBAAa,cAAe,YAAW,KAAK;IAC1C,QAAQ,EAAE;QACR,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,YAAY,CAAC;IAC3B,mBAAmB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAAA;KAAE,CAAM;IAChE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;gBAE5B,MAAM,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,MAAM;IAOlD,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoJnE,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYlE,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAoB9E,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAU3E,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAarE,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkBxE,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzD,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAsoBtD,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAavD;8CAC0C;YAC5B,eAAe;IAY7B,4EAA4E;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAQxE,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAUpF,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAU9E,sBAAsB,CAC1B,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,8BAA8B,CAAC;YAgE5B,gBAAgB;YAoChB,oBAAoB;IAkC5B,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAKxE,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAKjF,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU;YA4J3B,2BAA2B;YAa3B,kBAAkB;YAmBlB,sBAAsB;YAoGtB,kBAAkB;YA2ClB,aAAa;CAgX5B;AAwfD,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CA6EpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE,GAAG,gBAAgB,EAAE,GAAG,wBAAwB,EAAE,EACvF,IAAI,EAAE,WAAW,GAAG,MAAM,EAC1B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,GACA,mBAAmB,EAAE,CAsSvB;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,0BAA0B,EACnC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,GACA,mBAAmB,EAAE,CAgDvB;AAED,wBAAgB,MAAM;;;EAWrB"}
+{"version":3,"file":"acp-agent.d.ts","sourceRoot":"","sources":["../src/acp-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,mBAAmB,EACnB,mBAAmB,EAGnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EAEnB,iBAAiB,EACjB,kBAAkB,EAElB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EAEpB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,6BAA6B,EAC7B,8BAA8B,EAC9B,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,UAAU,EAKV,SAAS,EAET,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,KAAK,EAKL,gBAAgB,EAChB,0BAA0B,EAC1B,cAAc,EAGf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAKlG,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EASL,SAAS,EAKV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAwC,QAAQ,EAAe,MAAM,YAAY,CAAC;AAEzF,eAAO,MAAM,iBAAiB,QACuC,CAAC;AAgBtE;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CACjC;AAED,KAAK,gBAAgB,GAAG;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AA6BF;;;yDAGyD;AACzD,KAAK,iBAAiB,GAAG;IACvB,eAAe,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChF,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,KAAK,OAAO,GAAG;IACb,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ;+EAC2E;IAC3E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,eAAe,CAAC;IACjC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvF,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,eAAe,CAAC;IACjC;;;;;wCAKoC;IACpC,gBAAgB,CAAC,EAAE,eAAe,CAAC;IACnC;;kBAEc;IACd,gBAAgB,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IACjD,kBAAkB,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAAC;IACjD;;;;kEAI8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B;yEACqE;IACrE,SAAS,EAAE,SAAS,CAAC;IACrB;;;;4CAIwC;IACxC,YAAY,EAAE,YAAY,CAAC;IAC3B;;;;;;;;;;;;;;;;uBAgBmB;IACnB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAAC;AAcF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE;QACX;;;;;;;;;;;;;;WAcG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB;;;;;;WAMG;QACH,kBAAkB,CAAC,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAAC;KACnD,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB;;;;;OAKG;IACH,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,CAAC;CACH,CAAC;AAEF,KAAK,kBAAkB,GAAG,mBAAmB,GAAG;IAAE,KAAK,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC;AAE5E;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE;QAEX,QAAQ,EAAE,MAAM,CAAC;QAEjB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC;IAEF,aAAa,CAAC,EAAE;QACd,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,eAAe,CAAC,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,aAAa,CAAC,EAAE;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,IAAI,EAAE,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAAC;QACtD,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;CACH,CAAC;AAEF,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAsCrD;AAkED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CA0B1E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEhE;AAYD,wBAAgB,qBAAqB,CACnC,WAAW,CAAC,EAAE,OAAO,EACrB,MAAM,GAAE,MAAgB,GACvB,cAAc,CA8BhB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC3C,QAAQ,EAAE,MAAM,GACf,MAAM,CAiCR;AAGD,qBAAa,cAAe,YAAW,KAAK;IAC1C,QAAQ,EAAE;QACR,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,MAAM,EAAE,mBAAmB,CAAC;IAC5B,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;+BAE2B;IAC3B,kBAAkB,EAAE,MAAM,CAAiC;gBAE/C,MAAM,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,MAAM;IAMlD,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoJnE,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYlE,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAoB9E,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAU3E,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAarE,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkBxE,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzD,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAyzBtD,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCvD;8CAC0C;YAC5B,eAAe;IAwB7B,4EAA4E;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAQxE,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAUpF,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAU9E,sBAAsB,CAC1B,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,8BAA8B,CAAC;YAgE5B,gBAAgB;YAoChB,oBAAoB;IA6C5B,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAKxE,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAKjF,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU;YA4J3B,2BAA2B;YAa3B,kBAAkB;YAmBlB,sBAAsB;YAoGtB,kBAAkB;YA2ClB,aAAa;CA+W5B;AA2fD,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CA6EpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,GAAG,SAAS,CAYrB;AAqBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE,GAAG,gBAAgB,EAAE,GAAG,wBAAwB,EAAE,EACvF,IAAI,EAAE,WAAW,GAAG,MAAM,EAC1B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;IAMtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,mBAAmB,EAAE,CA4SvB;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,0BAA0B,EACnC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,mBAAmB,EAAE,CAkDvB;AAED,wBAAgB,MAAM;;;EAWrB"}

package/dist/acp-agent.js

@@ -27,6 +27,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
@@ -233,10 +243,12 @@ export function describeAlwaysAllow(suggestions, toolName) {
 // Implement the ACP Agent interface
 export class ClaudeAcpAgent {
     constructor(client, logger) {
-        this.backgroundTerminals = {};
+        /** 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. */
+        this.forceCancelGraceMs = DEFAULT_FORCE_CANCEL_GRACE_MS;
         this.sessions = {};
         this.client = client;
-        this.toolUseCache = {};
         this.logger = logger ?? console;
     }
     async initialize(request) {
@@ -463,6 +475,12 @@ export class ClaudeAcpAgent {
         // forward it to clients as structured `data`, sparing them from
         // pattern-matching on the human-readable message 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.
+        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
@@ -470,6 +488,17 @@ export class ClaudeAcpAgent {
         // `compacting` status sets it again, so every distinct compaction (e.g.
         // repeated auto-compactions in a long turn) is still shown.
         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).
+        let currentStreamMessageId;
         const userMessage = promptToClaude(params);
         const promptUuid = randomUUID();
         userMessage.uuid = promptUuid;
@@ -495,9 +524,26 @@ export class ClaudeAcpAgent {
         let handedOff = false;
         let errored = false;
         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 });
+        });
         try {
             while (true) {
-                const { value: message, done } = await session.query.next();
+                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.
+                    void nextMessage.catch(() => { });
+                    return { stopReason: "cancelled" };
+                }
+                const { value: message, done } = next;
                 if (done || !message) {
                     if (session.cancelled) {
                         return { stopReason: "cancelled" };
@@ -554,28 +600,35 @@ export class ClaudeAcpAgent {
                                 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.
+                                //
+                                // 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.
                                 //
-                                // 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.
+                                // `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.
-                                lastAssistantTotalUsage = 0;
+                                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,
                                     },
                                 });
@@ -637,6 +690,63 @@ 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 "hook_started":
                             case "hook_progress":
                             case "hook_response":
@@ -649,8 +759,6 @@ export class ClaudeAcpAgent {
                             case "plugin_install":
                             case "notification":
                             case "api_retry":
-                            case "mirror_error":
-                            case "permission_denied":
                             case "thinking_tokens":
                                 // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
                                 break;
@@ -704,6 +812,25 @@ 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";
+                            break;
+                        }
                         switch (message.subtype) {
                             case "success": {
                                 if (message.result.includes("Please run /login")) {
@@ -723,7 +850,7 @@ export class ClaudeAcpAgent {
                                 // 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)) {
+                                    for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
                                         await this.client.sessionUpdate(notification);
                                     }
                                 }
@@ -761,6 +888,12 @@ export class ClaudeAcpAgent {
                         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;
+                        }
                         if (message.parent_tool_use_id === null &&
                             (message.event.type === "message_start" || message.event.type === "message_delta")) {
                             if (message.event.type === "message_start") {
@@ -808,10 +941,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);
                         }
@@ -822,6 +956,14 @@ export class ClaudeAcpAgent {
                         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).
+                        const mappedMessageId = messageIdForGrouping(message);
+                        if (mappedMessageId && typeof message.uuid === "string" && message.uuid.length > 0) {
+                            session.messageIdToUuid.set(mappedMessageId, message.uuid);
+                        }
                         // Check for prompt replay
                         if (message.type === "user" && "uuid" in message && message.uuid) {
                             if (message.uuid === promptUuid) {
@@ -854,6 +996,9 @@ 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.
@@ -865,11 +1010,12 @@ export class ClaudeAcpAgent {
                             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);
                                 }
@@ -907,21 +1053,51 @@ export class ClaudeAcpAgent {
                             ? // 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, {
+                        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);
@@ -973,6 +1149,16 @@ export class ClaudeAcpAgent {
             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) {
@@ -1008,6 +1194,27 @@ export class ClaudeAcpAgent {
             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
+        // 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.promptRunning &&
+            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);
+        }
         await session.query.interrupt();
     }
     /** Cleanly tear down a session: cancel in-flight work, dispose resources,
@@ -1018,6 +1225,18 @@ export class ClaudeAcpAgent {
             return;
         }
         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).
+        if (session.forceCancelTimer) {
+            clearTimeout(session.forceCancelTimer);
+            session.forceCancelTimer = undefined;
+        }
+        session.cancelController?.abort();
         session.settingsManager.dispose();
         session.abortController.abort();
         session.query.close();
@@ -1145,6 +1364,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
@@ -1162,6 +1390,7 @@ export class ClaudeAcpAgent {
                 clientCapabilities: this.clientCapabilities,
                 cwd: this.sessions[sessionId]?.cwd,
                 taskState: this.sessions[sessionId]?.taskState,
+                messageId: replayMessageId,
             })) {
                 await this.client.sessionUpdate(notification);
             }
@@ -1513,10 +1742,8 @@ 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)
@@ -1535,7 +1762,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
@@ -1752,6 +1979,8 @@ export class ClaudeAcpAgent {
             emitRawSDKMessages: sessionMeta?.claudeCode?.emitRawSDKMessages ?? false,
             contextWindowSize: inferContextWindowFromModel(models.currentModelId) ?? DEFAULT_CONTEXT_WINDOW,
             taskState,
+            toolUseCache: {},
+            messageIdToUuid: new Map(),
         };
         return {
             sessionId,
@@ -1993,11 +2222,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) {
@@ -2265,6 +2499,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.
@@ -2281,6 +2551,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 text: content,
             },
         };
+        applyMessageId(update, options?.messageId);
         if (options?.parentToolUseId) {
             update._meta = {
                 ...update._meta,
@@ -2353,40 +2624,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,
+                                });
                             },
                         });
                     }
@@ -2509,6 +2780,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":
@@ -2537,6 +2813,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     },
                 };
             }
+            applyMessageId(update, options?.messageId);
             output.push({ sessionId, update });
         }
     }
@@ -2551,6 +2828,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, {
@@ -2558,6 +2836,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
@@ -2593,7 +2872,8 @@ 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.
+ *  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. */
@@ -2602,6 +2882,42 @@ function inferContextWindowFromModel(model) {
         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;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -61,7 +61,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@agentclientprotocol/sdk": "0.24.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.160",
+    "@anthropic-ai/claude-agent-sdk": "0.3.165",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {