Skip to content

fix(free-tier): restore official tool names and drop ghost tool calls - #166

Merged
jasonxu114514 merged 1 commit into
jasonxu114514:mainfrom
cheerc:fix/free-tier-tool-name-restore
Nov 5, 2026
Merged

jasonxu114514 merged 1 commit into
jasonxu114514:mainfrom
cheerc:fix/free-tier-tool-name-restore

Conversation

@cheerc

@cheerc cheerc commented Oct 29, 2026

Copy link
Copy Markdown
Contributor

What

Shaped free-tier bodies put two sets of tool names on the wire: the renamed client tools (clint_<digest>) and the appended official set (shell, grep, glob, read, task, …). Only the first set was understood on the way back, so any official tool the model picked, any mangled digest name (clit_…, clnt_…), and any ghost call left in history reached the client verbatim and became Error: No such tool available: ….

This PR teaches the response and history paths about the names the gateway itself sends.

  • Response mapping resolves official names to the tool the client actually declared: shell/bash → Bash, read → Read, edit → Edit, write → Write, webfetch → WebFetch, websearch → WebSearch, skill → Skill, glob → Glob, grep → Grep, task/subagent → Agent, question → AskUserQuestion, todowrite → TodoWrite, patch → Patch. When the client declared no equivalent the name is left alone instead of being guessed.
  • Request history is sanitised for Anthropic, Chat and Responses. A call whose name is neither declared nor equivalent to a declared tool is removed with its paired result (tool_use_id / tool_call_id / call_id); an official name with a declared equivalent is rewritten to that tool's wire name; a named tool_choice pointing at a removed tool is dropped.
  • Chat stream rewriting no longer treats a name as complete just because the same delta carries an arguments field. While the accumulated name is still a prefix of a known wire name, the arguments are held back and released together with the resolved name, or flushed verbatim at finish_reason / EOF.

Digest naming, the official system prompt, the appended official set, and 429/403 classification are untouched.

Why not just drop the official set?

That would remove the shell class at the source and is the better end state, but #163/PR #161 showed the free tier's gate is sensitive to body shape, and dropping the set needs an upstream replay against a captured Claude Code request to prove the 429 does not return. That replay costs free quota and IP reputation, so it is left for a follow-up rather than folded into this fix.

Verification

Run in a scratch copy of 2bf547c against a captured Claude Code request (Anthropic /v1/messages → Chat) shaped through PrepareRequest + prepareAnonymousBody:

check result
Resolve("shell") → Bash; "bash"/"read"/"edit"/"write"/"webfetch" map likewise pass
exact clint_9b9a8d05a7ec → Read unchanged pass
clit_9b9a8d05a7ec / clnt_9b9a8d05a7ec stay unchanged pass
client declares no Grep/Glob → those names are not invented pass
history carrying clit_… and shell: mangled call and its result removed, official call rewritten to clint_d1e9567da9a8, zero orphan tool messages pass
full captured request: zero orphan tool_result across 586 tool blocks pass
split Chat name with interleaved arguments emits "name":"Read" and arguments {"x":1} pass
single-frame tool call output unchanged pass

Also run in the repo: gofmt -l . (empty), go vet ./... (clean), go build -trimpath ./cmd/opencode2api (clean), git diff --check (clean).

Not verified, and deliberately so: whether the client accepts the official tool's extra argument fields when its own schema is narrower (shell carries optional background/workdir; task/subagent differ from Agent). Only the name is rewritten; arguments are passed through as the model produced them. No upstream replay was run.

No _test.go is added — the released tree is kept test-free per 2bf547c; the probes above live only in a scratch copy.

Related

Follows #163 / PR #161. Closes #165.

🤖 Generated with Claude Code

A shaped free-tier body appends the lane's official tool set (shell, grep,
glob, read, task, …) and the official system prompt names those tools. Models
follow it and call `shell` / `grep` / `glob`, but the downstream client never
declared those names, so Claude Code answers "No such tool available: shell".
The same happens to mangled wire names (`clit_…`, `clnt_…`) and to leftover
tool calls such as `d4e3b...`, which were forwarded verbatim and then imitated
on later turns.

Response mapping now resolves an official name to the client tool the client
actually declared (`shell`/`bash` → `Bash`, `read` → `Read`, `edit` → `Edit`,
`task`/`subagent` → `Agent`, `question` → `AskUserQuestion`, …). When the
client declared no equivalent, the name stays unchanged instead of being
guessed.

Request history is sanitised for Anthropic, Chat and Responses: a call whose
name is neither declared nor equivalent to a declared tool is removed together
with its paired result (tool_use_id / tool_call_id / call_id), an official name
with a declared equivalent is rewritten to that tool's wire name, and a named
tool_choice pointing at a removed tool is dropped.

Chat stream rewriting no longer treats a name as complete just because the
same delta carries an `arguments` field. While the accumulated name is still a
prefix of a known wire name the arguments are held back and released with the
resolved name, or flushed verbatim at finish_reason / EOF, so a name split over
chunks cannot leak a partial or wire name to the client.

Verified in a scratch copy against a captured Claude Code request: shell, bash,
read, edit, write and webfetch resolve to the declared client tools while
`clit_…`/`clnt_…` pass through untouched and undeclared official names are not
mapped; history sanitisation leaves zero orphan tool results across 586 tool
blocks; a split name with interleaved arguments emits `Read` with intact
arguments and a single-frame call is unchanged. gofmt, go vet and go build
pass.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@jasonxu114514
jasonxu114514 merged commit 87e7983 into jasonxu114514:main Nov 5, 2026
5 checks passed
froyoandroid added a commit to froyoandroid/opencode2api that referenced this pull request Nov 10, 2026
…e WARP egress embargo

Upstream shipped the same jasonxu114514#165 fix independently (jasonxu114514#166) and did it more
completely: Responses-protocol coverage, paired-result removal keyed on
tool_call_id / tool_use_id / call_id, a named tool_choice dropped with the
call it names, and Chat name fragments whose arguments arrive in the same
delta now held back until the name resolves. Took theirs whole and dropped
our narrower alias table and history pass.

Three conflicts, all resolved toward upstream except where our work adds a
layer upstream lacks:

- warp/pool.go: upstream's penalizeFor honours the upstream Retry-After and
  adds HasUntriedActive. Kept both, and the quota embargo now takes that
  Retry-After as its window instead of a fixed ten minutes, so an egress is
  skipped for exactly as long as the upstream asked.
- protocol/stream.go: upstream's pendingArguments buffering replaces our
  simpler name-hold. Kept it, and re-added the tool-call id synthesis on top:
  a call whose fragments carry no id still gets one, minted once and repeated,
  because a strict OpenAI client aborts the turn otherwise.
- gateway/pool.go: both sides added CursorForOffset; dropped ours. Our
  CursorFor had been rewired to delegate to it, which recursed once the
  duplicate went -- restored upstream's body.

go build, go vet, gofmt and all six test packages pass.
@cheerc
cheerc deleted the fix/free-tier-tool-name-restore branch November 15, 2026 09:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Shaped requests leak official tool names (shell/grep/glob) and ghost tool calls, so client tool calls fail

2 participants