Prep 0.21.0 release (#399)

## Summary

- Pass through `_meta.claudeCode.options.tools` to the Claude Agent SDK
instead of hard-coding `{ type: "preset", preset: "claude_code" }`
- Reimplement `disableBuiltInTools` as `tools: []` instead of pushing 14
tool names into `disallowedTools`
- Explicit `tools` array takes precedence over `disableBuiltInTools`

## Problem

The ACP adapter hard-coded `tools: { type: "preset", preset:
"claude_code" }`, ignoring any value the caller provided via
`_meta.claudeCode.options.tools`. This caused two problems:

1. **Wasted context tokens** — All ~15 tool schemas were always sent to
the model, even when the caller only needed a subset (e.g., Read and
Glob for a review-only workflow) or none at all (MCP-only sessions).

2. **Rejected tool call round trips** — When `disableBuiltInTools: true`
was used, the tools were still registered in the model's context (the
flag only added them to `disallowedTools`). The model would see the tool
schemas, attempt to call them, get rejected, and waste a round trip.

Additionally, the existing `disableBuiltInTools` flag maintained a
hard-coded list of 14 tool names to blocklist. If the SDK added a new
built-in tool, `disableBuiltInTools` wouldn't cover it — the new tool
would leak through.

## SDK Contract Validation

The `tools` option is documented in the [Claude Agent SDK TypeScript
reference](https://platform.claude.com/docs/en/agent-sdk/typescript) as:

```typescript
tools?: string[] | { type: 'preset'; preset: 'claude_code' };
```

> Tool configuration. Pass an array of tool names or use the preset to
get Claude Code's default tools.

The type `string[]` includes `[]` (empty array) with no minimum length
constraint. Passing an empty array to disable all built-in tools is a
valid use of the SDK contract, not a workaround.

## Changes

### `src/acp-agent.ts`

**One line of behavioral change** — the `tools` field now uses the
caller-provided value if present, falling back to the preset:

```typescript
tools: userProvidedOptions?.tools ?? { type: "preset", preset: "claude_code" },
```

**`disableBuiltInTools` reimplemented** — instead of pushing 14 tool
names into `disallowedTools`, it resolves to `tools: []`:

```typescript
const resolvedTools: Options["tools"] =
  userProvidedOptions?.tools ??
  (params._meta?.disableBuiltInTools === true
    ? []
    : { type: "preset", preset: "claude_code" });
```

Resolution priority:
```
_meta.claudeCode.options.tools  →  use it (explicit whitelist)
_meta.disableBuiltInTools: true →  tools: [] (legacy shorthand)
neither                         →  { type: "preset", preset: "claude_code" } (default)
```

### `src/tests/create-session-options.test.ts`

4 new tests + 1 updated test:

| Test | Verifies |
|------|----------|
| `defaults tools to claude_code preset when not provided` | Backward
compatibility — no `tools` = full preset |
| `passes through user-provided tools string array` | Whitelist:
`["Read", "Glob"]` arrives as-is |
| `passes through empty tools array to disable all built-in tools` |
`tools: []` disables everything |
| `explicit tools array takes precedence over disableBuiltInTools` |
Resolution priority: explicit `tools` wins over `disableBuiltInTools` |
| `sets tools to empty array when disableBuiltInTools is true` | Legacy
flag now produces `tools: []` instead of blocklist |

## Usage Examples

```typescript
// Review-only session: model can only read files
_meta: { claudeCode: { options: { tools: ["Read", "Glob"] } } }

// MCP-only session: no built-in tools
_meta: { claudeCode: { options: { tools: [] } } }

// Legacy: still works, now equivalent to tools: []
_meta: { disableBuiltInTools: true }
```

## Non-breaking

Callers that don't provide `tools` get identical behavior (full
`claude_code` preset). `disableBuiltInTools: true` still works but is
now a less flexible alias for `tools: []`.

## Test plan

