[maxmad64bis]

⚠️ base-red inherited: #14004

Summary

Requests to keyless OpenCode models have been answered 403 since 2026-09-17, making the whole oc/*-free catalog unusable. The upstream accepts a request only when all four hold — stream: true, a non-empty tools array, a session header shaped ses_ + 12 hex + 14 base62, and a User-Agent carrying opencode/<version >= 1.17> — and removing any one turns a 200 into a 403. OmniRoute satisfied none. Paid models on the same host are not gated and stay untouched.

The tools condition shapes this PR: the upstream inspects which names are declared. Measured twice per cell on 2026-09-18 — one made-up name, twelve made-up names and twelve plausible names from another vocabulary are all refused; three names from the official client are refused; six or more pass. What is accepted also differs by model and moved between two consecutive days, so no list is worth pinning here.

This PR reuses the one the traffic already carries. A request that goes out with tools and comes back accepted has its tool names remembered for that provider, model and — when the caller supplied a session id — that conversation. A later request of the same conversation carrying no tools goes out with the list its own client declared a moment earlier. That is the failing case exactly: a client sends its builds with a full tool list and its title and compaction requests with none, on one session, and only the second kind is refused (anomalyco/opencode#49433).

Also: a client User-Agent is now preserved only when it already satisfies the contract (the previous rule preserved opencode-cli/…, which the upstream refuses), client ids are translated one-to-one into the accepted shape instead of passed verbatim, and no tool_choice is imposed anywhere — the upstream answers 400 — only "auto" is supported. Supersedes #13937, keeping @AStupidBear's session regex and minimum-version rule.

Related Issues

• Related to [BUG] OpenCode free provider returns 403 for all API requests through OmniRoute #13935

Validation

• Change type: provider
• Focused tests and category gates from the golden path
• npm run lint — clean on the touched files with the repository suppressions; the full run is not green on the base
• Reconciled with the current active release base; focused checks rerun afterward
• Production-code changes include a new or updated automated test in this PR

Tests Added Or Updated

• tests/unit/opencode-free-tier-request-contract.test.ts — 36 cases over scope, both body shapes, the reuse path (teach, borrow within a conversation, conversation list beating the shared one, drop after three refusals in a row, a refusal on the caller's own tools changing nothing) and both settings.
• opencode-cli-headers-synthesis-5997, opencode-session-fingerprint-headers-10571, refactor-buildHeaders-opencode, opencode-executor (updated): these pinned values the upstream now refuses — UUID ids, opencode-cli/… preservation, the bare opencode user-agent, a UUID session for Muse Responses.

Negative controls on each new guard: lowering the refusal threshold, reintroducing tool_choice, dropping the session from the store key and neutralising the store each fail the cases covering them.

Coverage Notes

• New opencodeToolObservation.ts and the contract module: recording, scoping, resolution order, streak-based dropping, bounds, both body shapes, idempotence and the stream rebuild.
• opencodeHeaders.ts and opencode.ts: canonical rendering, translation, the client-session reader, the Accept decision and the rebuild through the real executor with a stubbed upstream. Neighbouring opencode suites stay green.

Reviewer Notes

What is stored. Tool names only, never a schema or conversation content; the placeholder built from them carries an empty parameter object and the client's own "do not call this tool" description. In memory, 32 names per entry, 64 entries, least-recently-confirmed eviction.

Resolution order is conversation, model, configured list, single placeholder. The model step means one caller's tool names can be declared on another caller's request in the same instance. A borrowed list is dropped only after three refusals in a row, and only on requests that borrowed it — the same body was refused then accepted on one free model minutes apart, so one verdict is not proof.

Scope comes from the surface derived from the registry baseUrl, not from provider ids. /zen/go/v1 refuses requests carrying tools (#44300, #44382 upstream) and is never brought up to this contract, including for ox-alpha-free; that rests on those reports, since this installation exposes no model there. Background calls (discovery, quota fetcher) hit the same gate and are out of scope — #13005 covers them.

Ordering with open PRs on these files. #13819 strips stream_options unless the body is OpenAI-format with stream: true, which this PR sets in transformRequest — whichever lands second should check the strip reads the transformed body. #12719 synthesizes a session without canonical rendering on the opt-out path, a shape the upstream refuses; it should reuse the renderer kept here.

Inherited gates. check-api-typecheck fails identically at the bare base (codex-responses-ws/route.ts, chat.ts), neither touched here; the test file-size gate flags chatcore-translation-paths.test.ts, untouched, same drift as #14004. opencode.ts leaves this PR shorter than it entered (1192 → 1189), no rebaseline.