feat(claude): gate lossy translated Messages with bounded diagnostics

docs-site/src/content/docs/reference/configuration/server.md

@@ -317,12 +317,32 @@ These settings govern `/v1/messages`, `/v1/messages/count_tokens`, the `ocx clau
 | --- | --- | --- | --- |
 | `claudeCode.bodyStallSec?` | `number` | `90` | Native-passthrough body inactivity budget in seconds while a read is pending, not total duration. Minimum 1; exactly `0` disables. |
 | `claudeCode.bodyMaxBytes?` | `number` | `67108864` | Cumulative native-passthrough body cap for streamed and buffered responses. Exactly `0` disables. |
+| `claudeCode.compatibility?` | `"shadow" \| "enforce"` | unset | Optional compatibility admission for translated `/v1/messages` requests. `shadow` records unsupported features and continues; `enforce` returns an Anthropic-shaped 400 before inference. Native Anthropic passthrough remains unchanged. |
 | `claudeCode.authMode?` | `"proxy" \| "subscription"` | auto | How launch handles `ANTHROPIC_AUTH_TOKEN`. Auto detects auth each launch; an explicit value is never overridden. |
 | `claudeCode.authModeMigratedAt?` | `string` | unset | Internal one-time upgrade marker. Do not set manually. |
 | `claudeCode.classifierModel?` | `string` | unset | Explicit target for Claude Code Auto Mode classifier turns, as a qualified `provider/model` (for example `RelayA/claude-opus-5`). Auto Mode sends bare safety checks such as `claude-opus-5` with no provider, so without this they fall through to `defaultProvider` — which may not speak Anthropic at all. Nothing is inferred automatically: only a target you declare here is used. |
 | `claudeCode.classifierFallbacks?` | `string[]` | unset | Ordered classifier targets used when `classifierModel` is not set. Same qualified `provider/model` form; the first usable entry wins. An explicit `modelMap` entry for the classifier model still outranks both. |
 | `claudeCode.subagentEffort?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | inherit | Effort written to generated `~/.claude/agents/ocx-*.md`; separate from Codex guidance and proxy caps. Restart through `ocx claude` to regenerate. |
 
+The compatibility policy applies to Claude Code, Desktop and other clients using translated
+Messages, including `?beta=true` and non-streaming requests. Every translated target uses the
+same conservative policy, including Anthropic and native Responses adapters. It rejects
+document content, thinking/redacted-thinking replay, hosted search and execution tools,
+tool-search references, active deferred loading, strict tools, non-default caller modes,
+structured-output formats, explicit service-tier intent, MCP connector features, context
+management, containers, inference placement and unsupported protocol fields or blocks.
+
+Unset preserves legacy translation. Cache hints, tool input examples and ordinary
+thinking/effort settings are deliberately admitted with possible degradation: this setting
+does not guarantee cache breakpoints or TTL, retained examples, exact thinking budgets or
+lossless translation. Beta headers alone are not validated for feature support. Shadow
+evidence contains only fixed protocol codes and derived reasons, retained in request logs
+and `usage.jsonl` and restored on restart. An invalid non-unset mode returns a fixed 503
+configuration error on translated Messages. Configure the value in `config.json` and
+restart the proxy to load it; there is no dedicated GUI setter. Count-tokens and direct
+Responses/Chat APIs are outside this policy; successful token counting does not imply
+Messages admission. This setting does not add a global authorization boundary.
+
 Auto auth selects subscription when stored Claude auth is found, proxy when none is found, and
 subscription with a warning when detection is inconclusive. See
 [Claude Code auth mode](/guides/claude-code/#auth-mode).

docs-site/src/content/docs/reference/proxy-formats.md

@@ -260,6 +260,14 @@ It does not issue an additional inference request. An incomplete response caused
 token limit or content filtering retains `length` or `content_filter`, even if it includes tool
 output. Other incomplete boundaries return an upstream error instead of claiming a normal finish.
 
+Refusal text stays separate from answer text: JSON completions use nullable `message.refusal`,
+and streaming chunks use `delta.refusal`. Native Chat JSON-to-SSE and SSE-to-JSON conversions
+preserve that field; native streaming relay preserves the provider's refusal deltas. On translated
+Responses streams, refusal parts are buffered until the terminal event and emitted once in their
+original output/content order. Compatible repeated or sparse snapshots do not duplicate or erase
+text. Contradictory refusal snapshots and buffer overflow produce a typed error without a successful
+finish or `[DONE]`. This preserves the upstream refusal; it does not introduce a proxy policy decision.
+
 Because the internal execution path is Responses-based, a provider adapter can impose a narrower
 feature set. For example, a request feature that cannot be represented by the selected adapter is
 returned as an error instead of silently changing its meaning.

scripts/test-layout/layout.json

@@ -271,6 +271,7 @@
     "catalog-vision-sidecar-modalities.test.ts": "codex-integration",
     "chat-completions-endpoint.test.ts": "responses",
     "chat-json-sse-fallback.test.ts": "responses",
+    "chat-refusal.test.ts": "responses",
     "chatgpt-device-auth.test.ts": "oauth",
     "chatgpt-oauth.test.ts": "oauth",
     "chatgpt-token-expiry.test.ts": "oauth",
@@ -289,6 +290,7 @@
     "claude-authmode-migration.test.ts": "claude-integration",
     "claude-cli.test.ts": "claude-integration",
     "claude-code-thought-signature-scope.test.ts": "claude-integration",
+    "claude-compatibility.test.ts": "claude-integration",
     "claude-context-windows.test.ts": "claude-integration",
     "claude-desktop-1m.test.ts": "claude-integration",
     "claude-desktop-cli.test.ts": "claude-integration",