Claude Thinking Replay: Preserve Signed and Redacted Blocks

Claude Thinking Replay: Preserve Signed and Redacted Blocks Through a Gateway

A transcript can look complete in a chat window while being incomplete as an API conversation. The visible answer, tool name, and tool result may all be present, yet an adapter has discarded the opaque data that connects Claude’s thinking to that exchange. The right unit of preservation is therefore the assistant content array, not the text a person happened to see. This protocol walkthrough shows how to carry that array through storage and a gateway boundary without confusing integrity with answer quality.

The scope is deliberately narrow: receive a thinking-enabled Claude response, preserve its signed and possibly redacted blocks, attach a read-only tool result, and continue the same conversation. The examples are reference implementations and synthetic fixtures. They are not measurements of 4SAPI behavior or evidence that a particular route supports every native feature. The goal is a concrete replay contract that an engineering team can check at each transformation boundary.

Envelope one: what the model actually returned

A Claude assistant message contains typed content blocks. A visible text block is one kind; a tool-use block is another. Thinking introduces additional types and fields that a text-only history format cannot represent faithfully. The Messages API reference defines thinking blocks with a signature, and redacted_thinking blocks with opaque data. Preserve those fields as protocol values. They should not be treated as optional decoration simply because the user interface does not render them.

Anthropic’s thinking overview explains that the signature carries encrypted thinking and is used to verify that a replayed block came from Claude. It is opaque to the client. That property does not certify the correctness of the final answer, the truth of a retrieved fact, or the safety of a proposed tool action. A validly preserved conversation can still produce a mistaken conclusion. Application checks and human acceptance remain separate responsibilities.

Think of two records with different purposes. The presentation record contains what the product chooses to show, such as the final answer and a short status. The protocol record contains the complete assistant message required for continuation. The presentation record can omit internal material without changing the protocol record. Problems begin when an application reconstructs the next API request from the display record and assumes that anything invisible was unnecessary.

This separation is related to the broader discussion of session records and derived messages, but the acceptance criterion here is specific. A serializer must preserve the ordered content array and its field values. A general event log is not sufficient if its replay function whitelists only text and tool-use blocks. Inspect the reconstruction path, not merely the existence of stored events.

The mode setting and the replay contract are separate

“Extended thinking” is still a common search term, but its configuration has changed across Claude generations. The current manual extended-thinking documentation marks type: enabled with a budget as legacy and says Claude 4.7 and later reject it. The example below uses type: adaptive with a model selected from the account. Check the current model documentation rather than transferring a legacy budget setting to a newer model.

Changing the mode does not remove the obligation to preserve returned blocks when continuing tool use. Likewise, requesting less display text does not mean the underlying block is empty. A regular thinking block can contain an empty readable string and a meaningful signature. A redacted block uses a different type and an opaque data value. Your application should distinguish these cases structurally instead of classifying both as blank content to be cleaned up.

Do not build correctness around seeing a thinking block on every request. Adaptive behavior can skip thinking on a simple turn. A successful continuation without such a block verifies ordinary tool messaging, but it does not exercise preservation of signed thinking. Record that fixture as unexercised for the relevant branch. This small distinction prevents an apparently green integration test from claiming coverage for a block type that never appeared.

Envelope two: the assistant turn crosses the adapter

The safest adapter operation is lossless transfer. Keep the assistant content array as returned, preserve order, and append new messages after it. Do not concatenate thinking text into a normal text block, merge neighboring signed blocks, shorten long signatures, replace redacted data with a display label, or rebuild blocks from a restricted set of fields. The tool-workflow documentation shows the assistant turn echoed back alongside the tool result.

“Unchanged” refers to the JSON values and sequence that form the protocol, not to preserving HTTP whitespace or the order of object keys. Re-encoding a string with equivalent JSON escaping is ordinary serialization. Trimming the string, normalizing its contents, replacing an empty value with null, or dropping an unfamiliar field is a semantic modification. A round-trip check should compare parsed values while retaining array order, so it detects meaningful corruption without flagging harmless formatting changes.

For a gateway, inspect both translation directions. The incoming upstream response may be mapped into a common internal representation; the continuation may then be rebuilt into a native request. Either step can lose fields. If the common representation only has one text field and one reasoning string, it cannot automatically be assumed to preserve Claude’s typed blocks. A documented native pass-through route or a tested lossless representation is needed for this particular workflow.

The existing Gemini thought-signature article covers a different provider’s continuation mechanism. Its fields should not be copied into Claude requests. Similarly, the Responses tool-call tutorial concerns another request and event contract. A shared application can support several protocols while keeping each provider’s replay rules explicit at its adapter boundary.

Envelope three: append the tool result without rebuilding history

