Cambia herramientas o instrucciones sin fallar la verificación de prefijo

Para actualizar herramientas, instrucciones u otro contexto, deja todo lo que enviaste tal como estaba y agrega la actualización al final, donde permanece. En los modelos con “preserved thinking” (pensamiento preservado), cambiar lo que enviaste puede invalidar el pensamiento posterior, y la solicitud puede fallar.

Los modelos con “preserved thinking” (pensamiento preservado) son Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 y Claude Haiku 5.5.

Devuelve los turnos del asistente exactamente

Devuelve todo el arreglo content de cada respuesta, en orden, incluidos los “thinking blocks” (bloques de pensamiento) cuyo texto está vacío. Un bloque con texto vacío está completo, porque su signature contiene el razonamiento, cifrado. Un turno que contiene un bloque fallback tiene su propia regla.

Los serializadores, filtros y analizadores de stream pueden romper esto.

Cambia las instrucciones

Mantén system igual en cada solicitud. Pon tus propias instrucciones en un mensaje role: "system" al final, y envía uno solo cuando algo haya cambiado. Claude lo trata como una instrucción tuya, el operador. Déjalo durante el resto de la conversación, porque eliminarlo o reformularlo después invalida el pensamiento posterior. Las palabras de tu usuario tienen su propia regla.

Un recordatorio que debe acompañar cada turno es diferente: envía uno que se borre solo.

El mensaje del sistema va después del mensaje de usuario más reciente, incluso uno con resultados de herramientas. Un mensaje del sistema con texto o bloques de herramientas recibe un error 400 justo después del turno de Claude o justo antes de un mensaje de usuario. Así que, cuando el turno de Claude es el último, espera hasta que el siguiente mensaje de usuario esté en su lugar.

Un mensaje del sistema no garantiza que Claude siga una instrucción, así que aplica límites como el modo de solo lectura en el código que ejecuta tus herramientas. Algunos modelos no aceptan mensajes del sistema.

Texto que otras personas pueden editar

Pregúntate si tu usuario esperaría que Claude confíe en un archivo, como un AGENTS.md o CLAUDE.md que otras personas pueden editar, o en la memoria almacenada. Si no, envía su texto solo en un bloque tool_result, incluida la primera versión. Para saber por qué, consulta Inyección indirecta de prompts.

No pongas ese texto en un mensaje del sistema ni en el texto de un mensaje de usuario, y en conversaciones nuevas, no lo pongas en system.

Cuando cargues ese archivo o cambie, indícale a Claude que lo lea con una herramienta, y no incluyas su texto. O bien, después del siguiente mensaje de usuario, agrega tú mismo la llamada a la herramienta y su resultado: un mensaje assistant con un bloque tool_use y luego un mensaje user cuyo bloque tool_result contenga el texto. Para ver los pasos, consulta Escribe tú mismo la llamada a la herramienta.

Un archivo que tu usuario espera que Claude siga puede ir en un mensaje de usuario. Un archivo de instrucciones que solo tú controlas puede ir en un mensaje del sistema: cárgalo una vez y agrega cada versión actualizada.

Actualiza la fecha, los archivos u otro contexto

Construye system y el primer mensaje una vez, y envíalos sin cambios en cada solicitud.

Pon un valor actualizado en su propio bloque de texto del mensaje de usuario que estás a punto de enviar, después de cualquier resultado de herramienta:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Environment update: the current branch is now release-2." },
    { "type": "text", "text": "Run the tests again." }
  ]
}

Indícalo solo cuando cambie, y déjalo ahí.

Almacena cualquier contexto que tu código agregue a un mensaje junto con ese mensaje. De lo contrario, la siguiente solicitud envía algo diferente antes del mismo pensamiento.

Agrega, elimina o desactiva herramientas

Mantén tools igual en cada solicitud. Agregar, cambiar o eliminar una herramienta ahí, salvo una diferida, invalida el pensamiento que ya está en la conversación, porque tools va antes de todo él. Basta con una oración reformulada en una descripción.