- [x] All existing tests pass (`npm test` — 131 tests, 126 passed, 5
skipped)
- [x] New tests cover: default preset, explicit array, empty array,
precedence over `disableBuiltInTools`
- [x] Verified `tools` type against [official SDK
docs](https://platform.claude.com/docs/en/agent-sdk/typescript)

---------

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

.github/workflows/publish.yml

@@ -54,7 +54,7 @@ jobs:
 
       - name: Build binary
         run: |
-          bun build src/static-entry.ts \
+          bun build src/index.ts \
             --compile \
             --target ${{ matrix.target }} \
             --define 'process.env.CLAUDE_AGENT_ACP_IS_SINGLE_FILE_BUN="true"' \

.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.agent-shell

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.21.0
+
+- Update to claude-agent-sdk 0.2.71
+- show project-relative paths in tool call titles
+- Lib: pass through tools array to control built-in tool availability
+- fix: skip user replay
+- fix: handle renamed Agent tool in toolInfoFromToolUse
+
+## 0.20.2
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.68
+
+## 0.20.1
+
+- fix: inherit process.env when spawning agent subprocess
+
+## 0.20.0
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.63
+- Respect user settings for permission mode and model selection
+- Better handling of concurrent prompts
+- Support --cli for node as well
+- Propagate max_tokens stop reason instead of throwing internal error
+- fix: throw resourceNotFound when loadSession fails to resume
+- fix: add missing zod dependency
+- Surface better error message when Claude Code process exits unexpectedly
+
 ## 0.19.2
 
 - Fix for broken notifications when reloading session messages

package-lock.json

@@ -1,29 +1,31 @@
 {
   "name": "@zed-industries/claude-agent-acp",
-  "version": "0.19.2",
+  "version": "0.21.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@zed-industries/claude-agent-acp",
-      "version": "0.19.2",
+      "version": "0.21.0",
       "license": "Apache-2.0",
       "dependencies": {
-        "@agentclientprotocol/sdk": "0.14.1",
-        "@anthropic-ai/claude-agent-sdk": "0.2.62"
+        "@agentclientprotocol/sdk": "0.15.0",
+        "@anthropic-ai/claude-agent-sdk": "0.2.71",
+        "zod": "^3.25.0 || ^4.0.0"
       },
       "bin": {
         "claude-agent-acp": "dist/index.js"
       },
       "devDependencies": {
+        "@anthropic-ai/claude-code": "2.1.71",
         "@anthropic-ai/sdk": "0.78.0",
         "@eslint/js": "10.0.1",
-        "@types/node": "25.3.2",
+        "@types/node": "25.3.5",
         "@typescript-eslint/eslint-plugin": "8.56.1",
         "@typescript-eslint/parser": "8.56.1",
-        "eslint": "10.0.2",
+        "eslint": "10.0.3",
         "eslint-config-prettier": "10.1.8",
-        "globals": "17.3.0",
+        "globals": "17.4.0",
         "prettier": "3.8.1",
         "ts-node": "10.9.2",
         "typescript": "5.9.3",
@@ -31,18 +33,18 @@
       }
     },
     "node_modules/@agentclientprotocol/sdk": {
-      "version": "0.14.1",
-      "resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-0.14.1.tgz",
-      "integrity": "sha512-b6r3PS3Nly+Wyw9U+0nOr47bV8tfS476EgyEMhoKvJCZLbgqoDFN7DJwkxL88RR0aiOqOYV1ZnESHqb+RmdH8w==",
+      "version": "0.15.0",
+      "resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-0.15.0.tgz",
+      "integrity": "sha512-TH4utu23Ix8ec34srBHmDD4p3HI0cYleS1jN9lghRczPfhFlMBNrQgZWeBBe12DWy27L11eIrtciY2MXFSEiDg==",
       "license": "Apache-2.0",
       "peerDependencies": {
         "zod": "^3.25.0 || ^4.0.0"
       }
     },
     "node_modules/@anthropic-ai/claude-agent-sdk": {
-      "version": "0.2.62",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.2.62.tgz",
-      "integrity": "sha512-exRJ2djKP6erRpUrtnVf5iXzqeS9dAie9d1ghODZVVXdLqieSqCpaAhZhe0hL1yvP33OL0J5CgT9RAyPzhYY9A==",
+      "version": "0.2.71",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.2.71.tgz",
+      "integrity": "sha512-pIsQJnM7Y+cJHL7aFY6SCCW3FIni218gVEpPqG8XGowfYxboFNBbNssWiUNRwthT8bp9jypcX7q5kx0Xsw14xg==",
       "license": "SEE LICENSE IN README.md",
       "engines": {
         "node": ">=18.0.0"
@@ -62,6 +64,30 @@
         "zod": "^4.0.0"
       }
     },
+    "node_modules/@anthropic-ai/claude-code": {
+      "version": "2.1.71",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-2.1.71.tgz",
+      "integrity": "sha512-DHvvzMifwmLnnUlR3cZ//Y8VjGmZxvs6+uJmiI1B0jewQykfI5dT9tfK1sdLfHj8ukofu2lx93/CzamqDInDxg==",
+      "dev": true,
+      "license": "SEE LICENSE IN README.md",
+      "bin": {
+        "claude": "cli.js"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "@img/sharp-darwin-arm64": "^0.34.2",
+        "@img/sharp-darwin-x64": "^0.34.2",
+        "@img/sharp-linux-arm": "^0.34.2",
+        "@img/sharp-linux-arm64": "^0.34.2",
+        "@img/sharp-linux-x64": "^0.34.2",
+        "@img/sharp-linuxmusl-arm64": "^0.34.2",
+        "@img/sharp-linuxmusl-x64": "^0.34.2",
+        "@img/sharp-win32-arm64": "^0.34.2",
+        "@img/sharp-win32-x64": "^0.34.2"
+      }
+    },
     "node_modules/@anthropic-ai/sdk": {
       "version": "0.78.0",
       "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.78.0.tgz",
@@ -578,37 +604,37 @@
       }
     },
     "node_modules/@eslint/config-array": {
-      "version": "0.23.2",
-      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.23.2.tgz",
-      "integrity": "sha512-YF+fE6LV4v5MGWRGj7G404/OZzGNepVF8fxk7jqmqo3lrza7a0uUcDnROGRBG1WFC1omYUS/Wp1f42i0M+3Q3A==",
+      "version": "0.23.3",
+      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.23.3.tgz",
+      "integrity": "sha512-j+eEWmB6YYLwcNOdlwQ6L2OsptI/LO6lNBuLIqe5R7RetD658HLoF+Mn7LzYmAWWNNzdC6cqP+L6r8ujeYXWLw==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "@eslint/object-schema": "^3.0.2",
+        "@eslint/object-schema": "^3.0.3",
         "debug": "^4.3.1",
-        "minimatch": "^10.2.1"
+        "minimatch": "^10.2.4"
       },
       "engines": {
         "node": "^20.19.0 || ^22.13.0 || >=24"
       }
     },
     "node_modules/@eslint/config-helpers": {
-      "version": "0.5.2",
-      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.5.2.tgz",
-      "integrity": "sha512-a5MxrdDXEvqnIq+LisyCX6tQMPF/dSJpCfBgBauY+pNZ28yCtSsTvyTYrMhaI+LK26bVyCJfJkT0u8KIj2i1dQ==",
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.5.3.tgz",
+      "integrity": "sha512-lzGN0onllOZCGroKJmRwY6QcEHxbjBw1gwB8SgRSqK8YbbtEXMvKynsXc3553ckIEBxsbMBU7oOZXKIPGZNeZw==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "@eslint/core": "^1.1.0"
+        "@eslint/core": "^1.1.1"
       },
       "engines": {
         "node": "^20.19.0 || ^22.13.0 || >=24"
       }
     },
     "node_modules/@eslint/core": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-1.1.0.tgz",
