Pensamento preservado

No Claude Fable 5.1, alterar turnos anteriores da conversa (o prompt system, as tools ou qualquer mensagem anterior) afeta a resposta da API. Por padrão, isso faz com que a API rejeite a requisição com um erro, a menos que você opte por ter os blocos de pensamento afetados descartados do que o modelo vê (prefix_mismatch_behavior: "drop_block"). A verificação é aplicada por padrão para novas contas criadas em ou após 31 de agosto de 2026, 00:00 UTC. Há mais detalhes em Como funciona e Quem é afetado.

Quando você envia um bloco de volta, a API usa sua signature para verificar que a conversa anterior está inalterada e que o modelo atual consegue ler o bloco. A verificação existe para que o raciocínio produzido sob um conjunto de instruções não possa ser reproduzido sob outro conjunto de instruções, potencialmente adversarial.

A API fornece alternativas de primeira classe para modificar uma conversa à medida que ela avança, cobrindo a maioria dos casos de uso de edições de transcrição: mensagens de sistema no meio da conversa para novas instruções, mensagens de sistema com escopo de turno para lembretes por turno, alterações de ferramentas no meio da conversa para adicionar e remover ferramentas, e esforço por mensagem para ajustar a profundidade do pensamento por turno. O restante desta página cobre como saber se sua integração é afetada e como migrar padrões comuns de harness para esses recursos. Como benefício adicional, manter tudo antes de cada bloco de pensamento inalterado byte a byte também mantém o prefixo estável para o "prompt caching" (cache de prompt), consulte cache de prompt.

Se você precisa fazer algo depende do que gerencia seu histórico de conversa:

• Você usa um produto ou SDK oficial do Claude: Claude Code, claude.ai, Claude Managed Agents ou o Claude Agent SDK. Eles mantêm o prefixo intacto para você.
• Você chama a Messages API diretamente, a partir do seu próprio loop de agente ou de qualquer outro contexto. Você deve verificar seu código e garantir que o array messages seja tratado como somente-anexação (append-only). Estes padrões comuns editam o prefixo e invalidam o pensamento após a edição:
  • Aparar ou descartar turnos mais antigos
  • Resumir turnos mais antigos no cliente e manter os recentes
  • Injetar um lembrete em um turno anterior e removê-lo na próxima requisição
  • Reconstruir o prompt system a cada requisição (hora atual, orçamento de tokens, flags de modo)
  • Adicionar ou remover entradas em tools no meio da sessão

Como funciona

Para novas requisições, a API verifica:

• O modelo é o mesmo ou mais novo. Um bloco é legível pelo modelo que o produziu e por modelos posteriores, não por anteriores. Uma conversa que passa para um modelo mais novo mantém seu raciocínio. Uma conversa que passa para um modelo mais antigo falha na verificação de modelo para esses blocos, e a API os descarta para aquela requisição. Consulte Pensamento preservado para a lista exata por modelo.
• Nada antes do bloco mudou. O prompt system de nível superior, o conjunto de ferramentas em tools e cada mensagem antes do bloco. Com compactação no lado do servidor, o prefixo verificado começa no bloco de compactação mais recente.
• A cadeia de blocos de pensamento anteriores está intacta. Blocos thinking e redacted_thinking anteriores não fazem parte do prefixo, mas cada bloco de pensamento registra o anterior a ele, entre turnos. Você pode remover blocos de pensamento do início do histórico. Remover um do meio invalida todos os blocos de pensamento após ele.

Um bloco que falha na verificação de modelo é sempre descartado. Para uma incompatibilidade de prefixo, você escolhe o que acontece com thinking.block_binding.prefix_mismatch_behavior, que requer o cabeçalho beta thinking-binding-controls-2026-08-01:

• "drop_block": a API remove o bloco e todos os blocos de pensamento após ele na conversa, e a requisição é bem-sucedida. Blocos descartados não são cobrados. A resposta os lista em um array input_transformations de nível superior (no evento message_start ao usar streaming).
• "error": a API rejeita a requisição com um 400 invalid_request_error que nomeia o primeiro bloco com falha.

O padrão é "error". O cabeçalho permite que você defina o campo e adiciona input_transformations às respostas.

Quem é afetado

Claude Fable 5.1. Consulte Pensamento preservado para a lista de modelos.

No Claude Fable 5.1, a API aplica a verificação para novas contas. Uma nova conta é aquela criada em ou após 31 de agosto de 2026, 00:00 UTC. A mesma definição se aplica na Claude API e nas plataformas de nuvem. Modelos posteriores aplicarão a verificação para todos os usuários.

Uma requisição que define prefix_mismatch_behavior opta pela aplicação independentemente da idade da conta, e é assim que você testa a partir de uma conta mais antiga. Para verificar se sua conta tem a aplicação por padrão, envie uma requisição que edite o histórico sem o cabeçalho beta: um 400 que nomeia o cabeçalho significa que está aplicada.

