Compare commits

...

4 Commits

Author SHA1 Message Date
Ben Brandt
eb4c16f10a fix: keep built-in web-fetch and claude-code-guide agents out of the Agent picker (#1672)
Fixes #1670.

## Problem

The Agent picker is meant to show only when the user has custom agents.
It showed with none, listing `web-fetch` as if it were one.

`supportedAgents()` returns Claude Code's built-in subagents together
with the custom ones, and `AgentInfo` does not say which is which, so
the adapter filters the built-ins by name (`BUILTIN_AGENT_NAMES`).
Claude Code lists two built-ins that the set did not name:

- `web-fetch`: listed where Claude Code's staged rollout turns it on, or
with `CLAUDE_CODE_WEB_FETCH_AGENT=1`.
- `claude-code-guide`: listed where the adapter's environment already
sets `CLAUDE_CODE_ENTRYPOINT`. The SDK sets `sdk-ts` only when the
variable is unset, and Claude Code leaves the agent out for that value.

The roster integration test (`src/tests/agent-discovery.test.ts`) exists
to catch this drift. It did not, because neither agent is in the roster
of an account outside the rollout that runs the test from a plain shell.

## Change

- Add `web-fetch` and `claude-code-guide` to `BUILTIN_AGENT_NAMES`. This
covers v1 and v2: both build the picker from the same set.
- The roster test sets `CLAUDE_CODE_WEB_FETCH_AGENT=1` and its own
`CLAUDE_CODE_ENTRYPOINT`, so the roster it compares against no longer
depends on the account or on the shell.

## Why the list is still hard-coded

The issue asks to derive the built-ins from the SDK. The only SDK
surface that separates them is `getContextUsage().agents`, which lists
the agents that are not built in. Session setup deliberately does not
wait for `getContextUsage` (see `readContextWindow` and the "does not
wait for getContextUsage during session creation" tests), so the picker
cannot be built from it without putting that request back on the
`session/new` and `session/load` path. A built-in behind a future
rollout can therefore still leak until it is added to the set and to the
test.

## Testing

- With CLI 2.1.328 and `CLAUDE_CODE_WEB_FETCH_AGENT=1`,
`supportedAgents()` reports `web-fetch` with no custom agents
configured, as in the issue. With a preset `CLAUDE_CODE_ENTRYPOINT` it
reports `claude-code-guide`.
- Both the roster test and the `discoverCustomAgents` unit test fail on
the old set and pass with the new one.
- `npm run build`, `npm run check`, and the whole suite against the real
CLI (`RUN_INTEGRATION_TESTS=true`): 4406 passed, 9 skipped.
2026-11-19 16:22:29 +01:00
acp-release-bot[bot]
9f1ca6eb9c chore(main): release 0.109.0 (#1665)
🤖 I have created a release *beep* *boop*
---


##
[0.109.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.108.1...v0.109.0)
(2026-11-19)


### Features

* announce session cursors on v2 and fork at a cursor
([#1658](https://github.com/agentclientprotocol/claude-agent-acp/issues/1658))
([5075d2e](5075d2e0df))
* insert one message per idempotencyKey on v2 session/prompt
([#1657](https://github.com/agentclientprotocol/claude-agent-acp/issues/1657))
([1c0792e](1c0792ea8c))
* order config options as model, effort, fast, ultracode, mode, agent
([#1666](https://github.com/agentclientprotocol/claude-agent-acp/issues/1666))
([f31da7f](f31da7f9f5))
* report Fast mode in the speed config option category
([#1659](https://github.com/agentclientprotocol/claude-agent-acp/issues/1659))
([8990c24](8990c2441d))
* send the predicted next prompt as prompt_suggestions_update
([#1660](https://github.com/agentclientprotocol/claude-agent-acp/issues/1660))
([f20ed1d](f20ed1d96a))


### Bug Fixes

* send a session's settings to Claude Code over stdin
([#1669](https://github.com/agentclientprotocol/claude-agent-acp/issues/1669))
([a768a9f](a768a9f50c))
* update to @anthropic-ai/claude-agent-sdk 0.3.328
([#1668](https://github.com/agentclientprotocol/claude-agent-acp/issues/1668))
([6e30711](6e307116d4))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: acp-release-bot[bot] <246668977+acp-release-bot[bot]@users.noreply.github.com>
2026-11-19 14:31:59 +01:00
Ben Brandt
a768a9f50c fix: send a session's settings to Claude Code over stdin (#1669)
## Summary

The adapter now sends a session's `settings` to Claude Code over stdin,
in the SDK's initialize request, as it has done for MCP servers since
#1647. They went in the `--settings` flag before.

Builds on #1668, which updated the SDK to 0.3.328.

## What changes

`cliDelivery()` in `src/claude-cli.ts` replaces `mcpServersDelivery()`.
It returns the SDK options `mcpServersDelivery` and `settingsDelivery`
together, because one rule decides both:

- **The CLI that the adapter ships** gets MCP servers and settings over
stdin: `'initialize'`. Claude Code is then started with
`--await-initialize --initialize-fields=settings` and without
`--settings`.
- **A CLI that `CLAUDE_CODE_EXECUTABLE` names** gets both in flags as
before: `'argv'`. Its version is not known, and an older one fails the
session at startup. Checked with 2.1.323: "unknown option
'--initialize-fields=settings'".
- **Settings stay in the flag when the client's `extraArgs` hold
`settings` or `sdk-url`.** With `settings` there, Claude Code refuses to
start with both ("--initialize-fields=settings cannot be used with
--settings"), and in the flag the `settings` option replaces that
argument, as before. A session with `sdk-url` cannot read the initialize
request at launch, which is why the SDK sends its MCP servers in the
flag too.

Both cores set the two options before the client's options, so a
client's own `mcpServersDelivery` or `settingsDelivery` wins.

The settings in question are the ones the adapter passes as the SDK's
`settings` option: a client's `_meta.claudeCode.options.settings`, the
model configuration of the environment, and the route of a provider or
gateway. A `settings` value that is a file path stays in the flag: the
SDK only sends an object over stdin.

## `settingsDelivery` is not in the SDK's types

SDK 0.3.328 reads `settingsDelivery`, but `sdk.d.ts` does not declare it
and the changelog does not name it. The SDK version is pinned, and no
cast is needed: the options are spread into the query's options.

Nothing fails to compile if a later SDK drops the option. For that case
the v2 integration tests have a new test against the real CLI: it starts
a session with settings, and checks that Claude Code was started with
`--initialize-fields=settings` and that no command line holds the
settings' value.

## Delivery tests in `npm run test:integration`

Each core has a test that expects `'argv'` for the MCP servers and one
for the settings ("sends MCP servers as the CLI takes them", "sends
settings as the CLI takes them"). They now set `CLAUDE_CODE_EXECUTABLE`
themselves.

Before, they relied on the value that `vitest.config.ts` sets for unit
runs only. In `npm run test:integration` the variable is unset, the
adapter's own CLI gets `'initialize'`, and the tests failed. On `main`,
the MCP servers test fails in that run on both cores since #1647. This
PR fixes it.

## Checked against the real CLI

Through the built adapter, on v1 and on v2, without API usage:

| Session | Started with | Result |
| --- | --- | --- |
| A client's `settings` | `--await-initialize
--initialize-fields=settings` | the session starts |
| The same, with the client's `settingsDelivery: 'argv'` | `--settings`
| the session starts |
| A provider with a header (`providers/set`, a local stand-in gateway) |
`--await-initialize --initialize-fields=settings` | the session's model
request reaches the gateway, with the provider's header |

With the SDK alone:

- The settings land in the same layer as before (`flagSettings` in
`getSettings()`), and they survive `applyFlagSettings()` calls for
effort and Fast mode.
- Without a `settings` option, nothing changes in the launch flags.

## Testing

- `npm run build`, `npm run check`, `npm run test:run` (4,375 tests
pass)
- Real CLI: the whole suite, as `npm run test:integration` runs it (with
`CLAUDE_CODE_ENTRYPOINT` unset): 4,406 tests pass and 9 are skipped (the
live capability audits, the baseline recording, and one test that skips
itself). With `CLAUDE_CODE_EXECUTABLE` set, the new integration test is
skipped.
- Real CLI: the probes above
2026-11-19 14:28:44 +01:00
Ben Brandt
6e307116d4 fix: update to @anthropic-ai/claude-agent-sdk 0.3.328 (#1668)
## Summary

Updates `@anthropic-ai/claude-agent-sdk` from 0.3.326 to 0.3.328, which
bundles Claude Code 2.1.328. The new version needs one adapter fix,
included here: a session's settings are released when the SDK refuses
the session's options.

Also bumps these dev dependencies: `@anthropic-ai/sdk` 1.9.0 → 1.10.0
and `vitest` 5.1.0 → 5.1.1.

`npm update` brings the in-range lockfile bumps: `express-rate-limit`
8.7.4 → 8.7.5, `jose` 6.2.17 → 6.2.18, `object-inspect` 1.13.4 → 1.14.0,
`standardwebhooks` 1.1.1 → 1.3.0, `source-map-js` 1.2.2 → 1.2.3 and
`tinybench` 6.2.3 → 6.2.4.

TypeScript stays at 6.0.3: 7.0.2 is out, but `@typescript-eslint/parser`
8.73.0 still requires `typescript <6.1.0`.

## Options that the SDK refuses

SDK 0.3.327 has a breaking change: `query()` refuses options that it
cannot send to Claude Code, and it does so by throwing at once. Recorded
with the real SDK for `hooks: { PreToolUse: [{ matcher: "Bash" }] }`, a
matcher without `hooks`:

- 0.3.326: `query()` returns, and `initializationResult()` rejects with
"a.hooks is not iterable".
- 0.3.328: `query()` throws "The session was not started, because the
hooks option can't be sent to Claude Code: hooks.PreToolUse[0].hooks
must be an array of callbacks. Fix that value and try again."

Both cores disposed the settings of a session that fails to start (the
`SettingsManager` and its file watchers) only when
`initializationResult()` rejected. A `query()` that throws skipped that,
and v1 also left the session's input open. Both cores now release them
there too. On v1, `discardUnregisteredQuery` does it, and takes no query
for this case.

What changes for a client:

- The error for such options is still `-32603`, now with the SDK's
message in `data.details`. Checked through the built adapter on v1 and
v2. The adapter serves the next request as before.
- **The SDK is stricter.** `hooks` with an event that is no list of
matchers, such as `{ "SessionStart": { … } }`, started a session on
0.3.326. It is refused now ("hooks.SessionStart must be an array of
matchers"), for the events that the adapter adds no hooks of its own to.

## Changelog review

Read the SDK changelog for 0.3.327 and 0.3.328 and the Claude Code
changelog for 2.1.327 and 2.1.328. No other entry needs a code change:

- **Types.** Doc text and new optional members, plus one new
`SDKStartupFailureReason` (`initialize_fields_not_delivered`).
`startupFailureError` treats a reason it does not list as an internal
error with the CLI's message.
- **`task_started` has no `prompt` when Claude Code wakes a background
subagent with text of its own**, such as a task notification. Both cores
start a run without a prompt then (`promptText` in
`src/native-subagents.ts`, `startRun` in `src/v2/tasks.ts`), so the
child's session no longer gets that text as a prompt.
- **The error for usage credits that run out mid-response** no longer
names a rate limit. The adapter takes the failure kind from the SDK's
`error` field, not from the text.
- **More calls ask for permission:** `ExitWorktree` for a worktree that
may hold unsaved work, some paths and symbolic links, and a subagent
that a sibling's message resumed. They reach `canUseTool` as any other
request.
- **`agent` and `agents` fixes** (an inline definition wins over one of
the same name, `--agents` survive a plugin reload). Picked up as they
are: the adapter passes a client's `agents` on.
- **"Background agents still running" after an interrupt, and after a
permission request that waited 30 seconds.** Picked up as they are.
- **`CLAUDE_CODE_DISABLE_DEFERRED_TOOL_RESUME`** and
**`CLAUDE_CODE_DISABLE_SHELL_HEAD_START`.** The adapter sets neither, so
it keeps Claude Code's defaults.
- **`getSessionInfo` and `listSessions`** read a transcript as before: a
differential run of 0.3.326 against 0.3.328 over 4,500 generated
transcripts gave no mismatch. The run is not part of this PR.
- **`@anthropic-ai/sdk` 1.10.0.** The adapter uses its types only. The
release adds API error codes and fixes tool runners that the adapter
does not use.
- **`vitest` 5.1.1.** Bug fixes.

## Not in this PR

- A throw of the adapter's own between the settings read and `query()`
still skips the dispose. Example: a client's `hooks.PostToolUse` that is
an object, which the adapter's own merge of the hooks cannot spread.
- `-32602` for options that the SDK refuses. The code is `-32603`, as it
was for these requests before.

## Testing

- `npm run build`, `npm run check`, `npm run test:run` (4,369 tests
pass)
- Each core has a test with a `query()` that throws the SDK's refusal.
Both fail without the fix.
- Real CLI: the integration tests (`RUN_INTEGRATION_TESTS=true`, with
`CLAUDE_CODE_ENTRYPOINT` unset), 941 tests pass, and one that the test
file itself skips
- Real SDK and CLI, without a prompt: the two `hooks` cases above with
0.3.326 and 0.3.328, and through the built adapter on v1 and v2
2026-11-19 13:53:15 +01:00
14 changed files with 362 additions and 140 deletions

View File

@@ -1,3 +1,3 @@
{
".": "0.108.1"
".": "0.109.0"
}

View File

@@ -1,5 +1,22 @@
# Changelog
## [0.109.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.108.1...v0.109.0) (2026-11-19)
### Features
* announce session cursors on v2 and fork at a cursor ([#1658](https://github.com/agentclientprotocol/claude-agent-acp/issues/1658)) ([5075d2e](https://github.com/agentclientprotocol/claude-agent-acp/commit/5075d2e0dffed68c4c1417d67c1c1e3ed43e6549))
* insert one message per idempotencyKey on v2 session/prompt ([#1657](https://github.com/agentclientprotocol/claude-agent-acp/issues/1657)) ([1c0792e](https://github.com/agentclientprotocol/claude-agent-acp/commit/1c0792ea8cbdfb96ac2afb1f675e4309446d0e5c))
* order config options as model, effort, fast, ultracode, mode, agent ([#1666](https://github.com/agentclientprotocol/claude-agent-acp/issues/1666)) ([f31da7f](https://github.com/agentclientprotocol/claude-agent-acp/commit/f31da7f9f5264eb2b57fbda577ac35141eb530c8))
* report Fast mode in the speed config option category ([#1659](https://github.com/agentclientprotocol/claude-agent-acp/issues/1659)) ([8990c24](https://github.com/agentclientprotocol/claude-agent-acp/commit/8990c2441d3d45cb4781cd81316b3ffbafee85ee))
* send the predicted next prompt as prompt_suggestions_update ([#1660](https://github.com/agentclientprotocol/claude-agent-acp/issues/1660)) ([f20ed1d](https://github.com/agentclientprotocol/claude-agent-acp/commit/f20ed1d96ac786af36b6bee3b4d5925a85b6d7ae))
### Bug Fixes
* send a session's settings to Claude Code over stdin ([#1669](https://github.com/agentclientprotocol/claude-agent-acp/issues/1669)) ([a768a9f](https://github.com/agentclientprotocol/claude-agent-acp/commit/a768a9f50c65b66b9f2d5806909a1db643fe3b6e))
* update to @anthropic-ai/claude-agent-sdk 0.3.328 ([#1668](https://github.com/agentclientprotocol/claude-agent-acp/issues/1668)) ([6e30711](https://github.com/agentclientprotocol/claude-agent-acp/commit/6e307116d461af22fb5d42eb4b8fbdb3643c6d6c))
## [0.108.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.108.0...v0.108.1) (2026-11-18)

160
package-lock.json generated
View File

@@ -1,16 +1,16 @@
{
"name": "@agentclientprotocol/claude-agent-acp",
"version": "0.108.1",
"version": "0.109.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@agentclientprotocol/claude-agent-acp",
"version": "0.108.1",
"version": "0.109.0",
"license": "Apache-2.0",
"dependencies": {
"@agentclientprotocol/sdk": "2.8.0",
"@anthropic-ai/claude-agent-sdk": "0.3.326",
"@anthropic-ai/claude-agent-sdk": "0.3.328",
"diff": "9.0.0",
"zod": "4.6.7"
},
@@ -18,7 +18,7 @@
"claude-agent-acp": "dist/index.js"
},
"devDependencies": {
"@anthropic-ai/sdk": "1.9.0",
"@anthropic-ai/sdk": "1.10.0",
"@eslint/js": "10.0.1",
"@tsconfig/node22": "22.0.7",
"@types/node": "26.6.6",
@@ -31,7 +31,7 @@
"globals": "17.14.0",
"prettier": "3.10.1",
"typescript": "6.0.3",
"vitest": "5.1.0"
"vitest": "5.1.1"
},
"engines": {
"node": ">=22"
@@ -53,22 +53,22 @@
}
},
"node_modules/@anthropic-ai/claude-agent-sdk": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.326.tgz",
"integrity": "sha512-BUTSky/4YWfL/MxC+4kV0NDbJFjbJPoQMFEk/s9G6hV9LUfYPMbsWz94bFQ7ZIo2ubj2xwJ2c2NVxkNlQhVw+Q==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.328.tgz",
"integrity": "sha512-YcOWlpXVm7etPjPVrvSJEfynDksMiG11zvEybSBnk1EVWji6rSjU75HbbhJ8XPEB2ECEwRRP597Udu6IWMtsDw==",
"license": "SEE LICENSE IN README.md",
"engines": {
"node": ">=18.14.0"
},
"optionalDependencies": {
"@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.326",
"@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.326",
"@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.326",
"@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.326",
"@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.326",
"@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.326",
"@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.326",
"@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.326"
"@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.328",
"@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.328",
"@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.328",
"@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.328",
"@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.328",
"@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.328",
"@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.328",
"@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.328"
},
"peerDependencies": {
"@anthropic-ai/sdk": ">=0.93.0",
@@ -77,9 +77,9 @@
}
},
"node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.326.tgz",
"integrity": "sha512-D3ZbowCMdKNet0YPZlsJxdJUW1t1Q8KLy1BwNd+5eilf18TlCRtWZlm8DrewFLmu/gxBK7gcsq6uysrIVbPyQg==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.328.tgz",
"integrity": "sha512-vjBASSSZFNs5M84XONCM4xAJMKPD0E9RtF0UDQ/a1Qqt5L+slNxhSADkH5n0tEM5HJMK7j9DCPi+0FVOBpZr3w==",
"cpu": [
"arm64"
],
@@ -90,9 +90,9 @@
]
},
"node_modules/@anthropic-ai/claude-agent-sdk-darwin-x64": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.326.tgz",
"integrity": "sha512-m8K3Im2S8STdAVBrriuDZyJcnjsu/Vc3476wIOqTAefnCCdtdZ4AHcOcWxt+4KIHE5Vx1qT2qacTRrQBaVVweA==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.328.tgz",
"integrity": "sha512-pkZuDNi16H4yJFo6cS2sw8mFj7m7ESAxV74t2gQ9EFzZOpXbQoJqhPBHNEZJ2q/+kr/3vHUtRc2W6jURA6nS+A==",
"cpu": [
"x64"
],
@@ -103,9 +103,9 @@
]
},
"node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.326.tgz",
"integrity": "sha512-nYVN8jCcH490DCXIvby7rllzQFxLzKeKClfo2u/yv7mx3ipZQv344caULL/amwZ8w8GUzYyZ8hnS6pI9goSq+A==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.328.tgz",
"integrity": "sha512-VvsUzOEf7r3ZtOPfliNGxqknsIvxEmnUOtQnq4+uw7MsfiALKR4s0bx2SP32UuXpqbmqxR1gn456D27XgsAmnA==",
"cpu": [
"arm64"
],
@@ -119,9 +119,9 @@
]
},
"node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64-musl": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.326.tgz",
"integrity": "sha512-baSsuP2/wuWujRpHjKT4WkJB5lhttqKq9jcTfY2KRtQpylbk8E5PWcct/pmwJfNCKIUoE8CD+JpmoWzsdd5Ajw==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.328.tgz",
"integrity": "sha512-4Vui26/OZwr8AU7FpAt+R5s/1AKmj5qDorUZIqF1MMfdjAQf8/ut/+HyEkuMom/MVF2JeQLdvnFFFmbfgmAq/g==",
"cpu": [
"arm64"
],
@@ -135,9 +135,9 @@
]
},
"node_modules/@anthropic-ai/claude-agent-sdk-linux-x64": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.326.tgz",
"integrity": "sha512-WMhDY07gk2O0E8FXTbrVYmPjSLFaYPDCPwsNueVxm6vZ7ek+lPaKuOMAxTb1K07TzSmTOexoWeX2Y9VrbVDMpw==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.328.tgz",
"integrity": "sha512-saP4fWgVZj1n7MYCqvTKADHXIc/hIAMRDpLVpXD5xB0IT68vhWgIMkzIrsg5P02P6zA49TDuoijbP1YBUEXT4A==",
"cpu": [
"x64"
],
@@ -151,9 +151,9 @@
]
},
"node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.326.tgz",
"integrity": "sha512-kK9VO3uFqNd4wgeU0Cefluam5AdPu6mvF1nn6aboGy8TA5NoxlWTmA4/AwMhK39zK1S9Q2OjeX0JtAahYlIchw==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.328.tgz",
"integrity": "sha512-oJowzzjhWGbdBGyRjqV9CT0nfh4A4/fEI11LjX6b1SkhrNNgy9QT2HzSe8A2yNlliOWo1xJl6nAHT8pLwMNlVg==",
"cpu": [
"x64"
],
@@ -167,9 +167,9 @@
]
},
"node_modules/@anthropic-ai/claude-agent-sdk-win32-arm64": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.326.tgz",
"integrity": "sha512-S+Ai+HhGRVFfTDmYWRfTrdWF3b4KMsfLSThZCqRJ0WCOKOXrRShMKV1hqqHBljx/wkMDPCpY0V/9S/e6w57eGQ==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.328.tgz",
"integrity": "sha512-FkqzA++c+giPH2k8svb0egWDiGDkvSLQJTp5bq7QFXOxPEael4ct1yjKit/Yu6Sd48uLEgNT1waBYbyApPzhOw==",
"cpu": [
"arm64"
],
@@ -180,9 +180,9 @@
]
},
"node_modules/@anthropic-ai/claude-agent-sdk-win32-x64": {
"version": "0.3.326",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.326.tgz",
"integrity": "sha512-Yn1gZXYFuHmjHz7SpHx4TqDcRDsC8TfwWcntJdYjFzMWm+caPAp6QRqr/aTvirjqVA1D+D8Rd29xhuytpE3xTQ==",
"version": "0.3.328",
"resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.328.tgz",
"integrity": "sha512-9Wd0XrZ0QWkgtcKxObcYDvUpQjUzN3Uq4Chbvu1SOWOoKPfQdD40dwRQMCeKx2KGxAfMrggJ7I3JYnvRWAFYjg==",
"cpu": [
"x64"
],
@@ -193,9 +193,9 @@
]
},
"node_modules/@anthropic-ai/sdk": {
"version": "1.9.0",
"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-1.9.0.tgz",
"integrity": "sha512-xDu4za3B+rK+5ZI8wLLoosiIuwi1ktZk/3L3KKNahwO50O34H+622hly8JdXzaEerLQDhsqwVzp81Nrw80BYHg==",
"version": "1.10.0",
"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-1.10.0.tgz",
"integrity": "sha512-j4uVct5p3aGIz/BU4K8VU5vt2A6AueHTvx2gfF3xr4mVpwH9IJMWEAUKNwSwdZSJOHQq1Za2tv5huYc5v02D0w==",
"license": "Apache-2.0",
"dependencies": {
"@opentelemetry/api": "^1.4.1",
@@ -1251,16 +1251,16 @@
}
},
"node_modules/@vitest/mocker": {
"version": "5.1.0",
"resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-5.1.0.tgz",
"integrity": "sha512-5umB9/jlWcqVS6fsrFmv5Gdnpu6wAUio/lEOwAmvB7v+lFo/IW2B9FhAD0p19GCULTgMzLCdUmuCDCnAzWgppQ==",
"version": "5.1.1",
"resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-5.1.1.tgz",
"integrity": "sha512-b2OgTB4+3ImWIVafXKazJXwLKwQxUNnix6b3xUvUTMh7RyXlrtzoxfZr8aEz9zkHOMAS4K5lu3TvFWoiVeVTQg==",
"dev": true,
"license": "MIT",
"dependencies": {
"@jridgewell/trace-mapping": "0.3.31",
"@vitest/spy": "5.1.0",
"@vitest/spy": "5.1.1",
"estree-walker": "^3.0.3",
"magic-string": "^1.4.3"
"magic-string": "^1.4.5"
},
"funding": {
"url": "https://opencollective.com/vitest"
@@ -1279,9 +1279,9 @@
}
},
"node_modules/@vitest/spy": {
"version": "5.1.0",
"resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-5.1.0.tgz",
"integrity": "sha512-2DPO5OMHWKrBngC+fCmTQqemNF0gidRhp3lxbBmRhW+M1XJrfgPpqNqWVevXtn2f2ufD5ZaR1B6B641aAlcX5A==",
"version": "5.1.1",
"resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-5.1.1.tgz",
"integrity": "sha512-6K8C6alQG1/Yc8/ZI22iJS7JEsxPdVzqtqDq+/xM4Z0mGVykemMVjLhqMy/q6/IHYG3kKD8hKSwRen/ZdyI9vQ==",
"dev": true,
"license": "MIT",
"funding": {
@@ -2050,9 +2050,9 @@
}
},
"node_modules/express-rate-limit": {
"version": "8.7.4",
"resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.7.4.tgz",
"integrity": "sha512-LKBXzX700wz3zAGNNmVnjRI5mEbYkLv7UbMI4+9Xa+JPcg2UZh6AgY/2CZh9RrJjFM5ttC/N1lD+KzyFoZITCw==",
"version": "8.7.5",
"resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.7.5.tgz",
"integrity": "sha512-wi+v38cx2EqD0JnhE/e74o5tFqKWUOAPFJIgyEiqJ8v2MNpoOAA3kI2hXYOI+YM+HE5yqbdAlVxm2GqOIeYOgA==",
"license": "MIT",
"peer": true,
"dependencies": {
@@ -2513,9 +2513,9 @@
"license": "ISC"
},
"node_modules/jose": {
"version": "6.2.17",
"resolved": "https://registry.npmjs.org/jose/-/jose-6.2.17.tgz",
"integrity": "sha512-wOuK9V1yujQFH5S0ZWmLcDZN7+IKh9bUCC2ZPCf2HDlol3WWHy+PPyNjEI75FXRLMp3vDKQcupP59xhVU95hcg==",
"version": "6.2.18",
"resolved": "https://registry.npmjs.org/jose/-/jose-6.2.18.tgz",
"integrity": "sha512-doV4thUwgkrycJH4yLeqwTGIIZphHl+pk7CPReuMIhYhncmgzdko85MaCG4YQFTxqMFr1/oEH32tZuKKovcDEg==",
"license": "MIT",
"peer": true,
"funding": {
@@ -3046,9 +3046,9 @@
}
},
"node_modules/object-inspect": {
"version": "1.13.4",
"resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
"integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
"version": "1.14.0",
"resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.14.0.tgz",
"integrity": "sha512-IVgHNlp/jwQX271+Xzoq9LZNTWXxZK+cEOrGBOBxXNbn7fapnZ+Ts6TVMgNOuAezwG2wdtnMX97tTPK6VEnuOQ==",
"license": "MIT",
"peer": true,
"engines": {
@@ -3609,9 +3609,9 @@
}
},
"node_modules/source-map-js": {
"version": "1.2.2",
"resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
"integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==",
"version": "1.2.3",
"resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.3.tgz",
"integrity": "sha512-xj+WrAkyv5Qp+t7r9N5HvCBu7g1qOe6CKRNpq22X1GGcPEQADFU54v5qsPVs3/vrUFQ7XivFrcAVKA2stI0kWA==",
"dev": true,
"license": "BSD-3-Clause",
"peer": true,
@@ -3620,9 +3620,9 @@
}
},
"node_modules/standardwebhooks": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/standardwebhooks/-/standardwebhooks-1.1.1.tgz",
"integrity": "sha512-bCbX9ZEyFkWPsRz7Bl3NuQUJohmwGSev/yhr7vhaGPlc4AfIrspIRa6cPTBuI1ItmrTDJ4d/S2hCsfe4+vQGnQ==",
"version": "1.3.0",
"resolved": "https://registry.npmjs.org/standardwebhooks/-/standardwebhooks-1.3.0.tgz",
"integrity": "sha512-5W9skHjqAm2dlA9wWvglTP+oX47JX4lFXVk1aJV7+TG1snvTR4QXaVgPscEzvOw9GRreeavMwbqEeL+MGhZHCg==",
"license": "MIT",
"dependencies": {
"@stablelib/base64": "^1.0.0",
@@ -3647,9 +3647,9 @@
"license": "MIT"
},
"node_modules/tinybench": {
"version": "6.2.3",
"resolved": "https://registry.npmjs.org/tinybench/-/tinybench-6.2.3.tgz",
"integrity": "sha512-Al01C2JIBnO2CXCAPbpAl6sUiOZHeThGtHYNTa51JRw9PyWOCdr+9Ong05R4qg/Sk3+H645E8ov1h2c58ityNw==",
"version": "6.2.4",
"resolved": "https://registry.npmjs.org/tinybench/-/tinybench-6.2.4.tgz",
"integrity": "sha512-SQ52jEncXxbMCzJuY2A/jGIbbAu6NYsBWW7grz2pNE+EnzQdoGaoBfpk4qC/opE7qiUcGmGgaGIz5EoHdS1O9w==",
"dev": true,
"license": "MIT",
"engines": {
@@ -3898,22 +3898,22 @@
}
},
"node_modules/vitest": {
"version": "5.1.0",
"resolved": "https://registry.npmjs.org/vitest/-/vitest-5.1.0.tgz",
"integrity": "sha512-MzmNFnrwa8v8lF1bLxw3UJ4EREwVOVb75VqJZmUDRjJ6EluK/x9th7qTbaeDk41WxE1GxWqmTXcdsfobfH5sOA==",
"version": "5.1.1",
"resolved": "https://registry.npmjs.org/vitest/-/vitest-5.1.1.tgz",
"integrity": "sha512-trVmzUFOSraCZcI3uZIMD5FqBh4atFkC/XuJP/IU7qtyQay0FCs3Ia+0QiQ2JJwGyWG/xrcBoJNel2+O7kEZ0g==",
"dev": true,
"license": "MIT",
"dependencies": {
"@types/chai": "^5.2.2",
"@vitest/mocker": "5.1.0",
"@vitest/mocker": "5.1.1",
"chai": "^6.3.0",
"es-module-lexer": "^2.3.2",
"expect-type": "^1.4.0",
"magic-string": "^1.4.3",
"magic-string": "^1.4.5",
"obug": "^3.0.0",
"picomatch": "^4.0.7",
"std-env": "^4.3.0",
"tinybench": "^6.2.2",
"tinybench": "^6.2.3",
"tinyexec": "^1.3.1",
"tinyglobby": "^0.2.17",
"why-is-node-running": "3.2.1"
@@ -3931,12 +3931,12 @@
"@edge-runtime/vm": "*",
"@opentelemetry/api": "^1.9.0",
"@types/node": "^22.0.0 || >=24.0.0",
"@vitest/browser-playwright": "5.1.0",
"@vitest/browser-preview": "5.1.0",
"@vitest/browser-playwright": "5.1.1",
"@vitest/browser-preview": "5.1.1",
"@vitest/browser-webdriverio": "^5.0.0-beta.5 || >=5.0.0",
"@vitest/coverage-istanbul": "5.1.0",
"@vitest/coverage-v8": "5.1.0",
"@vitest/ui": "5.1.0",
"@vitest/coverage-istanbul": "5.1.1",
"@vitest/coverage-v8": "5.1.1",
"@vitest/ui": "5.1.1",
"happy-dom": "*",
"jsdom": "*",
"vite": "^6.4.0 || ^7.0.0 || ^8.0.0"

View File

@@ -3,7 +3,7 @@
"publishConfig": {
"access": "public"
},
"version": "0.108.1",
"version": "0.109.0",
"description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
"main": "dist/lib.js",
"types": "dist/lib.d.ts",
@@ -69,12 +69,12 @@
},
"dependencies": {
"@agentclientprotocol/sdk": "2.8.0",
"@anthropic-ai/claude-agent-sdk": "0.3.326",
"@anthropic-ai/claude-agent-sdk": "0.3.328",
"diff": "9.0.0",
"zod": "4.6.7"
},
"devDependencies": {
"@anthropic-ai/sdk": "1.9.0",
"@anthropic-ai/sdk": "1.10.0",
"@eslint/js": "10.0.1",
"@tsconfig/node22": "22.0.7",
"@types/node": "26.6.6",
@@ -87,6 +87,6 @@
"globals": "17.14.0",
"prettier": "3.10.1",
"typescript": "6.0.3",
"vitest": "5.1.0"
"vitest": "5.1.1"
}
}

View File

@@ -31,26 +31,44 @@ export async function claudeCliPath(): Promise<string> {
return installedClaudeCliPath();
}
/** How an option reaches the Claude CLI: in a flag, or over stdin in the SDK's initialize request. */
type Delivery = NonNullable<Options["mcpServersDelivery"]>;
/**
* How a session's MCP servers reach the CLI of {@link claudeCliPath}, unless
* the client's options name a `mcpServersDelivery`.
* The SDK options that say how a session's MCP servers and its `settings`
* reach the CLI of {@link claudeCliPath}. A client's own options replace them.
*
* - `'initialize'` for the CLI that the adapter ships: over stdin, in the
* SDK's initialize request. A server's `env` and `headers`, such as the
* bearer token of an MCP-over-ACP endpoint (see `McpOverAcp`), stay off the
* CLI's command line, which other users of the machine can read. Only a
* launch that the client's options give `--sdk-url` still gets them there.
* SDK's initialize request.
* - `'argv'` for a CLI that `CLAUDE_CODE_EXECUTABLE` names: in the
* `--mcp-config` flag, so on its command line, as before SDK 0.3.326. Its
* version is not known, and the SDK ends the session at startup when the CLI
* cannot read the servers from the initialize request (e.g. 2.1.323).
* `--mcp-config` and `--settings` flags, as before SDK 0.3.326. Its version
* is not known, and a CLI that cannot take them over stdin fails the session
* at startup (2.1.323: "too old to read MCP servers from the initialize
* request", "unknown option '--initialize-fields=settings'").
* - `settings` stay `'argv'` when the client's `extraArgs` hold `settings`:
* Claude Code refuses to start with both ("--initialize-fields=settings
* cannot be used with --settings"), and in the flag the `settings` option
* replaces that argument. They also stay `'argv'` with `sdk-url` in the
* `extraArgs`: such a session cannot read the request at launch, and the SDK
* sends its MCP servers in the flag for the same reason.
*
* The adapter always sets the option. It names the CLI to start
* The SDK reads `settingsDelivery` (0.3.328) but does not declare it in
* `sdk.d.ts`, so nothing fails to compile if a later SDK drops it. The v2
* integration tests check the delivery against the real CLI.
*
* `mcpServersDelivery` is always set. The adapter names the CLI to start
* (`pathToClaudeCodeExecutable`), and for such an app the SDK prints a
* `DeprecationWarning` when a session has MCP servers and the option is unset.
*/
export function mcpServersDelivery(): NonNullable<Options["mcpServersDelivery"]> {
return process.env.CLAUDE_CODE_EXECUTABLE ? "argv" : "initialize";
export function cliDelivery(clientExtraArgs: Options["extraArgs"]): {
mcpServersDelivery: Delivery;
settingsDelivery: Delivery;
} {
const delivery = process.env.CLAUDE_CODE_EXECUTABLE ? "argv" : "initialize";
const settingsInFlag = Object.keys(clientExtraArgs ?? {}).some(
(name) => name === "settings" || name === "sdk-url" || name.startsWith("sdk-url="),
);
return { mcpServersDelivery: delivery, settingsDelivery: settingsInFlag ? "argv" : delivery };
}
function bundledClaudeCliPath(directory: string): string {

View File

@@ -44,12 +44,25 @@ import {
// personas, so we filter them out and only surface the Agent picker when the
// user (or a plugin/project) has configured custom agents. Update this set if
// the SDK's built-in roster changes.
//
// The set is matched by name because `AgentInfo` does not say where an agent
// comes from. `getContextUsage().agents` lists only the agents that are not
// built in, but session setup does not wait for that request (see
// `readContextWindow`).
//
// Claude Code does not list two of them in every session: `web-fetch` only
// where its staged rollout or `CLAUDE_CODE_WEB_FETCH_AGENT=1` turns it on, and
// `claude-code-guide` only where the adapter's environment sets
// `CLAUDE_CODE_ENTRYPOINT` (the SDK sets `sdk-ts` when it is unset, and Claude
// Code leaves the agent out for that value).
export const BUILTIN_AGENT_NAMES = new Set([
"claude",
"claude-code-guide",
"general-purpose",
"Explore",
"Plan",
"statusline-setup",
"web-fetch",
]);
// Value of the synthetic "Default" entry in the agent picker, which maps to the

View File

@@ -11,6 +11,13 @@ import { discoverCustomAgents, BUILTIN_AGENT_NAMES } from "../session-config-opt
// silently if the SDK changes its default roster: a newly added built-in would
// leak into the ACP "Agent" picker as if the user had configured it. This
// integration test runs the real SDK so the set is flagged the moment it does.
//
// Claude Code does not list every built-in in every session (issue #1670):
// `web-fetch` needs its staged rollout or `CLAUDE_CODE_WEB_FETCH_AGENT=1`, and
// `claude-code-guide` an entrypoint other than the SDK's `sdk-ts`. The test
// sets both variables, so the roster does not depend on the account or on the
// shell that runs it. A built-in behind a rollout with no variable set here
// shows up only where that rollout is on.
describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("agent discovery (SDK)", () => {
it("BUILTIN_AGENT_NAMES exactly covers the SDK's default agent roster", async () => {
const input = new Pushable<SDKUserMessage>();
@@ -24,6 +31,11 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("agent discovery (SDK)", ()
// regardless of what the developer has in ~/.claude/agents.
settingSources: [],
includePartialMessages: true,
env: {
...process.env,
CLAUDE_CODE_WEB_FETCH_AGENT: "1",
CLAUDE_CODE_ENTRYPOINT: "agent-roster-test",
},
},
});

View File

@@ -56,24 +56,49 @@ describe("claudeCliPath", () => {
});
});
describe("mcpServersDelivery", () => {
describe("cliDelivery", () => {
afterEach(() => vi.unstubAllEnvs());
it.each([
it.each<{
name: string;
cli: string;
extraArgs?: Record<string, string>;
mcpServers: string;
settings: string;
}>([
{
name: "is initialize for the CLI that it ships",
name: "is stdin for the CLI that it ships",
cli: "",
delivery: "initialize",
mcpServers: "initialize",
settings: "initialize",
},
{
name: "is argv for a CLAUDE_CODE_EXECUTABLE CLI",
name: "is a flag for a CLAUDE_CODE_EXECUTABLE",
cli: "/opt/claude",
delivery: "argv",
mcpServers: "argv",
settings: "argv",
},
])("$name", async ({ cli, delivery }) => {
{
name: "keeps settings a flag beside a client's",
cli: "",
extraArgs: { settings: "{}" },
mcpServers: "initialize",
settings: "argv",
},
{
name: "keeps settings a flag with sdk-url",
cli: "",
extraArgs: { "sdk-url": "wss://example.com/session" },
mcpServers: "initialize",
settings: "argv",
},
])("$name", async ({ cli, extraArgs, mcpServers, settings }) => {
vi.stubEnv("CLAUDE_CODE_EXECUTABLE", cli);
const { mcpServersDelivery } = await load();
const { cliDelivery } = await load();
expect(mcpServersDelivery()).toBe(delivery);
expect(cliDelivery(extraArgs)).toEqual({
mcpServersDelivery: mcpServers,
settingsDelivery: settings,
});
});
});

View File

@@ -30656,10 +30656,12 @@ describe("agent selection config option", () => {
const q = {
supportedAgents: async () => [
{ name: "claude", description: "catch-all" },
{ name: "claude-code-guide", description: "guide" },
{ name: "Explore", description: "search" },
{ name: "general-purpose", description: "gp" },
{ name: "Plan", description: "architect" },
{ name: "statusline-setup", description: "status" },
{ name: "web-fetch", description: "fetch" },
{ name: "my-reviewer", description: "Reviews code" },
{ name: "my-writer", description: "Writes docs" },
],

View File

@@ -1,4 +1,4 @@
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import { describe, it, expect, beforeEach, afterEach, onTestFinished, vi } from "vitest";
import {
CreateElicitationRequest,
RequestError,
@@ -28,6 +28,8 @@ let initModels: Record<string, unknown>[] | undefined;
/** Holds the CLI initialization until the test resolves it. */
let initGate: Promise<void> | undefined;
let initError: Error | undefined;
/** When set, the SDK refuses the query's options with it: `query()` throws. */
let optionsRefusal: Error | undefined;
let setModelImpl: ((model: string) => Promise<void>) | undefined;
let interruptImpl: (() => Promise<undefined>) | undefined;
let closeSpy: ReturnType<typeof vi.fn<() => void>>;
@@ -45,6 +47,7 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
return {
...actual,
query: (args: { prompt: unknown; options: Options }) => {
if (optionsRefusal) throw optionsRefusal;
capturedOptions = args.options;
// Like Claude Code's, the stream stays open until the query is closed.
let streamClosed = () => {};
@@ -123,6 +126,7 @@ describe("createSession options merging", () => {
initModels = undefined;
initGate = undefined;
initError = undefined;
optionsRefusal = undefined;
setModelImpl = undefined;
interruptImpl = undefined;
closeSpy = vi.fn<() => void>();
@@ -626,17 +630,33 @@ describe("createSession options merging", () => {
});
it.each([
{ name: "sends MCP servers as the CLI takes them", delivery: undefined },
{ name: "lets a caller choose the MCP delivery", delivery: "initialize" as const },
])("$name", async ({ delivery }) => {
{ name: "sends MCP servers as the CLI takes them", option: "mcpServersDelivery" },
{
name: "lets a caller choose the MCP delivery",
option: "mcpServersDelivery",
own: "initialize",
},
{ name: "sends settings as the CLI takes them", option: "settingsDelivery" },
{
name: "lets a caller choose settings delivery",
option: "settingsDelivery",
own: "initialize",
},
])("$name", async ({ option, own }) => {
// A CLI that CLAUDE_CODE_EXECUTABLE names gets both in flags.
// `vitest.config.ts` sets the variable for unit runs only.
vi.stubEnv("CLAUDE_CODE_EXECUTABLE", "/usr/bin/false");
onTestFinished(() => {
vi.unstubAllEnvs();
});
await agent.newSession({
cwd: process.cwd(),
mcpServers: [],
...(delivery && { _meta: { claudeCode: { options: { mcpServersDelivery: delivery } } } }),
...(own && { _meta: { claudeCode: { options: { [option]: own } } } }),
});
// Unit runs name a CLI with CLAUDE_CODE_EXECUTABLE (see `vitest.config.ts`).
expect(capturedOptions!.mcpServersDelivery).toBe(delivery ?? "argv");
expect((capturedOptions as Record<string, unknown>)[option]).toBe(own ?? "argv");
});
it("defaults tools to claude_code preset when not provided", async () => {
@@ -1747,6 +1767,27 @@ describe("createSession options merging", () => {
initError,
);
});
it("disposes the settings of a session whose options the SDK refuses", async () => {
// What SDK 0.3.328 throws from `query()` for a hook matcher without `hooks`.
optionsRefusal = new Error(
"The session was not started, because the hooks option can't be sent to Claude Code: " +
"hooks.PreToolUse[0].hooks must be an array of callbacks. Fix that value and try again.",
);
// The module that the agent of this test loaded (see `beforeEach`).
const { SettingsManager } = await import("../../settings.js");
const initialized = vi.spyOn(SettingsManager.prototype, "initialize");
const disposed = vi.spyOn(SettingsManager.prototype, "dispose");
await expect(agent.newSession({ cwd: process.cwd(), mcpServers: [] })).rejects.toBe(
optionsRefusal,
);
expect(initialized).toHaveBeenCalled();
expect(disposed).toHaveBeenCalledTimes(initialized.mock.calls.length);
initialized.mockRestore();
disposed.mockRestore();
});
});
describe("elicitation", () => {

View File

@@ -1,4 +1,5 @@
import { spawn, spawnSync, type ChildProcess } from "node:child_process";
import { randomUUID } from "node:crypto";
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import * as os from "node:os";
import * as path from "node:path";
@@ -70,6 +71,19 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("v2 core with Claude Code",
afterAll(() => child?.kill());
/**
* Whether the adapter sends MCP servers and settings to Claude Code over
* stdin (see `cliDelivery`), and `ps` can show that: not for a
* CLAUDE_CODE_EXECUTABLE CLI, and not on Windows.
*/
const takesOptionsOverStdin = process.platform !== "win32" && !process.env.CLAUDE_CODE_EXECUTABLE;
/** The command lines of the processes that the adapter started. */
const adapterCommandLines = () =>
spawnSync("ps", ["-axww", "-o", "ppid=,command="], { encoding: "utf8" })
.stdout.split("\n")
.filter((line) => line.trim().startsWith(`${child.pid} `));
/** The states of the root session's `state_update`s, in order. */
const states = (sessionId: string) =>
updates.flatMap(({ sessionId: id, update }) =>
@@ -218,19 +232,34 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("v2 core with Claude Code",
// Claude Code asks for the server's MCP revision first, not with `initialize`.
await until(() => served.includes("tools/list"), 30_000);
expect(served[0]).toBe("server/discover");
// The server's bearer token went to Claude Code over stdin: it is on no
// command line of the adapter's processes (`ps`, so not on Windows). A
// CLAUDE_CODE_EXECUTABLE CLI gets it on its command line.
if (process.platform !== "win32" && !process.env.CLAUDE_CODE_EXECUTABLE) {
const commandLines = spawnSync("ps", ["-axww", "-o", "ppid=,command="], { encoding: "utf8" })
.stdout.split("\n")
.filter((line) => line.trim().startsWith(`${child.pid} `));
// The server's bearer token went to Claude Code over stdin.
if (takesOptionsOverStdin) {
const commandLines = adapterCommandLines();
// Claude Code's session process is one of them.
expect(commandLines.some((line) => line.includes("stream-json"))).toBe(true);
expect(commandLines.filter((line) => line.includes("Bearer "))).toEqual([]);
}
}, 60_000);
// No prompt: it costs no API usage.
it.skipIf(!takesOptionsOverStdin)(
"sends a session's settings to Claude Code over stdin",
async () => {
const marker = `v2-integration-${randomUUID()}`;
await agent.request(v2.methods.agent.session.new, {
cwd,
_meta: {
claudeCode: { options: { settings: { env: { V2_INTEGRATION_MARKER: marker } } } },
},
});
const commandLines = adapterCommandLines();
// Claude Code's session process, told to read the settings from the initialize request.
expect(commandLines.some((line) => line.includes("--initialize-fields=settings"))).toBe(true);
expect(commandLines.filter((line) => line.includes(marker))).toEqual([]);
},
60_000,
);
it("reports requires_action while a permission request waits", async () => {
const sessionId = await newSession("default");
await prompt(

View File

@@ -73,6 +73,8 @@ const sdk = vi.hoisted(() => ({
previewGate: undefined as Promise<void> | undefined,
/** When set, Claude Code fails to start with it. */
startFailure: undefined as Error | undefined,
/** When set, the SDK refuses the query's options with it: `query()` throws. */
optionsRefusal: undefined as Error | undefined,
/** When set, Claude Code's start waits for it. */
startGate: undefined as Promise<void> | undefined,
/** When set, the query serves Remote Control with it (`enableRemoteControl`). */
@@ -86,6 +88,7 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
return {
...actual,
query: ({ prompt, options }: { prompt: AsyncIterable<SDKUserMessage>; options: Options }) => {
if (sdk.optionsRefusal) throw sdk.optionsRefusal;
const queue: Array<IteratorResult<Record<string, unknown>> | Error> = [];
let wake = () => {};
const prompts: SDKUserMessage[] = [];
@@ -219,6 +222,7 @@ beforeEach(async () => {
sdk.subagents = new Map();
sdk.previewGate = undefined;
sdk.startFailure = undefined;
sdk.optionsRefusal = undefined;
sdk.startGate = undefined;
sdk.enableRemoteControl = undefined;
vi.mocked(forkSession).mockClear();
@@ -1020,9 +1024,23 @@ describe("ACP v2 core", () => {
});
it.each([
{ name: "sends MCP servers as the CLI takes them", delivery: undefined },
{ name: "lets the client choose the MCP delivery", delivery: "initialize" },
])("$name", async ({ delivery }) => {
{ name: "sends MCP servers as the CLI takes them", option: "mcpServersDelivery" },
{
name: "lets the client choose the MCP delivery",
option: "mcpServersDelivery",
own: "initialize",
},
{ name: "sends settings as the CLI takes them", option: "settingsDelivery" },
{
name: "lets the client choose settings delivery",
option: "settingsDelivery",
own: "initialize",
},
])("$name", async ({ option, own }) => {
// A CLI that CLAUDE_CODE_EXECUTABLE names gets both in flags.
// `vitest.config.ts` sets the variable for unit runs only.
vi.stubEnv("CLAUDE_CODE_EXECUTABLE", "/usr/bin/false");
const client = v2Client();
await client.connect(async (agent) => {
await agent.request(v2.methods.agent.initialize, {
@@ -1032,12 +1050,11 @@ describe("ACP v2 core", () => {
});
await agent.request(v2.methods.agent.session.new, {
cwd,
...(delivery && { _meta: { claudeCode: { options: { mcpServersDelivery: delivery } } } }),
...(own && { _meta: { claudeCode: { options: { [option]: own } } } }),
});
});
// Unit runs name a CLI with CLAUDE_CODE_EXECUTABLE (see `vitest.config.ts`).
expect(sdk.processes[0].options.mcpServersDelivery).toBe(delivery ?? "argv");
expect((sdk.processes[0].options as Record<string, unknown>)[option]).toBe(own ?? "argv");
});
it("answers a prompt when Claude Code starts it, and reports the work until the turn's result", async () => {
@@ -3540,6 +3557,31 @@ describe("ACP v2 core", () => {
disposed.mockRestore();
});
it("disposes the settings of a session whose options the SDK refuses", async () => {
// What SDK 0.3.328 throws from `query()` for a hook matcher without `hooks`.
sdk.optionsRefusal = new Error(
"The session was not started, because the hooks option can't be sent to Claude Code: " +
"hooks.PreToolUse[0].hooks must be an array of callbacks. Fix that value and try again.",
);
const initialized = vi.spyOn(SettingsManager.prototype, "initialize");
const disposed = vi.spyOn(SettingsManager.prototype, "dispose");
const client = v2Client();
const error = await client.connect(async (agent) => {
await agent.request(v2.methods.agent.initialize, {
protocolVersion: v2.PROTOCOL_VERSION,
info: { name: "v2-test-client", version: "1.0.0" },
capabilities: {},
});
return agent.request(v2.methods.agent.session.new, { cwd }).catch((error: unknown) => error);
});
expect(error).toMatchObject({ data: { details: sdk.optionsRefusal.message } });
expect(initialized).toHaveBeenCalled();
expect(disposed).toHaveBeenCalledTimes(initialized.mock.calls.length);
initialized.mockRestore();
disposed.mockRestore();
});
describe("subagents and background work", () => {
it("announces a subagent before its traffic, and reports its runs on its own stream", async () => {
const client = v2Client();

View File

@@ -192,7 +192,7 @@ import {
import { AuthStatusReporter, cliLogout } from "../auth-status-reporter.js";
import { terminalAuthMethods as authMethodsForTerminal } from "../auth-methods.js";
import { McpOverAcp, sdkMcpServers, type UnservedMcpServer } from "../mcp-servers.js";
import { claudeCliPath, mcpServersDelivery } from "../claude-cli.js";
import { claudeCliPath, cliDelivery } from "../claude-cli.js";
import { ContentBlockParam } from "@anthropic-ai/sdk/resources";
import { randomUUID } from "node:crypto";
import type { Stats } from "node:fs";
@@ -7743,16 +7743,18 @@ export class ClaudeAcpAgent {
}
}
/** Release a query that was spawned but never registered as a session. */
/** Release a query that was spawned but never registered as a session, or
* the settings and input of one that the SDK refused to create (`q` is
* undefined). */
private discardUnregisteredQuery(
q: Query,
q: Query | undefined,
input: Pushable<SDKUserMessage>,
settingsManager: SettingsManager,
): void {
settingsManager.dispose();
input.end();
try {
q.close();
q?.close();
} catch (error) {
this.logger.error("Failed to close unregistered Claude query", error);
}
@@ -10224,8 +10226,9 @@ export class ClaudeAcpAgent {
// Before `userProvidedOptions`, so a client that passes
// `promptSuggestions: false` keeps it off.
...promptSuggestionOptions(suggestionForms),
// Before `userProvidedOptions`, so a client's own `mcpServersDelivery` wins.
mcpServersDelivery: mcpServersDelivery(),
// Before `userProvidedOptions`, so a client's own `mcpServersDelivery`
// and `settingsDelivery` win.
...cliDelivery(userProvidedOptions?.extraArgs),
...userProvidedOptions,
// Claude Code uses the same checkpoint store for /rewind. Enable it only
// for clients that negotiated per-turn file-change reports; this avoids
@@ -10415,10 +10418,19 @@ export class ClaudeAcpAgent {
throw new Error("Cancelled");
}
const q = query({
prompt: input,
options,
});
let q: Query;
try {
q = query({
prompt: input,
options,
});
} catch (error) {
// The SDK refuses options that it cannot send to Claude Code, e.g. a
// client's hook matcher without `hooks`: "hooks.PreToolUse[0].hooks must
// be an array of callbacks".
this.discardUnregisteredQuery(undefined, input, settingsManager);
throw error;
}
this.authStatus.useSettings(
settingsManager,
configuredSettingsObject,

View File

@@ -26,6 +26,7 @@ import {
listSessions,
query,
type Options,
type Query,
type SDKUserMessage,
type SessionMessage,
} from "@anthropic-ai/claude-agent-sdk";
@@ -34,7 +35,7 @@ import { messageIdForGrouping } from "../sdk-to-acp.js";
import type { Logger } from "../logger.js";
import { customAgents } from "../session-config-options.js";
import { restrictedChild } from "../acp-subagents.js";
import { claudeCliPath, mcpServersDelivery } from "../claude-cli.js";
import { claudeCliPath, cliDelivery } from "../claude-cli.js";
import { clientSystemPrompt, sessionSystemPrompt } from "../client-system-prompt.js";
import type { ElicitationSupport } from "../elicitation.js";
import { forkSession } from "../fork-session.js";
@@ -1101,8 +1102,9 @@ class V2Agent implements AgentHandle, SessionConnection {
// other client's session spends a request on it.
// Before the client's options: `promptSuggestions: false` turns it off.
...promptSuggestionOptions(this.promptSuggestions),
// Before the client's options: its own `mcpServersDelivery` wins.
mcpServersDelivery: mcpServersDelivery(),
// Before the client's options: its own `mcpServersDelivery` and
// `settingsDelivery` win.
...cliDelivery(client?.extraArgs),
...client,
// The checkpoints that AIR's file-change reports read (see
// `file-changes.ts`), only for a client that declared them, as on v1.
@@ -1175,7 +1177,16 @@ class V2Agent implements AgentHandle, SessionConnection {
...(resume !== undefined ? { resume } : { sessionId }),
...(persist ? {} : { persistSession: false }),
};
const q = query({ prompt: input, options });
let q: Query;
try {
q = query({ prompt: input, options });
} catch (error) {
// The SDK refuses options that it cannot send to Claude Code, e.g. a
// client's hook matcher without `hooks`: "hooks.PreToolUse[0].hooks must
// be an array of callbacks".
settings.dispose();
throw error;
}
let initialization;
try {
initialization = await q.initializationResult();