Para agregar o eliminar una herramienta, agrega al final un mensaje del sistema con un bloque tool_addition o tool_removal y el encabezado beta para tu caso. Haz lo mismo cuando se conecte un servidor MCP o un plugin.

Para desactivar las herramientas en una solicitud, establece tool_choice: {"type": "none"} y mantén tools como estaba.

Recorta o resume los turnos anteriores

Para conservar los turnos recientes con su pensamiento, deja que la API escriba el resumen con compactación bajo demanda, bajo las condiciones para el pensamiento conservado. Comienza messages con el bloque de compactación que devuelve, y elimina los mensajes que resume.

Si tu propio código escribe el resumen, o corta turnos anteriores sin uno, elimina el pensamiento de los turnos conservados o envía "drop_block". Cada nuevo corte vuelve a invalidar el pensamiento de los turnos conservados, así que corta con poca frecuencia, en pasos grandes. Para borrar resultados de herramientas antiguos en su lugar, usa la edición de contexto.

Guarda, reanuda o bifurca una conversación

Almacena lo que enviaste y lo que recibiste, y envía exactamente eso. Una conversación reanudada es una siguiente solicitud normal: system, tools y los messages anteriores deben tener los valores que tenían. Para una bifurcación, pon la instrucción de la rama en su primer mensaje de usuario nuevo, o en un mensaje del sistema después de ese. El pensamiento no puede pasar a una conversación con un historial diferente: en su lugar, inicia esa conversación a partir de un resumen.

Una versión que cambia tu “system prompt” (indicación del sistema) o tus herramientas es un cambio en las conversaciones que ya están en curso. La corrección que hace que tu código sea “append-only” (de solo anexar) también puede serlo. Sigue enviando a cada conversación en curso el system y las tools de su última solicitud exitosa, porque su pensamiento más reciente se produjo después de esa versión. Volver a una versión anterior invalidaría ese pensamiento.

Usa el system y las tools actualizados en las conversaciones nuevas. Si la versión elimina una herramienta o cambia una instrucción por seguridad, aplícala también a las conversaciones en curso. Agrega al final un bloque tool_removal o un mensaje del sistema.

Elimina secretos, datos personales o texto inyectado

La seguridad y la privacidad van antes que mantener válido el pensamiento. Si un mensaje contiene un secreto o datos personales que debes eliminar, elimina ese texto. Elimínalo también de cada mensaje y resumen que lo repita.

Para un resultado de herramienta con instrucciones inyectadas, reemplaza su contenido con una nota breve como “Eliminado.” Conserva el bloque tool_result en sí, porque su tool_use necesita uno. Si un bloque de compactación contiene el texto, elimina el bloque y empieza desde tu propio resumen.

Luego elimina cada bloque thinking y redacted_thinking posterior al primer lugar donde apareció el texto. Si estaba en system o tools, son todos. Cada bloque puede repetir el texto, y no puedes leer ni editar lo que contiene. Enviar "drop_block" no basta aquí, porque deja esos bloques en tu historial almacenado. La conversación continúa sin ese razonamiento.

Después de un resultado inyectado, es posible que los turnos posteriores ya hayan actuado en consecuencia. Revisa las llamadas a herramientas hechas desde entonces y deshaz lo que necesites.

Detalles técnicos

Formas en que el código cambia los turnos del asistente

• Un serializador omite los tipos de bloque que no conoce, o reordena, combina o divide bloques. Eso cambia lo que venía antes de cada bloque posterior.
• El código omite los bloques de pensamiento que parecen vacíos. Si los omite todos, Claude pierde ese razonamiento. Si omite solo algunos, el hueco invalida el pensamiento posterior.
• Un analizador de stream propio omite un bloque de pensamiento que no recibió texto. Los ayudantes de stream del SDK lo conservan.

Omite el pensamiento

Claude pierde el razonamiento que omites. Omite los bloques más antiguos, los más recientes o todos, pero ninguno intermedio. Cada bloque registra aquel después del cual se produjo, así que un hueco invalida los bloques posteriores. Los bloques de pensamiento sin ningún otro bloque entre ellos en un turno pasan juntos por la verificación de prefijo, así que omítelos todos o ninguno. Una vez que un bloque queda fuera, mantenlo fuera.

