docs(opencode): explain Claude 32k thinking cutoff and workaround

[rexdotsh]

Summary

Document the OpenCode V2 Claude output-limit regression and a client-side, opt-in workaround. This PR does not modify the Kleis proxy or anyone's request budget. It is independent of #49.

Root cause

• OpenCode commit 99490f289b (August 20) changed the Anthropic Messages transport from a model-derived output limit to a fixed 32k fallback when generation.maxTokens is absent. It predates V2 2.0.0, the first V2 release. Released V2 through 2.0.18 still leaves primary generation options empty by default.
• OpenCode commit d9987ef9c8 sets a model-based primary output limit and fits it to remaining context. It landed after the 2.0.18 release commit; do not assume 2.0.18 includes it.
• The matching local turn (msg_0e19bee88001XHOV0SysxSldcH) had rawFinish: max_tokens, 32,000 reasoning tokens, zero answer tokens, and a normal terminal response. This is not evidence of a Kleis SSE disconnect.
• Kleis perf(proxy): read and parse request bodies once #51 moved body parsing earlier but kept Claude's requested max_tokens; Harden Claude OAuth refresh and recover pre-output 401s #43 changed token replay/refresh; chore: remove Copilot support #32 removed Copilot. The Opus 5.5 user-agent bump enabled access to that model, but did not set the output budget.

Why documentation, not a proxy rewrite?

Kleis receives max_tokens: 32000 and cannot distinguish an intentional caller limit from OpenCode's fallback, nor compute OpenCode's remaining context room. The previous #52 draft silently changed some callers' budget to 128k based on a version regex; that is unsafe. The README instead shows an optional V2 context hook scoped to Kleis Opus 5.5 max-effort requests, and recommends upgrading only to a release containing the upstream fix. Installing the hook remains an explicit client-side choice.

Checks

• bun test (140 passing)
• bun typecheck
• bun lint

No live Claude request or service restart was performed. Leave this PR and #49 unmerged pending review.