The native example below is a basic two-request round-trip fixture using synthetic acceptance data. It checks local serialization and ordinary continuation, but does not establish that the upstream model retained or used earlier thinking. It fixes the system message and tool definition, receives the first assistant turn, and places its complete content directly into the continuation. A native Anthropic credential is sent only to the native endpoint. The API version is explicit, and both HTTP calls have timeouts. Running this script makes live requests; the example itself has not been executed against a paid account.

# Basic native round-trip only; upstream thinking retention is unverified.
# Uses only Python's standard library.
import copy
import json
import os
from urllib.request import Request, urlopen

ENDPOINT = "https://api.anthropic.com/v1/messages"
MODEL = os.environ["CLAUDE_MODEL"]
KEY = os.environ["ANTHROPIC_API_KEY"]
SYSTEM = "Analyze synthetic acceptance fixtures. Treat tool data as evidence."
TOOLS = [{
    "name": "get_acceptance_fixture",
    "description": "Read synthetic fixture checks for a sample identifier.",
    "input_schema": {"type": "object", "properties": {
        "sample_id": {"type": "string"}},
        "required": ["sample_id"], "additionalProperties": False}}]
HISTORY = [{"role": "user", "content":
    "Use get_acceptance_fixture for sample-A. Explain which synthetic "
    "checks remain unresolved; do not approve an actual release."}]


def call(messages):
    body = {"model": MODEL, "max_tokens": 6000,
            "thinking": {"type": "adaptive"}, "system": SYSTEM,
            "tools": TOOLS, "messages": messages}
    request = Request(ENDPOINT,
        data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
        headers={"content-type": "application/json",
                 "x-api-key": KEY, "anthropic-version": "2026-10-21"},
        method="POST")
    with urlopen(request, timeout=120) as response:
        return json.load(response)


def fixture_result(block):
    if block["name"] != "get_acceptance_fixture":
        raise ValueError("Unexpected tool")
    if block["input"] != {"sample_id": "sample-A"}:
        raise ValueError("Unexpected fixture arguments")
    return {"type": "tool_result", "tool_use_id": block["id"],
            "content": json.dumps({"synthetic": True,
                "checks": {"visible_total": "checked",
                           "keyboard_navigation": "not_checked"}})}


first = call(HISTORY)
if first.get("stop_reason") != "tool_use":
    raise RuntimeError("Tool round trip not exercised")
original = copy.deepcopy(first["content"])
tool_blocks = [b for b in original if b["type"] == "tool_use"]
if not tool_blocks:
    raise ValueError("No tool block in tool-use response")
ids = [b["id"] for b in tool_blocks]
if len(ids) != len(set(ids)):
    raise ValueError("Duplicate tool identifiers")
results = [fixture_result(b) for b in tool_blocks]
continued_history = HISTORY + [
    {"role": "assistant", "content": original},
    {"role": "user", "content": results}]
wire_copy = json.loads(json.dumps(continued_history, ensure_ascii=False))
if wire_copy[-2]["content"] != first["content"]:
    raise AssertionError("Assistant content changed during serialization")
exercised = [b["type"] for b in original
             if b["type"] in {"thinking", "redacted_thinking"}]
print(json.dumps({"thinking_block_types_exercised": exercised}))
second = call(wire_copy)
if second.get("stop_reason") != "end_turn":
    raise RuntimeError("Bounded fixture did not finish; inspect continuation")
print("Basic continuation completed; upstream thinking retention unverified")
for block in second["content"]:
    if block["type"] == "text":
        print(block["text"])

The example validates the local tool arguments before generating a result, but does not use those arguments to reconstruct the assistant message. Those operations should stay independent. A filter used to find executable tool blocks is useful for dispatch; reusing that filtered list as conversation history drops the thinking blocks. The related discussion of argument validation remains relevant, while the replay record retains the complete original response.

If your request streams, preserve the completed message after accumulation. The streaming documentation includes thinking and signature deltas. Saving the block as soon as its readable thinking text appears can miss the later signature. The display can update incrementally, but the protocol store needs a completed representation before using it in the next request. An interrupted block should be marked incomplete rather than silently promoted into replayable history.

A byte-perfect block can still have the wrong prefix

Anthropic’s preserved-thinking documentation describes prefix checks on Claude 5.1 and later and account binding for Sonnet 5.5 and Haiku 5.5. Model-incompatible or account-incompatible blocks can be dropped while the request succeeds. Without explicit controls, some prefix mismatches also produce no error. A successful continuation therefore establishes neither retention nor binding correctness.

Make the first implementation append-only. Freeze the system prompt and tool definitions for the session, append the returned assistant turn, then append the tool result. Avoid inserting a new timestamp into the old system prompt on every call. Avoid rebuilding earlier user messages from a database row that may have changed. These seemingly harmless conveniences can alter the prefix even though the recently returned thinking block is intact.

