AWS bedrock: Expand thinking block binding docs: model compatibility and error guidance
Summary
Adds a Model compatibility section (which models can read which thinking blocks), expands the model/prefix binding checks for Claude Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 and Mythos 5.1, clarifies the 400 error text and beta-value requirement, documents drop_block cache/token side effects, and adds guidance for proxies/gateways to pass through anthropic_beta and thinking.block_binding and to log input_transformations.
Security assessment
The change is API-behavior documentation for a model-reasoning binding feature (which thinking blocks are accepted or dropped, error strings, model compatibility table, and integration advice). While it references 'integrity of Claude's reasoning' and advises gateways to pass through caller parameters unchanged, no vulnerability, CVE, credential, encryption, or IAM concern is addressed and no specific incident is cited, so it is treated as non-security documentation churn.
Evidence
+On Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, each thinking block is tied to the model and the conversation that produced it. On Claude Mythos 5.1, thinking blocks are tied to the model only; the conversation prefix isn't checked. The API checks that the system prompt, the tool list, and all messages before the block are unchanged when you replay that block in a later request. This protects the integrity of Claude's reasoning: reasoning produced under one set of instructions cannot be replayed under a different set.
Diff
diff --git a/bedrock/latest/userguide/claude-messages-thinking-block-binding.md b/bedrock/latest/userguide/claude-messages-thinking-block-binding.md index 44c4cb4..ca832c7 100644 --- a//bedrock/latest/userguide/claude-messages-thinking-block-binding.md +++ b//bedrock/latest/userguide/claude-messages-thinking-block-binding.md @@ -7 +7 @@ -OverviewThe block_binding request object (beta)Controlling mismatch behaviorThe input_transformations response arrayOrganization-locked thinkingError responsesGuidance for multi-turn and agentic applications +OverviewModel compatibilityThe block_binding request object (beta)Controlling mismatch behaviorThe input_transformations response arrayOrganization-locked thinkingError responsesGuidance for multi-turn and agentic applications @@ -13 +13 @@ OverviewThe block_binding request object (beta)Controlling mismatch behaviorThe -On Claude Fable 5.1, each thinking block is tied to the conversation that produced it. The API checks that the system prompt, the tool list, and all messages before the block are unchanged when you replay that block in a later request. This protects the integrity of Claude's reasoning: reasoning produced under one set of instructions cannot be replayed under a different set. +On Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, each thinking block is tied to the model and the conversation that produced it. On Claude Mythos 5.1, thinking blocks are tied to the model only; the conversation prefix isn't checked. The API checks that the system prompt, the tool list, and all messages before the block are unchanged when you replay that block in a later request. This protects the integrity of Claude's reasoning: reasoning produced under one set of instructions cannot be replayed under a different set. @@ -21,2 +21,2 @@ If your harness sends conversation history back exactly as it received it, nothi -Model | The model reading the block is allowed to read the producer's thinking. A model cannot read another model's thinking unless the two are explicitly compatible. This check applies on any thinking-capable model. Claude Haiku 5.5 is an exception: its thinking blocks are not locked to the model that produced them and replay unchanged on other models. The reverse still applies: a block produced by a different model and replayed on Claude Haiku 5.5 is dropped as `model_binding_mismatch`. -Conversation prefix | The top-level system prompt, tools, and all message content before the block are unchanged from the request that produced it. Claude Fable 5.1 runs this check. Claude Mythos 5.1 records the same signature but doesn't run it. On Claude Haiku 5.5, this check applies only to accounts created after the Claude Fable 5.1 launch. +Model | The model reading the block is allowed to read the producer's thinking. A model cannot read another model's thinking unless the two are explicitly compatible. This check applies on any thinking-capable model. A block that fails this check is always dropped as `model_binding_mismatch`, and the request still succeeds. For which models read each other's blocks, see Model compatibility. +Conversation prefix | The top-level system prompt, tools, and all message content before the block are unchanged from the request that produced it. Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5 run this check. By default, a failed check returns a 400 error. Claude Mythos 5.1 doesn't run this check: a block replayed after the prefix changed reaches the model, and `prefix_mismatch_behavior` has no effect. @@ -28,0 +29,12 @@ A thinking block whose signature has been altered or cannot be decrypted always +## Model compatibility + +When you switch models partway through a conversation, the model check decides whether earlier thinking blocks reach the new model. Blocks that the new model can't read are dropped for that request; the API doesn't edit your `messages`, so the blocks are used again if you switch back to a model that can read them. + +**Thinking blocks produced by** | **Read by** | **Dropped as`model_binding_mismatch` on** +---|---|--- +Claude Fable 5.1 | Claude Fable 5.1, Claude Mythos 5.1 | Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, Claude Opus 5 +Claude Mythos 5.1 | Claude Mythos 5.1, Claude Fable 5.1 | Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, Claude Opus 5 +Claude Opus 5.5 | Claude Opus 5.5, Claude Fable 5.1, Claude Mythos 5.1 | Claude Sonnet 5.5, Claude Haiku 5.5, Claude Opus 5 +Claude Sonnet 5.5 | Claude Sonnet 5.5, Claude Opus 5.5 | Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5 +Claude Haiku 5.5 | Claude Haiku 5.5, Claude Opus 5.5, Claude Sonnet 5.5 | Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5 + @@ -47 +59 @@ Add `block_binding` to the `thinking` object and include the beta value in `anth -`block_binding` accepts one field, `prefix_mismatch_behavior`, which controls what the API does with a thinking block that fails the conversation prefix check. `mismatch_behavior` is accepted as a deprecated alias for this field. Setting both `prefix_mismatch_behavior` and `mismatch_behavior` in the same request returns a `400 invalid_request_error`: `cannot set both block_binding.prefix_mismatch_behavior and block_binding.mismatch_behavior; send only prefix_mismatch_behavior`. Sent without the beta value, `block_binding` returns a 400. Malformed values also return a 400 naming the field. +`block_binding` accepts one field, `prefix_mismatch_behavior`, which controls what the API does with a thinking block that fails the conversation prefix check. `mismatch_behavior` is accepted as a deprecated alias for this field. Setting both `prefix_mismatch_behavior` and `mismatch_behavior` in the same request returns a `400 invalid_request_error`: `cannot set both block_binding.prefix_mismatch_behavior and block_binding.mismatch_behavior; send only prefix_mismatch_behavior`. Sent without the beta value, `block_binding` returns `400 thinking.adaptive.block_binding: Extra inputs are not permitted`. Malformed values also return a 400 naming the field. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking.type: "adaptive"`. @@ -54 +66 @@ Add `block_binding` to the `thinking` object and include the beta value in `anth -`"drop_block"` | Request succeeds with 200. The failing block is removed before the model, along with every later thinking block in the conversation, and each removed block is listed in `input_transformations`. +`"drop_block"` | Request succeeds with 200. The failing block is removed before the model, along with every later thinking block in the conversation, and each removed block is listed in `input_transformations`. Dropping blocks restarts the prompt cache from the first dropped block and can increase output tokens, so treat `drop_block` as a temporary fix while you remove the edit that causes the mismatch. @@ -100 +112 @@ When `prefix_mismatch_behavior` is `"error"`, a prefix mismatch returns: - "message": "messages.3.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to \"drop_block\". The system prompt differs." + "message": "messages.3.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to \"drop_block\". The `system` prompt differs from the one this block was created with." @@ -103,0 +116,2 @@ When `prefix_mismatch_behavior` is `"error"`, a prefix mismatch returns: +The last sentence names what changed (for example, the `system` prompt). If the request doesn't include the `thinking-binding-controls-2026-08-01` beta value, the message instead ends with a reminder that `prefix_mismatch_behavior` requires that beta value. + @@ -108 +122,7 @@ This error is permanent for that request — an automatic retry loop will not cl - * Replay assistant turns exactly as they were returned, and keep the system prompt and tools stable within a conversation. + * Replay assistant turns exactly as they were returned, including thinking blocks with empty `thinking` text, and keep the system prompt and tools stable within a conversation. A serializer that skips empty thinking blocks silently removes the model's earlier reasoning. + + * Changes that invalidate later thinking blocks include editing earlier messages, changing `system` or `tools`, re-rendering an earlier message with different values (such as the current date), and changing earlier tool results or images. For an image or document referenced by URL, the check covers the fetched content, so a URL whose content changes between turns also invalidates later thinking. + + * Changes that are safe include appending messages and changing `output_config.effort`, `max_tokens`, `tool_choice`, `metadata`, or `cache_control`. Server-side compaction doesn't count as an edit. + + * Removing thinking blocks from the start or end of the history, or removing all of them, is valid. Removing a thinking block from the middle invalidates every later thinking block. @@ -115,0 +136,4 @@ This error is permanent for that request — an automatic retry loop will not cl + * If you build a library, proxy, or gateway, pass the caller's `anthropic_beta` values and `thinking.block_binding` through unchanged, return `input_transformations` to the caller, and leave `role: "system"` messages where the caller put them. + + * Log `input_transformations` in production. Any `prefix_binding_mismatch` entry means something before that block changed. Ignore entries with types or reasons you don't recognize. +