-      "integrity": "sha512-/nr9K9wkr3P1EzFTdFdMoLuo1PmIxjmwvPozwoSodjNBdefGujXQUF93u1DDZpEaTuDvMsIQddsd35BwtrW9Xw==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-1.1.1.tgz",
+      "integrity": "sha512-QUPblTtE51/7/Zhfv8BDwO0qkkzQL7P/aWWbqcf4xWLEYn1oKjdO0gglQBB4GAsu7u6wjijbCmzsUTy6mnk6oQ==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
@@ -640,9 +666,9 @@
       }
     },
     "node_modules/@eslint/object-schema": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-3.0.2.tgz",
-      "integrity": "sha512-HOy56KJt48Bx8KmJ+XGQNSUMT/6dZee/M54XyUyuvTvPXJmsERRvBchsUVx1UMe1WwIH49XLAczNC7V2INsuUw==",
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-3.0.3.tgz",
+      "integrity": "sha512-iM869Pugn9Nsxbh/YHRqYiqd23AmIbxJOcpUMOuWCVNdoQJ5ZtwL6h3t0bcZzJUlC3Dq9jCFCESBZnX0GTv7iQ==",
       "dev": true,
       "license": "Apache-2.0",
       "engines": {
@@ -650,13 +676,13 @@
       }
     },
     "node_modules/@eslint/plugin-kit": {
-      "version": "0.6.0",
-      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.6.0.tgz",
-      "integrity": "sha512-bIZEUzOI1jkhviX2cp5vNyXQc6olzb2ohewQubuYlMXZ2Q/XjBO0x0XhGPvc9fjSIiUN0vw+0hq53BJ4eQSJKQ==",
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.6.1.tgz",
+      "integrity": "sha512-iH1B076HoAshH1mLpHMgwdGeTs0CYwL0SPMkGuSebZrwBp16v415e9NZXg2jtrqPVQjf6IANe2Vtlr5KswtcZQ==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "@eslint/core": "^1.1.0",
+        "@eslint/core": "^1.1.1",
         "levn": "^0.4.1"
       },
       "engines": {
@@ -1472,9 +1498,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "25.3.2",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.2.tgz",
-      "integrity": "sha512-RpV6r/ij22zRRdyBPcxDeKAzH43phWVKEjL2iksqo1Vz3CuBUrgmPpPhALKiRfU7OMCmeeO9vECBMsV0hMTG8Q==",
+      "version": "25.3.5",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.5.tgz",
+      "integrity": "sha512-oX8xrhvpiyRCQkG1MFchB09f+cXftgIXb3a7UUa4Y3wpmZPw5tyZGTLWhlESOLq1Rq6oDlc8npVU2/9xiCuXMA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2048,18 +2074,18 @@
       }
     },
     "node_modules/eslint": {
-      "version": "10.0.2",
-      "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.0.2.tgz",
-      "integrity": "sha512-uYixubwmqJZH+KLVYIVKY1JQt7tysXhtj21WSvjcSmU5SVNzMus1bgLe+pAt816yQ8opKfheVVoPLqvVMGejYw==",
+      "version": "10.0.3",
+      "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.0.3.tgz",
+      "integrity": "sha512-COV33RzXZkqhG9P2rZCFl9ZmJ7WL+gQSCRzE7RhkbclbQPtLAWReL7ysA0Sh4c8Im2U9ynybdR56PV0XcKvqaQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.2",
-        "@eslint/config-array": "^0.23.2",
+        "@eslint/config-array": "^0.23.3",
         "@eslint/config-helpers": "^0.5.2",
-        "@eslint/core": "^1.1.0",
-        "@eslint/plugin-kit": "^0.6.0",
+        "@eslint/core": "^1.1.1",
+        "@eslint/plugin-kit": "^0.6.1",
         "@humanfs/node": "^0.16.6",
         "@humanwhocodes/module-importer": "^1.0.1",
         "@humanwhocodes/retry": "^0.4.2",
@@ -2068,7 +2094,7 @@
         "cross-spawn": "^7.0.6",
         "debug": "^4.3.2",
         "escape-string-regexp": "^4.0.0",
-        "eslint-scope": "^9.1.1",
+        "eslint-scope": "^9.1.2",
         "eslint-visitor-keys": "^5.0.1",
         "espree": "^11.1.1",
         "esquery": "^1.7.0",
@@ -2081,7 +2107,7 @@
         "imurmurhash": "^0.1.4",
         "is-glob": "^4.0.0",
         "json-stable-stringify-without-jsonify": "^1.0.1",
-        "minimatch": "^10.2.1",
+        "minimatch": "^10.2.4",
         "natural-compare": "^1.4.0",
         "optionator": "^0.9.3"
       },
