fix(sse): preserve Claude Code cache breakpoints

[cryptiklemur]

Summary

• Add a cache breakpoint to the latest user message when native Claude Code history has none and the four-breakpoint limit permits it.
• Preserve existing client message breakpoints unchanged.
• Keep supported Opus mid-conversation system blocks in messages[].
• Prevent a mid-conversation cache marker from being hoisted into top-level system, which invalidates the cached conversation prefix.
• Keep the legacy system-message hoist for unsupported models and providers.

Why this change

Anthropic documents two cache behaviors that apply to the affected Claude Code requests.

First, "Cache writes happen only at your breakpoint." Anthropic checks up to 20 blocks behind each breakpoint for a prior write and supports up to four breakpoints. A request with cache markers on static system or tool content, but none in messages[], does not write a recent conversation-prefix entry. As the conversation grows, the last usable write can fall outside the lookback window. This patch adds a marker to the latest user content only when no message marker exists and a breakpoint slot remains. See Anthropic prompt caching.

Second, Anthropic hashes the prompt in tools, system, then messages order. Its documentation says, "A cache hit requires the prefix to match a recent request exactly, byte for byte." Hoisting a system message from the middle of messages[] into top-level system changes an earlier part of that hash and invalidates every cached message after it. Anthropic recommends appending the instruction as a role: "system" message instead because "The cached prefix stays the same." This patch preserves that structure for eligible Opus full-agent requests while retaining the legacy hoist elsewhere. See Anthropic mid-conversation system messages.

The cost difference is material. Anthropic prices a 5-minute cache write at 1.25 times the base input-token rate and a cache read at 0.1 times that rate. Rewriting a large prefix instead of reading it can cost 12.5 times as much for those tokens. See Anthropic prompt caching pricing.

Related issues

• None.

Validation

• Red/green request-path regression for an Opus 5 mid-conversation system cache breakpoint
• Focused handler, cache-control, system-role, beta-flag, and Claude identity tests
• npm run typecheck:core
• ESLint passes for the changed production files
• Prettier passes for all changed files
• Production-code changes include a new or updated automated test in this PR
• SonarQube PR analysis is green or any remaining issues are explicitly documented below
• Production Docker image built successfully for the first commit
• Isolated Opus 5 validation wrote 13,893 cache tokens, then read all 13,893 on the identical request

Tests added or updated

• tests/unit/chatcore-translation-paths.test.ts
• tests/unit/claude-code-parity.test.ts

Coverage notes

The request-path regression runs native Claude passthrough through the executor and inspects the final upstream body. It verifies that Opus 5 keeps the original message order, preserves the mid-conversation cache marker, does not hoist that block into top-level system, and does not add a redundant marker to the latest user turn.

The existing Sonnet and generic-client tests continue to cover the legacy hoisting path. The parity tests cover existing message markers and the four surviving-breakpoint limit.

Reviewer notes

The new behavior is limited to native Claude full-agent requests for supported Opus models. The same eligibility helper controls both the payload behavior and the Anthropic beta header, so unsupported request shapes keep the old normalization.

This PR does not change database state, migrations, or user settings.