Como saber se sua integração é impactada

Capture os corpos exatos das requisições que sua integração envia ao longo de alguns turnos normais, incluindo uma compactação ou uma alteração de ferramenta se seu produto faz isso. Para cada par de requisições consecutivas, compare system, tools e a parte compartilhada de messages. Eles devem ser idênticos byte a byte até os turnos recém-anexados.

Em seguida, confirme com a API. Com o cabeçalho beta thinking-binding-controls-2026-08-01 e claude-fable-5-1, defina thinking.block_binding.prefix_mismatch_behavior como "drop_block" e execute uma sessão normal de múltiplos turnos através da sua integração. Esta requisição é o segundo turno de tal sessão, enviando de volta o turno do assistente da primeira resposta exatamente como recebido:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: thinking-binding-controls-2026-08-01" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 16000,
    "thinking": {
      "type": "adaptive",
      "block_binding": { "prefix_mismatch_behavior": "drop_block" }
    },
    "system": "You are a coding agent.",
    "messages": [
      { "role": "user", "content": "Fix the failing test." },
      {
        "role": "assistant",
        "content": [
          { "type": "thinking", "thinking": "", "signature": "EqQBCkYIBxgCKkD..." },
          { "type": "text", "text": "I need to see the test first. Which file is it in?" }
        ]
      },
      { "role": "user", "content": "tests/test_auth.py" }
    ]
  }'

Cada resposta então carrega um array input_transformations de nível superior. Registre-o em cada turno:

{
  "input_transformations": [
    {
      "type": "thinking_dropped",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

• Vazio em todos os turnos: sua integração mantém o histórico intacto.
• reason: "prefix_binding_mismatch": algo antes do bloco em path mudou entre esta requisição e a anterior. Faça um diff de system, tools e messages até aquele turno para encontrá-lo.
• reason: "model_binding_mismatch": a conversa passou para um modelo que não consegue ler os blocos do modelo anterior (um roteador, um fallback). Não é um bug na sua integração. Continue enviando os blocos e deixe a API descartar o que o modelo atual não consegue ler.

Isso funciona a partir de qualquer conta, porque definir o campo faz a requisição optar pela aplicação. Para falhar de forma explícita em CI, defina "error". O 400 começa com:

messages.1.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".

Sem o cabeçalho beta na requisição, a mensagem continua: That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header. A mensagem geralmente termina com uma frase nomeando o que mudou, por exemplo que o prompt system ou a lista tools difere de quando o bloco foi criado.

Consulte Solução de problemas de pensamento para todas as variantes deste erro.

O que conta como uma edição

Entre duas requisições consecutivas:

Atualize sua integração

Cada padrão substitui um tipo de edição de histórico por um recurso da API que tem o mesmo efeito no modelo sem alterar bytes anteriores.

Anexe turnos do assistente exatamente como retornados

Armazene o array content de cada resposta e envie-o de volta inalterado como o turno do assistente, todos os tipos de bloco na ordem recebida, incluindo blocos thinking cujo campo thinking está vazio. Não reserialize através de um tipo intermediário que descarte tipos de bloco desconhecidos ou campos vazios.

Adicione instruções com uma mensagem de sistema no meio da conversa, não editando system

Se seu código reconstrói o prompt system de nível superior a cada requisição (hora atual, orçamento de tokens, flag de modo, contexto de projeto recém-descoberto), todos os blocos de pensamento na conversa falham na verificação. Congele system no início da sessão e, quando algo mudar, anexe uma mensagem role: "system" no ponto de messages em que isso se torna verdadeiro:

{
  "role": "system",
  "content": "The user switched the workspace to read-only mode. Do not write files until told otherwise."
}

O modelo a trata com autoridade de prompt do sistema, e tudo antes dela permanece inalterado. Nenhum cabeçalho beta é necessário no Claude Fable 5.1. Em um loop de ferramentas, coloque-a após a mensagem de usuário tool_result, nunca entre um tool_use do assistente e seu tool_result (consulte Limitações).

Envie lembretes por turno como mensagens de sistema com escopo de turno

A edição de histórico mais comum é o empurrão por turno: uma linha anexada após cada lote de resultados de ferramentas ("solicite leituras independentes juntas", "você não atualizou o usuário há algum tempo") e removida na próxima requisição para que os lembretes não se acumulem. Removê-la é a edição.

Em vez disso, envie o empurrão como uma mensagem de sistema no meio da conversa com clear_at: "next_user_message" após a mensagem de usuário tool_result (cabeçalho beta mid-conversation-system-clear-at-2026-08-21). Este array messages é a requisição após duas rodadas de ferramentas. messages[3] é o empurrão da requisição anterior, deixado no lugar, e messages[6] é a cópia desta requisição:

[
  { "role": "user", "content": "Fix the failing test." },
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_01",
        "name": "read_file",
        "input": { "path": "tests/test_auth.py" }
      }
    ]
  },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }]
  },
  {
    "role": "system",
    "clear_at": "next_user_message",
    "content": "Request every independent read in one turn."
  },
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_02",
        "name": "read_file",
        "input": { "path": "src/auth.py" }
      }
    ]
  },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "toolu_02", "content": "..." }]
  },
  {
    "role": "system",
    "clear_at": "next_user_message",
    "content": "Request every independent read in one turn."
  }
]