@@ -2120,9 +2146,9 @@
       }
     },
     "node_modules/eslint-scope": {
-      "version": "9.1.1",
-      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-9.1.1.tgz",
-      "integrity": "sha512-GaUN0sWim5qc8KVErfPBWmc31LEsOkrUJbvJZV+xuL3u2phMUK4HIvXlWAakfC8W4nzlK+chPEAkYOYb5ZScIw==",
+      "version": "9.1.2",
+      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-9.1.2.tgz",
+      "integrity": "sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ==",
       "dev": true,
       "license": "BSD-2-Clause",
       "dependencies": {
@@ -2175,9 +2201,9 @@
       }
     },
     "node_modules/espree": {
-      "version": "11.1.1",
-      "resolved": "https://registry.npmjs.org/espree/-/espree-11.1.1.tgz",
-      "integrity": "sha512-AVHPqQoZYc+RUM4/3Ly5udlZY/U4LS8pIG05jEjWM2lQMU/oaZ7qshzAl2YP1tfNmXfftH3ohurfwNAug+MnsQ==",
+      "version": "11.2.0",
+      "resolved": "https://registry.npmjs.org/espree/-/espree-11.2.0.tgz",
+      "integrity": "sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw==",
       "dev": true,
       "license": "BSD-2-Clause",
       "dependencies": {
@@ -2355,9 +2381,9 @@
       }
     },
     "node_modules/flatted": {
-      "version": "3.3.3",
-      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz",
-      "integrity": "sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==",
+      "version": "3.4.1",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.1.tgz",
+      "integrity": "sha512-IxfVbRFVlV8V/yRaGzk0UVIcsKKHMSfYw66T/u4nTwlWteQePsxe//LjudR1AMX4tZW3WFCh3Zqa/sjlqpbURQ==",
       "dev": true,
       "license": "ISC"
     },
