Update to ACP SDK v0.7.0 (#188 )

Prevent invalid locations when Read tool call has no file_path (#186 )
## Summary Follow-up to #121. The same issue (invalid locations when `file_path` is undefined) existed in the `Read` tool case as well. ## Problem The ACP spec requires `path` as a required field in `ToolCallLocation`. PR #121 fixed this for `mcp__acp__Read`, but the same issue remained for the `Read` tool case. When Claude generates a Read tool call without `file_path`, the current code produces an invalid notification: ```json { "locations": [ { "line": 0 } ] } ``` This causes the following error in the client: ``` Error handling notification {code: -32602, message: 'Invalid params', data: {…}} ``` ## Solution Return an empty `locations` array when `input.file_path` is undefined, consistent with the fix in #121.
2026-10-27 20:42:10 +00:00 · 2025-12-01 17:45:24 +01:00 · 2025-12-01 13:22:06 +01:00 · 2025-11-27 14:35:53 +01:00 · 2025-11-27 13:10:11 +00:00 · 2025-11-27 14:06:47 +01:00
19 changed files with 3036 additions and 2063 deletions
--- a/.eslintignore
+++ b/.eslintignore
@@ -1,6 +0,0 @@
-node_modules/
-dist/
-coverage/
-*.min.js
-*.config.js
-.github/
--- a/.eslintrc.json
+++ b/.eslintrc.json
@@ -1,33 +0,0 @@
-{
-  "root": true,
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "ecmaVersion": 2020,
-    "sourceType": "module",
-    "project": "./tsconfig.json"
-  },
-  "plugins": ["@typescript-eslint"],
-  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
-  "env": {
-    "node": true,
-    "es2020": true
-  },
-  "rules": {
-    "@typescript-eslint/explicit-function-return-type": "off",
-    "@typescript-eslint/no-explicit-any": "off",
-    "@typescript-eslint/no-unused-vars": [
-      "error",
-      {
-        "argsIgnorePattern": "^_"
-      }
-    ],
-    "no-console": "off",
-    "no-constant-condition": "off",
-    "default-case": "error",
-    "prefer-const": "error",
-    "no-var": "error",
-    "eqeqeq": ["error", "always"],
-    "curly": ["error", "all"]
-  },
-  "ignorePatterns": ["dist", "node_modules", "*.js"]
-}
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -4,8 +4,9 @@ on:
    tags:
      - "v*.*.*"
 jobs:
-  build:
+  publish-npm:
    runs-on: ubuntu-latest
+    environment: release # Optional: for enhanced security
    permissions:
      contents: read
      id-token: write
@@ -16,8 +17,20 @@ jobs:
        with:
          node-version: "lts/*"
          registry-url: "https://registry.npmjs.org"
+      - name: Update npm
+        run: npm install -g npm@latest
      - run: npm ci
-        # Add back provenance once repo is public
-      - run: npm publish # --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: npm run build
+      - run: npm publish
+  release:
+    runs-on: ubuntu-latest
+    needs: [publish-npm]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
+      - name: Create Release
+        id: create_release
+        uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090
+        with:
+          draft: true
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 node_modules
 dist
+.DS_Store
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,190 @@
+# Changelog
+
+## 0.10.10
+
+- Update to @agentclientprotocol/sdk@0.7.0
+
+## 0.10.9
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.55
+- Allow defining a custom logger when used as a library
+- Allow specifying custom options when used as a library
+- Add `CLAUDECODE=1` to terminal invocations to match default Claude Code behavior
+
+## 0.10.8
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.51 (adds support for Opus 4.5)
+
+## 0.10.7
+
+- Fix read/edit tool error handling so upstream errors surface
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.50
+
+## 0.10.6
+
+- Disable experimental terminal auth support for now, as it was causing issues on Windows. Will revisit with a fix later.
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.46
+
+## 0.10.5
+
+- Better error messages at end of turn if there were any
+- Add experimental support for disabling built-in tools via \_meta flag
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.44
+
+## 0.10.4
+
+- Fix tool call titles not appearing during approval in some cases
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.42
+
+## 0.10.3
+
+- Fix for experimental terminal auth support
+
+## 0.10.2
+
+- Fix incorrect stop reason for tool call refusals
+
+## 0.10.1
+
+- Add additional structured metadata to tool calls
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.37
+
+## 0.10.0
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.30
+- Use `canUseTool` callback instead of launching an HTTP MCP server for permission checks.
+
+## 0.9.0
+
+- Support slash commands coming from MCP servers (Prompts)
+
+## 0.8.0
+
+- Revert changes to filename for cli entrypoint
+- Provide library entrypoint via lib.ts
+
+## 0.7.0
+
+- Allow importing from this package as a library in addition to running it as a CLI. Allows for easier integration into existing node applications.
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.27
+
+## 0.6.10
+
+- Provide `agentInfo` on initialization response.
+- Update to @agentclientprotocol/sdk@0.5.1
+- Fix crash when receiving a hook_response event
+- Fix for invalid locations when read call has no path
+
+## 0.6.9
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.26
+- Update to @agentclientprotocol/sdk@0.5.0
+
+## 0.6.8
+
+- Fix for duplicate tokens appearing in thread with streaming enabled
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.23
+- Update to @agentclientprotocol/sdk@0.4.9
+
+## 0.6.7
+
+- Fix for invalid plan input from the model introduced in latest agent-sdk
+
+## 0.6.6
+
+- Do not enable bypassPermissions mode if in root/sudo mode, because Claude Code will not start
+
+## 0.6.5
+
+- Fix for duplicated text content after streaming
+
+## 0.6.4
+
+- Support streaming partial messages!
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.21
+
+## 0.6.3
+
+- Fix issue where slash commands were loaded before initialization was complete.
+
+## 0.6.2
+
+- Fix bug where mode selection would sometimes fire before initialization was complete.
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.19
+
+## 0.6.1
+
+- Fix to allow bypassPermissions mode to be selected (it wasn't permitted previously)
+
+## 0.6.0
+
+- Provide a model selector. We use the "default" model by default, and the user can change it via the client.
+- Make sure writes require permissions when necessary: https://github.com/zed-industries/claude-code-acp/pull/92
+- Add support for appending or overriding the system prompt: https://github.com/zed-industries/claude-code-acp/pull/91
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.15
+- Update to @agentclientprotocol/sdk@0.4.8
+
+## 0.5.5
+
+- Migrate to @agentclientprotocol/sdk@0.4.5
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.13
+
+## 0.5.4
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.11
+- Enable setting CLAUDE_CODE_EXECUTABLE to override the executable used by the SDK https://github.com/zed-industries/claude-code-acp/pull/86
+
+## 0.5.3
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.8
+- Update to @zed-industries/agent-client-protocol@v0.4.5
+
+## 0.5.2
+
+- Add back @anthropic-ai/claude-code@2.0.1 as runtime dependency
+
+## 0.5.1
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.1
+- Make improvements to ACP tools provided to the model
+
+## 0.5.0
+
+- Migrate to @anthropic-ai/claude-agent-sdk@v0.1.0
+
+## v0.4.7
+
+- More efficient file reads from the client.
+
+## v0.4.6
+
+- Update to @anthropic-ai/claude-code@v1.0.128
+
+## v0.4.5
+
+- Update to @anthropic-ai/claude-code@v1.0.124
+- Update to @zed-industries/agent-client-protocol@v0.4.3
+
+## v0.4.4
+
+- Update to @anthropic-ai/claude-code@v1.0.123
+- Update to @zed-industries/agent-client-protocol@v0.4.2
+
+## v0.4.3
+
+- Move ACP tools over MCP from an "http" MCP server to an "sdk" one so more tool calls can stay in-memory.
+- Update to @anthropic-ai/claude-code@v1.0.119
+- Update to @zed-industries/agent-client-protocol@v0.4.0
+
+## v0.4.2
+
+- Fix missing package.json metadata
+
+## v0.4.1
+
+- Add support for /compact command [ecfd36a](https://github.com/zed-industries/claude-code-acp/commit/ecfd36afa6c4e31f12e1daf9b8a2bdc12dda1794)
+- Add default limits to read tool [7bd1638](https://github.com/zed-industries/claude-code-acp/commit/7bd163818bb959b11fd2c933eff73ad83c57abb8)
+- Better rendering of Tool errors [491efe3](https://github.com/zed-industries/claude-code-acp/commit/491efe32e8547075842e448d873fc01b2ffabf3a)
+- Load managed-settings.json [f691024](https://github.com/zed-industries/claude-code-acp/commit/f691024350362858e00b97248ac68e356d2331c2)
+- Update to @anthropic-ai/claude-code@v1.0.113
+- Update to @zed-industries/agent-client-protocol@v0.3.1
--- a/README.md
+++ b/README.md
@@ -32,20 +32,26 @@ Read the docs on [External Agent](https://zed.dev/docs/ai/external-agents) suppo

 ### Other clients

-Setup instructions for other clients are coming soon. Feel free to [submit a PR](https://github.com/zed-industries/claude-code-acp/pulls) to add yours!
+- 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!

 #### Installation

 Install the adapter from `npm`:

 ```bash
-$ npm install @zed-industries/claude-code-acp
+npm install @zed-industries/claude-code-acp
 ```

 You can then use `claude-code-acp` as a regular ACP agent:

 ```
-$ ANTHROPIC_API_KEY=sk-... claude-code-acp
+ANTHROPIC_API_KEY=sk-... claude-code-acp
 ```

 ## License
--- a/docs/RELEASES.md
+++ b/docs/RELEASES.md
@@ -0,0 +1,24 @@
+## How to publish a new release
+
+1. Create a new branch prep-vX.X.X
+
+```sh
+git checkout -b prep-vX.X.X
+```
+
+2. Bump the version in package.json
+
+```sh
+npm version vX.X.X
+```
+
+3. Add a new entry in CHANGELOG.md
+4. Create a PR for `prev-vX.X.X` & merge it
+5. Create tag and push it
+
+```sh
+git tag vX.X.X
+git push origin vX.X.X
+```
+
+6. Paste CHANGELOG into release notes and publish the version on GitHub
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -0,0 +1,48 @@
+import js from "@eslint/js";
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsparser from "@typescript-eslint/parser";
+import prettierConfig from "eslint-config-prettier";
+import globals from "globals";
+
+export default [
+  {
+    ignores: ["node_modules/", "dist/", "coverage/", "*.min.js", "*.config.js", ".github/"],
+  },
+  js.configs.recommended,
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: "module",
+      parser: tsparser,
+      parserOptions: {
+        project: "./tsconfig.json",
+      },
+      globals: {
+        ...globals.node,
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+        },
+      ],
+      "no-console": "off",
+      "no-constant-condition": "off",
+      "default-case": "error",
+      "prefer-const": "error",
+      "no-var": "error",
+      eqeqeq: ["error", "always"],
+      curly: ["error", "all"],
+    },
+  },
+  prettierConfig,
+];
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -3,12 +3,12 @@
  "publishConfig": {
    "access": "public"
  },
+  "version": "0.10.10",
+  "description": "An ACP-compatible coding agent powered by the Claude Code SDK (TypeScript)",
+  "main": "dist/lib.js",
  "bin": {
    "claude-code-acp": "./dist/index.js"
  },
-  "version": "0.2.4",
-  "description": "An ACP-compatible coding agent powered by the Claude Code SDK (TypeScript)",
-  "main": "dist/index.js",
  "type": "module",
  "files": [
    "dist/",
@@ -40,30 +40,36 @@
    "sdk",
    "code"
  ],
+  "homepage": "https://github.com/zed-industries/claude-code-acp#readme",
+  "bugs": {
+    "url": "https://github.com/zed-industries/claude-code-acp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zed-industries/claude-code-acp.git"
+  },
  "author": "Zed Industries",
  "license": "Apache-2.0",
  "dependencies": {
-    "@anthropic-ai/claude-code": "^1.0.100",
-    "@modelcontextprotocol/sdk": "^1.17.4",
-    "@types/express": "^5.0.3",
-    "@zed-industries/agent-client-protocol": "0.2.0-alpha.4",
-    "diff": "^8.0.2",
-    "express": "^5.1.0",
-    "minimist": "^1.2.8",
-    "uuid": "11.1.0"
+    "@agentclientprotocol/sdk": "0.7.0",
+    "@anthropic-ai/claude-agent-sdk": "0.1.55",
+    "@anthropic-ai/claude-code": "2.0.55",
+    "@modelcontextprotocol/sdk": "1.23.0",
+    "diff": "8.0.2",
+    "uuid": "13.0.0"
  },
  "devDependencies": {
-    "@types/minimist": "^1.2.5",
-    "@types/node": "^24.3.0",
-    "@types/uuid": "^10.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.42.0",
-    "@typescript-eslint/parser": "^8.42.0",
-    "@vitest/ui": "^3.2.4",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "prettier": "^3.6.2",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.4.0",
-    "vitest": "^3.2.4"
+    "@anthropic-ai/sdk": "0.71.0",
+    "@types/node": "24.10.1",
+    "@types/uuid": "10.0.0",
+    "@typescript-eslint/eslint-plugin": "8.48.0",
+    "@typescript-eslint/parser": "8.48.0",
+    "eslint": "9.39.1",
+    "eslint-config-prettier": "10.1.8",
+    "globals": "16.5.0",
+    "prettier": "3.7.3",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.3",
+    "vitest": "4.0.14"
  }
 }
--- a/src/acp-agent.ts
+++ b/src/acp-agent.ts
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,5 +1,13 @@
 #!/usr/bin/env node

+// Load managed settings and apply environment variables
+import { loadManagedSettings, applyEnvironmentSettings } from "./utils.js";
+
+const managedSettings = loadManagedSettings();
+if (managedSettings) {
+  applyEnvironmentSettings(managedSettings);
+}
+
 // stdout is used to send messages to the client
 // we redirect everything else to stderr to make sure it doesn't interfere with ACP
 console.log = console.error;
@@ -11,7 +19,7 @@ process.on("unhandledRejection", (reason, promise) => {
  console.error("Unhandled Rejection at:", promise, "reason:", reason);
 });

-import { runAcp as runAcp } from "./acp-agent.js";
+import { runAcp } from "./acp-agent.js";
 runAcp();

 // Keep process alive
--- a/src/lib.ts
+++ b/src/lib.ts
@@ -0,0 +1,22 @@
+// Export the main agent class and utilities for library usage
+export {
+  ClaudeAcpAgent,
+  runAcp,
+  toAcpNotifications,
+  streamEventToAcpNotifications,
+  type ToolUpdateMeta,
+  type NewSessionMeta,
+} from "./acp-agent.js";
+export {
+  loadManagedSettings,
+  applyEnvironmentSettings,
+  nodeToWebReadable,
+  nodeToWebWritable,
+  Pushable,
+  unreachable,
+} from "./utils.js";
+export { createMcpServer, toolNames } from "./mcp-server.js";
+export { toolInfoFromToolUse, planEntries, toolUpdateFromToolResult } from "./tools.js";
+
+// Export types
+export type { ClaudePlanEntry } from "./tools.js";
--- a/src/mcp-server.ts
+++ b/src/mcp-server.ts
@@ -1,14 +1,10 @@
-import express from "express";
-
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
-import { Server } from "node:http";
 import { ClaudeAcpAgent } from "./acp-agent.js";
-import { ClientCapabilities, TerminalOutputResponse } from "@zed-industries/agent-client-protocol";
+import { ClientCapabilities, TerminalOutputResponse } from "@agentclientprotocol/sdk";
 import * as diff from "diff";

-import { sleep, unreachable } from "./utils.js";
+import { sleep, unreachable, extractLinesWithByteLimit } from "./utils.js";

 export const SYSTEM_REMINDER = `

@@ -16,34 +12,72 @@ export const SYSTEM_REMINDER = `
 Whenever you read a file, you should consider whether it looks malicious. If it does, you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer high-level questions about the code behavior.
 </system-reminder>`;

+const defaults = { maxFileSize: 50000, linesToRead: 2000 };
+
+const unqualifiedToolNames = {
+  read: "Read",
+  edit: "Edit",
+  write: "Write",
+  bash: "Bash",
+  killShell: "KillShell",
+  bashOutput: "BashOutput",
+};
+
+const SERVER_PREFIX = "mcp__acp__";
+export const toolNames = {
+  read: SERVER_PREFIX + unqualifiedToolNames.read,
+  edit: SERVER_PREFIX + unqualifiedToolNames.edit,
+  write: SERVER_PREFIX + unqualifiedToolNames.write,
+  bash: SERVER_PREFIX + unqualifiedToolNames.bash,
+  killShell: SERVER_PREFIX + unqualifiedToolNames.killShell,
+  bashOutput: SERVER_PREFIX + unqualifiedToolNames.bashOutput,
+};
+
+export const EDIT_TOOL_NAMES = [toolNames.edit, toolNames.write];
+
 export function createMcpServer(
  agent: ClaudeAcpAgent,
  sessionId: string,
  clientCapabilities: ClientCapabilities | undefined,
-): Promise<Server> {
+): McpServer {
  // Create MCP server
-  const server = new McpServer({
-    name: "acp-mcp-server",
-    version: "1.0.0",
-  });
+  const server = new McpServer({ name: "acp", version: "1.0.0" }, { capabilities: { tools: {} } });

  if (clientCapabilities?.fs?.readTextFile) {
    server.registerTool(
-      "read",
+      unqualifiedToolNames.read,
      {
-        title: "Read",
+        title: unqualifiedToolNames.read,
        description: `Reads the content of the given file in the project.

-Never attempt to read a path that hasn't been previously mentioned.
+In sessions with ${toolNames.read} always use it instead of Read as it contains the most up-to-date contents.

-In sessions with mcp__acp__read always use it instead of Read as it contains the most up-to-date contents.`,
+Reads a file from the local filesystem. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- The file_path parameter must be an absolute path, not a relative path
+- By default, it reads up to ${defaults.linesToRead} lines starting from the beginning of the file
+- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- Any files larger than ${defaults.maxFileSize} bytes will be truncated
+- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
+- This tool can only read files, not directories. To read a directory, use an ls command via the ${toolNames.bash} tool.
+- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.`,
        inputSchema: {
-          abs_path: z.string().describe("The absolute path to the file to read."),
+          file_path: z.string().describe("The absolute path to the file to read"),
          offset: z
            .number()
            .optional()
-            .describe("Which line to start reading from. Omit to start from the beginning."),
-          limit: z.number().optional().describe("How many lines to read. Omit for the whole file."),
+            .default(1)
+            .describe(
+              "The line number to start reading from. Only provide if the file is too large to read at once",
+            ),
+          limit: z
+            .number()
+            .optional()
+            .default(defaults.linesToRead)
+            .describe(
+              `The number of lines to read. Only provide if the file is too large to read at once.`,
+            ),
        },
        annotations: {
          title: "Read file",
@@ -66,18 +100,44 @@ In sessions with mcp__acp__read always use it instead of Read as it contains the
              ],
            };
          }
-          const content = await agent.readTextFile({
+
+          const readResponse = await agent.readTextFile({
            sessionId,
-            path: input.abs_path,
-            limit: input.limit,
+            path: input.file_path,
            line: input.offset,
+            limit: input.limit,
          });

+          if (typeof readResponse?.content !== "string") {
+            throw new Error(`No file contents for ${input.file_path}.`);
+          }
+
+          // Extract lines with byte limit enforcement
+          const result = extractLinesWithByteLimit(readResponse.content, defaults.maxFileSize);
+
+          // Construct informative message about what was read
+          let readInfo = "";
+          if (input.offset > 1 || result.wasLimited) {
+            readInfo = "\n\n<file-read-info>";
+
+            if (result.wasLimited) {
+              readInfo += `Read ${result.linesRead} lines (hit 50KB limit). `;
+            } else {
+              readInfo += `Read lines ${input.offset}-${result.linesRead}. `;
+            }
+
+            if (result.wasLimited) {
+              readInfo += `Continue with offset=${result.linesRead}.`;
+            }
+
+            readInfo += "</file-read-info>";
+          }
+
          return {
            content: [
              {
                type: "text",
-                text: content.content + SYSTEM_REMINDER,
+                text: result.content + readInfo + SYSTEM_REMINDER,
              },
            ],
          };
@@ -97,16 +157,25 @@ In sessions with mcp__acp__read always use it instead of Read as it contains the

  if (clientCapabilities?.fs?.writeTextFile) {
    server.registerTool(
-      "write",
+      unqualifiedToolNames.write,
      {
-        title: "Write",
-        description: `Writes content to the specified file in the project.
+        title: unqualifiedToolNames.write,
+        description: `Writes a file to the local filesystem..

-In sessions with mcp__acp__write always use it instead of Write as it will
-allow the user to conveniently review changes.`,
+In sessions with ${toolNames.write} always use it instead of Write as it will
+allow the user to conveniently review changes.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the ${toolNames.read} tool first to read the file's contents. This tool will fail if you did not read the file first.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`,
        inputSchema: {
-          abs_path: z.string().describe("The absolute path to the file to write"),
-          content: z.string().describe("The full content to write"),
+          file_path: z
+            .string()
+            .describe("The absolute path to the file to write (must be absolute, not relative)"),
+          content: z.string().describe("The content to write to the file"),
        },
        annotations: {
          title: "Write file",
@@ -131,7 +200,7 @@ allow the user to conveniently review changes.`,
          }
          await agent.writeTextFile({
            sessionId,
-            path: input.abs_path,
+            path: input.file_path,
            content: input.content,
          });

@@ -152,28 +221,32 @@ allow the user to conveniently review changes.`,
    );

    server.registerTool(
-      "edit",
+      unqualifiedToolNames.edit,
      {
-        title: "Edit",
-        description: `Edit a file.
+        title: unqualifiedToolNames.edit,
+        description: `Performs exact string replacements in files.

-In sessions with mcp__acp__edit always use it instead of Edit as it will
+In sessions with ${toolNames.edit} always use it instead of Edit as it will
 allow the user to conveniently review changes.

-File editing instructions:
- The \`old_string\` param must match existing file content, including indentation.
- The \`old_string\` param must come from the actual file, not an outline.
- The \`old_string\` section must not be empty.
- Be minimal with replacements:
-  - For unique lines, include only those lines.
-  - For non-unique lines, include enough context to identify them.
- Do not escape quotes, newlines, or other characters.
- Only edit the specified file.
- If the \`old_string\` value isn't found in the file, the edit won't be applied. The tool will fail and must be retried.`,
+Usage:
+- You must use your \`${toolNames.read}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`.
+- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`,
        inputSchema: {
-          abs_path: z.string().describe("The absolute path to the file to read."),
-          old_string: z.string().describe("The old text to replace (must be unique in the file)"),
-          new_string: z.string().describe("The new text."),
+          file_path: z.string().describe("The absolute path to the file to modify"),
+          old_string: z.string().describe("The text to replace"),
+          new_string: z
+            .string()
+            .describe("The text to replace it with (must be different from old_string)"),
+          replace_all: z
+            .boolean()
+            .default(false)
+            .optional()
+            .describe("Replace all occurences of old_string (default false)"),
        },
        annotations: {
          title: "Edit file",
@@ -184,156 +257,98 @@ File editing instructions:
        },
      },
      async (input) => {
-        const session = agent.sessions[sessionId];
-        if (!session) {
+        try {
+          const session = agent.sessions[sessionId];
+          if (!session) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "The user has left the building",
+                },
+              ],
+            };
+          }
+
+          const readResponse = await agent.readTextFile({
+            sessionId,
+            path: input.file_path,
+          });
+
+          if (typeof readResponse?.content !== "string") {
+            throw new Error(`No file contents for ${input.file_path}.`);
+          }
+
+          const { newContent } = replaceAndCalculateLocation(readResponse.content, [
+            {
+              oldText: input.old_string,
+              newText: input.new_string,
+              replaceAll: input.replace_all,
+            },
+          ]);
+
+          const patch = diff.createPatch(input.file_path, readResponse.content, newContent);
+
+          await agent.writeTextFile({
+            sessionId,
+            path: input.file_path,
+            content: newContent,
+          });
+
          return {
            content: [
              {
                type: "text",
-                text: "The user has left the building",
+                text: patch,
              },
            ],
          };
-        }
-
-        const { content } = await agent.readTextFile({
-          sessionId,
-          path: input.abs_path,
-        });
-
-        const { newContent } = replaceAndCalculateLocation(content, [
-          {
-            oldText: input.old_string,
-            newText: input.new_string,
-            replaceAll: false,
-          },
-        ]);
-
-        const patch = diff.createPatch(input.abs_path, content, newContent);
-
-        await agent.writeTextFile({
-          sessionId,
-          path: input.abs_path,
-          content: newContent,
-        });
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: patch,
-            },
-          ],
-        };
-      },
-    );
-
-    server.registerTool(
-      "multi-edit",
-      {
-        title: "Multi Edit",
-        description: `Edit a file with multiple sequential edits.
-
-In sessions with mcp__acp__multi-edit always use it instead of MultiEdit as it will
-allow the user to conveniently review changes.
-
-File editing instructions:
- The \`old_string\` param must match existing file content, including indentation.
- The \`old_string\` param must come from the actual file, not an outline.
- The \`old_string\` section must not be empty.
- Be minimal with replacements:
-  - For unique lines, include only those lines.
-  - For non-unique lines, include enough context to identify them, unless you're using \`replace_all\`
- Do not escape quotes, newlines, or other characters.
- If any of the provided \`old_string\` values aren't found in the file, no edits will be applied. The tool will fail and must be retried.`,
-        inputSchema: {
-          file_path: z.string().describe("The absolute path to the file to modify"),
-          edits: z
-            .array(
-              z.object({
-                old_string: z.string().describe("The text to replace"),
-                new_string: z.string().describe("The text to replace it with"),
-                replace_all: z
-                  .boolean()
-                  .optional()
-                  .describe("Replace all occurrences of old_string (default false)"),
-              }),
-            )
-            .min(1)
-            .describe("Array of edit operations to perform sequentially on the file"),
-        },
-        annotations: {
-          title: "Multi Edit file",
-          readOnlyHint: false,
-          destructiveHint: false,
-          openWorldHint: false,
-          idempotentHint: false,
-        },
-      },
-      async (input) => {
-        const session = agent.sessions[sessionId];
-        if (!session) {
+        } catch (error: any) {
          return {
            content: [
              {
                type: "text",
-                text: "The user has left the building",
+                text: "Editing file failed: " + (error?.message ?? String(error)),
              },
            ],
          };
        }
-
-        const { content } = await agent.readTextFile({
-          sessionId,
-          path: input.file_path,
-        });
-
-        const { newContent } = replaceAndCalculateLocation(
-          content,
-          input.edits.map((edit) => ({
-            oldText: edit.old_string,
-            newText: edit.new_string,
-            replaceAll: edit.replace_all ?? false,
-          })),
-        );
-
-        const patch = diff.createPatch(input.file_path, content, newContent);
-
-        await agent.writeTextFile({
-          sessionId,
-          path: input.file_path,
-          content: newContent,
-        });
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: patch,
-            },
-          ],
-        };
      },
    );
  }

  if (agent.clientCapabilities?.terminal) {
    server.registerTool(
-      "Bash",
+      unqualifiedToolNames.bash,
      {
-        title: "Bash",
-        description: "Executes a bash command",
+        title: unqualifiedToolNames.bash,
+        description: `Executes a bash command
+
+In sessions with ${toolNames.bash} always use it instead of Bash`,
        inputSchema: {
-          command: z.string().describe("The bash command to execute as a one-liner"),
-          timeout_ms: z
+          command: z.string().describe("The command to execute"),
+          timeout: z
            .number()
            .default(2 * 60 * 1000)
-            .describe("Optional timeout in milliseconds"),
+            .describe(`Optional timeout in milliseconds (max ${2 * 60 * 1000})`),
+          description: z.string().optional()
+            .describe(`Clear, concise description of what this command does in 5-10 words, in active voice. Examples:
+Input: ls
+Output: List files in current directory
+
+Input: git status
+Output: Show working tree status
+
+Input: npm install
+Output: Install package dependencies
+
+Input: mkdir foo
+Output: Create directory 'foo'`),
          run_in_background: z
            .boolean()
            .default(false)
            .describe(
-              "When set to true, the command is started in the background. The tool returns an `id` that can be used with the `mcp__acp__BashOutput` tool to retrieve the current output, or the `mcp__acp__KillBash` tool to stop it early.",
+              `Set to true to run this command in the background. The tool returns an \`id\` that can be used with the \`${toolNames.bashOutput}\` tool to retrieve the current output, or the \`${toolNames.killShell}\` tool to stop it early.`,
            ),
        },
      },
@@ -362,6 +377,7 @@ File editing instructions:

        const handle = await agent.client.createTerminal({
          command: input.command,
+          env: [{ name: "CLAUDECODE", value: "1" }],
          sessionId,
          outputByteLimit: 32_000,
        });
@@ -372,6 +388,7 @@ File editing instructions:
            sessionUpdate: "tool_call_update",
            toolCallId,
            status: "in_progress",
+            title: input.description,
            content: [{ type: "terminal", terminalId: handle.id }],
          },
        });
@@ -389,7 +406,7 @@ File editing instructions:
        const statusPromise = Promise.race([
          handle.waitForExit().then((exitStatus) => ({ status: "exited" as const, exitStatus })),
          abortPromise.then(() => ({ status: "aborted" as const, exitStatus: null })),
-          sleep(input.timeout_ms).then(async () => {
+          sleep(input.timeout).then(async () => {
            if (agent.backgroundTerminals[handle.id]?.status === "started") {
              await handle.kill();
            }
@@ -454,22 +471,27 @@ File editing instructions:
    );

    server.registerTool(
-      "BashOutput",
+      unqualifiedToolNames.bashOutput,
      {
-        title: "BashOutput",
-        description:
-          "Returns the current output and exit status of a background bash command by its id. Includes only new output since last invocation.",
+        title: unqualifiedToolNames.bashOutput,
+        description: `- Retrieves output from a running or completed background bash shell
+- Takes a shell_id parameter identifying the shell
+- Always returns only new output since the last check
+- Returns stdout and stderr output along with shell status
+- Use this tool when you need to monitor or check the output of a long-running shell
+
+In sessions with ${toolNames.bashOutput} always use it instead of BashOutput.`,
        inputSchema: {
-          id: z
+          shell_id: z
            .string()
-            .describe("The id of the background bash command as returned by `mcp__acp__Bash`"),
+            .describe(`The id of the background bash command as returned by \`${toolNames.bash}\``),
        },
      },
      async (input) => {
-        const bgTerm = agent.backgroundTerminals[input.id];
+        const bgTerm = agent.backgroundTerminals[input.shell_id];

        if (!bgTerm) {
-          throw new Error(`Unknown shell ${input.id}`);
+          throw new Error(`Unknown shell ${input.shell_id}`);
        }

        if (bgTerm.status === "started") {
@@ -505,21 +527,26 @@ File editing instructions:
    );

    server.registerTool(
-      "KillBash",
+      unqualifiedToolNames.killShell,
      {
-        title: "KillBash",
-        description: "Stops a background command by its id",
+        title: unqualifiedToolNames.killShell,
+        description: `- Kills a running background bash shell by its ID
+- Takes a shell_id parameter identifying the shell to kill
+- Returns a success or failure status
+- Use this tool when you need to terminate a long-running shell
+
+In sessions with ${toolNames.killShell} always use it instead of KillShell.`,
        inputSchema: {
-          id: z
+          shell_id: z
            .string()
-            .describe("The id of the background bash command as returned by `mcp__acp__Bash`"),
+            .describe(`The id of the background bash command as returned by \`${toolNames.bash}\``),
        },
      },
      async (input) => {
-        const bgTerm = agent.backgroundTerminals[input.id];
+        const bgTerm = agent.backgroundTerminals[input.shell_id];

        if (!bgTerm) {
-          throw new Error(`Unknown shell ${input.id}`);
+          throw new Error(`Unknown shell ${input.shell_id}`);
        }

        switch (bgTerm.status) {
@@ -556,140 +583,15 @@ File editing instructions:
              content: [{ type: "text", text: "Command killed by timeout." }],
            };
          default: {
-            return unreachable(bgTerm);
+            unreachable(bgTerm);
+            throw new Error("Unexpected background terminal status");
          }
        }
      },
    );
  }

-  const alwaysAllowedTools: { [key: string]: boolean } = {};
-  server.registerTool(
-    "permission",
-    {
-      title: "Permission Tool",
-      description: "Used to request tool permissions",
-      inputSchema: {
-        tool_name: z.string(),
-        input: z.any(),
-        tool_use_id: z.string().optional(),
-      },
-    },
-    async (input) => {
-      const session = agent.sessions[sessionId];
-      if (!session) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                behavior: "deny",
-                message: "Session not found",
-              }),
-            },
-          ],
-        };
-      }
-      if (alwaysAllowedTools[input.tool_name]) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                behavior: "allow",
-                updatedInput: input.input,
-              }),
-            },
-          ],
-        };
-      }
-      const response = await agent.client.requestPermission({
-        options: [
-          {
-            kind: "allow_always",
-            name: "Always Allow",
-            optionId: "allow_always",
-          },
-          { kind: "allow_once", name: "Allow", optionId: "allow" },
-          { kind: "reject_once", name: "Reject", optionId: "reject" },
-        ],
-        sessionId,
-        toolCall: {
-          toolCallId: input.tool_use_id!,
-          rawInput: input.input,
-        },
-      });
-      if (
-        response.outcome?.outcome === "selected" &&
-        (response.outcome.optionId === "allow" || response.outcome.optionId === "allow_always")
-      ) {
-        if (response.outcome.optionId === "allow_always") {
-          alwaysAllowedTools[input.tool_name] = true;
-        }
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                behavior: "allow",
-                updatedInput: input.input,
-              }),
-            },
-          ],
-        };
-      } else {
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                behavior: "deny",
-                message: "User refused permission to run tool",
-              }),
-            },
-          ],
-        };
-      }
-    },
-  );
-
-  const app = express();
-  app.use(express.json());
-
-  app.post("/mcp", async (req, res) => {
-    try {
-      const transport: StreamableHTTPServerTransport = new StreamableHTTPServerTransport({
-        sessionIdGenerator: undefined,
-      });
-      res.on("close", () => {
-        transport.close();
-        server.close();
-      });
-      await server.connect(transport);
-      await transport.handleRequest(req, res, req.body);
-    } catch (error) {
-      if (!res.headersSent) {
-        res.status(500).json({
-          jsonrpc: "2.0",
-          error: {
-            code: -32603,
-            message: `Internal server error: ${error}`,
-          },
-          id: null,
-        });
-      }
-    }
-  });
-
-  return new Promise((resolve, reject) => {
-    const listener = app.listen(0, "127.0.0.1", (error) => {
-      if (error) {
-        reject(error);
-        return;
-      }
-      resolve(listener);
-    });
-  });
+  return server;
 }

 function stripCommonPrefix(a: string, b: string): string {
--- a/src/tests/acp-agent.test.ts
+++ b/src/tests/acp-agent.test.ts
@@ -2,8 +2,11 @@ import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import { spawn, spawnSync } from "child_process";
 import {
  Agent,
+  AgentSideConnection,
+  AvailableCommand,
  Client,
  ClientSideConnection,
+  ndJsonStream,
  NewSessionResponse,
  ReadTextFileRequest,
  ReadTextFileResponse,
@@ -12,11 +15,11 @@ import {
  SessionNotification,
  WriteTextFileRequest,
  WriteTextFileResponse,
-} from "@zed-industries/agent-client-protocol";
+} from "@agentclientprotocol/sdk";
 import { nodeToWebWritable, nodeToWebReadable } from "../utils.js";
 import { markdownEscape, toolInfoFromToolUse, toolUpdateFromToolResult } from "../tools.js";
-import { toAcpNotifications } from "../acp-agent.js";
-import { SDKAssistantMessage } from "@anthropic-ai/claude-code";
+import { toAcpNotifications, promptToClaude } from "../acp-agent.js";
+import { query, SDKAssistantMessage } from "@anthropic-ai/claude-agent-sdk";

 describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration", () => {
  let child: ReturnType<typeof spawn>;
@@ -47,9 +50,15 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
    agent: Agent;
    files: Map<string, string> = new Map();
    receivedText: string = "";
+    resolveAvailableCommands: (commands: AvailableCommand[]) => void;
+    availableCommandsPromise: Promise<AvailableCommand[]>;

    constructor(agent: Agent) {
      this.agent = agent;
+      this.resolveAvailableCommands = () => {};
+      this.availableCommandsPromise = new Promise((resolve) => {
+        this.resolveAvailableCommands = resolve;
+      });
    }

    takeReceivedText() {
@@ -67,17 +76,24 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
    async sessionUpdate(params: SessionNotification): Promise<void> {
      console.error("RECEIVED", JSON.stringify(params, null, 4));

-      if (
-        params.update.sessionUpdate === "agent_message_chunk" &&
-        params.update.content.type === "text"
-      ) {
-        this.receivedText += params.update.content.text;
+      switch (params.update.sessionUpdate) {
+        case "agent_message_chunk": {
+          if (params.update.content.type === "text") {
+            this.receivedText += params.update.content.text;
+          }
+          break;
+        }
+        case "available_commands_update":
+          this.resolveAvailableCommands(params.update.availableCommands);
+          break;
+        default:
+          break;
      }
    }

    async writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse> {
      this.files.set(params.path, params.content);
-      return null;
+      return {};
    }

    async readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
@@ -94,14 +110,13 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
    newSessionResponse: NewSessionResponse;
  }> {
    let client;
-    const connection = new ClientSideConnection(
-      (agent) => {
-        client = new TestClient(agent);
-        return client;
-      },
-      nodeToWebWritable(child.stdin!),
-      nodeToWebReadable(child.stdout!),
-    );
+    const input = nodeToWebWritable(child.stdin!);
+    const output = nodeToWebReadable(child.stdout!);
+    const stream = ndJsonStream(input, output);
+    const connection = new ClientSideConnection((agent) => {
+      client = new TestClient(agent);
+      return client;
+    }, stream);

    await connection.initialize({
      protocolVersion: 1,
@@ -140,12 +155,14 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
  it("should include available commands", async () => {
    const { client, connection, newSessionResponse } = await setupTestSession(__dirname);

-    expect(newSessionResponse.availableCommands).toContainEqual({
+    const commands = await client.availableCommandsPromise;
+
+    expect(commands).toContainEqual({
      name: "quick-math",
      description: "10 * 3 = 30 (project)",
      input: null,
    });
-    expect(newSessionResponse.availableCommands).toContainEqual({
+    expect(commands).toContainEqual({
      name: "say-hello",
      description: "Say hello (project)",
      input: { hint: "[name]" },
@@ -175,6 +192,50 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"

    expect(client.takeReceivedText()).toContain("Hello GPT-5");
  }, 30000);
+
+  it("/compact works", async () => {
+    const { client, connection, newSessionResponse } = await setupTestSession(__dirname);
+
+    const commands = await client.availableCommandsPromise;
+
+    expect(commands).toContainEqual({
+      description:
+        "Clear conversation history but keep a summary in context. Optional: /compact [instructions for summarization]",
+      input: {
+        hint: "<optional custom summarization instructions>",
+      },
+      name: "compact",
+    });
+
+    // Error case (no previous message)
+    await connection.prompt({
+      prompt: [{ type: "text", text: "/compact" }],
+      sessionId: newSessionResponse.sessionId,
+    });
+
+    expect(client.takeReceivedText()).toBe("");
+
+    // Send something
+    await connection.prompt({
+      prompt: [{ type: "text", text: "Hi" }],
+      sessionId: newSessionResponse.sessionId,
+    });
+    // Clear response
+    client.takeReceivedText();
+
+    // Test with instruction
+    await connection.prompt({
+      prompt: [
+        {
+          type: "text",
+          text: "/compact greeting",
+        },
+      ],
+      sessionId: newSessionResponse.sessionId,
+    });
+
+    expect(client.takeReceivedText()).toContain("");
+  }, 30000);
 });

 describe("tool conversions", () => {
@@ -311,13 +372,13 @@ describe("tool conversions", () => {
    });
  });

-  it("should handle mcp__acp__write tool calls", () => {
+  it("should handle mcp__acp__Write tool calls", () => {
    const tool_use = {
      type: "tool_use",
      id: "toolu_01GHI789JKL456",
-      name: "mcp__acp__write",
+      name: "mcp__acp__Write",
      input: {
-        abs_path: "/Users/test/project/config.json",
+        file_path: "/Users/test/project/config.json",
        content: '{"version": "1.0.0"}',
      },
    };
@@ -355,13 +416,13 @@ describe("tool conversions", () => {
    });
  });

-  it("should handle mcp__acp__read tool calls", () => {
+  it("should handle mcp__acp__Read tool calls", () => {
    const tool_use = {
      type: "tool_use",
      id: "toolu_01YZA789BCD123",
-      name: "mcp__acp__read",
+      name: "mcp__acp__Read",
      input: {
-        abs_path: "/Users/test/project/data.json",
+        file_path: "/Users/test/project/data.json",
      },
    };

@@ -373,13 +434,13 @@ describe("tool conversions", () => {
    });
  });

-  it("should handle mcp__acp__read with limit", () => {
+  it("should handle mcp__acp__Read with limit", () => {
    const tool_use = {
      type: "tool_use",
      id: "toolu_01EFG456HIJ789",
-      name: "mcp__acp__read",
+      name: "mcp__acp__Read",
      input: {
-        abs_path: "/Users/test/project/large.txt",
+        file_path: "/Users/test/project/large.txt",
        limit: 100,
      },
    };
@@ -392,13 +453,13 @@ describe("tool conversions", () => {
    });
  });

-  it("should handle mcp__acp__read with offset and limit", () => {
+  it("should handle mcp__acp__Read with offset and limit", () => {
    const tool_use = {
      type: "tool_use",
      id: "toolu_01KLM789NOP456",
-      name: "mcp__acp__read",
+      name: "mcp__acp__Read",
      input: {
-        abs_path: "/Users/test/project/large.txt",
+        file_path: "/Users/test/project/large.txt",
        offset: 50,
        limit: 100,
      },
@@ -412,13 +473,13 @@ describe("tool conversions", () => {
    });
  });

-  it("should handle mcp__acp__read with only offset", () => {
+  it("should handle mcp__acp__Read with only offset", () => {
    const tool_use = {
      type: "tool_use",
      id: "toolu_01QRS123TUV789",
-      name: "mcp__acp__read",
+      name: "mcp__acp__Read",
      input: {
-        abs_path: "/Users/test/project/large.txt",
+        file_path: "/Users/test/project/large.txt",
        offset: 200,
      },
    };
@@ -479,7 +540,7 @@ describe("tool conversions", () => {
    const tool_use = {
      type: "tool_use",
      id: "toolu_01PhLms5fuvmdjy2bb6dfUKT",
-      name: "KillBash",
+      name: "KillShell",
      input: {
        shell_id: "bash_1",
      },
@@ -516,6 +577,7 @@ describe("tool conversions", () => {
        id: "msg_017eNosJgww7F5qD4a8BcAcx",
        type: "message",
        role: "assistant",
+        container: null,
        model: "claude-sonnet-4-20250514",
        content: [
          {
@@ -580,13 +642,25 @@ describe("tool conversions", () => {
          },
          output_tokens: 1,
          service_tier: "standard",
+          server_tool_use: null,
        },
+        context_management: null,
      },
      parent_tool_use_id: null,
      session_id: "d056596f-e328-41e9-badd-b07122ae5227",
      uuid: "b7c3330c-de8f-4bba-ac53-68c7f76ffeb5",
    };
-    expect(toAcpNotifications(received, "test", {}, {})).toStrictEqual([
+    expect(
+      toAcpNotifications(
+        received.message.content,
+        received.message.role,
+        "test",
+        {},
+        {},
+        {} as AgentSideConnection,
+        console,
+      ),
+    ).toStrictEqual([
      {
        sessionId: "test",
        update: {
@@ -638,78 +712,13 @@ describe("tool conversions", () => {
    ]);
  });

-  it("should show full diff for multi edit tool", () => {
-    const toolUse = {
-      type: "tool_use",
-      id: "toolu_01DEF456",
-      name: "mcp__acp__multi-edit",
-      input: {
-        file_path: "/Users/test/project/config.json",
-        edits: [
-          {
-            old_string: 'version": 1',
-            new_string: 'version": 2',
-            replace_all: false,
-          },
-          {
-            old_string: 'enabled": false',
-            new_string: 'enabled": true',
-            replace_all: true,
-          },
-        ],
-      },
-    };
-    const fileCache: { [key: string]: string } = {
-      "/Users/test/project/config.json": JSON.stringify(
-        {
-          version: 1,
-          filler: "filler",
-          enabled: false,
-        },
-        null,
-        4,
-      ),
-    };
-
-    expect(toolInfoFromToolUse(toolUse, fileCache)).toEqual({
-      content: [
-        {
-          newText: `{
-    "version": 2,
-    "filler": "filler",
-    "enabled": true
-}`,
-          oldText: `{
-    "version": 1,
-    "filler": "filler",
-    "enabled": false
-}`,
-          path: "/Users/test/project/config.json",
-          type: "diff",
-        },
-      ],
-      kind: "edit",
-      locations: [
-        {
-          path: "/Users/test/project/config.json",
-          line: 1,
-        },
-        {
-          path: "/Users/test/project/config.json",
-          line: 3,
-        },
-      ],
-      title: "Edit /Users/test/project/config.json",
-    });
-  });
-
  it("should return empty update for successful edit result", () => {
    const toolUse = {
      type: "tool_use",
      id: "toolu_01MNO345",
-      name: "mcp__acp__edit",
+      name: "mcp__acp__Edit",
      input: {
-        abs_path: "/Users/test/project/test.txt",
+        file_path: "/Users/test/project/test.txt",
        old_string: "old",
        new_string: "new",
      },
@@ -718,7 +727,7 @@ describe("tool conversions", () => {
    const toolResult = {
      content: [
        {
-          type: "text",
+          type: "text" as const,
          text: "not valid json",
        },
      ],
@@ -737,9 +746,9 @@ describe("tool conversions", () => {
    const toolUse = {
      type: "tool_use",
      id: "toolu_01MNO345",
-      name: "mcp__acp__edit",
+      name: "mcp__acp__Edit",
      input: {
-        abs_path: "/Users/test/project/test.txt",
+        file_path: "/Users/test/project/test.txt",
        old_string: "old",
        new_string: "new",
      },
@@ -748,7 +757,7 @@ describe("tool conversions", () => {
    const toolResult = {
      content: [
        {
-          type: "text",
+          type: "text" as const,
          text: "Failed to find `old_string`",
        },
      ],
@@ -762,7 +771,10 @@ describe("tool conversions", () => {
    // Should return empty object when parsing fails
    expect(update).toEqual({
      content: [
-        { content: { type: "text", text: "Failed to find `old_string`" }, type: "content" },
+        {
+          content: { type: "text", text: "```\nFailed to find `old_string`\n```" },
+          type: "content",
+        },
      ],
    });
  });
@@ -779,3 +791,111 @@ describe("escape markdown", () => {
    expect(escaped).toEqual("````\nfor example:\n```markdown\nHello *world*!\n```\n````");
  });
 });
+
+describe("prompt conversion", () => {
+  it("should not change built-in slash commands", () => {
+    const message = promptToClaude({
+      sessionId: "test",
+      prompt: [
+        {
+          type: "text",
+          text: "/compact args",
+        },
+      ],
+    });
+    expect(message.message.content).toEqual([
+      {
+        text: "/compact args",
+        type: "text",
+      },
+    ]);
+  });
+
+  it("should remove MCP prefix from MCP slash commands", () => {
+    const message = promptToClaude({
+      sessionId: "test",
+      prompt: [
+        {
+          type: "text",
+          text: "/mcp:server:name args",
+        },
+      ],
+    });
+    expect(message.message.content).toEqual([
+      {
+        text: "/server:name (MCP) args",
+        type: "text",
+      },
+    ]);
+  });
+});
+
+describe("SDK behavior", () => {
+  it.skipIf(!process.env.RUN_INTEGRATION_TESTS)(
+    "query has a 'default' model",
+    async () => {
+      const q = query({ prompt: "hi" });
+      const models = await q.supportedModels();
+      const defaultModel = models.find((m) => m.value === "default");
+      expect(defaultModel).toBeDefined();
+    },
+    10000,
+  );
+});
+
+describe("permission requests", () => {
+  it("should include title field in tool permission request structure", () => {
+    // Test various tool types to ensure title is correctly generated
+    const testCases = [
+      {
+        toolUse: {
+          type: "tool_use" as const,
+          id: "test-1",
+          name: "Write",
+          input: { file_path: "/test/file.txt", content: "test" },
+        },
+        expectedTitlePart: "/test/file.txt",
+      },
+      {
+        toolUse: {
+          type: "tool_use" as const,
+          id: "test-2",
+          name: "Bash",
+          input: { command: "ls -la", description: "List files" },
+        },
+        expectedTitlePart: "`ls -la`",
+      },
+      {
+        toolUse: {
+          type: "tool_use" as const,
+          id: "test-3",
+          name: "mcp__acp__Read",
+          input: { file_path: "/test/data.json" },
+        },
+        expectedTitlePart: "/test/data.json",
+      },
+    ];
+
+    for (const testCase of testCases) {
+      // Get the tool info that would be used in requestPermission
+      const toolInfo = toolInfoFromToolUse(testCase.toolUse, {});
+
+      // Verify toolInfo has a title
+      expect(toolInfo.title).toBeDefined();
+      expect(toolInfo.title).toContain(testCase.expectedTitlePart);
+
+      // Verify the structure that our fix creates for requestPermission
+      const requestStructure = {
+        toolCall: {
+          toolCallId: testCase.toolUse.id,
+          rawInput: testCase.toolUse.input,
+          title: toolInfo.title, // This is what commit 1785d86 adds
+        },
+      };
+
+      // Ensure the title field is present and populated
+      expect(requestStructure.toolCall.title).toBeDefined();
+      expect(requestStructure.toolCall.title).toContain(testCase.expectedTitlePart);
+    }
+  });
+});
--- a/src/tests/extract-lines.test.ts
+++ b/src/tests/extract-lines.test.ts
@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest";
+import { extractLinesWithByteLimit } from "../utils.js";
+
+describe("extractLinesWithByteLimit", () => {
+  const simpleContent = "Line 1\nLine 2\nLine 3\nLine 4\nLine 5";
+
+  it("should extract all lines when under byte limit", () => {
+    const result = extractLinesWithByteLimit(simpleContent, 1000);
+
+    expect(result.content).toBe(simpleContent);
+    expect(result.wasLimited).toBe(false);
+    expect(result.linesRead).toBe(5);
+  });
+
+  it("should limit output when exceeding byte limit", () => {
+    // Create content that will exceed byte limit
+    const longLine = "x".repeat(100);
+    const manyLines = Array(10).fill(longLine).join("\n");
+
+    const result = extractLinesWithByteLimit(manyLines, 250);
+
+    expect(result.wasLimited).toBe(true);
+    expect(result.linesRead).toBe(2);
+  });
+
+  it("should handle empty content", () => {
+    const result = extractLinesWithByteLimit("", 1000);
+
+    expect(result.content).toBe("");
+    expect(result.wasLimited).toBe(false);
+    expect(result.linesRead).toBe(1); // We read the one empty line
+  });
+
+  it("should handle single line file", () => {
+    const singleLine = "This is a single line without newline";
+    const result = extractLinesWithByteLimit(singleLine, 1000);
+
+    expect(result.content).toBe(singleLine);
+    expect(result.wasLimited).toBe(false);
+    expect(result.linesRead).toBe(1);
+  });
+
+  it("should correctly count bytes with multi-byte characters", () => {
+    const unicodeContent = "Hello 世界\n你好 World\nEmoji: 🌍\nNormal line";
+    const result = extractLinesWithByteLimit(unicodeContent, 1000);
+
+    expect(result.content).toBe(unicodeContent);
+    expect(result.linesRead).toBe(4);
+  });
+
+  it("should stop at byte limit even with one more line available", () => {
+    // Create lines where adding one more would exceed limit
+    const line1 = "a".repeat(40);
+    const line2 = "b".repeat(40);
+    const line3 = "c".repeat(40);
+    const content = `${line1}\n${line2}\n${line3}`;
+
+    const result = extractLinesWithByteLimit(content, 85);
+
+    expect(result.content).toBe(`${line1}\n${line2}\n`);
+    expect(result.wasLimited).toBe(true);
+    expect(result.linesRead).toBe(2);
+  });
+
+  it("should read exactly to limit when possible", () => {
+    const exactContent = "12345\n67890\n12345"; // 17 bytes total
+    const result = extractLinesWithByteLimit(exactContent, 17);
+
+    expect(result.content).toBe(exactContent);
+    expect(result.wasLimited).toBe(false);
+    expect(result.linesRead).toBe(3);
+  });
+
+  it("should handle Windows-style line endings", () => {
+    const windowsContent = "Line 1\r\nLine 2\r\nLine 3";
+    const result = extractLinesWithByteLimit(windowsContent, 1000);
+
+    // Note: split("\n") will keep the \r characters
+    expect(result.content).toBe("Line 1\r\nLine 2\r\nLine 3");
+    expect(result.linesRead).toBe(3);
+  });
+
+  it("should handle very large files efficiently", () => {
+    // Create a 100KB file
+    const largeLine = "x".repeat(1000);
+    const largeContent = Array(110).fill(largeLine).join("\n");
+
+    const result = extractLinesWithByteLimit(largeContent, 50000);
+
+    expect(result.wasLimited).toBe(true);
+  });
+
+  it("should allow at least one line even if it exceeds byte limit", () => {
+    const veryLongLine = "x".repeat(100000); // 100KB line
+    const result = extractLinesWithByteLimit(veryLongLine, 50000);
+
+    // Should return the line even though it exceeds the byte limit
+    // because we always allow at least one line if no lines have been added yet
+    expect(result.content).toBe(veryLongLine);
+    expect(result.linesRead).toBe(1);
+    expect(result.wasLimited).toBe(false);
+  });
+});
--- a/src/tests/mcp-server-read.test.ts
+++ b/src/tests/mcp-server-read.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMcpServer } from "../mcp-server.js";
+
+const SESSION_ID = "session-id";
+
+function getTool(server: any, name: string) {
+  const tools = server?._registeredTools;
+  if (!tools || !tools[name]) {
+    throw new Error(`Tool ${name} not registered`);
+  }
+  return tools[name];
+}
+
+function createAgent(overrides: Record<string, unknown> = {}) {
+  return {
+    sessions: {
+      [SESSION_ID]: {},
+    },
+    readTextFile: vi.fn(),
+    writeTextFile: vi.fn(),
+    backgroundTerminals: {},
+    clientCapabilities: {},
+    client: {
+      sessionUpdate: vi.fn(),
+      createTerminal: vi.fn(),
+      requestPermission: vi.fn(),
+    },
+    ...overrides,
+  };
+}
+
+describe("MCP server read-related tools", () => {
+  it("reports missing file contents instead of crashing the read tool", async () => {
+    const agent = createAgent();
+    agent.readTextFile.mockResolvedValue({});
+
+    const server = createMcpServer(agent as any, SESSION_ID, {
+      fs: { readTextFile: true },
+    });
+
+    const readTool = getTool(server, "Read");
+
+    const result = await readTool.callback({
+      file_path: "/tmp/file.txt",
+      offset: 1,
+      limit: 2000,
+    });
+
+    expect(result.content[0].text).toBe("Reading file failed: No file contents for /tmp/file.txt.");
+  });
+
+  it("reports missing contents inside the edit tool and skips writes", async () => {
+    const agent = createAgent();
+    agent.readTextFile.mockResolvedValue({});
+
+    const server = createMcpServer(agent as any, SESSION_ID, {
+      fs: { readTextFile: true, writeTextFile: true },
+    });
+
+    const editTool = getTool(server, "Edit");
+
+    const result = await editTool.callback({
+      file_path: "/tmp/file.txt",
+      old_string: "foo",
+      new_string: "bar",
+      replace_all: false,
+    });
+
+    expect(result.content[0].text).toBe("Editing file failed: No file contents for /tmp/file.txt.");
+    expect(agent.writeTextFile).not.toHaveBeenCalled();
+  });
+});
--- a/src/tools.ts
+++ b/src/tools.ts
@@ -1,10 +1,17 @@
+import { PlanEntry, ToolCallContent, ToolCallLocation, ToolKind } from "@agentclientprotocol/sdk";
+import { replaceAndCalculateLocation, SYSTEM_REMINDER, toolNames } from "./mcp-server.js";
+import { ToolResultBlockParam, WebSearchToolResultBlockParam } from "@anthropic-ai/sdk/resources";
 import {
-  PlanEntry,
-  ToolCallContent,
-  ToolCallLocation,
-  ToolKind,
-} from "@zed-industries/agent-client-protocol";
-import { replaceAndCalculateLocation, SYSTEM_REMINDER } from "./mcp-server.js";
+  BetaBashCodeExecutionToolResultBlockParam,
+  BetaCodeExecutionToolResultBlockParam,
+  BetaRequestMCPToolResultBlockParam,
+  BetaTextEditorCodeExecutionToolResultBlockParam,
+  BetaToolSearchToolResultBlockParam,
+  BetaWebFetchToolResultBlockParam,
+  BetaWebSearchToolResultBlockParam,
+} from "@anthropic-ai/sdk/resources/beta.mjs";
+import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { Logger } from "./acp-agent.js";

 interface ToolInfo {
  title: string;
@@ -22,6 +29,7 @@ interface ToolUpdate {
 export function toolInfoFromToolUse(
  toolUse: any,
  cachedFileContent: { [key: string]: string },
+  logger: Logger = console,
 ): ToolInfo {
  const name = toolUse.name;
  const input = toolUse.input;
@@ -67,7 +75,7 @@ export function toolInfoFromToolUse(
      };

    case "Bash":
-    case "mcp__acp__Bash":
+    case toolNames.bash:
      return {
        title: input?.command ? "`" + input.command.replaceAll("`", "\\`") + "`" : "Terminal",
        kind: "execute",
@@ -83,22 +91,22 @@ export function toolInfoFromToolUse(
      };

    case "BashOutput":
-    case "mcp__acp__BashOutput":
+    case toolNames.bashOutput:
      return {
        title: "Tail Logs",
        kind: "execute",
        content: [],
      };

-    case "KillBash":
-    case "mcp__acp__KillBash":
+    case "KillShell":
+    case toolNames.killShell:
      return {
        title: "Kill Process",
        kind: "execute",
        content: [],
      };

-    case "mcp__acp__read": {
+    case toolNames.read: {
      let limit = "";
      if (input.limit) {
        limit =
@@ -107,14 +115,16 @@ export function toolInfoFromToolUse(
        limit = " (from line " + (input.offset + 1) + ")";
      }
      return {
-        title: "Read " + (input.abs_path ?? "File") + limit,
+        title: "Read " + (input.file_path ?? "File") + limit,
        kind: "read",
-        locations: [
-          {
-            path: input.abs_path,
-            line: input.offset ?? 0,
-          },
-        ],
+        locations: input.file_path
+          ? [
+              {
+                path: input.file_path,
+                line: input.offset ?? 0,
+              },
+            ]
+          : [],
        content: [],
      };
    }
@@ -124,7 +134,14 @@ export function toolInfoFromToolUse(
        title: "Read File",
        kind: "read",
        content: [],
-        locations: [{ path: input.file_path, line: input.offset ?? 0 }],
+        locations: input.file_path
+          ? [
+              {
+                path: input.file_path,
+                line: input.offset ?? 0,
+              },
+            ]
+          : [],
      };

    case "LS":
@@ -135,9 +152,9 @@ export function toolInfoFromToolUse(
        locations: [],
      };

-    case "mcp__acp__edit":
+    case toolNames.edit:
    case "Edit": {
-      const path = input?.abs_path ?? input?.file_path;
+      const path = input?.file_path ?? input?.file_path;
      let oldText = input.old_string ?? null;
      let newText = input.new_string ?? "";
      let affectedLines: number[] = [];
@@ -156,7 +173,7 @@ export function toolInfoFromToolUse(
          newText = newContent.newContent;
          affectedLines = newContent.lineNumbers;
        } catch (e) {
-          console.error(e);
+          logger.error(e);
        }
      }
      return {
@@ -181,66 +198,13 @@ export function toolInfoFromToolUse(
      };
    }

-    case "mcp__acp__multi-edit":
-    case "MultiEdit": {
-      const multiInput = input as {
-        file_path: string;
-        edits: {
-          old_string: string;
-          new_string: string;
-          replace_all?: boolean;
-        }[];
-      };
-      let oldTextMulti = multiInput.edits.map((edit: any) => edit.old_string).join("\n");
-      let newTextMulti = multiInput.edits.map((edit: any) => edit.new_string).join("\n");
-      let affectedLines: number[] = [];
-      try {
-        if (multiInput.edits && multiInput.file_path) {
-          const oldContent =
-            cachedFileContent[multiInput.file_path] ||
-            multiInput.edits.map((edit: any) => edit.oldText).join("\n");
-          const newContent = replaceAndCalculateLocation(
-            oldContent,
-            multiInput.edits.map((edit) => ({
-              oldText: edit.old_string,
-              newText: edit.new_string,
-              replaceAll: edit.replace_all,
-            })),
-          );
-          oldTextMulti = oldContent;
-          newTextMulti = newContent.newContent;
-          affectedLines = newContent.lineNumbers;
-        }
-      } catch (e) {
-        console.error(e);
-      }
-      // Display it as a normal edit, because end users don't care about
-      // the distinction between edits and multi-edits.
-      return {
-        title: input?.file_path ? `Edit ${input.file_path}` : "Edit",
-        kind: "edit",
-        content: [
-          {
-            type: "diff" as const,
-            path: input.file_path,
-            oldText: oldTextMulti,
-            newText: newTextMulti,
-          },
-        ],
-        locations: input?.file_path
-          ? affectedLines.length > 0
-            ? affectedLines.map((line) => ({ line, path: input.file_path }))
-            : [{ path: input.file_path }]
-          : [],
-      };
-    }
-    case "mcp__acp__write": {
+    case toolNames.write: {
      let content: ToolCallContent[] = [];
-      if (input && input.abs_path) {
+      if (input && input.file_path) {
        content = [
          {
            type: "diff",
-            path: input.abs_path,
+            path: input.file_path,
            oldText: null,
            newText: input.content,
          },
@@ -254,10 +218,10 @@ export function toolInfoFromToolUse(
        ];
      }
      return {
-        title: input?.abs_path ? `Write ${input.abs_path}` : "Write",
+        title: input?.file_path ? `Write ${input.file_path}` : "Write",
        kind: "edit",
        content,
-        locations: input?.abs_path ? [{ path: input.abs_path }] : [],
+        locations: input?.file_path ? [{ path: input.file_path }] : [],
      };
    }

@@ -393,24 +357,30 @@ export function toolInfoFromToolUse(

    case "TodoWrite":
      return {
-        title: input?.todos
+        title: Array.isArray(input?.todos)
          ? `Update TODOs: ${input.todos.map((todo: any) => todo.content).join(", ")}`
          : "Update TODOs",
        kind: "think",
        content: [],
      };

-    case "exit_plan_mode":
+    case "ExitPlanMode":
      return {
-        title: "Exit Plan Mode",
-        kind: "think",
+        title: "Ready to code?",
+        kind: "switch_mode",
        content:
          input && input.plan
            ? [{ type: "content", content: { type: "text", text: input.plan } }]
            : [],
      };

-    case "Other":
+    case "Other": {
+      let output;
+      try {
+        output = JSON.stringify(input, null, 2);
+      } catch {
+        output = typeof input === "string" ? input : "{}";
+      }
      return {
        title: name || "Unknown Tool",
        kind: "other",
@@ -419,11 +389,12 @@ export function toolInfoFromToolUse(
            type: "content",
            content: {
              type: "text",
-              text: `\`\`\`json\n${JSON.stringify(input, null, 2) || "{}"}\`\`\``,
+              text: `\`\`\`json\n${output}\`\`\``,
            },
          },
        ],
      };
+    }

    default:
      return {
@@ -434,20 +405,22 @@ export function toolInfoFromToolUse(
  }
 }

-type ToolResult = {
-  type: "tool_result";
-  content: any;
-  tool_use_id: string;
-  is_error: boolean;
-};
-
 export function toolUpdateFromToolResult(
-  toolResult: ToolResult,
+  toolResult:
+    | ToolResultBlockParam
+    | BetaWebSearchToolResultBlockParam
+    | BetaWebFetchToolResultBlockParam
+    | WebSearchToolResultBlockParam
+    | BetaCodeExecutionToolResultBlockParam
+    | BetaBashCodeExecutionToolResultBlockParam
+    | BetaTextEditorCodeExecutionToolResultBlockParam
+    | BetaRequestMCPToolResultBlockParam
+    | BetaToolSearchToolResultBlockParam,
  toolUse: any | undefined,
 ): ToolUpdate {
  switch (toolUse?.name) {
    case "Read":
-    case "mcp__acp__read":
+    case toolNames.read:
      if (Array.isArray(toolResult.content) && toolResult.content.length > 0) {
        return {
          content: toolResult.content.map((content: any) => ({
@@ -476,22 +449,28 @@ export function toolUpdateFromToolResult(
      }
      return {};

-    case "mcp__acp__Bash":
-    case "mcp__acp__edit":
+    case toolNames.bash:
    case "edit":
    case "Edit":
-    case "mcp__acp__multi-edit":
-    case "multi-edit":
-    case "MultiEdit":
-    case "mcp__acp__write":
+    case toolNames.edit:
+    case toolNames.write:
    case "Write": {
-      if (toolResult.is_error && toolResult.content?.length > 0) {
+      if (
+        "is_error" in toolResult &&
+        toolResult.is_error &&
+        toolResult.content &&
+        toolResult.content.length > 0
+      ) {
        // Only return errors
-        return toAcpContentUpdate(toolResult.content);
+        return toAcpContentUpdate(toolResult.content, true);
      }
      return {};
    }

+    case "ExitPlanMode": {
+      return { title: "Exited Plan Mode" };
+    }
+
    case "Task":
    case "NotebookEdit":
    case "NotebookRead":
@@ -507,17 +486,29 @@ export function toolUpdateFromToolResult(
    case "WebSearch":
    case "Other":
    default: {
-      return toAcpContentUpdate(toolResult.content);
+      return toAcpContentUpdate(
+        toolResult.content,
+        "is_error" in toolResult ? toolResult.is_error : false,
+      );
    }
  }
 }

-function toAcpContentUpdate(content: any): { content?: ToolCallContent[] } {
+function toAcpContentUpdate(
+  content: any,
+  isError: boolean = false,
+): { content?: ToolCallContent[] } {
  if (Array.isArray(content) && content.length > 0) {
    return {
      content: content.map((content: any) => ({
        type: "content",
-        content,
+        content:
+          isError && content.type === "text"
+            ? {
+                ...content,
+                text: `\`\`\`\n${content.text}\n\`\`\``,
+              }
+            : content,
      })),
    };
  } else if (typeof content === "string" && content.length > 0) {
@@ -527,7 +518,7 @@ function toAcpContentUpdate(content: any): { content?: ToolCallContent[] } {
          type: "content",
          content: {
            type: "text",
-            text: content,
+            text: isError ? `\`\`\`\n${content}\n\`\`\`` : content,
          },
        },
      ],
@@ -536,7 +527,7 @@ function toAcpContentUpdate(content: any): { content?: ToolCallContent[] } {
  return {};
 }

-type ClaudePlanEntry = {
+export type ClaudePlanEntry = {
  content: string;
  status: "pending" | "in_progress" | "completed";
  activeForm: string;
@@ -559,3 +550,49 @@ export function markdownEscape(text: string): string {
  }
  return escape + "\n" + text + (text.endsWith("\n") ? "" : "\n") + escape;
 }
+
+/* A global variable to store callbacks that should be executed when receiving hooks from Claude Code */
+const toolUseCallbacks: {
+  [toolUseId: string]: {
+    onPostToolUseHook?: (
+      toolUseID: string,
+      toolInput: unknown,
+      toolResponse: unknown,
+    ) => Promise<void>;
+  };
+} = {};
+
+/* Setup callbacks that will be called when receiving hooks from Claude Code */
+export const registerHookCallback = (
+  toolUseID: string,
+  {
+    onPostToolUseHook,
+  }: {
+    onPostToolUseHook?: (
+      toolUseID: string,
+      toolInput: unknown,
+      toolResponse: unknown,
+    ) => Promise<void>;
+  },
+) => {
+  toolUseCallbacks[toolUseID] = {
+    onPostToolUseHook,
+  };
+};
+
+/* A callback for Claude Code that is called when receiving a PostToolUse hook */
+export const createPostToolUseHook =
+  (logger: Logger = console): 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];
+      }
+    }
+    return { continue: true };
+  };
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -2,6 +2,9 @@

 import { Readable, Writable } from "node:stream";
 import { WritableStream, ReadableStream } from "node:stream/web";
+import { readFileSync } from "node:fs";
+import { platform } from "node:os";
+import { Logger } from "./acp-agent.js";

 // Useful for bridging push-based and async-iterator-based code.
 export class Pushable<T> implements AsyncIterable<T> {
@@ -73,10 +76,120 @@ export function nodeToWebReadable(nodeStream: Readable): ReadableStream<Uint8Arr
  });
 }

-export function unreachable(value: never): never {
-  throw new Error(`Unexpected case: ${value}`);
+export function unreachable(value: never, logger: Logger = console) {
+  let valueAsString;
+  try {
+    valueAsString = JSON.stringify(value);
+  } catch {
+    valueAsString = value;
+  }
+  logger.error(`Unexpected case: ${valueAsString}`);
 }

 export function sleep(time: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, time));
 }
+
+interface ManagedSettings {
+  permissions?: {
+    allow?: string[];
+    deny?: string[];
+  };
+  env?: Record<string, string>;
+}
+
+// Following the rules in https://docs.anthropic.com/en/docs/claude-code/settings#settings-files
+// This can be removed once the SDK supports it natively.
+function getManagedSettingsPath(): string {
+  const os = platform();
+  switch (os) {
+    case "darwin":
+      return "/Library/Application Support/ClaudeCode/managed-settings.json";
+    case "linux": // including WSL
+      return "/etc/claude-code/managed-settings.json";
+    case "win32":
+      return "C:\\ProgramData\\ClaudeCode\\managed-settings.json";
+    default:
+      return "/etc/claude-code/managed-settings.json";
+  }
+}
+
+export function loadManagedSettings(): ManagedSettings | null {
+  try {
+    return JSON.parse(readFileSync(getManagedSettingsPath(), "utf8")) as ManagedSettings;
+  } catch {
+    return null;
+  }
+}
+
+export function applyEnvironmentSettings(settings: ManagedSettings): void {
+  if (settings.env) {
+    for (const [key, value] of Object.entries(settings.env)) {
+      process.env[key] = value;
+    }
+  }
+}
+
+export interface ExtractLinesResult {
+  content: string;
+  wasLimited: boolean;
+  linesRead: number;
+}
+
+/**
+ * Extracts lines from file content with byte limit enforcement.
+ *
+ * @param fullContent - The complete file content
+ * @param maxContentLength - Maximum number of UTF-16 Code Units to return
+ * @returns Object containing extracted content and metadata
+ */
+export function extractLinesWithByteLimit(
+  fullContent: string,
+  maxContentLength: number,
+): ExtractLinesResult {
+  if (fullContent === "") {
+    return {
+      content: "",
+      wasLimited: false,
+      linesRead: 1,
+    };
+  }
+
+  let linesSeen = 0;
+  let index = 0;
+  linesSeen = 0;
+
+  let contentLength = 0;
+  let wasLimited = false;
+
+  while (true) {
+    const nextIndex = fullContent.indexOf("\n", index);
+
+    if (nextIndex < 0) {
+      // Last line in file (no trailing newline)
+      if (linesSeen > 0 && fullContent.length > maxContentLength) {
+        wasLimited = true;
+        break;
+      }
+      linesSeen += 1;
+      contentLength = fullContent.length;
+      break;
+    } else {
+      // Line with newline - include up to the newline
+      const newContentLength = nextIndex + 1;
+      if (linesSeen > 0 && newContentLength > maxContentLength) {
+        wasLimited = true;
+        break;
+      }
+      linesSeen += 1;
+      contentLength = newContentLength;
+      index = newContentLength;
+    }
+  }
+
+  return {
+    content: fullContent.slice(0, contentLength),
+    wasLimited,
+    linesRead: linesSeen,
+  };
+}