Tools oder Anweisungen ändern, ohne dass die Präfixprüfung fehlschlägt

Um Tools, Anweisungen oder anderen Kontext zu aktualisieren, lass alles, was du gesendet hast, so, wie es war, und füge die Aktualisierung am Ende hinzu, wo sie bleibt. Auf Modellen mit „preserved thinking“ (bewahrtes Nachdenken) kann eine Änderung an dem, was du gesendet hast, das Nachdenken danach ungültig machen, und die Anfrage kann fehlschlagen.

Die Modelle mit „preserved thinking“ (Bewahrtes Nachdenken) sind Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5.

Assistant-Turns exakt zurücksenden

Sende das gesamte content-Array jeder Antwort in der richtigen Reihenfolge zurück, einschließlich Thinking-Blöcken, deren Text leer ist. Ein Block mit leerem Text ist vollständig, denn seine signature enthält das Reasoning, verschlüsselt. Für einen Turn, der einen fallback-Block enthält, gilt eine eigene Regel.

Serialisierer, Filter und Stream-Parser können das aushebeln.

Anweisungen ändern

Halte system bei jeder Anfrage gleich. Setze deine eigenen Anweisungen in eine role: "system"-Nachricht am Ende, und sende eine nur dann, wenn sich etwas geändert hat. Claude behandelt sie als Anweisung von dir, dem Betreiber. Lass sie für den Rest der Konversation stehen, denn wenn du sie später löschst oder umformulierst, wird das Nachdenken danach ungültig. Für die Worte deiner Nutzer gilt eine eigene Regel.

Eine Erinnerung, die mit jedem Turn mitkommen muss, ist etwas anderes: Sende eine, die sich selbst leert.

Die System-Nachricht kommt nach der neuesten Nutzernachricht, auch nach einer mit Tool-Ergebnissen. Eine System-Nachricht mit Text- oder Tool-Blöcken erhält direkt nach Claudes Turn oder direkt vor einer Nutzernachricht einen 400-Fehler. Wenn also Claudes Turn der letzte ist, warte, bis die nächste Nutzernachricht vorhanden ist.

Eine System-Nachricht garantiert nicht, dass Claude einer Anweisung folgt, also setze Einschränkungen wie einen Nur-Lese-Modus in dem Code um, der deine Tools ausführt. Einige Modelle akzeptieren keine System-Nachrichten.

Text, den andere Personen bearbeiten können

Frage dich, ob dein Nutzer erwarten würde, dass Claude einer Datei vertraut, etwa einer AGENTS.md oder CLAUDE.md, die andere Personen bearbeiten können, oder gespeicherten Erinnerungen. Falls nicht, sende ihren Text nur in einem tool_result-Block, die erste Version eingeschlossen. Zu den Gründen siehe Indirekte Prompt-Injection.

Setze solchen Text nicht in eine System-Nachricht oder in den Text einer Nutzernachricht, und setze ihn in neuen Konversationen nicht in system.

Wenn du eine solche Datei lädst oder sie sich ändert, sag Claude, dass es sie mit einem Tool lesen soll, und füge ihren Text nicht ein. Oder hänge nach der nächsten Nutzernachricht den Tool-Aufruf und sein Ergebnis selbst an: eine assistant-Nachricht mit einem tool_use-Block, dann eine user-Nachricht, deren tool_result-Block den Text enthält. Die Schritte findest du unter Den Tool-Aufruf selbst schreiben.

Eine Datei, von der dein Nutzer erwartet, dass Claude ihr folgt, kann in eine Nutzernachricht. Eine Anweisungsdatei, die nur du kontrollierst, kann in eine System-Nachricht: Lade sie einmal und hänge jede aktualisierte Version an.

Datum, Dateien oder anderen Kontext aktualisieren

Erstelle system und die erste Nachricht einmal und sende sie bei jeder Anfrage unverändert.

Setze einen aktualisierten Wert in einen eigenen Textblock der Nutzernachricht, die du gleich sendest, nach allen Tool-Ergebnissen:

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

Gib ihn nur an, wenn er sich ändert, und lass ihn dort stehen.

Speichere jeden Kontext, den dein Code zu einer Nachricht hinzufügt, zusammen mit dieser Nachricht. Andernfalls sendet die nächste Anfrage vor demselben Nachdenken etwas anderes.

Tools hinzufügen, entfernen oder deaktivieren

Halte tools bei jeder Anfrage gleich. Wenn du dort ein Tool hinzufügst, änderst oder entfernst, außer einem zurückgestellten, wird das bereits in der Konversation vorhandene Nachdenken ungültig, denn tools steht vor all dem. Ein einziger umformulierter Satz in einer Beschreibung reicht dafür aus.