Uma mensagem de usuário contendo apenas tool_result conta como a "próxima mensagem de usuário", então messages[3] já está limpa: ela não renderiza nada e não custa tokens de entrada, mas ainda está no array, então o pensamento em messages[4] permanece válido. messages[6] é o que o modelo vê neste turno. Em requisições posteriores, mantenha ambas onde estão e anexe a próxima cópia após a próxima mensagem tool_result. Mensagens com escopo de turno carregam apenas text e não aceitam cache_control. Coloque o ponto de interrupção de cache no turno de usuário precedente. Consulte Mensagens de sistema com escopo de turno.

Sem o beta, anexe o empurrão como um bloco text após os blocos tool_result na mesma mensagem de usuário e deixe as cópias anteriores no lugar. O modelo age com base na mais recente.

Altere ferramentas com tool_addition e tool_removal, não editando tools

Se o conjunto de ferramentas muda no meio da sessão (uma ferramenta é desbloqueada após autenticação, uma ferramenta perigosa é retirada após uma troca de modo), não edite tools. Declare o conjunto completo no início da sessão e use alterações de ferramentas no meio da conversa para oferecer ou retirar uma ferramenta a partir daquele ponto (cabeçalho beta mid-conversation-tool-changes-2026-07-01). Uma ferramenta que ainda não está disponível recebe defer_loading: true e um bloco tool_addition posterior, com o mesmo formato deste tool_removal:

{
  "role": "system",
  "content": [
    { "type": "tool_removal", "tool": { "type": "tool_reference", "name": "delete_branch" } },
    { "type": "text", "text": "Branch deletion is disabled for the rest of this session." }
  ]
}

Uma ferramenta cujo schema você descobre no meio da sessão (um servidor MCP descoberto em tempo de execução) pode ser anexada a tools com defer_loading: true e oferecida com tool_addition. Uma ferramenta adiada não referenciada não faz parte do prefixo, então anexá-la é seguro. Anexar uma ferramenta regular não é.

Apare o contexto no servidor onde puder

Truncamento e resumo no lado do cliente são a segunda edição mais comum: descartar ou resumir os turnos mais antigos e manter os recentes literalmente. Os blocos de pensamento dos turnos recentes foram produzidos enquanto o histórico que você removeu ainda estava no lugar, então eles falham na verificação. Os equivalentes no lado do servidor não contam como edições, porque a verificação compara a conversa como você a enviou:

• Compactação resume turnos mais antigos em um bloco de compactação quando o contexto se aproxima de um limite que você define, e o prefixo verificado recomeça a partir desse bloco. Seu parâmetro instructions aceita seu próprio prompt de resumo ("preserve cada ticker, tamanho de posição e suposição declarada").
• Edição de contexto limpa resultados de ferramentas antigos (clear_tool_uses_20250919) ou blocos de pensamento antigos, do mais antigo primeiro (clear_thinking_20251015), por regra.

Compactação personalizada no cliente

Esta verificação não proíbe a compactação no lado do cliente. A regra é mais restrita: não mantenha um bloco de pensamento atrás de um prefixo que você reescreveu.

Compactação simples é o formato recomendado e não precisa de alterações. Quando a conversa fica muito longa, resuma-a em uma mensagem e inicie a próxima requisição com esse resumo mais o novo turno do usuário, sem reproduzir turnos ou blocos de pensamento anteriores: messages se torna [{"role": "user", "content": "<summary of the session so far>\n\n<the next instruction>"}]. Nenhum pensamento anterior permanece, então nada falha, e o modelo pensa do zero sobre a conversa compactada. Os modelos Claude são treinados em tarefas de longo horizonte com este esquema, e ele tem desempenho comparável a esquemas mais elaborados para a maioria das cargas de trabalho. Ele redefine o cache de prompt no ponto de compactação, como qualquer compactação faz.

Dois outros formatos comuns falham como escritos e precisam de uma alteração cada:

