Files
PaperClipAI/packages
Nicky LeachandClaude Fable 5.2 7866e9ef05 fix(acpx): admit a Claude tool call only for a tool use its turn announced (#21278)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner runs Claude Code through the ACPX sidecar. Claude
calls Paperclip tools through a Runner-owned MCP endpoint, the tool
bridge.
> - The bridge identifies a call by its JSON-RPC request id. That id
does not say which turn sent the call. The sidecar binds a call to the
turn that is active when the call arrives.
> - Because of this, the Runner stops and starts the Claude process at
each turn boundary. A late call from an earlier turn then cannot run in
a later turn. This restart also stops all background work that Claude
started.
> - Claude Code already sends the missing identity. Each MCP
`tools/call` has `_meta["claudecode/toolUseId"]`. It is the id of the
ACP `tool_call` that the provider announces first, inside one turn.
> - This pull request uses that id. The sidecar admits a Claude tool
call only if the active turn announced its tool use.
> - The benefit is that a call from an earlier turn is refused by its
identity. This is the first step to keep the Claude process alive
between turns. This pull request does not change the restart.

## Linked Issues or Issue Description

No public issue exists. The issue is described here.

Refs #19912 (the design for turn-scoped ACPX MCP authority), #12419 (the
restart at turn start) and #20190 (the restart at turn end).

This pull request is the bottom of a stack. #21274 is merged, so the
base branch is `master`. It uses no code from #21274. The stack order
lets a later pull request remove the direct gateway path after both.

**What existing behavior does this improve?**

How the Runner decides which turn a Claude tool call belongs to.

**Subsystem affected**

Paperclip Runner: the tool bridge and the ACPX sidecar, for the Claude
provider only.

**Current behavior**

- The bridge keys a call by the JSON-RPC request id
(`runner-tool-bridge.ts`).
- The sidecar gives the call to the active turn (`waitForTool` in
`acpx-runtime-sidecar.ts`).
- After `session/cancel`, Claude Code does not stop an MCP request that
is in flight. A test run showed two calls from two turns live at the
same time on one MCP session. Request ids cannot tell them apart.

**Proposed behavior**

- The bridge can read a provider tool-use id from `params._meta` and
give it to the handler. It keys replays by that id.
- For Claude, the sidecar admits a call only when the turn event stream
of the active turn contains the ACP `tool_call` with the same id, and no
earlier call used that id.
- The announcement and the call use different channels. If the call
arrives first, the sidecar waits for the announcement for a maximum of 5
seconds. The wait stops when the turn ends or the call is cancelled.
- A call with no id, an id from an earlier turn, an id that was never
announced, or an id that was used before gets a tool error. There is no
fallback.
- The call id that the sidecar sends to runnerd is `tool-use:<id>` for
Claude.

**Reason and benefit**

- A late call from an earlier turn cannot run in a later turn. The
identity of the call prevents this, not only the process restart.
- A later change can stop the restart between turns.

## What Changed

- `packages/paperclip-runner/src/drivers/runner-tool-bridge.ts`
- New option `providerToolUseIdMetaKey`. Without it the bridge does not
change.
- With it, the bridge reads `params._meta[key]`. It refuses a value that
is not a bounded string. It gives a valid value to the handler as
`providerToolUseId`.
- The replay key is the tool-use id. A retry with a new request id
replays the first result. The same id with different arguments is
refused.
  - `notifications/cancelled` still finds the call by its request id.
-
`packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts`
(new): `ClaudeToolUseAdmission`.
- `observe` records an id only from an event with `type === "tool_call"`
and `tag === "tool_call"`. A `tool_call_update` does not count, so a
late update about an old tool use cannot admit it.
- `admit` applies the rule above. An id is used when it is admitted.
Limits: 4,096 announcements for each turn and 8,192 admitted ids. At a
limit, new calls are refused.
- `packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts`
- The sidecar creates the admission object only for `agent === "claude"`
and sets the bridge option only for Claude.
- `pumpTurn` gives each turn event to `observe`. `waitForTool` calls
`admit` and then checks the turn and run again.
- The internal `get_task_context` call for a completion continuation
does not go through admission.
- The Claude call id does not use the per-process namespace, because a
tool-use id is unique.
- No change to Rust, the sidecar contract, the `claude-agent-acp` patch,
the server, or restart, park and turn lifecycle code. Other ACPX agents
and Cursor Cloud use the same code path as before.

Why 5 seconds: the measured time between the announcement and the call
is 1.1 ms to 14.7 ms. The limit must also include queue and event-loop
delay. 5 seconds is far above that, and a call that cannot be attributed
still gets a fast answer.