Um ein Tool hinzuzufügen oder zu entfernen, hänge eine System-Nachricht mit einem tool_addition- oder tool_removal-Block und dem Beta-Header für deinen Fall an. Mach dasselbe, wenn sich ein MCP-Server oder Plugin verbindet.

Um Tools für eine einzelne Anfrage zu deaktivieren, setze tool_choice: {"type": "none"} und lass tools so, wie es war.

Ältere Turns kürzen oder zusammenfassen

Um neuere Turns mit ihrem Nachdenken zu behalten, lass die API die Zusammenfassung mit On-Demand-Komprimierung schreiben, unter den Bedingungen für beibehaltenes Nachdenken. Beginne messages mit dem Komprimierungsblock, den sie zurückgibt, und entferne die Nachrichten, die er zusammenfasst.

Wenn dein eigener Code die Zusammenfassung schreibt oder ältere Turns ohne eine solche abschneidet, entferne das Nachdenken der beibehaltenen Turns oder sende "drop_block". Jeder neue Schnitt macht das Nachdenken der beibehaltenen Turns erneut ungültig, also schneide selten und in großen Schritten. Um stattdessen alte Tool-Ergebnisse zu löschen, verwende Kontextbearbeitung.

Eine Konversation speichern, fortsetzen oder verzweigen

Speichere, was du gesendet und was du empfangen hast, und sende genau das. Eine fortgesetzte Konversation ist eine gewöhnliche nächste Anfrage: system, tools und frühere messages müssen die Werte haben, die sie hatten. Bei einer Verzweigung setze die Anweisung des Zweigs in seine erste neue Nutzernachricht oder in eine System-Nachricht danach. Nachdenken kann nicht in eine Konversation mit einem anderen Verlauf übertragen werden: Beginne diese Konversation stattdessen mit einer Zusammenfassung.

Ein Release, das deinen System-Prompt oder deine Tools ändert, ist eine Änderung in bereits laufenden Konversationen. Die Korrektur, die deinen Code append-only (nur anhängend) macht, kann ebenfalls eine sein. Sende jeder laufenden Konversation weiterhin das system und die tools ihrer letzten erfolgreichen Anfrage, denn ihr neuestes Nachdenken wurde nach dieser Version erzeugt. Eine Rückkehr zu einer früheren Version würde dieses Nachdenken ungültig machen.

Verwende das aktualisierte system und die aktualisierten tools in neuen Konversationen. Wenn das Release aus Sicherheitsgründen ein Tool entfernt oder eine Anweisung ändert, wende es auch auf laufende Konversationen an. Hänge einen tool_removal-Block oder eine System-Nachricht an.

Geheimnisse, personenbezogene Daten oder eingeschleusten Text entfernen

Sicherheit und Datenschutz haben Vorrang davor, das Nachdenken gültig zu halten. Wenn eine Nachricht ein Geheimnis oder personenbezogene Daten enthält, die du löschen musst, entferne diesen Text. Entferne ihn auch aus jeder Nachricht und Zusammenfassung, die ihn wiederholt.

Bei einem Tool-Ergebnis mit eingeschleusten Anweisungen ersetze seinen Inhalt durch einen kurzen Hinweis wie „Entfernt.“ Behalte den tool_result-Block selbst, denn sein tool_use braucht einen. Wenn ein Komprimierungsblock den Text enthält, lösche den Block und beginne mit deiner eigenen Zusammenfassung.

Lösche dann jeden thinking- und redacted_thinking-Block nach der ersten Stelle, an der der Text auftauchte. Wenn er in system oder tools stand, sind das alle. Jeder Block kann den Text wiederholen, und du kannst nicht lesen oder bearbeiten, was darin steht. "drop_block" zu senden reicht hier nicht aus, denn dabei bleiben diese Blöcke in deinem gespeicherten Verlauf. Die Konversation läuft ohne dieses Reasoning weiter.

Nach einem eingeschleusten Ergebnis könnten spätere Turns bereits darauf reagiert haben. Prüfe die seitdem erfolgten Tool-Aufrufe und mache rückgängig, was nötig ist.

Technische Details

Wie Code Assistant-Turns verändert

• Ein Serialisierer lässt Blocktypen, die er nicht kennt, weg, oder ordnet Blöcke um, führt sie zusammen oder teilt sie auf. Das ändert, was vor jedem späteren Block stand.
• Code überspringt Thinking-Blöcke, die leer aussehen. Wenn er alle überspringt, verliert Claude dieses Reasoning. Wenn er nur einige überspringt, macht die Lücke das Nachdenken danach ungültig.
• Ein eigener Stream-Parser lässt einen Thinking-Block weg, der keinen Text erhalten hat. Die Stream-Helfer des SDK behalten ihn.

