Prep 0.14.0 release (#278)

Adds support for the draft session/list RFD spec by reading Claude
Code's local session files.

- Implement `unstable_listSessions` method that parses JSONL session
files from `~/.claude/projects/`
- Advertise `list` capability in `sessionCapabilities`
- Support filtering by `cwd` parameter
- Implement cursor-based pagination (50 sessions per page)
- Extract title from first user message, use file mtime as `updatedAt`

Related: https://agentclientprotocol.com/rfds/session-list

What do you think @benbrandt? Is it ok to do the json files parsing
ourselves? I also opened [an
issue](https://github.com/anthropics/claude-agent-sdk-typescript/issues/147)
in the claude agent sdk repo but I doubt they will add that
functionality in the sdk npm package

---------

Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>

.gitignore

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

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 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

README.md

@@ -4,7 +4,7 @@
 
 Use [Claude Code](https://www.anthropic.com/claude-code) 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
@@ -32,20 +32,14 @@ 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-code-acp
 ```
 
 You can then use `claude-code-acp` as a regular ACP agent:

package.json

@@ -3,15 +3,24 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.12.4",
+  "version": "0.14.0",
   "description": "An ACP-compatible coding agent powered by the Claude Code SDK (TypeScript)",
   "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
   "bin": {
     "claude-code-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"
@@ -51,23 +60,23 @@
   "author": "Zed Industries",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.11.0",
-    "@anthropic-ai/claude-agent-sdk": "0.1.67",
-    "@modelcontextprotocol/sdk": "1.24.3",
-    "diff": "8.0.2",
-    "minimatch": "^10.1.1"
+    "@agentclientprotocol/sdk": "0.13.1",
+    "@anthropic-ai/claude-agent-sdk": "0.2.29",
+    "@modelcontextprotocol/sdk": "1.25.3",
+    "diff": "8.0.3",
+    "minimatch": "10.1.1"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.71.2",
-    "@types/node": "25.0.1",
-    "@typescript-eslint/eslint-plugin": "8.49.0",
-    "@typescript-eslint/parser": "8.49.0",
-    "eslint": "9.39.1",
+    "@anthropic-ai/sdk": "0.72.1",
+    "@types/node": "25.2.0",
+    "@typescript-eslint/eslint-plugin": "8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
+    "eslint": "9.39.2",
     "eslint-config-prettier": "10.1.8",
-    "globals": "16.5.0",
-    "prettier": "3.7.4",
+    "globals": "17.3.0",
+    "prettier": "3.8.1",
     "ts-node": "10.9.2",
     "typescript": "5.9.3",
-    "vitest": "4.0.15"
+    "vitest": "4.0.18"
   }
 }

src/acp-agent.ts

@@ -9,6 +9,8 @@ import {
   ForkSessionResponse,
   InitializeRequest,
   InitializeResponse,
+  ListSessionsRequest,
+  ListSessionsResponse,
   ndJsonStream,
   NewSessionRequest,
   NewSessionResponse,
@@ -17,6 +19,9 @@ import {
   ReadTextFileRequest,
   ReadTextFileResponse,
   RequestError,
+  ResumeSessionRequest,
+  ResumeSessionResponse,
+  SessionInfo,
   SessionModelState,
   SessionNotification,
   SetSessionModelRequest,
@@ -58,8 +63,44 @@ import { ContentBlockParam } from "@anthropic-ai/sdk/resources";
 import { BetaContentBlock, BetaRawContentBlockDelta } from "@anthropic-ai/sdk/resources/beta.mjs";
 import packageJson from "../package.json" with { type: "json" };
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 
-export const CLAUDE_CONFIG_DIR = process.env.CLAUDE ?? path.join(os.homedir(), ".claude");
+export const CLAUDE_CONFIG_DIR =
+  process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
+
+/**
+ * Decode a Claude project path encoding back to the original filesystem path.
+ * Claude encodes paths by replacing path separators with dashes:
+ * - Unix: "/Users/morse/project" -> "-Users-morse-project"
+ * - Windows: "C:\Users\morse\project" -> "C-Users-morse-project"
+ */
+function decodeProjectPath(encodedPath: string): string {
+  // Check if this looks like a Windows path (starts with drive letter pattern like "C-")
+  const windowsDriveMatch = encodedPath.match(/^([A-Za-z])-/);
+  if (windowsDriveMatch) {
+    // Windows path: "C-Users-morse-project" -> "C:\Users\morse\project"
+    const driveLetter = windowsDriveMatch[1];
+    const rest = encodedPath.slice(2); // Skip "C-"
+    return `${driveLetter}:\\${rest.replace(/-/g, "\\")}`;
+  }
+
+  // Unix path: "-Users-morse-project" -> "/Users/morse/project"
+  return encodedPath.replace(/-/g, "/");
+}
+
+const MAX_TITLE_LENGTH = 128;
+
+function sanitizeTitle(text: string): string {
+  // Replace newlines and collapse whitespace
+  const sanitized = text
+    .replace(/[\r\n]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (sanitized.length <= MAX_TITLE_LENGTH) {
+    return sanitized;
+  }
+  return sanitized.slice(0, MAX_TITLE_LENGTH - 1) + "…";
+}
 
 /**
  * Logger interface for customizing logging output
@@ -122,17 +163,18 @@ export type ToolUpdateMeta = {
   };
 };
 
-type ToolUseCache = {
+export type ToolUseCache = {
   [key: string]: {
     type: "tool_use" | "server_tool_use" | "mcp_tool_use";
     id: string;
     name: string;
-    input: any;
+    input: unknown;
   };
 };
 
 // Bypass Permissions doesn't work if we are a root/sudo user
 const IS_ROOT = (process.geteuid?.() ?? process.getuid?.()) === 0;
+const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
 
 // Implement the ACP Agent interface
 export class ClaudeAcpAgent implements Agent {
@@ -141,7 +183,6 @@ export class ClaudeAcpAgent implements Agent {
   };
   client: AgentSideConnection;
   toolUseCache: ToolUseCache;
-  fileContentCache: { [key: string]: string };
   backgroundTerminals: { [key: string]: BackgroundTerminal } = {};
   clientCapabilities?: ClientCapabilities;
   logger: Logger;
@@ -150,7 +191,6 @@ export class ClaudeAcpAgent implements Agent {
     this.sessions = {};
     this.client = client;
     this.toolUseCache = {};
-    this.fileContentCache = {};
     this.logger = logger ?? console;
   }
 
@@ -165,17 +205,17 @@ export class ClaudeAcpAgent implements Agent {
     };
 
     // If client supports terminal-auth capability, use that instead.
-    // if (request.clientCapabilities?._meta?.["terminal-auth"] === true) {
-    //   const cliPath = fileURLToPath(import.meta.resolve("@anthropic-ai/claude-agent-sdk/cli.js"));
+    if (request.clientCapabilities?._meta?.["terminal-auth"] === true) {
+      const cliPath = fileURLToPath(import.meta.resolve("@anthropic-ai/claude-agent-sdk/cli.js"));
 
-    //   authMethod._meta = {
-    //     "terminal-auth": {
-    //       command: "node",
-    //       args: [cliPath, "/login"],
-    //       label: "Claude Code Login",
-    //     },
-    //   };
-    // }
+      authMethod._meta = {
+        "terminal-auth": {
+          command: "node",
+          args: [cliPath, "/login"],
+          label: "Claude Code Login",
+        },
+      };
+    }
 
     return {
       protocolVersion: 1,
@@ -189,8 +229,9 @@ export class ClaudeAcpAgent implements Agent {
           sse: true,
         },
         sessionCapabilities: {
-          // TODO: announce fork capability when sessionId handling is fixed
-          // fork: {},
+          fork: {},
+          list: {},
+          resume: {},
         },
       },
       agentInfo: {
@@ -216,7 +257,7 @@ export class ClaudeAcpAgent implements Agent {
     });
   }
 
-  async forkSession(params: ForkSessionRequest): Promise<ForkSessionResponse> {
+  async unstable_forkSession(params: ForkSessionRequest): Promise<ForkSessionResponse> {
     return await this.createSession(
       {
         cwd: params.cwd,
@@ -230,6 +271,164 @@ export class ClaudeAcpAgent implements Agent {
     );
   }
 
+  async unstable_resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse> {
+    const response = await this.createSession(
+      {
+        cwd: params.cwd,
+        mcpServers: params.mcpServers ?? [],
+        _meta: params._meta,
+      },
+      {
+        resume: params.sessionId,
+      },
+    );
+
+    return response;
+  }
+
+  /**
+   * List Claude Code sessions by parsing JSONL files
+   * Sessions are stored in ~/.claude/projects/<path-encoded>/
+   * Implements the draft session/list RFD spec
+   */
+  async unstable_listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse> {
+    // Note: We load all sessions into memory for sorting, so pagination here is for
+    // API response size limits rather than memory efficiency. This matches the RFD spec.
+    const PAGE_SIZE = 50;
+    const claudeDir = path.join(CLAUDE_CONFIG_DIR, "projects");
+
+    try {
+      await fs.promises.access(claudeDir);
+    } catch {
+      return { sessions: [] };
+    }
+
+    // Collect all sessions across all project directories
+    const allSessions: SessionInfo[] = [];
+
+    try {
+      const projectDirs = await fs.promises.readdir(claudeDir);
+
+      for (const encodedPath of projectDirs) {
+        const projectDir = path.join(claudeDir, encodedPath);
+        const stat = await fs.promises.stat(projectDir);
+        if (!stat.isDirectory()) continue;
+
+        // Decode the path based on platform:
+        // - Unix: "-Users-morse-project" -> "/Users/morse/project"
+        // - Windows: "C-Users-morse-project" -> "C:\Users\morse\project"
+        const decodedCwd = decodeProjectPath(encodedPath);
+
+        // Skip if filtering by cwd and this doesn't match
+        if (params.cwd && decodedCwd !== params.cwd) continue;
+
+        const files = await fs.promises.readdir(projectDir);
+        // Filter to user session files only. Skip agent-*.jsonl files which contain
+        // internal agent metadata and system logs, not user-visible conversation sessions.
+        const jsonlFiles = files.filter((f) => f.endsWith(".jsonl") && !f.startsWith("agent-"));
+
+        for (const file of jsonlFiles) {
+          const filePath = path.join(projectDir, file);
+          try {
+            const content = await fs.promises.readFile(filePath, "utf-8");
+            const lines = content.trim().split("\n").filter(Boolean);
+
+            const firstLine = lines[0];
+            if (!firstLine) continue;
+
+            // Parse first line to get session info
+            const firstEntry = JSON.parse(firstLine);
+            const sessionId = firstEntry.sessionId || file.replace(".jsonl", "");
+
+            // Find first user message for title
+            let title: string | undefined;
+            for (const line of lines) {
+              try {
+                const entry = JSON.parse(line);
+                if (entry.type === "user" && entry.message?.content) {
+                  const msgContent = entry.message.content;
+                  if (typeof msgContent === "string") {
+                    title = sanitizeTitle(msgContent);
+                    break;
+                  }
+                  if (Array.isArray(msgContent) && msgContent.length > 0) {
+                    const first = msgContent[0];
+                    const text =
+                      typeof first === "string"
+                        ? first
+                        : first && typeof first === "object" && typeof first.text === "string"
+                          ? first.text
+                          : undefined;
+                    if (text) {
+                      title = sanitizeTitle(text);
+                      break;
+                    }
+                  }
+                }
+              } catch {
+                // Skip malformed lines
+              }
+            }
+
+            // Get file modification time as updatedAt
+            const fileStat = await fs.promises.stat(filePath);
+            const updatedAt = fileStat.mtime.toISOString();
+
+            allSessions.push({
+              sessionId,
+              cwd: decodedCwd,
+              title: title ?? null,
+              updatedAt,
+            });
+          } catch (err) {
+            this.logger.error(
+              `[unstable_listSessions] Failed to parse session file: ${filePath}`,
+              err,
+            );
+          }
+        }
+      }
+    } catch (err) {
+      this.logger.error("[unstable_listSessions] Failed to list sessions", err);
+      return { sessions: [] };
+    }
+
+    // Sort by updatedAt descending (most recent first)
+    allSessions.sort((a, b) => {
+      const timeA = a.updatedAt ? new Date(a.updatedAt).getTime() : 0;
+      const timeB = b.updatedAt ? new Date(b.updatedAt).getTime() : 0;
+      return timeB - timeA;
+    });
+
+    // Handle pagination with cursor
+    let startIndex = 0;
+    if (params.cursor) {
+      try {
+        const decoded = Buffer.from(params.cursor, "base64").toString("utf-8");
+        const cursorData = JSON.parse(decoded);
+        startIndex = cursorData.offset ?? 0;
+      } catch {
+        // Invalid cursor, start from beginning
+      }
+    }
+
+    const pageOfSessions = allSessions.slice(startIndex, startIndex + PAGE_SIZE);
+    const hasMore = startIndex + PAGE_SIZE < allSessions.length;
+
+    const response: ListSessionsResponse = {
+      sessions: pageOfSessions,
+    };
+
+    if (hasMore) {
+      const nextCursor = Buffer.from(JSON.stringify({ offset: startIndex + PAGE_SIZE })).toString(
+        "base64",
+      );
+      response.nextCursor = nextCursor;
+    }
+
+    return response;
+  }
+
   async authenticate(_params: AuthenticateRequest): Promise<void> {
     throw new Error("Method not implemented.");
   }
@@ -259,8 +458,12 @@ export class ClaudeAcpAgent implements Agent {
             case "init":
               break;
             case "compact_boundary":
+            case "hook_started":
+            case "task_notification":
+            case "hook_progress":
             case "hook_response":
             case "status":
+            case "files_persisted":
               // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
               break;
             default:
@@ -312,7 +515,6 @@ export class ClaudeAcpAgent implements Agent {
             message,
             params.sessionId,
             this.toolUseCache,
-            this.fileContentCache,
             this.client,
             this.logger,
           )) {
@@ -332,6 +534,21 @@ export class ClaudeAcpAgent implements Agent {
             typeof message.message.content === "string" &&
             message.message.content.includes("<local-command-stdout>")
           ) {
+            // Handle /context by sending its reply as regular agent message.
+            if (message.message.content.includes("Context Usage")) {
+              for (const notification of toAcpNotifications(
+                message.message.content
+                  .replace("<local-command-stdout>", "")
+                  .replace("</local-command-stdout>", ""),
+                "assistant",
+                params.sessionId,
+                this.toolUseCache,
+                this.client,
+                this.logger,
+              )) {
+                await this.client.sessionUpdate(notification);
+              }
+            }
             this.logger.log(message.message.content);
             break;
           }
@@ -376,7 +593,6 @@ export class ClaudeAcpAgent implements Agent {
             message.message.role,
             params.sessionId,
             this.toolUseCache,
-            this.fileContentCache,
             this.client,
             this.logger,
           )) {
@@ -385,6 +601,7 @@ export class ClaudeAcpAgent implements Agent {
           break;
         }
         case "tool_progress":
+        case "tool_use_summary":
           break;
         case "auth_status":
           break;
@@ -404,7 +621,9 @@ export class ClaudeAcpAgent implements Agent {
     await this.sessions[params.sessionId].query.interrupt();
   }
 
-  async setSessionModel(params: SetSessionModelRequest): Promise<SetSessionModelResponse | void> {
+  async unstable_setSessionModel(
+    params: SetSessionModelRequest,
+  ): Promise<SetSessionModelResponse | void> {
     if (!this.sessions[params.sessionId]) {
       throw new Error("Session not found");
     }
@@ -439,15 +658,11 @@ export class ClaudeAcpAgent implements Agent {
 
   async readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
     const response = await this.client.readTextFile(params);
-    if (!params.limit && !params.line) {
-      this.fileContentCache[params.path] = response.content;
-    }
     return response;
   }
 
   async writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse> {
     const response = await this.client.writeTextFile(params);
-    this.fileContentCache[params.path] = params.content;
     return response;
   }
 
@@ -477,11 +692,7 @@ export class ClaudeAcpAgent implements Agent {
           toolCall: {
             toolCallId: toolUseID,
             rawInput: toolInput,
-            title: toolInfoFromToolUse(
-              { name: toolName, input: toolInput },
-              this.fileContentCache,
-              this.logger,
-            ).title,
+            title: toolInfoFromToolUse({ name: toolName, input: toolInput }).title,
           },
         });
 
@@ -544,11 +755,7 @@ export class ClaudeAcpAgent implements Agent {
         toolCall: {
           toolCallId: toolUseID,
           rawInput: toolInput,
-          title: toolInfoFromToolUse(
-            { name: toolName, input: toolInput },
-            this.fileContentCache,
-            this.logger,
-          ).title,
+          title: toolInfoFromToolUse({ name: toolName, input: toolInput }).title,
         },
       });
       if (signal.aborted || response.outcome?.outcome === "cancelled") {
@@ -591,7 +798,17 @@ export class ClaudeAcpAgent implements Agent {
     params: NewSessionRequest,
     creationOpts: { resume?: string; forkSession?: boolean } = {},
   ): Promise<NewSessionResponse> {
-    const sessionId = creationOpts.resume ?? randomUUID();
+    // We want to create a new session id unless it is resume,
+    // but not resume + forkSession.
+    let sessionId;
+    if (creationOpts.forkSession) {
+      sessionId = randomUUID();
+    } else if (creationOpts.resume) {
+      sessionId = creationOpts.resume;
+    } else {
+      sessionId = randomUUID();
+    }
+
     const input = new Pushable<SDKUserMessage>();
 
     const settingsManager = new SettingsManager(params.cwd, {
@@ -652,16 +869,21 @@ export class ClaudeAcpAgent implements Agent {
     // Extract options from _meta if provided
     const userProvidedOptions = (params._meta as NewSessionMeta | undefined)?.claudeCode?.options;
     const extraArgs = { ...userProvidedOptions?.extraArgs };
-    if (creationOpts?.resume === undefined) {
+    if (creationOpts?.resume === undefined || creationOpts?.forkSession) {
       // Set our own session id if not resuming an existing session.
-      // TODO: find a way to make this work for fork
       extraArgs["session-id"] = sessionId;
     }
 
+    // Configure thinking tokens from environment variable
+    const maxThinkingTokens = process.env.MAX_THINKING_TOKENS
+      ? parseInt(process.env.MAX_THINKING_TOKENS, 10)
+      : undefined;
+
     const options: Options = {
       systemPrompt,
       settingSources: ["user", "project", "local"],
       stderr: (err) => this.logger.error(err),
+      ...(maxThinkingTokens !== undefined && { maxThinkingTokens }),
       ...userProvidedOptions,
       // Override certain fields that must be controlled by ACP
       cwd: params.cwd,
@@ -670,7 +892,7 @@ export class ClaudeAcpAgent implements Agent {
       extraArgs,
       // If we want bypassPermissions to be an option, we have to allow it here.
       // But it doesn't work in root mode, so we only activate it if it will work.
-      allowDangerouslySkipPermissions: !IS_ROOT,
+      allowDangerouslySkipPermissions: ALLOW_BYPASS,
       permissionMode,
       canUseTool: this.canUseTool(sessionId),
       // note: although not documented by the types, passing an absolute path
@@ -679,6 +901,7 @@ export class ClaudeAcpAgent implements Agent {
       ...(process.env.CLAUDE_CODE_EXECUTABLE && {
         pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE,
       }),
+      tools: { type: "preset", preset: "claude_code" },
       hooks: {
         ...userProvidedOptions?.hooks,
         PreToolUse: [
@@ -690,7 +913,23 @@ export class ClaudeAcpAgent implements Agent {
         PostToolUse: [
           ...(userProvidedOptions?.hooks?.PostToolUse || []),
           {
-            hooks: [createPostToolUseHook(this.logger)],
+            hooks: [
+              createPostToolUseHook(this.logger, {
+                onEnterPlanMode: async () => {
+                  const session = this.sessions[sessionId];
+                  if (session) {
+                    session.permissionMode = "plan";
+                  }
+                  await this.client.sessionUpdate({
+                    sessionId,
+                    update: {
+                      sessionUpdate: "current_mode_update",
+                      currentModeId: "plan",
+                    },
+                  });
+                },
+              }),
+            ],
           },
         ],
       },
@@ -698,7 +937,8 @@ export class ClaudeAcpAgent implements Agent {
     };
 
     const allowedTools = [];
-    const disallowedTools = [];
+    // Disable this for now, not a great way to expose this over ACP at the moment (in progress work so we can revisit)
+    const disallowedTools = ["AskUserQuestion"];
 
     // Check if built-in tools should be disabled
     const disableBuiltInTools = params._meta?.disableBuiltInTools === true;
@@ -807,7 +1047,7 @@ export class ClaudeAcpAgent implements Agent {
       },
     ];
     // Only works in non-root mode
-    if (!IS_ROOT) {
+    if (ALLOW_BYPASS) {
       availableModes.push({
         id: "bypassPermissions",
         name: "Bypass Permissions",
@@ -847,7 +1087,6 @@ async function getAvailableModels(query: Query): Promise<SessionModelState> {
 
 async function getAvailableSlashCommands(query: Query): Promise<AvailableCommand[]> {
   const UNSUPPORTED_COMMANDS = [
-    "context",
     "cost",
     "login",
     "logout",
@@ -859,7 +1098,13 @@ async function getAvailableSlashCommands(query: Query): Promise<AvailableCommand
 
   return commands
     .map((command) => {
-      const input = command.argumentHint ? { hint: command.argumentHint } : null;
+      const input = command.argumentHint
+        ? {
+            hint: Array.isArray(command.argumentHint)
+              ? command.argumentHint.join(" ")
+              : command.argumentHint,
+          }
+        : null;
       let name = command.name;
       if (command.name.endsWith(" (MCP)")) {
         name = `mcp:${name.replace(" (MCP)", "")}`;
@@ -978,7 +1223,6 @@ export function toAcpNotifications(
   role: "assistant" | "user",
   sessionId: string,
   toolUseCache: ToolUseCache,
-  fileContentCache: { [key: string]: string },
   client: AgentSideConnection,
   logger: Logger,
 ): SessionNotification[] {
@@ -1089,7 +1333,7 @@ export function toAcpNotifications(
             sessionUpdate: "tool_call",
             rawInput,
             status: "pending",
-            ...toolInfoFromToolUse(chunk, fileContentCache, logger),
+            ...toolInfoFromToolUse(chunk),
           };
         }
         break;
@@ -1121,6 +1365,7 @@ export function toAcpNotifications(
             toolCallId: chunk.tool_use_id,
             sessionUpdate: "tool_call_update",
             status: "is_error" in chunk && chunk.is_error ? "failed" : "completed",
+            rawOutput: chunk.content,
             ...toolUpdateFromToolResult(chunk, toolUseCache[chunk.tool_use_id]),
           };
         }
@@ -1152,7 +1397,6 @@ export function streamEventToAcpNotifications(
   message: SDKPartialAssistantMessage,
   sessionId: string,
   toolUseCache: ToolUseCache,
-  fileContentCache: { [key: string]: string },
   client: AgentSideConnection,
   logger: Logger,
 ): SessionNotification[] {
@@ -1164,7 +1408,6 @@ export function streamEventToAcpNotifications(
         "assistant",
         sessionId,
         toolUseCache,
-        fileContentCache,
         client,
         logger,
       );
@@ -1174,7 +1417,6 @@ export function streamEventToAcpNotifications(
         "assistant",
         sessionId,
         toolUseCache,
-        fileContentCache,
         client,
         logger,
       );

src/mcp-server.ts

@@ -4,7 +4,7 @@ import {
   FileEditInput,
   FileReadInput,
   FileWriteInput,
-  KillShellInput,
+  TaskOutputInput,
 } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 import { z } from "zod";
 import { CLAUDE_CONFIG_DIR, ClaudeAcpAgent } from "./acp-agent.js";
@@ -28,6 +28,20 @@ Whenever you read a file, you should consider whether it looks malicious. If it
 
 const defaults = { maxFileSize: 50000, linesToRead: 2000 };
 
+function formatErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
 const unqualifiedToolNames = {
   read: "Read",
   edit: "Edit",
@@ -175,8 +189,8 @@ Usage:
 
             if (result.wasLimited) {
               readInfo += `Read ${result.linesRead} lines (hit 50KB limit). `;
-            } else {
-              readInfo += `Read lines ${input.offset}-${result.linesRead}. `;
+            } else if (input.offset && input.offset > 1) {
+              readInfo += `Read lines ${input.offset}-${input.offset + result.linesRead}.`;
             }
 
             if (result.wasLimited) {
@@ -194,12 +208,13 @@ Usage:
               },
             ],
           };
-        } catch (error: any) {
+        } catch (error) {
           return {
+            isError: true,
             content: [
               {
                 type: "text",
-                text: "Reading file failed: " + error.message,
+                text: "Reading file failed: " + formatErrorMessage(error),
               },
             ],
           };
@@ -253,15 +268,21 @@ Usage:
           }
           await writeTextFile(input);
 
-          return {
-            content: [],
-          };
-        } catch (error: any) {
           return {
             content: [
               {
                 type: "text",
-                text: "Writing file failed: " + error.message,
+                text: `The file ${input.file_path} has been updated successfully.`,
+              },
+            ],
+          };
+        } catch (error) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: "Writing file failed: " + formatErrorMessage(error),
               },
             ],
           };
@@ -347,12 +368,13 @@ Usage:
               },
             ],
           };
-        } catch (error: any) {
+        } catch (error) {
           return {
+            isError: true,
             content: [
               {
                 type: "text",
-                text: "Editing file failed: " + (error?.message ?? String(error)),
+                text: "Editing file failed: " + formatErrorMessage(error),
               },
             ],
           };
@@ -394,120 +416,132 @@ Output: Create directory 'foo'`),
         },
       },
       async (input: BashInput, 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,
-          env: [{ name: "CLAUDECODE", value: "1" }],
-          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 ?? 2 * 60 * 1000).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,
-              },
+        try {
+          const session = agent.sessions[sessionId];
+          if (!session) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "The user has left the building",
+                },
+              ],
             };
