Prep v0.12.6 (#214)

Verified in Tidewave!

---------

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

.github/workflows/publish.yml

@@ -4,7 +4,7 @@ on:
     tags:
       - "v*.*.*"
 jobs:
-  build:
+  publish-npm:
     runs-on: ubuntu-latest
     environment: release # Optional: for enhanced security
     permissions:
@@ -22,3 +22,13 @@ jobs:
       - run: npm ci
       - 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

.gitignore

@@ -1,2 +1,3 @@
 node_modules
 dist
+.DS_Store

CHANGELOG.md

@@ -1,5 +1,155 @@
 # Changelog
 
+## 0.12.6
+
+- Fix model selection
+
+## 0.12.5
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.70
+- Unstable implementation of resuming sessions
+
+## 0.12.4
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.67
+- Better respect permissions specified in settings files
+- Unstable implementation of forking
+
+## 0.12.3
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.65
+- Update to @agentclientprotocol/sdk@0.9.0
+- Allow agent to write plans and todos to its config directory
+- Fix experimental resume ids
+
+## 0.12.2
+
+- Fix duplicate tool use IDs error
+
+## 0.12.1
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.61
+- Update to @agentclientprotocol/sdk@0.8.0
+
+## 0.12.0
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.59
+  - Brings Opus to Claude Pro plans
+  - Support "Don't Ask" profile
+- Unify ACP + Claude Code session ids
+
+## 0.11.0
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.57
+- Removed dependency on @anthropic-ai/claude-code since this is no longer needed
+
+## 0.10.10
+
+- Update to @agentclientprotocol/sdk@0.7.0
+
+## 0.10.9
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.55
+- Allow defining a custom logger when used as a library
+- Allow specifying custom options when used as a library
+- Add `CLAUDECODE=1` to terminal invocations to match default Claude Code behavior
+
+## 0.10.8
+
+- Update to @anthropic-ai/claude-agent-sdk@v0.1.51 (adds support for Opus 4.5)
+
+## 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.

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

package.json

@@ -3,12 +3,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "version": "0.12.6",
+  "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.6.2",
-  "description": "An ACP-compatible coding agent powered by the Claude Code SDK (TypeScript)",
-  "main": "dist/index.js",
   "type": "module",
   "files": [
     "dist/",
@@ -51,30 +51,23 @@
   "author": "Zed Industries",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.4.8",
-    "@anthropic-ai/claude-agent-sdk": "0.1.19",
-    "@anthropic-ai/claude-code": "2.0.19",
-    "@modelcontextprotocol/sdk": "1.20.0",
+    "@agentclientprotocol/sdk": "0.12.0",
+    "@anthropic-ai/claude-agent-sdk": "0.1.70",
+    "@modelcontextprotocol/sdk": "1.25.0",
     "diff": "8.0.2",
-    "express": "5.1.0",
-    "minimist": "1.2.8",
-    "uuid": "13.0.0"
+    "minimatch": "^10.1.1"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.66.0",
-    "@types/express": "5.0.3",
-    "@types/minimist": "1.2.5",
-    "@types/node": "24.8.0",
-    "@types/uuid": "10.0.0",
-    "@typescript-eslint/eslint-plugin": "8.46.1",
-    "@typescript-eslint/parser": "8.46.1",
-    "@vitest/ui": "3.2.4",
-    "eslint": "9.37.0",
+    "@anthropic-ai/sdk": "0.71.2",
+    "@types/node": "25.0.2",
+    "@typescript-eslint/eslint-plugin": "8.50.0",
+    "@typescript-eslint/parser": "8.50.0",
+    "eslint": "9.39.2",
     "eslint-config-prettier": "10.1.8",
-    "globals": "16.4.0",
-    "prettier": "3.6.2",
+    "globals": "16.5.0",
+    "prettier": "3.7.4",
     "ts-node": "10.9.2",
     "typescript": "5.9.3",
-    "vitest": "3.2.4"
+    "vitest": "4.0.15"
   }
 }

src/index.ts

@@ -19,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

src/lib.ts

@@ -0,0 +1,36 @@
+// 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 } from "./mcp-server.js";
+export {
+  toolInfoFromToolUse,
+  planEntries,
+  toolUpdateFromToolResult,
+  createPreToolUseHook,
+  acpToolNames as toolNames,
+} from "./tools.js";
+export {
+  SettingsManager,
+  type ClaudeCodeSettings,
+  type PermissionSettings,
+  type PermissionDecision,
+  type PermissionCheckResult,
+  type SettingsManagerOptions,
+} from "./settings.js";
+
+// Export types
+export type { ClaudePlanEntry } from "./tools.js";

src/mcp-server.ts

@@ -1,15 +1,24 @@
-import express from "express";
-
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  BashInput,
+  FileEditInput,
+  FileReadInput,
+  FileWriteInput,
+  KillShellInput,
+} from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 import { z } from "zod";
-import { Server } from "node:http";
-import { ClaudeAcpAgent } from "./acp-agent.js";
-import { ClientCapabilities, TerminalOutputResponse } from "@agentclientprotocol/sdk";
+import { CLAUDE_CONFIG_DIR, ClaudeAcpAgent } from "./acp-agent.js";
+import {
+  ClientCapabilities,
+  ReadTextFileResponse,
+  TerminalOutputResponse,
+} from "@agentclientprotocol/sdk";
 import * as diff from "diff";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
 
 import { sleep, unreachable, extractLinesWithByteLimit } from "./utils.js";
-import { PermissionResult } from "@anthropic-ai/claude-agent-sdk";
+import { acpToolNames } from "./tools.js";
 
 export const SYSTEM_REMINDER = `
 
@@ -28,23 +37,67 @@ const unqualifiedToolNames = {
   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,
-};
-
-const editToolNames = [toolNames.edit, toolNames.write];
-
 export function createMcpServer(
   agent: ClaudeAcpAgent,
   sessionId: string,
   clientCapabilities: ClientCapabilities | undefined,
 ): McpServer {
+  /**
+   * This checks if a given path is related to internal agent persistence and if the agent should be allowed to read/write from here.
+   * We let the agent do normal fs operations on these paths so that it can persist its state.
+   * However, we block access to settings files for security reasons.
+   */
+  function internalPath(file_path: string) {
+    return (
+      file_path.startsWith(CLAUDE_CONFIG_DIR) &&
+      !file_path.startsWith(path.join(CLAUDE_CONFIG_DIR, "settings.json")) &&
+      !file_path.startsWith(path.join(CLAUDE_CONFIG_DIR, "session-env"))
+    );
+  }
+
+  async function readTextFile(input: FileReadInput): Promise<ReadTextFileResponse> {
+    if (internalPath(input.file_path)) {
+      const content = await fs.readFile(input.file_path, "utf8");
+
+      // eslint-disable-next-line eqeqeq
+      if (input.offset != null || input.limit != null) {
+        const lines = content.split("\n");
+
+        // Apply offset and limit if provided
+        const offset = input.offset ?? 1;
+        const limit = input.limit ?? lines.length;
+
+        // Extract the requested lines (offset is 1-based)
+        const startIndex = Math.max(0, offset - 1);
+        const endIndex = Math.min(lines.length, startIndex + limit);
+        const selectedLines = lines.slice(startIndex, endIndex);
+
+        return { content: selectedLines.join("\n") };
+      } else {
+        return { content };
+      }
+    }
+
+    return agent.readTextFile({
+      sessionId,
+      path: input.file_path,
+      line: input.offset,
+      limit: input.limit,
+    });
+  }
+
+  async function writeTextFile(input: FileWriteInput): Promise<void> {
+    if (internalPath(input.file_path)) {
+      await fs.writeFile(input.file_path, input.content, "utf8");
+    } else {
+      await agent.writeTextFile({
+        sessionId,
+        path: input.file_path,
+        content: input.content,
+      });
+    }
+  }
+
   // Create MCP server
   const server = new McpServer({ name: "acp", version: "1.0.0" }, { capabilities: { tools: {} } });
 
@@ -55,7 +108,7 @@ export function createMcpServer(
         title: unqualifiedToolNames.read,
         description: `Reads the content of the given file in the project.
 
