Pensamiento preservado

En Claude Fable 5.1, cambiar turnos anteriores de la conversación (la indicación system, las tools o cualquier mensaje anterior) afecta la respuesta de la API. De forma predeterminada, hace que la API rechace la solicitud con un error, a menos que optes por que los bloques de pensamiento afectados se descarten de lo que ve el modelo (prefix_mismatch_behavior: "drop_block"). La verificación se aplica de forma predeterminada para las cuentas nuevas creadas a partir del 31 de agosto de 2026, 00:00 UTC. Hay más detalles en Cómo funciona y A quién afecta.

Cuando envías un bloque de vuelta, la API usa su signature para verificar que la conversación anterior no haya cambiado y que el modelo actual pueda leer el bloque. La verificación existe para que el razonamiento producido bajo un conjunto de instrucciones no pueda reproducirse bajo otro conjunto de instrucciones, potencialmente adversario.

La API proporciona alternativas de primera clase para modificar una conversación a medida que avanza, que cubren la mayoría de los casos de uso de edición de transcripciones: mensajes de sistema a mitad de conversación para nuevas instrucciones, mensajes de sistema con alcance de turno para recordatorios por turno, cambios de herramientas a mitad de conversación para agregar y quitar herramientas, y esfuerzo por mensaje para ajustar la profundidad del pensamiento por turno. El resto de esta página cubre cómo saber si tu integración está afectada y cómo migrar los patrones comunes de harness a estas funciones. Como beneficio adicional, mantener todo lo que precede a cada bloque de pensamiento sin cambios byte por byte también mantiene el prefijo estable para el "prompt caching" (almacenamiento en caché de prompts).

Si necesitas hacer algo depende de qué administra tu historial de conversación:

• Usas un producto o SDK oficial de Claude: Claude Code, claude.ai, Claude Managed Agents o el Claude Agent SDK. Estos mantienen el prefijo intacto por ti.
• Llamas a la Messages API directamente, desde tu propio bucle de agente o cualquier otro entorno. Debes revisar tu código y asegurarte de que el arreglo messages se trate como de solo anexado (append-only). Estos patrones comunes editan el prefijo e invalidan el pensamiento posterior a la edición:
  • Recortar o descartar turnos antiguos
  • Resumir turnos antiguos en el cliente y conservar los recientes
  • Inyectar un recordatorio en un turno anterior y quitarlo en la siguiente solicitud
  • Reconstruir la indicación system en cada solicitud (hora actual, presupuesto de tokens, indicadores de modo)
  • Agregar o quitar entradas en tools a mitad de sesión

Cómo funciona

Para las solicitudes nuevas, la API verifica:

• El modelo es el mismo o más nuevo. Un bloque es legible por el modelo que lo produjo y por modelos posteriores, no por modelos anteriores. Una conversación que pasa a un modelo más nuevo conserva su razonamiento. Una conversación que pasa a un modelo más antiguo falla la verificación de modelo para esos bloques, y la API los descarta para esa solicitud. Consulta Pensamiento preservado para ver la lista exacta por modelo.
• Nada antes del bloque ha cambiado. La indicación system de nivel superior, el conjunto de herramientas en tools y cada mensaje anterior al bloque. Con la compactación del lado del servidor, el prefijo verificado comienza en el bloque de compactación más reciente.
• La cadena de bloques de pensamiento anteriores no está rota. Los bloques thinking y redacted_thinking anteriores no forman parte del prefijo, pero cada bloque de pensamiento registra el que lo precede, a través de los turnos. Puedes quitar bloques de pensamiento del inicio del historial. Quitar uno del medio invalida todos los bloques de pensamiento posteriores.

Un bloque que falla la verificación de modelo siempre se descarta. Para una discrepancia de prefijo, tú eliges qué sucede con thinking.block_binding.prefix_mismatch_behavior, que requiere el encabezado beta thinking-binding-controls-2026-08-01:

• "drop_block": la API quita el bloque y todos los bloques de pensamiento posteriores en la conversación, y la solicitud tiene éxito. Los bloques descartados no se facturan. La respuesta los enumera en un arreglo input_transformations de nivel superior (en el evento message_start cuando se usa streaming).
• "error": la API rechaza la solicitud con un 400 invalid_request_error que nombra el primer bloque que falla.

El valor predeterminado es "error". El encabezado te permite establecer el campo y agrega input_transformations a las respuestas.

A quién afecta

Claude Fable 5.1. Consulta Pensamiento preservado para ver la lista de modelos.