@@ -2390,9 +2416,9 @@
       }
     },
     "node_modules/globals": {
-      "version": "17.3.0",
-      "resolved": "https://registry.npmjs.org/globals/-/globals-17.3.0.tgz",
-      "integrity": "sha512-yMqGUQVVCkD4tqjOJf3TnrvaaHDMYp4VlUSObbkIiuCPe/ofdMBFIAcBbCSRFWOnos6qRiTVStDwqPLUclaxIw==",
+      "version": "17.4.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-17.4.0.tgz",
+      "integrity": "sha512-hjrNztw/VajQwOLsMNT1cbJiH2muO3OROCHnbehc8eY5JyD2gqz4AcMHPqgaOR59DjgUjYAYLeH699g/eWi2jw==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -2702,9 +2728,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.6",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
-      "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
+      "version": "8.5.8",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz",
+      "integrity": "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==",
       "dev": true,
       "funding": [
         {
@@ -3261,7 +3287,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
       "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.19.2",
+  "version": "0.21.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -60,18 +60,20 @@
   "author": "Zed Industries",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.14.1",
-    "@anthropic-ai/claude-agent-sdk": "0.2.62"
+    "@agentclientprotocol/sdk": "0.15.0",
+    "@anthropic-ai/claude-agent-sdk": "0.2.71",
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-code": "2.1.71",
     "@anthropic-ai/sdk": "0.78.0",
     "@eslint/js": "10.0.1",
-    "@types/node": "25.3.2",
+    "@types/node": "25.3.5",
     "@typescript-eslint/eslint-plugin": "8.56.1",
     "@typescript-eslint/parser": "8.56.1",
-    "eslint": "10.0.2",
+    "eslint": "10.0.3",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.3.0",
+    "globals": "17.4.0",
     "prettier": "3.8.1",
     "ts-node": "10.9.2",
     "typescript": "5.9.3",

src/index.ts

@@ -2,25 +2,30 @@
 
 // Load managed settings and apply environment variables
 import { loadManagedSettings, applyEnvironmentSettings } from "./utils.js";
+import { claudeCliPath, runAcp } from "./acp-agent.js";
 
-const managedSettings = loadManagedSettings();
-if (managedSettings) {
-  applyEnvironmentSettings(managedSettings);
+if (process.argv.includes("--cli")) {
+  process.argv = process.argv.filter((arg) => arg !== "--cli");
+  await import(await claudeCliPath());
+} else {
+  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;
+  console.info = console.error;
+  console.warn = console.error;
+  console.debug = console.error;
+
+  process.on("unhandledRejection", (reason, promise) => {
+    console.error("Unhandled Rejection at:", promise, "reason:", reason);
+  });
+
+  runAcp();
+
+  // Keep process alive
+  process.stdin.resume();
 }
-
-// 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;
-console.info = console.error;
-console.warn = console.error;
-console.debug = console.error;
-
-process.on("unhandledRejection", (reason, promise) => {
-  console.error("Unhandled Rejection at:", promise, "reason:", reason);
-});
-
-import { runAcp } from "./acp-agent.js";
-runAcp();
-
-// Keep process alive
-process.stdin.resume();

src/lib.ts

@@ -15,7 +15,12 @@ export {
   Pushable,
   unreachable,
 } from "./utils.js";
-export { toolInfoFromToolUse, planEntries, toolUpdateFromToolResult } from "./tools.js";
+export {
+  toolInfoFromToolUse,
+  toDisplayPath,
+  planEntries,
+  toolUpdateFromToolResult,
+} from "./tools.js";
 export {
   SettingsManager,
   type ClaudeCodeSettings,

src/settings.ts

@@ -14,7 +14,12 @@ import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
  * Docs: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
  */
 
+export interface PermissionSettings {
+  defaultMode?: string;
+}
+
 export interface ClaudeCodeSettings {
+  permissions?: PermissionSettings;
   env?: Record<string, string>;
   model?: string;
 }
@@ -162,6 +167,13 @@ export class SettingsManager {
       if (settings.model) {
         merged.model = settings.model;
       }
+
+      if (settings.permissions?.defaultMode !== undefined) {
+        merged.permissions = {
+          ...merged.permissions,
+          defaultMode: settings.permissions.defaultMode,
+        };
+      }
     }
 
     this.mergedSettings = merged;

src/static-entry.ts

@@ -1,7 +0,0 @@
-if (process.argv.includes("--cli")) {
-  process.argv = process.argv.filter((arg) => arg !== "--cli");
-  // @ts-expect-error -- no types
-  await import("@anthropic-ai/claude-agent-sdk/cli.js");
-} else {
-  await import("./index.js");
-}

src/tests/acp-agent-settings.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { AgentSideConnection } from "@agentclientprotocol/sdk";
+import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+
+const { querySpy } = vi.hoisted(() => ({
+  querySpy: vi.fn(),
+}));
+
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
+  const actual = await vi.importActual<any>("@anthropic-ai/claude-agent-sdk");
+  return {
+    ...actual,
+    query: querySpy,
+  };
+});
+
+describe("ClaudeAcpAgent settings", () => {
+  let tempDir: string;
+  let originalClaudeConfigDir: string | undefined;
+
+  function createMockClient(): AgentSideConnection {
+    return {
+      sessionUpdate: async () => {},
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AgentSideConnection;
+  }
+
+  function mockQuery() {
+    let capturedOptions: any;
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(({ options }: any) => {
+      capturedOptions = options;
+      return {
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "claude-sonnet-4-5",
+              displayName: "Claude Sonnet 4.5",
+              description: "Default",
+            },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+    return { getCapturedOptions: () => capturedOptions, setModelSpy };
+  }
+
+  beforeEach(async () => {
+    tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "acp-agent-settings-"));
+    originalClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = tempDir;
+    querySpy.mockReset();
+    vi.resetModules();
+  });
+
+  afterEach(async () => {
+    if (originalClaudeConfigDir) {
+      process.env.CLAUDE_CONFIG_DIR = originalClaudeConfigDir;
+    } else {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    }
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("uses permissions.defaultMode for new sessions", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        permissions: {
+          defaultMode: "dontAsk",
+        },
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { getCapturedOptions } = mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(getCapturedOptions().permissionMode).toBe("dontAsk");
+    expect(getCapturedOptions().settingSources).toEqual(["user", "project", "local"]);
+    expect(response.modes.currentModeId).toBe("dontAsk");
+  });
+
+  it("supports acceptEdits mode defaults", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        permissions: {
+          defaultMode: "acceptEdits",
+        },
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { getCapturedOptions } = mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(getCapturedOptions().permissionMode).toBe("acceptEdits");
+    expect(response.modes.currentModeId).toBe("acceptEdits");
+  });
+
+  it("defaults to 'default' when no permissions.defaultMode is set", async () => {
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { getCapturedOptions } = mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(getCapturedOptions().permissionMode).toBe("default");
+    expect(response.modes.currentModeId).toBe("default");
+  });
+
+  it("throws when permissions.defaultMode is not a string", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        permissions: {
+          defaultMode: 123,
+        },
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    await expect(
+      (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      }),
+    ).rejects.toThrow("Invalid permissions.defaultMode");
+  });
+
+  it("resolves model aliases like opus[1m] to the correct model", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        model: "opus[1m]",
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(({ options: _options }: any) => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "claude-opus-4-6",
+              displayName: "Claude Opus 4.6",
+              description: "Base",
+            },
+            {
+              value: "claude-opus-4-6-1m",
+              displayName: "Claude Opus 4.6 (1M)",
+              description: "Long context",
+            },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(setModelSpy).toHaveBeenCalledWith("claude-opus-4-6-1m");
+    expect(response.models.currentModelId).toBe("claude-opus-4-6-1m");
+  });
+});

src/tests/acp-agent.test.ts

@@ -20,10 +20,12 @@ import { nodeToWebWritable, nodeToWebReadable } from "../utils.js";
 import {
   markdownEscape,
   toolInfoFromToolUse,
+  toDisplayPath,
   toolUpdateFromToolResult,
   toolUpdateFromEditToolResponse,
 } from "../tools.js";
-import { toAcpNotifications, promptToClaude } from "../acp-agent.js";
+import { toAcpNotifications, promptToClaude, ClaudeAcpAgent, claudeCliPath } from "../acp-agent.js";
+import { Pushable } from "../utils.js";
 import { query, SDKAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
 import { randomUUID } from "crypto";
 import type {
@@ -226,7 +228,7 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
       sessionId: newSessionResponse.sessionId,
     });
 
-    expect(client.takeReceivedText()).toBe("");
+    expect(client.takeReceivedText()).toBe("Compacting...\n\nCompacting completed.");
 
     // Send something
     await connection.prompt({
@@ -247,7 +249,7 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
       sessionId: newSessionResponse.sessionId,
     });
 
-    expect(client.takeReceivedText()).toContain("");
+    expect(client.takeReceivedText()).toContain("Compacting...\n\nCompacting completed.");
   }, 30000);
 });
 
@@ -562,6 +564,20 @@ describe("tool conversions", () => {
     });
   });
 
