chore(main): release 0.43.0 (#752 )

🤖 I have created a release *beep* *boop* --- ## [0.43.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.42.0...v0.43.0) (2026-06-09) ### Features * Add experimental elicitation support ([#756](https://github.com/agentclientprotocol/claude-agent-acp/issues/756)) ([12bd276](12bd2762d9)) * **deps:** update to @anthropic-ai/claude-agent-sdk 0.3.169 ([#754](https://github.com/agentclientprotocol/claude-agent-acp/issues/754)) ([bd0ae4d](bd0ae4dde1)) * Update ACP SDK to 0.25.0 ([#753](https://github.com/agentclientprotocol/claude-agent-acp/issues/753)) ([0dbccf5](0dbccf588f)) ### Bug Fixes * Forward unstreamed assistant text blocks ([#757](https://github.com/agentclientprotocol/claude-agent-acp/issues/757)) ([7ff6b7f](7ff6b7fd6b)) * Validate cwd before creating sessions ([#751](https://github.com/agentclientprotocol/claude-agent-acp/issues/751)) ([9854b0c](9854b0c679)), closes [#749](https://github.com/agentclientprotocol/claude-agent-acp/issues/749) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: acp-release-bot[bot] <246668977+acp-release-bot[bot]@users.noreply.github.com>
feat(deps): update to @anthropic-ai/claude-agent-sdk 0.3.169 (#754 )
2026-11-07 09:52:05 +00:00 · 2026-06-09 08:58:23 +00:00 · 2026-06-09 08:56:57 +00:00 · 2026-06-09 08:48:48 +00:00 · 2026-06-09 09:59:06 +02:00 · 2026-06-05 13:21:20 +00:00
17 changed files with 2891 additions and 573 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -21,7 +21,7 @@ jobs:
    timeout-minutes: 5

    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10

      - name: Use Node.js
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -44,7 +44,7 @@ jobs:
      contents: read
      id-token: write
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
        with:
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.38.0"
+  ".": "0.43.0"
 }
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,69 @@
 # Changelog

+## [0.43.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.42.0...v0.43.0) (2026-06-09)
+
+
+### Features
+
+* Add experimental elicitation support ([#756](https://github.com/agentclientprotocol/claude-agent-acp/issues/756)) ([12bd276](https://github.com/agentclientprotocol/claude-agent-acp/commit/12bd2762d9ba0ccb7497a3848a5928b8bb2ce820))
+* **deps:** update to @anthropic-ai/claude-agent-sdk 0.3.169 ([#754](https://github.com/agentclientprotocol/claude-agent-acp/issues/754)) ([bd0ae4d](https://github.com/agentclientprotocol/claude-agent-acp/commit/bd0ae4dde160f59559ab4ac1bf703fcf151eff17))
+* Update ACP SDK to 0.25.0 ([#753](https://github.com/agentclientprotocol/claude-agent-acp/issues/753)) ([0dbccf5](https://github.com/agentclientprotocol/claude-agent-acp/commit/0dbccf588ff702015494dd29969d47f0b7402feb))
+
+
+### Bug Fixes
+
+* Forward unstreamed assistant text blocks ([#757](https://github.com/agentclientprotocol/claude-agent-acp/issues/757)) ([7ff6b7f](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ff6b7fd6b157aedbce0c636087f51ae7d1df3a7))
+* Validate cwd before creating sessions ([#751](https://github.com/agentclientprotocol/claude-agent-acp/issues/751)) ([9854b0c](https://github.com/agentclientprotocol/claude-agent-acp/commit/9854b0c6790ebafff514e3c4c8e03a131f065a4a)), closes [#749](https://github.com/agentclientprotocol/claude-agent-acp/issues/749)
+
+## [0.42.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.41.0...v0.42.0) (2026-06-05)
+
+
+### Features
+
+* **deps-dev:** bump obug from 2.1.1 to 2.1.2 in the minor group ([#743](https://github.com/agentclientprotocol/claude-agent-acp/issues/743)) ([7ffb78c](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ffb78c57280fc32af77862896c0035ce0e690b7))
+* Send message ids for assistant and user messages ([#750](https://github.com/agentclientprotocol/claude-agent-acp/issues/750)) ([18516a3](https://github.com/agentclientprotocol/claude-agent-acp/commit/18516a3088f847a38f5eee0fe81ad5ca3e2a751c))
+* Update Claude Agent SDK to 0.3.165 ([#746](https://github.com/agentclientprotocol/claude-agent-acp/issues/746)) ([23cbe6f](https://github.com/agentclientprotocol/claude-agent-acp/commit/23cbe6f58fa9e10ad736f664c4cf94dbd1c6ad65))
+
+
+### Bug Fixes
+
+* Prevent cross-family model matching in resolveModelPreference ([#731](https://github.com/agentclientprotocol/claude-agent-acp/issues/731)) ([f4704c1](https://github.com/agentclientprotocol/claude-agent-acp/commit/f4704c168f917e6710f2b3cd49e1fef49613a469))
+* Prune tool cache per session after results ([#748](https://github.com/agentclientprotocol/claude-agent-acp/issues/748)) ([ec14211](https://github.com/agentclientprotocol/claude-agent-acp/commit/ec142110561f680330c6976783805685c5c069ec))
+* Update to better utilize existing SDK data ([#747](https://github.com/agentclientprotocol/claude-agent-acp/issues/747)) ([398f763](https://github.com/agentclientprotocol/claude-agent-acp/commit/398f763f71bd2fe2ca9e8269de120d26a744b7a8))
+
+## [0.41.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.40.0...v0.41.0) (2026-06-04)
+
+
+### Features
+
+* **deps:** upgrade to @anthropic-ai/claude-agent-sdk@0.3.162 ([#740](https://github.com/agentclientprotocol/claude-agent-acp/issues/740)) ([add7e31](https://github.com/agentclientprotocol/claude-agent-acp/commit/add7e31704581aa70febb6341ca0e8cee5d93b43))
+
+
+### Bug Fixes
+
+* Force cancellation when SDK query hangs ([#742](https://github.com/agentclientprotocol/claude-agent-acp/issues/742)) ([cffea4b](https://github.com/agentclientprotocol/claude-agent-acp/commit/cffea4be28e6def91027110433a99e80b1be8a0c)), closes [#680](https://github.com/agentclientprotocol/claude-agent-acp/issues/680)
+
+## [0.40.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.39.0...v0.40.0) (2026-06-02)
+
+
+### Features
+
+* **deps-dev:** bump the minor group with 2 updates ([#726](https://github.com/agentclientprotocol/claude-agent-acp/issues/726)) ([51a370e](https://github.com/agentclientprotocol/claude-agent-acp/commit/51a370e4feb8a74279698b156e35b96631a74d74))
+* **deps:** bump actions/checkout from 6.0.2 to 6.0.3 ([#736](https://github.com/agentclientprotocol/claude-agent-acp/issues/736)) ([9cda07b](https://github.com/agentclientprotocol/claude-agent-acp/commit/9cda07ba9df27b48bd94332e365eed982e3f5613))
+* **deps:** bump the minor group with 50 updates ([#737](https://github.com/agentclientprotocol/claude-agent-acp/issues/737)) ([32175b8](https://github.com/agentclientprotocol/claude-agent-acp/commit/32175b83a0227d0baa1f7d7eedabe743b4b870e8))
+
+
+### Bug Fixes
+
+* Optimize local command marker stripping ([#738](https://github.com/agentclientprotocol/claude-agent-acp/issues/738)) ([895422c](https://github.com/agentclientprotocol/claude-agent-acp/commit/895422c72d5f955903f227dc6887df823d2730e6)), closes [#727](https://github.com/agentclientprotocol/claude-agent-acp/issues/727)
+
+## [0.39.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.38.0...v0.39.0) (2026-05-29)
+
+
+### Features
+
+* **deps:** update Claude Agent SDK to 0.3.156 ([#722](https://github.com/agentclientprotocol/claude-agent-acp/issues/722)) ([3fb6db4](https://github.com/agentclientprotocol/claude-agent-acp/commit/3fb6db4e5ee5bd1f431cf5d2ce5331ce983f9597))
+
 ## [0.38.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.37.0...v0.38.0) (2026-05-28)


--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
  "publishConfig": {
    "access": "public"
  },
-  "version": "0.38.0",
+  "version": "0.43.0",
  "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
  "main": "dist/lib.js",
  "types": "dist/lib.d.ts",
@@ -60,22 +60,22 @@
  "author": "Zed Industries",
  "license": "Apache-2.0",
  "dependencies": {
-    "@agentclientprotocol/sdk": "0.22.1",
-    "@anthropic-ai/claude-agent-sdk": "0.3.154",
+    "@agentclientprotocol/sdk": "0.25.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.169",
    "zod": "^3.25.0 || ^4.0.0"
  },
  "devDependencies": {
-    "@anthropic-ai/sdk": "0.100.0",
+    "@anthropic-ai/sdk": "0.102.0",
    "@eslint/js": "10.0.1",
-    "@types/node": "25.9.1",
-    "@typescript-eslint/eslint-plugin": "8.60.0",
-    "@typescript-eslint/parser": "8.60.0",
-    "eslint": "10.4.0",
+    "@types/node": "25.9.2",
+    "@typescript-eslint/eslint-plugin": "8.60.1",
+    "@typescript-eslint/parser": "8.60.1",
+    "eslint": "10.4.1",
    "eslint-config-prettier": "10.1.8",
    "globals": "17.6.0",
    "prettier": "3.8.3",
    "ts-node": "10.9.2",
    "typescript": "6.0.3",
-    "vitest": "4.1.7"
+    "vitest": "4.1.8"
  }
 }
--- a/src/acp-agent.ts
+++ b/src/acp-agent.ts
--- a/src/elicitation.ts
+++ b/src/elicitation.ts
@@ -0,0 +1,249 @@
+import { randomUUID } from "node:crypto";
+import type {
+  CreateElicitationRequest,
+  CreateElicitationResponse,
+  ElicitationPropertySchema,
+  ElicitationSchema,
+  EnumOption,
+} from "@agentclientprotocol/sdk";
+import type { ElicitationRequest, ElicitationResult } from "@anthropic-ai/claude-agent-sdk";
+import type {
+  AskUserQuestionInput,
+  AskUserQuestionOutput,
+} from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
+
+/**
+ * Bridges between the Claude Agent SDK's elicitation/dialog callbacks and ACP's
+ * (unstable) elicitation protocol.
+ *
+ * Two distinct SDK surfaces flow through here:
+ *
+ *   1. `onElicitation` — fired when an MCP server requests user input. These map
+ *      directly onto ACP `session/create_elicitation` (form or url mode).
+ *   2. The built-in AskUserQuestion tool — when a `canUseTool` callback is
+ *      registered the SDK routes its permission check through `canUseTool`
+ *      (not the interactive `permission_ask_user_question` dialog). We render
+ *      its questions as an ACP form elicitation and feed the user's selections
+ *      back as the tool's `updatedInput`, which the tool's own `call()` reads.
+ */
+
+/** Modes the connected client advertised support for. */
+export type ElicitationSupport = {
+  form: boolean;
+  url: boolean;
+};
+
+/**
+ * Convert an MCP elicitation request (from the SDK's `onElicitation` callback)
+ * into an ACP `CreateElicitationRequest`. Returns `null` when the request can't
+ * be represented (e.g. a url-mode request with no url).
+ */
+export function mcpElicitationToCreateRequest(
+  request: ElicitationRequest,
+  sessionId: string,
+): CreateElicitationRequest | null {
+  if (request.mode === "url") {
+    if (!request.url) {
+      return null;
+    }
+    return {
+      mode: "url",
+      sessionId,
+      message: request.message,
+      url: request.url,
+      // URL elicitations need a stable id so the client can correlate the
+      // later `session/complete_elicitation` notification. MCP servers usually
+      // provide one; fall back to a generated id if not.
+      elicitationId: request.elicitationId ?? randomUUID(),
+    };
+  }
+
+  // Form mode (the default). The MCP `requestedSchema` is already a JSON Schema
+  // with primitive-typed properties, which is structurally what ACP expects.
+  return {
+    mode: "form",
+    sessionId,
+    message: request.message,
+    requestedSchema: normalizeElicitationSchema(request.requestedSchema),
+  };
+}
+
+/**
+ * Map an ACP elicitation response back to the MCP `ElicitResult` the SDK expects
+ * to hand back to the requesting server.
+ */
+export function createElicitationResponseToElicitResult(
+  response: CreateElicitationResponse,
+): ElicitationResult {
+  switch (response.action) {
+    case "accept":
+      return { action: "accept", content: response.content ?? {} };
+    case "decline":
+      return { action: "decline" };
+    case "cancel":
+    default:
+      return { action: "cancel" };
+  }
+}
+
+/**
+ * A single question as supplied by the AskUserQuestion tool. Derived from the
+ * SDK's input type so the shape stays in sync; the SDK validates the model's
+ * tool call against this schema before it reaches us.
+ */
+export type AskUserQuestion = AskUserQuestionInput["questions"][number];
+
+/**
+ * Pull the well-formed questions out of an AskUserQuestion tool input. Returns
+ * `null` when there are no usable questions — including the case where every
+ * entry is malformed and filtering leaves an empty list — so callers can treat
+ * "nothing to ask" uniformly.
+ */
+export function extractAskUserQuestions(input: Record<string, unknown>): AskUserQuestion[] | null {
+  const questions = (input as { questions?: unknown }).questions;
+  if (!Array.isArray(questions)) {
+    return null;
+  }
+  const valid = questions.filter(
+    (q): q is AskUserQuestion =>
+      !!q && typeof q.question === "string" && Array.isArray(q.options) && q.options.length > 0,
+  );
+  return valid.length > 0 ? valid : null;
+}
+
+/** Stable form-field key for the question at the given index. */
+function questionFieldKey(index: number): string {
+  return `question_${index}`;
+}
+
+/** Form-field key for the optional free-text "custom answer" field. */
+const CUSTOM_ANSWER_FIELD = "customAnswer";
+
+/**
+ * Render the AskUserQuestion tool's questions as an ACP form elicitation.
+ *
+ * Fields are keyed by a short stable id (`question_<n>`) rather than the full
+ * question text, so the question text appears in exactly one place per field.
+ * Single-select questions use a titled `oneOf` enum; multi-select questions use
+ * an array with a titled `anyOf` item enum. The enum `const` is always the
+ * option label, since that is what the tool records as the answer.
+ *
+ * A trailing optional free-text field mirrors the CLI's custom-answer box: the
+ * user can type their own answer instead of (or as well as) picking an option.
+ * Nothing is marked required, so the user can also just skip — matching the
+ * built-in tool, which always offers Skip + a free-text box.
+ */
+export function askUserQuestionsToCreateRequest(
+  questions: AskUserQuestion[],
+  sessionId: string,
+  toolCallId: string | undefined,
+): CreateElicitationRequest {
+  const single = questions.length === 1;
+  const properties: Record<string, ElicitationPropertySchema> = {};
+
+  questions.forEach((question, index) => {
+    const options: EnumOption[] = question.options.map((option) => ({
+      const: option.label,
+      title: option.description ? `${option.label} — ${option.description}` : option.label,
+    }));
+
+    // 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.
+    const description = single ? undefined : question.question;
+    const title = question.header || undefined;
+
+    properties[questionFieldKey(index)] = question.multiSelect
+      ? { type: "array", title, description, items: { anyOf: options } }
+      : { type: "string", title, description, oneOf: options };
+  });
+
+  properties[CUSTOM_ANSWER_FIELD] = {
+    type: "string",
+    title: "Other",
+    description: "Type your own answer instead of choosing an option above (optional).",
+  };
+
+  const requestedSchema: ElicitationSchema = {
+    type: "object",
+    properties,
+  };
+
+  const message = single ? questions[0].question : "Please answer the following questions.";
+
+  return {
+    mode: "form",
+    sessionId,
+    ...(toolCallId ? { toolCallId } : {}),
+    message,
+    requestedSchema,
+  };
+}
+
+/** Outcome of an AskUserQuestion elicitation, decoupled from any transport. */
+export type AskUserQuestionOutcome =
+  | { action: "answered"; updatedInput: Record<string, unknown> }
+  | { action: "cancel" };
+
+/**
+ * Fold an ACP elicitation response into the AskUserQuestion tool's input.
+ *
+ * Selected labels are read back from the indexed form fields and written into
+ * `answers` as a `{ [questionText]: label }` map (comma-joining multi-selects)
+ * — the key shape the tool's own `call()` reads. Free text from the custom-
+ * answer field becomes the tool's top-level `response`. Decline yields empty
+ * answers (the model is told the user skipped rather than the turn aborting);
+ * cancel aborts the tool call.
+ */
+export function applyAskElicitationResponse(
+  response: CreateElicitationResponse,
+  toolInput: Record<string, unknown>,
+  questions: AskUserQuestion[],
+): AskUserQuestionOutcome {
+  if (response.action === "cancel") {
+    return { action: "cancel" };
+  }
+
+  if (response.action === "decline") {
+    return { action: "answered", updatedInput: { ...toolInput, answers: {} } };
+  }
+
+  const content = response.content ?? {};
+  // Typed against the tool's own output schema so the answer/response shapes
+  // stay in sync with what the built-in tool's call() expects to read back.
+  const answers: AskUserQuestionOutput["answers"] = {};
+  questions.forEach((question, index) => {
+    const value = content[questionFieldKey(index)];
+    if (value === undefined || value === null) {
+      return;
+    }
+    const text = Array.isArray(value) ? value.join(", ") : String(value);
+    if (text === "") {
+      return;
+    }
+    answers[question.question] = text;
+  });
+
+  const updatedInput: Record<string, unknown> = { ...toolInput, answers };
+  const custom = content[CUSTOM_ANSWER_FIELD];
+  if (typeof custom === "string" && custom.trim() !== "") {
+    const response: AskUserQuestionOutput["response"] = custom;
+    updatedInput.response = response;
+  }
+
+  return { action: "answered", updatedInput };
+}
+
+/**
+ * Coerce an arbitrary MCP `requestedSchema` into an ACP `ElicitationSchema`.
+ * The two are structurally compatible JSON Schemas; we just guarantee the
+ * `type: "object"` discriminator is present.
+ */
+function normalizeElicitationSchema(
+  schema: Record<string, unknown> | undefined,
+): ElicitationSchema {
+  if (!schema || typeof schema !== "object") {
+    return { type: "object", properties: {} };
+  }
+  return { ...(schema as ElicitationSchema), type: "object" };
+}
--- a/src/tests/acp-agent-settings.test.ts
+++ b/src/tests/acp-agent-settings.test.ts
@@ -225,7 +225,9 @@ describe("ClaudeAcpAgent settings", () => {
    // No setModel call is needed because no override was applied — the SDK is
    // already on its own default.
    expect(setModelSpy).not.toHaveBeenCalled();
-    expect(response.models.currentModelId).toBe("claude-sonnet-4-6");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-sonnet-4-6",
+    );
  });

  describe("auto mode availability per model", () => {
@@ -578,10 +580,12 @@ describe("ClaudeAcpAgent settings", () => {
      });

      expect(setModelSpy).toHaveBeenCalledWith("claude-haiku-4-5");
-      expect(response.models.currentModelId).toBe("claude-haiku-4-5");
+      expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+        "claude-haiku-4-5",
+      );
    });

-    it("does not inherit display info across mismatched model family versions", async () => {
+    it("does not inherit display info across mismatched model versions", async () => {
      // https://github.com/agentclientprotocol/claude-agent-acp/issues/639:
      // when the SDK's `opus` alias resolves to Opus 4.7, an allowlist entry
      // of `claude-opus-4-6` (or `claude-opus-4-6[1m]`) used to substring-match
@@ -642,6 +646,60 @@ describe("ClaudeAcpAgent settings", () => {
      expect(byValue["claude-opus-4-7"].name).toBe("Opus 4.7");
      expect(byValue["claude-opus-4-7[1m]"].name).toMatch(/Opus 4\.7/);
    });
+
+    it("does not inherit display info across mismatched model families", async () => {
+      // https://github.com/agentclientprotocol/claude-agent-acp/issues/639:
+      // when the SDK's `opus` alias resolves to Opus 4.8, `claude-opus-4-6[1m]`
+      // fails the version check against `opus` but the tokenized matcher
+      // falls through to `sonnet[1m]` because the `1m` context hint alone
+      // is enough to score a match.
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-opus-4-6", "claude-opus-4-6[1m]"],
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        {
+          value: "sonnet",
+          displayName: "Sonnet",
+          description: "Sonnet 4.6 · Best for everyday tasks",
+        },
+        {
+          value: "sonnet[1m]",
+          displayName: "Sonnet (1M context)",
+          description: "Sonnet 4.6 for long sessions",
+        },
+        {
+          value: "opus",
+          displayName: "Opus 4.8",
+          description: "Claude Opus 4.8",
+        },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      const modelOption = response.configOptions.find((o: any) => o.id === "model");
+      const byValue: Record<string, { name: string; description?: string }> = {};
+      for (const opt of modelOption.options) {
+        byValue[opt.value] = { name: opt.name, description: opt.description };
+      }
+
+      expect(byValue["claude-opus-4-6[1m]"].name).toBe("claude-opus-4-6[1m]");
+      expect(byValue["claude-opus-4-6"].name).toBe("claude-opus-4-6");
+    });
  });

  it("resolves model aliases like opus[1m] to the correct model", async () => {
@@ -687,7 +745,9 @@ describe("ClaudeAcpAgent settings", () => {
    });

    expect(setModelSpy).toHaveBeenCalledWith("claude-opus-4-6-1m");
-    expect(response.models.currentModelId).toBe("claude-opus-4-6-1m");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-opus-4-6-1m",
+    );
  });

  it("skips the initial setModel when the resolved value matches the SDK's model list verbatim", async () => {
@@ -727,7 +787,9 @@ describe("ClaudeAcpAgent settings", () => {
      });

      expect(setModelSpy).not.toHaveBeenCalled();
-      expect(response.models.currentModelId).toBe("claude-opus-4-6");
+      expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+        "claude-opus-4-6",
+      );
    } finally {
      if (originalEnv === undefined) {
        delete process.env.ANTHROPIC_MODEL;
@@ -777,6 +839,8 @@ describe("ClaudeAcpAgent settings", () => {
    });

    expect(setModelSpy).toHaveBeenCalledWith("claude-haiku-4-5");
-    expect(response.models.currentModelId).toBe("claude-haiku-4-5");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-haiku-4-5",
+    );
  });
 });
--- a/src/tests/acp-agent.test.ts
+++ b/src/tests/acp-agent.test.ts
@@ -6,6 +6,8 @@ import {
  AvailableCommand,
  Client,
  ClientSideConnection,
+  CreateElicitationRequest,
+  CreateElicitationResponse,
  ndJsonStream,
  NewSessionResponse,
  ReadTextFileRequest,
@@ -33,10 +35,16 @@ import {
  claudeCliPath,
  describeAlwaysAllow,
  streamEventToAcpNotifications,
+  messageIdForGrouping,
  type SDKMessageFilter,
 } from "../acp-agent.js";
 import { Pushable } from "../utils.js";
-import { deleteSession, query, SDKAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
+import {
+  deleteSession,
+  getSessionMessages,
+  query,
+  SDKAssistantMessage,
+} from "@anthropic-ai/claude-agent-sdk";
 import { randomUUID } from "crypto";

 vi.mock("@anthropic-ai/claude-agent-sdk", async (importOriginal) => {
@@ -83,6 +91,10 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
    agent: Agent;
    files: Map<string, string> = new Map();
    receivedText: string = "";
+    // Records for the AskUserQuestion elicitation test.
+    elicitations: CreateElicitationRequest[] = [];
+    permissionToolInputs: unknown[] = [];
+    chosenAnswers: Record<string, string | string[]> = {};
    resolveAvailableCommands: (commands: AvailableCommand[]) => void;
    availableCommandsPromise: Promise<AvailableCommand[]>;

@@ -101,11 +113,39 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
    }

    async requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+      // Record what asked for permission so a test can assert that
+      // AskUserQuestion did NOT fall back to a generic permission prompt.
+      this.permissionToolInputs.push(params.toolCall?.rawInput);
      const optionId = params.options.find((p) => p.kind === "allow_once")!.optionId;

      return { outcome: { outcome: "selected", optionId } };
    }

+    async unstable_createElicitation(
+      params: CreateElicitationRequest,
+    ): Promise<CreateElicitationResponse> {
+      this.elicitations.push(params);
+      if (params.mode !== "form") {
+        return { action: "decline" };
+      }
+      // Accept the first option of every choice field (skip the free-text one).
+      const content: Record<string, string | string[]> = {};
+      for (const [key, prop] of Object.entries(params.requestedSchema.properties ?? {})) {
+        if (key === "customAnswer") continue;
+        const p = prop as {
+          oneOf?: Array<{ const: string }>;
+          items?: { anyOf?: Array<{ const: string }> };
+        };
+        if (p.oneOf?.length) {
+          content[key] = p.oneOf[0].const;
+        } else if (p.items?.anyOf?.length) {
+          content[key] = [p.items.anyOf[0].const];
+        }
+      }
+      this.chosenAnswers = content;
+      return { action: "accept", content };
+    }
+
    async sessionUpdate(params: SessionNotification): Promise<void> {
      console.error("RECEIVED", JSON.stringify(params, null, 4));

@@ -158,6 +198,9 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
          readTextFile: true,
          writeTextFile: true,
        },
+        elicitation: {
+          form: {},
+        },
      },
    });

@@ -170,7 +213,7 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
  }

  it("should connect to the ACP subprocess", async () => {
-    const { client, connection, newSessionResponse } = await setupTestSession("./");
+    const { client, connection, newSessionResponse } = await setupTestSession(process.cwd());

    await connection.prompt({
      prompt: [
@@ -261,6 +304,60 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"

    expect(client.takeReceivedText()).toContain("Compacting...\n\nCompacting completed.");
  }, 60000);
+
+  // Regression guard for the SDK's AskUserQuestion routing. The built-in
+  // AskUserQuestion tool is delivered to us through `canUseTool` (not the
+  // interactive `onUserDialog` path), where we intercept it and render an ACP
+  // form elicitation, returning the answer via `updatedInput`. If a future SDK
+  // changes that routing — e.g. stops calling `canUseTool` for it, or no longer
+  // reads answers back from `updatedInput` — this test fails: either no
+  // elicitation arrives, the tool falls back to a permission prompt, or the
+  // answer never reaches the model's reply.
+  it("routes AskUserQuestion through ACP form elicitation and round-trips the answer", async () => {
+    const { client, connection, newSessionResponse } = await setupTestSession(process.cwd());
+
+    await connection.prompt({
+      prompt: [
+        {
+          type: "text",
+          text:
+            "Use the AskUserQuestion tool right now to ask me to choose a favorite color. " +
+            "Offer exactly two options: 'Red' and 'Blue'. Do not use any other tool and do " +
+            "not ask in plain text. After I answer, reply with one short sentence naming the " +
+            "color I picked.",
+        },
+      ],
+      sessionId: newSessionResponse.sessionId,
+    });
+
+    // The tool surfaced as an ACP form elicitation...
+    expect(client.elicitations.length).toBeGreaterThan(0);
+    const elicitation = client.elicitations[0];
+    expect(elicitation.mode).toBe("form");
+
+    // ...built by our converter (indexed field key + free-text "Other" field),
+    // which confirms our interception path produced it rather than some other
+    // mechanism.
+    const properties =
+      elicitation.mode === "form" ? Object.keys(elicitation.requestedSchema.properties ?? {}) : [];
+    expect(properties).toContain("question_0");
+    expect(properties).toContain("customAnswer");
+
+    // AskUserQuestion must NOT fall back to a generic permission prompt: no
+    // permission request should have carried AskUserQuestion's `questions`.
+    const fellBackToPermission = client.permissionToolInputs.some(
+      (input) =>
+        !!input &&
+        typeof input === "object" &&
+        Array.isArray((input as { questions?: unknown }).questions),
+    );
+    expect(fellBackToPermission).toBe(false);
+
+    // The chosen answer round-trips: the model's reply names the picked option.
+    const picked = String(Object.values(client.chosenAnswers)[0] ?? "");
+    expect(picked).not.toEqual("");
+    expect(client.takeReceivedText().toLowerCase()).toContain(picked.toLowerCase());
+  }, 60000);
 });

 describe("tool conversions", () => {
@@ -1318,6 +1415,67 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("SDK behavior", () => {
    const { value } = await q.next();
    expect(value).toMatchObject({ type: "system", session_id: sessionId });
  }, 10000);
+
+  // Pins the SDK invariant our `messageId` plumbing relies on: the Anthropic
+  // API message id is available at `message_start` (before any delta), is the
+  // same on the consolidated assistant message, and is recoverable from the
+  // persisted transcript — so a turn keeps one stable id across streaming and
+  // replay. The per-`stream_event` uuid is NOT used because it is unique per
+  // event and never persisted; this test would fail if a future SDK regressed
+  // any of those properties.
+  it("uses the API message id as a stable anchor across streaming and replay", async () => {
+    const sessionId = randomUUID();
+    const q = query({
+      prompt: "Reply with exactly these words and nothing else: hello there my friend",
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        sessionId,
+        includePartialMessages: true,
+        maxTurns: 1,
+        allowedTools: [],
+      },
+    });
+
+    let messageStartApiId: string | undefined;
+    let consolidatedApiId: string | undefined;
+    let sawDelta = false;
+    let allPartialsTopLevel = true;
+
+    for await (const message of q) {
+      if (message.type === "assistant") {
+        consolidatedApiId = message.message.id;
+      }
+      if (message.type !== "stream_event") continue;
+      // Every streaming partial must belong to the top-level agent
+      // (parent_tool_use_id === null). Subagent work is folded into tool-result
+      // messages rather than surfaced as partial streams, which is what lets us
+      // track a single anchor without keying by parent_tool_use_id.
+      if (message.parent_tool_use_id !== null) allPartialsTopLevel = false;
+      if (message.event.type === "message_start") {
+        messageStartApiId = message.event.message.id;
+      } else if (message.event.type === "content_block_delta") {
+        sawDelta = true;
+      }
+    }
+
+    // The API message id is present at message_start (before deltas), so we can
+    // tag every streamed chunk with it, and it is identical on the consolidated
+    // assistant message.
+    expect(messageStartApiId).toBeTruthy();
+    expect(sawDelta).toBe(true);
+    expect(allPartialsTopLevel).toBe(true);
+    expect(consolidatedApiId).toBe(messageStartApiId);
+
+    // ...and the SAME id is recoverable from the persisted transcript, so chunks
+    // grouped live keep their id when the session is replayed.
+    const persisted = await getSessionMessages(sessionId);
+    const replayedAssistant = persisted.find((m) => m.type === "assistant");
+    expect(replayedAssistant).toBeDefined();
+    expect((replayedAssistant!.message as { id?: string }).id).toBe(messageStartApiId);
+    // The helper used in production must derive that same id from the replayed
+    // message.
+    expect(messageIdForGrouping(replayedAssistant!)).toBe(messageStartApiId);
+  }, 30000);
 });

 describe("permission requests", () => {
@@ -1548,6 +1706,8 @@ describe("stop reason propagation", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
  }

@@ -1692,6 +1852,8 @@ describe("stop reason propagation", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };

    const response = await agent.prompt({
@@ -1851,6 +2013,8 @@ describe("session/close", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
    return agent.sessions[sessionId]!;
  }
@@ -1935,6 +2099,8 @@ describe("session/delete", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
    return agent.sessions[sessionId]!;
  }
@@ -1948,7 +2114,7 @@ describe("session/delete", () => {
    const agent = createMockAgent();
    const session = injectSession(agent, "session-1");

-    const result = await agent.unstable_deleteSession({ sessionId: "session-1" });
+    const result = await agent.deleteSession({ sessionId: "session-1" });

    expect(result).toEqual({});
    expect(agent.sessions["session-1"]).toBeUndefined();
@@ -1961,7 +2127,7 @@ describe("session/delete", () => {
  it("deletes a session from disk that is not currently active", async () => {
    const agent = createMockAgent();

-    const result = await agent.unstable_deleteSession({ sessionId: "not-active" });
+    const result = await agent.deleteSession({ sessionId: "not-active" });

    expect(result).toEqual({});
    expect(deleteSession).toHaveBeenCalledWith("not-active");
@@ -1971,7 +2137,7 @@ describe("session/delete", () => {
    const agent = createMockAgent();
    vi.mocked(deleteSession).mockRejectedValueOnce(new Error("Session not found on disk"));

-    await expect(agent.unstable_deleteSession({ sessionId: "missing" })).rejects.toThrow(
+    await expect(agent.deleteSession({ sessionId: "missing" })).rejects.toThrow(
      "Session not found on disk",
    );
  });
@@ -1981,7 +2147,7 @@ describe("session/delete", () => {
    injectSession(agent, "session-a");
    injectSession(agent, "session-b");

-    await agent.unstable_deleteSession({ sessionId: "session-a" });
+    await agent.deleteSession({ sessionId: "session-a" });

    expect(agent.sessions["session-a"]).toBeUndefined();
    expect(agent.sessions["session-b"]).toBeDefined();
@@ -2036,6 +2202,8 @@ describe("getOrCreateSession param change detection", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
    return agent.sessions[sessionId]!;
  }
@@ -2271,6 +2439,8 @@ describe("usage_update computation", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
  }

@@ -3108,6 +3278,309 @@ describe("usage_update computation", () => {
    // size should be 1000000 (Opus), not 200000 (the fallback if <synthetic> overrode the model)
    expect(usageUpdate.update.size).toBe(1000000);
  });
+
+  it("compact_boundary uses authoritative getContextUsage for used, keeps session window for size", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    injectSession(agent, [
+      { type: "system", subtype: "compact_boundary", session_id: "test-session" },
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+    const session = agent.sessions["test-session"];
+    // A 1M window learned earlier (e.g. from modelUsage) must survive compaction
+    // — getContextUsage's window field under-reports it, so we don't use it.
+    session.contextWindowSize = 1000000;
+    (session.query as any).getContextUsage = vi
+      .fn()
+      .mockResolvedValue({ totalTokens: 12345, rawMaxTokens: 200000 });
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "test" }] });
+
+    const usageUpdate = updates.find((u: any) => u.update?.sessionUpdate === "usage_update");
+    expect(usageUpdate).toBeDefined();
+    expect(usageUpdate.update.used).toBe(12345);
+    // size stays at the session's learned window, NOT getContextUsage's value.
+    expect(usageUpdate.update.size).toBe(1000000);
+    expect(session.contextWindowSize).toBe(1000000);
+  });
+
+  it("compact_boundary falls back to used:0 when getContextUsage fails", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    injectSession(agent, [
+      { type: "system", subtype: "compact_boundary", session_id: "test-session" },
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+    const session = agent.sessions["test-session"];
+    session.contextWindowSize = 200000;
+    (session.query as any).getContextUsage = vi.fn().mockRejectedValue(new Error("boom"));
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "test" }] });
+
+    const usageUpdate = updates.find((u: any) => u.update?.sessionUpdate === "usage_update");
+    expect(usageUpdate).toBeDefined();
+    expect(usageUpdate.update.used).toBe(0);
+    expect(usageUpdate.update.size).toBe(200000);
+    expect(session.contextWindowSize).toBe(200000);
+  });
+});
+
+describe("assembled assistant text fallback", () => {
+  const ZERO_USAGE = {
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_input_tokens: 0,
+    cache_creation_input_tokens: 0,
+  };
+
+  function createMockAgentWithCapture() {
+    const updates: any[] = [];
+    const mockClient = {
+      sessionUpdate: async (notification: any) => {
+        updates.push(notification);
+      },
+    } as unknown as AgentSideConnection;
+    const agent = new ClaudeAcpAgent(mockClient, { log: () => {}, error: () => {} });
+    return { agent, updates };
+  }
+
+  function messageStart(apiId: string) {
+    return {
+      type: "stream_event" as const,
+      parent_tool_use_id: null,
+      uuid: randomUUID(),
+      session_id: "test-session",
+      event: {
+        type: "message_start" as const,
+        message: { id: apiId, model: "claude-sonnet-4-20250514", usage: ZERO_USAGE },
+      },
+    };
+  }
+
+  function textDelta(text: string) {
+    return {
+      type: "stream_event" as const,
+      parent_tool_use_id: null,
+      uuid: randomUUID(),
+      session_id: "test-session",
+      event: {
+        type: "content_block_delta" as const,
+        index: 0,
+        delta: { type: "text_delta" as const, text },
+      },
+    };
+  }
+
+  function assistantMessage(apiId: string, content: any[], parentToolUseId: string | null = null) {
+    return {
+      type: "assistant" as const,
+      parent_tool_use_id: parentToolUseId,
+      uuid: randomUUID(),
+      session_id: "test-session",
+      message: {
+        id: apiId,
+        role: "assistant" as const,
+        model: "claude-sonnet-4-20250514",
+        content,
+        usage: ZERO_USAGE,
+      },
+    };
+  }
+
+  function result() {
+    return {
+      type: "result" as const,
+      subtype: "success" as const,
+      stop_reason: "end_turn",
+      is_error: false,
+      result: "",
+      errors: [],
+      duration_ms: 0,
+      duration_api_ms: 0,
+      num_turns: 1,
+      total_cost_usd: 0,
+      usage: ZERO_USAGE,
+      modelUsage: {},
+      permission_denials: [],
+      uuid: randomUUID(),
+      session_id: "test-session",
+    };
+  }
+
+  const idle = { type: "system", subtype: "session_state_changed", state: "idle" };
+
+  function injectSession(agent: ClaudeAcpAgent, messages: any[]) {
+    const input = new Pushable<any>();
+    async function* messageGenerator() {
+      const iter = input[Symbol.asyncIterator]();
+      const { value: userMessage, done } = await iter.next();
+      if (!done && userMessage) {
+        yield {
+          type: "user",
+          message: userMessage.message,
+          parent_tool_use_id: null,
+          uuid: userMessage.uuid,
+          session_id: "test-session",
+          isReplay: true,
+        };
+      }
+      yield* messages;
+    }
+    agent.sessions["test-session"] = {
+      query: messageGenerator() as any,
+      input,
+      cancelled: false,
+      cwd: "/test",
+      sessionFingerprint: JSON.stringify({ cwd: "/test", mcpServers: [] }),
+      modes: { currentModeId: "default", availableModes: [] },
+      models: { currentModelId: "default", availableModels: [] },
+      modelInfos: [],
+      settingsManager: { dispose: vi.fn() } as any,
+      accumulatedUsage: {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedReadTokens: 0,
+        cachedWriteTokens: 0,
+      },
+      configOptions: [],
+      promptRunning: false,
+      pendingMessages: new Map(),
+      nextPendingOrder: 0,
+      abortController: new AbortController(),
+      emitRawSDKMessages: false,
+      contextWindowSize: 200000,
+      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
+    };
+  }
+
+  function messageChunkTexts(updates: any[]): string[] {
+    return updates
+      .filter((u) => u.update?.sessionUpdate === "agent_message_chunk")
+      .map((u) => u.update.content.text);
+  }
+
+  function thoughtChunkTexts(updates: any[]): string[] {
+    return updates
+      .filter((u) => u.update?.sessionUpdate === "agent_thought_chunk")
+      .map((u) => u.update.content.text);
+  }
+
+  it("emits the assembled text when no content_block_delta was streamed", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    // Gateway delivers a fully assembled message with no preceding deltas.
+    injectSession(agent, [
+      assistantMessage("msg-no-stream", [{ type: "text", text: "the final answer" }]),
+      result(),
+      idle,
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    expect(messageChunkTexts(updates)).toEqual(["the final answer"]);
+  });
+
+  it("does not re-emit text already streamed via content_block_delta", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    // Normal streaming: deltas arrive, then the consolidated message repeats them.
+    injectSession(agent, [
+      messageStart("msg-streamed"),
+      textDelta("hello "),
+      textDelta("world"),
+      assistantMessage("msg-streamed", [{ type: "text", text: "hello world" }]),
+      result(),
+      idle,
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    // Only the two streamed deltas — the assembled block is filtered out.
+    expect(messageChunkTexts(updates)).toEqual(["hello ", "world"]);
+  });
+
+  it("dedupes per block type: streamed text is dropped but an un-streamed thinking block in the same message is forwarded", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    // Gateway streams the text live but delivers the thinking block only in the
+    // assembled message (no thinking_delta). The dedupe must be per-type so the
+    // thinking survives. This also makes the test non-vacuous: if the fallback
+    // were removed (text/thinking always dropped) the thought chunk disappears.
+    injectSession(agent, [
+      messageStart("msg-mixed"),
+      textDelta("streamed text"),
+      assistantMessage("msg-mixed", [
+        { type: "text", text: "streamed text" },
+        { type: "thinking", thinking: "private reasoning" },
+      ]),
+      result(),
+      idle,
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    // Streamed text appears once (delta only — assembled copy deduped).
+    expect(messageChunkTexts(updates)).toEqual(["streamed text"]);
+    // The un-streamed thinking block is forwarded despite text having streamed.
+    expect(thoughtChunkTexts(updates)).toEqual(["private reasoning"]);
+  });
+
+  it("does not leak subagent assistant text into the top-level feed", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    // Subagent assistant messages (parent_tool_use_id !== null) are never
+    // streamed live; their text/thinking is internal to the tool call and must
+    // stay filtered out, not surface as a fallback chunk.
+    injectSession(agent, [
+      assistantMessage(
+        "msg-subagent",
+        [{ type: "text", text: "subagent internal prose" }],
+        "tool_use_1",
+      ),
+      result(),
+      idle,
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    expect(messageChunkTexts(updates)).toEqual([]);
+    expect(thoughtChunkTexts(updates)).toEqual([]);
+  });
+
+  it("forwards distinct blocks that a gateway splits across same-id messages", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    // Observed with OpenAI-compatible gateways: one response id split into an
+    // empty thinking block, then the real text — both with no deltas.
+    injectSession(agent, [
+      assistantMessage("msg-split", [{ type: "thinking", thinking: "" }]),
+      assistantMessage("msg-split", [{ type: "text", text: "the real answer" }]),
+      result(),
+      idle,
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    // The text survives even though an earlier same-id message already triggered
+    // the fallback for a different (thinking) block.
+    expect(messageChunkTexts(updates)).toEqual(["the real answer"]);
+    // The empty thinking block carries nothing and must not produce a stray
+    // empty thought chunk.
+    expect(thoughtChunkTexts(updates)).toEqual([]);
+  });
+
+  it("re-forwards a block a gateway re-delivers (no content-keyed dedupe)", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    // The fallback intentionally keys only on whether the id streamed live, not
+    // on block content — so a gateway re-delivering the same assembled block
+    // emits it twice. This is the accepted, cosmetic tradeoff for not caching
+    // every fallback block's full text; see `streamedTextMessageIds`.
+    injectSession(agent, [
+      assistantMessage("msg-dup", [{ type: "text", text: "answer" }]),
+      assistantMessage("msg-dup", [{ type: "text", text: "answer" }]),
+      result(),
+      idle,
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    expect(messageChunkTexts(updates)).toEqual(["answer", "answer"]);
+  });
 });

 describe("emitRawSDKMessages", () => {
@@ -3171,6 +3644,8 @@ describe("emitRawSDKMessages", () => {
      emitRawSDKMessages,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
  }

@@ -3399,6 +3874,8 @@ describe("result origin handling", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
  }

@@ -3574,6 +4051,8 @@ describe("memory_recall handling", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
  }

@@ -3804,6 +4283,8 @@ describe("post-error recovery", () => {
      emitRawSDKMessages: false,
      contextWindowSize: 200000,
      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
    };
    return { interrupt };
  }
@@ -3877,6 +4358,186 @@ describe("post-error recovery", () => {
  });
 });

+describe("session/cancel wedge recovery (issue #680)", () => {
+  function createMockAgent() {
+    const mockClient = {
+      sessionUpdate: async () => {},
+    } as unknown as AgentSideConnection;
+    return new ClaudeAcpAgent(mockClient, { log: () => {}, error: () => {} });
+  }
+
+  // Generator that replays the prompt's user message and then blocks forever,
+  // simulating the SDK wedged in a `TaskOutput { block: true }` poll against a
+  // hung background task. `interrupt()` is a no-op — it does NOT unblock the
+  // generator, matching the SDK behavior described in the issue.
+  function injectWedgedSession(agent: ClaudeAcpAgent, opts: { interruptUnblocks?: boolean } = {}) {
+    const input = new Pushable<any>();
+    const interrupt = vi.fn(async () => {});
+    const close = vi.fn();
+    // A promise the wedged poll awaits. When `interruptUnblocks` is set, the
+    // mocked interrupt() resolves it so the generator yields a trailing idle —
+    // the normal, healthy interrupt path.
+    let releaseBlock!: () => void;
+    const blocked = new Promise<void>((resolve) => {
+      releaseBlock = resolve;
+    });
+    if (opts.interruptUnblocks) {
+      interrupt.mockImplementation(async () => {
+        releaseBlock();
+      });
+    }
+
+    async function* messageGenerator() {
+      const iter = input[Symbol.asyncIterator]();
+      const first = await iter.next();
+      if (!first.done && first.value) {
+        yield {
+          type: "user",
+          message: first.value.message,
+          parent_tool_use_id: null,
+          uuid: first.value.uuid,
+          session_id: "test-session",
+          isReplay: true,
+        };
+      }
+      // Wedge: never yield again unless interrupt() releases us.
+      await blocked;
+      yield { type: "system", subtype: "session_state_changed", state: "idle" };
+    }
+
+    const gen = Object.assign(messageGenerator(), { interrupt, close });
+    agent.sessions["test-session"] = {
+      query: gen as any,
+      input,
+      cancelled: false,
+      cwd: "/test",
+      sessionFingerprint: JSON.stringify({ cwd: "/test", mcpServers: [] }),
+      modes: { currentModeId: "default", availableModes: [] },
+      models: { currentModelId: "default", availableModels: [] },
+      modelInfos: [],
+      settingsManager: { dispose: vi.fn() } as any,
+      accumulatedUsage: {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedReadTokens: 0,
+        cachedWriteTokens: 0,
+      },
+      configOptions: [],
+      promptRunning: false,
+      pendingMessages: new Map(),
+      nextPendingOrder: 0,
+      abortController: new AbortController(),
+      emitRawSDKMessages: false,
+      contextWindowSize: 200000,
+      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
+    };
+    return { interrupt };
+  }
+
+  it("resolves the pending prompt with cancelled when the SDK never yields after interrupt", async () => {
+    const agent = createMockAgent();
+    // Shrink the grace period so the test doesn't wait the production default.
+    agent.forceCancelGraceMs = 20;
+    const { interrupt } = injectWedgedSession(agent);
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+
+    // Let the loop consume the replay and block on the wedged query.next().
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.cancel({ sessionId: "test-session" });
+
+    const response = await promptPromise;
+    expect(response.stopReason).toBe("cancelled");
+    expect(interrupt).toHaveBeenCalled();
+  });
+
+  it("returns cancelled through the normal idle path without waiting the grace period when interrupt works", async () => {
+    const agent = createMockAgent();
+    // Large grace so that if the test ever falls through to the backstop it
+    // would hang past the test timeout instead of passing by accident.
+    agent.forceCancelGraceMs = 60_000;
+    const { interrupt } = injectWedgedSession(agent, { interruptUnblocks: true });
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.cancel({ sessionId: "test-session" });
+
+    const response = await promptPromise;
+    expect(response.stopReason).toBe("cancelled");
+    expect(interrupt).toHaveBeenCalled();
+    // Backstop timer must have been cleared so it can't fire later.
+    expect(agent.sessions["test-session"].forceCancelTimer).toBeUndefined();
+  });
+
+  it("does not arm the backstop when no prompt is running", async () => {
+    const agent = createMockAgent();
+    injectWedgedSession(agent);
+
+    await agent.cancel({ sessionId: "test-session" });
+
+    const session = agent.sessions["test-session"];
+    expect(session.cancelled).toBe(true);
+    expect(session.forceCancelTimer).toBeUndefined();
+  });
+
+  it("does not reset the force-cancel floor on repeated cancels", async () => {
+    const agent = createMockAgent();
+    // Long floor so the timer handle stays observable across both cancels.
+    agent.forceCancelGraceMs = 60_000;
+    injectWedgedSession(agent);
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.cancel({ sessionId: "test-session" });
+    const firstTimer = agent.sessions["test-session"].forceCancelTimer;
+    expect(firstTimer).toBeDefined();
+
+    await agent.cancel({ sessionId: "test-session" });
+    // Same handle: the second cancel did not clear-and-rearm (which would push
+    // the floor out). The deadline stays anchored to the first cancel.
+    expect(agent.sessions["test-session"].forceCancelTimer).toBe(firstTimer);
+
+    // Clean up the wedged prompt + long timer.
+    await agent.closeSession({ sessionId: "test-session" });
+    await expect(promptPromise).resolves.toEqual({ stopReason: "cancelled" });
+  });
+
+  it("resolves an in-flight wedged prompt immediately when the session is closed", async () => {
+    const agent = createMockAgent();
+    // Large floor: if closeSession relied on the force-cancel timer this would
+    // hang past the test timeout. Teardown must wake the loop via
+    // cancelController instead.
+    agent.forceCancelGraceMs = 60_000;
+    injectWedgedSession(agent);
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.closeSession({ sessionId: "test-session" });
+
+    await expect(promptPromise).resolves.toEqual({ stopReason: "cancelled" });
+    expect(agent.sessions["test-session"]).toBeUndefined();
+  });
+});
+
 describe("streamEventToAcpNotifications", () => {
  it("treats `ping` keep-alive events as no-ops without logging to stderr", () => {
    const errors: unknown[][] = [];
@@ -3910,4 +4571,166 @@ describe("streamEventToAcpNotifications", () => {
    expect(result).toEqual([]);
    expect(errors).toEqual([]);
  });
+
+  it("attaches the supplied messageId to streamed text chunks", () => {
+    const messageId = randomUUID();
+    const message = {
+      type: "stream_event",
+      parent_tool_use_id: null,
+      uuid: randomUUID(),
+      session_id: "test-session",
+      event: {
+        type: "content_block_delta",
+        index: 0,
+        delta: { type: "text_delta", text: "hello" },
+      },
+    } as Parameters<typeof streamEventToAcpNotifications>[0];
+
+    const result = streamEventToAcpNotifications(
+      message,
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+
+    expect(result).toEqual([
+      {
+        sessionId: "test",
+        update: {
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: "hello" },
+          messageId,
+        },
+      },
+    ]);
+  });
+});
+
+describe("toAcpNotifications messageId", () => {
+  const messageId = "11111111-2222-3333-4444-555555555555";
+
+  it("sets messageId on agent message chunks from string content", () => {
+    const result = toAcpNotifications(
+      "hello world",
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+
+    expect(result).toEqual([
+      {
+        sessionId: "test",
+        update: {
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: "hello world" },
+          messageId,
+        },
+      },
+    ]);
+  });
+
+  it("sets messageId on user message chunks and thought chunks", () => {
+    const userResult = toAcpNotifications(
+      [{ type: "text", text: "hi" }],
+      "user",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+    expect(userResult[0].update).toMatchObject({
+      sessionUpdate: "user_message_chunk",
+      messageId,
+    });
+
+    const thoughtResult = toAcpNotifications(
+      [{ type: "thinking", thinking: "hmm", signature: "" }],
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+    expect(thoughtResult[0].update).toMatchObject({
+      sessionUpdate: "agent_thought_chunk",
+      messageId,
+    });
+  });
+
+  it("omits messageId when none is supplied", () => {
+    const result = toAcpNotifications(
+      "hello",
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+    );
+    expect(result[0].update).not.toHaveProperty("messageId");
+  });
+
+  it("never sets messageId on non-chunk updates (tool_call)", () => {
+    const result = toAcpNotifications(
+      [
+        {
+          type: "tool_use",
+          id: "toolu_abc",
+          name: "Read",
+          input: { file_path: "/tmp/x" },
+        },
+      ],
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId, registerHooks: false },
+    );
+    expect(result[0].update.sessionUpdate).toBe("tool_call");
+    expect(result[0].update).not.toHaveProperty("messageId");
+  });
+});
+
+describe("messageIdForGrouping", () => {
+  it("uses the Anthropic API message id for assistant messages", () => {
+    const message = {
+      type: "assistant",
+      uuid: "de242400-cdb3-4af7-9856-d3b114b20af9",
+      message: { id: "msg_018DQGVuZbGYwVnvDakAP9Do", role: "assistant" },
+    };
+    // The API id is identical at message_start, on the consolidated message,
+    // and in the persisted transcript — so it stays stable across replay,
+    // unlike the per-message uuid.
+    expect(messageIdForGrouping(message)).toBe("msg_018DQGVuZbGYwVnvDakAP9Do");
+  });
+
+  it("falls back to the uuid for assistant messages without an API id", () => {
+    const message = {
+      type: "assistant",
+      uuid: "de242400-cdb3-4af7-9856-d3b114b20af9",
+      message: { role: "assistant" },
+    };
+    expect(messageIdForGrouping(message)).toBe("de242400-cdb3-4af7-9856-d3b114b20af9");
+  });
+
+  it("uses the uuid for user messages (they carry no API id and aren't streamed)", () => {
+    const message = {
+      type: "user",
+      uuid: "11111111-2222-3333-4444-555555555555",
+      message: { id: "msg_should_be_ignored", role: "user" },
+    };
+    expect(messageIdForGrouping(message)).toBe("11111111-2222-3333-4444-555555555555");
+  });
+
+  it("returns undefined when there is no usable id", () => {
+    expect(messageIdForGrouping({ type: "system", message: {} })).toBeUndefined();
+    expect(messageIdForGrouping({ type: "assistant", uuid: "", message: {} })).toBeUndefined();
+  });
 });
--- a/src/tests/additional-roots.test.ts
+++ b/src/tests/additional-roots.test.ts
@@ -39,7 +39,7 @@ vi.mock("../tools.js", async () => ({
 describe("additionalRoots", () => {
  let agent: ClaudeAcpAgentType;
  const tempDirs: string[] = [];
-  const newSession = (meta: Record<string, unknown>, cwd = "/test") =>
+  const newSession = (meta: Record<string, unknown>, cwd = process.cwd()) =>
    agent.newSession({ cwd, mcpServers: [], _meta: meta });

  beforeEach(async () => {
@@ -79,7 +79,7 @@ describe("additionalRoots", () => {

  it("prefers the official ACP additionalDirectories field over _meta.additionalRoots", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      additionalDirectories: ["/from/official"],
      _meta: { additionalRoots: ["/from/meta"] },
@@ -89,7 +89,7 @@ describe("additionalRoots", () => {

  it("merges official ACP additionalDirectories with claudeCode SDK additionalDirectories", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      additionalDirectories: ["/from/official"],
      _meta: { claudeCode: { options: { additionalDirectories: ["/from/sdk"] } } },
@@ -99,7 +99,7 @@ describe("additionalRoots", () => {

  it("falls back to _meta.additionalRoots when the official field is omitted", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: { additionalRoots: ["/from/meta"] },
    });
--- a/src/tests/authorization.test.ts
+++ b/src/tests/authorization.test.ts
@@ -103,7 +103,7 @@ describe("authorization", () => {
    });

    await agent.newSession({
-      cwd: "testRoot",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -148,7 +148,7 @@ describe("authorization", () => {
    });

    await agent.newSession({
-      cwd: "testRoot",
+      cwd: process.cwd(),
      mcpServers: [],
    });

@@ -166,6 +166,63 @@ describe("authorization", () => {
    );
  });

+  it("hide claude authentication without terminal-auth", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("hide claude auth but still show console login when terminal-auth is set", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        _meta: { "terminal-auth": true },
+      },
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+  });
+
+  it("hide claude auth but still show console login with terminal capability", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { terminal: true },
+      },
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+  });
+
  it("SSH session falls back to single legacy login method", async () => {
    const [agent] = await createAgentMock();
    vi.stubGlobal("process", { ...process, env: { ...process.env, SSH_TTY: "/dev/pts/0" } });
@@ -206,6 +263,24 @@ describe("authorization", () => {
    );
  });

+  it("remote environment respects hide-claude-auth", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", {
+      ...process,
+      argv: ["--hide-claude-auth"],
+      env: { ...process.env, SSH_CONNECTION: "192.168.1.1 12345 192.168.1.2 22" },
+    });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { auth: { terminal: true } },
+    });
+
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+  });
+
  it("show claude authentication", async () => {
    const [agent] = await createAgentMock();

--- a/src/tests/create-session-options.test.ts
+++ b/src/tests/create-session-options.test.ts
@@ -1,7 +1,10 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
+import { AgentSideConnection, RequestError, SessionNotification } from "@agentclientprotocol/sdk";
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
 import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";

 let capturedOptions: Options | undefined;
 vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
@@ -65,7 +68,7 @@ describe("createSession options merging", () => {

  it("merges user-provided disallowedTools with ACP internal list", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -85,7 +88,7 @@ describe("createSession options merging", () => {

  it("works when user provides no disallowedTools", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
    });

@@ -94,7 +97,7 @@ describe("createSession options merging", () => {

  it("works when user provides empty disallowedTools", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -110,7 +113,7 @@ describe("createSession options merging", () => {

  it("sets tools to empty array when disableBuiltInTools is true", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        disableBuiltInTools: true,
@@ -133,7 +136,7 @@ describe("createSession options merging", () => {
    const userPreToolUseHook = { hooks: [{ command: "echo pre" }] };

    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -155,7 +158,7 @@ describe("createSession options merging", () => {

  it("inherits HOME and PATH from process.env when no env is provided", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
    });

@@ -165,7 +168,7 @@ describe("createSession options merging", () => {

  it("merges user-provided env vars on top of process.env", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -185,7 +188,7 @@ describe("createSession options merging", () => {

  it("allows user-provided env vars to override process.env entries", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -203,7 +206,7 @@ describe("createSession options merging", () => {

  it("defaults tools to claude_code preset when not provided", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
    });

@@ -212,7 +215,7 @@ describe("createSession options merging", () => {

  it("passes through user-provided tools string array", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -228,7 +231,7 @@ describe("createSession options merging", () => {

  it("explicit tools array takes precedence over disableBuiltInTools", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        disableBuiltInTools: true,
@@ -245,7 +248,7 @@ describe("createSession options merging", () => {

  it("passes through empty tools array to disable all built-in tools", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [],
      _meta: {
        claudeCode: {
@@ -261,7 +264,7 @@ describe("createSession options merging", () => {

  describe("systemPrompt via _meta", () => {
    it("defaults to the claude_code preset when not provided", async () => {
-      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });

      expect(capturedOptions!.systemPrompt).toEqual({
        type: "preset",
@@ -271,7 +274,7 @@ describe("createSession options merging", () => {

    it("replaces the preset when a string is provided", async () => {
      await agent.newSession({
-        cwd: "/test",
+        cwd: process.cwd(),
        mcpServers: [],
        _meta: { systemPrompt: "custom prompt" },
      });
@@ -281,7 +284,7 @@ describe("createSession options merging", () => {

    it("forwards append", async () => {
      await agent.newSession({
-        cwd: "/test",
+        cwd: process.cwd(),
        mcpServers: [],
        _meta: { systemPrompt: { append: "extra instructions" } },
      });
@@ -295,7 +298,7 @@ describe("createSession options merging", () => {

    it("forwards excludeDynamicSections", async () => {
      await agent.newSession({
-        cwd: "/test",
+        cwd: process.cwd(),
        mcpServers: [],
        _meta: { systemPrompt: { excludeDynamicSections: true } },
      });
@@ -309,7 +312,7 @@ describe("createSession options merging", () => {

    it("forwards append and excludeDynamicSections together", async () => {
      await agent.newSession({
-        cwd: "/test",
+        cwd: process.cwd(),
        mcpServers: [],
        _meta: {
          systemPrompt: {
@@ -329,7 +332,7 @@ describe("createSession options merging", () => {

    it("ignores caller-provided type/preset overrides", async () => {
      await agent.newSession({
-        cwd: "/test",
+        cwd: process.cwd(),
        mcpServers: [],
        _meta: {
          systemPrompt: {
@@ -369,7 +372,7 @@ describe("createSession options merging", () => {
        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
      });

-      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });

      expect(capturedOptions!.settings).toEqual({
        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
@@ -381,7 +384,7 @@ describe("createSession options merging", () => {
        availableModels: ["opus", "sonnet"],
      });

-      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });

      expect(capturedOptions!.settings).toEqual({
        availableModels: ["opus", "sonnet"],
@@ -394,7 +397,7 @@ describe("createSession options merging", () => {
        availableModels: ["opus"],
      });

-      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });

      expect(capturedOptions!.settings).toEqual({
        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
@@ -403,7 +406,7 @@ describe("createSession options merging", () => {
    });

    it("does not add settings when env var is not set", async () => {
-      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });

      expect(capturedOptions!.settings).toBeUndefined();
    });
@@ -414,7 +417,7 @@ describe("createSession options merging", () => {
      });

      await agent.newSession({
-        cwd: "/test",
+        cwd: process.cwd(),
        mcpServers: [],
        _meta: {
          claudeCode: {
@@ -438,13 +441,13 @@ describe("createSession options merging", () => {
    it("throws on invalid JSON", async () => {
      process.env.CLAUDE_MODEL_CONFIG = "not-json";

-      await expect(agent.newSession({ cwd: "/test", mcpServers: [] })).rejects.toThrow();
+      await expect(agent.newSession({ cwd: process.cwd(), mcpServers: [] })).rejects.toThrow();
    });
  });

  it("merges user-provided mcpServers with ACP mcpServers", async () => {
    await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
      mcpServers: [
        {
          name: "acp-server",
@@ -473,4 +476,140 @@ describe("createSession options merging", () => {
    // ACP-provided MCP server should also be present
    expect(capturedOptions!.mcpServers).toHaveProperty("acp-server");
  });
+
+  describe("thinking config from MAX_THINKING_TOKENS", () => {
+    let originalMaxThinking: string | undefined;
+
+    beforeEach(() => {
+      originalMaxThinking = process.env.MAX_THINKING_TOKENS;
+      delete process.env.MAX_THINKING_TOKENS;
+    });
+
+    afterEach(() => {
+      if (originalMaxThinking !== undefined) {
+        process.env.MAX_THINKING_TOKENS = originalMaxThinking;
+      } else {
+        delete process.env.MAX_THINKING_TOKENS;
+      }
+    });
+
+    it("leaves thinking unset (SDK default) when env var is absent", async () => {
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toBeUndefined();
+      // The deprecated option must not be set either.
+      expect(capturedOptions!.maxThinkingTokens).toBeUndefined();
+    });
+
+    it("maps 0 to disabled thinking", async () => {
+      process.env.MAX_THINKING_TOKENS = "0";
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toEqual({ type: "disabled" });
+    });
+
+    it("maps a positive value to a fixed thinking budget", async () => {
+      process.env.MAX_THINKING_TOKENS = "12000";
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toEqual({ type: "enabled", budgetTokens: 12000 });
+    });
+
+    it("ignores a non-numeric value", async () => {
+      process.env.MAX_THINKING_TOKENS = "lots";
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toBeUndefined();
+    });
+
+    it("lets a user-provided thinking option override the env default", async () => {
+      process.env.MAX_THINKING_TOKENS = "12000";
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: {
+          claudeCode: {
+            options: {
+              thinking: { type: "adaptive" },
+            },
+          },
+        },
+      });
+      expect(capturedOptions!.thinking).toEqual({ type: "adaptive" });
+    });
+  });
+
+  describe("cwd validation", () => {
+    it("rejects a relative cwd with invalidParams", async () => {
+      await expect(
+        agent.newSession({ cwd: "relative/path", mcpServers: [] }),
+      ).rejects.toMatchObject({ code: RequestError.invalidParams().code });
+    });
+
+    it("rejects a non-existent cwd with invalidParams", async () => {
+      const missing = path.join(os.tmpdir(), "claude-acp-does-not-exist-xyz");
+      await expect(agent.newSession({ cwd: missing, mcpServers: [] })).rejects.toMatchObject({
+        code: RequestError.invalidParams().code,
+      });
+    });
+
+    it("rejects a cwd that points at a file with invalidParams", async () => {
+      const file = path.join(os.tmpdir(), "claude-acp-cwd-is-a-file.txt");
+      fs.writeFileSync(file, "not a directory");
+      try {
+        await expect(agent.newSession({ cwd: file, mcpServers: [] })).rejects.toMatchObject({
+          code: RequestError.invalidParams().code,
+        });
+      } finally {
+        fs.rmSync(file, { force: true });
+      }
+    });
+
+    it("accepts an existing absolute directory", async () => {
+      await expect(agent.newSession({ cwd: process.cwd(), mcpServers: [] })).resolves.toBeDefined();
+    });
+  });
+
+  describe("elicitation", () => {
+    it("keeps AskUserQuestion disabled and omits callbacks without elicitation capability", async () => {
+      await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+      expect(capturedOptions!.onElicitation).toBeUndefined();
+    });
+
+    it("enables AskUserQuestion and wires the elicitation callback when form is supported", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { form: {} } },
+      });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.disallowedTools).not.toContain("AskUserQuestion");
+      expect(typeof capturedOptions!.onElicitation).toBe("function");
+    });
+
+    it("wires callbacks for url-only elicitation but keeps AskUserQuestion disabled", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { url: {} } },
+      });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+      expect(typeof capturedOptions!.onElicitation).toBe("function");
+    });
+
+    it("still merges user-provided disallowedTools when AskUserQuestion is enabled", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { form: {} } },
+      });
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { claudeCode: { options: { disallowedTools: ["WebSearch"] } } },
+      });
+
+      expect(capturedOptions!.disallowedTools).toContain("WebSearch");
+      expect(capturedOptions!.disallowedTools).not.toContain("AskUserQuestion");
+    });
+  });
 });
--- a/src/tests/elicitation.test.ts
+++ b/src/tests/elicitation.test.ts
@@ -0,0 +1,309 @@
+import { describe, it, expect } from "vitest";
+import type { CreateElicitationRequest, CreateElicitationResponse } from "@agentclientprotocol/sdk";
+import type { ElicitationRequest } from "@anthropic-ai/claude-agent-sdk";
+import {
+  applyAskElicitationResponse,
+  askUserQuestionsToCreateRequest,
+  AskUserQuestion,
+  createElicitationResponseToElicitResult,
+  extractAskUserQuestions,
+  mcpElicitationToCreateRequest,
+} from "../elicitation.js";
+
+const SESSION_ID = "session-1";
+
+/**
+ * Build a question matching the SDK's (strict) AskUserQuestion schema while
+ * keeping test sites terse. Option descriptions default to "" (the tool always
+ * provides one); pass a description to exercise the "label — description" title.
+ */
+function mkQuestion(
+  question: string,
+  options: Array<{ label: string; description?: string }>,
+  opts: { header?: string; multiSelect?: boolean } = {},
+): AskUserQuestion {
+  return {
+    question,
+    header: opts.header ?? "",
+    multiSelect: opts.multiSelect ?? false,
+    options: options.map((o) => ({ label: o.label, description: o.description ?? "" })),
+  } as AskUserQuestion;
+}
+
+describe("mcpElicitationToCreateRequest", () => {
+  it("maps a form-mode request, defaulting the schema type to object", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Need your name",
+      mode: "form",
+      requestedSchema: { properties: { name: { type: "string" } } },
+    };
+
+    const result = mcpElicitationToCreateRequest(request, SESSION_ID);
+
+    expect(result).toEqual({
+      mode: "form",
+      sessionId: SESSION_ID,
+      message: "Need your name",
+      requestedSchema: { type: "object", properties: { name: { type: "string" } } },
+    });
+  });
+
+  it("maps a url-mode request and preserves the elicitation id", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Authorize",
+      mode: "url",
+      url: "https://example.com/auth",
+      elicitationId: "el-123",
+    };
+
+    expect(mcpElicitationToCreateRequest(request, SESSION_ID)).toEqual({
+      mode: "url",
+      sessionId: SESSION_ID,
+      message: "Authorize",
+      url: "https://example.com/auth",
+      elicitationId: "el-123",
+    });
+  });
+
+  it("generates an elicitation id when a url request omits one", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Authorize",
+      mode: "url",
+      url: "https://example.com/auth",
+    };
+
+    const result = mcpElicitationToCreateRequest(request, SESSION_ID);
+    expect(result?.mode).toBe("url");
+    expect((result as { elicitationId: string }).elicitationId).toMatch(/.+/);
+  });
+
+  it("returns null for a url request with no url", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Authorize",
+      mode: "url",
+    };
+
+    expect(mcpElicitationToCreateRequest(request, SESSION_ID)).toBeNull();
+  });
+});
+
+describe("createElicitationResponseToElicitResult", () => {
+  it("maps accept with content", () => {
+    const response = { action: "accept", content: { name: "Ada" } } as CreateElicitationResponse;
+    expect(createElicitationResponseToElicitResult(response)).toEqual({
+      action: "accept",
+      content: { name: "Ada" },
+    });
+  });
+
+  it("defaults accept content to an empty object", () => {
+    const response = { action: "accept" } as CreateElicitationResponse;
+    expect(createElicitationResponseToElicitResult(response)).toEqual({
+      action: "accept",
+      content: {},
+    });
+  });
+
+  it("maps decline and cancel", () => {
+    expect(
+      createElicitationResponseToElicitResult({ action: "decline" } as CreateElicitationResponse),
+    ).toEqual({ action: "decline" });
+    expect(
+      createElicitationResponseToElicitResult({ action: "cancel" } as CreateElicitationResponse),
+    ).toEqual({ action: "cancel" });
+  });
+});
+
+describe("extractAskUserQuestions", () => {
+  const question = mkQuestion("Which?", [{ label: "A" }, { label: "B" }]);
+
+  it("reads questions off the tool input", () => {
+    expect(extractAskUserQuestions({ questions: [question] })).toEqual([question]);
+  });
+
+  it("returns null when there are no questions", () => {
+    expect(extractAskUserQuestions({})).toBeNull();
+    expect(extractAskUserQuestions({ questions: [] })).toBeNull();
+  });
+
+  it("filters out malformed questions (missing options, empty options, bad question)", () => {
+    const input = {
+      questions: [
+        question,
+        { question: "missing options" },
+        { options: [] },
+        { options: [], question: "empty" },
+      ],
+    } as unknown as Record<string, unknown>;
+    expect(extractAskUserQuestions(input)).toEqual([question]);
+  });
+
+  it("returns null when every question is filtered out", () => {
+    const input = {
+      questions: [{ question: "no options" }, { options: [{ label: "A" }] }],
+    } as unknown as Record<string, unknown>;
+    expect(extractAskUserQuestions(input)).toBeNull();
+  });
+});
+
+describe("askUserQuestionsToCreateRequest", () => {
+  it("keys a single-select question by a stable id and carries the prompt in message only", () => {
+    const questions = [
+      mkQuestion(
+        "Which library?",
+        [{ label: "date-fns", description: "Lightweight" }, { label: "luxon" }],
+        {
+          header: "Library",
+        },
+      ),
+    ];
+
+    const result = askUserQuestionsToCreateRequest(questions, SESSION_ID, "tool-1");
+
+    expect(result).toMatchObject({
+      mode: "form",
+      sessionId: SESSION_ID,
+      toolCallId: "tool-1",
+      message: "Which library?",
+    });
+    const schema = (result as Extract<CreateElicitationRequest, { mode: "form" }>).requestedSchema;
+    // Nothing is required; the user can pick, type a custom answer, or skip.
+    expect(schema.required).toBeUndefined();
+    // Single question → no duplicated description (prompt is in `message`).
+    expect(schema.properties?.["question_0"]).toEqual({
+      type: "string",
+      title: "Library",
+      description: undefined,
+      oneOf: [
+        { const: "date-fns", title: "date-fns — Lightweight" },
+        { const: "luxon", title: "luxon" },
+      ],
+    });
+    // The full question text is not used as a property key.
+    expect(schema.properties?.["Which library?"]).toBeUndefined();
+  });
+
+  it("includes an optional free-text custom-answer field", () => {
+    const questions = [mkQuestion("Which?", [{ label: "A" }, { label: "B" }])];
+    const schema = (
+      askUserQuestionsToCreateRequest(questions, SESSION_ID, undefined) as Extract<
+        CreateElicitationRequest,
+        { mode: "form" }
+      >
+    ).requestedSchema;
+
+    expect(schema.properties?.["customAnswer"]).toMatchObject({ type: "string", title: "Other" });
+  });
+
+  it("builds an array property for multi-select questions and includes per-field question text", () => {
+    const questions = [
+      mkQuestion("Pick one?", [{ label: "A" }, { label: "B" }]),
+      mkQuestion("Which features?", [{ label: "auth" }, { label: "logging" }], {
+        multiSelect: true,
+      }),
+    ];
+
+    const result = askUserQuestionsToCreateRequest(questions, SESSION_ID, undefined);
+    const schema = (result as Extract<CreateElicitationRequest, { mode: "form" }>).requestedSchema;
+
+    expect(result).not.toHaveProperty("toolCallId");
+    // Multiple questions → generic message, each field carries its own question.
+    expect(result.message).toBe("Please answer the following questions.");
+    expect(schema.properties?.["question_1"]).toEqual({
+      type: "array",
+      title: undefined,
+      description: "Which features?",
+      items: {
+        anyOf: [
+          { const: "auth", title: "auth" },
+          { const: "logging", title: "logging" },
+        ],
+      },
+    });
+  });
+});
+
+describe("applyAskElicitationResponse", () => {
+  const questions = [
+    mkQuestion("Single?", [{ label: "A" }, { label: "B" }]),
+    mkQuestion("Multi?", [{ label: "X" }, { label: "Y" }], { multiSelect: true }),
+  ];
+  const toolInput = { questions, metadata: { source: "test" } };
+
+  it("writes selected labels (keyed by indexed fields) into updatedInput on accept", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "A", question_1: ["X", "Y"] },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: {
+        questions,
+        metadata: { source: "test" },
+        answers: { "Single?": "A", "Multi?": "X, Y" },
+      },
+    });
+  });
+
+  it("maps the free-text custom-answer field to the tool's response", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "A", customAnswer: "something else entirely" },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: {
+        questions,
+        metadata: { source: "test" },
+        answers: { "Single?": "A" },
+        response: "something else entirely",
+      },
+    });
+  });
+
+  it("ignores empty selections and blank custom answers", () => {
+    const response = {
+      action: "accept",
+      content: { question_1: [], customAnswer: "   " },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: { questions, metadata: { source: "test" }, answers: {} },
+    });
+  });
+
+  it("treats decline as answered with no answers", () => {
+    const response = { action: "decline" } as CreateElicitationResponse;
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: { questions, metadata: { source: "test" }, answers: {} },
+    });
+  });
+
+  it("returns cancel on cancel", () => {
+    const response = { action: "cancel" } as CreateElicitationResponse;
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "cancel",
+    });
+  });
+
+  it("omits answers for questions the user left unanswered", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "B" },
+    } as CreateElicitationResponse;
+
+    const result = applyAskElicitationResponse(response, toolInput, questions);
+    expect(result.action).toBe("answered");
+    expect((result as Extract<typeof result, { action: "answered" }>).updatedInput.answers).toEqual(
+      { "Single?": "B" },
+    );
+  });
+});
--- a/src/tests/session-config-options.test.ts
+++ b/src/tests/session-config-options.test.ts
@@ -148,13 +148,13 @@ describe("session config options", () => {

  describe("newSession returns configOptions", () => {
    it("includes configOptions in the response", async () => {
-      const response = await agent.newSession({ cwd: "/test", mcpServers: [] });
+      const response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
      expect(response.configOptions).toBeDefined();
      expect(response.configOptions).toEqual(MOCK_CONFIG_OPTIONS);
    });

    it("includes mode and model config options", async () => {
-      const response = await agent.newSession({ cwd: "/test", mcpServers: [] });
+      const response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
      const modeOption = response.configOptions?.find((o) => o.id === "mode");
      const modelOption = response.configOptions?.find((o) => o.id === "model");
      expect(modeOption).toBeDefined();
@@ -173,7 +173,7 @@ describe("session config options", () => {
      (agent as unknown as { loadSession: typeof loadSessionSpy }).loadSession = loadSessionSpy;

      const response = await agent.loadSession({
-        cwd: "/test",
+        cwd: process.cwd(),
        sessionId: SESSION_ID,
        mcpServers: [],
      });
@@ -377,33 +377,30 @@ describe("session config options", () => {
    });
  });

-  describe("unstable_setSessionModel sends config_option_update", () => {
+  describe("setSessionConfigOption(model) returns updated configOptions", () => {
    beforeEach(() => {
      populateSession();
    });

-    it("sends config_option_update when model is changed via setSessionModel", async () => {
-      await agent.unstable_setSessionModel({
+    it("returns configOptions with the new model when changed", async () => {
+      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
      });

-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      expect(configUpdate?.update).toMatchObject({
-        sessionUpdate: "config_option_update",
-        configOptions: expect.arrayContaining([
+      expect(response.configOptions).toEqual(
+        expect.arrayContaining([
          expect.objectContaining({ id: "model", currentValue: "claude-sonnet-4-6" }),
        ]),
-      });
+      );
    });

    it("updates stored configOptions currentValue when model changes", async () => {
-      await agent.unstable_setSessionModel({
+      await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
      });

      const session = (
@@ -415,7 +412,7 @@ describe("session config options", () => {
      expect(modelOption?.currentValue).toBe("claude-sonnet-4-6");
    });

-    it("includes updated effort in config_option_update when model drops effort support", async () => {
+    it("drops effort from returned configOptions when model drops effort support", async () => {
      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
      session.modelInfos = [
        {
@@ -433,23 +430,18 @@ describe("session config options", () => {
        },
      ];

-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
      });

-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      const effortOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "effort",
-      );
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
      expect(effortOption).toBeUndefined();
      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
    });

-    it("clamps effort in config_option_update when new model has different supported levels", async () => {
+    it("clamps effort in returned configOptions when new model has different supported levels", async () => {
      // Set current effort to "max" which the new model won't support
      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
@@ -472,39 +464,31 @@ describe("session config options", () => {
        },
      ];

-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
      });

-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      const effortOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "effort",
-      );
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
      expect(effortOption).toBeDefined();
-      expect(effortOption.currentValue).toBe("default");
+      expect(effortOption?.currentValue).toBe("default");
      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
    });

-    it("preserves effort in config_option_update when new model supports same level", async () => {
+    it("preserves effort in returned configOptions when new model supports same level", async () => {
      // Set effort to "low" first
      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
      if (effortOpt) effortOpt.currentValue = "low";

-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
      });

-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      const effortOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "effort",
-      );
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
      expect(effortOption?.currentValue).toBe("low");
      // Effort didn't change, so applyFlagSettings should NOT be called
      expect(applyFlagSettingsSpy).not.toHaveBeenCalled();
@@ -821,10 +805,11 @@ describe("session config options", () => {
      expect(session.configOptions.find((o) => o.id === "mode")?.currentValue).toBe("plan");
    });

-    it("setSessionModel also syncs configOptions", async () => {
-      await agent.unstable_setSessionModel({
+    it("setSessionConfigOption(model) also syncs configOptions", async () => {
+      await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
      });

      const session = (
@@ -947,58 +932,21 @@ describe("session config options", () => {
    it("drops `auto` from available modes when switching to Haiku", async () => {
      setupHaikuOpusSession("default");

-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-haiku-4-5",
+        configId: "model",
+        value: "claude-haiku-4-5",
      });

-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      const modeOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
      expect(modeOption).toBeDefined();
-      const modeValues = modeOption.options.map((o: any) => o.value);
+      const modeValues = (modeOption as any).options.map((o: any) => o.value);
      expect(modeValues).not.toContain("auto");
      expect(modeValues).toEqual(
        expect.arrayContaining(["default", "acceptEdits", "plan", "dontAsk"]),
      );
    });

-    it("clamps to `default` and emits current_mode_update when Opus(auto) → Haiku", async () => {
-      setupHaikuOpusSession("auto");
-
-      await agent.unstable_setSessionModel({
-        sessionId: SESSION_ID,
-        modelId: "claude-haiku-4-5",
-      });
-
-      // SDK was synced to "default".
-      expect(setPermissionModeSpy).toHaveBeenCalledWith("default");
-
-      // current_mode_update was emitted before config_option_update so a
-      // client applying notifications in order observes the mode change
-      // before re-rendering the config-option list.
-      const modeUpdateIdx = sessionUpdates.findIndex(
-        (n) => n.update.sessionUpdate === "current_mode_update",
-      );
-      const configUpdateIdx = sessionUpdates.findIndex(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(modeUpdateIdx).toBeGreaterThanOrEqual(0);
-      expect(configUpdateIdx).toBeGreaterThanOrEqual(0);
-      expect(modeUpdateIdx).toBeLessThan(configUpdateIdx);
-      expect((sessionUpdates[modeUpdateIdx].update as any).currentModeId).toBe("default");
-
-      // configOptions reflect the clamped mode.
-      const modeOption = (sessionUpdates[configUpdateIdx].update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
-      expect(modeOption.currentValue).toBe("default");
-    });
-
    it("re-adds `auto` when switching from Haiku back to Opus", async () => {
      const session = setupHaikuOpusSession("default");
      // Pretend Haiku is the current model with no `auto`.
@@ -1013,19 +961,15 @@ describe("session config options", () => {
        description: m.description,
      }));

-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-opus-4-5",
+        configId: "model",
+        value: "claude-opus-4-5",
      });

-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      const modeOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
-      const modeValues = modeOption.options.map((o: any) => o.value);
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect(modeOption).toBeDefined();
+      const modeValues = (modeOption as any).options.map((o: any) => o.value);
      expect(modeValues).toContain("auto");

      // The current mode ("default") is still valid on Opus, so no
@@ -1039,9 +983,10 @@ describe("session config options", () => {
    it("preserves the current mode when it remains valid after a model switch", async () => {
      setupHaikuOpusSession("plan");

-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
-        modelId: "claude-haiku-4-5",
+        configId: "model",
+        value: "claude-haiku-4-5",
      });

      // `plan` is in availableModes for both Opus and Haiku, so no clamp.
@@ -1052,20 +997,15 @@ describe("session config options", () => {
      );
      expect(modeUpdates).toHaveLength(0);

-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      const modeOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
-      expect(modeOption.currentValue).toBe("plan");
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect((modeOption as any).currentValue).toBe("plan");
    });

    it("clamps mode and emits current_mode_update via setSessionConfigOption(model)", async () => {
-      // Mirrors the unstable_setSessionModel(auto → Haiku) test, but goes
-      // through the request/response API. The `current_mode_update` side
-      // effect must still fire so clients learn about the clamp regardless of
-      // which entry point triggered the model switch.
+      // Switching Opus(auto) → Haiku clamps the mode to "default". The
+      // `current_mode_update` side effect must fire so clients learn about the
+      // clamp even though the request/response API returns the new
+      // configOptions rather than emitting a config_option_update.
      setupHaikuOpusSession("auto");

      const response = await agent.setSessionConfigOption({
--- a/src/tests/tools.test.ts
+++ b/src/tests/tools.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, beforeEach } from "vitest";
 import { AgentSideConnection, ClientCapabilities } from "@agentclientprotocol/sdk";
 import { ImageBlockParam, ToolResultBlockParam } from "@anthropic-ai/sdk/resources";
 import {
@@ -673,14 +673,19 @@ describe("Bash terminal output", () => {
  });

  describe("toAcpNotifications with clientCapabilities", () => {
-    const toolUseCache: ToolUseCache = {
-      toolu_bash: {
-        type: "tool_use",
-        id: "toolu_bash",
-        name: "Bash",
-        input: { command: "ls -la" },
-      },
-    };
+    // Reset before each test: toAcpNotifications prunes the cache entry once it
+    // maps the tool_result, so a shared object would be empty by the 2nd test.
+    let toolUseCache: ToolUseCache;
+    beforeEach(() => {
+      toolUseCache = {
+        toolu_bash: {
+          type: "tool_use",
+          id: "toolu_bash",
+          name: "Bash",
+          input: { command: "ls -la" },
+        },
+      };
+    });

    const bashResult: BetaBashCodeExecutionResultBlock = {
      type: "bash_code_execution_result",
@@ -792,11 +797,21 @@ describe("Bash terminal output", () => {
        { clientCapabilities: { _meta: { terminal_output: true } } },
      );

+      // Fresh cache: the withSupport call above already consumed the entry,
+      // since toAcpNotifications prunes the tool_use once it maps the result.
+      const toolUseCacheWithoutSupport: ToolUseCache = {
+        toolu_bash: {
+          type: "tool_use",
+          id: "toolu_bash",
+          name: "Bash",
+          input: { command: "ls -la" },
+        },
+      };
      const withoutSupport = toAcpNotifications(
        [toolResult],
        "assistant",
        "test-session",
-        toolUseCache,
+        toolUseCacheWithoutSupport,
        mockClient,
        mockLogger,
      );
@@ -848,6 +863,31 @@ describe("Bash terminal output", () => {
    });
  });

+  describe("toolUseCache pruning", () => {
+    it("retains the tool_use entry until its result, then prunes it", () => {
+      const toolUseCache: ToolUseCache = {};
+      const toolUse = {
+        type: "tool_use" as const,
+        id: "toolu_read",
+        name: "Read",
+        input: { file_path: "/tmp/x.txt" },
+      };
+
+      // tool_use is cached and kept (the matching result hasn't arrived yet).
+      toAcpNotifications([toolUse], "assistant", "s", toolUseCache, mockClient, mockLogger);
+      expect(toolUseCache.toolu_read).toBeDefined();
+
+      // tool_result resolves it, so the entry is pruned to bound memory.
+      const toolResult: ToolResultBlockParam = {
+        type: "tool_result",
+        tool_use_id: "toolu_read",
+        content: [{ type: "text", text: "hello" }],
+      };
+      toAcpNotifications([toolResult], "assistant", "s", toolUseCache, mockClient, mockLogger);
+      expect(toolUseCache.toolu_read).toBeUndefined();
+    });
+  });
+
  describe("post-tool-use hook sends diff content for Edit tool", () => {
    it("should include content and locations from structuredPatch in hook update", async () => {
      const toolUseCache: ToolUseCache = {};
--- a/src/tools.ts
+++ b/src/tools.ts
@@ -8,6 +8,7 @@ import {
 import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
 import {
  AgentInput,
+  AskUserQuestionInput,
  BashInput,
  FileEditInput,
  FileReadInput,
@@ -415,6 +416,24 @@ export function toolInfoFromToolUse(
      };
    }

+    case "AskUserQuestion": {
+      const input = toolUse.input as Partial<AskUserQuestionInput> | undefined;
+      const questions = Array.isArray(input?.questions) ? input.questions : [];
+      return {
+        title:
+          questions.length === 1 && questions[0]?.question
+            ? questions[0].question
+            : "Asking for your input",
+        kind: "other",
+        content: questions
+          .filter((q) => typeof q?.question === "string")
+          .map((q) => ({
+            type: "content" as const,
+            content: { type: "text" as const, text: q.question },
+          })),
+      };
+    }
+
    case "Other": {
      const input = toolUse.input;
      let output;