feat(gateway): answer Claude Code's one-token model probes

[Menci]

Problem

Switching models in Claude Code fails against any model whose candidate translates Messages to Responses:

❯ /model gpt-5.6-sol[1m]
  ⎿  API error: 400 {"error":{"message":"Invalid 'max_output_tokens': integer below minimum value. Expected a value >= 16, but got 1 instead.","code":"invalid_request_body"}}

Claude Code validates a model by generating one token against it. /model <id> issues a non-streaming POST /v1/messages?beta=true with max_tokens: 1 and a fixed throwaway prompt, and calls the model unusable if that request throws.

Upstream research

Decompiled from the Claude Code 2.1.226 binary — the model_validation side query:

await eie({model:r, max_tokens:1, maxRetries:0, querySource:"model_validation",
  messages:[{role:"user",content:[{type:"text",text:"Hi",cache_control:{type:"ephemeral"}}]}]}),
  lra.set(r,!0), {valid:!0}

The verdict is "did not throw". The path dereferences usage.input_tokens / usage.output_tokens unguarded to populate the CLI's own telemetry event, and reads _request_id, stop_reason and the cache counters behind ??. A missing usage throws inside the CLI and reads as a failed probe.

The CLI runs several other one-token probes, each from an independent call site rather than through eie: quota (rate-limit preflight), test (credential verification), . (Bedrock / Vertex / Mantle reachability).

A one-token cap is not portable: OpenAI's Responses API floors max_output_tokens at 16 and rejects anything lower outright.

Prior art: CLIProxyAPI#3571 proposes short-circuiting on max_tokens === 1 alone — it is open and unmerged, and CLIProxyAPI ships no such short-circuit today. LiteLLM#35061 reports this exact symptom and fixes it from the other side, by rewriting the upstream's output-limit error.

Change

An unconditional answerClaudeCodeProbe Messages interceptor, registered ahead of the rest of the chain because it replaces the turn rather than shaping it. On a match it answers with a turn that stopped at the one-token cap: no content blocks, stop_reason: max_tokens, zero usage.

Detection requires all of: the claude-cli/<semver> User-Agent prefix, max_tokens: 1, no tools, and a single user turn whose text matches one of Hi / test exactly.

The synthesized turn needs an Anthropic-shaped msg_ id, which the Messages error envelopes already minted privately. That generator moves to @floway-dev/protocols/messages as generateAnthropicId, alongside createRandomResponsesItemId, its counterpart on the Responses side — the id shape is a property of the wire contract, not of the gateway that happens to synthesize bodies carrying one.

Decisions worth a look

• Which probes we answer. Only the ones a synthesized turn can satisfy honestly. quota is excluded because its caller reads the anthropic-ratelimit-unified-* response headers, not the body — answering it would replace a working quota reading, on every upstream that serves the probe today, with a silent blank. . is excluded because it only ever reaches a Bedrock / Vertex / Mantle base URL.
• Exact matching. Every accepted literal is read off a binary rather than inferred, so an unobserved shape reaches the upstream instead of being answered from a guess. The cost is that these literals are a Claude Code build detail: a release that renames one re-exposes the 400 until the new literal is read off that build and added.
• Interception sits after model resolution, inside the per-candidate interceptor chain. An id no upstream serves therefore still fails with a 404 and the CLI still reports it not found — real model validation is preserved; only the pointless generation behind the probe is suppressed.
• Telemetry. The intercepted turn makes no upstream call and records a usage row with requests: 1 and no metrics — visible in the dashboard, billed at zero. It attaches no performance context, so it contributes no latency sample: there was no upstream call to measure.
• Not done: clamping. LiteLLM's route — raising max_tokens to the target's floor and passing through — keeps real upstream validation but bills a real turn. Out of scope here, and the two are not mutually exclusive.

Test Plan

Driven against a local Node instance with a fake OpenAI-compatible upstream that reproduces the max_output_tokens >= 16 floor.

• Real claude CLI: /model gpt-5.6-sol[1m] reports Set model to gpt-5.6-sol[1m] for this session only instead of the 400
• The switch produces zero upstream requests, one usage_requests row, zero usage token-metric rows, and zero performance_summary rows
• A real inference turn on the switched model still proxies and bills normally — 7 input / 3 output, one upstream request
• A model no upstream serves is still rejected — the CLI reports There's an issue with the selected model
• Streaming probe variant emits a well-formed message_start → message_delta → message_stop SSE sequence
• pnpm run typegen, pnpm run lint, pnpm run typecheck
• pnpm run test — 534 files / 5531 tests
• pnpm run test:installers, pnpm run check:agents-md, pnpm run check:generated-assets, pnpm run check:verify-parity, pnpm run build:web