+          }
 
-            return handle.release();
+          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,
+            env: [{ name: "CLAUDECODE", value: "1" }],
+            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 ?? 2 * 60 * 1000).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) }],
+          };
+        } catch (error) {
+          return {
+            isError: true,
             content: [
               {
                 type: "text",
-                text: `Command started in background with id: ${handle.id}`,
+                text: "Running bash command failed: " + formatErrorMessage(error),
               },
             ],
           };
         }
-
-        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) }],
-        };
       },
     );
 
@@ -523,45 +557,104 @@ Output: Create directory 'foo'`),
 
 In sessions with ${acpToolNames.bashOutput} always use it for output from Bash commands instead of TaskOutput.`,
         inputSchema: {
-          bash_id: z
+          task_id: z
             .string()
             .describe(
               `The id of the background bash command as returned by \`${acpToolNames.bash}\``,
             ),
+          block: z.boolean().describe("Whether to wait for completion"),
+          timeout: z.number().describe("Max wait time in ms"),
         },
       },
-      async (input) => {
-        const bgTerm = agent.backgroundTerminals[input.bash_id];
+      async (input: TaskOutputInput) => {
+        try {
+          const bgTerm = agent.backgroundTerminals[input.task_id];
 
-        if (!bgTerm) {
-          throw new Error(`Unknown shell ${input.bash_id}`);
-        }
+          if (!bgTerm) {
+            throw new Error(`Unknown shell ${input.task_id}`);
+          }
 
-        if (bgTerm.status === "started") {
-          const newOutput = await bgTerm.handle.currentOutput();
-          const strippedOutput = stripCommonPrefix(
-            bgTerm.lastOutput?.output ?? "",
-            newOutput.output,
-          );
-          bgTerm.lastOutput = newOutput;
+          if (input.block && bgTerm.status === "started") {
+            const statusPromise = Promise.race([
+              bgTerm.handle
+                .waitForExit()
+                .then((exitStatus) => ({ status: "exited" as const, exitStatus })),
+              sleep(input.timeout ?? 2 * 60 * 1000).then(async () => {
+                if (bgTerm.status === "started") {
+                  await bgTerm.handle.kill();
+                }
+                return { status: "timedOut" as const, exitStatus: null };
+              }),
+            ]);
 
-          return {
-            content: [
-              {
-                type: "text",
-                text: toolCommandOutput(bgTerm.status, {
-                  ...newOutput,
-                  output: strippedOutput,
-                }),
+            const { status, exitStatus } = await statusPromise;
+            const currentOutput = await bgTerm.handle.currentOutput();
+            const strippedOutput = stripCommonPrefix(
+              bgTerm.lastOutput?.output ?? "",
+              currentOutput.output,
+            );
+
+            agent.backgroundTerminals[input.task_id] = {
+              status,
+              pendingOutput: {
+                ...currentOutput,
+                output: strippedOutput,
+                exitStatus: exitStatus ?? currentOutput.exitStatus,
               },
-            ],
-          };
-        } else {
+            };
+
+            await bgTerm.handle.release();
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: toolCommandOutput(status, {
+                    ...currentOutput,
+                    output: strippedOutput,
+                    exitStatus: exitStatus ?? currentOutput.exitStatus,
+                  }),
+                },
+              ],
+            };
+          }
+
+          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),
+                },
+              ],
+            };
+          }
+        } catch (error) {
           return {
+            isError: true,
             content: [
               {
                 type: "text",
-                text: toolCommandOutput(bgTerm.status, bgTerm.pendingOutput),
+                text: "Retrieving bash output failed: " + formatErrorMessage(error),
               },
             ],
           };
@@ -587,50 +680,62 @@ In sessions with ${acpToolNames.killShell} always use it instead of KillShell.`,
             ),
         },
       },
-      async (input: KillShellInput) => {
-        const bgTerm = agent.backgroundTerminals[input.shell_id];
+      async (input) => {
+        try {
+          const bgTerm = agent.backgroundTerminals[input.shell_id];
 
-        if (!bgTerm) {
-          throw new Error(`Unknown shell ${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),
+          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");
+            }
+          }
+        } catch (error) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: "Killing shell failed: " + formatErrorMessage(error),
               },