Mientras una llamada a herramienta esté abierta, devuelve el pensamiento de ese turno, para que Claude termine la ronda con su razonamiento.

Tus instrucciones en un bucle de herramientas

Los mensajes van en este orden:

[
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_01",
        "name": "run_tests",
        "input": { "path": "tests/" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "2 failed, 48 passed" }
    ]
  },
  {
    "role": "system",
    "content": "Plan mode is off. You can edit files."
  }
]

Escribe tú mismo la llamada a la herramienta

Declara una herramienta que lea archivos en la primera solicitud, o agrégala después en un mensaje del sistema, y haz que tu código responda a las llamadas de Claude a ella. Después del siguiente mensaje de usuario, agrega un mensaje assistant con un bloque tool_use para esa herramienta. Justo después, agrega un mensaje user cuyo bloque tool_result tenga el tool_use_id correspondiente y contenga el texto del archivo. Claude responde después de eso:

[
  { "role": "user", "content": "Run the tests again." },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_app_agents_md_1",
        "name": "read_file",
        "input": { "path": "AGENTS.md" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_app_agents_md_1",
        "content": "The file's text"
      }
    ]
  }
]

Deja ambos en su lugar, y agrega un nuevo par, con un nuevo id, para cada versión nueva.

Las palabras de tu usuario y los valores actualizados en un bucle de herramientas

Si transmites lo que tu usuario escribió mientras Claude trabajaba, agrégalo antes de enviar el mensaje de usuario que lleva los bloques tool_result. Hazlo un bloque de texto después del último tool_result.

Un valor que viene de ti puede ir en un mensaje del sistema en su lugar. Después de los resultados de herramientas, Claude Sonnet 5.5 y Claude Haiku 5.5 pueden ignorar las palabras de un usuario en un mensaje del sistema como una inyección de prompt. Claude Sonnet 5.5 puede hacer lo mismo con tus propias instrucciones y recordatorios si vienen después de cada resultado de herramienta.

El mensaje de usuario con los resultados de herramientas debe contener solo bloques tool_result cuando el turno también llamó a una herramienta de servidor que aún no tiene resultado, o usó llamadas programáticas a herramientas. En ese caso, agrega el texto al siguiente mensaje de usuario.

Modelos que no aceptan mensajes del sistema

En la Claude API, todos los modelos con pensamiento preservado aceptan mensajes del sistema. Para un modelo que no los acepta, consulta Cuando un modelo no acepta mensajes del sistema.

Envía un recordatorio para un turno

Envía un recordatorio como un mensaje del sistema con alcance de turno: establece clear_at: "next_user_message" y envía el encabezado beta mid-conversation-system-clear-at-2026-08-21. Va después del mensaje de usuario que lleva los bloques tool_result:

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "Run the linter before you report that a task is done."
}

En el siguiente mensaje de usuario, incluso uno con solo bloques tool_result, la API lo borra, así que Claude deja de leerlo. En Claude Sonnet 5.5, no envíes uno después de cada resultado de herramienta. Conserva cada recordatorio en tus messages, borrado o no, a menos que contenga algo que debas eliminar. Eliminar o reformular uno invalida el pensamiento posterior.

Sin el encabezado, envía un mensaje del sistema normal y déjalo en su lugar. Nunca se borra, así que los recordatorios se acumulan. En un modelo que no acepta mensajes del sistema, usa un bloque de texto en el mensaje de usuario.

Qué bloque y encabezado beta necesita un cambio de herramienta

Para ver las plataformas que aceptan cada encabezado, consulta Mensajes del sistema y cambios de herramientas a mitad de conversación.