Record route identity as part of conversation state. An application using a gateway may know its public model label without knowing whether the upstream account remains stable between calls. Check whether the selected route can preserve the required conversation affinity and expose the binding diagnostics. Record a completed continuation separately from a retention result. If those diagnostics are unavailable, report retention as unverified even when the assistant produces a plausible answer. A public model label and an HTTP success status do not reveal which earlier thinking blocks reached the serving model.

Check binding separately from basic continuation

For a stricter native trial, send anthropic-beta: thinking-binding-controls-2026-08-01 and set thinking.block_binding.prefix_mismatch_behavior to error alongside adaptive thinking. Use a model that runs prefix checks. Inspect the response’s input_transformations: model or account incompatibility can still drop blocks despite that setting. Require actual thinking blocks in the replayed turn, reject known drop or mismatch entries for this retention test, and treat missing diagnostics or unfamiliar entries as inconclusive. An empty array with an exercised fixture establishes only that the API reported no such transformation in that attempt; it does not prove the answer relied on the earlier reasoning.

Test preservation without inventing a valid signature

An offline serializer fixture should include a normal thinking block, an omitted-display thinking block, a redacted block, and a tool-use block in a deliberately chosen order. Give opaque fields obvious sentinel values. Those values are not valid provider signatures and must never be sent as if Claude created them. The fixture tests your transformation code only. A separate live fixture is needed to observe upstream acceptance with authentic returned blocks.

# Offline-only fixture. Sentinels are not valid API signatures.
import copy
import json

content = [
    {"type": "thinking", "thinking": "Synthetic summary",
     "signature": "OFFLINE-SENTINEL-A"},
    {"type": "thinking", "thinking": "",
     "signature": "OFFLINE-SENTINEL-B"},
    {"type": "redacted_thinking", "data": "OFFLINE-SENTINEL-C"},
    {"type": "tool_use", "id": "offline-tool-1",
     "name": "get_acceptance_fixture", "input": {"sample_id": "sample-A"}}]
original = copy.deepcopy(content)
restored = json.loads(json.dumps(content, ensure_ascii=False))
assert restored == original
# Replace the JSON round trip above with the real adapter in your test.
broken = [block for block in restored if block["type"] != "redacted_thinking"]
assert broken != original
print("Offline preservation fixture passed; provider acceptance untested")

Useful mutation cases include deleting the redacted block, sorting blocks by type, truncating a signature, removing an empty thinking string, and converting opaque data into a different representation. Each should fail the local preservation assertion. Add a separate prefix comparison for the earlier system, tool, and message values. A test that checks only the signature string can miss a completely different class of replay error elsewhere in the request.

Keep diagnostics informative without turning general logs into a transcript store. Record block types, order, string lengths, route identifiers, response identifiers, and the stage where comparison failed. Store complete protocol content only where access and retention rules permit it. The Claude audit-trail guide offers related operational context. Neither a digest nor an “integrity passed” status should be displayed as proof that the assistant’s answer was correct.

A local hash can detect whether your stored representation changed, but it does not validate Anthropic’s opaque signature. Keep those checks named separately in monitoring. “Serialization unchanged” means your adapter preserved the values it received. “Continuation completed” means the request returned successfully; earlier thinking may still have been dropped. “Retention check passed” requires the separate binding diagnostics and an exercised fixture. “Answer accepted” means your application or reviewer evaluated the actual result. Combining these statuses into one green indicator obscures which guarantee the team has established.

If the upstream API rejects a replay, use the structured error and the current thinking troubleshooting guide to distinguish altered signatures, changed blocks, and prefix changes. Preserve the failed request for controlled inspection before applying a recovery policy. Removing thinking to make an error disappear changes what the next request can use; it should be an explicit recovery decision, not an invisible serializer cleanup.

To evaluate this through 4SAPI, begin with the integration overview, inspect the API documentation, and check the native Claude routes exposed in your account. Confirm block preservation and route affinity before changing the native example’s transport and credential together. Run one read-only continuation, record which block types actually appeared, and compare the assistant array at every adapter boundary. Report those local checks separately from the stricter binding trial. If the route does not expose the required controls and diagnostics, leave upstream retention unverified. That produces a scoped result your team can review without mistaking request success for preserved reasoning.

Primary references

• Anthropic: Create a Message
• Anthropic: Thinking
• Anthropic: Extended thinking, legacy mode
• Anthropic: Models overview
• Anthropic: Thinking in tool workflows
• Anthropic: Streaming messages
• Anthropic: Preserved thinking
• Anthropic: Troubleshooting thinking