Pensiero preservato

Su Claude Fable 5.1, modificare i turni precedenti della conversazione (il prompt system, i tools o qualsiasi messaggio precedente) influisce sulla risposta dell'API. Per impostazione predefinita, fa sì che l'API rifiuti la richiesta con un errore, a meno che tu non scelga invece di far scartare i blocchi di pensiero interessati da ciò che il modello vede (prefix_mismatch_behavior: "drop_block"). Il controllo è applicato per impostazione predefinita per i nuovi account creati a partire dal 31 agosto 2026, 00:00 UTC. Trovi maggiori dettagli in Come funziona e Chi è interessato.

Quando rimandi indietro un blocco, l'API usa la sua signature per verificare che la conversazione precedente sia invariata e che il modello corrente possa leggere il blocco. Il controllo esiste affinché il ragionamento prodotto sotto un insieme di istruzioni non possa essere riprodotto sotto un altro insieme di istruzioni, potenzialmente ostile.

L'API fornisce alternative di prima classe per modificare una conversazione man mano che procede, coprendo la maggior parte dei casi d'uso per le modifiche alla trascrizione: messaggi di sistema a metà conversazione per nuove istruzioni, messaggi di sistema con ambito di turno per promemoria per turno, modifiche degli strumenti a metà conversazione per aggiungere e rimuovere strumenti, e effort per messaggio per regolare la profondità del pensiero per turno. Il resto di questa pagina spiega come capire se la tua integrazione è interessata e come migrare i pattern comuni degli harness verso queste funzionalità. Come vantaggio aggiuntivo, mantenere tutto ciò che precede ogni blocco di pensiero invariato byte per byte mantiene anche il prefisso stabile per la cache dei prompt ("prompt caching").

Se devi fare qualcosa dipende da cosa gestisce la cronologia della tua conversazione:

• Usi un prodotto o SDK ufficiale Claude: Claude Code, claude.ai, Claude Managed Agents o il Claude Agent SDK. Questi mantengono il prefisso intatto per te.
• Chiami direttamente la Messages API, dal tuo ciclo agente o da qualsiasi altro contesto. Dovresti controllare il tuo codice e assicurarti che l'array messages sia trattato come append-only (solo aggiunta). Questi pattern comuni modificano il prefisso e invalidano il pensiero successivo alla modifica:
  • Tagliare o scartare i turni più vecchi
  • Riassumere i turni più vecchi sul client e mantenere quelli recenti
  • Iniettare un promemoria in un turno precedente e rimuoverlo alla richiesta successiva
  • Ricostruire il prompt system a ogni richiesta (ora corrente, budget di token, flag di modalità)
  • Aggiungere o rimuovere voci in tools a metà sessione

Come funziona

Per le nuove richieste l'API verifica:

• Il modello è lo stesso o più recente. Un blocco è leggibile dal modello che lo ha prodotto e dai modelli successivi, non da quelli precedenti. Una conversazione che passa a un modello più recente mantiene il suo ragionamento. Una conversazione che passa a un modello più vecchio non supera il controllo del modello per quei blocchi, e l'API li scarta per quella richiesta. Consulta Pensiero preservato per l'elenco esatto per modello.
• Nulla prima del blocco è cambiato. Il prompt system di primo livello, l'insieme di strumenti in tools e ogni messaggio prima del blocco. Con la compattazione lato server il prefisso verificato inizia dal blocco di compattazione più recente.
• La catena dei blocchi di pensiero precedenti è ininterrotta. I blocchi thinking e redacted_thinking precedenti non fanno parte del prefisso, ma ogni blocco di pensiero registra quello che lo precede, attraverso i turni. Puoi rimuovere blocchi di pensiero dall'inizio della cronologia. Rimuoverne uno dal mezzo invalida ogni blocco di pensiero successivo.

Un blocco che non supera il controllo del modello viene sempre scartato. Per una mancata corrispondenza del prefisso scegli tu cosa succede con thinking.block_binding.prefix_mismatch_behavior, che richiede l'header beta thinking-binding-controls-2026-08-01:

• "drop_block": l'API rimuove il blocco e ogni blocco di pensiero successivo nella conversazione, e la richiesta ha successo. I blocchi scartati non vengono fatturati. La risposta li elenca in un array input_transformations di primo livello (nell'evento message_start in streaming).
• "error": l'API rifiuta la richiesta con un 400 invalid_request_error che indica il primo blocco che non supera il controllo.

Il valore predefinito è "error". L'header ti permette di impostare il campo e aggiunge input_transformations alle risposte.

Chi è interessato

Claude Fable 5.1. Consulta Pensiero preservato per l'elenco dei modelli.