• Si conoces todas las herramientas desde el inicio: Declara todas en la primera solicitud, con defer_loading: true en las que ofreces después. Luego nombra la herramienta en un bloque tool_addition o tool_removal de un mensaje del sistema. Encabezado beta: inline-tools-2026-09-15 o mid-conversation-tool-changes-2026-07-01.
• Si te enteras de una herramienta después, o tienes una cuyo esquema cambia: Define la herramienta en un bloque tool_addition de un mensaje del sistema. Encabezado beta: inline-tools-2026-09-15.
• Si te enteras de una herramienta después, en una plataforma sin el encabezado inline-tools-2026-09-15: Agrega la herramienta al final de tools con defer_loading: true, lo cual no es un cambio, y luego ofrécela por nombre. Encabezado beta: mid-conversation-tool-changes-2026-07-01.
• Si conectas un servidor MCP tarde a través del conector MCP, en la Claude API: Define su mcp_toolset en un bloque tool_addition. Encabezados beta: inline-tools-2026-09-15 y mcp-client-2026-09-15.

Si la lista de herramientas de un servidor MCP puede cambiar, consulta Fija la lista de herramientas de un servidor MCP.

Este mensaje del sistema ofrece por nombre una herramienta declarada y define otra, lo que necesita inline-tools-2026-09-15:

{
  "role": "system",
  "content": [
    {
      "type": "tool_addition",
      "tool": { "type": "tool_reference", "name": "search_tickets" }
    },
    {
      "type": "tool_addition",
      "tool": {
        "type": "tool_definition",
        "definition": {
          "name": "get_weather",
          "description": "Get the current weather in a city.",
          "input_schema": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    }
  ]
}

Herramientas con defer_loading y el error 400 que lo nombra

Una herramienta con defer_loading: true queda fuera del contexto de Claude y de la “prefix check” (verificación de prefijo) hasta que un mensaje o un resultado de búsqueda de herramientas hace referencia a ella. Hasta entonces, agregarla, actualizarla o eliminarla no es un cambio. Después, sí lo es. Activar o desactivar defer_loading también cuenta como cambiar tools.

Declara al menos una herramienta que no sea diferida, o la solicitud puede recibir un error 400 que nombra defer_loading.

Acorta o borra resultados e imágenes antiguos

Acorta o reduce la resolución de un resultado de herramienta o imagen antes de enviarlo por primera vez. Si tu código borra, acorta o vuelve a codificar algo que ya envió, el pensamiento posterior deja de ser válido. Para borrar resultados de herramientas antiguos más adelante, incluidas las imágenes que contengan, usa la edición de contexto. Envía context_management con una edición de tipo clear_tool_uses_20250919 y el encabezado beta context-management-2025-06-27. Para ver la solicitud completa y sus opciones, consulta Edición de contexto.

Archivos que envías por URL

Para un archivo por URL, la API compara los bytes que obtuvo. Así que, cuando una URL firmada caduca, una nueva para el mismo archivo está bien. Si el contenido detrás de una URL puede cambiar, envía un file_id o base64 desde la primera solicitud.

Si tu propio código resume o corta turnos anteriores

Después de tu propio resumen o corte, el pensamiento de un turno conservado falla la verificación de prefijo, porque los mensajes después de los cuales venía ya no están. Elimina ese pensamiento, o envía "drop_block". Claude sigue leyendo el turno sin él.

Bibliotecas, proxies y gateways

Si las solicitudes de otras personas pasan por tu código, tus reescrituras cambian su historial, y es posible que no puedan ver ni corregir esos cambios. No ocultes el error 400. Si te recuperas en nombre de quien llama, indícalo, porque su historial aún contiene el cambio.

• Pasa los valores de anthropic-beta y thinking.block_binding tal como se enviaron. Si tu gateway permite solo campos conocidos, agrega thinking.block_binding y el valor de encabezado thinking-binding-controls-2026-08-01, o tus usuarios no podrán elegir "drop_block".
• No elimines el encabezado beta y reenvíes la configuración. Esa solicitud recibe un error 400.
• Devuelve a quien llama los bloques de pensamiento cuyo texto está vacío y el arreglo input_transformations.
• Deja un mensaje role: "system" donde está. Moverlo a system invalida el pensamiento que ya está en la conversación.
• Prueba con prefix_mismatch_behavior establecido en "error", lo que produce el error en todos los modelos con pensamiento preservado.

Próximos pasos