Epic: make Claude 5.x reliable on existing transports #4580

🤖 Automated architect agent — this comment was posted by the architect bot from Docker Agentic Platform, not by a human engineer

What

Track reliable Claude 5.x behavior on docker-agent's existing transports, delivered as complete user-facing increments rather than request serialization first and history safety later.

The outcome is: preserve user intent; serialize supported requests correctly; preserve signed history exactly or refuse unverifiable continuation; and attribute usage/cost to the model and endpoint that actually served the response.

This is an approved issue-publication plan, not an implementation launch. Implementation base/SDK selection, PR publication, reviews, merges and eventual closure of #4553 remain separate authorizations. No code or live-model validation is claimed by these issues.

Scope and evidence boundary

Three specialized native paths exist: Anthropic Messages (standard/Beta), Google publisher: anthropic through native Vertex prediction, and AWS Bedrock ConverseStream. Custom Anthropic-compatible base_url endpoints and Models Gateway reuse a client protocol; OpenAI-compatible aggregators use a different one. A provider name or catalog entry does not establish host capabilities, signature portability, beta support or prices.

Documentation audited on 2026-10-13 gives the following model/platform matrix. “Documented” is not “implemented and tested in docker-agent” or proof of region/account entitlement.

That is 24 corroborated model/platform pairs + 2 limited-access Google announcements + 1 explicitly unsupported pair, not 26 passing tests. AWS identifiers additionally use anthropic. and model-specific inference-profile qualifiers. Dateless 5.x IDs are pinned snapshots, not rolling aliases; normalization for capability lookup must not rewrite the wire ID or prove producer equivalence.

Excluded: new native Mantle, InvokeModel, Bedrock Messages, Claude Platform on AWS or Foundry transports; client refusal-retry middleware; hidden retries or mode changes; destructive history reset/purge/epochs; a new session engine; global catalog/dependency refresh; cloud consent/retention/account changes. Native Vertex compaction expansion is also outside this series.

Why

The vendor contracts and existing implementation gaps are different kinds of evidence:

• The migration index, thinking contract and effort contract require model-specific treatment of adaptive thinking, disabled/between-tools modes, sampling, forced tools and assistant prefill. One broad “version >= 5” rule cannot encode those differences.
• Preserved thinking requires unchanged signed blocks and the relevant prefix/sequence. Its mismatch section calls error the default and describes drop_block as a stopgap, with potential extra output-token cost. The current client default instead auto-selects drop_block for some models. Changing that is an explicit client-policy decision, not a claim that today's client already follows the API default.
• The AWS Mythos 5 card and endpoint availability table exclude Mythos 5 from runtime/Converse and place it on Mantle. The Mythos 5.1 card and endpoint table establish the reverse. Adding a model ID cannot add a missing transport.
• AWS compaction explicitly says neither compaction mechanism is supported by Converse; both work with InvokeModel. Anthropic compaction documents Google availability, whereas the current Vertex integration rejects it. Service support and integration support must not be conflated.
• Server fallback adds ordered boundaries, rules for superseded tools, per-attempt usage.iterations, and sticky routing without a fallback marker. A request option alone is not end-to-end support.
• Internal defects have source evidence rather than invented vendor mandates: clone failure returns the original provider; Vertex rewrites catalog identity before later reconstruction; Converse reconstructs signed content from flattened fields; routed pricing is already tracked in Rule-based routing: routed requests are priced with the router's model, not the model that served them #4576.

Source links pin the research revision 49e4ca657fd454e9d46ea258e8cf61c517df9aab; this does not select a future implementation base. Findings above are static inspection and documentation, not runtime reproduction.

How — recommended design and delivery

Use one explicit capability table, one pure effective-policy resolver, the three existing native serializers, and the existing ProviderState/persistence mechanisms. Resolve policy after inheritance/environment expansion and transport/host selection; validate the final request. Keep capability identity, wire ID, display alias, actual producer/provenance and pricing identity separate. State that varies between conversations belongs to a request/response/session, not a shared provider client.

Approved product decisions