Nachdenken weglassen

Claude verliert das Reasoning, das du weglässt. Lass die ältesten Blöcke, die neuesten oder alle weg, aber keine dazwischen. Jeder Block zeichnet auf, nach welchem Block er erzeugt wurde, sodass eine Lücke die Blöcke danach ungültig macht. Thinking-Blöcke, zwischen denen in einem Turn kein anderer Block steht, werden gemeinsam geprüft, also lass alle oder keinen davon weg. Sobald ein Block weggelassen ist, lass ihn weiterhin weg.

Solange ein Tool-Aufruf offen ist, sende das Nachdenken dieses Turns zurück, damit Claude die Runde mit seinem Reasoning abschließt.

Deine Anweisungen in einer Tool-Schleife

Die Nachrichten kommen in dieser Reihenfolge:

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

Den Tool-Aufruf selbst schreiben

Deklariere bei der ersten Anfrage ein Tool, das Dateien liest, oder füge es später in einer System-Nachricht hinzu, und lass deinen Code Claudes Aufrufe dieses Tools beantworten. Hänge nach der nächsten Nutzernachricht eine assistant-Nachricht mit einem tool_use-Block für dieses Tool an. Hänge direkt danach eine user-Nachricht an, deren tool_result-Block die passende tool_use_id hat und den Text der Datei enthält. Claude antwortet danach:

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

Lass beide stehen und hänge für jede neue Version ein neues Paar mit einer neuen id an.

Die Worte deiner Nutzer und aktualisierte Werte in einer Tool-Schleife

Wenn du weitergibst, was dein Nutzer eingegeben hat, während Claude gearbeitet hat, füge es hinzu, bevor du die Nutzernachricht sendest, die die tool_result-Blöcke enthält. Mach daraus einen Textblock nach dem letzten tool_result.

Ein Wert, der von dir kommt, kann stattdessen in eine System-Nachricht. Nach Tool-Ergebnissen können Claude Sonnet 5.5 und Claude Haiku 5.5 die Worte eines Nutzers in einer System-Nachricht als Prompt-Injection ignorieren. Claude Sonnet 5.5 kann dasselbe mit deinen eigenen Anweisungen und Erinnerungen tun, wenn sie nach jedem Tool-Ergebnis kommen.

Die Nutzernachricht mit den Tool-Ergebnissen darf nur tool_result-Blöcke enthalten, wenn der Turn auch ein Server-Tool aufgerufen hat, das noch kein Ergebnis hat, oder programmatische Tool-Aufrufe verwendet hat. Füge den Text dann der nächsten Nutzernachricht hinzu.

Modelle, die keine System-Nachrichten akzeptieren

Auf der Claude API akzeptiert jedes Modell mit bewahrtem Nachdenken System-Nachrichten. Für ein Modell, das sie nicht akzeptiert, siehe Wenn ein Modell keine System-Nachrichten akzeptiert.

Eine Erinnerung für einen Turn senden

Sende eine Erinnerung als turn-gebundene System-Nachricht: Setze clear_at: "next_user_message" und sende den Beta-Header mid-conversation-system-clear-at-2026-08-21. Sie kommt nach der Nutzernachricht, die die tool_result-Blöcke enthält:

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

Bei der nächsten Nutzernachricht, selbst einer mit nur tool_result-Blöcken, leert die API sie, sodass Claude sie nicht mehr liest. Auf Claude Sonnet 5.5 sende keine nach jedem Tool-Ergebnis. Behalte jede Erinnerung in deinen messages, ob geleert oder nicht, es sei denn, sie enthält etwas, das du entfernen musst. Wenn du eine entfernst oder umformulierst, wird das Nachdenken danach ungültig.

Ohne den Header sende eine einfache System-Nachricht und lass sie stehen. Sie wird nie geleert, sodass sich Erinnerungen ansammeln. Auf einem Modell, das keine System-Nachrichten annimmt, verwende einen Textblock in der Nutzernachricht.

Welchen Block und welchen Beta-Header eine Tool-Änderung braucht

Welche Plattformen welchen Header annehmen, findest du unter System-Nachrichten und Tool-Änderungen mitten im Gespräch.