-In sessions with ${toolNames.read} always use it instead of Read as it contains the most up-to-date contents.
+In sessions with ${acpToolNames.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.
 
@@ -65,7 +118,7 @@ Usage:
 - 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.
+- This tool can only read files, not directories. To read a directory, use an ls command via the ${acpToolNames.bash} tool.
 - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.`,
         inputSchema: {
           file_path: z.string().describe("The absolute path to the file to read"),
@@ -92,7 +145,7 @@ Usage:
           idempotentHint: false,
         },
       },
-      async (input) => {
+      async (input: FileReadInput) => {
         try {
           const session = agent.sessions[sessionId];
           if (!session) {
@@ -106,19 +159,18 @@ Usage:
             };
           }
 
-          const content = await agent.readTextFile({
-            sessionId,
-            path: input.file_path,
-            line: input.offset,
-            limit: input.limit,
-          });
+          const readResponse = await readTextFile(input);
+
+          if (typeof readResponse?.content !== "string") {
+            throw new Error(`No file contents for ${input.file_path}.`);
+          }
 
           // Extract lines with byte limit enforcement
-          const result = extractLinesWithByteLimit(content.content, defaults.maxFileSize);
+          const result = extractLinesWithByteLimit(readResponse.content, defaults.maxFileSize);
 
           // Construct informative message about what was read
           let readInfo = "";
-          if (input.offset > 1 || result.wasLimited) {
+          if ((input.offset && input.offset > 1) || result.wasLimited) {
             readInfo = "\n\n<file-read-info>";
 
             if (result.wasLimited) {
@@ -163,12 +215,12 @@ Usage:
         title: unqualifiedToolNames.write,
         description: `Writes a file to the local filesystem..
 
-In sessions with ${toolNames.write} always use it instead of Write as it will
+In sessions with ${acpToolNames.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.
+- If this is an existing file, you MUST use the ${acpToolNames.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.`,
@@ -186,7 +238,7 @@ Usage:
           idempotentHint: false,
         },
       },
-      async (input) => {
+      async (input: FileWriteInput) => {
         try {
           const session = agent.sessions[sessionId];
           if (!session) {
@@ -199,11 +251,7 @@ Usage:
               ],
             };
           }
-          await agent.writeTextFile({
-            sessionId,
-            path: input.file_path,
-            content: input.content,
-          });
+          await writeTextFile(input);
 
           return {
             content: [],
@@ -227,11 +275,11 @@ Usage:
         title: unqualifiedToolNames.edit,
         description: `Performs exact string replacements in files.
 
-In sessions with ${toolNames.edit} always use it instead of Edit as it will
+In sessions with ${acpToolNames.edit} always use it instead of Edit as it will
 allow the user to conveniently review changes.
 
 Usage:
-- You must use your \`${toolNames.read}\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- You must use your \`${acpToolNames.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.
@@ -247,7 +295,7 @@ Usage:
             .boolean()
             .default(false)
             .optional()
-            .describe("Replace all occurences of old_string (default false)"),
+            .describe("Replace all occurrences of old_string (default false)"),
         },
         annotations: {
           title: "Edit file",
@@ -257,48 +305,58 @@ Usage:
           idempotentHint: false,
         },
       },
-      async (input) => {
-        const session = agent.sessions[sessionId];
-        if (!session) {
+      async (input: FileEditInput) => {
+        try {
+          const session = agent.sessions[sessionId];
+          if (!session) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "The user has left the building",
+                },
+              ],
+            };
+          }
+
+          const readResponse = await readTextFile({
+            file_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 writeTextFile({ file_path: input.file_path, content: newContent });
+
           return {
             content: [
               {
                 type: "text",
-                text: "The user has left the building",
+                text: patch,
+              },
+            ],
+          };
+        } catch (error: any) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Editing file failed: " + (error?.message ?? String(error)),
               },
             ],
           };
         }
-
-        const { content } = await agent.readTextFile({
-          sessionId,
-          path: input.file_path,
-        });
-
-        const { newContent } = replaceAndCalculateLocation(content, [
-          {
-            oldText: input.old_string,
-            newText: input.new_string,
-            replaceAll: input.replace_all,
-          },
-        ]);
-
-        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,
-            },
-          ],
-        };
       },
     );
   }
@@ -310,13 +368,10 @@ Usage:
         title: unqualifiedToolNames.bash,
         description: `Executes a bash command
 
-In sessions with ${toolNames.bash} always use it instead of Bash`,
+In sessions with ${acpToolNames.bash} always use it instead of Bash`,
         inputSchema: {
           command: z.string().describe("The command to execute"),
-          timeout: z
-            .number()
-            .default(2 * 60 * 1000)
-            .describe(`Optional timeout in milliseconds (max ${2 * 60 * 1000})`),
+          timeout: z.number().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
@@ -334,11 +389,11 @@ Output: Create directory 'foo'`),
             .boolean()
             .default(false)
             .describe(
-              `Set to true to run this command in the background. The tool returns an \`id\` that can be used with the \`${toolNames.bashOutput}\` tool to retrieve the current output, or the \`${toolNames.killShell}\` tool to stop it early.`,
+              `Set to true to run this command in the background. The tool returns an \`id\` that can be used with the \`${acpToolNames.bashOutput}\` tool to retrieve the current output, or the \`${acpToolNames.killShell}\` tool to stop it early.`,
             ),
         },
       },
-      async (input, extra) => {
+      async (input: BashInput, extra) => {
         const session = agent.sessions[sessionId];
         if (!session) {
           return {
@@ -363,6 +418,7 @@ Output: Create directory 'foo'`),
 
         const handle = await agent.client.createTerminal({
           command: input.command,
+          env: [{ name: "CLAUDECODE", value: "1" }],
           sessionId,
           outputByteLimit: 32_000,
         });
@@ -391,7 +447,7 @@ Output: Create directory 'foo'`),
         const statusPromise = Promise.race([
           handle.waitForExit().then((exitStatus) => ({ status: "exited" as const, exitStatus })),
           abortPromise.then(() => ({ status: "aborted" as const, exitStatus: null })),
-          sleep(input.timeout).then(async () => {
+          sleep(input.timeout ?? 2 * 60 * 1000).then(async () => {
             if (agent.backgroundTerminals[handle.id]?.status === "started") {
               await handle.kill();
             }
@@ -460,23 +516,25 @@ Output: Create directory 'foo'`),
       {
         title: unqualifiedToolNames.bashOutput,
         description: `- Retrieves output from a running or completed background bash shell
-- Takes a shell_id parameter identifying the shell
+- Takes a bash_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.`,
+In sessions with ${acpToolNames.bashOutput} always use it for output from Bash commands instead of TaskOutput.`,
         inputSchema: {
-          shell_id: z
+          bash_id: z
             .string()
-            .describe(`The id of the background bash command as returned by \`${toolNames.bash}\``),
+            .describe(
+              `The id of the background bash command as returned by \`${acpToolNames.bash}\``,
+            ),
         },
       },
       async (input) => {
-        const bgTerm = agent.backgroundTerminals[input.shell_id];
+        const bgTerm = agent.backgroundTerminals[input.bash_id];
 
         if (!bgTerm) {
-          throw new Error(`Unknown shell ${input.shell_id}`);
+          throw new Error(`Unknown shell ${input.bash_id}`);
         }
 
         if (bgTerm.status === "started") {
@@ -520,14 +578,16 @@ In sessions with ${toolNames.bashOutput} always use it instead of BashOutput.`,
 - 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.`,
+In sessions with ${acpToolNames.killShell} always use it instead of KillShell.`,
         inputSchema: {
           shell_id: z
             .string()
-            .describe(`The id of the background bash command as returned by \`${toolNames.bash}\``),
+            .describe(
+              `The id of the background bash command as returned by \`${acpToolNames.bash}\``,
+            ),
         },
       },
-      async (input) => {
+      async (input: KillShellInput) => {
         const bgTerm = agent.backgroundTerminals[input.shell_id];
 
         if (!bgTerm) {
@@ -568,7 +628,8 @@ In sessions with ${toolNames.killShell} always use it instead of KillShell.`,
               content: [{ type: "text", text: "Command killed by timeout." }],
             };
           default: {
-            return unreachable(bgTerm);
+            unreachable(bgTerm);
+            throw new Error("Unexpected background terminal status");
           }
         }
       },
@@ -578,189 +639,6 @@ In sessions with ${toolNames.killShell} always use it instead of KillShell.`,
   return server;
 }
 
-const UNQUALIFIED_PERMISSION_TOOL_NAME = "permission";
-const PERMISSION_SERVER_PREFIX = "mcp__acpPermission__";
-export const PERMISSION_TOOL_NAME = PERMISSION_SERVER_PREFIX + UNQUALIFIED_PERMISSION_TOOL_NAME;
-
-/**
- * Separate permission tool. Needs to be an HTTP server for now, because Claude Code doesn't
- * support permission tools via SDK servers.
- * Ideally it moves to the `canUseTool` callback in the future.
- */
-export function createPermissionMcpServer(
-  agent: ClaudeAcpAgent,
-  sessionId: string,
-): Promise<Server> {
-  const server = new McpServer(
-    { name: "acpPermission", version: "1.0.0" },
-    { capabilities: { tools: {} } },
-  );
-
-  const alwaysAllowedTools: { [key: string]: boolean } = {};
-  server.registerTool(
-    UNQUALIFIED_PERMISSION_TOOL_NAME,
-    {
-      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 result = await canUseTool(input);
-
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
-      };
-    },
-  );
-
-  async function canUseTool(input: {
-    tool_use_id?: string;
-    tool_name: string;
-    input?: any;
-  }): Promise<PermissionResult> {
-    const session = agent.sessions[sessionId];
-    if (!session) {
-      return {
-        behavior: "deny",
-        message: "Session not found",
-      };
-    }
-
-    if (input.tool_name === "ExitPlanMode") {
-      const response = await agent.client.requestPermission({
-        options: [
-          {
-            kind: "allow_always",
-            name: "Yes, and auto-accept edits",
-            optionId: "acceptEdits",
-          },
-          { kind: "allow_once", name: "Yes, and manually approve edits", optionId: "default" },
-          { kind: "reject_once", name: "No, keep planning", optionId: "plan" },
-        ],
-        sessionId,
-        toolCall: {
-          toolCallId: input.tool_use_id!,
-          rawInput: input.input,
-        },
-      });
-
-      if (
-        response.outcome?.outcome === "selected" &&
-        (response.outcome.optionId === "default" || response.outcome.optionId === "acceptEdits")
-      ) {
-        session.permissionMode = response.outcome.optionId;
-        await agent.client.sessionUpdate({
-          sessionId,
-          update: {
-            sessionUpdate: "current_mode_update",
-            currentModeId: response.outcome.optionId,
-          },
-        });
-
-        return {
-          behavior: "allow",
-          updatedInput: input.input,
-          updatedPermissions: [
-            { type: "setMode", mode: response.outcome.optionId, destination: "session" },
-          ],
-        };
-      } else {
-        return {
-          behavior: "deny",
-          message: "User rejected request to exit plan mode.",
-        };
-      }
-    }
-
-    if (
-      session.permissionMode === "bypassPermissions" ||
-      (session.permissionMode === "acceptEdits" && editToolNames.includes(input.tool_name)) ||
-      alwaysAllowedTools[input.tool_name]
-    ) {
-      return {
-        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 {
-        behavior: "allow",
-        updatedInput: input.input,
-      };
-    } else {
-      return {
-        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);
-    });
-  });
-}
-
 function stripCommonPrefix(a: string, b: string): string {
   let i = 0;
   while (i < a.length && i < b.length && a[i] === b[i]) {

src/settings.ts

@@ -0,0 +1,522 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { minimatch } from "minimatch";
+import { ACP_TOOL_NAME_PREFIX, acpToolNames } from "./tools.js";
+import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
+
+/**
+ * Permission rule format examples:
+ * - "Read" - matches all Read tool calls
+ * - "Read(./.env)" - matches specific path
+ * - "Read(./.env.*)" - glob pattern
+ * - "Read(./secrets/**)" - recursive glob
+ * - "Bash(npm run lint)" - exact command prefix
+ * - "Bash(npm run:*)" - command prefix with wildcard
+ *
+ * Docs: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
+ */
+
+export interface PermissionSettings {
+  allow?: string[];
+  deny?: string[];
+  ask?: string[];
+  additionalDirectories?: string[];
+  defaultMode?: string;
+}
+
+export interface ClaudeCodeSettings {
+  permissions?: PermissionSettings;
+  env?: Record<string, string>;
+}
+
+export type PermissionDecision = "allow" | "deny" | "ask";
+
+export interface PermissionCheckResult {
+  decision: PermissionDecision;
+  rule?: string;
+  source?: "allow" | "deny" | "ask";
+}
+
+interface ParsedRule {
+  toolName: string;
+  argument?: string;
+  isWildcard?: boolean;
+}
+
+/**
+ * Shell operators that can be used for command chaining/injection
+ * These should cause a prefix match to fail to prevent bypasses like:
+ * - "safe-cmd && malicious-cmd"
+ * - "safe-cmd; malicious-cmd"
+ * - "safe-cmd | malicious-cmd"
+ * - "safe-cmd || malicious-cmd"
+ * - "$(malicious-cmd)"
+ * - "`malicious-cmd`"
+ */
+const SHELL_OPERATORS = ["&&", "||", ";", "|", "$(", "`", "\n"];
+
+/**
+ * Checks if a string contains shell operators that could allow command chaining
+ */
+function containsShellOperator(str: string): boolean {
+  return SHELL_OPERATORS.some((op) => str.includes(op));
+}
+
+/*
+ * Tools that modify files. Per Claude Code docs:
+ * "Edit rules apply to all built-in tools that edit files."
+ * This means an Edit(...) rule should match Write, MultiEdit, etc.
+ */
+const FILE_EDITING_TOOLS = [acpToolNames.edit, acpToolNames.write];
+
+/**
+ * Tools that read files. Per Claude Code docs:
+ * "Claude will make a best-effort attempt to apply Read rules to all built-in tools
+ * that read files like Grep and Glob."
+ * This means a Read(...) rule should match Grep, Glob, etc.
+ */
+const FILE_READING_TOOLS = [acpToolNames.read];
+
+/**
+ * Functions to extract the relevant argument from tool input for permission matching
+ */
+const TOOL_ARG_ACCESSORS: Record<string, (input: unknown) => string | undefined> = {
+  mcp__acp__Read: (input) => (input as { file_path?: string })?.file_path,
+  mcp__acp__Edit: (input) => (input as { file_path?: string })?.file_path,
+  mcp__acp__Write: (input) => (input as { file_path?: string })?.file_path,
+  mcp__acp__Bash: (input) => (input as { command?: string })?.command,
+};
+
+/**
+ * Parses a permission rule string into its components
+ * Examples:
+ *   "Read" -> { toolName: "Read" }
+ *   "Read(./.env)" -> { toolName: "Read", argument: "./.env" }
+ *   "Bash(npm run:*)" -> { toolName: "Bash", argument: "npm run", isWildcard: true }
+ */
+function parseRule(rule: string): ParsedRule {
+  const match = rule.match(/^(\w+)(?:\((.+)\))?$/);
+  if (!match) {
+    return { toolName: rule };
+  }
+
+  const [, toolName, argument] = match;
+
+  if (argument && argument.endsWith(":*")) {
+    return {
+      toolName,
+      argument: argument.slice(0, -2),
+      isWildcard: true,
+    };
+  }
+
+  return { toolName, argument };
+}
+
+/**
+ * Normalizes a path for comparison:
+ * - Expands ~ to home directory
+ * - Resolves relative paths against cwd
+ * - Normalizes path separators
+ */
+function normalizePath(filePath: string, cwd: string): string {
+  if (filePath.startsWith("~/")) {
+    filePath = path.join(os.homedir(), filePath.slice(2));
+  } else if (filePath.startsWith("./")) {
+    filePath = path.join(cwd, filePath.slice(2));
+  } else if (!path.isAbsolute(filePath)) {
+    filePath = path.join(cwd, filePath);
+  }
+  return path.normalize(filePath);
+}
+
+/**
+ * Checks if a file path matches a glob pattern
+ */
+function matchesGlob(pattern: string, filePath: string, cwd: string): boolean {
+  const normalizedPattern = normalizePath(pattern, cwd);
+  const normalizedPath = normalizePath(filePath, cwd);
+
+  return minimatch(normalizedPath, normalizedPattern, {
+    dot: true,
+    matchBase: false,
+    nocase: process.platform === "win32",
+  });
+}
+
+/**
+ * Checks if a tool invocation matches a parsed permission rule
+ */
+function matchesRule(rule: ParsedRule, toolName: string, toolInput: unknown, cwd: string): boolean {
+  // Per Claude Code docs:
+  // - "Edit rules apply to all built-in tools that edit files."
+  // - "Claude will make a best-effort attempt to apply Read rules to all built-in tools
+  //    that read files like Grep, Glob, and LS."
+  const ruleAppliesToTool =
+    rule.toolName === "Bash" ||
+    (rule.toolName === "Edit" && FILE_EDITING_TOOLS.includes(toolName)) ||
+    (rule.toolName === "Read" && FILE_READING_TOOLS.includes(toolName));
+
+  if (!ruleAppliesToTool) {
+    return false;
+  }
+
+  if (!rule.argument) {
+    return true;
+  }
+
+  const argAccessor = TOOL_ARG_ACCESSORS[toolName];
+  if (!argAccessor) {
+    return true;
+  }
+
+  const actualArg = argAccessor(toolInput);
+  if (!actualArg) {
+    return false;
+  }
+
+  if (toolName === acpToolNames.bash) {
+    // Per Claude Code docs: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
+    // - Bash(npm run build) matches the EXACT command "npm run build"
+    // - Bash(npm run test:*) matches commands STARTING WITH "npm run test"
+    // The :* suffix enables prefix matching, without it the match is exact
+    //
+    // Also from docs: "Claude Code is aware of shell operators (like &&) so a prefix match
+    // rule like Bash(safe-cmd:*) won't give it permission to run the command safe-cmd && other-cmd"
+    if (rule.isWildcard) {
+      if (!actualArg.startsWith(rule.argument)) {
+        return false;
+      }
+      // Check that the matched prefix isn't followed by shell operators that could
+      // allow command chaining/injection
+      const remainder = actualArg.slice(rule.argument.length);
+      if (containsShellOperator(remainder)) {
+        return false;
+      }
+      return true;
+    }
+    return actualArg === rule.argument;
+  }
+
+  // For file-based tools (Read, Edit, Write), use glob matching
+  return matchesGlob(rule.argument, actualArg, cwd);
+}
+
+/**
+ * Reads and parses a JSON settings file, returning an empty object if not found or invalid
+ */
+async function loadSettingsFile(filePath: string | null): Promise<ClaudeCodeSettings> {
+  if (!filePath) {
+    return {};
+  }
+
+  try {
+    const content = await fs.promises.readFile(filePath, "utf-8");
+    return JSON.parse(content) as ClaudeCodeSettings;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Gets the enterprise settings path based on the current platform
+ */
+export function getManagedSettingsPath(): string {
+  switch (process.platform) {
+    case "darwin":
+      return "/Library/Application Support/ClaudeCode/managed-settings.json";
+    case "linux":
+      return "/etc/claude-code/managed-settings.json";
+    case "win32":
+      return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
+    default:
+      return "/etc/claude-code/managed-settings.json";
+  }
+}
+
+export interface SettingsManagerOptions {
+  onChange?: () => void;
+  logger?: { log: (...args: any[]) => void; error: (...args: any[]) => void };
+}
+
+/**
+ * Manages Claude Code settings from multiple sources with proper precedence.
+ *
+ * Settings are loaded from (in order of increasing precedence):
+ * 1. User settings (~/.claude/settings.json)
+ * 2. Project settings (<cwd>/.claude/settings.json)
+ * 3. Local project settings (<cwd>/.claude/settings.local.json)
+ * 4. Enterprise managed settings (platform-specific path)
+ *
+ * The manager watches all settings files for changes and automatically reloads.
+ */
+export class SettingsManager {
+  private cwd: string;
+  private userSettings: ClaudeCodeSettings = {};
+  private projectSettings: ClaudeCodeSettings = {};
+  private localSettings: ClaudeCodeSettings = {};
+  private enterpriseSettings: ClaudeCodeSettings = {};
+  private mergedSettings: ClaudeCodeSettings = {};
+  private watchers: fs.FSWatcher[] = [];
+  private onChange?: () => void;
+  private logger: { log: (...args: any[]) => void; error: (...args: any[]) => void };
+  private initialized = false;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(cwd: string, options?: SettingsManagerOptions) {
+    this.cwd = cwd;
+    this.onChange = options?.onChange;
+    this.logger = options?.logger ?? console;
+  }
+
+  /**
+   * Initialize the settings manager by loading all settings and setting up file watchers
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    await this.loadAllSettings();
+    this.setupWatchers();
+    this.initialized = true;
+  }
+
+  /**
+   * Returns the path to the user settings file
+   */
+  private getUserSettingsPath(): string {
+    return path.join(CLAUDE_CONFIG_DIR, "settings.json");
+  }
+
+  /**
+   * Returns the path to the project settings file
+   */
+  private getProjectSettingsPath(): string {
+    return path.join(this.cwd, ".claude", "settings.json");
+  }
+
+  /**
+   * Returns the path to the local project settings file
+   */
+  private getLocalSettingsPath(): string {
+    return path.join(this.cwd, ".claude", "settings.local.json");
+  }
+
+  /**
+   * Loads settings from all sources
+   */
+  private async loadAllSettings(): Promise<void> {
+    const [userSettings, projectSettings, localSettings, enterpriseSettings] = await Promise.all([
+      loadSettingsFile(this.getUserSettingsPath()),
+      loadSettingsFile(this.getProjectSettingsPath()),
+      loadSettingsFile(this.getLocalSettingsPath()),
+      loadSettingsFile(getManagedSettingsPath()),
+    ]);
+
+    this.userSettings = userSettings;
+    this.projectSettings = projectSettings;
+    this.localSettings = localSettings;
+    this.enterpriseSettings = enterpriseSettings;
+
+    this.mergeSettings();
+  }
+
+  /**
+   * Merges all settings sources with proper precedence.
+   * For permissions, rules from all sources are combined.
+   * Deny rules always take precedence during permission checks.
+   */
+  private mergeSettings(): void {
+    const allSettings = [
+      this.userSettings,
+      this.projectSettings,
+      this.localSettings,
+      this.enterpriseSettings,
+    ];
+
+    const merged: ClaudeCodeSettings = {
+      permissions: {
+        allow: [],
+        deny: [],
+        ask: [],
+      },
+    };
+
+    for (const settings of allSettings) {
+      if (settings.permissions) {
+        if (settings.permissions.allow) {
+          merged.permissions!.allow!.push(...settings.permissions.allow);
+        }
+        if (settings.permissions.deny) {
+          merged.permissions!.deny!.push(...settings.permissions.deny);
+        }
+        if (settings.permissions.ask) {
+          merged.permissions!.ask!.push(...settings.permissions.ask);
+        }
+        if (settings.permissions.additionalDirectories) {
+          merged.permissions!.additionalDirectories = [
+            ...(merged.permissions!.additionalDirectories || []),
+            ...settings.permissions.additionalDirectories,
+          ];
+        }
+        if (settings.permissions.defaultMode) {
+          merged.permissions!.defaultMode = settings.permissions.defaultMode;
+        }
+      }
+
+      if (settings.env) {
+        merged.env = { ...merged.env, ...settings.env };
+      }
+    }
+
+    this.mergedSettings = merged;
+  }
+
+  /**
+   * Sets up file watchers for all settings files
+   */
+  private setupWatchers(): void {
+    const paths = [
+      this.getUserSettingsPath(),
+      this.getProjectSettingsPath(),
+      this.getLocalSettingsPath(),
+      getManagedSettingsPath(),
+    ];
+
+    for (const filePath of paths) {
+      if (!filePath) continue;
+
+      try {
+        const dir = path.dirname(filePath);
+        const filename = path.basename(filePath);
+
+        if (fs.existsSync(dir)) {
+          const watcher = fs.watch(dir, (eventType, changedFilename) => {
+            if (changedFilename === filename) {
+              this.handleSettingsChange();
+            }
+          });
+
+          watcher.on("error", (error) => {
+            this.logger.error(`Settings watcher error for ${filePath}:`, error);
+          });
+
+          this.watchers.push(watcher);
+        }
+      } catch (error) {
+        this.logger.error(`Failed to set up watcher for ${filePath}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Handles settings file changes with debouncing to avoid rapid reloads
+   */
+  private handleSettingsChange(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(async () => {
+      this.debounceTimer = null;
+      try {
+        await this.loadAllSettings();
+        this.onChange?.();
+      } catch (error) {
+        this.logger.error("Failed to reload settings:", error);
+      }
+    }, 100);
+  }
+
+  /**
+   * Checks if a tool invocation is allowed based on the loaded settings.
+   *
+   * @param toolName - The tool name (can be ACP-prefixed like mcp__acp__Read or plain like Read)
+   * @param toolInput - The tool input object
+   * @returns The permission decision and matching rule info
+   */
+  checkPermission(toolName: string, toolInput: unknown): PermissionCheckResult {
+    if (!toolName.startsWith(ACP_TOOL_NAME_PREFIX)) {
+      return { decision: "ask" };
+    }
+
+    const permissions = this.mergedSettings.permissions;
+
+    if (!permissions) {
+      return { decision: "ask" };
+    }
+
+    // Check deny rules first (highest priority)
+    for (const rule of permissions.deny || []) {
+      const parsed = parseRule(rule);
+      if (matchesRule(parsed, toolName, toolInput, this.cwd)) {
+        return { decision: "deny", rule, source: "deny" };
+      }
+    }
+
+    // Check allow rules
+    for (const rule of permissions.allow || []) {
+      const parsed = parseRule(rule);
+      if (matchesRule(parsed, toolName, toolInput, this.cwd)) {
+        return { decision: "allow", rule, source: "allow" };
+      }
+    }
+
+    // Check ask rules
+    for (const rule of permissions.ask || []) {
+      const parsed = parseRule(rule);
+      if (matchesRule(parsed, toolName, toolInput, this.cwd)) {
+        return { decision: "ask", rule, source: "ask" };
+      }
+    }
+
+    // No matching rule - default to ask
+    return { decision: "ask" };
+  }
+
+  /**
+   * Returns the current merged settings
+   */
+  getSettings(): ClaudeCodeSettings {
+    return this.mergedSettings;
+  }
+
+  /**
+   * Returns the current working directory
+   */
+  getCwd(): string {
+    return this.cwd;
+  }
+
+  /**
+   * Updates the working directory and reloads project-specific settings
+   */
+  async setCwd(cwd: string): Promise<void> {
+    if (this.cwd === cwd) {
+      return;
+    }
+
+    this.dispose();
+    this.cwd = cwd;
+    this.initialized = false;
+    await this.initialize();
+  }
+
+  /**
+   * Disposes of file watchers and cleans up resources
+   */
+  dispose(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+    this.initialized = false;
+  }
+}

src/tests/acp-agent.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import { spawn, spawnSync } from "child_process";
 import {
   Agent,
+  AgentSideConnection,
   AvailableCommand,
   Client,
   ClientSideConnection,
@@ -17,8 +18,9 @@ import {
 } from "@agentclientprotocol/sdk";
 import { nodeToWebWritable, nodeToWebReadable } from "../utils.js";
 import { markdownEscape, toolInfoFromToolUse, toolUpdateFromToolResult } from "../tools.js";
-import { toAcpNotifications } from "../acp-agent.js";
+import { toAcpNotifications, promptToClaude } from "../acp-agent.js";
 import { query, SDKAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
+import { randomUUID } from "crypto";
 
 describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration", () => {
   let child: ReturnType<typeof spawn>;
@@ -491,50 +493,6 @@ describe("tool conversions", () => {
     });
   });
 
-  it("should handle WebFetch tool calls", () => {
-    const tool_use = {
-      type: "tool_use",
-      id: "toolu_01LxEjDn8ci9SAc3qG7LbbXV",
-      name: "WebFetch",
-      input: {
-        url: "https://agentclientprotocol.com",
-        prompt:
-          "Please provide a comprehensive summary of the content on this page, including what the Agent Client Protocol is, its main features, documentation links, and any other relevant information.",
-      },
-    };
-
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
-      kind: "fetch",
-      title: "Fetch https://agentclientprotocol.com",
-      content: [
-        {
-          content: {
-            text: "Please provide a comprehensive summary of the content on this page, including what the Agent Client Protocol is, its main features, documentation links, and any other relevant information.",
-            type: "text",
-          },
-          type: "content",
-        },
-      ],
-    });
-  });
-
-  it("should handle WebSearch tool calls", () => {
-    const tool_use = {
-      type: "tool_use",
-      id: "toolu_01NYMwiZFbdoQFxYxuQDFZXQ",
-      name: "WebSearch",
-      input: {
-        query: "agentclientprotocol.com",
-      },
-    };
-
-    expect(toolInfoFromToolUse(tool_use, {})).toStrictEqual({
-      kind: "fetch",
-      title: '"agentclientprotocol.com"',
-      content: [],
-    });
-  });
-
   it("should handle KillBash entries", () => {
     const tool_use = {
       type: "tool_use",
@@ -649,7 +607,17 @@ describe("tool conversions", () => {
       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: {
@@ -781,15 +749,122 @@ describe("escape markdown", () => {
   });
 });
 
-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("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.skipIf(!process.env.RUN_INTEGRATION_TESTS)("SDK behavior", () => {
+  it("query has a 'default' model", async () => {
+    const q = query({ prompt: "hi" });
+    const models = await q.supportedModels();
+    const defaultModel = models.find((m) => m.value === "default");
+    expect(defaultModel).toBeDefined();
+  }, 10000);
+
+  it("custom session id", async () => {
+    const sessionId = randomUUID();
+    const q = query({
+      prompt: "hi",
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        extraArgs: { "session-id": sessionId },
+        settingSources: ["user", "project", "local"],
+        includePartialMessages: true,
+      },
+    });
+
+    const { value } = await q.next();
+    expect(value).toMatchObject({ type: "system", subtype: "init", session_id: sessionId });
+  }, 10000);
+});
+
+describe("permission requests", () => {
+  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);
+    }
+  });
 });

src/tests/settings.test.ts

@@ -0,0 +1,617 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { SettingsManager } from "../settings.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+describe("SettingsManager", () => {
+  let tempDir: string;
+  let settingsManager: SettingsManager;
+
+  beforeEach(async () => {
+    tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "settings-test-"));
+  });
+
+  afterEach(async () => {
+    settingsManager?.dispose();
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe("permission checking", () => {
+    it("should return 'ask' when no settings exist", async () => {
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const result = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: "/some/file.txt",
+      });
+      expect(result.decision).toBe("ask");
+    });
+
+    it("should return 'ask' for non-ACP tools (permission checks only apply to mcp__acp__* tools)", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Read"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      // Non-ACP tools should always return 'ask' regardless of rules
+      const result = settingsManager.checkPermission("Read", { file_path: "/some/file.txt" });
+      expect(result.decision).toBe("ask");
+    });
+
+    it("should allow tool use when matching allow rule exists", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Read"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const result = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: "/some/file.txt",
+      });
+      expect(result.decision).toBe("allow");
+      expect(result.rule).toBe("Read");
+    });
+
+    it("should deny tool use when matching deny rule exists", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Read(./.env)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const result = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".env"),
+      });
+      expect(result.decision).toBe("deny");
+      expect(result.rule).toBe("Read(./.env)");
+    });
+
+    it("should prioritize deny rules over allow rules", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Read"],
+            deny: ["Read(./.env)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      // .env should be denied
+      const envResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".env"),
+      });
+      expect(envResult.decision).toBe("deny");
+
+      // other files should be allowed
+      const otherResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, "other.txt"),
+      });
+      expect(otherResult.decision).toBe("allow");
+    });
+
+    it("should handle ACP-prefixed tool names", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Read"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const result = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: "/some/file.txt",
+      });
+      expect(result.decision).toBe("allow");
+    });
+  });
+
+  describe("Bash permission rules", () => {
+    it("should match exact Bash commands without :* wildcard", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            // Per docs: Bash(npm run build) matches the EXACT command "npm run build"
+            allow: ["Bash(npm run lint)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      // Exact match should be allowed
+      const exactResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm run lint",
+      });
+      expect(exactResult.decision).toBe("allow");
+
+      // Command with extra arguments should NOT match (exact match only)
+      const withArgsResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm run lint --fix",
+      });
+      expect(withArgsResult.decision).toBe("ask");
+
+      // Similar command should NOT match (exact match only)
+      const similarResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm run linting",
+      });
+      expect(similarResult.decision).toBe("ask");
+
+      // Different command should not match
+      const differentResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm run test",
+      });
+      expect(differentResult.decision).toBe("ask");
+    });
+
+    it("should match Bash commands with :* wildcard suffix (prefix matching)", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            // The :* suffix is a convention to make prefix matching explicit
+            allow: ["Bash(npm run:*)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      // Any command starting with "npm run" should match (prefix matching with :*)
+      const lintResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm run lint",
+      });
+      expect(lintResult.decision).toBe("allow");
+
+      const testResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm run test",
+      });
+      expect(testResult.decision).toBe("allow");
+
+      // Commands with additional args also match
+      const withArgsResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm run test --watch",
+      });
+      expect(withArgsResult.decision).toBe("allow");
+
+      // Non-matching command
+      const installResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "npm install",
+      });
+      expect(installResult.decision).toBe("ask");
+    });
+
+    it("should not allow shell operators to bypass prefix matching", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Bash(safe-cmd:*)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      // Normal prefix match should work
+      const normalResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd --flag",
+      });
+      expect(normalResult.decision).toBe("allow");
+
+      // Shell operators should NOT be allowed (per docs: Claude Code is aware of shell operators)
+      const andResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd && malicious-cmd",
+      });
+      expect(andResult.decision).toBe("ask");
+
+      const orResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd || malicious-cmd",
+      });
+      expect(orResult.decision).toBe("ask");
+
+      const semicolonResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd; malicious-cmd",
+      });
+      expect(semicolonResult.decision).toBe("ask");
+
+      const pipeResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd | malicious-cmd",
+      });
+      expect(pipeResult.decision).toBe("ask");
+
+      const subshellResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd $(malicious-cmd)",
+      });
+      expect(subshellResult.decision).toBe("ask");
+
+      const backtickResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd `malicious-cmd`",
+      });
+      expect(backtickResult.decision).toBe("ask");
+
+      const newlineResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "safe-cmd\nmalicious-cmd",
+      });
+      expect(newlineResult.decision).toBe("ask");
+    });
+
+    it("should deny dangerous Bash commands", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Bash(curl:*)", "Bash(wget:*)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const curlResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "curl https://example.com",
+      });
+      expect(curlResult.decision).toBe("deny");
+
+      const wgetResult = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "wget https://example.com",
+      });
+      expect(wgetResult.decision).toBe("deny");
+
+      const lsResult = settingsManager.checkPermission("mcp__acp__Bash", { command: "ls -la" });
+      expect(lsResult.decision).toBe("ask");
+    });
+  });
+
+  describe("file path glob matching", () => {
+    it("should match exact file paths", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Read(./.env)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const envResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".env"),
+      });
+      expect(envResult.decision).toBe("deny");
+
+      const otherResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".envrc"),
+      });
+      expect(otherResult.decision).toBe("ask");
+    });
+
+    it("should match glob patterns with single wildcard", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Read(./.env.*)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const envLocalResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".env.local"),
+      });
+      expect(envLocalResult.decision).toBe("deny");
+
+      const envProdResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".env.production"),
+      });
+      expect(envProdResult.decision).toBe("deny");
+
+      // Plain .env should not match .env.*
+      const plainEnvResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".env"),
+      });
+      expect(plainEnvResult.decision).toBe("ask");
+    });
+
+    it("should match glob patterns with double wildcard (recursive)", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Read(./secrets/**)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const secretResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, "secrets", "api-key.txt"),
+      });
+      expect(secretResult.decision).toBe("deny");
+
+      const nestedSecretResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, "secrets", "deep", "nested", "key.txt"),
+      });
+      expect(nestedSecretResult.decision).toBe("deny");
+
+      const otherResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, "public", "file.txt"),
+      });
+      expect(otherResult.decision).toBe("ask");
+    });
+
+    it("should handle home directory expansion", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Read(~/.zshrc)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const zshrcResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(os.homedir(), ".zshrc"),
+      });
+      expect(zshrcResult.decision).toBe("allow");
+    });
+  });
+
+  describe("settings merging", () => {
+    it("should merge project and local settings", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+
+      // Project settings
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Read"],
+          },
+        }),
+      );
+
+      // Local settings
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.local.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Read(./.env)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      // Read should be allowed in general
+      const readResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, "file.txt"),
+      });
+      expect(readResult.decision).toBe("allow");
+
+      // But .env should be denied (local settings take precedence)
+      const envResult = settingsManager.checkPermission("mcp__acp__Read", {
+        file_path: path.join(tempDir, ".env"),
+      });
+      expect(envResult.decision).toBe("deny");
+    });
+  });
+
+  describe("ask rules", () => {
+    it("should return 'ask' for matching ask rules", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            ask: ["Bash(git push:*)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const result = settingsManager.checkPermission("mcp__acp__Bash", {
+        command: "git push origin main",
+      });
+      expect(result.decision).toBe("ask");
+      expect(result.rule).toBe("Bash(git push:*)");
+    });
+  });
+
+  describe("Edit and Write tools", () => {
+    it("should handle Edit tool permissions", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Edit(./package-lock.json)"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const lockFileResult = settingsManager.checkPermission("mcp__acp__Edit", {
+        file_path: path.join(tempDir, "package-lock.json"),
+      });
+      expect(lockFileResult.decision).toBe("deny");
+
+      const otherResult = settingsManager.checkPermission("mcp__acp__Edit", {
+        file_path: path.join(tempDir, "package.json"),
+      });
+      expect(otherResult.decision).toBe("ask");
+    });
+
+    it("should handle mcp__acp__Edit and mcp__acp__Write tool names", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Edit", "Write"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const editResult = settingsManager.checkPermission("mcp__acp__Edit", {
+        file_path: "/some/file.ts",
+      });
+      expect(editResult.decision).toBe("allow");
+
+      const writeResult = settingsManager.checkPermission("mcp__acp__Write", {
+        file_path: "/some/file.ts",
+      });
+      expect(writeResult.decision).toBe("allow");
+    });
+  });
+
+  describe("getSettings", () => {
+    it("should return merged settings", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Read", "Bash(npm:*)"],
+            deny: ["Read(./.env)"],
+          },
+          env: {
+            FOO: "bar",
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const settings = settingsManager.getSettings();
+      expect(settings.permissions?.allow).toContain("Read");
+      expect(settings.permissions?.allow).toContain("Bash(npm:*)");
+      expect(settings.permissions?.deny).toContain("Read(./.env)");
+      expect(settings.env?.FOO).toBe("bar");
+    });
+  });
+
+  describe("setCwd", () => {
+    it("should reload settings when cwd changes", async () => {
+      const claudeDir1 = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir1, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir1, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            allow: ["Read"],
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      let result = settingsManager.checkPermission("mcp__acp__Read", { file_path: "/file.txt" });
+      expect(result.decision).toBe("allow");
+
+      // Create a new temp directory with different settings
+      const tempDir2 = await fs.promises.mkdtemp(path.join(os.tmpdir(), "settings-test-2-"));
+      const claudeDir2 = path.join(tempDir2, ".claude");
+      await fs.promises.mkdir(claudeDir2, { recursive: true });
+      await fs.promises.writeFile(
+        path.join(claudeDir2, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            deny: ["Read"],
+          },
+        }),
+      );
+
+      await settingsManager.setCwd(tempDir2);
+
+      result = settingsManager.checkPermission("mcp__acp__Read", { file_path: "/file.txt" });
+      expect(result.decision).toBe("deny");
+
+      // Cleanup second temp dir
+      await fs.promises.rm(tempDir2, { recursive: true, force: true });
+    });
+  });
+});

src/tools.ts

@@ -1,6 +1,40 @@
 import { PlanEntry, ToolCallContent, ToolCallLocation, ToolKind } from "@agentclientprotocol/sdk";
-import { replaceAndCalculateLocation, SYSTEM_REMINDER, toolNames } from "./mcp-server.js";
-import { ToolResultBlockParam } from "@anthropic-ai/sdk/resources";
+import { replaceAndCalculateLocation, SYSTEM_REMINDER } from "./mcp-server.js";
+import { ToolResultBlockParam, WebSearchToolResultBlockParam } from "@anthropic-ai/sdk/resources";
+
+const acpUnqualifiedToolNames = {
+  read: "Read",
+  edit: "Edit",
+  write: "Write",
+  bash: "Bash",
+  killShell: "KillShell",
+  bashOutput: "BashOutput",
+};
+
+export const ACP_TOOL_NAME_PREFIX = "mcp__acp__";
+export const acpToolNames = {
+  read: ACP_TOOL_NAME_PREFIX + acpUnqualifiedToolNames.read,
+  edit: ACP_TOOL_NAME_PREFIX + acpUnqualifiedToolNames.edit,
+  write: ACP_TOOL_NAME_PREFIX + acpUnqualifiedToolNames.write,
+  bash: ACP_TOOL_NAME_PREFIX + acpUnqualifiedToolNames.bash,
+  killShell: ACP_TOOL_NAME_PREFIX + acpUnqualifiedToolNames.killShell,
+  bashOutput: ACP_TOOL_NAME_PREFIX + acpUnqualifiedToolNames.bashOutput,
+};
+
+export const EDIT_TOOL_NAMES = [acpToolNames.edit, acpToolNames.write];
+
+import {
+  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";
+import { SettingsManager } from "./settings.js";
 
 interface ToolInfo {
   title: string;
@@ -18,6 +52,7 @@ interface ToolUpdate {
 export function toolInfoFromToolUse(
   toolUse: any,
   cachedFileContent: { [key: string]: string },
+  logger: Logger = console,
 ): ToolInfo {
   const name = toolUse.name;
   const input = toolUse.input;
@@ -63,7 +98,7 @@ export function toolInfoFromToolUse(
       };
 
     case "Bash":
-    case toolNames.bash:
+    case acpToolNames.bash:
       return {
         title: input?.command ? "`" + input.command.replaceAll("`", "\\`") + "`" : "Terminal",
         kind: "execute",
@@ -79,7 +114,7 @@ export function toolInfoFromToolUse(
       };
 
     case "BashOutput":
-    case toolNames.bashOutput:
+    case acpToolNames.bashOutput:
       return {
         title: "Tail Logs",
         kind: "execute",
@@ -87,14 +122,14 @@ export function toolInfoFromToolUse(
       };
 
     case "KillShell":
-    case toolNames.killShell:
+    case acpToolNames.killShell:
       return {
         title: "Kill Process",
         kind: "execute",
         content: [],
       };
 
-    case toolNames.read: {
+    case acpToolNames.read: {
       let limit = "";
       if (input.limit) {
         limit =
@@ -105,12 +140,14 @@ export function toolInfoFromToolUse(
       return {
         title: "Read " + (input.file_path ?? "File") + limit,
         kind: "read",
-        locations: [
-          {
-            path: input.file_path,
-            line: input.offset ?? 0,
-          },
-        ],
+        locations: input.file_path
+          ? [
+              {
+                path: input.file_path,
+                line: input.offset ?? 0,
+              },
+            ]
+          : [],
         content: [],
       };
     }
@@ -120,7 +157,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":
@@ -131,7 +175,7 @@ export function toolInfoFromToolUse(
         locations: [],
       };
 
-    case toolNames.edit:
+    case acpToolNames.edit:
     case "Edit": {
       const path = input?.file_path ?? input?.file_path;
       let oldText = input.old_string ?? null;
@@ -152,7 +196,7 @@ export function toolInfoFromToolUse(
           newText = newContent.newContent;
           affectedLines = newContent.lineNumbers;
         } catch (e) {
-          console.error(e);
+          logger.error(e);
         }
       }
       return {
@@ -177,7 +221,7 @@ export function toolInfoFromToolUse(
       };
     }
 
-    case toolNames.write: {
+    case acpToolNames.write: {
       let content: ToolCallContent[] = [];
       if (input && input.file_path) {
         content = [
@@ -336,7 +380,7 @@ 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",
@@ -385,12 +429,21 @@ export function toolInfoFromToolUse(
 }
 
 export function toolUpdateFromToolResult(
-  toolResult: ToolResultBlockParam,
+  toolResult:
+    | ToolResultBlockParam
+    | BetaWebSearchToolResultBlockParam
+    | BetaWebFetchToolResultBlockParam
+    | WebSearchToolResultBlockParam
+    | BetaCodeExecutionToolResultBlockParam
+    | BetaBashCodeExecutionToolResultBlockParam
+    | BetaTextEditorCodeExecutionToolResultBlockParam
+    | BetaRequestMCPToolResultBlockParam
+    | BetaToolSearchToolResultBlockParam,
   toolUse: any | undefined,
 ): ToolUpdate {
   switch (toolUse?.name) {
     case "Read":
-    case toolNames.read:
+    case acpToolNames.read:
       if (Array.isArray(toolResult.content) && toolResult.content.length > 0) {
         return {
           content: toolResult.content.map((content: any) => ({
@@ -419,13 +472,18 @@ export function toolUpdateFromToolResult(
       }
       return {};
 
-    case toolNames.bash:
+    case acpToolNames.bash:
     case "edit":
     case "Edit":
-    case toolNames.edit:
-    case toolNames.write:
+    case acpToolNames.edit:
+    case acpToolNames.write:
     case "Write": {
-      if (toolResult.is_error && toolResult.content && 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, true);
       }
@@ -451,7 +509,10 @@ export function toolUpdateFromToolResult(
     case "WebSearch":
     case "Other":
     default: {
-      return toAcpContentUpdate(toolResult.content, toolResult.is_error);
+      return toAcpContentUpdate(
+        toolResult.content,
+        "is_error" in toolResult ? toolResult.is_error : false,
+      );
     }
   }
 }
@@ -512,3 +573,100 @@ 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 };
+  };
+
+/**
+ * Creates a PreToolUse hook that checks permissions using the SettingsManager.
+ * This runs before the SDK's built-in permission rules, allowing us to enforce
+ * our own permission settings for ACP-prefixed tools.
+ */
+export const createPreToolUseHook =
+  (settingsManager: SettingsManager, logger: Logger = console): HookCallback =>
+  async (input: any, _toolUseID: string | undefined) => {
+    if (input.hook_event_name !== "PreToolUse") {
+      return { continue: true };
+    }
+
+    const toolName = input.tool_name;
+    const toolInput = input.tool_input;
+
+    const permissionCheck = settingsManager.checkPermission(toolName, toolInput);
+
+    if (permissionCheck.decision !== "ask") {
+      logger.log(
+        `[PreToolUseHook] Tool: ${toolName}, Decision: ${permissionCheck.decision}, Rule: ${permissionCheck.rule}`,
+      );
+    }
+
+    switch (permissionCheck.decision) {
+      case "allow":
+        return {
+          continue: true,
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse" as const,
+            permissionDecision: "allow" as const,
+            permissionDecisionReason: `Allowed by settings rule: ${permissionCheck.rule}`,
+          },
+        };
+
+      case "deny":
+        return {
+          continue: true,
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse" as const,
+            permissionDecision: "deny" as const,
+            permissionDecisionReason: `Denied by settings rule: ${permissionCheck.rule}`,
+          },
+        };
+
+      case "ask":
+      default:
+        // Let the normal permission flow continue
+        return { continue: true };
+    }
+  };

src/utils.ts

@@ -3,7 +3,8 @@
 import { Readable, Writable } from "node:stream";
 import { WritableStream, ReadableStream } from "node:stream/web";
 import { readFileSync } from "node:fs";
-import { platform } from "node:os";
+import { Logger } from "./acp-agent.js";
+import { ClaudeCodeSettings, getManagedSettingsPath } from "./settings.js";
 
 // Useful for bridging push-based and async-iterator-based code.
 export class Pushable<T> implements AsyncIterable<T> {
@@ -75,47 +76,29 @@ 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 {
+export function loadManagedSettings(): ClaudeCodeSettings | null {
   try {
-    return JSON.parse(readFileSync(getManagedSettingsPath(), "utf8")) as ManagedSettings;
+    return JSON.parse(readFileSync(getManagedSettingsPath(), "utf8")) as ClaudeCodeSettings;
   } catch {
     return null;
   }
 }
 
-export function applyEnvironmentSettings(settings: ManagedSettings): void {
+export function applyEnvironmentSettings(settings: ClaudeCodeSettings): void {
   if (settings.env) {
     for (const [key, value] of Object.entries(settings.env)) {
       process.env[key] = value;