1. No new transport; refuse Mythos 5/Converse before inference when statically identifiable.
2. New 5.x default: append-only / error; drop_block only when explicitly selected, with diagnostics. No automatic retry without thinking. Use native binding only where its mapping is documented; do not invent a Converse beta/diagnostic mapping or impose a universal local adaptive-prefix rejection.
3. The core may ship before full server fallback only with a visible temporary gate: reject nonempty fallbacks whenever the primary or any explicit target is one of these nine 5.x models. Absent/empty fallback permits ordinary requests. Entirely non-5.x fallback remains unchanged and tested. A legacy primary targeting 5.x is subject to the gate. Histories requiring an unsupported fallback boundary fail intact, not after stripping data.

P1 and P2 provide independent benefits on today's product. P4 must ship request activation, signed-state safety, lifecycle behavior, UI/helpers and its tests/docs together; no unsafe intermediate activation flag. P5 lifts the temporary fallback gate only when its end-to-end contract is complete.

External P3 dependency — do not duplicate or presume coverage

#4576 already has a PR being prepared separately, according to the owner. Leave that issue and workstream untouched. P4/P5 need immutable per-stream origin, selected-leaf endpoint/configured-price context and persistence/concurrency behavior—not a shared “last selected model” lookup. Review the eventual PR's coverage later; neither opening nor merging a pricing fix automatically proves all of that contract. Report any gap before implementation rather than silently expanding that work or duplicating it.

#4116 remains related, separate work on cache-preserving effort changes, not a new dependency. Preserve or safely refuse its existing compositions if they are present on the eventual base.

Acceptance and completion

• All four child workstreams and the required external origin/pricing contract are delivered, reviewed and validated; cross-links and the actual implementation PRs are recorded.
• The acceptance matrix distinguishes pass/fail/not-established/expected-refusal by model, transport and feature. Limited access is not a synthetic PASS. No required lifecycle composition is silently omitted.
• Each code PR includes its tests, docs and examples; config changes affect latest plus schema/examples, never frozen numbered versions. Run canonical task build, task test, task lint, relevant targeted/race/shuffle checks and independent review of the exact final head during the separately authorized implementation phase. Retain failure/setup/timeout evidence; no implicit waivers.
• Legacy models, non-Claude providers, embedders and entirely non-5.x fallback retain their tested behavior. Unknown state versions are not silently flattened and re-certified. No destructive migration or promise of transparent downgrade when an older reader cannot preserve the new state.
• Keep fix: make Haiku 5.5 requests compatible across Claude providers #4553 open and draft until core and fallback replacements have merged, Haiku coverage is mapped, and closure is separately authorized. Documentation/clone/pricing work or this epic's creation alone does not supersede it.
• Track issue, PR, authorized base SHA, reviewed head SHA, review/CI evidence, shipped behavior, remaining limitations and release. A merged PR and an available release are distinct facts; issue publication is neither.

Implementation PR linkage: pending. No implementation PR is created or claimed by this publication.

External pricing work: PR #4579 — price routed turns using the serving model is now listed as open. Discovery only; not reviewed here. This link does not establish the full per-stream origin/P3 contract or per-attempt fallback accounting. Do not duplicate or intervene in that workstream.

Linked work and delivery order

Child delivery checklist (issue creation is not implementation completion):

• docs(Claude): document existing backends, protocols and feature limits [P1; independent] #4581
• fix(provider): preserve transport and surface clone failures [P2; independent] #4582
• feat(Claude): ship atomic 5.x request and signed-history safety [P4; depends on #4582, #4576 contract] #4583
• feat(Claude): enable end-to-end 5.x server fallback [P5; depends on #4583, #4576 contract] #4584

#4581: independent; recommended first, not a technical blocker
#4582 ──────────────────┐
                        ├──> #4583 ───> #4584
#4576 required contract ─┘                 ^
          └───────────────────────────────┘

#4582 and the external #4576 work can ship in either order. Later review must establish what #4579 actually covers; this epic neither changes its acceptance criteria nor starts a duplicate pricing effort. #4116 remains related and separate. Track authorization/base/head/review/CI/release evidence when those phases actually occur; nothing in this table asserts their completion.