Su Claude Fable 5.1, l'API applica il controllo per i nuovi account. Un nuovo account è uno creato a partire dal 31 agosto 2026, 00:00 UTC. La stessa definizione si applica sulla Claude API e sulle piattaforme cloud. I modelli successivi applicheranno il controllo per tutti gli utenti.

Una richiesta che imposta prefix_mismatch_behavior aderisce all'applicazione del controllo indipendentemente dall'età dell'account, ed è così che puoi testare da un account più vecchio. Per verificare se il tuo account è soggetto al controllo per impostazione predefinita, invia una richiesta che modifica la cronologia senza l'header beta: un 400 che nomina l'header significa che il controllo è applicato.

Come capire se la tua integrazione è interessata

Cattura i corpi esatti delle richieste che la tua integrazione invia nel corso di alcuni turni normali, inclusa una compattazione o una modifica degli strumenti se il tuo prodotto le esegue. Per ogni coppia di richieste consecutive, confronta system, tools e la parte condivisa di messages. Dovrebbero essere identici byte per byte fino ai turni appena aggiunti.

Poi conferma con l'API. Con l'header beta thinking-binding-controls-2026-08-01 e claude-fable-5-1, imposta thinking.block_binding.prefix_mismatch_behavior su "drop_block" ed esegui una normale sessione multi-turno attraverso la tua integrazione. Questa richiesta è il secondo turno di tale sessione, che rimanda indietro il turno dell'assistente della prima risposta esattamente come ricevuto:

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" }
    ]
  }'

Ogni risposta contiene quindi un array input_transformations di primo livello. Registralo a ogni turno:

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

• Vuoto a ogni turno: la tua integrazione mantiene la cronologia intatta.
• reason: "prefix_binding_mismatch": qualcosa prima del blocco in path è cambiato tra questa richiesta e la precedente. Confronta system, tools e messages fino a quel turno per trovarlo.
• reason: "model_binding_mismatch": la conversazione è passata a un modello che non può leggere i blocchi del modello precedente (un router, un fallback). Non è un bug nella tua integrazione. Continua a inviare i blocchi e lascia che l'API scarti ciò che il modello corrente non può leggere.

Questo funziona da qualsiasi account, perché impostare il campo fa aderire la richiesta all'applicazione del controllo. Per fallire in modo evidente in CI, imposta invece "error". Il 400 inizia con:

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

Senza l'header beta nella richiesta, il messaggio continua: That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header. Il messaggio di solito termina con una frase che indica cosa è cambiato, ad esempio che il prompt system o l'elenco tools differisce da quando il blocco è stato creato.

Consulta Risoluzione dei problemi del pensiero per ogni variante di questo errore.

Cosa conta come modifica

Tra due richieste consecutive:

Aggiorna la tua integrazione

Ogni pattern sostituisce un tipo di modifica della cronologia con una funzionalità dell'API che ha lo stesso effetto sul modello senza modificare i byte precedenti.

Aggiungi i turni dell'assistente esattamente come restituiti

Memorizza l'array content di ogni risposta e rimandalo indietro invariato come turno dell'assistente, ogni tipo di blocco nell'ordine ricevuto, inclusi i blocchi thinking il cui campo thinking è vuoto. Non riserializzare attraverso un tipo intermedio che scarta tipi di blocco sconosciuti o campi vuoti.

Aggiungi istruzioni con un messaggio di sistema a metà conversazione, non modificando system

Se il tuo codice ricostruisce il prompt system di primo livello a ogni richiesta (ora corrente, budget di token, flag di modalità, contesto di progetto appena scoperto), ogni blocco di pensiero nella conversazione non supera il controllo. Congela system all'inizio della sessione e, quando qualcosa cambia, aggiungi un messaggio role: "system" nel punto di messages in cui diventa vero:

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

Il modello lo tratta con l'autorità del prompt di sistema, e tutto ciò che lo precede resta invariato. Nessun header beta è necessario su Claude Fable 5.1. In un ciclo di strumenti, posizionalo dopo il messaggio utente tool_result, mai tra un tool_use dell'assistente e il suo tool_result (vedi Limitazioni).

Invia i promemoria per turno come messaggi di sistema con ambito di turno

La modifica della cronologia più comune è la spinta per turno: una riga aggiunta dopo ogni gruppo di risultati degli strumenti ("richiedi insieme le letture indipendenti", "non aggiorni l'utente da un po'") e rimossa alla richiesta successiva in modo che i promemoria non si accumulino. Rimuoverla è la modifica.