• Wenn du jedes Tool von Anfang an kennst: Deklariere sie alle bei der ersten Anfrage, mit defer_loading: true bei denen, die du später anbietest. Nenne das Tool dann in einem tool_addition- oder tool_removal-Block einer System-Nachricht. Beta-Header: inline-tools-2026-09-15 oder mid-conversation-tool-changes-2026-07-01.
• Wenn du erst später von einem Tool erfährst oder eines hast, dessen Schema sich ändert: Definiere das Tool in einem tool_addition-Block einer System-Nachricht. Beta-Header: inline-tools-2026-09-15.
• Wenn du erst später von einem Tool erfährst, auf einer Plattform ohne den Header inline-tools-2026-09-15: Füge das Tool am Ende von tools mit defer_loading: true hinzu, was keine Änderung ist, und biete es dann namentlich an. Beta-Header: mid-conversation-tool-changes-2026-07-01.
• Wenn du einen MCP-Server über den MCP-Connector spät verbindest, auf der Claude API: Definiere sein mcp_toolset in einem tool_addition-Block. Beta-Header: inline-tools-2026-09-15 und mcp-client-2026-09-15.

Wenn sich die Tool-Liste eines MCP-Servers ändern kann, siehe Die Tool-Liste eines MCP-Servers festlegen.

Diese System-Nachricht bietet ein deklariertes Tool namentlich an und definiert ein weiteres, was inline-tools-2026-09-15 erfordert:

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

Tools mit defer_loading und der 400-Fehler, der es nennt

Ein Tool mit defer_loading: true bleibt außerhalb von Claudes Kontext und der Präfixprüfung, bis eine Nachricht oder ein Tool-Suchergebnis darauf verweist. Bis dahin ist es keine Änderung, es hinzuzufügen, zu aktualisieren oder zu entfernen. Danach schon. Das Ein- oder Ausschalten von defer_loading zählt ebenfalls als Änderung von tools.

Deklariere mindestens ein Tool, das nicht zurückgestellt ist, sonst kann die Anfrage einen 400-Fehler erhalten, der defer_loading nennt.

Alte Ergebnisse und Bilder kürzen oder löschen

Kürze oder verkleinere ein Tool-Ergebnis oder Bild, bevor du es zum ersten Mal sendest. Wenn dein Code etwas löscht, kürzt oder neu kodiert, das er bereits gesendet hat, wird das Nachdenken danach ungültig. Um alte Tool-Ergebnisse später zu löschen, einschließlich darin enthaltener Bilder, verwende Kontextbearbeitung. Sende context_management mit einer Bearbeitung vom Typ clear_tool_uses_20250919 und den Beta-Header context-management-2025-06-27. Die vollständige Anfrage und ihre Optionen findest du unter Kontextbearbeitung.

Dateien, die du per URL sendest

Bei einer Datei per URL vergleicht die API die Bytes, die sie abgerufen hat. Wenn also eine signierte URL abläuft, ist eine neue für dieselbe Datei in Ordnung. Wenn sich der Inhalt hinter einer URL ändern kann, sende ab der ersten Anfrage eine file_id oder base64.

Wenn dein eigener Code ältere Turns zusammenfasst oder abschneidet

Nach deiner eigenen Zusammenfassung oder deinem eigenen Schnitt schlägt beim Nachdenken eines beibehaltenen Turns die Präfixprüfung fehl, weil die Nachrichten, auf die es folgte, weg sind. Entferne dieses Nachdenken oder sende "drop_block". Claude liest den Turn trotzdem, nur ohne es.

Bibliotheken, Proxys und Gateways

Wenn Anfragen anderer Personen durch deinen Code laufen, ändern deine Umschreibungen deren Verlauf, und sie können diese Änderungen möglicherweise nicht sehen oder beheben. Verstecke den 400-Fehler nicht. Wenn du die Konversation für den Aufrufer wiederherstellst, sag es, denn sein Verlauf enthält die Änderung weiterhin.

• Reiche anthropic-beta-Werte und thinking.block_binding so weiter, wie sie gesendet wurden. Wenn dein Gateway nur bekannte Felder zulässt, füge thinking.block_binding und den Header-Wert thinking-binding-controls-2026-08-01 hinzu, sonst können deine Nutzer "drop_block" nicht wählen.
• Entferne nicht den Beta-Header, während du die Einstellung weiterleitest. Diese Anfrage erhält einen 400-Fehler.
• Gib Thinking-Blöcke, deren Text leer ist, und das input_transformations-Array an den Aufrufer zurück.
• Lass eine role: "system"-Nachricht dort, wo sie ist. Wenn du sie in system verschiebst, wird das bereits in der Konversation vorhandene Nachdenken ungültig.
• Teste mit prefix_mismatch_behavior auf "error" gesetzt, was den Fehler auf jedem Modell mit bewahrtem Nachdenken auslöst.

Nächste Schritte