Prep 0.18.0 release (#331)

- **Fix sending markdown content that replaces terminal content**
- **Make sure to always updated content to be safe**

.github/workflows/publish.yml

@@ -33,4 +33,4 @@ jobs:
         id: create_release
         uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090
         with:
-          draft: true
+          generate_release_notes: true

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 dist
 .DS_Store
+.claude/*.local.*
+CLAUDE.local.md

CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## 0.18.0
+
+- Switch over to built-in Claude tools. We no longer replicate specific ACP tools and just rely on sending updates based on Claude's internal tools. This means it won't use client capabilities for files or terminals, but also means there will be less difference and hopefully issues arising from the differences in behavior.
+- Support ACP session config options: https://agentclientprotocol.com/protocol/session-config-options
+- Fix for image output from tool calls.
+
+## 0.17.1
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.45 to add access to Sonnet 4.6
+
+## 0.17.0
+
+Rename from `@zed-industries/claude-code-acp` to `@zed-industries/claude-agent-acp` to align with the current [branding guidelines](https://platform.claude.com/docs/en/agent-sdk/overview#branding-guidelines)
+
+## 0.16.2
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.44
+- fix: Replace all non-alphanumeric characters for session loading in encodeProjectPath (#307)
+- don't include /login slash command in login command (#315)
+
+## 0.16.1
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.38
+- Fix incorrect paths for session/list
+- Fix available commands after loading a session
+- Make loading session more permissive for finding events
+- Fix overriding user-provided disallowedTools
+
+## 0.16.0
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.34
+- Experimental support for session loading
+
+## 0.15.0
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.32 (adds support for Opus 4.6 and 1M context Opus)
+
+## 0.14.0
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.29
+- Update to using the recommended `CLAUDE_CONFIG_DIR` env variable for setting where config files are kept
+- Support /context command
+- Fix incorrect context type mapping for tool calls
+- Fix glob metching for file permissions on Windows
+- Support the `IS_SANDBOX` env var for supporting bypass permissions in root mode
+- Fix missing notification for entering plan mode
+- Experimental unstable support for listing sessions
+
+## 0.13.2
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.22
+- Fix: return content from ACP write tool to help with issues with alternate providers.
+
+## 0.13.1
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.7
+- Add TypeScript declaration files for library users
+- Fixed error handling in custom ACP focused MCP tools
+
+## 0.13.0
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.6
+- Update to @agentclientprotocol/sdk@0.13.0
+
+## 0.12.6
+
+- Fix model selection
+
+## 0.12.5
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.70
+- Unstable implementation of resuming sessions
+
+## 0.12.4
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.67
+- Better respect permissions specified in settings files
+- Unstable implementation of forking
+
+## 0.12.3
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.65
+- Update to @agentclientprotocol/sdk@0.9.0
+- Allow agent to write plans and todos to its config directory
+- Fix experimental resume ids
+
+## 0.12.2
+
+- Fix duplicate tool use IDs error
+
+## 0.12.1
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.61
+- Update to @agentclientprotocol/sdk@0.8.0
+
+## 0.12.0
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.59
+  - Brings Opus to Claude Pro plans
+  - Support "Don't Ask" profile
+- Unify ACP + Claude Code session ids
+
+## 0.11.0
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.57
+- Removed dependency on @anthropic-ai/claude-code since this is no longer needed
+
+## 0.10.10
+
+- Update to @agentclientprotocol/sdk@0.7.0
+
+## 0.10.9
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.55
+- Allow defining a custom logger when used as a library
+- Allow specifying custom options when used as a library
+- Add `CLAUDECODE=1` to terminal invocations to match default Claude Code behavior
+
 ## 0.10.8
 
 - Update to @anthropic-ai/claude-agent-sdk@v0.1.51 (adds support for Opus 4.5)

README.md

@@ -1,10 +1,10 @@
-# ACP adapter for Claude Code
+# ACP adapter for the Claude Agent SDK
 
-[![npm](https://img.shields.io/npm/v/%40zed-industries%2Fclaude-code-acp)](https://www.npmjs.com/package/@zed-industries/claude-code-acp)
+[![npm](https://img.shields.io/npm/v/%40zed-industries%2Fclaude-agent-acp)](https://www.npmjs.com/package/@zed-industries/claude-agent-acp)
 
-Use [Claude Code](https://www.anthropic.com/claude-code) from [ACP-compatible](https://agentclientprotocol.com) clients such as [Zed](https://zed.dev)!
+Use [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview#branding-guidelines) from [ACP-compatible](https://agentclientprotocol.com) clients such as [Zed](https://zed.dev)!
 
-This tool implements an ACP agent by using the official [Claude Code SDK](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview), supporting:
+This tool implements an ACP agent by using the official [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), supporting:
 
 - Context @-mentions
 - Images
@@ -24,7 +24,7 @@ Learn more about the [Agent Client Protocol](https://agentclientprotocol.com/).
 
 The latest version of Zed can already use this adapter out of the box.
 
-To use Claude Code, open the Agent Panel and click "New Claude Code Thread" from the `+` button menu in the top-right:
+To use Claude Agent, open the Agent Panel and click "New Claude Agent Thread" from the `+` button menu in the top-right:
 
 https://github.com/user-attachments/assets/ddce66c7-79ac-47a3-ad59-4a6a3ca74903
 
@@ -32,26 +32,20 @@ Read the docs on [External Agent](https://zed.dev/docs/ai/external-agents) suppo
 
 ### Other clients
 
-- Emacs via [agent-shell.el](https://github.com/xenodium/agent-shell)
-- [marimo notebook](https://github.com/marimo-team/marimo)
-- Neovim
-  - via [CodeCompanion.nvim](https://codecompanion.olimorris.dev/configuration/adapters#setup-claude-code-via-acp)
-  - via [yetone/avante.nvim](https://github.com/yetone/avante.nvim)
-
-[Submit a PR](https://github.com/zed-industries/claude-code-acp/pulls) to add yours!
+Or try it with any of the other [ACP compatible clients](https://agentclientprotocol.com/overview/clients)!
 
 #### Installation
 
 Install the adapter from `npm`:
 
 ```bash
-npm install @zed-industries/claude-code-acp
+npm install -g @zed-industries/claude-agent-acp
 ```
 
-You can then use `claude-code-acp` as a regular ACP agent:
+You can then use `claude-agent-acp` as a regular ACP agent:
 
 ```
-ANTHROPIC_API_KEY=sk-... claude-code-acp
+ANTHROPIC_API_KEY=sk-... claude-agent-acp
 ```
 
 ## License

package.json

@@ -1,17 +1,26 @@
 {
-  "name": "@zed-industries/claude-code-acp",
+  "name": "@zed-industries/claude-agent-acp",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.10.8",
-  "description": "An ACP-compatible coding agent powered by the Claude Code SDK (TypeScript)",
+  "version": "0.18.0",
+  "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
   "bin": {
-    "claude-code-acp": "./dist/index.js"
+    "claude-agent-acp": "dist/index.js"
   },
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./*": "./*"
+  },
   "files": [
     "dist/",
+    "!dist/tests/",
     "README.md",
     "LICENSE",
     "package.json"
@@ -40,37 +49,32 @@
     "sdk",
     "code"
   ],
-  "homepage": "https://github.com/zed-industries/claude-code-acp#readme",
+  "homepage": "https://github.com/zed-industries/claude-agent-acp#readme",
   "bugs": {
-    "url": "https://github.com/zed-industries/claude-code-acp/issues"
+    "url": "https://github.com/zed-industries/claude-agent-acp/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zed-industries/claude-code-acp.git"
+    "url": "git+https://github.com/zed-industries/claude-agent-acp.git"
   },
   "author": "Zed Industries",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.5.1",
-    "@anthropic-ai/claude-agent-sdk": "0.1.51",
-    "@anthropic-ai/claude-code": "2.0.51",
-    "@modelcontextprotocol/sdk": "1.22.0",
-    "diff": "8.0.2",
-    "uuid": "13.0.0"
+    "@agentclientprotocol/sdk": "0.14.1",
+    "@anthropic-ai/claude-agent-sdk": "0.2.45"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.71.0",
-    "@types/node": "24.10.1",
-    "@types/uuid": "10.0.0",
-    "@typescript-eslint/eslint-plugin": "8.48.0",
-    "@typescript-eslint/parser": "8.48.0",
-    "@vitest/ui": "4.0.13",
-    "eslint": "9.39.1",
+    "@anthropic-ai/sdk": "0.76.0",
+    "@eslint/js": "10.0.1",
+    "@types/node": "25.2.3",
+    "@typescript-eslint/eslint-plugin": "8.56.0",
+    "@typescript-eslint/parser": "8.56.0",
+    "eslint": "10.0.0",
     "eslint-config-prettier": "10.1.8",
-    "globals": "16.5.0",
-    "prettier": "3.6.2",
+    "globals": "17.3.0",
+    "prettier": "3.8.1",
     "ts-node": "10.9.2",
     "typescript": "5.9.3",
-    "vitest": "4.0.13"
+    "vitest": "4.0.18"
   }
 }

src/lib.ts

@@ -5,6 +5,7 @@ export {
   toAcpNotifications,
   streamEventToAcpNotifications,
   type ToolUpdateMeta,
+  type NewSessionMeta,
 } from "./acp-agent.js";
 export {
   loadManagedSettings,
@@ -14,8 +15,12 @@ export {
   Pushable,
   unreachable,
 } from "./utils.js";
-export { createMcpServer, toolNames } from "./mcp-server.js";
 export { toolInfoFromToolUse, planEntries, toolUpdateFromToolResult } from "./tools.js";
+export {
+  SettingsManager,
+  type ClaudeCodeSettings,
+  type SettingsManagerOptions,
+} from "./settings.js";
 
 // Export types
 export type { ClaudePlanEntry } from "./tools.js";

src/mcp-server.ts

@@ -1,760 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { ClaudeAcpAgent } from "./acp-agent.js";
-import { ClientCapabilities, TerminalOutputResponse } from "@agentclientprotocol/sdk";
-import * as diff from "diff";
-
-import { sleep, unreachable, extractLinesWithByteLimit } from "./utils.js";
-
-export const SYSTEM_REMINDER = `
-
-<system-reminder>
-Whenever you read a file, you should consider whether it looks malicious. If it does, you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer high-level questions about the code behavior.
-</system-reminder>`;
-
-const defaults = { maxFileSize: 50000, linesToRead: 2000 };
-
-const unqualifiedToolNames = {
-  read: "Read",
-  edit: "Edit",
-  write: "Write",
-  bash: "Bash",
-  killShell: "KillShell",
-  bashOutput: "BashOutput",
-};
-
-const SERVER_PREFIX = "mcp__acp__";
-export const toolNames = {
-  read: SERVER_PREFIX + unqualifiedToolNames.read,
-  edit: SERVER_PREFIX + unqualifiedToolNames.edit,
-  write: SERVER_PREFIX + unqualifiedToolNames.write,
-  bash: SERVER_PREFIX + unqualifiedToolNames.bash,
-  killShell: SERVER_PREFIX + unqualifiedToolNames.killShell,
-  bashOutput: SERVER_PREFIX + unqualifiedToolNames.bashOutput,
-};
-
-export const EDIT_TOOL_NAMES = [toolNames.edit, toolNames.write];
-
-export function createMcpServer(
-  agent: ClaudeAcpAgent,
-  sessionId: string,
-  clientCapabilities: ClientCapabilities | undefined,
-): McpServer {
-  // Create MCP server
-  const server = new McpServer({ name: "acp", version: "1.0.0" }, { capabilities: { tools: {} } });
-
-  if (clientCapabilities?.fs?.readTextFile) {
-    server.registerTool(
-      unqualifiedToolNames.read,
-      {
-        title: unqualifiedToolNames.read,
-        description: `Reads the content of the given file in the project.
-
-In sessions with ${toolNames.read} always use it instead of Read as it contains the most up-to-date contents.
-
-Reads a file from the local filesystem. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
-
-Usage:
-- The file_path parameter must be an absolute path, not a relative path
-- By default, it reads up to ${defaults.linesToRead} lines starting from the beginning of the file
-- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
-- Any files larger than ${defaults.maxFileSize} bytes will be truncated
-- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
-- This tool can only read files, not directories. To read a directory, use an ls command via the ${toolNames.bash} tool.
-- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.`,
-        inputSchema: {
-          file_path: z.string().describe("The absolute path to the file to read"),
-          offset: z
-            .number()
-            .optional()
-            .default(1)
-            .describe(
-              "The line number to start reading from. Only provide if the file is too large to read at once",
-            ),
-          limit: z
-            .number()
-            .optional()
-            .default(defaults.linesToRead)
-            .describe(
-              `The number of lines to read. Only provide if the file is too large to read at once.`,
-            ),
-        },
-        annotations: {
-          title: "Read file",
-          readOnlyHint: true,
-          destructiveHint: false,
-          openWorldHint: false,
-          idempotentHint: false,
-        },
-      },
-      async (input) => {
-        try {
-          const session = agent.sessions[sessionId];
-          if (!session) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: "The user has left the building",
-                },
-              ],
-            };
-          }
-
-          const readResponse = await agent.readTextFile({
-            sessionId,
-            path: input.file_path,
-            line: input.offset,
-            limit: input.limit,
-          });
-
-          if (typeof readResponse?.content !== "string") {
-            throw new Error(`No file contents for ${input.file_path}.`);
-          }
-
-          // Extract lines with byte limit enforcement
-          const result = extractLinesWithByteLimit(readResponse.content, defaults.maxFileSize);
-
-          // Construct informative message about what was read
-          let readInfo = "";
-          if (input.offset > 1 || result.wasLimited) {
-            readInfo = "\n\n<file-read-info>";
-
-            if (result.wasLimited) {
-              readInfo += `Read ${result.linesRead} lines (hit 50KB limit). `;
-            } else {
-              readInfo += `Read lines ${input.offset}-${result.linesRead}. `;
-            }
-
-            if (result.wasLimited) {
-              readInfo += `Continue with offset=${result.linesRead}.`;
-            }
-
-            readInfo += "</file-read-info>";
-          }
-
-          return {
-            content: [
-              {
-                type: "text",
-                text: result.content + readInfo + SYSTEM_REMINDER,
-              },
-            ],
-          };
-        } catch (error: any) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Reading file failed: " + error.message,
-              },
-            ],
-          };
-        }
-      },
-    );
-  }
-
-  if (clientCapabilities?.fs?.writeTextFile) {
-    server.registerTool(
-      unqualifiedToolNames.write,
-      {
-        title: unqualifiedToolNames.write,
-        description: `Writes a file to the local filesystem..
-
-In sessions with ${toolNames.write} always use it instead of Write as it will
-allow the user to conveniently review changes.
-
-Usage:
-- This tool will overwrite the existing file if there is one at the provided path.
-- If this is an existing file, you MUST use the ${toolNames.read} tool first to read the file's contents. This tool will fail if you did not read the file first.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`,
-        inputSchema: {
-          file_path: z
-            .string()
-            .describe("The absolute path to the file to write (must be absolute, not relative)"),
-          content: z.string().describe("The content to write to the file"),
-        },
-        annotations: {
-          title: "Write file",
-          readOnlyHint: false,
-          destructiveHint: false,
-          openWorldHint: false,
-          idempotentHint: false,
-        },
-      },
-      async (input) => {
-        try {
-          const session = agent.sessions[sessionId];
-          if (!session) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: "The user has left the building",
-                },
-              ],
-            };
-          }
-          await agent.writeTextFile({
-            sessionId,
-            path: input.file_path,
-            content: input.content,
-          });
-
-          return {
-            content: [],
-          };
-        } catch (error: any) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Writing file failed: " + error.message,
-              },
-            ],
-          };
-        }
-      },
-    );
-
-    server.registerTool(
-      unqualifiedToolNames.edit,
-      {
-        title: unqualifiedToolNames.edit,
-        description: `Performs exact string replacements in files.
-
-In sessions with ${toolNames.edit} always use it instead of Edit as it will
-allow the user to conveniently review changes.
-
-Usage:
-- You must use your \`${toolNames.read}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
-- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`.
-- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`,
-        inputSchema: {
-          file_path: z.string().describe("The absolute path to the file to modify"),
-          old_string: z.string().describe("The text to replace"),
-          new_string: z
-            .string()
-            .describe("The text to replace it with (must be different from old_string)"),
-          replace_all: z
-            .boolean()
-            .default(false)
-            .optional()
-            .describe("Replace all occurences of old_string (default false)"),
-        },
-        annotations: {
-          title: "Edit file",
-          readOnlyHint: false,
-          destructiveHint: false,
-          openWorldHint: false,
-          idempotentHint: false,
-        },
-      },
-      async (input) => {
-        try {
-          const session = agent.sessions[sessionId];
-          if (!session) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: "The user has left the building",
-                },
-              ],
-            };
-          }
-
-          const readResponse = await agent.readTextFile({
-            sessionId,
-            path: input.file_path,
-          });
-
-          if (typeof readResponse?.content !== "string") {
-            throw new Error(`No file contents for ${input.file_path}.`);
-          }
-
-          const { newContent } = replaceAndCalculateLocation(readResponse.content, [
-            {
-              oldText: input.old_string,
-              newText: input.new_string,
-              replaceAll: input.replace_all,
-            },
-          ]);
-
-          const patch = diff.createPatch(input.file_path, readResponse.content, newContent);
-
-          await agent.writeTextFile({
-            sessionId,
-            path: input.file_path,
-            content: newContent,
-          });
-
-          return {
-            content: [
-              {
-                type: "text",
-                text: patch,
-              },
-            ],
-          };
-        } catch (error: any) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Editing file failed: " + (error?.message ?? String(error)),
-              },
-            ],
-          };
-        }
-      },
-    );
-  }
-
-  if (agent.clientCapabilities?.terminal) {
-    server.registerTool(
-      unqualifiedToolNames.bash,
-      {
-        title: unqualifiedToolNames.bash,
-        description: `Executes a bash command
-
-In sessions with ${toolNames.bash} always use it instead of Bash`,
-        inputSchema: {
-          command: z.string().describe("The command to execute"),
-          timeout: z
-            .number()
-            .default(2 * 60 * 1000)
-            .describe(`Optional timeout in milliseconds (max ${2 * 60 * 1000})`),
-          description: z.string().optional()
-            .describe(`Clear, concise description of what this command does in 5-10 words, in active voice. Examples:
-Input: ls
-Output: List files in current directory
-
-Input: git status
-Output: Show working tree status
-
-Input: npm install
-Output: Install package dependencies
-
-Input: mkdir foo
-Output: Create directory 'foo'`),
-          run_in_background: z
-            .boolean()
-            .default(false)
-            .describe(
-              `Set to true to run this command in the background. The tool returns an \`id\` that can be used with the \`${toolNames.bashOutput}\` tool to retrieve the current output, or the \`${toolNames.killShell}\` tool to stop it early.`,
-            ),
-        },
-      },
-      async (input, extra) => {
-        const session = agent.sessions[sessionId];
-        if (!session) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "The user has left the building",
-              },
-            ],
-          };
-        }
-
-        const toolCallId = extra._meta?.["claudecode/toolUseId"];
-
-        if (typeof toolCallId !== "string") {
-          throw new Error("No tool call ID found");
-        }
-
-        if (!agent.clientCapabilities?.terminal || !agent.client.createTerminal) {
-          throw new Error("unreachable");
-        }
-
-        const handle = await agent.client.createTerminal({
-          command: input.command,
-          sessionId,
-          outputByteLimit: 32_000,
-        });
-
-        await agent.client.sessionUpdate({
-          sessionId,
-          update: {
-            sessionUpdate: "tool_call_update",
-            toolCallId,
-            status: "in_progress",
-            title: input.description,
-            content: [{ type: "terminal", terminalId: handle.id }],
-          },
-        });
-
-        const abortPromise = new Promise((resolve) => {
-          if (extra.signal.aborted) {
-            resolve(null);
-          } else {
-            extra.signal.addEventListener("abort", () => {
-              resolve(null);
-            });
-          }
-        });
-
-        const statusPromise = Promise.race([
-          handle.waitForExit().then((exitStatus) => ({ status: "exited" as const, exitStatus })),
-          abortPromise.then(() => ({ status: "aborted" as const, exitStatus: null })),
-          sleep(input.timeout).then(async () => {
-            if (agent.backgroundTerminals[handle.id]?.status === "started") {
-              await handle.kill();
-            }
-            return { status: "timedOut" as const, exitStatus: null };
-          }),
-        ]);
-
-        if (input.run_in_background) {
-          agent.backgroundTerminals[handle.id] = {
-            handle,
-            lastOutput: null,
-            status: "started",
-          };
-
-          statusPromise.then(async ({ status, exitStatus }) => {
-            const bgTerm = agent.backgroundTerminals[handle.id];
-
-            if (bgTerm.status !== "started") {
-              return;
-            }
-
-            const currentOutput = await handle.currentOutput();
-
-            agent.backgroundTerminals[handle.id] = {
-              status,
-              pendingOutput: {
-                ...currentOutput,
-                output: stripCommonPrefix(bgTerm.lastOutput?.output ?? "", currentOutput.output),
-                exitStatus: exitStatus ?? currentOutput.exitStatus,
-              },
-            };
-
-            return handle.release();
-          });
-
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Command started in background with id: ${handle.id}`,
-              },
-            ],
-          };
-        }
-
-        await using terminal = handle;
-
-        const { status } = await statusPromise;
-
-        if (status === "aborted") {
-          return {
-            content: [{ type: "text", text: "Tool cancelled by user" }],
-          };
-        }
-
-        const output = await terminal.currentOutput();
-
-        return {
-          content: [{ type: "text", text: toolCommandOutput(status, output) }],
-        };
-      },
-    );
-
-    server.registerTool(
-      unqualifiedToolNames.bashOutput,
-      {
-        title: unqualifiedToolNames.bashOutput,
-        description: `- Retrieves output from a running or completed background bash shell
-- Takes a shell_id parameter identifying the shell
-- Always returns only new output since the last check
-- Returns stdout and stderr output along with shell status
-- Use this tool when you need to monitor or check the output of a long-running shell
-
-In sessions with ${toolNames.bashOutput} always use it instead of BashOutput.`,
-        inputSchema: {
-          shell_id: z
-            .string()
-            .describe(`The id of the background bash command as returned by \`${toolNames.bash}\``),
-        },
-      },
-      async (input) => {
-        const bgTerm = agent.backgroundTerminals[input.shell_id];
-
-        if (!bgTerm) {
-          throw new Error(`Unknown shell ${input.shell_id}`);
-        }
-
-        if (bgTerm.status === "started") {
-          const newOutput = await bgTerm.handle.currentOutput();
-          const strippedOutput = stripCommonPrefix(
-            bgTerm.lastOutput?.output ?? "",
-            newOutput.output,
-          );
-          bgTerm.lastOutput = newOutput;
-
-          return {
-            content: [
-              {
-                type: "text",
-                text: toolCommandOutput(bgTerm.status, {
-                  ...newOutput,
-                  output: strippedOutput,
-                }),
-              },
-            ],
-          };
-        } else {
-          return {
-            content: [
-              {
-                type: "text",
-                text: toolCommandOutput(bgTerm.status, bgTerm.pendingOutput),
-              },
-            ],
-          };
-        }
-      },
-    );
-
-    server.registerTool(
-      unqualifiedToolNames.killShell,
-      {
-        title: unqualifiedToolNames.killShell,
-        description: `- Kills a running background bash shell by its ID
-- Takes a shell_id parameter identifying the shell to kill
-- Returns a success or failure status
-- Use this tool when you need to terminate a long-running shell
-
-In sessions with ${toolNames.killShell} always use it instead of KillShell.`,
-        inputSchema: {
-          shell_id: z
-            .string()
-            .describe(`The id of the background bash command as returned by \`${toolNames.bash}\``),
-        },
-      },
-      async (input) => {
-        const bgTerm = agent.backgroundTerminals[input.shell_id];
-
-        if (!bgTerm) {
-          throw new Error(`Unknown shell ${input.shell_id}`);
-        }
-
-        switch (bgTerm.status) {
-          case "started": {
-            await bgTerm.handle.kill();
-            const currentOutput = await bgTerm.handle.currentOutput();
-            agent.backgroundTerminals[bgTerm.handle.id] = {
-              status: "killed",
-              pendingOutput: {
-                ...currentOutput,
-                output: stripCommonPrefix(bgTerm.lastOutput?.output ?? "", currentOutput.output),
-              },
-            };
-            await bgTerm.handle.release();
-
-            return {
-              content: [{ type: "text", text: "Command killed successfully." }],
-            };
-          }
-          case "aborted":
-            return {
-              content: [{ type: "text", text: "Command aborted by user." }],
-            };
-          case "exited":
-            return {
-              content: [{ type: "text", text: "Command had already exited." }],
-            };
-          case "killed":
-            return {
-              content: [{ type: "text", text: "Command was already killed." }],
-            };
-          case "timedOut":
-            return {
-              content: [{ type: "text", text: "Command killed by timeout." }],
-            };
-          default: {
-            unreachable(bgTerm);
-            throw new Error("Unexpected background terminal status");
-          }
-        }
-      },
-    );
-  }
-
-  return server;
-}
-
-function stripCommonPrefix(a: string, b: string): string {
-  let i = 0;
-  while (i < a.length && i < b.length && a[i] === b[i]) {
-    i++;
-  }
-  return b.slice(i);
-}
-
-function toolCommandOutput(
-  status: "started" | "aborted" | "exited" | "killed" | "timedOut",
-  output: TerminalOutputResponse,
-): string {
-  const { exitStatus, output: commandOutput, truncated } = output;
-
-  let toolOutput = "";
-
-  switch (status) {
-    case "started":
-    case "exited": {
-      if (exitStatus && (exitStatus.exitCode ?? null) === null) {
-        toolOutput += `Interrupted by the user. `;
-      }
-      break;
-    }
-    case "killed":
-      toolOutput += `Killed. `;
-      break;
-    case "timedOut":
-      toolOutput += `Timed out. `;
-      break;
-    case "aborted":
-      break;
-    default: {
-      const unreachable: never = status;
-      return unreachable;
-    }
-  }
-
-  if (exitStatus) {
-    if (typeof exitStatus.exitCode === "number") {
-      toolOutput += `Exited with code ${exitStatus.exitCode}.`;
-    }
-
-    if (typeof exitStatus.signal === "string") {
-      toolOutput += `Signal \`${exitStatus.signal}\`. `;
-    }
-
-    toolOutput += "Final output:\n\n";
-  } else {
-    toolOutput += "New output:\n\n";
-  }
-
-  toolOutput += commandOutput;
-
-  if (truncated) {
-    toolOutput += `\n\nCommand output was too long, so it was truncated to ${commandOutput.length} bytes.`;
-  }
-
-  return toolOutput;
-}
-
-/**
- * Replace text in a file and calculate the line numbers where the edits occurred.
- *
- * @param fileContent - The full file content
- * @param edits - Array of edit operations to apply sequentially
- * @returns the new content and the line numbers where replacements occurred in the final content
- */
-export function replaceAndCalculateLocation(
-  fileContent: string,
-  edits: Array<{
-    oldText: string;
-    newText: string;
-    replaceAll?: boolean;
-  }>,
-): { newContent: string; lineNumbers: number[] } {
-  let currentContent = fileContent;
-
-  // Use unique markers to track where replacements happen
-  const markerPrefix = `__REPLACE_MARKER_${Math.random().toString(36).substr(2, 9)}_`;
-  let markerCounter = 0;
-  const markers: string[] = [];
-
-  // Apply edits sequentially, inserting markers at replacement positions
-  for (const edit of edits) {
-    // Skip empty oldText
-    if (edit.oldText === "") {
-      throw new Error(`The provided \`old_string\` is empty.\n\nNo edits were applied.`);
-    }
-
-    if (edit.replaceAll) {
-      // Replace all occurrences with marker + newText
-      const parts: string[] = [];
-      let lastIndex = 0;
-      let searchIndex = 0;
-
-      while (true) {
-        const index = currentContent.indexOf(edit.oldText, searchIndex);
-        if (index === -1) {
-          if (searchIndex === 0) {
-            throw new Error(
-              `The provided \`old_string\` does not appear in the file: "${edit.oldText}".\n\nNo edits were applied.`,
-            );
-          }
-          break;
-        }
-
-        // Add content before the match
-        parts.push(currentContent.substring(lastIndex, index));
-
-        // Add marker and replacement
-        const marker = `${markerPrefix}${markerCounter++}__`;
-        markers.push(marker);
-        parts.push(marker + edit.newText);
-
-        lastIndex = index + edit.oldText.length;
-        searchIndex = lastIndex;
-      }
-
-      // Add remaining content
-      parts.push(currentContent.substring(lastIndex));
-      currentContent = parts.join("");
-    } else {
-      // Replace first occurrence only
-      const index = currentContent.indexOf(edit.oldText);
-      if (index === -1) {
-        throw new Error(
-          `The provided \`old_string\` does not appear in the file: "${edit.oldText}".\n\nNo edits were applied.`,
-        );
-      } else {
-        const marker = `${markerPrefix}${markerCounter++}__`;
-        markers.push(marker);
-        currentContent =
-          currentContent.substring(0, index) +
-          marker +
-          edit.newText +
-          currentContent.substring(index + edit.oldText.length);
-      }
-    }
-  }
-
-  // Find line numbers where markers appear in the content
-  const lineNumbers: number[] = [];
-  for (const marker of markers) {
-    const index = currentContent.indexOf(marker);
-    if (index !== -1) {
-      const lineNumber = Math.max(
-        0,
-        currentContent.substring(0, index).split(/\r\n|\r|\n/).length - 1,
-      );
-      lineNumbers.push(lineNumber);
-    }
-  }
-
-  // Remove all markers from the final content
-  let finalContent = currentContent;
-  for (const marker of markers) {
-    finalContent = finalContent.replace(marker, "");
-  }
-
-  // Dedupe and sort line numbers
-  const uniqueLineNumbers = [...new Set(lineNumbers)].sort();
-
-  return { newContent: finalContent, lineNumbers: uniqueLineNumbers };
-}

src/settings.ts

@@ -0,0 +1,269 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
+
+/**
+ * Permission rule format examples:
+ * - "Read" - matches all Read tool calls
+ * - "Read(./.env)" - matches specific path
+ * - "Read(./.env.*)" - glob pattern
+ * - "Read(./secrets/**)" - recursive glob
+ * - "Bash(npm run lint)" - exact command prefix
+ * - "Bash(npm run:*)" - command prefix with wildcard
+ *
+ * Docs: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
+ */
+
+export interface ClaudeCodeSettings {
+  env?: Record<string, string>;
+  model?: string;
+}
+
+/**
+ * Reads and parses a JSON settings file, returning an empty object if not found or invalid
+ */
+async function loadSettingsFile(filePath: string | null): Promise<ClaudeCodeSettings> {
+  if (!filePath) {
+    return {};
+  }
+
+  try {
+    const content = await fs.promises.readFile(filePath, "utf-8");
+    return JSON.parse(content) as ClaudeCodeSettings;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Gets the enterprise settings path based on the current platform
+ */
+export function getManagedSettingsPath(): string {
+  switch (process.platform) {
+    case "darwin":
+      return "/Library/Application Support/ClaudeCode/managed-settings.json";
+    case "linux":
+      return "/etc/claude-code/managed-settings.json";
+    case "win32":
+      return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
+    default:
+      return "/etc/claude-code/managed-settings.json";
+  }
+}
+
+export interface SettingsManagerOptions {
+  onChange?: () => void;
+  logger?: { log: (...args: any[]) => void; error: (...args: any[]) => void };
+}
+
+/**
+ * Manages Claude Code settings from multiple sources with proper precedence.
+ *
+ * Settings are loaded from (in order of increasing precedence):
+ * 1. User settings (~/.claude/settings.json)
+ * 2. Project settings (<cwd>/.claude/settings.json)
+ * 3. Local project settings (<cwd>/.claude/settings.local.json)
+ * 4. Enterprise managed settings (platform-specific path)
+ *
+ * The manager watches all settings files for changes and automatically reloads.
+ */
+export class SettingsManager {
+  private cwd: string;
+  private userSettings: ClaudeCodeSettings = {};
+  private projectSettings: ClaudeCodeSettings = {};
+  private localSettings: ClaudeCodeSettings = {};
+  private enterpriseSettings: ClaudeCodeSettings = {};
+  private mergedSettings: ClaudeCodeSettings = {};
+  private watchers: fs.FSWatcher[] = [];
+  private onChange?: () => void;
+  private logger: { log: (...args: any[]) => void; error: (...args: any[]) => void };
+  private initialized = false;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(cwd: string, options?: SettingsManagerOptions) {
+    this.cwd = cwd;
+    this.onChange = options?.onChange;
+    this.logger = options?.logger ?? console;
+  }
+
+  /**
+   * Initialize the settings manager by loading all settings and setting up file watchers
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    await this.loadAllSettings();
+    this.setupWatchers();
+    this.initialized = true;
+  }
+
+  /**
+   * Returns the path to the user settings file
+   */
+  private getUserSettingsPath(): string {
+    return path.join(CLAUDE_CONFIG_DIR, "settings.json");
+  }
+
+  /**
+   * Returns the path to the project settings file
+   */
+  private getProjectSettingsPath(): string {
+    return path.join(this.cwd, ".claude", "settings.json");
+  }
+
+  /**
+   * Returns the path to the local project settings file
+   */
+  private getLocalSettingsPath(): string {
+    return path.join(this.cwd, ".claude", "settings.local.json");
+  }
+
+  /**
+   * Loads settings from all sources
+   */
+  private async loadAllSettings(): Promise<void> {
+    const [userSettings, projectSettings, localSettings, enterpriseSettings] = await Promise.all([
+      loadSettingsFile(this.getUserSettingsPath()),
+      loadSettingsFile(this.getProjectSettingsPath()),
+      loadSettingsFile(this.getLocalSettingsPath()),
+      loadSettingsFile(getManagedSettingsPath()),
+    ]);
+
+    this.userSettings = userSettings;
+    this.projectSettings = projectSettings;
+    this.localSettings = localSettings;
+    this.enterpriseSettings = enterpriseSettings;
+
+    this.mergeSettings();
+  }
+
+  /**
+   * Merges all settings sources with proper precedence.
+   * For permissions, rules from all sources are combined.
+   * Deny rules always take precedence during permission checks.
+   */
+  private mergeSettings(): void {
+    const allSettings = [
+      this.userSettings,
+      this.projectSettings,
+      this.localSettings,
+      this.enterpriseSettings,
+    ];
+
+    const merged: ClaudeCodeSettings = {};
+
+    for (const settings of allSettings) {
+      if (settings.env) {
+        merged.env = { ...merged.env, ...settings.env };
+      }
+
+      if (settings.model) {
+        merged.model = settings.model;
+      }
+    }
+
+    this.mergedSettings = merged;
+  }
+
+  /**
+   * Sets up file watchers for all settings files
+   */
+  private setupWatchers(): void {
+    const paths = [
+      this.getUserSettingsPath(),
+      this.getProjectSettingsPath(),
+      this.getLocalSettingsPath(),
+      getManagedSettingsPath(),
+    ];
+
+    for (const filePath of paths) {
+      if (!filePath) continue;
+
+      try {
+        const dir = path.dirname(filePath);
+        const filename = path.basename(filePath);
+
+        if (fs.existsSync(dir)) {
+          const watcher = fs.watch(dir, (eventType, changedFilename) => {
+            if (changedFilename === filename) {
+              this.handleSettingsChange();
+            }
+          });
+
+          watcher.on("error", (error) => {
+            this.logger.error(`Settings watcher error for ${filePath}:`, error);
+          });
+
+          this.watchers.push(watcher);
+        }
+      } catch (error) {
+        this.logger.error(`Failed to set up watcher for ${filePath}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Handles settings file changes with debouncing to avoid rapid reloads
+   */
+  private handleSettingsChange(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(async () => {
+      this.debounceTimer = null;
+      try {
+        await this.loadAllSettings();
+        this.onChange?.();
+      } catch (error) {
+        this.logger.error("Failed to reload settings:", error);
+      }
+    }, 100);
+  }
+
+  /**
+   * Returns the current merged settings
+   */
+  getSettings(): ClaudeCodeSettings {
+    return this.mergedSettings;
+  }
+
+  /**
+   * Returns the current working directory
+   */
+  getCwd(): string {
+    return this.cwd;
+  }
+
+  /**
+   * Updates the working directory and reloads project-specific settings
+   */
+  async setCwd(cwd: string): Promise<void> {
+    if (this.cwd === cwd) {
+      return;
+    }
+
+    this.dispose();
+    this.cwd = cwd;
+    this.initialized = false;
+    await this.initialize();
+  }
+
+  /**
+   * Disposes of file watchers and cleans up resources
+   */
+  dispose(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+    this.initialized = false;
+  }
+}

src/tests/.claude/commands/say-hello.md

@@ -1,6 +1,6 @@
 ---
 description: Say hello
-argument-hint: [name]
+argument-hint: name
 ---
 
 Respond with "Hello $1" and nothing else.

src/tests/acp-agent.test.ts

@@ -17,9 +17,22 @@ import {
   WriteTextFileResponse,
 } from "@agentclientprotocol/sdk";
 import { nodeToWebWritable, nodeToWebReadable } from "../utils.js";
-import { markdownEscape, toolInfoFromToolUse, toolUpdateFromToolResult } from "../tools.js";
+import {
+  markdownEscape,
+  toolInfoFromToolUse,
+  toolUpdateFromToolResult,
+  toolUpdateFromEditToolResponse,
+} from "../tools.js";
 import { toAcpNotifications, promptToClaude } from "../acp-agent.js";
 import { query, SDKAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
+import { randomUUID } from "crypto";
+import type {
+  BetaToolResultBlockParam,
+  BetaToolSearchToolResultBlockParam,
+  BetaWebSearchToolResultBlockParam,
+  BetaWebFetchToolResultBlockParam,
+  BetaCodeExecutionToolResultBlockParam,
+} from "@anthropic-ai/sdk/resources/beta.mjs";
 
 describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration", () => {
   let child: ReturnType<typeof spawn>;
@@ -165,7 +178,7 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
     expect(commands).toContainEqual({
       name: "say-hello",
       description: "Say hello (project)",
-      input: { hint: "[name]" },
+      input: { hint: "name" },
     });
 
     await connection.prompt({
@@ -250,9 +263,9 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "execute",
-      title: "`rm README.md.rm`",
+      title: "rm README.md.rm",
       content: [
         {
           content: {
@@ -275,7 +288,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "search",
       title: "Find `*/**.ts`",
       content: [],
@@ -296,7 +309,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "think",
       title: "Handle user's work request",
       content: [
@@ -311,24 +324,6 @@ describe("tool conversions", () => {
     });
   });
 
-  it("should handle LS tool calls", () => {
-    const tool_use = {
-      type: "tool_use",
-      id: "toolu_01EEqsX7Eb9hpx87KAHVPTey",
-      name: "LS",
-      input: {
-        path: "/Users/test/github/claude-code-acp",
-      },
-    };
-
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
-      kind: "search",
-      title: "List the `/Users/test/github/claude-code-acp` directory's contents",
-      content: [],
-      locations: [],
-    });
-  });
-
   it("should handle Grep tool calls", () => {
     const tool_use = {
       type: "tool_use",
@@ -339,7 +334,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "search",
       title: 'grep ".*"',
       content: [],
@@ -357,7 +352,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "edit",
       title: "Write /Users/test/project/example.txt",
       content: [
@@ -372,18 +367,18 @@ describe("tool conversions", () => {
     });
   });
 
-  it("should handle mcp__acp__Write tool calls", () => {
+  it("should handle Write tool calls", () => {
     const tool_use = {
       type: "tool_use",
       id: "toolu_01GHI789JKL456",
-      name: "mcp__acp__Write",
+      name: "Write",
       input: {
         file_path: "/Users/test/project/config.json",
         content: '{"version": "1.0.0"}',
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "edit",
       title: "Write /Users/test/project/config.json",
       content: [
@@ -398,6 +393,81 @@ describe("tool conversions", () => {
     });
   });
 
+  it("should handle Edit tool calls", () => {
+    const tool_use = {
+      type: "tool_use",
+      id: "toolu_01EDIT123",
+      name: "Edit",
+      input: {
+        file_path: "/Users/test/project/test.txt",
+        old_string: "old text",
+        new_string: "new text",
+      },
+    };
+
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
+      kind: "edit",
+      title: "Edit /Users/test/project/test.txt",
+      content: [
+        {
+          type: "diff",
+          path: "/Users/test/project/test.txt",
+          oldText: "old text",
+          newText: "new text",
+        },
+      ],
+      locations: [{ path: "/Users/test/project/test.txt" }],
+    });
+  });
+
+  it("should handle Edit tool calls with replace_all", () => {
+    const tool_use = {
+      type: "tool_use",
+      id: "toolu_01EDIT456",
+      name: "Edit",
+      input: {
+        replace_all: false,
+        file_path: "/Users/benbrandt/github/codex-acp/src/thread.rs",
+        old_string:
+          "struct PromptState {\n    active_command: Option<ActiveCommand>,\n    active_web_search: Option<String>,\n}",
+        new_string:
+          "struct PromptState {\n    active_commands: HashMap<String, ActiveCommand>,\n    active_web_search: Option<String>,\n}",
+      },
+    };
+
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
+      kind: "edit",
+      title: "Edit /Users/benbrandt/github/codex-acp/src/thread.rs",
+      content: [
+        {
+          type: "diff",
+          path: "/Users/benbrandt/github/codex-acp/src/thread.rs",
+          oldText:
+            "struct PromptState {\n    active_command: Option<ActiveCommand>,\n    active_web_search: Option<String>,\n}",
+          newText:
+            "struct PromptState {\n    active_commands: HashMap<String, ActiveCommand>,\n    active_web_search: Option<String>,\n}",
+        },
+      ],
+      locations: [{ path: "/Users/benbrandt/github/codex-acp/src/thread.rs" }],
+    });
+  });
+
+  it("should handle Edit tool calls without file_path", () => {
+    const tool_use = {
+      type: "tool_use",
+      id: "toolu_01EDIT789",
+      name: "Edit",
+      input: {},
+    };
+
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
+      kind: "edit",
+      title: "Edit",
+      content: [],
+      locations: [],
+    });
+  });
+
   it("should handle Read tool calls", () => {
     const tool_use = {
       type: "tool_use",
@@ -408,56 +478,56 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
-      title: "Read File",
+      title: "Read /Users/test/project/readme.md",
       content: [],
-      locations: [{ path: "/Users/test/project/readme.md", line: 0 }],
+      locations: [{ path: "/Users/test/project/readme.md", line: 1 }],
     });
   });
 
-  it("should handle mcp__acp__Read tool calls", () => {
+  it("should handle Read tool calls", () => {
     const tool_use = {
       type: "tool_use",
       id: "toolu_01YZA789BCD123",
-      name: "mcp__acp__Read",
+      name: "Read",
       input: {
         file_path: "/Users/test/project/data.json",
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
       title: "Read /Users/test/project/data.json",
       content: [],
-      locations: [{ path: "/Users/test/project/data.json", line: 0 }],
+      locations: [{ path: "/Users/test/project/data.json", line: 1 }],
     });
   });
 
-  it("should handle mcp__acp__Read with limit", () => {
+  it("should handle Read with limit", () => {
     const tool_use = {
       type: "tool_use",
       id: "toolu_01EFG456HIJ789",
-      name: "mcp__acp__Read",
+      name: "Read",
       input: {
         file_path: "/Users/test/project/large.txt",
         limit: 100,
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
       title: "Read /Users/test/project/large.txt (1 - 100)",
       content: [],
-      locations: [{ path: "/Users/test/project/large.txt", line: 0 }],
+      locations: [{ path: "/Users/test/project/large.txt", line: 1 }],
     });
   });
 
-  it("should handle mcp__acp__Read with offset and limit", () => {
+  it("should handle Read with offset and limit", () => {
     const tool_use = {
       type: "tool_use",
       id: "toolu_01KLM789NOP456",
-      name: "mcp__acp__Read",
+      name: "Read",
       input: {
         file_path: "/Users/test/project/large.txt",
         offset: 50,
@@ -465,111 +535,33 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
-      title: "Read /Users/test/project/large.txt (51 - 150)",
+      title: "Read /Users/test/project/large.txt (50 - 149)",
       content: [],
       locations: [{ path: "/Users/test/project/large.txt", line: 50 }],
     });
   });
 
-  it("should handle mcp__acp__Read with only offset", () => {
+  it("should handle Read with only offset", () => {
     const tool_use = {
       type: "tool_use",
       id: "toolu_01QRS123TUV789",
-      name: "mcp__acp__Read",
+      name: "Read",
       input: {
         file_path: "/Users/test/project/large.txt",
         offset: 200,
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
-      title: "Read /Users/test/project/large.txt (from line 201)",
+      title: "Read /Users/test/project/large.txt (from line 200)",
       content: [],
       locations: [{ path: "/Users/test/project/large.txt", line: 200 }],
     });
   });
 
-  it("should handle WebFetch tool calls", () => {
-    const tool_use = {
-      type: "tool_use",
-      id: "toolu_01LxEjDn8ci9SAc3qG7LbbXV",
-      name: "WebFetch",
-      input: {
-        url: "https://agentclientprotocol.com",
-        prompt:
-          "Please provide a comprehensive summary of the content on this page, including what the Agent Client Protocol is, its main features, documentation links, and any other relevant information.",
-      },
-    };
-
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
-      kind: "fetch",
-      title: "Fetch https://agentclientprotocol.com",
-      content: [
-        {
-          content: {
-            text: "Please provide a comprehensive summary of the content on this page, including what the Agent Client Protocol is, its main features, documentation links, and any other relevant information.",
-            type: "text",
-          },
-          type: "content",
-        },
-      ],
-    });
-  });
-
-  it("should handle WebSearch tool calls", () => {
-    const tool_use = {
-      type: "tool_use",
-      id: "toolu_01NYMwiZFbdoQFxYxuQDFZXQ",
-      name: "WebSearch",
-      input: {
-        query: "agentclientprotocol.com",
-      },
-    };
-
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
-      kind: "fetch",
-      title: '"agentclientprotocol.com"',
-      content: [],
-    });
-  });
-
-  it("should handle KillBash entries", () => {
-    const tool_use = {
-      type: "tool_use",
-      id: "toolu_01PhLms5fuvmdjy2bb6dfUKT",
-      name: "KillShell",
-      input: {
-        shell_id: "bash_1",
-      },
-    };
-
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
-      kind: "execute",
-      title: `Kill Process`,
-      content: [],
-    });
-  });
-
-  it("should handle BashOutput entries", () => {
-    const tool_use = {
-      type: "tool_use",
-      id: "toolu_01SJUWPtj1QspgANgtpqGPuN",
-      name: "BashOutput",
-      input: {
-        bash_id: "bash_1",
-      },
-    };
-
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
-      kind: "execute",
-      title: `Tail Logs`,
-      content: [],
-    });
-  });
-
   it("should handle plan entries", () => {
     const received: SDKAssistantMessage = {
       type: "assistant",
@@ -643,6 +635,9 @@ describe("tool conversions", () => {
           output_tokens: 1,
           service_tier: "standard",
           server_tool_use: null,
+          inference_geo: null,
+          iterations: null,
+          speed: null,
         },
         context_management: null,
       },
@@ -656,8 +651,8 @@ describe("tool conversions", () => {
         received.message.role,
         "test",
         {},
-        {},
         {} as AgentSideConnection,
+        console,
       ),
     ).toStrictEqual([
       {
@@ -715,7 +710,7 @@ describe("tool conversions", () => {
     const toolUse = {
       type: "tool_use",
       id: "toolu_01MNO345",
-      name: "mcp__acp__Edit",
+      name: "Edit",
       input: {
         file_path: "/Users/test/project/test.txt",
         old_string: "old",
@@ -745,7 +740,7 @@ describe("tool conversions", () => {
     const toolUse = {
       type: "tool_use",
       id: "toolu_01MNO345",
-      name: "mcp__acp__Edit",
+      name: "Edit",
       input: {
         file_path: "/Users/test/project/test.txt",
         old_string: "old",
@@ -777,6 +772,320 @@ describe("tool conversions", () => {
       ],
     });
   });
+
+  it("should transform tool_reference content to valid ACP content", () => {
+    const toolUse = {
+      type: "tool_use",
+      id: "toolu_01MNO345",
+      name: "ToolSearch",
+      input: { query: "test" },
+    };
+
+    const toolResult: BetaToolResultBlockParam = {
+      content: [
+        {
+          type: "tool_reference",
+          tool_name: "some_discovered_tool",
+        },
+      ],
+      tool_use_id: "toolu_01MNO345",
+      is_error: false,
+      type: "tool_result",
+    };
+
+    const update = toolUpdateFromToolResult(toolResult, toolUse);
+
+    expect(update).toEqual({
+      content: [
+        {
+          type: "content",
+          content: { type: "text", text: "Tool: some_discovered_tool" },
+        },
+      ],
+    });
+  });
+
+  it("should transform web_search_result content to valid ACP content", () => {
+    const toolUse = {
+      type: "tool_use",
+      id: "toolu_01MNO345",
+      name: "WebSearch",
+      input: { query: "test" },
+    };
+
+    const toolResult: BetaWebSearchToolResultBlockParam = {
+      content: [
+        {
+          type: "web_search_result",
+          title: "Test Result",
+          url: "https://example.com",
+          encrypted_content: "...",
+          page_age: null,
+        },
+      ],
+      tool_use_id: "toolu_01MNO345",
+      type: "web_search_tool_result",
+    };
+
+    const update = toolUpdateFromToolResult(toolResult, toolUse);
+
+    expect(update).toEqual({
+      content: [
+        {
+          type: "content",
+          content: { type: "text", text: "Test Result (https://example.com)" },
+        },
+      ],
+    });
+  });
+
+  it("should transform web_search_tool_result_error to valid ACP content", () => {
+    const toolUse = {
+      type: "tool_use",
+      id: "toolu_01MNO345",
+      name: "WebSearch",
+      input: { query: "test" },
+    };
+
+    const toolResult: BetaWebSearchToolResultBlockParam = {
+      content: {
+        type: "web_search_tool_result_error",
+        error_code: "unavailable",
+      },
+      tool_use_id: "toolu_01MNO345",
+      type: "web_search_tool_result",
+    };
+
+    const update = toolUpdateFromToolResult(toolResult, toolUse);
+
+    expect(update).toEqual({
+      content: [
+        {
+          type: "content",
+          content: { type: "text", text: "Error: unavailable" },
+        },
+      ],
+    });
+  });
+
+  it("should transform code_execution_result content to valid ACP content", () => {
+    const toolUse = {
+      type: "tool_use",
+      id: "toolu_01MNO345",
+      name: "CodeExecution",
+      input: {},
+    };
+
+    const toolResult: BetaCodeExecutionToolResultBlockParam = {
+      content: {
+        type: "code_execution_result",
+        stdout: "Hello World",
+        stderr: "",
+        return_code: 0,
+        content: [],
+      },
+      tool_use_id: "toolu_01MNO345",
+      type: "code_execution_tool_result",
+    };
+
+    const update = toolUpdateFromToolResult(toolResult, toolUse);
+
+    expect(update).toEqual({
+      content: [
+        {
+          type: "content",
+          content: { type: "text", text: "Output: Hello World" },
+        },
+      ],
+    });
+  });
+
+  it("should transform web_fetch_result content to valid ACP content", () => {
+    const toolUse = {
+      type: "tool_use",
+      id: "toolu_01MNO345",
+      name: "WebFetch",
+      input: { url: "https://example.com" },
+    };
+
+    const toolResult: BetaWebFetchToolResultBlockParam = {
+      content: {
+        type: "web_fetch_result",
+        url: "https://example.com",
+        content: {
+          type: "document",
+          citations: null,
+          title: null,
+          source: { type: "text", media_type: "text/plain", data: "Page content here" },
+        },
+      },
+      tool_use_id: "toolu_01MNO345",
+      type: "web_fetch_tool_result",
+    };
+
+    const update = toolUpdateFromToolResult(toolResult, toolUse);
+
+    expect(update).toEqual({
+      content: [
+        {
+          type: "content",
+          content: { type: "text", text: "Fetched: https://example.com" },
+        },
+      ],
+    });
+  });
+
+  it("should transform tool_search_tool_search_result to valid ACP content", () => {
+    const toolUse = {
+      type: "tool_use",
+      id: "toolu_01MNO345",
+      name: "ToolSearch",
+      input: { query: "test" },
+    };
+
+    const toolResult: BetaToolSearchToolResultBlockParam = {
+      content: {
+        type: "tool_search_tool_search_result",
+        tool_references: [
+          { type: "tool_reference", tool_name: "tool_a" },
+          { type: "tool_reference", tool_name: "tool_b" },
+        ],
+      },
+      tool_use_id: "toolu_01MNO345",
+      type: "tool_search_tool_result",
+    };
+
+    const update = toolUpdateFromToolResult(toolResult, toolUse);
+
+    expect(update).toEqual({
+      content: [
+        {
+          type: "content",
+          content: { type: "text", text: "Tools found: tool_a, tool_b" },
+        },
+      ],
+    });
+  });
+});
+
+describe("toolUpdateFromEditToolResponse", () => {
+  it("should return empty for non-object input", () => {
+    expect(toolUpdateFromEditToolResponse(null)).toEqual({});
+    expect(toolUpdateFromEditToolResponse(undefined)).toEqual({});
+    expect(toolUpdateFromEditToolResponse("string")).toEqual({});
+  });
+
+  it("should return empty when filePath or structuredPatch is missing", () => {
+    expect(toolUpdateFromEditToolResponse({})).toEqual({});
+    expect(toolUpdateFromEditToolResponse({ filePath: "/foo.ts" })).toEqual({});
+    expect(toolUpdateFromEditToolResponse({ structuredPatch: [] })).toEqual({});
+  });
+
+  it("should build diff content from a single-hunk structuredPatch", () => {
+    const toolResponse = {
+      filePath: "/Users/test/project/test.txt",
+      structuredPatch: [
+        {
+          oldStart: 1,
+          oldLines: 3,
+          newStart: 1,
+          newLines: 3,
+          lines: [" context before", "-old line", "+new line", " context after"],
+        },
+      ],
+    };
+
+    expect(toolUpdateFromEditToolResponse(toolResponse)).toEqual({
+      content: [
+        {
+          type: "diff",
+          path: "/Users/test/project/test.txt",
+          oldText: "context before\nold line\ncontext after",
+          newText: "context before\nnew line\ncontext after",
+        },
+      ],
+      locations: [{ path: "/Users/test/project/test.txt", line: 1 }],
+    });
+  });
+
+  it("should build multiple diff content blocks for replaceAll with multiple hunks", () => {
+    const toolResponse = {
+      filePath: "/Users/test/project/file.ts",
+      structuredPatch: [
+        {
+          oldStart: 5,
+          oldLines: 1,
+          newStart: 5,
+          newLines: 1,
+          lines: ["-oldValue", "+newValue"],
+        },
+        {
+          oldStart: 20,
+          oldLines: 1,
+          newStart: 20,
+          newLines: 1,
+          lines: ["-oldValue", "+newValue"],
+        },
+      ],
+    };
+
+    expect(toolUpdateFromEditToolResponse(toolResponse)).toEqual({
+      content: [
+        {
+          type: "diff",
+          path: "/Users/test/project/file.ts",
+          oldText: "oldValue",
+          newText: "newValue",
+        },
+        {
+          type: "diff",
+          path: "/Users/test/project/file.ts",
+          oldText: "oldValue",
+          newText: "newValue",
+        },
+      ],
+      locations: [
+        { path: "/Users/test/project/file.ts", line: 5 },
+        { path: "/Users/test/project/file.ts", line: 20 },
+      ],
+    });
+  });
+
+  it("should handle deletion (newText becomes empty string)", () => {
+    const toolResponse = {
+      filePath: "/Users/test/project/file.ts",
+      structuredPatch: [
+        {
+          oldStart: 10,
+          oldLines: 2,
+          newStart: 10,
+          newLines: 1,
+          lines: [" context", "-removed line"],
+        },
+      ],
+    };
+
+    expect(toolUpdateFromEditToolResponse(toolResponse)).toEqual({
+      content: [
+        {
+          type: "diff",
+          path: "/Users/test/project/file.ts",
+          oldText: "context\nremoved line",
+          newText: "context",
+        },
+      ],
+      locations: [{ path: "/Users/test/project/file.ts", line: 10 }],
+    });
+  });
+
+  it("should return empty for empty structuredPatch array", () => {
+    const toolResponse = {
+      filePath: "/Users/test/project/file.ts",
+      structuredPatch: [],
+    };
+
+    expect(toolUpdateFromEditToolResponse(toolResponse)).toEqual({});
+  });
 });
 
 describe("escape markdown", () => {
@@ -829,17 +1138,29 @@ describe("prompt conversion", () => {
   });
 });
 
-describe("SDK behavior", () => {
-  it.skipIf(!process.env.RUN_INTEGRATION_TESTS)(
-    "query has a 'default' model",
-    async () => {
-      const q = query({ prompt: "hi" });
-      const models = await q.supportedModels();
-      const defaultModel = models.find((m) => m.value === "default");
-      expect(defaultModel).toBeDefined();
-    },
-    10000,
-  );
+describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("SDK behavior", () => {
+  it("query has a 'default' model", async () => {
+    const q = query({ prompt: "hi" });
+    const models = await q.supportedModels();
+    const defaultModel = models.find((m) => m.value === "default");
+    expect(defaultModel).toBeDefined();
+  }, 10000);
+
+  it("custom session id", async () => {
+    const sessionId = randomUUID();
+    const q = query({
+      prompt: "hi",
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        sessionId,
+        settingSources: ["user", "project", "local"],
+        includePartialMessages: true,
+      },
+    });
+
+    const { value } = await q.next();
+    expect(value).toMatchObject({ type: "system", subtype: "init", session_id: sessionId });
+  }, 10000);
 });
 
 describe("permission requests", () => {
@@ -862,13 +1183,13 @@ describe("permission requests", () => {
           name: "Bash",
           input: { command: "ls -la", description: "List files" },
         },
-        expectedTitlePart: "`ls -la`",
+        expectedTitlePart: "ls -la",
       },
       {
         toolUse: {
           type: "tool_use" as const,
           id: "test-3",
-          name: "mcp__acp__Read",
+          name: "Read",
           input: { file_path: "/test/data.json" },
         },
         expectedTitlePart: "/test/data.json",
@@ -877,24 +1198,33 @@ describe("permission requests", () => {
 
     for (const testCase of testCases) {
       // Get the tool info that would be used in requestPermission
-      const toolInfo = toolInfoFromToolUse(testCase.toolUse, {});
+      const toolInfo = toolInfoFromToolUse(testCase.toolUse);
 
       // Verify toolInfo has a title
       expect(toolInfo.title).toBeDefined();
       expect(toolInfo.title).toContain(testCase.expectedTitlePart);
 
       // Verify the structure that our fix creates for requestPermission
+      // We now spread the full toolInfo (title, kind, content, locations)
       const requestStructure = {
         toolCall: {
           toolCallId: testCase.toolUse.id,
           rawInput: testCase.toolUse.input,
-          title: toolInfo.title, // This is what commit 1785d86 adds
+          ...toolInfo,
         },
       };
 
       // Ensure the title field is present and populated
       expect(requestStructure.toolCall.title).toBeDefined();
       expect(requestStructure.toolCall.title).toContain(testCase.expectedTitlePart);
+
+      // Ensure kind is included so the client can render appropriate UI
+      expect(requestStructure.toolCall.kind).toBeDefined();
+      expect(typeof requestStructure.toolCall.kind).toBe("string");
+
+      // Ensure content is included so the client always has tool call details
+      expect(requestStructure.toolCall.content).toBeDefined();
+      expect(Array.isArray(requestStructure.toolCall.content)).toBe(true);
     }
   });
 });

src/tests/extract-lines.test.ts

@@ -1,103 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { extractLinesWithByteLimit } from "../utils.js";
-
-describe("extractLinesWithByteLimit", () => {
-  const simpleContent = "Line 1\nLine 2\nLine 3\nLine 4\nLine 5";
-
-  it("should extract all lines when under byte limit", () => {
-    const result = extractLinesWithByteLimit(simpleContent, 1000);
-
-    expect(result.content).toBe(simpleContent);
-    expect(result.wasLimited).toBe(false);
-    expect(result.linesRead).toBe(5);
-  });
-
-  it("should limit output when exceeding byte limit", () => {
-    // Create content that will exceed byte limit
-    const longLine = "x".repeat(100);
-    const manyLines = Array(10).fill(longLine).join("\n");
-
-    const result = extractLinesWithByteLimit(manyLines, 250);
-
-    expect(result.wasLimited).toBe(true);
-    expect(result.linesRead).toBe(2);
-  });
-
-  it("should handle empty content", () => {
-    const result = extractLinesWithByteLimit("", 1000);
-
-    expect(result.content).toBe("");
-    expect(result.wasLimited).toBe(false);
-    expect(result.linesRead).toBe(1); // We read the one empty line
-  });
-
-  it("should handle single line file", () => {
-    const singleLine = "This is a single line without newline";
-    const result = extractLinesWithByteLimit(singleLine, 1000);
-
-    expect(result.content).toBe(singleLine);
-    expect(result.wasLimited).toBe(false);
-    expect(result.linesRead).toBe(1);
-  });
-
-  it("should correctly count bytes with multi-byte characters", () => {
-    const unicodeContent = "Hello 世界\n你好 World\nEmoji: 🌍\nNormal line";
-    const result = extractLinesWithByteLimit(unicodeContent, 1000);
-
-    expect(result.content).toBe(unicodeContent);
-    expect(result.linesRead).toBe(4);
-  });
-
-  it("should stop at byte limit even with one more line available", () => {
-    // Create lines where adding one more would exceed limit
-    const line1 = "a".repeat(40);
-    const line2 = "b".repeat(40);
-    const line3 = "c".repeat(40);
-    const content = `${line1}\n${line2}\n${line3}`;
-
-    const result = extractLinesWithByteLimit(content, 85);
-
-    expect(result.content).toBe(`${line1}\n${line2}\n`);
-    expect(result.wasLimited).toBe(true);
-    expect(result.linesRead).toBe(2);
-  });
-
-  it("should read exactly to limit when possible", () => {
-    const exactContent = "12345\n67890\n12345"; // 17 bytes total
-    const result = extractLinesWithByteLimit(exactContent, 17);
-
-    expect(result.content).toBe(exactContent);
-    expect(result.wasLimited).toBe(false);
-    expect(result.linesRead).toBe(3);
-  });
-
-  it("should handle Windows-style line endings", () => {
-    const windowsContent = "Line 1\r\nLine 2\r\nLine 3";
-    const result = extractLinesWithByteLimit(windowsContent, 1000);
-
-    // Note: split("\n") will keep the \r characters
-    expect(result.content).toBe("Line 1\r\nLine 2\r\nLine 3");
-    expect(result.linesRead).toBe(3);
-  });
-
-  it("should handle very large files efficiently", () => {
-    // Create a 100KB file
-    const largeLine = "x".repeat(1000);
-    const largeContent = Array(110).fill(largeLine).join("\n");
-
-    const result = extractLinesWithByteLimit(largeContent, 50000);
-
-    expect(result.wasLimited).toBe(true);
-  });
-
-  it("should allow at least one line even if it exceeds byte limit", () => {
-    const veryLongLine = "x".repeat(100000); // 100KB line
-    const result = extractLinesWithByteLimit(veryLongLine, 50000);
-
-    // Should return the line even though it exceeds the byte limit
-    // because we always allow at least one line if no lines have been added yet
-    expect(result.content).toBe(veryLongLine);
-    expect(result.linesRead).toBe(1);
-    expect(result.wasLimited).toBe(false);
-  });
-});

src/tests/list-sessions.test.ts

@@ -0,0 +1,596 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { AgentSideConnection } from "@agentclientprotocol/sdk";
+import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import { encodeProjectPath } from "../utils.js";
+
+describe("unstable_listSessions", () => {
+  let tempDir: string;
+  let originalClaudeConfigDir: string | undefined;
+  let agent: ClaudeAcpAgentType;
+  let ClaudeAcpAgent: typeof ClaudeAcpAgentType;
+
+  // Helper to create a mock AgentSideConnection
+  function createMockClient(): AgentSideConnection {
+    return {
+      sessionUpdate: async () => {},
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AgentSideConnection;
+  }
+
+  // Helper to write a session file
+  function writeSessionFile(
+    cwd: string,
+    sessionId: string,
+    options: {
+      userMessage?: string;
+      userMessageArray?: boolean;
+      mtime?: Date;
+      malformed?: boolean;
+      isAgentFile?: boolean;
+      omitCwdFromEntries?: boolean;
+    } = {},
+  ): void {
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const filename = options.isAgentFile ? `agent-${sessionId}.jsonl` : `${sessionId}.jsonl`;
+    const filePath = path.join(projectDir, filename);
+
+    if (options.malformed) {
+      fs.writeFileSync(filePath, "not valid json\n{also bad");
+      return;
+    }
+
+    const lines: string[] = [];
+
+    // First line with sessionId
+    lines.push(JSON.stringify({ sessionId, type: "init" }));
+
+    // User message if provided
+    if (options.userMessage) {
+      const content = options.userMessageArray
+        ? [{ type: "text", text: options.userMessage }]
+        : options.userMessage;
+      lines.push(
+        JSON.stringify({
+          type: "user",
+          sessionId,
+          ...(options.omitCwdFromEntries ? {} : { cwd }),
+          message: { content },
+        }),
+      );
+    }
+
+    // Assistant response
+    lines.push(
+      JSON.stringify({
+        type: "assistant",
+        sessionId,
+        ...(options.omitCwdFromEntries ? {} : { cwd }),
+        message: { content: "Hello!" },
+      }),
+    );
+
+    fs.writeFileSync(filePath, lines.join("\n"));
+
+    // Set modification time if specified
+    if (options.mtime) {
+      fs.utimesSync(filePath, options.mtime, options.mtime);
+    }
+  }
+
+  beforeEach(async () => {
+    // Create temp directory to isolate tests from real filesystem.
+    // We set process.env.CLAUDE_CONFIG_DIR before importing the module so that
+    // CLAUDE_CONFIG_DIR is evaluated with our temp directory.
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "claude-test-"));
+    originalClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = tempDir;
+
+    // Reset modules to pick up the new CLAUDE_CONFIG_DIR env var
+    vi.resetModules();
+
+    // Dynamic import after setting env var
+    const acpAgent = await import("../acp-agent.js");
+    ClaudeAcpAgent = acpAgent.ClaudeAcpAgent;
+
+    // Create agent instance
+    agent = new ClaudeAcpAgent(createMockClient());
+  });
+
+  afterEach(() => {
+    // Restore env and cleanup
+    if (originalClaudeConfigDir !== undefined) {
+      process.env.CLAUDE_CONFIG_DIR = originalClaudeConfigDir;
+    } else {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    }
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("returns empty array when projects directory does not exist", async () => {
+    const result = await agent.unstable_listSessions({});
+    expect(result.sessions).toEqual([]);
+    expect(result.nextCursor).toBeUndefined();
+  });
+
+  it("returns empty array when projects directory is empty", async () => {
+    fs.mkdirSync(path.join(tempDir, "projects"), { recursive: true });
+
+    const result = await agent.unstable_listSessions({});
+    expect(result.sessions).toEqual([]);
+  });
+
+  it("parses session files and returns correct metadata", async () => {
+    const cwd = "/Users/test/myproject";
+    const sessionId = "sess-123";
+    const mtime = new Date("2025-01-15T10:30:00Z");
+
+    writeSessionFile(cwd, sessionId, {
+      userMessage: "Hello, can you help me?",
+      mtime,
+    });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]).toMatchObject({
+      sessionId: "sess-123",
+      cwd: "/Users/test/myproject",
+      title: "Hello, can you help me?",
+    });
+    expect(result.sessions[0]!.updatedAt).toBeDefined();
+  });
+
+  it("extracts title from array-style user message content", async () => {
+    writeSessionFile("/Users/test/project", "sess-456", {
+      userMessage: "Fix the bug in auth",
+      userMessageArray: true,
+    });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.title).toBe("Fix the bug in auth");
+  });
+
+  it("truncates long titles to 128 characters with ellipsis", async () => {
+    const longMessage = "A".repeat(150);
+    writeSessionFile("/Users/test/project", "sess-789", {
+      userMessage: longMessage,
+    });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.title).toBe("A".repeat(127) + "…");
+  });
+
+  it("replaces newlines with spaces in titles", async () => {
+    const messageWithNewlines = "First line\nSecond line\r\nThird line";
+    writeSessionFile("/Users/test/project", "sess-newlines", {
+      userMessage: messageWithNewlines,
+    });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.title).toBe("First line Second line Third line");
+  });
+
+  it("collapses multiple whitespace characters in titles", async () => {
+    const messageWithWhitespace = "Hello    world  \n\n  test";
+    writeSessionFile("/Users/test/project", "sess-whitespace", {
+      userMessage: messageWithWhitespace,
+    });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.title).toBe("Hello world test");
+  });
+
+  it("filters sessions by cwd parameter", async () => {
+    writeSessionFile("/Users/test/projectone", "sess-a", { userMessage: "Project A" });
+    writeSessionFile("/Users/test/projecttwo", "sess-b", { userMessage: "Project B" });
+
+    const result = await agent.unstable_listSessions({ cwd: "/Users/test/projectone" });
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("sess-a");
+  });
+
+  it("uses per-entry cwd when filtering even if encoded folder collides", async () => {
+    const encodedPath = encodeProjectPath("/Users/test/a-b");
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(projectDir, "sess-a-b.jsonl"),
+      [
+        JSON.stringify({ sessionId: "sess-a-b", type: "init" }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "sess-a-b",
+          cwd: "/Users/test/a-b",
+          message: { content: "A-B" },
+        }),
+      ].join("\n"),
+    );
+
+    fs.writeFileSync(
+      path.join(projectDir, "sess-a-slash-b.jsonl"),
+      [
+        JSON.stringify({ sessionId: "sess-a-slash-b", type: "init" }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "sess-a-slash-b",
+          cwd: "/Users/test/a/b",
+          message: { content: "A/B" },
+        }),
+      ].join("\n"),
+    );
+
+    const result = await agent.unstable_listSessions({ cwd: "/Users/test/a-b" });
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("sess-a-b");
+    expect(result.sessions[0]!.cwd).toBe("/Users/test/a-b");
+  });
+
+  it("returns the true cwd for paths containing hyphens", async () => {
+    const cwd = "/Users/test/claude-agent-acp";
+    writeSessionFile(cwd, "hyphen-session", { userMessage: "Hyphen test" });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.cwd).toBe(cwd);
+    expect(result.sessions[0]!.sessionId).toBe("hyphen-session");
+  });
+
+  it("filters hyphenated paths by cwd correctly", async () => {
+    writeSessionFile("/Users/test/claude-agent-acp", "hyphen-a", { userMessage: "A" });
+    writeSessionFile("/Users/test/other-project", "hyphen-b", { userMessage: "B" });
+
+    const result = await agent.unstable_listSessions({ cwd: "/Users/test/claude-agent-acp" });
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("hyphen-a");
+    expect(result.sessions[0]!.cwd).toBe("/Users/test/claude-agent-acp");
+  });
+
+  it("returns all sessions when cwd is not specified", async () => {
+    writeSessionFile("/Users/test/projectone", "sess-a", { userMessage: "A" });
+    writeSessionFile("/Users/test/projecttwo", "sess-b", { userMessage: "B" });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(2);
+  });
+
+  it("sorts sessions by updatedAt descending (most recent first)", async () => {
+    writeSessionFile("/Users/test/project", "old-session", {
+      userMessage: "Old",
+      mtime: new Date("2025-01-01T00:00:00Z"),
+    });
+    writeSessionFile("/Users/test/project", "new-session", {
+      userMessage: "New",
+      mtime: new Date("2025-01-15T00:00:00Z"),
+    });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.sessionId).toBe("new-session");
+    expect(result.sessions[1]!.sessionId).toBe("old-session");
+  });
+
+  it("skips files starting with agent-", async () => {
+    writeSessionFile("/Users/test/project", "regular-session", { userMessage: "Regular" });
+    writeSessionFile("/Users/test/project", "hidden-session", {
+      userMessage: "Hidden",
+      isAgentFile: true,
+    });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("regular-session");
+  });
+
+  it("skips malformed session files gracefully", async () => {
+    writeSessionFile("/Users/test/project", "good-session", { userMessage: "Good" });
+    writeSessionFile("/Users/test/project", "bad-session", { malformed: true });
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("good-session");
+  });
+
+  it("uses filename as sessionId when not in file content", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    // Write file without sessionId in content (uses filename fallback), but with cwd.
+    const filePath = path.join(projectDir, "fallback-id.jsonl");
+    fs.writeFileSync(
+      filePath,
+      [
+        JSON.stringify({ type: "init" }),
+        JSON.stringify({ type: "assistant", cwd, message: { content: "Hi" } }),
+      ].join("\n"),
+    );
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.sessionId).toBe("fallback-id");
+  });
+
+  it("keeps sessionId stable from filename when later entries have different sessionId", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const filePath = path.join(projectDir, "stable-id.jsonl");
+    fs.writeFileSync(
+      filePath,
+      [
+        JSON.stringify({ type: "init", sessionId: "stable-id" }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "stable-id",
+          cwd,
+          message: { content: "Hello" },
+        }),
+        JSON.stringify({
+          type: "assistant",
+          sessionId: "other-id",
+          cwd,
+          message: { content: "Wrong session id from sidechain" },
+        }),
+      ].join("\n"),
+    );
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("stable-id");
+  });
+
+  it("derives cwd from entries for the filename sessionId only", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const filePath = path.join(projectDir, "target-session.jsonl");
+    fs.writeFileSync(
+      filePath,
+      [
+        JSON.stringify({
+          type: "user",
+          sessionId: "target-session",
+          cwd,
+          message: { content: "Correct cwd entry" },
+        }),
+      ].join("\n"),
+    );
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("target-session");
+    expect(result.sessions[0]!.cwd).toBe(cwd);
+  });
+
+  it("keeps scanning after title to find later cwd in same session", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const filePath = path.join(projectDir, "late-cwd.jsonl");
+    fs.writeFileSync(
+      filePath,
+      [
+        JSON.stringify({ type: "init", sessionId: "late-cwd" }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "late-cwd",
+          message: { content: "Title from first user message" },
+        }),
+        JSON.stringify({
+          type: "assistant",
+          sessionId: "late-cwd",
+          cwd,
+          message: { content: "Assistant entry carries cwd" },
+        }),
+      ].join("\n"),
+    );
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("late-cwd");
+    expect(result.sessions[0]!.cwd).toBe(cwd);
+    expect(result.sessions[0]!.title).toBe("Title from first user message");
+  });
+
+  it("ignores sidechain entries when deriving cwd and title", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const filePath = path.join(projectDir, "sidechain-metadata.jsonl");
+    fs.writeFileSync(
+      filePath,
+      [
+        JSON.stringify({ type: "init", sessionId: "sidechain-metadata" }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "sidechain-metadata",
+          isSidechain: true,
+          cwd: "/Users/test/wrong-project",
+          message: { content: "Wrong sidechain title" },
+        }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "sidechain-metadata",
+          cwd,
+          message: { content: "Correct primary title" },
+        }),
+      ].join("\n"),
+    );
+
+    const result = await agent.unstable_listSessions({ cwd });
+
+    expect(result.sessions).toHaveLength(1);
+    expect(result.sessions[0]!.sessionId).toBe("sidechain-metadata");
+    expect(result.sessions[0]!.cwd).toBe(cwd);
+    expect(result.sessions[0]!.title).toBe("Correct primary title");
+  });
+
+  it("skips entries without cwd when cwd filter is not provided", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const filePath = path.join(projectDir, "no-cwd.jsonl");
+    fs.writeFileSync(filePath, JSON.stringify({ sessionId: "no-cwd", type: "summary" }) + "\n");
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions).toHaveLength(0);
+  });
+
+  it("returns null title when no user message exists", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    // Write file with only init and assistant message
+    const filePath = path.join(projectDir, "no-user.jsonl");
+    fs.writeFileSync(
+      filePath,
+      [
+        JSON.stringify({ sessionId: "no-user", type: "init" }),
+        JSON.stringify({ type: "assistant", cwd, message: { content: "Hi" } }),
+      ].join("\n"),
+    );
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.title).toBeNull();
+  });
+
+  describe("pagination", () => {
+    it("returns nextCursor when there are more results", async () => {
+      // Create 60 sessions (more than PAGE_SIZE of 50)
+      for (let i = 0; i < 60; i++) {
+        writeSessionFile("/Users/test/project", `sess-${i.toString().padStart(3, "0")}`, {
+          userMessage: `Session ${i}`,
+          mtime: new Date(Date.now() - i * 1000), // Each older by 1 second
+        });
+      }
+
+      const result = await agent.unstable_listSessions({});
+
+      expect(result.sessions).toHaveLength(50);
+      expect(result.nextCursor).toBeDefined();
+    });
+
+    it("does not return nextCursor when all results fit in one page", async () => {
+      for (let i = 0; i < 10; i++) {
+        writeSessionFile("/Users/test/project", `sess-${i}`, { userMessage: `Session ${i}` });
+      }
+
+      const result = await agent.unstable_listSessions({});
+
+      expect(result.sessions).toHaveLength(10);
+      expect(result.nextCursor).toBeUndefined();
+    });
+
+    it("returns next page when cursor is provided", async () => {
+      // Create 60 sessions
+      for (let i = 0; i < 60; i++) {
+        writeSessionFile("/Users/test/project", `sess-${i.toString().padStart(3, "0")}`, {
+          userMessage: `Session ${i}`,
+          mtime: new Date(Date.now() - i * 1000),
+        });
+      }
+
+      // Get first page
+      const firstPage = await agent.unstable_listSessions({});
+      expect(firstPage.sessions).toHaveLength(50);
+      expect(firstPage.nextCursor).toBeDefined();
+
+      // Get second page
+      const secondPage = await agent.unstable_listSessions({ cursor: firstPage.nextCursor });
+      expect(secondPage.sessions).toHaveLength(10);
+      expect(secondPage.nextCursor).toBeUndefined();
+    });
+
+    it("handles invalid cursor gracefully (starts from beginning)", async () => {
+      writeSessionFile("/Users/test/project", "sess-1", { userMessage: "Test" });
+
+      const result = await agent.unstable_listSessions({ cursor: "invalid-base64!" });
+
+      expect(result.sessions).toHaveLength(1);
+    });
+
+    it("handles malformed cursor JSON gracefully", async () => {
+      writeSessionFile("/Users/test/project", "sess-1", { userMessage: "Test" });
+
+      // Valid base64 but not valid JSON
+      const badCursor = Buffer.from("not json").toString("base64");
+      const result = await agent.unstable_listSessions({ cursor: badCursor });
+
+      expect(result.sessions).toHaveLength(1);
+    });
+  });
+
+  describe("Windows path support", () => {
+    it("decodes Windows-style paths correctly", async () => {
+      // Simulate a Windows path encoded as "C-Users-test-project"
+      const windowsCwd = "C:\\Users\\test\\project";
+      writeSessionFile(windowsCwd, "win-session", { userMessage: "Windows test" });
+
+      const result = await agent.unstable_listSessions({});
+
+      expect(result.sessions).toHaveLength(1);
+      expect(result.sessions[0]!.cwd).toBe("C:\\Users\\test\\project");
+      expect(result.sessions[0]!.sessionId).toBe("win-session");
+    });
+
+    it("filters Windows paths by cwd correctly", async () => {
+      writeSessionFile("C:\\Users\\test\\projectone", "win-a", { userMessage: "A" });
+      writeSessionFile("C:\\Users\\test\\projecttwo", "win-b", { userMessage: "B" });
+
+      const result = await agent.unstable_listSessions({ cwd: "C:\\Users\\test\\projectone" });
+
+      expect(result.sessions).toHaveLength(1);
+      expect(result.sessions[0]!.sessionId).toBe("win-a");
+    });
+
+    it("handles mixed Unix and Windows paths", async () => {
+      writeSessionFile("/Users/test/unixproject", "unix-session", { userMessage: "Unix" });
+      writeSessionFile("C:\\Users\\test\\winproject", "win-session", { userMessage: "Windows" });
+
+      const result = await agent.unstable_listSessions({});
+
+      expect(result.sessions).toHaveLength(2);
+      const cwds = result.sessions.map((s) => s.cwd);
+      expect(cwds).toContain("/Users/test/unixproject");
+      expect(cwds).toContain("C:\\Users\\test\\winproject");
+    });
+  });
+});

src/tests/load-session.test.ts

@@ -0,0 +1,320 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
+import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import { encodeProjectPath } from "../utils.js";
+
+const { registerHookCallbackSpy } = vi.hoisted(() => ({
+  registerHookCallbackSpy: vi.fn(),
+}));
+
+vi.mock("../tools.js", async () => {
+  const actual = await vi.importActual<typeof import("../tools.js")>("../tools.js");
+  return {
+    ...actual,
+    registerHookCallback: registerHookCallbackSpy,
+  };
+});
+
+describe("loadSession", () => {
+  let tempDir: string;
+  let originalClaudeConfigDir: string | undefined;
+  let agent: ClaudeAcpAgentType;
+  let ClaudeAcpAgent: typeof ClaudeAcpAgentType;
+  let sessionUpdates: SessionNotification[];
+  let createSessionSpy: ReturnType<typeof vi.fn>;
+
+  // Helper to create a mock AgentSideConnection
+  function createMockClient(): AgentSideConnection {
+    return {
+      sessionUpdate: async (notification: SessionNotification) => {
+        sessionUpdates.push(notification);
+      },
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AgentSideConnection;
+  }
+
+  function writeSessionFile(
+    cwd: string,
+    sessionId: string,
+    entries: Array<Record<string, unknown> | string>,
+  ): void {
+    const encodedPath = encodeProjectPath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    const filePath = path.join(projectDir, `${sessionId}.jsonl`);
+    const lines = entries.map((entry) =>
+      typeof entry === "string" ? entry : JSON.stringify(entry),
+    );
+    fs.writeFileSync(filePath, lines.join("\n"));
+  }
+
+  beforeEach(async () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "claude-load-session-"));
+    originalClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = tempDir;
+    sessionUpdates = [];
+    registerHookCallbackSpy.mockClear();
+
+    vi.resetModules();
+
+    const acpAgent = await import("../acp-agent.js");
+    ClaudeAcpAgent = acpAgent.ClaudeAcpAgent;
+
+    agent = new ClaudeAcpAgent(createMockClient());
+    createSessionSpy = vi.fn(async () => ({ modes: null, models: null }));
+    (agent as unknown as { createSession: typeof createSessionSpy }).createSession =
+      createSessionSpy;
+  });
+
+  afterEach(() => {
+    if (originalClaudeConfigDir !== undefined) {
+      process.env.CLAUDE_CONFIG_DIR = originalClaudeConfigDir;
+    } else {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    }
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("throws when the session file does not exist", async () => {
+    await expect(
+      agent.loadSession({
+        cwd: "/Users/test/project",
+        sessionId: "missing-session",
+        mcpServers: [],
+      }),
+    ).rejects.toThrow("Session not found");
+
+    expect(createSessionSpy).not.toHaveBeenCalled();
+  });
+
+  it("replays history and returns modes/models from createSession", async () => {
+    const cwd = "/Users/test/project";
+    const sessionId = "session-123";
+
+    writeSessionFile(cwd, sessionId, [
+      { type: "summary", summary: "ignored" },
+      {
+        type: "user",
+        sessionId,
+        message: { role: "user", content: "Hello" },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        message: {
+          role: "assistant",
+          content: [{ type: "thinking", thinking: "Thinking" }],
+        },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "Hi" }],
+        },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "tool_use",
+              id: "tool-1",
+              name: "Read",
+              input: { file_path: "/tmp/example.txt" },
+            },
+          ],
+        },
+      },
+      {
+        type: "user",
+        sessionId,
+        message: {
+          role: "user",
+          content: [{ type: "tool_result", tool_use_id: "tool-1", content: "ok" }],
+        },
+      },
+    ]);
+
+    const result = await agent.loadSession({ cwd, sessionId, mcpServers: [] });
+
+    expect(result).toEqual({ modes: null, models: null });
+    expect(createSessionSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ cwd, mcpServers: [] }),
+      { resume: sessionId },
+    );
+    expect(registerHookCallbackSpy).not.toHaveBeenCalled();
+
+    expect(sessionUpdates.map((notification) => notification.update.sessionUpdate)).toEqual([
+      "user_message_chunk",
+      "agent_thought_chunk",
+      "agent_message_chunk",
+      "tool_call",
+      "tool_call_update",
+    ]);
+
+    expect(sessionUpdates[0]?.update).toMatchObject({
+      sessionUpdate: "user_message_chunk",
+      content: { type: "text", text: "Hello" },
+    });
+    expect(sessionUpdates[1]?.update).toMatchObject({
+      sessionUpdate: "agent_thought_chunk",
+      content: { type: "text", text: "Thinking" },
+    });
+    expect(sessionUpdates[2]?.update).toMatchObject({
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "Hi" },
+    });
+    expect(sessionUpdates[3]?.update).toMatchObject({
+      sessionUpdate: "tool_call",
+      toolCallId: "tool-1",
+      status: "pending",
+    });
+    expect(sessionUpdates[4]?.update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "tool-1",
+      status: "completed",
+    });
+  });
+
+  it("skips sidechain, mismatched sessionId, invalid, and unsupported entries", async () => {
+    const cwd = "/Users/test/project";
+    const sessionId = "session-456";
+
+    writeSessionFile(cwd, sessionId, [
+      "{not valid json}",
+      { type: "summary", summary: "ignore" },
+      {
+        type: "user",
+        sessionId,
+        isSidechain: true,
+        message: { role: "user", content: "Sidechain" },
+      },
+      {
+        type: "assistant",
+        sessionId: "other-session",
+        message: { role: "assistant", content: "Wrong session" },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        message: { role: "system", content: "Unsupported role" },
+      },
+      {
+        type: "user",
+        sessionId,
+        message: { role: "user", content: 123 },
+      },
+      {
+        type: "user",
+        sessionId,
+        message: { role: "user", content: "Keep me" },
+      },
+    ]);
+
+    await agent.loadSession({ cwd, sessionId, mcpServers: [] });
+
+    expect(sessionUpdates).toHaveLength(1);
+    expect(sessionUpdates[0]?.update).toMatchObject({
+      sessionUpdate: "user_message_chunk",
+      content: { type: "text", text: "Keep me" },
+    });
+  });
+
+  it("finds session file when cwd differs from the original session cwd", async () => {
+    const originalCwd = "/Users/test/original-project";
+    const differentCwd = "/Users/test/different-project";
+    const sessionId = "cross-cwd-session";
+
+    // Session was created in originalCwd
+    writeSessionFile(originalCwd, sessionId, [
+      {
+        type: "user",
+        sessionId,
+        cwd: originalCwd,
+        message: { role: "user", content: "Hello from original" },
+      },
+    ]);
+
+    // Load with a different cwd
+    await agent.loadSession({ cwd: differentCwd, sessionId, mcpServers: [] });
+
+    expect(sessionUpdates).toHaveLength(1);
+    expect(sessionUpdates[0]?.update).toMatchObject({
+      sessionUpdate: "user_message_chunk",
+      content: { type: "text", text: "Hello from original" },
+    });
+    expect(createSessionSpy).toHaveBeenCalledWith(expect.objectContaining({ cwd: differentCwd }), {
+      resume: sessionId,
+    });
+  });
+
+  it("sends available_commands_update after history replay, not during", async () => {
+    const cwd = "/Users/test/project";
+    const sessionId = "session-commands";
+
+    // Mock createSession to populate the sessions map with a mock query
+    createSessionSpy.mockImplementationOnce(async () => {
+      (agent as unknown as { sessions: Record<string, unknown> }).sessions[sessionId] = {
+        query: {
+          supportedCommands: async () => [{ name: "help", description: "Get help" }],
+        },
+      };
+      return { modes: null, models: null };
+    });
+
+    writeSessionFile(cwd, sessionId, [
+      {
+        type: "user",
+        sessionId,
+        message: { role: "user", content: "Hello" },
+      },
+      {
+        type: "assistant",
+        sessionId,
+        message: { role: "assistant", content: [{ type: "text", text: "Hi" }] },
+      },
+    ]);
+
+    await agent.loadSession({ cwd, sessionId, mcpServers: [] });
+
+    // Flush the setTimeout + async work inside sendAvailableCommandsUpdate
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    const updateTypes = sessionUpdates.map((n) => n.update.sessionUpdate);
+
+    // available_commands_update should come AFTER all replay notifications
+    expect(updateTypes).toEqual([
+      "user_message_chunk",
+      "agent_message_chunk",
+      "available_commands_update",
+    ]);
+  });
+
+  it("handles Windows-style paths", async () => {
+    const cwd = "C:\\Users\\test\\project";
+    const sessionId = "win-session";
+
+    writeSessionFile(cwd, sessionId, [
+      {
+        type: "user",
+        sessionId,
+        message: { role: "user", content: "Hello" },
+      },
+    ]);
+
+    await agent.loadSession({ cwd, sessionId, mcpServers: [] });
+
+    expect(sessionUpdates).toHaveLength(1);
+    expect(sessionUpdates[0]?.sessionId).toBe(sessionId);
+  });
+});

src/tests/mcp-server-read.test.ts

@@ -1,72 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { createMcpServer } from "../mcp-server.js";
-
-const SESSION_ID = "session-id";
-
-function getTool(server: any, name: string) {
-  const tools = server?._registeredTools;
-  if (!tools || !tools[name]) {
-    throw new Error(`Tool ${name} not registered`);
-  }
-  return tools[name];
-}
-
-function createAgent(overrides: Record<string, unknown> = {}) {
-  return {
-    sessions: {
-      [SESSION_ID]: {},
-    },
-    readTextFile: vi.fn(),
-    writeTextFile: vi.fn(),
-    backgroundTerminals: {},
-    clientCapabilities: {},
-    client: {
-      sessionUpdate: vi.fn(),
-      createTerminal: vi.fn(),
-      requestPermission: vi.fn(),
-    },
-    ...overrides,
-  };
-}
-
-describe("MCP server read-related tools", () => {
-  it("reports missing file contents instead of crashing the read tool", async () => {
-    const agent = createAgent();
-    agent.readTextFile.mockResolvedValue({});
-
-    const server = createMcpServer(agent as any, SESSION_ID, {
-      fs: { readTextFile: true },
-    });
-
-    const readTool = getTool(server, "Read");
-
-    const result = await readTool.callback({
-      file_path: "/tmp/file.txt",
-      offset: 1,
-      limit: 2000,
-    });
-
-    expect(result.content[0].text).toBe("Reading file failed: No file contents for /tmp/file.txt.");
-  });
-
-  it("reports missing contents inside the edit tool and skips writes", async () => {
-    const agent = createAgent();
-    agent.readTextFile.mockResolvedValue({});
-
-    const server = createMcpServer(agent as any, SESSION_ID, {
-      fs: { readTextFile: true, writeTextFile: true },
-    });
-
-    const editTool = getTool(server, "Edit");
-
-    const result = await editTool.callback({
-      file_path: "/tmp/file.txt",
-      old_string: "foo",
-      new_string: "bar",
-      replace_all: false,
-    });
-
-    expect(result.content[0].text).toBe("Editing file failed: No file contents for /tmp/file.txt.");
-    expect(agent.writeTextFile).not.toHaveBeenCalled();
-  });
-});

src/tests/replace-and-calculate-location.test.ts

@@ -1,334 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { replaceAndCalculateLocation } from "../mcp-server.js";
-
-describe("replaceAndCalculateLocation", () => {
-  it("should replace first occurrence and return correct line number", () => {
-    const content = "line 1\nline 2 with text\nline 3 with text\nline 4";
-    const result = replaceAndCalculateLocation(content, [{ oldText: "text", newText: "replaced" }]);
-
-    expect(result.newContent).toBe("line 1\nline 2 with replaced\nline 3 with text\nline 4");
-    expect(result.lineNumbers).toEqual([1]); // Line 2 (0-based indexing)
-  });
-
-  it("should replace all occurrences when replaceAll is true", () => {
-    const content = "line 1\nline 2 with text\nline 3 with text\nline 4";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "text", newText: "replaced", replaceAll: true },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nline 2 with replaced\nline 3 with replaced\nline 4");
-    expect(result.lineNumbers).toEqual([1, 2]); // Lines 2 and 3 (0-based)
-  });
-
-  it("should return empty line numbers array when no match found", () => {
-    const content = "line 1\nline 2\nline 3";
-    expect(() => {
-      replaceAndCalculateLocation(content, [{ oldText: "notfound", newText: "replaced" }]);
-    }).toThrow('The provided `old_string` does not appear in the file: "notfound"');
-  });
-
-  it("should handle Windows line endings (CRLF)", () => {
-    const content = "line 1\r\nline 2 with text\r\nline 3 with text\r\nline 4";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "text", newText: "replaced", replaceAll: true },
-    ]);
-
-    expect(result.newContent).toBe(
-      "line 1\r\nline 2 with replaced\r\nline 3 with replaced\r\nline 4",
-    );
-    expect(result.lineNumbers).toEqual([1, 2]);
-  });
-
-  it("should handle old Mac line endings (CR)", () => {
-    const content = "line 1\rline 2 with text\rline 3 with text\rline 4";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "text", newText: "replaced", replaceAll: true },
-    ]);
-
-    expect(result.newContent).toBe("line 1\rline 2 with replaced\rline 3 with replaced\rline 4");
-    expect(result.lineNumbers).toEqual([1, 2]);
-  });
-
-  it("should handle mixed line endings", () => {
-    const content = "line 1\nline 2 with text\r\nline 3 with text\rline 4";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "text", newText: "replaced", replaceAll: true },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nline 2 with replaced\r\nline 3 with replaced\rline 4");
-    expect(result.lineNumbers).toEqual([1, 2]);
-  });
-
-  it("should handle text at the beginning of file", () => {
-    const content = "text at start\nline 2\nline 3";
-    const result = replaceAndCalculateLocation(content, [{ oldText: "text", newText: "replaced" }]);
-
-    expect(result.newContent).toBe("replaced at start\nline 2\nline 3");
-    expect(result.lineNumbers).toEqual([0]); // First line (0-based)
-  });
-
-  it("should handle text at the end of file", () => {
-    const content = "line 1\nline 2\nlast line with text";
-    const result = replaceAndCalculateLocation(content, [{ oldText: "text", newText: "replaced" }]);
-
-    expect(result.newContent).toBe("line 1\nline 2\nlast line with replaced");
-    expect(result.lineNumbers).toEqual([2]); // Last line (0-based)
-  });
-
-  it("should handle multiple occurrences on the same line", () => {
-    const content = "line 1\ntext text text\nline 3";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "text", newText: "replaced", replaceAll: true },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nreplaced replaced replaced\nline 3");
-    expect(result.lineNumbers).toEqual([1]); // All on line 2 (0-based), deduplicated
-  });
-
-  it("should handle empty file content", () => {
-    expect(() => {
-      replaceAndCalculateLocation("", [{ oldText: "text", newText: "replaced" }]);
-    }).toThrowError(
-      'The provided `old_string` does not appear in the file: "text".\n\nNo edits were applied.',
-    );
-  });
-
-  it("should handle empty search text", () => {
-    // Test with replaceAll false (default)
-    const content1 = "line 1\nline 2\nline 3";
-    expect(() => {
-      replaceAndCalculateLocation(content1, [{ oldText: "", newText: "replaced" }]);
-    }).toThrowError("The provided `old_string` is empty.\n\nNo edits were applied.");
-
-    // Test with replaceAll true on single line
-    const content2 = "abc";
-    expect(() => {
-      replaceAndCalculateLocation(content2, [{ oldText: "", newText: "X", replaceAll: true }]);
-    }).toThrowError("The provided `old_string` is empty.\n\nNo edits were applied.");
-
-    // Test with replaceAll true on multiline content
-    const content3 = "ab\ncd";
-    expect(() => {
-      replaceAndCalculateLocation(content3, [{ oldText: "", newText: "X", replaceAll: true }]);
-    }).toThrowError("The provided `old_string` is empty.\n\nNo edits were applied.");
-  });
-
-  it("should handle single line content", () => {
-    const content = "single line with text here";
-    const result = replaceAndCalculateLocation(content, [{ oldText: "text", newText: "replaced" }]);
-
-    expect(result.newContent).toBe("single line with replaced here");
-    expect(result.lineNumbers).toEqual([0]); // Line 1 (0-based)
-  });
-
-  it("should handle special characters in search text", () => {
-    const content = "line 1\nline with $special.chars*\nline 3";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "$special.chars*", newText: "replaced" },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nline with replaced\nline 3");
-    expect(result.lineNumbers).toEqual([1]);
-  });
-
-  it("should handle newlines in search text", () => {
-    const content = "line 1\nline 2\nline 3";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "1\nline", newText: "1\nmodified line" },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nmodified line 2\nline 3");
-    expect(result.lineNumbers).toEqual([0]); // Match starts at line 1 (0-based)
-  });
-
-  it("should handle newlines in replacement text", () => {
-    const content = "line 1\nline 2\nline 3";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "line 2", newText: "line 2a\nline 2b" },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nline 2a\nline 2b\nline 3");
-    expect(result.lineNumbers).toEqual([1]);
-  });
-
-  it("should handle very long lines", () => {
-    const longLine = "a".repeat(10000) + "text" + "b".repeat(10000);
-    const content = `line 1\n${longLine}\nline 3`;
-    const result = replaceAndCalculateLocation(content, [{ oldText: "text", newText: "replaced" }]);
-
-    expect(result.newContent).toBe(
-      `line 1\n${"a".repeat(10000)}replaced${"b".repeat(10000)}\nline 3`,
-    );
-    expect(result.lineNumbers).toEqual([1]);
-  });
-
-  it("should handle many lines", () => {
-    const lines = Array.from({ length: 1000 }, (_, i) => `line ${i}`);
-    lines[500] = "line with text";
-    const content = lines.join("\n");
-
-    const result = replaceAndCalculateLocation(content, [{ oldText: "text", newText: "replaced" }]);
-
-    expect(result.lineNumbers).toEqual([500]);
-    expect(result.newContent).includes("line with replaced");
-  });
-
-  it("should handle overlapping matches correctly", () => {
-    const content = "aaaa\nbbbb\ncccc";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "aa", newText: "xx", replaceAll: true },
-    ]);
-
-    // Should replace non-overlapping occurrences
-    expect(result.newContent).toBe("xxxx\nbbbb\ncccc");
-    expect(result.lineNumbers).toEqual([0]); // Two matches on first line, deduplicated
-  });
-
-  it("should preserve content after replacement with different lengths", () => {
-    const content = "short\nmedium line\nlong line here";
-
-    // Replacing with longer text
-    const result1 = replaceAndCalculateLocation(content, [
-      { oldText: "short", newText: "very very long text" },
-    ]);
-    expect(result1.newContent).toBe("very very long text\nmedium line\nlong line here");
-    expect(result1.lineNumbers).toEqual([0]);
-
-    // Replacing with shorter text
-    const result2 = replaceAndCalculateLocation(content, [
-      { oldText: "medium line", newText: "m" },
-    ]);
-    expect(result2.newContent).toBe("short\nm\nlong line here");
-    expect(result2.lineNumbers).toEqual([1]);
-  });
-
-  it("should handle consecutive replacements", () => {
-    const content = "text1 text2 text3";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "text", newText: "replaced", replaceAll: true },
-    ]);
-
-    expect(result.newContent).toBe("replaced1 replaced2 replaced3");
-    expect(result.lineNumbers).toEqual([0]); // All on first line, deduplicated
-  });
-
-  it("should handle case-sensitive replacements", () => {
-    const content = "Text TEXT text";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "text", newText: "replaced", replaceAll: true },
-    ]);
-
-    // Should only replace exact matches
-    expect(result.newContent).toBe("Text TEXT replaced");
-    expect(result.lineNumbers).toEqual([0]); // Only lowercase "text" matched
-  });
-
-  it("should handle replacement at exact end of line", () => {
-    const content = "line ends with text\nnext line";
-    const result = replaceAndCalculateLocation(content, [{ oldText: "text", newText: "replaced" }]);
-
-    expect(result.newContent).toBe("line ends with replaced\nnext line");
-    expect(result.lineNumbers).toEqual([0]);
-  });
-
-  it("should handle replacement spanning multiple lines", () => {
-    const content = "line 1\nspan\nacross\nlines\nline 5";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "span\nacross\nlines", newText: "single" },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nsingle\nline 5");
-    expect(result.lineNumbers).toEqual([1]); // Match starts at line 2 (0-based)
-  });
-
-  it("should default replaceAll to false", () => {
-    const content = "match match match";
-
-    // Without passing replaceAll parameter
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "match", newText: "replaced" },
-    ]);
-
-    expect(result.newContent).toBe("replaced match match");
-    expect(result.lineNumbers).toEqual([0]); // Only first match
-  });
-
-  it("should handle multiple edits with correct line numbers", () => {
-    const content = "line 1\nfoo bar\nline 3\nfoo baz\nline 5\nbar foo\nline 7";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "foo", newText: "FOO", replaceAll: true },
-      { oldText: "bar", newText: "BAR", replaceAll: false },
-      { oldText: "line 3", newText: "LINE THREE" },
-    ]);
-
-    // Should replace:
-    // - All "foo" occurrences (lines 1, 3, 5 in original)
-    // - First "bar" occurrence (line 1 after first edit)
-    // - "line 3" (line 2 after previous edits)
-    expect(result.newContent).toBe("line 1\nFOO BAR\nLINE THREE\nFOO baz\nline 5\nbar FOO\nline 7");
-
-    // Line numbers reflect position in final content, deduplicated and sorted
-    expect(result.lineNumbers).toEqual([
-      1, // FOO and BAR on line 1
-      2, // LINE THREE on line 2
-      3, // FOO on line 3
-      5, // FOO on line 5
-    ]);
-  });
-
-  it("should handle multiple edits with overlapping text", () => {
-    const content = "hello world\nhello hello\nworld hello world";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "hello", newText: "hi", replaceAll: false },
-      { oldText: "world", newText: "earth", replaceAll: true },
-      { oldText: "hello", newText: "greetings", replaceAll: true },
-    ]);
-
-    // First edit replaces first "hello" only
-    // Second edit replaces all "world" in the modified content
-    // Third edit replaces remaining "hello"s in the modified content
-    expect(result.newContent).toBe("hi earth\ngreetings greetings\nearth greetings earth");
-
-    // Line numbers reflect position in final content, deduplicated and sorted
-    expect(result.lineNumbers).toEqual([
-      0, // hi and earth on line 0
-      1, // greetings (multiple) on line 1
-      2, // earth and greetings on line 2
-    ]);
-  });
-
-  it("should handle complex scenarios with marker-like text", () => {
-    // Test that our marker approach doesn't get confused by similar text
-    const content = "line 1\n__MARKER__text\nline 3\n__REPLACE_MARKER_abc__\nline 5";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "__MARKER__", newText: "REPLACED", replaceAll: true },
-      { oldText: "text", newText: "content" },
-      { oldText: "__REPLACE_MARKER_abc__", newText: "DONE" },
-    ]);
-
-    expect(result.newContent).toBe("line 1\nREPLACEDcontent\nline 3\nDONE\nline 5");
-
-    // Line numbers should be correct even with marker-like text
-    expect(result.lineNumbers).toEqual([
-      1, // REPLACED on line 1
-      3, // DONE on line 3
-    ]);
-  });
-
-  it("should handle edits where newText matches subsequent oldText", () => {
-    const content = "foo\nbar\nbaz";
-    const result = replaceAndCalculateLocation(content, [
-      { oldText: "foo", newText: "bar" },
-      { oldText: "bar", newText: "baz", replaceAll: true },
-      { oldText: "baz", newText: "qux", replaceAll: true },
-    ]);
-
-    // First edit: foo -> bar
-    // Second edit: both original bar and new bar -> baz
-    // Third edit: all baz instances -> qux
-    expect(result.newContent).toBe("qux\nqux\nqux");
-
-    // All replacements end up on their respective lines
-    expect(result.lineNumbers).toEqual([0, 1, 2]);
-  });
-});

src/tests/session-config-options.test.ts

@@ -0,0 +1,418 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
+import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+
+const { registerHookCallbackSpy } = vi.hoisted(() => ({
+  registerHookCallbackSpy: vi.fn(),
+}));
+
+vi.mock("../tools.js", async () => {
+  const actual = await vi.importActual<typeof import("../tools.js")>("../tools.js");
+  return {
+    ...actual,
+    registerHookCallback: registerHookCallbackSpy,
+  };
+});
+
+const SESSION_ID = "test-session-id";
+
+const MOCK_MODES = {
+  currentModeId: "default",
+  availableModes: [
+    { id: "default", name: "Default", description: "Standard behavior" },
+    { id: "plan", name: "Plan Mode", description: "Planning mode" },
+    { id: "acceptEdits", name: "Accept Edits", description: "Auto-accept edits" },
+  ],
+};
+
+const MOCK_MODELS = {
+  currentModelId: "claude-opus-4-5",
+  availableModels: [
+    { modelId: "claude-opus-4-5", name: "Claude Opus", description: "Most capable" },
+    { modelId: "claude-sonnet-4-5", name: "Claude Sonnet", description: "Balanced" },
+  ],
+};
+
+const MOCK_CONFIG_OPTIONS = [
+  {
+    id: "mode",
+    name: "Mode",
+    type: "select",
+    category: "mode",
+    currentValue: "default",
+    options: MOCK_MODES.availableModes.map((m) => ({
+      value: m.id,
+      name: m.name,
+      description: m.description,
+    })),
+  },
+  {
+    id: "model",
+    name: "Model",
+    type: "select",
+    category: "model",
+    currentValue: "claude-opus-4-5",
+    options: MOCK_MODELS.availableModels.map((m) => ({
+      value: m.modelId,
+      name: m.name,
+      description: m.description,
+    })),
+  },
+];
+
+describe("session config options", () => {
+  let agent: ClaudeAcpAgentType;
+  let ClaudeAcpAgent: typeof ClaudeAcpAgentType;
+  let sessionUpdates: SessionNotification[];
+  let createSessionSpy: ReturnType<typeof vi.fn>;
+  let setPermissionModeSpy: ReturnType<typeof vi.fn>;
+  let setModelSpy: ReturnType<typeof vi.fn>;
+
+  function createMockClient(): AgentSideConnection {
+    return {
+      sessionUpdate: async (notification: SessionNotification) => {
+        sessionUpdates.push(notification);
+      },
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AgentSideConnection;
+  }
+
+  function populateSession() {
+    setPermissionModeSpy = vi.fn();
+    setModelSpy = vi.fn();
+
+    (agent as unknown as { sessions: Record<string, unknown> }).sessions[SESSION_ID] = {
+      query: {
+        setPermissionMode: setPermissionModeSpy,
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      },
+      input: null,
+      cancelled: false,
+      permissionMode: "default",
+      settingsManager: {},
+      configOptions: structuredClone(MOCK_CONFIG_OPTIONS),
+    };
+  }
+
+  beforeEach(async () => {
+    sessionUpdates = [];
+    registerHookCallbackSpy.mockClear();
+
+    vi.resetModules();
+    const acpAgent = await import("../acp-agent.js");
+    ClaudeAcpAgent = acpAgent.ClaudeAcpAgent;
+
+    agent = new ClaudeAcpAgent(createMockClient());
+    createSessionSpy = vi.fn(async () => ({
+      sessionId: SESSION_ID,
+      modes: MOCK_MODES,
+      models: MOCK_MODELS,
+      configOptions: MOCK_CONFIG_OPTIONS,
+    }));
+    (agent as unknown as { createSession: typeof createSessionSpy }).createSession =
+      createSessionSpy;
+  });
+
+  describe("newSession returns configOptions", () => {
+    it("includes configOptions in the response", async () => {
+      const response = await agent.newSession({ cwd: "/test", 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 modeOption = response.configOptions?.find((o) => o.id === "mode");
+      const modelOption = response.configOptions?.find((o) => o.id === "model");
+      expect(modeOption).toBeDefined();
+      expect(modelOption).toBeDefined();
+    });
+  });
+
+  describe("loadSession returns configOptions", () => {
+    it("includes configOptions from createSession", async () => {
+      // loadSession calls findSessionFile first - override the whole method
+      const loadSessionSpy = vi.fn(async () => ({
+        modes: MOCK_MODES,
+        models: MOCK_MODELS,
+        configOptions: MOCK_CONFIG_OPTIONS,
+      }));
+      (agent as unknown as { loadSession: typeof loadSessionSpy }).loadSession = loadSessionSpy;
+
+      const response = await agent.loadSession({
+        cwd: "/test",
+        sessionId: SESSION_ID,
+        mcpServers: [],
+      });
+      expect(response.configOptions).toEqual(MOCK_CONFIG_OPTIONS);
+    });
+  });
+
+  describe("setSessionConfigOption", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("throws when session not found", async () => {
+      await expect(
+        agent.setSessionConfigOption({
+          sessionId: "nonexistent",
+          configId: "mode",
+          value: "plan",
+        }),
+      ).rejects.toThrow("Session not found");
+    });
+
+    it("throws when config option not found", async () => {
+      await expect(
+        agent.setSessionConfigOption({
+          sessionId: SESSION_ID,
+          configId: "unknown-option",
+          value: "some-value",
+        }),
+      ).rejects.toThrow("Unknown config option: unknown-option");
+    });
+
+    it("throws when value is not valid for the option", async () => {
+      await expect(
+        agent.setSessionConfigOption({
+          sessionId: SESSION_ID,
+          configId: "mode",
+          value: "invalid-mode",
+        }),
+      ).rejects.toThrow("Invalid value for config option mode: invalid-mode");
+    });
+
+    it("changes mode, sends current_mode_update but not config_option_update", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "mode",
+        value: "plan",
+      });
+
+      expect(setPermissionModeSpy).toHaveBeenCalledWith("plan");
+
+      const modeUpdate = sessionUpdates.find(
+        (n) => n.update.sessionUpdate === "current_mode_update",
+      );
+      expect(modeUpdate?.update).toMatchObject({
+        sessionUpdate: "current_mode_update",
+        currentModeId: "plan",
+      });
+
+      const configUpdate = sessionUpdates.find(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdate).toBeUndefined();
+    });
+
+    it("changes model and does not send a config_option_update notification", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-5",
+      });
+
+      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-5");
+
+      const configUpdate = sessionUpdates.find(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdate).toBeUndefined();
+    });
+
+    it("returns full configOptions in the response", async () => {
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "mode",
+        value: "plan",
+      });
+
+      expect(response.configOptions).toHaveLength(MOCK_CONFIG_OPTIONS.length);
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect(modeOption?.currentValue).toBe("plan");
+    });
+
+    it("other options are unchanged when one is updated", async () => {
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "mode",
+        value: "plan",
+      });
+
+      const modelOption = response.configOptions.find((o) => o.id === "model");
+      expect(modelOption?.currentValue).toBe("claude-opus-4-5");
+    });
+  });
+
+  describe("setSessionMode sends config_option_update", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("sends config_option_update when mode is changed via setSessionMode", async () => {
+      await agent.setSessionMode({ sessionId: SESSION_ID, modeId: "acceptEdits" });
+
+      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.objectContaining({ id: "mode", currentValue: "acceptEdits" }),
+        ]),
+      });
+    });
+
+    it("updates stored configOptions currentValue when mode changes", async () => {
+      await agent.setSessionMode({ sessionId: SESSION_ID, modeId: "plan" });
+
+      const session = (
+        agent as unknown as {
+          sessions: Record<string, { configOptions: typeof MOCK_CONFIG_OPTIONS }>;
+        }
+      ).sessions[SESSION_ID];
+      const modeOption = session.configOptions.find((o) => o.id === "mode");
+      expect(modeOption?.currentValue).toBe("plan");
+    });
+
+    it("does not send config_option_update for an invalid mode", async () => {
+      await expect(
+        agent.setSessionMode({ sessionId: SESSION_ID, modeId: "not-a-mode" as any }),
+      ).rejects.toThrow("Invalid Mode");
+
+      const configUpdate = sessionUpdates.find(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdate).toBeUndefined();
+    });
+  });
+
+  describe("unstable_setSessionModel sends config_option_update", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("sends config_option_update when model is changed via setSessionModel", async () => {
+      await agent.unstable_setSessionModel({
+        sessionId: SESSION_ID,
+        modelId: "claude-sonnet-4-5",
+      });
+
+      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.objectContaining({ id: "model", currentValue: "claude-sonnet-4-5" }),
+        ]),
+      });
+    });
+
+    it("updates stored configOptions currentValue when model changes", async () => {
+      await agent.unstable_setSessionModel({
+        sessionId: SESSION_ID,
+        modelId: "claude-sonnet-4-5",
+      });
+
+      const session = (
+        agent as unknown as {
+          sessions: Record<string, { configOptions: typeof MOCK_CONFIG_OPTIONS }>;
+        }
+      ).sessions[SESSION_ID];
+      const modelOption = session.configOptions.find((o) => o.id === "model");
+      expect(modelOption?.currentValue).toBe("claude-sonnet-4-5");
+    });
+  });
+
+  describe("no config_option_update notification when using setSessionConfigOption", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("sends no config_option_update when setting mode via config option", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "mode",
+        value: "plan",
+      });
+
+      const configUpdates = sessionUpdates.filter(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdates).toHaveLength(0);
+    });
+
+    it("sends no config_option_update when setting model via config option", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-5",
+      });
+
+      const configUpdates = sessionUpdates.filter(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdates).toHaveLength(0);
+    });
+  });
+
+  describe("bidirectional consistency", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("setSessionConfigOption for mode also calls underlying setPermissionMode", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "mode",
+        value: "acceptEdits",
+      });
+
+      expect(setPermissionModeSpy).toHaveBeenCalledWith("acceptEdits");
+    });
+
+    it("setSessionConfigOption for model also calls underlying setModel", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-5",
+      });
+
+      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-5");
+    });
+
+    it("setSessionMode also syncs configOptions", async () => {
+      await agent.setSessionMode({ sessionId: SESSION_ID, modeId: "plan" });
+
+      const session = (
+        agent as unknown as {
+          sessions: Record<string, { configOptions: typeof MOCK_CONFIG_OPTIONS }>;
+        }
+      ).sessions[SESSION_ID];
+      expect(session.configOptions.find((o) => o.id === "mode")?.currentValue).toBe("plan");
+    });
+
+    it("setSessionModel also syncs configOptions", async () => {
+      await agent.unstable_setSessionModel({
+        sessionId: SESSION_ID,
+        modelId: "claude-sonnet-4-5",
+      });
+
+      const session = (
+        agent as unknown as {
+          sessions: Record<string, { configOptions: typeof MOCK_CONFIG_OPTIONS }>;
+        }
+      ).sessions[SESSION_ID];
+      expect(session.configOptions.find((o) => o.id === "model")?.currentValue).toBe(
+        "claude-sonnet-4-5",
+      );
+    });
+  });
+});

src/tests/settings.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SettingsManager } from "../settings.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+describe("SettingsManager", () => {
+  let tempDir: string;
+  let settingsManager: SettingsManager;
+
+  beforeEach(async () => {
+    tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "settings-test-"));
+  });
+
+  afterEach(async () => {
+    settingsManager?.dispose();
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe("settings merging", () => {
+    it("should merge model setting with later sources taking precedence", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+
+      // Project settings with one model
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          model: "claude-3-5-sonnet",
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      let settings = settingsManager.getSettings();
+      expect(settings.model).toBe("claude-3-5-sonnet");
+
+      // Add local settings that override the model
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.local.json"),
+        JSON.stringify({
+          model: "claude-3-5-haiku",
+        }),
+      );
+
+      // Re-initialize to pick up local settings
+      settingsManager.dispose();
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      settings = settingsManager.getSettings();
+      expect(settings.model).toBe("claude-3-5-haiku");
+    });
+  });
+});

src/tools.ts

@@ -1,16 +1,80 @@
-import { PlanEntry, ToolCallContent, ToolCallLocation, ToolKind } from "@agentclientprotocol/sdk";
-import { replaceAndCalculateLocation, SYSTEM_REMINDER, toolNames } from "./mcp-server.js";
-import { ToolResultBlockParam, WebSearchToolResultBlockParam } from "@anthropic-ai/sdk/resources";
+import {
+  ContentBlock,
+  PlanEntry,
+  ToolCallContent,
+  ToolCallLocation,
+  ToolKind,
+} from "@agentclientprotocol/sdk";
+import {
+  ImageBlockParam,
+  TextBlockParam,
+  ToolResultBlockParam,
+  WebSearchResultBlock,
+  WebSearchToolResultBlockParam,
+  WebSearchToolResultError,
+} from "@anthropic-ai/sdk/resources";
 import {
   BetaBashCodeExecutionToolResultBlockParam,
+  BetaBashCodeExecutionResultBlock,
+  BetaBashCodeExecutionToolResultError,
   BetaCodeExecutionToolResultBlockParam,
+  BetaCodeExecutionResultBlock,
+  BetaCodeExecutionToolResultError,
   BetaRequestMCPToolResultBlockParam,
   BetaTextEditorCodeExecutionToolResultBlockParam,
+  BetaTextEditorCodeExecutionViewResultBlock,
+  BetaTextEditorCodeExecutionCreateResultBlock,
+  BetaTextEditorCodeExecutionStrReplaceResultBlock,
+  BetaTextEditorCodeExecutionToolResultError,
+  BetaToolResultBlockParam,
   BetaToolSearchToolResultBlockParam,
+  BetaToolReferenceBlock,
+  BetaToolSearchToolSearchResultBlock,
+  BetaToolSearchToolResultError,
   BetaWebFetchToolResultBlockParam,
+  BetaWebFetchBlock,
+  BetaWebFetchToolResultErrorBlock,
   BetaWebSearchToolResultBlockParam,
+  BetaImageBlockParam,
 } from "@anthropic-ai/sdk/resources/beta.mjs";
+
+/**
+ * Union of all possible content types that can appear in tool results from the Anthropic SDK.
+ * These are transformed to valid ACP ContentBlock types by toValidAcpContent().
+ */
+type ToolResultContent =
+  | TextBlockParam
+  | ImageBlockParam
+  | BetaImageBlockParam
+  | BetaToolReferenceBlock
+  | BetaToolSearchToolSearchResultBlock
+  | BetaToolSearchToolResultError
+  | WebSearchResultBlock
+  | WebSearchToolResultError
+  | BetaWebFetchBlock
+  | BetaWebFetchToolResultErrorBlock
+  | BetaCodeExecutionResultBlock
+  | BetaCodeExecutionToolResultError
+  | BetaBashCodeExecutionResultBlock
+  | BetaBashCodeExecutionToolResultError
+  | BetaTextEditorCodeExecutionViewResultBlock
+  | BetaTextEditorCodeExecutionCreateResultBlock
+  | BetaTextEditorCodeExecutionStrReplaceResultBlock
+  | BetaTextEditorCodeExecutionToolResultError;
 import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { Logger } from "./acp-agent.js";
+import {
+  AgentInput,
+  BashInput,
+  FileEditInput,
+  FileReadInput,
+  FileWriteInput,
+  GlobInput,
+  GrepInput,
+  TodoWriteInput,
+  WebFetchInput,
+  WebSearchInput,
+} from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 
 interface ToolInfo {
   title: string;
@@ -23,22 +87,36 @@ interface ToolUpdate {
   title?: string;
   content?: ToolCallContent[];
   locations?: ToolCallLocation[];
+  _meta?: {
+    terminal_info?: {
+      terminal_id: string;
+    };
+    terminal_output?: {
+      terminal_id: string;
+      data: string;
+    };
+    terminal_exit?: {
+      terminal_id: string;
+      exit_code: number;
+      signal: string | null;
+    };
+  };
 }
 
 export function toolInfoFromToolUse(
   toolUse: any,
-  cachedFileContent: { [key: string]: string },
+  supportsTerminalOutput: boolean = false,
 ): ToolInfo {
   const name = toolUse.name;
-  const input = toolUse.input;
 
   switch (name) {
-    case "Task":
+    case "Task": {
+      const input = toolUse.input as AgentInput | BashInput;
       return {
         title: input?.description ? input.description : "Task",
         kind: "think",
         content:
-          input && input.prompt
+          input && "prompt" in input
             ? [
                 {
                   type: "content",
@@ -47,38 +125,16 @@ export function toolInfoFromToolUse(
               ]
             : [],
       };
+    }
 
-    case "NotebookRead":
+    case "Bash": {
+      const input = toolUse.input as BashInput;
       return {
-        title: input?.notebook_path ? `Read Notebook ${input.notebook_path}` : "Read Notebook",
-        kind: "read",
-        content: [],
-        locations: input?.notebook_path ? [{ path: input.notebook_path }] : [],
-      };
-
-    case "NotebookEdit":
-      return {
-        title: input?.notebook_path ? `Edit Notebook ${input.notebook_path}` : "Edit Notebook",
-        kind: "edit",
-        content:
-          input && input.new_source
-            ? [
-                {
-                  type: "content",
-                  content: { type: "text", text: input.new_source },
-                },
-              ]
-            : [],
-        locations: input?.notebook_path ? [{ path: input.notebook_path }] : [],
-      };
-
-    case "Bash":
-    case toolNames.bash:
-      return {
-        title: input?.command ? "`" + input.command.replaceAll("`", "\\`") + "`" : "Terminal",
+        title: input?.command ? input.command : "Terminal",
         kind: "execute",
-        content:
-          input && input.description
+        content: supportsTerminalOutput
+          ? [{ type: "terminal" as const, terminalId: toolUse.id }]
+          : input && input.description
             ? [
                 {
                   type: "content",
@@ -87,30 +143,15 @@ export function toolInfoFromToolUse(
               ]
             : [],
       };
+    }
 
-    case "BashOutput":
-    case toolNames.bashOutput:
-      return {
-        title: "Tail Logs",
-        kind: "execute",
-        content: [],
-      };
-
-    case "KillShell":
-    case toolNames.killShell:
-      return {
-        title: "Kill Process",
-        kind: "execute",
-        content: [],
-      };
-
-    case toolNames.read: {
+    case "Read": {
+      const input = toolUse.input as FileReadInput;
       let limit = "";
-      if (input.limit) {
-        limit =
-          " (" + ((input.offset ?? 0) + 1) + " - " + ((input.offset ?? 0) + input.limit) + ")";
+      if (input.limit && input.limit > 0) {
+        limit = " (" + (input.offset ?? 1) + " - " + ((input.offset ?? 1) + input.limit - 1) + ")";
       } else if (input.offset) {
-        limit = " (from line " + (input.offset + 1) + ")";
+        limit = " (from line " + input.offset + ")";
       }
       return {
         title: "Read " + (input.file_path ?? "File") + limit,
@@ -119,7 +160,7 @@ export function toolInfoFromToolUse(
           ? [
               {
                 path: input.file_path,
-                line: input.offset ?? 0,
+                line: input.offset ?? 1,
               },
             ]
           : [],
@@ -127,69 +168,8 @@ export function toolInfoFromToolUse(
       };
     }
 
-    case "Read":
-      return {
-        title: "Read File",
-        kind: "read",
-        content: [],
-        locations: [{ path: input.file_path, line: input.offset ?? 0 }],
-      };
-
-    case "LS":
-      return {
-        title: `List the ${input?.path ? "`" + input.path + "`" : "current"} directory's contents`,
-        kind: "search",
-        content: [],
-        locations: [],
-      };
-
-    case toolNames.edit:
-    case "Edit": {
-      const path = input?.file_path ?? input?.file_path;
-      let oldText = input.old_string ?? null;
-      let newText = input.new_string ?? "";
-      let affectedLines: number[] = [];
-
-      if (path && oldText) {
-        try {
-          const oldContent = cachedFileContent[path] || "";
-          const newContent = replaceAndCalculateLocation(oldContent, [
-            {
-              oldText,
-              newText,
-              replaceAll: false,
-            },
-          ]);
-          oldText = oldContent;
-          newText = newContent.newContent;
-          affectedLines = newContent.lineNumbers;
-        } catch (e) {
-          console.error(e);
-        }
-      }
-      return {
-        title: path ? `Edit \`${path}\`` : "Edit",
-        kind: "edit",
-        content:
-          input && path
-            ? [
-                {
-                  type: "diff",
-                  path,
-                  oldText,
-                  newText,
-                },
-              ]
-            : [],
-        locations: path
-          ? affectedLines.length > 0
-            ? affectedLines.map((line) => ({ line, path }))
-            : [{ path }]
-          : [],
-      };
-    }
-
-    case toolNames.write: {
+    case "Write": {
+      const input = toolUse.input as FileWriteInput;
       let content: ToolCallContent[] = [];
       if (input && input.file_path) {
         content = [
@@ -216,25 +196,29 @@ export function toolInfoFromToolUse(
       };
     }
 
-    case "Write":
+    case "Edit": {
+      const input = toolUse.input as FileEditInput;
+      let content: ToolCallContent[] = [];
+      if (input && input.file_path && (input.old_string || input.new_string)) {
+        content = [
+          {
+            type: "diff",
+            path: input.file_path,
+            oldText: input.old_string || null,
+            newText: input.new_string ?? "",
+          },
+        ];
+      }
       return {
-        title: input?.file_path ? `Write ${input.file_path}` : "Write",
+        title: input?.file_path ? `Edit ${input.file_path}` : "Edit",
         kind: "edit",
-        content:
-          input && input.file_path
-            ? [
-                {
-                  type: "diff",
-                  path: input.file_path,
-                  oldText: null,
-                  newText: input.content,
-                },
-              ]
-            : [],
+        content,
         locations: input?.file_path ? [{ path: input.file_path }] : [],
       };
+    }
 
     case "Glob": {
+      const input = toolUse.input as GlobInput;
       let label = "Find";
       if (input.path) {
         label += ` \`${input.path}\``;
@@ -251,6 +235,7 @@ export function toolInfoFromToolUse(
     }
 
     case "Grep": {
+      const input = toolUse.input as GrepInput;
       let label = "grep";
 
       if (input["-i"]) {
@@ -272,13 +257,13 @@ export function toolInfoFromToolUse(
 
       if (input.output_mode) {
         switch (input.output_mode) {
-          case "FilesWithMatches":
+          case "files_with_matches":
             label += " -l";
             break;
-          case "Count":
+          case "count":
             label += " -c";
             break;
-          case "Content":
+          case "content":
           default:
             break;
         }
@@ -300,7 +285,9 @@ export function toolInfoFromToolUse(
         label += " -P";
       }
 
-      label += ` "${input.pattern}"`;
+      if (input.pattern) {
+        label += ` "${input.pattern}"`;
+      }
 
       if (input.path) {
         label += ` ${input.path}`;
@@ -313,7 +300,8 @@ export function toolInfoFromToolUse(
       };
     }
 
-    case "WebFetch":
+    case "WebFetch": {
+      const input = toolUse.input as WebFetchInput;
       return {
         title: input?.url ? `Fetch ${input.url}` : "Fetch",
         kind: "fetch",
@@ -327,8 +315,10 @@ export function toolInfoFromToolUse(
               ]
             : [],
       };
+    }
 
     case "WebSearch": {
+      const input = toolUse.input as WebSearchInput;
       let label = `"${input.query}"`;
 
       if (input.allowed_domains && input.allowed_domains.length > 0) {
@@ -346,7 +336,8 @@ export function toolInfoFromToolUse(
       };
     }
 
-    case "TodoWrite":
+    case "TodoWrite": {
+      const input = toolUse.input as TodoWriteInput;
       return {
         title: Array.isArray(input?.todos)
           ? `Update TODOs: ${input.todos.map((todo: any) => todo.content).join(", ")}`
@@ -354,18 +345,18 @@ export function toolInfoFromToolUse(
         kind: "think",
         content: [],
       };
+    }
 
-    case "ExitPlanMode":
+    case "ExitPlanMode": {
       return {
         title: "Ready to code?",
         kind: "switch_mode",
-        content:
-          input && input.plan
-            ? [{ type: "content", content: { type: "text", text: input.plan } }]
-            : [],
+        content: [],
       };
+    }
 
     case "Other": {
+      const input = toolUse.input;
       let output;
       try {
         output = JSON.stringify(input, null, 2);
@@ -399,6 +390,7 @@ export function toolInfoFromToolUse(
 export function toolUpdateFromToolResult(
   toolResult:
     | ToolResultBlockParam
+    | BetaToolResultBlockParam
     | BetaWebSearchToolResultBlockParam
     | BetaWebFetchToolResultBlockParam
     | WebSearchToolResultBlockParam
@@ -408,10 +400,20 @@ export function toolUpdateFromToolResult(
     | BetaRequestMCPToolResultBlockParam
     | BetaToolSearchToolResultBlockParam,
   toolUse: any | undefined,
+  supportsTerminalOutput: boolean = false,
 ): ToolUpdate {
+  if (
+    "is_error" in toolResult &&
+    toolResult.is_error &&
+    toolResult.content &&
+    toolResult.content.length > 0
+  ) {
+    // Only return errors
+    return toAcpContentUpdate(toolResult.content, true);
+  }
+
   switch (toolUse?.name) {
     case "Read":
-    case toolNames.read:
       if (Array.isArray(toolResult.content) && toolResult.content.length > 0) {
         return {
           content: toolResult.content.map((content: any) => ({
@@ -420,9 +422,9 @@ export function toolUpdateFromToolResult(
               content.type === "text"
                 ? {
                     type: "text",
-                    text: markdownEscape(content.text.replace(SYSTEM_REMINDER, "")),
+                    text: markdownEscape(content.text),
                   }
-                : content,
+                : toAcpContentBlock(content, false),
           })),
         };
       } else if (typeof toolResult.content === "string" && toolResult.content.length > 0) {
@@ -432,7 +434,7 @@ export function toolUpdateFromToolResult(
               type: "content",
               content: {
                 type: "text",
-                text: markdownEscape(toolResult.content.replace(SYSTEM_REMINDER, "")),
+                text: markdownEscape(toolResult.content),
               },
             },
           ],
@@ -440,21 +442,76 @@ export function toolUpdateFromToolResult(
       }
       return {};
 
-    case toolNames.bash:
-    case "edit":
-    case "Edit":
-    case toolNames.edit:
-    case toolNames.write:
-    case "Write": {
+    case "Bash": {
+      const result = toolResult.content;
+      const terminalId = "tool_use_id" in toolResult ? String(toolResult.tool_use_id) : "";
+      const isError = "is_error" in toolResult && toolResult.is_error;
+
+      // Extract output and exit code from either format:
+      // 1. BetaBashCodeExecutionResultBlock: { type: "bash_code_execution_result", stdout, stderr, return_code }
+      // 2. Plain string content from a regular tool_result
+      // 3. Array content (e.g. [{ type: "text", text: "..." }])
+      let output = "";
+      let exitCode = isError ? 1 : 0;
+
       if (
-        "is_error" in toolResult &&
-        toolResult.is_error &&
-        toolResult.content &&
-        toolResult.content.length > 0
+        result &&
+        typeof result === "object" &&
+        "type" in result &&
+        result.type === "bash_code_execution_result"
       ) {
-        // Only return errors
-        return toAcpContentUpdate(toolResult.content, true);
+        const bashResult = result as BetaBashCodeExecutionResultBlock;
+        output = bashResult.stdout || bashResult.stderr || "";
+        exitCode = bashResult.return_code;
+      } else if (typeof result === "string") {
+        output = result;
+      } else if (
+        Array.isArray(result) &&
+        result.length > 0 &&
+        "text" in result[0] &&
+        typeof result[0].text === "string"
+      ) {
+        output = result.map((c: any) => c.text).join("\n");
       }
+
+      if (supportsTerminalOutput) {
+        return {
+          content: [{ type: "terminal" as const, terminalId }],
+          _meta: {
+            terminal_info: {
+              terminal_id: terminalId,
+            },
+            terminal_output: {
+              terminal_id: terminalId,
+              data: output,
+            },
+            terminal_exit: {
+              terminal_id: terminalId,
+              exit_code: exitCode,
+              signal: null,
+            },
+          },
+        };
+      }
+      // Fallback: format output as a code block without terminal _meta
+      if (output.trim()) {
+        return {
+          content: [
+            {
+              type: "content",
+              content: {
+                type: "text",
+                text: `\`\`\`console\n${output.trimEnd()}\n\`\`\``,
+              },
+            },
+          ],
+        };
+      }
+      return {};
+    }
+
+    case "Edit": // Edit is handled in hooks
+    case "Write": {
       return {};
     }
 
@@ -462,20 +519,6 @@ export function toolUpdateFromToolResult(
       return { title: "Exited Plan Mode" };
     }
 
-    case "Task":
-    case "NotebookEdit":
-    case "NotebookRead":
-    case "TodoWrite":
-    case "exit_plan_mode":
-    case "Bash":
-    case "BashOutput":
-    case "KillBash":
-    case "LS":
-    case "Glob":
-    case "Grep":
-    case "WebFetch":
-    case "WebSearch":
-    case "Other":
     default: {
       return toAcpContentUpdate(
         toolResult.content,
@@ -491,17 +534,20 @@ function toAcpContentUpdate(
 ): { content?: ToolCallContent[] } {
   if (Array.isArray(content) && content.length > 0) {
     return {
-      content: content.map((content: any) => ({
-        type: "content",
-        content:
-          isError && content.type === "text"
-            ? {
-                ...content,
-                text: `\`\`\`\n${content.text}\n\`\`\``,
-              }
-            : content,
+      content: content.map((c: any) => ({
+        type: "content" as const,
+        content: toAcpContentBlock(c, isError),
       })),
     };
+  } else if (typeof content === "object" && content !== null && "type" in content) {
+    return {
+      content: [
+        {
+          type: "content" as const,
+          content: toAcpContentBlock(content, isError),
+        },
+      ],
+    };
   } else if (typeof content === "string" && content.length > 0) {
     return {
       content: [
@@ -518,6 +564,74 @@ function toAcpContentUpdate(
   return {};
 }
 
+function toAcpContentBlock(content: ToolResultContent, isError: boolean): ContentBlock {
+  const wrapText = (text: string): ContentBlock => ({
+    type: "text" as const,
+    text: isError ? `\`\`\`\n${text}\n\`\`\`` : text,
+  });
+
+  switch (content.type) {
+    case "text":
+      return {
+        type: "text" as const,
+        text: isError ? `\`\`\`\n${content.text}\n\`\`\`` : content.text,
+      };
+    case "image":
+      if (content.source.type === "base64") {
+        return {
+          type: "image" as const,
+          data: content.source.data,
+          mimeType: content.source.media_type,
+        };
+      }
+      // URL and file-based images can't be converted to ACP format (requires data)
+      return wrapText(
+        content.source.type === "url"
+          ? `[image: ${content.source.url}]`
+          : "[image: file reference]",
+      );
+
+    case "tool_reference":
+      return wrapText(`Tool: ${content.tool_name}`);
+    case "tool_search_tool_search_result":
+      return wrapText(
+        `Tools found: ${content.tool_references.map((r) => r.tool_name).join(", ") || "none"}`,
+      );
+    case "tool_search_tool_result_error":
+      return wrapText(
+        `Error: ${content.error_code}${content.error_message ? ` - ${content.error_message}` : ""}`,
+      );
+    case "web_search_result":
+      return wrapText(`${content.title} (${content.url})`);
+    case "web_search_tool_result_error":
+      return wrapText(`Error: ${content.error_code}`);
+    case "web_fetch_result":
+      return wrapText(`Fetched: ${content.url}`);
+    case "web_fetch_tool_result_error":
+      return wrapText(`Error: ${content.error_code}`);
+    case "code_execution_result":
+      return wrapText(`Output: ${content.stdout || content.stderr || ""}`);
+    case "bash_code_execution_result":
+      return wrapText(`Output: ${content.stdout || content.stderr || ""}`);
+    case "code_execution_tool_result_error":
+    case "bash_code_execution_tool_result_error":
+      return wrapText(`Error: ${content.error_code}`);
+    case "text_editor_code_execution_view_result":
+      return wrapText(content.content);
+    case "text_editor_code_execution_create_result":
+      return wrapText(content.is_file_update ? "File updated" : "File created");
+    case "text_editor_code_execution_str_replace_result":
+      return wrapText(content.lines?.join("\n") || "");
+    case "text_editor_code_execution_tool_result_error":
+      return wrapText(
+        `Error: ${content.error_code}${content.error_message ? ` - ${content.error_message}` : ""}`,
+      );
+
+    default:
+      return wrapText(JSON.stringify(content));
+  }
+}
+
 export type ClaudePlanEntry = {
   content: string;
   status: "pending" | "in_progress" | "completed";
@@ -542,6 +656,66 @@ export function markdownEscape(text: string): string {
   return escape + "\n" + text + (text.endsWith("\n") ? "" : "\n") + escape;
 }
 
+interface EditToolResponseHunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: string[];
+}
+
+interface EditToolResponse {
+  filePath?: string;
+  structuredPatch?: EditToolResponseHunk[];
+}
+
+/**
+ * Builds diff ToolUpdate content from the structured Edit toolResponse provided
+ * by the PostToolUse hook. Unlike parsing the plain unified diff string, this uses
+ * the pre-parsed structuredPatch which supports multiple replacement sites (replaceAll)
+ * and always includes context lines for better readability.
+ */
+export function toolUpdateFromEditToolResponse(toolResponse: unknown): {
+  content?: ToolCallContent[];
+  locations?: ToolCallLocation[];
+} {
+  if (!toolResponse || typeof toolResponse !== "object") return {};
+  const response = toolResponse as EditToolResponse;
+  if (!response.filePath || !Array.isArray(response.structuredPatch)) return {};
+
+  const content: ToolCallContent[] = [];
+  const locations: ToolCallLocation[] = [];
+
+  for (const { lines, newStart } of response.structuredPatch) {
+    const oldText: string[] = [];
+    const newText: string[] = [];
+    for (const line of lines) {
+      if (line.startsWith("-")) {
+        oldText.push(line.slice(1));
+      } else if (line.startsWith("+")) {
+        newText.push(line.slice(1));
+      } else {
+        oldText.push(line.slice(1));
+        newText.push(line.slice(1));
+      }
+    }
+    if (oldText.length > 0 || newText.length > 0) {
+      locations.push({ path: response.filePath, line: newStart });
+      content.push({
+        type: "diff",
+        path: response.filePath,
+        oldText: oldText.join("\n") || null,
+        newText: newText.join("\n"),
+      });
+    }
+  }
+
+  const result: { content?: ToolCallContent[]; locations?: ToolCallLocation[] } = {};
+  if (content.length > 0) result.content = content;
+  if (locations.length > 0) result.locations = locations;
+  return result;
+}
+
 /* A global variable to store callbacks that should be executed when receiving hooks from Claude Code */
 const toolUseCallbacks: {
   [toolUseId: string]: {
@@ -572,19 +746,30 @@ export const registerHookCallback = (
 };
 
 /* A callback for Claude Code that is called when receiving a PostToolUse hook */
-export const postToolUseHook: HookCallback = async (
-  input: any,
-  toolUseID: string | undefined,
-): Promise<{ continue: boolean }> => {
-  if (input.hook_event_name === "PostToolUse" && toolUseID) {
-    const onPostToolUseHook = toolUseCallbacks[toolUseID]?.onPostToolUseHook;
-    if (onPostToolUseHook) {
-      await onPostToolUseHook(toolUseID, input.tool_input, input.tool_response);
-      delete toolUseCallbacks[toolUseID]; // Cleanup after execution
-    } else {
-      console.error(`No onPostToolUseHook found for tool use ID: ${toolUseID}`);
-      delete toolUseCallbacks[toolUseID];
+export const createPostToolUseHook =
+  (
+    logger: Logger = console,
+    options?: {
+      onEnterPlanMode?: () => Promise<void>;
+    },
+  ): HookCallback =>
+  async (input: any, toolUseID: string | undefined): Promise<{ continue: boolean }> => {
+    if (input.hook_event_name === "PostToolUse") {
+      // Handle EnterPlanMode tool - notify client of mode change after successful execution
+      if (input.tool_name === "EnterPlanMode" && options?.onEnterPlanMode) {
+        await options.onEnterPlanMode();
+      }
+
+      if (toolUseID) {
+        const onPostToolUseHook = toolUseCallbacks[toolUseID]?.onPostToolUseHook;
+        if (onPostToolUseHook) {
+          await onPostToolUseHook(toolUseID, input.tool_input, input.tool_response);
+          delete toolUseCallbacks[toolUseID]; // Cleanup after execution
+        } else {
+          logger.error(`No onPostToolUseHook found for tool use ID: ${toolUseID}`);
+          delete toolUseCallbacks[toolUseID];
+        }
+      }
     }
-  }
-  return { continue: true };
-};
+    return { continue: true };
+  };

src/utils.ts

@@ -3,7 +3,8 @@
 import { Readable, Writable } from "node:stream";
 import { WritableStream, ReadableStream } from "node:stream/web";
 import { readFileSync } from "node:fs";
-import { platform } from "node:os";
+import { Logger } from "./acp-agent.js";
+import { ClaudeCodeSettings, getManagedSettingsPath } from "./settings.js";
 
 // Useful for bridging push-based and async-iterator-based code.
 export class Pushable<T> implements AsyncIterable<T> {
@@ -75,53 +76,29 @@ export function nodeToWebReadable(nodeStream: Readable): ReadableStream<Uint8Arr
   });
 }
 
-export function unreachable(value: never) {
+export function unreachable(value: never, logger: Logger = console) {
   let valueAsString;
   try {
     valueAsString = JSON.stringify(value);
   } catch {
     valueAsString = value;
   }
-  console.error(`Unexpected case: ${valueAsString}`);
+  logger.error(`Unexpected case: ${valueAsString}`);
 }
 
 export function sleep(time: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, time));
 }
 
-interface ManagedSettings {
-  permissions?: {
-    allow?: string[];
-    deny?: string[];
-  };
-  env?: Record<string, string>;
-}
-
-// Following the rules in https://docs.anthropic.com/en/docs/claude-code/settings#settings-files
-// This can be removed once the SDK supports it natively.
-function getManagedSettingsPath(): string {
-  const os = platform();
-  switch (os) {
-    case "darwin":
-      return "/Library/Application Support/ClaudeCode/managed-settings.json";
-    case "linux": // including WSL
-      return "/etc/claude-code/managed-settings.json";
-    case "win32":
-      return "C:\\ProgramData\\ClaudeCode\\managed-settings.json";
-    default:
-      return "/etc/claude-code/managed-settings.json";
-  }
-}
-
-export function loadManagedSettings(): ManagedSettings | null {
+export function loadManagedSettings(): ClaudeCodeSettings | null {
   try {
-    return JSON.parse(readFileSync(getManagedSettingsPath(), "utf8")) as ManagedSettings;
+    return JSON.parse(readFileSync(getManagedSettingsPath(), "utf8")) as ClaudeCodeSettings;
   } catch {
     return null;
   }
 }
 
-export function applyEnvironmentSettings(settings: ManagedSettings): void {
+export function applyEnvironmentSettings(settings: ClaudeCodeSettings): void {
   if (settings.env) {
     for (const [key, value] of Object.entries(settings.env)) {
       process.env[key] = value;
@@ -129,66 +106,9 @@ export function applyEnvironmentSettings(settings: ManagedSettings): void {
   }
 }
 
-export interface ExtractLinesResult {
-  content: string;
-  wasLimited: boolean;
-  linesRead: number;
-}
-
-/**
- * Extracts lines from file content with byte limit enforcement.
- *
- * @param fullContent - The complete file content
- * @param maxContentLength - Maximum number of UTF-16 Code Units to return
- * @returns Object containing extracted content and metadata
- */
-export function extractLinesWithByteLimit(
-  fullContent: string,
-  maxContentLength: number,
-): ExtractLinesResult {
-  if (fullContent === "") {
-    return {
-      content: "",
-      wasLimited: false,
-      linesRead: 1,
-    };
-  }
-
-  let linesSeen = 0;
-  let index = 0;
-  linesSeen = 0;
-
-  let contentLength = 0;
-  let wasLimited = false;
-
-  while (true) {
-    const nextIndex = fullContent.indexOf("\n", index);
-
-    if (nextIndex < 0) {
-      // Last line in file (no trailing newline)
-      if (linesSeen > 0 && fullContent.length > maxContentLength) {
-        wasLimited = true;
-        break;
-      }
-      linesSeen += 1;
-      contentLength = fullContent.length;
-      break;
-    } else {
-      // Line with newline - include up to the newline
-      const newContentLength = nextIndex + 1;
-      if (linesSeen > 0 && newContentLength > maxContentLength) {
-        wasLimited = true;
-        break;
-      }
-      linesSeen += 1;
-      contentLength = newContentLength;
-      index = newContentLength;
-    }
-  }
-
-  return {
-    content: fullContent.slice(0, contentLength),
-    wasLimited,
-    linesRead: linesSeen,
-  };
+// Helper to encode a path like Claude does:
+// - Unix: "/Users/test" -> "-Users-test"
+// - Windows: "C:\Users\test" -> "C--Users-test"
+export function encodeProjectPath(cwd: string): string {
+  return cwd.replace(/[^a-zA-Z0-9]/g, "-");
 }

tsconfig.json

@@ -1,15 +1,17 @@
 {
   "compilerOptions": {
-    "target": "ES2020",
+    "target": "ES2021",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
-    "lib": ["ES2020"],
+    "lib": ["ES2021"],
     "strict": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true
   },
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]