En Claude Fable 5.1, la API aplica la verificación para las cuentas nuevas. Una cuenta nueva es una creada a partir del 31 de agosto de 2026, 00:00 UTC. La misma definición se aplica en la Claude API y en las plataformas en la nube. Los modelos posteriores aplicarán la verificación para todos los usuarios.

Una solicitud que establece prefix_mismatch_behavior opta por la aplicación de la verificación independientemente de la antigüedad de la cuenta, que es la forma de probar desde una cuenta más antigua. Para verificar si tu cuenta tiene la aplicación activada de forma predeterminada, envía una solicitud que edite el historial sin el encabezado beta: un 400 que nombre el encabezado significa que está activada.

Cómo saber si tu integración está afectada

Captura los cuerpos exactos de las solicitudes que tu integración envía durante algunos turnos normales, incluyendo una compactación o un cambio de herramientas si tu producto los hace. Para cada par de solicitudes consecutivas, compara system, tools y la parte compartida de messages. Deben ser idénticos byte por byte hasta los turnos recién anexados.

Luego confirma contra la API. Con el encabezado beta thinking-binding-controls-2026-08-01 y claude-fable-5-1, establece thinking.block_binding.prefix_mismatch_behavior en "drop_block" y ejecuta una sesión normal de varios turnos a través de tu integración. Esta solicitud es el segundo turno de una sesión así, enviando de vuelta el turno de asistente de la primera respuesta exactamente como se recibió:

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 respuesta lleva entonces un arreglo input_transformations de nivel superior. Regístralo en cada turno:

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

• Vacío en cada turno: tu integración mantiene el historial intacto.
• reason: "prefix_binding_mismatch": algo antes del bloque en path cambió entre esta solicitud y la anterior. Compara system, tools y messages hasta ese turno para encontrarlo.
• reason: "model_binding_mismatch": la conversación pasó a un modelo que no puede leer los bloques del modelo anterior (un enrutador, un fallback). No es un error en tu integración. Sigue enviando los bloques y deja que la API descarte lo que el modelo actual no puede leer.

Esto funciona desde cualquier cuenta, porque establecer el campo hace que la solicitud opte por la aplicación de la verificación. Para fallar de forma visible en CI, establece "error". El 400 comienza así:

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

Sin el encabezado beta en la solicitud, el mensaje continúa: That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header. El mensaje normalmente termina con una oración que nombra lo que cambió, por ejemplo que la indicación system o la lista tools difiere de cuando se creó el bloque.

Consulta Solución de problemas del pensamiento para ver todas las variantes de este error.

Qué cuenta como una edición

Entre dos solicitudes consecutivas:

Actualiza tu integración

Cada patrón reemplaza un tipo de edición del historial con una función de la API que tiene el mismo efecto en el modelo sin cambiar los bytes anteriores.

Anexa los turnos de asistente exactamente como se devolvieron

Almacena el arreglo content de cada respuesta y envíalo de vuelta sin cambios como el turno de asistente, cada tipo de bloque en el orden recibido, incluidos los bloques thinking cuyo campo thinking está vacío. No vuelvas a serializar a través de un tipo intermedio que descarte tipos de bloque desconocidos o campos vacíos.

Agrega instrucciones con un mensaje de sistema a mitad de conversación, no editando system

Si tu código reconstruye la indicación system de nivel superior en cada solicitud (hora actual, presupuesto de tokens, indicador de modo, contexto de proyecto recién descubierto), cada bloque de pensamiento de la conversación falla la verificación. Congela system al inicio de la sesión y, cuando algo cambie, anexa un mensaje role: "system" en el punto de messages donde se vuelve verdadero:

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

El modelo lo trata con la autoridad de una indicación del sistema, y todo lo anterior permanece sin cambios. No se necesita encabezado beta en Claude Fable 5.1. En un bucle de herramientas, colócalo después del mensaje de usuario tool_result, nunca entre un tool_use del asistente y su tool_result (consulta Limitaciones).

Envía recordatorios por turno como mensajes de sistema con alcance de turno

La edición de historial más común es el empujón por turno: una línea anexada después de cada lote de resultados de herramientas ("solicita las lecturas independientes juntas", "hace tiempo que no actualizas al usuario") y quitada en la siguiente solicitud para que los recordatorios no se acumulen. Quitarla es la edición.