## Verification

Commands, from `packages/paperclip-runner`:

- `npx vitest run
src/drivers/acpx/acpx-runtime-adapter.claude-tool-use.test.ts
src/drivers/acpx/claude-tool-use-admission.test.ts
src/drivers/runner-tool-bridge.test.ts
src/drivers/runner-tool-bridge.claude-tool-use.test.ts
src/drivers/runner-tool-bridge.claude-schema.test.ts
src/cli/acpx-runtime-sidecar.test.ts
src/drivers/acpx/acpx-runtime-adapter.test.ts
src/drivers/cursor-cloud/cursor-cloud-driver.test.ts`: `8 passed (8)`
files, `384 passed` tests.
- `npx tsc --noEmit -p tsconfig.json`: no errors.

New tests:

- **Real ACP runtime** (`acpx-runtime-adapter.claude-tool-use.test.ts`).
It uses the real `openCodexAcpxRuntime`, ACPX 0.22, the pinned and
patched `claude-agent-acp`, the pinned Claude Code client and a real
tool bridge, against a local fake Anthropic API.
- Turn 1: two parallel tool uses are admitted as `tool-use:<id>`. The
model receives both results. The turn completes.
- Turn 2 in the same session: a replay of a turn 1 id returns the cached
result and does not dispatch again. The same id with different arguments
is refused. `admit` refuses the old id.
- In five runs each call arrived 6.9 ms to 13.2 ms after its
announcement. No call waited.
- **Qualification** (`runner-tool-bridge.claude-tool-use.test.ts`). The
pinned Claude Code client sends `_meta["claudecode/toolUseId"]` on each
`tools/call`, with the id that the API issued. This test must pass
before a Claude Code version change.
- **Admission unit tests** (19): announced then called, called then
announced, never announced, turn end during the wait, cancel, an id from
the previous turn, reuse, two concurrent calls with one id, two turns
with live calls, a subagent call, a bad id.
- **Sidecar process tests** (2), with a fake host, for Claude and for
Codex. The Codex run shows no change.
- **Bridge unit tests** (5).

Mutation checks:

- Change the announcement predicate so that it matches nothing: the real
ACP test and one unit test fail.
- Remove the bridge option in the real ACP test: the test fails.
- Count only `tool_call_update`: the unit test "counts only an opening
ACP tool_call event as an announcement" fails.

Live run with a real Claude account, not in CI: the real ACP runtime
(ACPX 0.22, the patched `claude-agent-acp`, the pinned Claude Code
client), a real tool bridge, and the real Anthropic API with model
`claude-sonnet-5-5`, on the code at the top of this stack. In three
sessions, 8 Paperclip tool calls were admitted and none was refused.
This includes calls in a prompt turn, in a cycle that Claude started
itself, and in a later turn of the same process. Each call arrived 0.8 s
to 1.7 s after its announcement, so no call waited for a late
announcement.

Not run: a turn through the real sidecar process with the real host.
That needs a qualified provider installation, the runtime sandbox and
the provider lifetime lease. Not run: the Linux builds of the pinned
client and a test under load. Not run: `pnpm verify` and the full suite.
CI supplies that coverage.

## Risks

- **This changes each Paperclip tool call that Claude makes.** If the
announcement does not reach the turn event stream in production, the
sidecar refuses the call after 5 seconds. The real ACP test covers the
stream of ACPX 0.22 with the pinned provider. It does not cover the real
sidecar host.
- **The 5 second limit is not tested under load.** A slow host can delay
the announcement. The call is then refused, and Claude sees a tool
error.
- **A Claude Code version that stops sending the id breaks all Claude
tool calls.** The qualification test finds this before the version
changes.
- **The admitted-id ledger is in sidecar memory.** Today the sidecar
restarts at each turn boundary, so the ledger is small. The limit of
8,192 ids refuses new calls when it is full.
- **Subagent calls and calls from a cycle that Claude starts itself**
are covered by unit tests and fake-host tests, not by the real ACP
stream.
- **An admitted call that is in flight when its turn ends** is refused
by the existing turn cleanup. Claude Code can leave the HTTP request
open. The bridge stops it only on its own cancel or close, as before.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`) in Claude Code planned the
change, reviewed the diff, asked for the real ACP runtime test, and ran
the verification and a mutation check again.
- Claude Opus 5.5 (`claude-opus-5-5`), as a Claude Code subagent with
tool use (shell, file edits, local test runs), wrote the change and the
tests.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 11:56:42 -08:00
..