• Compactação mantendo a cauda resume turnos mais antigos e mantém os turnos mais recentes literalmente. Os blocos de pensamento dos turnos mantidos foram produzidos contra o histórico completo, então eles falham atrás do resumo. Correção: remova thinking e redacted_thinking de cada turno do assistente que você carrega adiante, mantendo text e tool_use, ou envie prefix_mismatch_behavior: "drop_block" e deixe a API removê-los.
• Compactação em segundo plano constrói o resumo fora do caminho crítico e o insere enquanto a conversa continua, então cada turno produzido nesse meio-tempo tem pensamento que antecede a troca. Correção: envie "drop_block" em cada requisição que ainda carrega blocos de pensamento produzidos antes da troca (ou remova esses blocos você mesmo; input_transformations na primeira resposta após a troca lista exatamente quais), ou compacte de forma síncrona.

Recortar turnos individuais do meio da transcrição invalida tudo após eles, e nenhum formato no lado do cliente evita isso. Use uma mensagem de sistema no meio da conversa para a alteração de instrução que você estava fazendo, ou edição de contexto no lado do servidor para remoção seletiva.

Não compacte no meio de uma rodada de ferramentas: um turno do assistente cujo tool_use ainda está aguardando um tool_result deve voltar com seu pensamento intacto, para que o modelo termine a rodada com seu raciocínio (consulte Preservando blocos de pensamento).

Referencie arquivos por ID, não por URL cujo conteúdo muda

Para um bloco image ou document com uma fonte url, os bytes buscados fazem parte do prefixo verificado e a string da URL não. Um endpoint de "captura de tela mais recente" ou um documento editado invalida o pensamento posterior. Uma URL assinada rotativa para o mesmo arquivo não. Para conteúdo que você referencia entre turnos, faça o upload uma vez com a Files API e use o file_id, ou envie base64.

Decida o que acontece em uma incompatibilidade

Uma vez que sua integração seja somente-anexação, escolha um prefix_mismatch_behavior para produção. Ele governa apenas incompatibilidades de prefixo. Um bloco que o modelo atual não consegue ler (após uma troca de roteador ou fallback no lado do servidor) é sempre descartado, e reportado em input_transformations quando o cabeçalho beta é enviado.

• "error" (o padrão) se uma incompatibilidade de prefixo só pode significar um bug no seu código. Você descobre por um 400 em testes em vez de por blocos descartados silenciosamente. Na Message Batches API, o padrão não definido descarta blocos com falha em vez de falhar o item do lote; defina "error" explicitamente se quiser que os itens resultem em erro.
• "drop_block" se você prefere descartar os blocos afetados em vez de falhar. Registre input_transformations.

Se você capturar o 400 em produção, tentar novamente a mesma requisição não o resolverá. Tente novamente com prefix_mismatch_behavior: "drop_block" (e o cabeçalho beta), que remove exatamente os blocos que falham, incluindo quaisquer em um turno do assistente cujo tool_use ainda está aguardando seu tool_result. O descarte se aplica apenas àquela requisição, então continue enviando "drop_block" (e o cabeçalho beta) pelo resto da sessão. Sem o beta, remova todos os blocos thinking e redacted_thinking do histórico, deixando os blocos text e tool_use de cada turno no lugar, e tente novamente uma vez. Depois corrija a edição que causou isso.

Recursos da API usados nesta página

Para combinar cabeçalhos em uma requisição:

anthropic-beta: thinking-binding-controls-2026-08-01,mid-conversation-system-clear-at-2026-08-21,mid-conversation-tool-changes-2026-07-01

Os mesmos nomes de beta se aplicam no Amazon Bedrock e no Google Cloud. Consulte Cabeçalhos beta para saber como enviá-los com cada SDK.

Checklist

• Se um produto ou SDK oficial do Claude (Claude Code, claude.ai, Claude Managed Agents, o Claude Agent SDK) gerencia seu histórico de conversa, pare aqui.
• Corpos de requisições consecutivas são idênticos byte a byte em system, tools e no prefixo compartilhado de messages.
• Uma sessão completa sob prefix_mismatch_behavior: "drop_block" não registra entradas prefix_binding_mismatch.
• Turnos do assistente voltam byte a byte como retornados, todos os tipos de bloco incluídos.
• system e tools de nível superior são fixos para a sessão. Alterações vão em mensagens role: "system" e blocos tool_addition / tool_removal.
• Lembretes por turno são mensagens de sistema com escopo de turno (ou blocos de texto finais) que são anexados novos e nunca removidos.
• O contexto é aparado por compactação ou edição de contexto, ou por uma compactação no lado do cliente que não deixa blocos de pensamento atrás do prefixo reescrito e nunca divide uma rodada de ferramentas.
• Arquivos entre turnos são file_id ou base64, não URLs mutáveis.
• Um prefix_mismatch_behavior de produção está definido e seus 400s ou entradas descartadas são monitorados.

Próximos passos