En su lugar, envía el empujón como un mensaje de sistema a mitad de conversación con clear_at: "next_user_message" después del mensaje de usuario tool_result (encabezado beta mid-conversation-system-clear-at-2026-08-21). Este arreglo messages es la solicitud después de dos rondas de herramientas. messages[3] es el empujón de la solicitud anterior, dejado en su lugar, y messages[6] es la copia de esta solicitud:

[
  { "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 mensaje de usuario que solo contiene tool_result cuenta como el "siguiente mensaje de usuario", así que messages[3] ya está limpiado: no renderiza nada y no cuesta tokens de entrada, pero sigue en el arreglo, por lo que el pensamiento en messages[4] sigue siendo válido. messages[6] es lo que el modelo ve en este turno. En solicitudes posteriores, mantén ambos donde están y anexa la siguiente copia después del siguiente mensaje tool_result. Los mensajes con alcance de turno llevan solo text y no aceptan cache_control. Coloca el punto de interrupción de caché en el turno de usuario precedente. Consulta Mensajes de sistema con alcance de turno.

Sin la beta, anexa el empujón como un bloque text después de los bloques tool_result en el mismo mensaje de usuario, y deja las copias anteriores en su lugar. El modelo actúa según la más reciente.

Cambia herramientas con tool_addition y tool_removal, no editando tools

Si el conjunto de herramientas cambia a mitad de sesión (una herramienta se desbloquea después de la autenticación, una herramienta peligrosa se retira después de un cambio de modo), no edites tools. Declara el conjunto completo al inicio de la sesión y usa cambios de herramientas a mitad de conversación para ofrecer o retirar una herramienta a partir de ese punto (encabezado beta mid-conversation-tool-changes-2026-07-01). Una herramienta que aún no está disponible recibe defer_loading: true y un bloque tool_addition posterior, con la misma forma que este 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." }
  ]
}

Una herramienta cuyo esquema conoces a mitad de sesión (un servidor MCP descubierto en tiempo de ejecución) puede anexarse a tools con defer_loading: true y ofrecerse con tool_addition. Una herramienta diferida sin referencias no forma parte del prefijo, así que anexarla es seguro. Anexar una herramienta normal no lo es.

Recorta el contexto en el servidor donde puedas

El truncamiento y el resumen del lado del cliente son la segunda edición más común: descartar o resumir los turnos más antiguos y conservar los recientes textualmente. Los bloques de pensamiento de los turnos recientes se produjeron mientras el historial que quitaste todavía estaba en su lugar, así que fallan la verificación. Los equivalentes del lado del servidor no cuentan como ediciones, porque la verificación compara la conversación tal como la enviaste:

• La compactación resume los turnos antiguos en un bloque de compactación cuando el contexto se acerca a un umbral que tú estableces, y el prefijo verificado se reinicia desde ese bloque. Su parámetro instructions acepta tu propio prompt de resumen ("preserva cada ticker, tamaño de posición y supuesto declarado").
• La edición de contexto limpia resultados de herramientas antiguos (clear_tool_uses_20250919) o bloques de pensamiento antiguos empezando por los más viejos (clear_thinking_20251015) según reglas.

Compactación personalizada en el cliente

Esta verificación no prohíbe la compactación del lado del cliente. La regla es más estrecha: no conserves un bloque de pensamiento detrás de un prefijo que hayas reescrito.

La compactación simple es la forma recomendada y no necesita cambios. Cuando la conversación se vuelve demasiado larga, resúmela en un mensaje y comienza la siguiente solicitud con ese resumen más el nuevo turno de usuario, sin reproducir turnos ni bloques de pensamiento anteriores: messages se convierte en [{"role": "user", "content": "<summary of the session so far>\n\n<the next instruction>"}]. No queda pensamiento anterior, así que nada falla, y el modelo piensa de nuevo sobre la conversación compactada. Los modelos Claude están entrenados en tareas de horizonte largo con este esquema, y su rendimiento es comparable al de esquemas más elaborados para la mayoría de las cargas de trabajo. Reinicia la caché de prompts en el punto de compactación, como lo hace cualquier compactación.

Otras dos formas comunes fallan tal como están escritas y necesitan un cambio cada una:

• La compactación que conserva la cola resume los turnos antiguos y conserva los turnos más recientes textualmente. Los bloques de pensamiento de los turnos conservados se produjeron contra el historial completo, así que fallan detrás del resumen. Solución: quita thinking y redacted_thinking de cada turno de asistente que traslades, conservando text y tool_use, o envía prefix_mismatch_behavior: "drop_block" y deja que la API los quite.
• La compactación en segundo plano construye el resumen fuera de la ruta crítica y lo intercambia mientras la conversación continúa, así que cada turno producido mientras tanto tiene pensamiento anterior al intercambio. Solución: envía "drop_block" en cada solicitud que todavía lleve bloques de pensamiento producidos antes del intercambio (o quita esos bloques tú mismo; input_transformations en la primera respuesta después del intercambio enumera exactamente cuáles), o compacta de forma síncrona.

Recortar turnos individuales del medio de la transcripción invalida todo lo que viene después, y ninguna forma del lado del cliente evita eso. Usa un mensaje de sistema a mitad de conversación para el cambio de instrucción que estabas haciendo, o la edición de contexto del lado del servidor para la eliminación selectiva.

No compactes en medio de una ronda de herramientas: un turno de asistente cuyo tool_use todavía espera un tool_result debe enviarse de vuelta con su pensamiento intacto, para que el modelo termine la ronda con su razonamiento (consulta Preservar bloques de pensamiento).

Referencia archivos por ID, no por una URL cuyo contenido cambia

Para un bloque image o document con una fuente url, los bytes obtenidos forman parte del prefijo verificado y la cadena de la URL no. Un endpoint de "última captura de pantalla" o un documento editado invalida el pensamiento posterior. Una URL firmada rotativa para el mismo archivo no. Para contenido al que haces referencia a través de turnos, súbelo una vez con la Files API y usa el file_id, o envía base64.

Decide qué sucede ante una discrepancia

Una vez que tu integración sea de solo anexado, elige un prefix_mismatch_behavior para producción. Solo rige las discrepancias de prefijo. Un bloque que el modelo actual no puede leer (después de un cambio de enrutador o un fallback del lado del servidor) siempre se descarta, y se informa en input_transformations cuando se envía el encabezado beta.

• "error" (el predeterminado) si una discrepancia de prefijo solo puede significar un error en tu código. Te enteras por un 400 en las pruebas en lugar de por bloques descartados silenciosamente. En la Message Batches API, el valor predeterminado sin establecer descarta los bloques que fallan en lugar de hacer fallar el elemento del lote; establece "error" explícitamente si quieres que los elementos den error.
• "drop_block" si prefieres descartar los bloques afectados en lugar de fallar. Registra input_transformations.

Si capturas el 400 en producción, reintentar la misma solicitud no lo resolverá. Reintenta con prefix_mismatch_behavior: "drop_block" (y el encabezado beta), lo que quita exactamente los bloques que fallan, incluidos los de un turno de asistente cuyo tool_use todavía espera su tool_result. El descarte se aplica solo a esa solicitud, así que sigue enviando "drop_block" (y el encabezado beta) durante el resto de la sesión. Sin la beta, quita cada bloque thinking y redacted_thinking del historial, dejando los bloques text y tool_use de cada turno en su lugar, y reintenta una vez. Luego corrige la edición que lo causó.

Funciones de la API usadas en esta página

Para combinar encabezados en una solicitud:

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

Los mismos nombres de beta se aplican en Amazon Bedrock y Google Cloud. Consulta Encabezados beta para ver cómo enviarlos con cada SDK.

Lista de verificación

• Si un producto o SDK oficial de Claude (Claude Code, claude.ai, Claude Managed Agents, el Claude Agent SDK) administra tu historial de conversación, detente aquí.
• Los cuerpos de solicitudes consecutivas son idénticos byte por byte en system, tools y el prefijo compartido de messages.
• Una sesión completa bajo prefix_mismatch_behavior: "drop_block" no registra entradas prefix_binding_mismatch.
• Los turnos de asistente se envían de vuelta byte por byte como se devolvieron, con todos los tipos de bloque incluidos.
• system y tools de nivel superior están fijos durante la sesión. Los cambios van en mensajes role: "system" y bloques tool_addition / tool_removal.
• Los recordatorios por turno son mensajes de sistema con alcance de turno (o bloques de texto al final) que se anexan nuevos y nunca se quitan.
• El contexto se recorta mediante compactación o edición de contexto, o mediante una compactación del lado del cliente que no deja bloques de pensamiento detrás del prefijo reescrito y nunca divide una ronda de herramientas.
• Los archivos entre turnos son file_id o base64, no URLs mutables.
• Hay un prefix_mismatch_behavior de producción establecido y sus 400 o entradas descartadas se monitorean.

Próximos pasos