-            };
-            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");
-          }
+            ],
+          };
         }
       },
     );

src/settings.ts

@@ -128,7 +128,8 @@ function normalizePath(filePath: string, cwd: string): string {
   } else if (!path.isAbsolute(filePath)) {
     filePath = path.join(cwd, filePath);
   }
-  return path.normalize(filePath);
+  // Convert backslashes to forward slashes for minimatch compatibility on Windows
+  return path.normalize(filePath).replace(/\\/g, "/");
 }
 
 /**

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

@@ -21,6 +21,13 @@ import { markdownEscape, toolInfoFromToolUse, toolUpdateFromToolResult } from ".
 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>;
@@ -166,7 +173,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({
@@ -251,7 +258,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "execute",
       title: "`rm README.md.rm`",
       content: [
@@ -276,7 +283,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "search",
       title: "Find `*/**.ts`",
       content: [],
@@ -297,7 +304,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "think",
       title: "Handle user's work request",
       content: [
@@ -322,7 +329,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "search",
       title: "List the `/Users/test/github/claude-code-acp` directory's contents",
       content: [],
@@ -340,7 +347,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "search",
       title: 'grep ".*"',
       content: [],
@@ -358,7 +365,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "edit",
       title: "Write /Users/test/project/example.txt",
       content: [
@@ -384,7 +391,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "edit",
       title: "Write /Users/test/project/config.json",
       content: [
@@ -409,7 +416,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
       title: "Read File",
       content: [],
@@ -427,7 +434,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
       title: "Read /Users/test/project/data.json",
       content: [],
@@ -446,7 +453,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
       title: "Read /Users/test/project/large.txt (1 - 100)",
       content: [],
@@ -466,7 +473,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
       title: "Read /Users/test/project/large.txt (51 - 150)",
       content: [],
@@ -485,7 +492,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "read",
       title: "Read /Users/test/project/large.txt (from line 201)",
       content: [],
@@ -503,7 +510,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "execute",
       title: `Kill Process`,
       content: [],
@@ -520,7 +527,7 @@ describe("tool conversions", () => {
       },
     };
 
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
+    expect(toolInfoFromToolUse(tool_use)).toStrictEqual({
       kind: "execute",
       title: `Tail Logs`,
       content: [],
@@ -613,7 +620,6 @@ describe("tool conversions", () => {
         received.message.role,
         "test",
         {},
-        {},
         {} as AgentSideConnection,
         console,
       ),
@@ -735,6 +741,200 @@ 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("escape markdown", () => {
@@ -847,7 +1047,7 @@ 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();

src/tests/list-sessions.test.ts

@@ -0,0 +1,386 @@
+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";
+
+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 encode a path like Claude does:
+  // - Unix: "/Users/test" -> "-Users-test"
+  // - Windows: "C:\Users\test" -> "C-Users-test"
+  function encodePath(cwd: string): string {
+    // Handle Windows paths
+    if (/^[A-Za-z]:\\/.test(cwd)) {
+      return cwd.replace(/\\/g, "-").replace(":", "");
+    }
+    // Unix paths
+    return cwd.replace(/\//g, "-");
+  }
+
+  // Helper to write a session file
+  function writeSessionFile(
+    cwd: string,
+    sessionId: string,
+    options: {
+      userMessage?: string;
+      userMessageArray?: boolean;
+      mtime?: Date;
+      malformed?: boolean;
+      isAgentFile?: boolean;
+    } = {},
+  ): void {
+    const encodedPath = encodePath(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", message: { content } }));
+    }
+
+    // Assistant response
+    lines.push(JSON.stringify({ type: "assistant", 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("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 = encodePath(cwd);
+    const projectDir = path.join(tempDir, "projects", encodedPath);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    // Write file without sessionId in content
+    const filePath = path.join(projectDir, "fallback-id.jsonl");
+    fs.writeFileSync(filePath, JSON.stringify({ type: "init" }) + "\n");
+
+    const result = await agent.unstable_listSessions({});
+
+    expect(result.sessions[0]!.sessionId).toBe("fallback-id");
+  });
+
+  it("returns null title when no user message exists", async () => {
+    const cwd = "/Users/test/project";
+    const encodedPath = encodePath(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", 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/tools.test.ts

@@ -0,0 +1,318 @@
+import { describe, it, expect } from "vitest";
+import { AgentSideConnection } from "@agentclientprotocol/sdk";
+import { ToolResultBlockParam } from "@anthropic-ai/sdk/resources";
+import {
+  BetaMCPToolResultBlock,
+  BetaTextBlock,
+  BetaWebSearchResultBlock,
+  BetaWebSearchToolResultBlock,
+  BetaBashCodeExecutionToolResultBlock,
+  BetaBashCodeExecutionResultBlock,
+} from "@anthropic-ai/sdk/resources/beta.mjs";
+import { toAcpNotifications, ToolUseCache, Logger } from "../acp-agent.js";
+
+describe("rawOutput in tool call updates", () => {
+  const mockClient = {} as AgentSideConnection;
+  const mockLogger: Logger = { log: () => {}, error: () => {} };
+
+  it("should include rawOutput with string content for tool_result", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_123: {
+        type: "tool_use",
+        id: "toolu_123",
+        name: "Bash",
+        input: { command: "echo hello" },
+      },
+    };
+
+    const toolResult: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_123",
+      content: "hello\n",
+      is_error: false,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_123",
+      status: "completed",
+      rawOutput: "hello\n",
+    });
+  });
+
+  it("should include rawOutput with array content for tool_result", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_456: {
+        type: "tool_use",
+        id: "toolu_456",
+        name: "Read",
+        input: { file_path: "/test/file.txt" },
+      },
+    };
+
+    // ToolResultBlockParam content can be string or array of TextBlockParam
+    const toolResult: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_456",
+      content: [{ type: "text", text: "Line 1\nLine 2\nLine 3" }],
+      is_error: false,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_456",
+      status: "completed",
+      rawOutput: [{ type: "text", text: "Line 1\nLine 2\nLine 3" }],
+    });
+  });
+
+  it("should include rawOutput for mcp_tool_result with string content", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_789: {
+        type: "tool_use",
+        id: "toolu_789",
+        name: "mcp__server__tool",
+        input: { query: "test" },
+      },
+    };
+
+    // BetaMCPToolResultBlock content can be string or Array<BetaTextBlock>
+    const toolResult: BetaMCPToolResultBlock = {
+      type: "mcp_tool_result",
+      tool_use_id: "toolu_789",
+      content: '{"result": "success", "data": [1, 2, 3]}',
+      is_error: false,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_789",
+      status: "completed",
+      rawOutput: '{"result": "success", "data": [1, 2, 3]}',
+    });
+  });
+
+  it("should include rawOutput for mcp_tool_result with array content", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_abc: {
+        type: "tool_use",
+        id: "toolu_abc",
+        name: "mcp__server__search",
+        input: { term: "test" },
+      },
+    };
+
+    // BetaTextBlock requires citations field
+    const arrayContent: BetaTextBlock[] = [
+      { type: "text", text: "Result 1", citations: null },
+      { type: "text", text: "Result 2", citations: null },
+    ];
+
+    const toolResult: BetaMCPToolResultBlock = {
+      type: "mcp_tool_result",
+      tool_use_id: "toolu_abc",
+      content: arrayContent,
+      is_error: false,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_abc",
+      status: "completed",
+      rawOutput: arrayContent,
+    });
+  });
+
+  it("should include rawOutput for web_search_tool_result", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_web: {
+        type: "tool_use",
+        id: "toolu_web",
+        name: "WebSearch",
+        input: { query: "test search" },
+      },
+    };
+
+    // BetaWebSearchResultBlock from SDK
+    const searchResults: BetaWebSearchResultBlock[] = [
+      {
+        type: "web_search_result",
+        url: "https://example.com",
+        title: "Example",
+        encrypted_content: "encrypted content here",
+        page_age: "2 days ago",
+      },
+    ];
+
+    const toolResult: BetaWebSearchToolResultBlock = {
+      type: "web_search_tool_result",
+      tool_use_id: "toolu_web",
+      content: searchResults,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_web",
+      status: "completed",
+      rawOutput: searchResults,
+    });
+  });
+
+  it("should include rawOutput for bash_code_execution_tool_result", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_bash: {
+        type: "tool_use",
+        id: "toolu_bash",
+        name: "Bash",
+        input: { command: "ls -la" },
+      },
+    };
+
+    // BetaBashCodeExecutionResultBlock from SDK
+    const bashResult: BetaBashCodeExecutionResultBlock = {
+      type: "bash_code_execution_result",
+      stdout: "file1.txt\nfile2.txt",
+      stderr: "",
+      return_code: 0,
+      content: [],
+    };
+
+    const toolResult: BetaBashCodeExecutionToolResultBlock = {
+      type: "bash_code_execution_tool_result",
+      tool_use_id: "toolu_bash",
+      content: bashResult,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_bash",
+      status: "completed",
+      rawOutput: bashResult,
+    });
+  });
+
+  it("should set status to failed when is_error is true", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_err: {
+        type: "tool_use",
+        id: "toolu_err",
+        name: "Bash",
+        input: { command: "invalid_command" },
+      },
+    };
+
+    const toolResult: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_err",
+      content: "command not found: invalid_command",
+      is_error: true,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_err",
+      status: "failed",
+      rawOutput: "command not found: invalid_command",
+    });
+  });
+
+  it("should not emit tool_call_update for TodoWrite (emits plan instead)", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_todo: {
+        type: "tool_use",
+        id: "toolu_todo",
+        name: "TodoWrite",
+        input: { todos: [{ content: "Test task", status: "pending" }] },
+      },
+    };
+
+    const toolResult: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_todo",
+      content: "Todos updated successfully",
+      is_error: false,
+    };
+
+    const notifications = toAcpNotifications(
+      [toolResult],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    // TodoWrite should not emit tool_call_update - it emits plan updates instead
+    expect(notifications).toHaveLength(0);
+  });
+});

src/tests/typescript-declarations.test.ts

@@ -0,0 +1,558 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { spawnSync } from "child_process";
+
+describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)(
+  "TypeScript declaration files integration",
+  () => {
+    let tempDir: string;
+    let tarballPath: string;
+    const projectRoot = path.resolve(__dirname, "../..");
+
+    // Base configuration templates
+    const basePackageJson = {
+      name: "ts-declaration-test",
+      version: "1.0.0",
+      type: "module",
+      dependencies: {},
+      devDependencies: {
+        typescript: "5.9.3",
+        "@types/node": "25.0.3",
+      },
+    };
+
+    const baseTsConfig = {
+      compilerOptions: {
+        target: "ES2020",
+        module: "NodeNext",
+        moduleResolution: "NodeNext",
+        lib: ["ES2020"],
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true, // Skip checking dependency internals, focus on our types
+        noEmit: true,
+        declaration: false,
+      },
+      include: ["*.ts"],
+    };
+
+    // Build and pack the package once for all tests
+    beforeAll(async () => {
+      // Step 1: Clean dist folder to ensure fresh build
+      const distPath = path.join(projectRoot, "dist");
+      await fs.promises.rm(distPath, { recursive: true, force: true });
+      console.log("Cleaned dist folder");
+
+      console.log("Building package...");
+
+      // Step 2: Build the package
+      const buildResult = spawnSync("npm", ["run", "build"], {
+        cwd: projectRoot,
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
+
+      if (buildResult.status !== 0) {
+        throw new Error(`Build failed: ${buildResult.stderr || buildResult.stdout}`);
+      }
+
+      console.log("Packing package...");
+
+      // Step 3: Pack to create tarball
+      const packResult = spawnSync("npm", ["pack", "--pack-destination", os.tmpdir()], {
+        cwd: projectRoot,
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
+
+      if (packResult.status !== 0) {
+        throw new Error(`Pack failed: ${packResult.stderr || packResult.stdout}`);
+      }
+
+      // Get the tarball filename from stdout (npm pack outputs the filename)
+      const tarballName = packResult.stdout.trim().split("\n").pop();
+      if (!tarballName) {
+        throw new Error("Failed to get tarball name from npm pack output");
+      }
+      tarballPath = path.join(os.tmpdir(), tarballName);
+
+      console.log(`Tarball created at: ${tarballPath}`);
+    }, 60000); // 60 second timeout for build
+
+    // Clean up the tarball after all tests
+    afterAll(async () => {
+      if (tarballPath && fs.existsSync(tarballPath)) {
+        await fs.promises.unlink(tarballPath);
+        console.log("Cleaned up tarball");
+      }
+    });
+
+    // Create fresh temp directory for each test
+    beforeEach(async () => {
+      tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "ts-declaration-test-"));
+    });
+
+    // Clean up temp directory after each test
+    afterEach(async () => {
+      if (tempDir) {
+        await fs.promises.rm(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    // Helper function to set up a test TypeScript project
+    async function setupTestProject(
+      packageJson: object = basePackageJson,
+      tsconfig: object = baseTsConfig,
+    ): Promise<void> {
+      // Write package.json
+      await fs.promises.writeFile(
+        path.join(tempDir, "package.json"),
+        JSON.stringify(packageJson, null, 2),
+      );
+
+      // Write tsconfig.json
+      await fs.promises.writeFile(
+        path.join(tempDir, "tsconfig.json"),
+        JSON.stringify(tsconfig, null, 2),
+      );
+
+      // Install all dependencies (TypeScript, @types/node, and the tarball)
+      console.log(`Installing dependencies in ${tempDir}...`);
+      const installResult = spawnSync("npm", ["install", tarballPath], {
+        cwd: tempDir,
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 60000, // 60 second timeout
+      });
+
+      if (installResult.status !== 0) {
+        throw new Error(`npm install failed: ${installResult.stderr || installResult.stdout}`);
+      }
+    }
+
+    // Helper function to run TypeScript type checking
+    function runTypeCheck(srcDir: string = tempDir): {
+      success: boolean;
+      output: string;
+    } {
+      const result = spawnSync("npx", ["tsc", "--noEmit"], {
+        cwd: srcDir,
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 30000, // 30 second timeout
+      });
+
+      return {
+        success: result.status === 0,
+        output: result.stdout + result.stderr,
+      };
+    }
+
+    // Helper function to write a test TypeScript file
+    async function writeTestFile(filename: string, content: string): Promise<void> {
+      await fs.promises.writeFile(path.join(tempDir, filename), content);
+    }
+
+    // Test 1: Main exports import verification
+    it("should successfully type-check main exports", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-main-exports.ts",
+        `
+import {
+  ClaudeAcpAgent,
+  runAcp,
+  toAcpNotifications,
+  streamEventToAcpNotifications,
+  SettingsManager,
+  createMcpServer,
+  loadManagedSettings,
+  applyEnvironmentSettings,
+  nodeToWebReadable,
+  nodeToWebWritable,
+  Pushable,
+  unreachable,
+  toolInfoFromToolUse,
+  planEntries,
+  toolUpdateFromToolResult,
+  createPreToolUseHook,
+  toolNames,
+} from "@zed-industries/claude-code-acp";
+
+// Type-only imports
+import type {
+  ToolUpdateMeta,
+  NewSessionMeta,
+  ClaudeCodeSettings,
+  PermissionSettings,
+  PermissionDecision,
+  PermissionCheckResult,
+  SettingsManagerOptions,
+  ClaudePlanEntry,
+} from "@zed-industries/claude-code-acp";
+
+// Verify exports exist and have expected types
+const _runAcp: typeof runAcp = runAcp;
+const _createMcpServer: typeof createMcpServer = createMcpServer;
+const _toolNames: typeof toolNames = toolNames;
+`,
+      );
+
+      const result = runTypeCheck();
+      if (!result.success) {
+        console.error("TypeScript errors:", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+
+    // Test 2: Deep imports verification (backwards compatibility)
+    it("should successfully type-check deep imports", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-deep-imports.ts",
+        `
+// Deep import from dist/tools.js
+import {
+  acpToolNames,
+  EDIT_TOOL_NAMES,
+  ACP_TOOL_NAME_PREFIX,
+  toolInfoFromToolUse,
+  planEntries,
+} from "@zed-industries/claude-code-acp/dist/tools.js";
+
+// Deep import from dist/settings.js
+import {
+  SettingsManager,
+  getManagedSettingsPath,
+} from "@zed-industries/claude-code-acp/dist/settings.js";
+
+// Deep import from dist/utils.js
+import {
+  Pushable,
+  nodeToWebReadable,
+  nodeToWebWritable,
+  loadManagedSettings,
+} from "@zed-industries/claude-code-acp/dist/utils.js";
+
+// Verify types work
+const prefix: string = ACP_TOOL_NAME_PREFIX;
+const editTools: readonly string[] = EDIT_TOOL_NAMES;
+`,
+      );
+
+      const result = runTypeCheck();
+      if (!result.success) {
+        console.error("TypeScript errors:", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+
+    // Test 3: SettingsManager type shape verification
+    it("should verify SettingsManager has correct type shape", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-settings-manager.ts",
+        `
+import {
+  SettingsManager,
+  ClaudeCodeSettings,
+  PermissionCheckResult,
+  SettingsManagerOptions
+} from "@zed-industries/claude-code-acp";
+
+// Test constructor signature
+const options: SettingsManagerOptions = {
+  onChange: () => {},
+  logger: { log: console.log, error: console.error },
+};
+declare const cwd: string;
+const manager = new SettingsManager(cwd, options);
+
+// Test method signatures
+async function testMethods() {
+  // initialize returns Promise<void>
+  await manager.initialize();
+
+  // checkPermission returns PermissionCheckResult
+  const result: PermissionCheckResult = manager.checkPermission(
+    "mcp__acp__Read",
+    { file_path: "/some/path" }
+  );
+
+  // Verify decision type
+  const decision: "allow" | "deny" | "ask" = result.decision;
+  const rule: string | undefined = result.rule;
+  const source: "allow" | "deny" | "ask" | undefined = result.source;
+
+  // getSettings returns ClaudeCodeSettings
+  const settings: ClaudeCodeSettings = manager.getSettings();
+
+  // getCwd returns string
+  const currentCwd: string = manager.getCwd();
+
+  // setCwd returns Promise<void>
+  await manager.setCwd("/new/path");
+
+  // dispose returns void
+  manager.dispose();
+}
+`,
+      );
+
+      const result = runTypeCheck();
+      if (!result.success) {
+        console.error("TypeScript errors:", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+
+    // Test 4: ClaudeAcpAgent instantiation and type verification
+    it("should verify ClaudeAcpAgent has correct type shape", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-claude-acp-agent.ts",
+        `
+import { ClaudeAcpAgent } from "@zed-industries/claude-code-acp";
+import type { AgentSideConnection } from "@agentclientprotocol/sdk";
+
+// ClaudeAcpAgent should be a class that can be instantiated
+declare const mockConnection: AgentSideConnection;
+declare const mockLogger: { log: (...args: any[]) => void; error: (...args: any[]) => void };
+
+// Test constructor - accepts AgentSideConnection and optional logger
+const agent = new ClaudeAcpAgent(mockConnection, mockLogger);
+
+// Verify it has sessions property
+const sessions: Record<string, any> = agent.sessions;
+
+// Verify it has client property
+const client: AgentSideConnection = agent.client;
+
+// Verify it has logger property
+const logger = agent.logger;
+`,
+      );
+
+      const result = runTypeCheck();
+      if (!result.success) {
+        console.error("TypeScript errors:", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+
+    // Test 5: Type-only exports work correctly
+    it("should verify type-only exports are usable", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-type-exports.ts",
+        `
+import type {
+  ClaudeCodeSettings,
+  PermissionSettings,
+  PermissionDecision,
+  PermissionCheckResult,
+  SettingsManagerOptions,
+  ClaudePlanEntry,
+  ToolUpdateMeta,
+  NewSessionMeta,
+} from "@zed-industries/claude-code-acp";
+
+// Test ClaudeCodeSettings shape
+const settings: ClaudeCodeSettings = {
+  permissions: {
+    allow: ["Read"],
+    deny: ["Read(./.env)"],
+    ask: ["Bash"],
+    additionalDirectories: ["/extra"],
+    defaultMode: "default",
+  },
+  env: {
+    API_KEY: "secret",
+  },
+};
+
+// Test PermissionSettings shape
+const perms: PermissionSettings = {
+  allow: ["Read"],
+  deny: ["Write"],
+};
+
+// Test PermissionDecision
+const decisions: PermissionDecision[] = ["allow", "deny", "ask"];
+
+// Test ClaudePlanEntry shape
+const planEntry: ClaudePlanEntry = {
+  content: "Do something",
+  status: "pending",
+  activeForm: "Doing something",
+};
+
+// Test valid status values
+const validStatuses: ClaudePlanEntry["status"][] = [
+  "pending",
+  "in_progress",
+  "completed",
+];
+
+// Test ToolUpdateMeta shape
+const toolMeta: ToolUpdateMeta = {
+  claudeCode: {
+    toolName: "Read",
+    toolResponse: { success: true },
+  },
+};
+
+// Test NewSessionMeta shape
+const sessionMeta: NewSessionMeta = {
+  claudeCode: {
+    options: {},
+  },
+};
+`,
+      );
+
+      const result = runTypeCheck();
+      if (!result.success) {
+        console.error("TypeScript errors:", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+
+    // Test 6: Function signatures verification
+    it("should verify function signatures are correct", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-function-signatures.ts",
+        `
+import {
+  runAcp,
+  createMcpServer,
+  toolInfoFromToolUse,
+  planEntries,
+  createPreToolUseHook,
+  loadManagedSettings,
+  applyEnvironmentSettings,
+  SettingsManager,
+} from "@zed-industries/claude-code-acp";
+
+import type { ClaudeCodeSettings } from "@zed-industries/claude-code-acp";
+
+// runAcp should be a function with no parameters that returns void
+const runAcpType: () => void = runAcp;
+
+// toolInfoFromToolUse should accept any and return object with title and kind
+const info = toolInfoFromToolUse({ name: "Read", input: {} });
+const title: string = info.title;
+const kind: string = info.kind;
+
+// planEntries should accept todos array and return array
+const entries = planEntries({
+  todos: [
+    { content: "test", status: "pending", activeForm: "testing" }
+  ]
+});
+// entries should be an array
+const entriesArray: any[] = entries;
+
+// createPreToolUseHook should accept SettingsManager and optional logger
+declare const settingsManager: SettingsManager;
+const hook = createPreToolUseHook(settingsManager, console);
+
+// loadManagedSettings should return ClaudeCodeSettings | null
+const managedSettings: ClaudeCodeSettings | null = loadManagedSettings();
+
+// applyEnvironmentSettings should accept ClaudeCodeSettings and return void
+const applyResult: void = applyEnvironmentSettings({ permissions: {} });
+`,
+      );
+
+      const result = runTypeCheck();
+      if (!result.success) {
+        console.error("TypeScript errors:", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+
+    // Test 7: Pushable generic class verification
+    it("should verify Pushable class works correctly", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-pushable.ts",
+        `
+import { Pushable } from "@zed-industries/claude-code-acp";
+
+// Pushable should be a generic class
+const pushable = new Pushable<string>();
+
+// Should have push method
+pushable.push("test");
+
+// Should have end method
+pushable.end();
+
+// Should implement AsyncIterable
+async function consume() {
+  for await (const item of pushable) {
+    const str: string = item;
+  }
+}
+
+// Generic type parameter should work
+const numPushable = new Pushable<number>();
+numPushable.push(42);
+
+interface MyType { id: number; name: string; }
+const customPushable = new Pushable<MyType>();
+customPushable.push({ id: 1, name: "test" });
+`,
+      );
+
+      const result = runTypeCheck();
+      if (!result.success) {
+        console.error("TypeScript errors:", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+
+    // Test 8: Verify incorrect types fail
+    it("should fail type-check with incorrect types", async () => {
+      await setupTestProject();
+
+      await writeTestFile(
+        "test-invalid-types.ts",
+        `
+import { SettingsManager, ClaudeCodeSettings } from "@zed-industries/claude-code-acp";
+
+// This should fail - SettingsManager constructor requires string cwd
+// @ts-expect-error - Testing that wrong argument type fails
+const badManager = new SettingsManager(123);
+
+// This should fail - ClaudeCodeSettings permissions must be an object
+const badSettings: ClaudeCodeSettings = {
+  // @ts-expect-error - Testing that wrong type fails
+  permissions: "not-an-object",
+};
+`,
+      );
+
+      // This test should PASS because we expect tsc to catch these errors
+      // with @ts-expect-error directives
+      const result = runTypeCheck();
+      if (!result.success) {
+        // If it fails, it means @ts-expect-error didn't catch the error
+        // which could mean the types are too permissive
+        console.error("TypeScript errors (expected @ts-expect-error to catch):", result.output);
+      }
+      expect(result.success).toBe(true);
+    }, 120000);
+  },
+);

src/tools.ts

@@ -1,6 +1,44 @@
-import { PlanEntry, ToolCallContent, ToolCallLocation, ToolKind } from "@agentclientprotocol/sdk";
-import { replaceAndCalculateLocation, SYSTEM_REMINDER } from "./mcp-server.js";
-import { ToolResultBlockParam, WebSearchToolResultBlockParam } from "@anthropic-ai/sdk/resources";
+import {
+  ContentBlock,
+  PlanEntry,
+  ToolCallContent,
+  ToolCallLocation,
+  ToolKind,
+} from "@agentclientprotocol/sdk";
+import { SYSTEM_REMINDER } from "./mcp-server.js";
+import * as diff from "diff";
+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";
 
 const acpUnqualifiedToolNames = {
   read: "Read",
@@ -23,15 +61,29 @@ export const acpToolNames = {
 
 export const EDIT_TOOL_NAMES = [acpToolNames.edit, acpToolNames.write];
 
-import {
-  BetaBashCodeExecutionToolResultBlockParam,
-  BetaCodeExecutionToolResultBlockParam,
-  BetaRequestMCPToolResultBlockParam,
-  BetaTextEditorCodeExecutionToolResultBlockParam,
-  BetaToolSearchToolResultBlockParam,
-  BetaWebFetchToolResultBlockParam,
-  BetaWebSearchToolResultBlockParam,
-} 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 { SettingsManager } from "./settings.js";
@@ -49,11 +101,7 @@ interface ToolUpdate {
   locations?: ToolCallLocation[];
 }
 
-export function toolInfoFromToolUse(
-  toolUse: any,
-  cachedFileContent: { [key: string]: string },
-  logger: Logger = console,
-): ToolInfo {
+export function toolInfoFromToolUse(toolUse: any): ToolInfo {
   const name = toolUse.name;
   const input = toolUse.input;
 
@@ -178,27 +226,7 @@ export function toolInfoFromToolUse(
     case acpToolNames.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) {
-          logger.error(e);
-        }
-      }
       return {
         title: path ? `Edit \`${path}\`` : "Edit",
         kind: "edit",