+  it("should use relative path in title when cwd is provided", () => {
+    const tool_use = {
+      type: "tool_use",
+      id: "toolu_01READ_CWD",
+      name: "Read",
+      input: { file_path: "/Users/test/project/src/main.ts" },
+    };
+
+    const result = toolInfoFromToolUse(tool_use, false, "/Users/test/project");
+    expect(result.title).toBe("Read src/main.ts");
+    // locations.path stays absolute for navigation
+    expect(result.locations).toStrictEqual([{ path: "/Users/test/project/src/main.ts", line: 1 }]);
+  });
+
   it("should handle plan entries", () => {
     const received: SDKAssistantMessage = {
       type: "assistant",
@@ -968,6 +984,22 @@ describe("tool conversions", () => {
   });
 });
 
+describe("toDisplayPath", () => {
+  it("should relativize paths inside cwd and keep absolute paths outside", () => {
+    expect(toDisplayPath("/Users/test/project/src/main.ts", "/Users/test/project")).toBe(
+      "src/main.ts",
+    );
+    expect(toDisplayPath("/etc/hosts", "/Users/test/project")).toBe("/etc/hosts");
+    expect(toDisplayPath("/Users/test/project/src/main.ts")).toBe(
+      "/Users/test/project/src/main.ts",
+    );
+    // Partial directory name match should not be treated as inside cwd
+    expect(toDisplayPath("/Users/test/project-other/file.ts", "/Users/test/project")).toBe(
+      "/Users/test/project-other/file.ts",
+    );
+  });
+});
+
 describe("toolUpdateFromEditToolResponse", () => {
   it("should return empty for non-object input", () => {
     expect(toolUpdateFromEditToolResponse(null)).toEqual({});
@@ -1139,6 +1171,11 @@ describe("prompt conversion", () => {
 });
 
 describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("SDK behavior", () => {
+  it("finds vendored cli path", async () => {
+    const path = await claudeCliPath();
+    expect(path).toContain("@anthropic-ai/claude-agent-sdk/cli.js");
+  });
+
   it("query has a 'default' model", async () => {
     const q = query({ prompt: "hi" });
     const models = await q.supportedModels();
@@ -1228,3 +1265,154 @@ describe("permission requests", () => {
     }
   });
 });
+
+describe("stop reason propagation", () => {
+  function createMockAgent() {
+    const mockClient = {
+      sessionUpdate: async () => {},
+    } as unknown as AgentSideConnection;
+    return new ClaudeAcpAgent(mockClient, { log: () => {}, error: () => {} });
+  }
+
+  function createResultMessage(overrides: {
+    subtype: "success" | "error_during_execution";
+    stop_reason: string | null;
+    is_error: boolean;
+    result?: string;
+    errors?: string[];
+  }) {
+    return {
+      type: "result" as const,
+      subtype: overrides.subtype,
+      stop_reason: overrides.stop_reason,
+      is_error: overrides.is_error,
+      result: overrides.result ?? "",
+      errors: overrides.errors ?? [],
+      duration_ms: 0,
+      duration_api_ms: 0,
+      num_turns: 1,
+      total_cost_usd: 0,
+      usage: {
+        input_tokens: 10,
+        output_tokens: 5,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+      modelUsage: {},
+      permission_denials: [],
+      uuid: randomUUID(),
+      session_id: "test-session",
+    };
+  }
+
+  function* messageGenerator(messages: any[]) {
+    yield* messages;
+  }
+
+  function injectSession(agent: ClaudeAcpAgent, messages: any[]) {
+    const gen = messageGenerator(messages);
+    agent.sessions["test-session"] = {
+      query: gen as any,
+      input: new Pushable(),
+      cancelled: false,
+      cwd: "/test",
+      permissionMode: "default",
+      settingsManager: {} as any,
+      accumulatedUsage: {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedReadTokens: 0,
+        cachedWriteTokens: 0,
+      },
+      configOptions: [],
+      promptRunning: false,
+      pendingMessages: new Map(),
+      nextPendingOrder: 0,
+    };
+  }
+
+  it("should return max_tokens when success result has stop_reason max_tokens", async () => {
+    const agent = createMockAgent();
+    injectSession(agent, [
+      createResultMessage({ subtype: "success", stop_reason: "max_tokens", is_error: false }),
+    ]);
+
+    const response = await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "test" }],
+    });
+
+    expect(response.stopReason).toBe("max_tokens");
+  });
+
+  it("should return max_tokens when success result has stop_reason max_tokens and is_error true", async () => {
+    const agent = createMockAgent();
+    injectSession(agent, [
+      createResultMessage({
+        subtype: "success",
+        stop_reason: "max_tokens",
+        is_error: true,
+        result: "Token limit reached",
+      }),
+    ]);
+
+    const response = await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "test" }],
+    });
+
+    expect(response.stopReason).toBe("max_tokens");
+  });
+
+  it("should return max_tokens when error_during_execution has stop_reason max_tokens", async () => {
+    const agent = createMockAgent();
+    injectSession(agent, [
+      createResultMessage({
+        subtype: "error_during_execution",
+        stop_reason: "max_tokens",
+        is_error: true,
+        errors: ["some error"],
+      }),
+    ]);
+
+    const response = await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "test" }],
+    });
+
+    expect(response.stopReason).toBe("max_tokens");
+  });
+
+  it("should return end_turn for success with null stop_reason", async () => {
+    const agent = createMockAgent();
+    injectSession(agent, [
+      createResultMessage({ subtype: "success", stop_reason: null, is_error: false }),
+    ]);
+
+    const response = await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "test" }],
+    });
+
+    expect(response.stopReason).toBe("end_turn");
+  });
+
+  it("should throw internal error for success with is_error true and no max_tokens", async () => {
+    const agent = createMockAgent();
+    injectSession(agent, [
+      createResultMessage({
+        subtype: "success",
+        stop_reason: "end_turn",
+        is_error: true,
+        result: "Something went wrong",
+      }),
+    ]);
+
+    await expect(
+      agent.prompt({
+        sessionId: "test-session",
+        prompt: [{ type: "text", text: "test" }],
+      }),
+    ).rejects.toThrow("Internal error");
+  });
+});