Invece, invia la spinta come messaggio di sistema a metà conversazione con clear_at: "next_user_message" dopo il messaggio utente tool_result (header beta mid-conversation-system-clear-at-2026-08-21). Questo array messages è la richiesta dopo due round di strumenti. messages[3] è la spinta della richiesta precedente, lasciata al suo posto, e messages[6] è la copia di questa richiesta:

[
  { "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."
  }
]

Un messaggio utente contenente solo tool_result conta come "prossimo messaggio utente", quindi messages[3] è già cancellato: non renderizza nulla e non costa token di input, ma è ancora nell'array, quindi il pensiero in messages[4] resta valido. messages[6] è ciò che il modello vede in questo turno. Nelle richieste successive mantieni entrambi dove sono e aggiungi la copia successiva dopo il prossimo messaggio tool_result. I messaggi con ambito di turno contengono solo text e non accettano cache_control. Metti il breakpoint della cache sul turno utente precedente. Consulta Messaggi di sistema con ambito di turno.

Senza la beta, aggiungi la spinta come blocco text dopo i blocchi tool_result nello stesso messaggio utente, e lascia le copie precedenti al loro posto. Il modello agisce su quella più recente.

Modifica gli strumenti con tool_addition e tool_removal, non modificando tools

Se l'insieme di strumenti cambia a metà sessione (uno strumento si sblocca dopo l'autenticazione, uno strumento pericoloso viene ritirato dopo un cambio di modalità), non modificare tools. Dichiara l'insieme completo all'inizio della sessione e usa le modifiche degli strumenti a metà conversazione per offrire o ritirare uno strumento da quel punto in poi (header beta mid-conversation-tool-changes-2026-07-01). Uno strumento non ancora disponibile riceve defer_loading: true e un successivo blocco tool_addition, con la stessa forma di questo 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." }
  ]
}

Uno strumento il cui schema apprendi a metà sessione (un server MCP scoperto a runtime) può essere aggiunto a tools con defer_loading: true e offerto con tool_addition. Uno strumento differito non referenziato non fa parte del prefisso, quindi aggiungerlo è sicuro. Aggiungere uno strumento normale non lo è.

Riduci il contesto sul server dove puoi

Il troncamento e il riassunto lato client sono la seconda modifica più comune: scartare o riassumere i turni più vecchi e mantenere quelli recenti alla lettera. I blocchi di pensiero dei turni recenti sono stati prodotti mentre la cronologia che hai rimosso era ancora presente, quindi non superano il controllo. Gli equivalenti lato server non contano come modifiche, perché il controllo confronta la conversazione così come l'hai inviata:

• La compattazione riassume i turni più vecchi in un blocco di compattazione quando il contesto si avvicina a una soglia che imposti tu, e il prefisso verificato riparte da quel blocco. Il suo parametro instructions accetta il tuo prompt di riassunto personalizzato ("preserva ogni ticker, dimensione di posizione e ipotesi dichiarata").
• Il context editing cancella i vecchi risultati degli strumenti (clear_tool_uses_20250919) o i vecchi blocchi di pensiero a partire dai più vecchi (clear_thinking_20251015) secondo regole.

Compattazione personalizzata sul client

Questo controllo non proibisce la compattazione lato client. La regola è più ristretta: non mantenere un blocco di pensiero dietro un prefisso che hai riscritto.

La compattazione semplice è la forma consigliata e non richiede modifiche. Quando la conversazione diventa troppo lunga, riassumila in un unico messaggio e inizia la richiesta successiva con quel riassunto più il nuovo turno utente, senza riprodurre turni o blocchi di pensiero precedenti: messages diventa [{"role": "user", "content": "<summary of the session so far>\n\n<the next instruction>"}]. Non resta alcun pensiero precedente, quindi nulla fallisce, e il modello pensa da capo sulla conversazione compattata. I modelli Claude sono addestrati su compiti a lungo orizzonte con questo schema, che ha prestazioni paragonabili a schemi più elaborati per la maggior parte dei carichi di lavoro. Reimposta la cache dei prompt al punto di compattazione, come fa qualsiasi compattazione.

Altre due forme comuni falliscono così come sono scritte e richiedono una modifica ciascuna:

• La compattazione keep-tail riassume i turni più vecchi e mantiene i turni più recenti alla lettera. I blocchi di pensiero dei turni mantenuti sono stati prodotti rispetto alla cronologia completa, quindi falliscono dietro il riassunto. Correzione: rimuovi thinking e redacted_thinking da ogni turno dell'assistente che porti avanti, mantenendo text e tool_use, oppure invia prefix_mismatch_behavior: "drop_block" e lascia che l'API li rimuova.
• La compattazione in background costruisce il riassunto fuori dal percorso critico e lo sostituisce mentre la conversazione continua, quindi ogni turno prodotto nel frattempo ha un pensiero che precede la sostituzione. Correzione: invia "drop_block" su ogni richiesta che contiene ancora blocchi di pensiero prodotti prima della sostituzione (oppure rimuovi tu stesso quei blocchi; input_transformations nella prima risposta dopo la sostituzione elenca esattamente quali), oppure compatta in modo sincrono.

Tagliare singoli turni dal mezzo della trascrizione invalida tutto ciò che li segue, e nessuna forma lato client lo evita. Usa un messaggio di sistema a metà conversazione per la modifica di istruzioni che stavi facendo, oppure il context editing lato server per la rimozione selettiva.

Non compattare nel mezzo di un round di strumenti: un turno dell'assistente il cui tool_use è ancora in attesa di un tool_result dovrebbe tornare indietro con il suo pensiero intatto, in modo che il modello concluda il round con il suo ragionamento (vedi Preservare i blocchi di pensiero).

Fai riferimento ai file tramite ID, non tramite URL il cui contenuto cambia

Per un blocco image o document con una sorgente url, i byte recuperati fanno parte del prefisso verificato mentre la stringa dell'URL no. Un endpoint "ultimo screenshot" o un documento modificato invalida il pensiero successivo. Un URL firmato a rotazione per lo stesso file no. Per i contenuti a cui fai riferimento attraverso i turni, caricali una volta con la Files API e usa il file_id, oppure invia base64.

Decidi cosa succede in caso di mancata corrispondenza

Una volta che la tua integrazione è append-only, scegli un prefix_mismatch_behavior per la produzione. Governa solo le mancate corrispondenze del prefisso. Un blocco che il modello corrente non può leggere (dopo un cambio di router o un fallback lato server) viene sempre scartato, e segnalato in input_transformations quando viene inviato l'header beta.

• "error" (il valore predefinito) se una mancata corrispondenza del prefisso può significare solo un bug nel tuo codice. Lo scopri da un 400 in fase di test piuttosto che da blocchi scartati silenziosamente. Nella Message Batches API, il valore predefinito non impostato scarta i blocchi che falliscono invece di far fallire l'elemento del batch; imposta "error" esplicitamente se vuoi che gli elementi diano errore.
• "drop_block" se preferisci scartare i blocchi interessati piuttosto che fallire. Registra input_transformations.

Se intercetti il 400 in produzione, riprovare la stessa richiesta non lo risolverà. Riprova con prefix_mismatch_behavior: "drop_block" (e l'header beta), che rimuove esattamente i blocchi che falliscono, inclusi quelli in un turno dell'assistente il cui tool_use è ancora in attesa del suo tool_result. Lo scarto si applica solo a quella richiesta, quindi continua a inviare "drop_block" (e l'header beta) per il resto della sessione. Senza la beta, rimuovi ogni blocco thinking e redacted_thinking dalla cronologia, lasciando al loro posto i blocchi text e tool_use di ogni turno, e riprova una volta. Poi correggi la modifica che lo ha causato.

Funzionalità dell'API usate in questa pagina

Per combinare gli header in una richiesta:

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

Gli stessi nomi beta si applicano su Amazon Bedrock e Google Cloud. Consulta Header beta per sapere come inviarli con ciascun SDK.

Checklist

• Se un prodotto o SDK ufficiale Claude (Claude Code, claude.ai, Claude Managed Agents, il Claude Agent SDK) gestisce la cronologia della tua conversazione, fermati qui.
• I corpi delle richieste consecutive sono identici byte per byte in system, tools e nel prefisso condiviso di messages.
• Una sessione completa con prefix_mismatch_behavior: "drop_block" non registra voci prefix_binding_mismatch.
• I turni dell'assistente tornano indietro byte per byte come restituiti, tutti i tipi di blocco inclusi.
• system e tools di primo livello sono fissi per la sessione. Le modifiche vanno in messaggi role: "system" e blocchi tool_addition / tool_removal.
• I promemoria per turno sono messaggi di sistema con ambito di turno (o blocchi di testo finali) che vengono aggiunti ex novo e mai rimossi.
• Il contesto viene ridotto tramite compattazione o context editing, oppure tramite una compattazione lato client che non lascia blocchi di pensiero dietro il prefisso riscritto e non divide mai un round di strumenti.
• I file usati attraverso i turni sono file_id o base64, non URL mutabili.
• Un prefix_mismatch_behavior di produzione è impostato e i suoi 400 o le voci scartate sono monitorati.

Passaggi successivi