@@ -208,16 +236,12 @@ export function toolInfoFromToolUse(
                 {
                   type: "diff",
                   path,
-                  oldText,
-                  newText,
+                  oldText: input.old_string ?? null,
+                  newText: input.new_string ?? "",
                 },
               ]
             : [],
-        locations: path
-          ? affectedLines.length > 0
-            ? affectedLines.map((line) => ({ line, path }))
-            : [{ path }]
-          : [],
+        locations: path ? [{ path }] : undefined,
       };
     }
 
@@ -332,7 +356,9 @@ export function toolInfoFromToolUse(
         label += " -P";
       }
 
-      label += ` "${input.pattern}"`;
+      if (input.pattern) {
+        label += ` "${input.pattern}"`;
+      }
 
       if (input.path) {
         label += ` ${input.path}`;
@@ -431,6 +457,7 @@ export function toolInfoFromToolUse(
 export function toolUpdateFromToolResult(
   toolResult:
     | ToolResultBlockParam
+    | BetaToolResultBlockParam
     | BetaWebSearchToolResultBlockParam
     | BetaWebFetchToolResultBlockParam
     | WebSearchToolResultBlockParam
@@ -441,6 +468,16 @@ export function toolUpdateFromToolResult(
     | BetaToolSearchToolResultBlockParam,
   toolUse: any | undefined,
 ): 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 acpToolNames.read:
@@ -472,21 +509,60 @@ export function toolUpdateFromToolResult(
       }
       return {};
 
+    case acpToolNames.edit: {
+      const content: ToolCallContent[] = [];
+      const locations: ToolCallLocation[] = [];
+
+      if (
+        Array.isArray(toolResult.content) &&
+        toolResult.content.length > 0 &&
+        "text" in toolResult.content[0] &&
+        typeof toolResult.content[0].text === "string"
+      ) {
+        const patches = diff.parsePatch(toolResult.content[0].text);
+        console.error(JSON.stringify(patches));
+        for (const { oldFileName, newFileName, hunks } of patches) {
+          for (const { lines, newStart } of hunks) {
+            const oldText = [];
+            const newText = [];
+            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: newFileName || oldFileName, line: newStart });
+              content.push({
+                type: "diff",
+                path: newFileName || oldFileName,
+                oldText: oldText.join("\n") || null,
+                newText: newText.join("\n"),
+              });
+            }
+          }
+        }
+      }
+
+      const result: ToolUpdate = {};
+      if (content.length > 0) {
+        result.content = content;
+      }
+      if (locations.length > 0) {
+        result.locations = locations;
+      }
+      return result;
+    }
+
     case acpToolNames.bash:
     case "edit":
     case "Edit":
-    case acpToolNames.edit:
     case acpToolNames.write:
     case "Write": {
-      if (
-        "is_error" in toolResult &&
-        toolResult.is_error &&
-        toolResult.content &&
-        toolResult.content.length > 0
-      ) {
-        // Only return errors
-        return toAcpContentUpdate(toolResult.content, true);
-      }
       return {};
     }
 
@@ -523,17 +599,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: [
@@ -550,6 +629,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";
@@ -605,16 +752,28 @@ export const registerHookCallback = (
 
 /* A callback for Claude Code that is called when receiving a PostToolUse hook */
 export const createPostToolUseHook =
-  (logger: Logger = console): HookCallback =>
+  (
+    logger: Logger = console,
+    options?: {
+      onEnterPlanMode?: () => Promise<void>;
+    },
+  ): 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 {
-        logger.error(`No onPostToolUseHook found for tool use ID: ${toolUseID}`);
-        delete toolUseCallbacks[toolUseID];
+    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 };

tsconfig.json

@@ -9,7 +9,9 @@
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true
   },
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]