src/tests/authorization.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, Mock, vi, afterEach, beforeEach } from "vitest";
+import { ClaudeAcpAgent } from "../acp-agent.js";
+import { AgentSideConnection } from "@agentclientprotocol/sdk";
+
+describe("authorization", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    //await all pending events like
+    vi.runAllTimers();
+    vi.useRealTimers();
+
+    vi.unstubAllGlobals();
+    vi.resetAllMocks();
+  });
+
+  async function createAgentMock(): Promise<[ClaudeAcpAgent, Mock]> {
+    const mockQuery = vi.hoisted(() =>
+      vi.fn(() => ({
+        initializationResult: vi.fn().mockResolvedValue({
+          models: [{ value: "id", displayName: "name", description: "description" }],
+        }),
+        setModel: vi.fn(),
+        supportedCommands: vi.fn().mockResolvedValue([]),
+      })),
+    );
+
+    vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+      query: mockQuery,
+    }));
+
+    const connectionMock = {
+      sessionUpdate: async (_: any) => {},
+    } as AgentSideConnection;
+
+    const agent = new ClaudeAcpAgent(connectionMock);
+
+    return [agent, mockQuery];
+  }
+
+  it("gateway auth not offered without capability", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {},
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("gateway auth offered when client advertises auth._meta.gateway capability", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("uses gateway env after gateway auth", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { terminal: true, _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+
+    await agent.authenticate({
+      methodId: "gateway",
+      _meta: { gateway: { baseUrl: "https://gateway.example", headers: { "x-api-key": "test" } } },
+    });
+
+    await agent.newSession({
+      cwd: "testRoot",
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            env: {
+              userEnv: "userEnv",
+            },
+          },
+        },
+      },
+    });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: expect.objectContaining({
+            ANTHROPIC_AUTH_TOKEN: "",
+            ANTHROPIC_BASE_URL: "https://gateway.example",
+            ANTHROPIC_CUSTOM_HEADERS: "x-api-key: test",
+            userEnv: "userEnv",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("hide claude authentication without terminal-auth", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("hide terminal auth even when terminal-auth is set", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        _meta: { "terminal-auth": true },
+      },
+    });
+    expect(initializeResponse.authMethods).toStrictEqual([]);
+  });
+
+  it("show claude authentication", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { auth: { terminal: true } },
+    });
+
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+  });
+});

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

@@ -102,7 +102,7 @@ describe("createSession options merging", () => {
     expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
   });
 
-  it("includes both user and built-in disallowed tools when disableBuiltInTools is true", async () => {
+  it("sets tools to empty array when disableBuiltInTools is true", async () => {
     await agent.newSession({
       cwd: "/test",
       mcpServers: [],
@@ -116,15 +116,11 @@ describe("createSession options merging", () => {
       },
     });
 
-    const disallowed = capturedOptions!.disallowedTools!;
-    // User-provided
-    expect(disallowed).toContain("CustomTool");
-    // ACP internal
-    expect(disallowed).toContain("AskUserQuestion");
-    // Built-in tools disabled by disableBuiltInTools
-    expect(disallowed).toContain("Read");
-    expect(disallowed).toContain("Write");
-    expect(disallowed).toContain("Bash");
+    // disableBuiltInTools removes all built-in tools from context
+    expect(capturedOptions!.tools).toEqual([]);
+    // User-provided and ACP disallowedTools still apply
+    expect(capturedOptions!.disallowedTools).toContain("CustomTool");
+    expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
   });
 
   it("merges user-provided hooks with ACP hooks", async () => {
@@ -151,6 +147,112 @@ describe("createSession options merging", () => {
     expect(capturedOptions!.hooks?.PostToolUse).toHaveLength(2);
   });
 
+  it("inherits HOME and PATH from process.env when no env is provided", async () => {
+    await agent.newSession({
+      cwd: "/test",
+      mcpServers: [],
+    });
+
+    expect(capturedOptions?.env?.HOME).toBe(process.env.HOME);
+    expect(capturedOptions?.env?.PATH).toBe(process.env.PATH);
+  });
+
+  it("merges user-provided env vars on top of process.env", async () => {
+    await agent.newSession({
+      cwd: "/test",
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            env: {
+              CUSTOM_VAR: "custom-value",
+            },
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions?.env?.HOME).toBe(process.env.HOME);
+    expect(capturedOptions?.env?.PATH).toBe(process.env.PATH);
+    expect(capturedOptions?.env?.CUSTOM_VAR).toBe("custom-value");
+  });
+
+  it("allows user-provided env vars to override process.env entries", async () => {
+    await agent.newSession({
+      cwd: "/test",
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            env: {
+              HOME: "/custom/home",
+            },
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions?.env?.HOME).toBe("/custom/home");
+  });
+
+  it("defaults tools to claude_code preset when not provided", async () => {
+    await agent.newSession({
+      cwd: "/test",
+      mcpServers: [],
+    });
+
+    expect(capturedOptions!.tools).toEqual({ type: "preset", preset: "claude_code" });
+  });
+
+  it("passes through user-provided tools string array", async () => {
+    await agent.newSession({
+      cwd: "/test",
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            tools: ["Read", "Glob"],
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions!.tools).toEqual(["Read", "Glob"]);
+  });
+
+  it("explicit tools array takes precedence over disableBuiltInTools", async () => {
+    await agent.newSession({
+      cwd: "/test",
+      mcpServers: [],
+      _meta: {
+        disableBuiltInTools: true,
+        claudeCode: {
+          options: {
+            tools: ["Read", "Glob"],
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions!.tools).toEqual(["Read", "Glob"]);
+  });
+
+  it("passes through empty tools array to disable all built-in tools", async () => {
+    await agent.newSession({
+      cwd: "/test",
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            tools: [],
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions!.tools).toEqual([]);
+  });
+
   it("merges user-provided mcpServers with ACP mcpServers", async () => {
     await agent.newSession({
       cwd: "/test",

src/tests/resolve-permission-mode.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { resolvePermissionMode } from "../acp-agent.js";
+
+describe("resolvePermissionMode", () => {
+  it("returns 'default' when no mode is provided", () => {
+    expect(resolvePermissionMode()).toBe("default");
+    expect(resolvePermissionMode(undefined)).toBe("default");
+  });
+
+  it("resolves exact canonical modes", () => {
+    expect(resolvePermissionMode("default")).toBe("default");
+    expect(resolvePermissionMode("acceptEdits")).toBe("acceptEdits");
+    expect(resolvePermissionMode("dontAsk")).toBe("dontAsk");
+    expect(resolvePermissionMode("plan")).toBe("plan");
+    expect(resolvePermissionMode("bypassPermissions")).toBe("bypassPermissions");
+  });
+
+  it("resolves case-insensitive aliases", () => {
+    expect(resolvePermissionMode("DontAsk")).toBe("dontAsk");
+    expect(resolvePermissionMode("DONTASK")).toBe("dontAsk");
+    expect(resolvePermissionMode("AcceptEdits")).toBe("acceptEdits");
+    expect(resolvePermissionMode("bypass")).toBe("bypassPermissions");
+  });
+
+  it("trims whitespace", () => {
+    expect(resolvePermissionMode("  dontAsk  ")).toBe("dontAsk");
+  });
+
+  it("throws on non-string values", () => {
+    expect(() => resolvePermissionMode(123)).toThrow("expected a string");
+    expect(() => resolvePermissionMode(true)).toThrow("expected a string");
+    expect(() => resolvePermissionMode({})).toThrow("expected a string");
+  });
+
+  it("throws on empty string", () => {
+    expect(() => resolvePermissionMode("")).toThrow("expected a non-empty string");
+    expect(() => resolvePermissionMode("  ")).toThrow("expected a non-empty string");
+  });
+
+  it("throws on unknown mode", () => {
+    expect(() => resolvePermissionMode("yolo")).toThrow("Invalid permissions.defaultMode: yolo");
+  });
+});

src/tests/settings.test.ts

@@ -52,5 +52,42 @@ describe("SettingsManager", () => {
       settings = settingsManager.getSettings();
       expect(settings.model).toBe("claude-3-5-haiku");
     });
+
+    it("should merge permissions.defaultMode with later sources taking precedence", 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: {
+            defaultMode: "dontAsk",
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      let settings = settingsManager.getSettings();
+      expect(settings.permissions?.defaultMode).toBe("dontAsk");
+
+      // Local settings override the mode
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.local.json"),
+        JSON.stringify({
+          permissions: {
+            defaultMode: "plan",
+          },
+        }),
+      );
+
+      settingsManager.dispose();
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      settings = settingsManager.getSettings();
+      expect(settings.permissions?.defaultMode).toBe("plan");
+    });
   });
 });

src/tools.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import {
   ContentBlock,
   PlanEntry,
@@ -74,7 +75,7 @@ import {
   TodoWriteInput,
   WebFetchInput,
   WebSearchInput,
-} from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
+} from "@anthropic-ai/claude-code/sdk-tools.js";
 
 interface ToolInfo {
   title: string;
@@ -103,13 +104,29 @@ interface ToolUpdate {
   };
 }
 
+/**
+ * Convert an absolute file path to a project-relative path for display.
+ * Returns the original path if it's outside the project directory or if no cwd is provided.
+ */
+export function toDisplayPath(filePath: string, cwd?: string): string {
+  if (!cwd) return filePath;
+  const resolvedCwd = path.resolve(cwd);
+  const resolvedFile = path.resolve(filePath);
+  if (resolvedFile.startsWith(resolvedCwd + path.sep) || resolvedFile === resolvedCwd) {
+    return path.relative(resolvedCwd, resolvedFile);
+  }
+  return filePath;
+}
+
 export function toolInfoFromToolUse(
   toolUse: any,
   supportsTerminalOutput: boolean = false,
+  cwd?: string,
 ): ToolInfo {
   const name = toolUse.name;
 
   switch (name) {
+    case "Agent":
     case "Task": {
       const input = toolUse.input as AgentInput | BashInput;
       return {
@@ -153,8 +170,9 @@ export function toolInfoFromToolUse(
       } else if (input.offset) {
         limit = " (from line " + input.offset + ")";
       }
+      const displayPath = input.file_path ? toDisplayPath(input.file_path, cwd) : "File";
       return {
-        title: "Read " + (input.file_path ?? "File") + limit,
+        title: "Read " + displayPath + limit,
         kind: "read",
         locations: input.file_path
           ? [
@@ -188,8 +206,9 @@ export function toolInfoFromToolUse(
           },
         ];
       }
+      const displayPath = input?.file_path ? toDisplayPath(input.file_path, cwd) : undefined;
       return {
-        title: input?.file_path ? `Write ${input.file_path}` : "Write",
+        title: displayPath ? `Write ${displayPath}` : "Write",
         kind: "edit",
         content,
         locations: input?.file_path ? [{ path: input.file_path }] : [],
@@ -209,8 +228,9 @@ export function toolInfoFromToolUse(
           },
         ];
       }
+      const displayPath = input?.file_path ? toDisplayPath(input.file_path, cwd) : undefined;
       return {
-        title: input?.file_path ? `Edit ${input.file_path}` : "Edit",
+        title: displayPath ? `Edit ${displayPath}` : "Edit",
         kind: "edit",
         content,
         locations: input?.file_path ? [{ path: input.file_path }] : [],