SPB Git

Repository Public

mid-conversation-system-messages.md 58.2 KB 1,200 lines markdown

1---2title: Mid-conversation system messages and tool changes3url: https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages4description: Change system instructions or tool availability partway through a conversation without invalidating the cached prefix that came before them.5---67<Note>8  To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).9</Note>1011System instructions normally live in the top-level `system` field, ahead of every message in the conversation. That position is great for [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): the system prompt is part of the stable prefix, so subsequent turns hit the cache. It is a poor position for instructions you only discover you need partway through a session, because editing the top-level `system` field changes the very beginning of the prompt and invalidates the cache for everything that follows.1213Mid-conversation system messages close that gap. You append a `{"role": "system"}` message at the point in the conversation where the new instruction becomes relevant, instead of editing the top-level `system` field. The cached prefix stays the same, so the next request still reads it from cache, and the new instruction is still applied as a system instruction rather than as ordinary user text.1415<Note>16  Mid-conversation system messages are available on the Claude API, [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai).1718  This feature is available on Claude Fable 5.1, [Claude Mythos 5.1](https://anthropic.com/glasswing), Claude Fable 5, [Claude Mythos 5](https://anthropic.com/glasswing), Claude Opus 4.8, and Claude Opus 5. No beta header is required for mid-conversation system messages. This feature is not available on Claude Sonnet 5. Use the top-level `system` field there instead.1920  [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta and require the `mid-conversation-tool-changes-2026-07-01` beta header. They are available on the same models, on the Claude API, Amazon Bedrock, and Google Cloud.2122  [Turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at`) are in beta and require the `mid-conversation-system-clear-at-2026-08-21` beta header, on the same models and platforms as mid-conversation system messages.23</Note>2425## Mid-conversation tool changes2627The `tools` array sits even earlier in the hashed request prefix than the top-level `system` field, so editing it invalidates the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for the entire conversation. Mid-conversation tool changes are the tools counterpart to mid-conversation system messages. Instead of fixing the tool list for the lifetime of the conversation, you change which tools are offered to the model between turns: declare the full tool set in `tools` up front, then use `tool_addition` and `tool_removal` blocks to offer a tool to the model, or withdraw it, from a specific point in the conversation onward. The `tools` array itself never changes, so the cached prefix stays intact.2829`tool_addition` and `tool_removal` are content blocks in the `content` array of a `role: "system"` message, and they can be mixed with `text` blocks in the same message. The message follows the placement rules for any mid-conversation system message, with one extra restriction after a paused turn (see [Limitations](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)), and the change applies from that point in the conversation onward. Each block's `tool` field references a tool rather than defining one: `{"type": "tool_reference", "name": "..."}` names a tool declared in the request's `tools` array, and [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) tools can be referenced individually with `mcp_tool_reference` (`server_name` and `name`) or as a whole toolset with `mcp_toolset_reference` (`server_name`). Referencing a name that is not declared in `tools` returns a 400 error (on the Claude API, with `error.details.error_code` set to `tool_reference_unresolved`).3031Every tool declared in `tools` is offered to the model from the start of the conversation unless it is declared with `defer_loading: true`, which keeps it withheld until a `tool_addition` block surfaces it. `tool_addition` also re-offers a tool that an earlier `tool_removal` withdrew.3233The following request declares `get_weather` in `tools`, then withdraws it after the first user turn with a `tool_removal` block. Mid-conversation tool changes are in beta, so the request sends the `mid-conversation-tool-changes-2026-07-01` beta header.3435<CodeGroup>36  ```bash cURL37  curl https://api.anthropic.com/v1/messages \38    -H "content-type: application/json" \39    -H "x-api-key: $ANTHROPIC_API_KEY" \40    -H "anthropic-version: 2023-06-01" \41    -H "anthropic-beta: mid-conversation-tool-changes-2026-07-01" \42    -d '{43      "model": "claude-opus-5",44      "max_tokens": 1024,45      "tools": [46        {47          "name": "get_weather",48          "description": "Get the current weather for a location.",49          "input_schema": {50            "type": "object",51            "properties": {52              "location": {"type": "string", "description": "City name"}53            },54            "required": ["location"]55          }56        }57      ],58      "messages": [59        {60          "role": "user",61          "content": "Say OK."62        },63        {64          "role": "system",65          "content": [66            {67              "type": "tool_removal",68              "tool": {"type": "tool_reference", "name": "get_weather"}69            }70          ]71        }72      ]73    }'74  ```7576  ```bash CLI77  ant beta:messages create --beta mid-conversation-tool-changes-2026-07-01 \78    --transform 'content.#(type=="text").text' --raw-output <<'YAML'79  model: claude-opus-580  max_tokens: 102481  tools:82    - name: get_weather83      description: Get the current weather for a location.84      input_schema:85        type: object86        properties:87          location:88            type: string89            description: City name90        required:91          - location92  messages:93    - role: user94      content: Say OK.95    - role: system96      content:97        - type: tool_removal98          tool:99            type: tool_reference100            name: get_weather101  YAML102  ```103104  ```python Python105  client = anthropic.Anthropic()106107  response = client.beta.messages.create(108      model="claude-opus-5",109      max_tokens=1024,110      betas=["mid-conversation-tool-changes-2026-07-01"],111      # The full tool set is declared up front and never changes, so the112      # cached prefix stays intact.113      tools=[114          {115              "name": "get_weather",116              "description": "Get the current weather for a location.",117              "input_schema": {118                  "type": "object",119                  "properties": {120                      "location": {"type": "string", "description": "City name"},121                  },122                  "required": ["location"],123              },124          },125      ],126      messages=[127          {128              "role": "user",129              "content": "Say OK.",130          },131          # Withdraw get_weather from this point onward. The block references132          # the tool by name instead of editing `tools`, so earlier turns stay133          # byte-identical and the cache still hits.134          {135              "role": "system",136              "content": [137                  {138                      "type": "tool_removal",139                      "tool": {"type": "tool_reference", "name": "get_weather"},140                  },141              ],142          },143      ],144  )145146  for block in response.content:147      if block.type == "text":148          print(block.text)149  ```150151  ```typescript TypeScript152  const client = new Anthropic();153154  const response = await client.beta.messages.create({155    model: "claude-opus-5",156    max_tokens: 1024,157    betas: ["mid-conversation-tool-changes-2026-07-01"],158    // The full tool set is declared up front and never changes, so the159    // cached prefix stays intact.160    tools: [161      {162        name: "get_weather",163        description: "Get the current weather for a location.",164        input_schema: {165          type: "object",166          properties: {167            location: {168              type: "string",169              description: "City name"170            }171          },172          required: ["location"]173        }174      }175    ],176    messages: [177      { role: "user", content: "Say OK." },178      // Withdraw get_weather from this point onward. The block references the179      // tool by name instead of editing `tools`, so earlier turns stay180      // byte-identical and the cache still hits.181      {182        role: "system",183        content: [184          {185            type: "tool_removal",186            tool: { type: "tool_reference", name: "get_weather" }187          }188        ]189      }190    ]191  });192193  for (const block of response.content) {194    if (block.type === "text") {195      console.log(block.text);196    }197  }198  ```199200  ```csharp C#201  using Anthropic.Models.Beta.Messages;202  using Messages = Anthropic.Models.Messages;203204  AnthropicClient client = new();205206  var response = await client.Beta.Messages.Create(new MessageCreateParams207  {208      Model = Messages::Model.ClaudeOpus5,209      MaxTokens = 1024,210      Betas = ["mid-conversation-tool-changes-2026-07-01"],211      // The full tool set is declared up front and never changes, so the212      // cached prefix stays intact.213      Tools =214      [215          new BetaTool216          {217              Name = "get_weather",218              Description = "Get the current weather for a location.",219              InputSchema = new InputSchema220              {221                  Properties = new Dictionary<string, JsonElement>222                  {223                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "City name" }),224                  },225                  Required = ["location"],226              },227          },228      ],229      Messages =230      [231          new() { Role = Role.User, Content = "Say OK." },232          // Withdraw get_weather from this point onward. The block references233          // the tool by name instead of editing `Tools`, so earlier turns stay234          // byte-identical and the cache still hits.235          new()236          {237              Role = Role.System,238              Content = new(239              [240                  new BetaRequestToolRemovalBlock241                  {242                      Tool = new BetaToolChangeToolReference { Name = "get_weather" },243                  },244              ]),245          },246      ],247  });248249  foreach (var block in response.Content)250  {251      if (block.TryPickText(out var text))252      {253          Console.WriteLine(text.Text);254      }255  }256  ```257258  ```go Go259  client := anthropic.NewClient()260261  response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{262  	Model:     anthropic.ModelClaudeOpus5,263  	MaxTokens: 1024,264  	Betas:     []anthropic.AnthropicBeta{"mid-conversation-tool-changes-2026-07-01"},265  	// The full tool set is declared up front and never changes, so the266  	// cached prefix stays intact.267  	Tools: []anthropic.BetaToolUnionParam{268  		{OfTool: &anthropic.BetaToolParam{269  			Name:        "get_weather",270  			Description: anthropic.String("Get the current weather for a location."),271  			InputSchema: anthropic.BetaToolInputSchemaParam{272  				Properties: map[string]any{273  					"location": map[string]any{274  						"type":        "string",275  						"description": "City name",276  					},277  				},278  				Required: []string{"location"},279  			},280  		}},281  	},282  	Messages: []anthropic.BetaMessageParam{283  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Say OK.")),284  		// Withdraw get_weather from this point onward. The block references285  		// the tool by name instead of editing Tools, so earlier turns stay286  		// byte-identical and the cache still hits.287  		{288  			Role: anthropic.BetaMessageParamRoleSystem,289  			Content: []anthropic.BetaContentBlockParamUnion{290  				anthropic.NewBetaToolRemovalBlock(anthropic.BetaToolChangeToolReferenceParam{291  					Name: "get_weather",292  				}),293  			},294  		},295  	},296  })297  if err != nil {298  	log.Fatal(err)299  }300301  for _, block := range response.Content {302  	if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {303  		fmt.Println(textBlock.Text)304  	}305  }306  ```307308  ```java Java309  import com.anthropic.models.beta.messages.BetaContentBlockParam;310  import com.anthropic.models.beta.messages.BetaMessage;311  import com.anthropic.models.beta.messages.BetaMessageParam;312  import com.anthropic.models.beta.messages.BetaRequestToolRemovalBlock;313  import com.anthropic.models.beta.messages.BetaTool;314  import com.anthropic.models.beta.messages.MessageCreateParams;315  // ...316      AnthropicClient client = AnthropicOkHttpClient.fromEnv();317318      // The full tool set is declared up front and never changes, so the319      // cached prefix stays intact.320      BetaTool weatherTool = BetaTool.builder()321          .name("get_weather")322          .description("Get the current weather for a location.")323          .inputSchema(BetaTool.InputSchema.builder()324              .properties(BetaTool.InputSchema.Properties.builder()325                  .putAdditionalProperty("location", JsonValue.from(Map.of(326                      "type", "string",327                      "description", "City name")))328                  .build())329              .addRequired("location")330              .build())331          .build();332333      MessageCreateParams params = MessageCreateParams.builder()334          .model(Model.CLAUDE_OPUS_5)335          .maxTokens(1024)336          .addBeta("mid-conversation-tool-changes-2026-07-01")337          .addTool(weatherTool)338          .addUserMessage("Say OK.")339          // Withdraw get_weather from this point onward. The block references340          // the tool by name instead of editing `tools`, so earlier turns stay341          // byte-identical and the cache still hits.342          .addMessage(BetaMessageParam.builder()343              .role(BetaMessageParam.Role.SYSTEM)344              .contentOfBetaContentBlockParams(List.of(345                  BetaContentBlockParam.ofToolRemoval(BetaRequestToolRemovalBlock.builder()346                      .referenceTool("get_weather")347                      .build())))348              .build())349          .build();350351      BetaMessage response = client.beta().messages().create(params);352      response.content().stream()353          .flatMap(block -> block.text().stream())354          .forEach(textBlock -> IO.println(textBlock.text()));355  ```356357  ```php PHP358  $client = new Client();359360  $response = $client->beta->messages->create(361      model: 'claude-opus-5',362      maxTokens: 1024,363      betas: ['mid-conversation-tool-changes-2026-07-01'],364      // The full tool set is declared up front and never changes, so the365      // cached prefix stays intact.366      tools: [367          [368              'name' => 'get_weather',369              'description' => 'Get the current weather for a location.',370              'input_schema' => [371                  'type' => 'object',372                  'properties' => [373                      'location' => [374                          'type' => 'string',375                          'description' => 'City name',376                      ],377                  ],378                  'required' => ['location'],379              ],380          ],381      ],382      messages: [383          ['role' => 'user', 'content' => 'Say OK.'],384          // Withdraw get_weather from this point onward. The block references385          // the tool by name instead of editing `tools`, so earlier turns stay386          // byte-identical and the cache still hits.387          [388              'role' => 'system',389              'content' => [390                  [391                      'type' => 'tool_removal',392                      'tool' => ['type' => 'tool_reference', 'name' => 'get_weather'],393                  ],394              ],395          ],396      ],397  );398399  foreach ($response->content as $block) {400      if ($block->type === 'text') {401          echo $block->text, PHP_EOL;402      }403  }404  ```405406  ```ruby Ruby407  client = Anthropic::Client.new408409  response = client.beta.messages.create(410    model: "claude-opus-5",411    max_tokens: 1024,412    betas: ["mid-conversation-tool-changes-2026-07-01"],413    # The full tool set is declared up front and never changes, so the414    # cached prefix stays intact.415    tools: [416      {417        name: "get_weather",418        description: "Get the current weather for a location.",419        input_schema: {420          type: "object",421          properties: {422            location: { type: "string", description: "City name" }423          },424          required: ["location"]425        }426      }427    ],428    messages: [429      { role: "user", content: "Say OK." },430      # Withdraw get_weather from this point onward. The block references431      # the tool by name instead of editing `tools`, so earlier turns stay432      # byte-identical and the cache still hits.433      {434        role: "system",435        content: [436          {437            type: "tool_removal",438            tool: { type: "tool_reference", name: "get_weather" }439          }440        ]441      }442    ]443  )444445  response.content.each do |block|446    puts block.text if block.type == :text447  end448  ```449</CodeGroup>450451## When to use a mid-conversation system message452453[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hashes the request prefix in order: `tools`, then `system`, then `messages`. A cache hit requires the prefix to match a recent request exactly, byte for byte, up to the cache breakpoint.454455That ordering means the top-level `system` field sits near the very start of the hashed prefix. Any change to it, even appending a sentence, produces a different hash, and the request misses the cache for the system prompt and every cached message after it.456457Mid-conversation system messages let you add the instruction at the **end** of the message history instead. Everything before the new instruction is unchanged, so the existing cache entry still matches, and only the new message is processed as fresh input.458459A few situations where this matters:460461* **Mid-session policy or persona changes.** A long agentic session needs a new constraint ("from now on, write all SQL as parameterized queries") after dozens of cached turns. Adding it to the top-level `system` field would re-process the entire history.462* **Per-turn context that must be authoritative.** You want to inject a freshness note, a session deadline, or a tool-availability change with system-level weight, and it changes too often to live in the cached prefix.463* **Per-turn reminders that shouldn't pile up.** A harness nudges the model after each batch of tool results ("request independent reads together", "the user hasn't heard from you in a while") and wants the model to see only the newest copy. A [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) renders for one turn and then costs nothing, without deleting anything from the history.464* **State changes your application observes.** Your application notices something Claude should treat as an operator-level fact: files changed on disk, the user toggled an auto-approve setting, available tools changed, or the remaining token budget dropped below a threshold.465* **User input that should not interrupt an agentic loop.** A user types a follow-up while Claude is still executing tools for the previous request. Relaying it as a system message after the next tool result lets Claude fold the new input into the work it is already doing, instead of treating it as a fresh request to switch to. See [Placement after tool results](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#placement-after-tool-results).466* **Mode switches that grant standing permissions.** A session-level mode can use a mid-conversation system message to grant standing consent to an expensive capability, such as automatically launching multiagent workflows, with a short refresher every several turns and an exit notice when the mode is turned off. For a worked example, see [Build an orchestration mode](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-effort-example).467468In all of these cases you could put the instruction in a regular `user` message, and Claude does follow instructions that arrive in user turns. The difference is priority: a `user` message is treated as coming from the end user, while a `system` message is treated as coming from you, the application operator. When the two conflict, system instructions take precedence, so use the `system` role for operator-level facts and constraints that should hold even if the end user asks for something different. A mid-conversation system message keeps that operator-level priority without paying the cache-miss cost of editing the top-level `system` field.469470## How it works471472Add a message with `"role": "system"` to the `messages` array. Use a plain string or content blocks for `content`, the same as a `user` or `assistant` turn. The instruction applies from that point in the conversation onward. When instructions conflict, later system messages take precedence over earlier ones, and mid-conversation system messages take precedence over the top-level `system` field for the turns that follow them.473474You can still set the top-level `system` field for instructions that should apply to the entire conversation. Reserve mid-conversation system messages for instructions that only become relevant later, or that you want to add without invalidating the cached prefix.475476A `role: "system"` message can also carry `output_config.effort` to change the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level from the next `user` turn on. This is in beta on Claude Fable 5.1, Claude Mythos 5.1, and Claude Opus 5 on the Claude API and Google Cloud, and requires the `mid-conversation-output-config-2026-07-01` beta header. See [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta).477478<CodeGroup>479  ```bash cURL480  curl https://api.anthropic.com/v1/messages \481    -H "content-type: application/json" \482    -H "x-api-key: $ANTHROPIC_API_KEY" \483    -H "anthropic-version: 2023-06-01" \484    -d '{485      "model": "claude-opus-5",486      "max_tokens": 1024,487      "cache_control": {"type": "ephemeral"},488      "system": "You are a code review assistant. Be concise.",489      "messages": [490        {491          "role": "user",492          "content": "Review process() in utils.py for performance issues."493        },494        {495          "role": "assistant",496          "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list."497        },498        {499          "role": "user",500          "content": "Now review the calling code that invokes process()."501        },502        {503          "role": "system",504          "content": "From now on, every suggestion must include explicit type annotations."505        }506      ]507    }'508  ```509510  ```bash CLI511  ant messages create --transform 'content.#(type=="text").text' --raw-output <<'YAML'512  model: claude-opus-5513  max_tokens: 1024514  cache_control:515    type: ephemeral516  system: You are a code review assistant. Be concise.517  messages:518    - role: user519      content: Review process() in utils.py for performance issues.520    - role: assistant521      content: >-522        The list comprehension is fine for small inputs. For large inputs,523        consider a generator to avoid materializing the full list.524    - role: user525      content: Now review the calling code that invokes process().526    - role: system527      content: From now on, every suggestion must include explicit type annotations.528  YAML529  ```530531  ```python Python532  client = anthropic.Anthropic()533534  response = client.messages.create(535      model="claude-opus-5",536      max_tokens=1024,537      # Automatic prompt caching: each request caches the conversation so far,538      # and the next request reads the unchanged prefix from cache.539      cache_control={"type": "ephemeral"},540      system="You are a code review assistant. Be concise.",541      messages=[542          {543              "role": "user",544              "content": "Review process() in utils.py for performance issues.",545          },546          {547              "role": "assistant",548              "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.",549          },550          {551              "role": "user",552              "content": "Now review the calling code that invokes process().",553          },554          # The reviewer realizes mid-session that all suggestions must555          # also pass the team's strict typing policy. Appending the556          # instruction here keeps earlier turns byte-identical, so the557          # prefix cached by the previous request is still read from cache.558          {559              "role": "system",560              "content": "From now on, every suggestion must include explicit type annotations.",561          },562      ],563  )564565  for block in response.content:566      if block.type == "text":567          print(block.text)568  ```569570  ```typescript TypeScript571  const client = new Anthropic();572573  const response = await client.messages.create({574    model: "claude-opus-5",575    max_tokens: 1024,576    // Automatic prompt caching: each request caches the conversation so far,577    // and the next request reads the unchanged prefix from cache.578    cache_control: { type: "ephemeral" },579    system: "You are a code review assistant. Be concise.",580    messages: [581      {582        role: "user",583        content: "Review process() in utils.py for performance issues."584      },585      {586        role: "assistant",587        content:588          "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list."589      },590      {591        role: "user",592        content: "Now review the calling code that invokes process()."593      },594      // The reviewer realizes mid-session that all suggestions must also pass595      // the team's strict typing policy. Appending the instruction here keeps596      // earlier turns byte-identical, so the prefix cached by the previous597      // request is still read from cache.598      {599        role: "system",600        content: "From now on, every suggestion must include explicit type annotations."601      }602    ]603  });604605  const textBlock = response.content.find(606    (block): block is Anthropic.TextBlock => block.type === "text"607  );608  console.log(textBlock?.text);609  ```610611  ```csharp C#612  AnthropicClient client = new();613614  var parameters = new MessageCreateParams615  {616      Model = Model.ClaudeOpus5,617      MaxTokens = 1024,618      // Automatic prompt caching: each request caches the conversation so far,619      // and the next request reads the unchanged prefix from cache.620      CacheControl = new CacheControlEphemeral(),621      System = "You are a code review assistant. Be concise.",622      Messages =623      [624          new()625          {626              Role = Role.User,627              Content = "Review process() in utils.py for performance issues."628          },629          new()630          {631              Role = Role.Assistant,632              Content = "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list."633          },634          new()635          {636              Role = Role.User,637              Content = "Now review the calling code that invokes process()."638          },639          // The reviewer realizes mid-session that all suggestions must also pass640          // the team's strict typing policy. Appending the instruction here keeps641          // earlier turns byte-identical, so the prefix cached by the previous642          // request is still read from cache.643          new()644          {645              Role = Role.System,646              Content = "From now on, every suggestion must include explicit type annotations."647          }648      ]649  };650651  var response = await client.Messages.Create(parameters);652  Console.WriteLine(response);653  ```654655  ```go Go656  client := anthropic.NewClient()657658  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{659  	Model:     anthropic.ModelClaudeOpus5,660  	MaxTokens: 1024,661  	// Automatic prompt caching: each request caches the conversation so far,662  	// and the next request reads the unchanged prefix from cache.663  	CacheControl: anthropic.NewCacheControlEphemeralParam(),664  	System: []anthropic.TextBlockParam{665  		{Text: "You are a code review assistant. Be concise."},666  	},667  	Messages: []anthropic.MessageParam{668  		anthropic.NewUserMessage(anthropic.NewTextBlock("Review process() in utils.py for performance issues.")),669  		anthropic.NewAssistantMessage(anthropic.NewTextBlock("The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.")),670  		anthropic.NewUserMessage(anthropic.NewTextBlock("Now review the calling code that invokes process().")),671  		// The reviewer realizes mid-session that all suggestions must also672  		// pass the team's strict typing policy. Appending the instruction673  		// here keeps earlier turns byte-identical, so the prefix cached by674  		// the previous request is still read from cache.675  		{676  			Role: anthropic.MessageParamRoleSystem,677  			Content: []anthropic.ContentBlockParamUnion{678  				anthropic.NewTextBlock("From now on, every suggestion must include explicit type annotations."),679  			},680  		},681  	},682  })683  if err != nil {684  	log.Fatal(err)685  }686  for _, block := range response.Content {687  	if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {688  		fmt.Println(textBlock.Text)689  	}690  }691  ```692693  ```java Java694  import com.anthropic.models.messages.CacheControlEphemeral;695  // ...696  import com.anthropic.models.messages.MessageParam;697  // ...698      AnthropicClient client = AnthropicOkHttpClient.fromEnv();699700      MessageCreateParams params = MessageCreateParams.builder()701          .model(Model.CLAUDE_OPUS_5)702          .maxTokens(1024)703          // Automatic prompt caching: each request caches the conversation so far,704          // and the next request reads the unchanged prefix from cache.705          .cacheControl(CacheControlEphemeral.builder().build())706          .system("You are a code review assistant. Be concise.")707          .addUserMessage("Review process() in utils.py for performance issues.")708          .addAssistantMessage("The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.")709          .addUserMessage("Now review the calling code that invokes process().")710          // The reviewer realizes mid-session that all suggestions must also pass711          // the team's strict typing policy. Appending the instruction here keeps712          // earlier turns byte-identical, so the prefix cached by the previous713          // request is still read from cache.714          .addMessage(MessageParam.builder()715              .role(MessageParam.Role.SYSTEM)716              .content("From now on, every suggestion must include explicit type annotations.")717              .build())718          .build();719720      Message response = client.messages().create(params);721      response.content().stream()722          .flatMap(block -> block.text().stream())723          .forEach(textBlock -> IO.println(textBlock.text()));724  ```725726  ```php PHP727  use Anthropic\Messages\CacheControlEphemeral;728  // ...729  $client = new Client();730731  $response = $client->messages->create(732      maxTokens: 1024,733      messages: [734          ['role' => 'user', 'content' => 'Review process() in utils.py for performance issues.'],735          ['role' => 'assistant', 'content' => 'The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.'],736          ['role' => 'user', 'content' => 'Now review the calling code that invokes process().'],737          // The reviewer realizes mid-session that all suggestions must also pass738          // the team's strict typing policy. Appending the instruction here keeps739          // earlier turns byte-identical, so the prefix cached by the previous740          // request is still read from cache.741          ['role' => 'system', 'content' => 'From now on, every suggestion must include explicit type annotations.']742      ],743      model: 'claude-opus-5',744      // Automatic prompt caching: each request caches the conversation so far,745      // and the next request reads the unchanged prefix from cache.746      cacheControl: CacheControlEphemeral::with(),747      system: 'You are a code review assistant. Be concise.',748  );749750  foreach ($response->content as $block) {751      if ($block->type === 'text') {752          echo $block->text, PHP_EOL;753      }754  }755  ```756757  ```ruby Ruby758  client = Anthropic::Client.new759760  response = client.messages.create(761    model: "claude-opus-5",762    max_tokens: 1024,763    # Automatic prompt caching: each request caches the conversation so far,764    # and the next request reads the unchanged prefix from cache.765    cache_control: { type: "ephemeral" },766    system: "You are a code review assistant. Be concise.",767    messages: [768      { role: "user", content: "Review process() in utils.py for performance issues." },769      { role: "assistant", content: "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list." },770      { role: "user", content: "Now review the calling code that invokes process()." },771      # The reviewer realizes mid-session that all suggestions must also pass772      # the team's strict typing policy. Appending the instruction here keeps773      # earlier turns byte-identical, so the prefix cached by the previous774      # request is still read from cache.775      { role: "system", content: "From now on, every suggestion must include explicit type annotations." }776    ]777  )778779  response.content.each do |block|780    puts block.text if block.type == :text781  end782  ```783</CodeGroup>784785This example enables [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) with the top-level `cache_control` field. Prompt caching is opt-in: if a request has no `cache_control` field (automatic or an [explicit breakpoint](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)), nothing is cached and every request pays the regular input token price for the full conversation. With caching enabled, appending the system message leaves the already-cached turns unchanged, so the request that carries the new instruction still reads them from cache instead of processing them again. Caching also requires the conversation to meet the [minimum cacheable prompt length](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations); an example as short as this one falls below it, so `cache_creation_input_tokens` and `cache_read_input_tokens` stay at 0 until the conversation grows.786787A mid-conversation system message must immediately follow a `user` turn (or an `assistant` turn ending in a server tool result), and must either be the last entry in `messages` or be immediately followed by an `assistant` turn. A `user` message that carries `tool_result` blocks counts: in an agentic loop you can place the system message right after the tool results, before Claude's next turn. Any other position, including between an `assistant` `tool_use` block and the `tool_result` that answers it, returns a 400 error.788789### Placement after tool results790791In an [agentic loop](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), the system message goes after the `user` message that delivers the tool results. This is also where your application can relay input that the user typed while Claude was working, so the new context is absorbed without restarting the turn:792793```json794[795  { "role": "user", "content": "Run the test suite and fix any failures." },796  {797    "role": "assistant",798    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]799  },800  {801    "role": "user",802    "content": [803      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }804    ]805  },806  {807    "role": "system",808    "content": "The user sent the following message while you were working: also update the changelog before you finish."809  }810]811```812813Phrase the system content as context rather than as a command that overrides the user. State the fact ("new input arrived from the user: X", "the remaining token budget is now Y") and let Claude act on it. Claude is trained to resist instructions that appear to work against the user, and that protection still applies to the system role, so language such as "ignore what the user said" is less effective than stating what changed.814815This pattern is for relaying input from the conversation's own end user. Do not use it to pass tool output, retrieved documents, or other third-party content; keep that content in `tool_result` blocks (see [Limitations](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)).816817### Turn-scoped system messages818819To scope a `role: "system"` message to the current turn, set its `clear_at` field. It takes one of two values:820821* `"never"` (the default): the message renders at its position on every request that includes it. Omitting the field is identical.822* `"next_user_message"`: the message is **turn-scoped**. Its text renders only while no `role: "user"` message comes after it in `messages`. A user message that carries only `tool_result` blocks counts as a user message here. Once a later user message exists, the message is **cleared**: it stays in the array but renders nothing and costs no input tokens, on that request and every later one.823824Turn-scoped system messages are in beta. Include the [beta header](https://platform.claude.com/docs/en/api/beta-headers) `mid-conversation-system-clear-at-2026-08-21`. Without it, `clear_at` is rejected as an unknown field.825826```json827{828  "role": "system",829  "clear_at": "next_user_message",830  "content": "First privately list what you need next; then request every item that doesn't depend on another's result in this one response."831}832```833834The main use is a per-turn reminder in a tool loop. Append the reminder after the `tool_result` message each time you want the model to see it, and leave every earlier copy where it is. The model sees only the copies that come after the last user message, so the reminder never piles up. Nothing earlier in `messages` changes, so the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) keeps matching. On Claude Fable 5.1 this also keeps later [thinking blocks valid](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation): deleting an earlier reminder would change the conversation before those blocks and fail the conversation check, while a cleared message stays in the array and leaves that conversation unchanged.835836The following request is a later step of an agent loop. `messages[3]` rendered on the earlier request, when it was the last message in the array. Once `messages[5]` (a later user message) exists, `messages[3]` is cleared: the cleared message stays in the array, so the conversation before the thinking block in `messages[4]` is unchanged, but the model no longer sees its text. `messages[6]` and `messages[7]` both render, in order.837838```json839{840  "model": "claude-fable-5-1",841  "max_tokens": 16000,842  "messages": [843    { "role": "user", "content": "Fix the failing test." },844    {845      "role": "assistant",846      "content": [847        { "type": "thinking", "thinking": "", "signature": "..." },848        {849          "type": "tool_use",850          "id": "toolu_01",851          "name": "read_file",852          "input": { "path": "test_auth.py" }853        }854      ]855    },856    {857      "role": "user",858      "content": [{ "type": "tool_result", "tool_use_id": "toolu_01", "content": "..." }]859    },860    {861      "role": "system",862      "clear_at": "next_user_message",863      "content": "Request independent reads in one turn."864    },865    {866      "role": "assistant",867      "content": [868        { "type": "thinking", "thinking": "", "signature": "..." },869        {870          "type": "tool_use",871          "id": "toolu_02",872          "name": "read_file",873          "input": { "path": "auth.py" }874        },875        {876          "type": "tool_use",877          "id": "toolu_03",878          "name": "read_file",879          "input": { "path": "tokens.py" }880        }881      ]882    },883    {884      "role": "user",885      "content": [886        { "type": "tool_result", "tool_use_id": "toolu_02", "content": "..." },887        {888          "type": "tool_result",889          "tool_use_id": "toolu_03",890          "content": "...",891          "cache_control": { "type": "ephemeral" }892        }893      ]894    },895    {896      "role": "system",897      "clear_at": "next_user_message",898      "content": "Request independent reads in one turn."899    },900    {901      "role": "system",902      "clear_at": "next_user_message",903      "content": "The shell exited with status 137."904    }905  ]906}907```908909Rules for turn-scoped messages:910911* **Re-send cleared messages verbatim.** A cleared message is still part of the conversation history. Rebuilding it from current state (a fresh token count, a timestamp), dropping it as redundant, or changing its `clear_at` value is an edit to an earlier message. The prompt cache misses from that point, and on Claude Fable 5.1 every thinking block produced after it fails the [conversation check](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation).912* **Text only.** `content` is one or more `text` blocks (or a string). `tool_addition` and `tool_removal` blocks return a 400 error on a turn-scoped message, and so does `output_config`. Use a separate `role: "system"` message without `clear_at` for those.913* **No `cache_control` on its blocks.** A cleared message is never part of a cache key, so a breakpoint on it could never match. Put the breakpoint on the last block of the preceding user turn instead, as the example does. The top-level [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) field skips turn-scoped messages when it picks a breakpoint. On the request that clears a message, the reusable cached prefix ends at the user turn before it, so only the one assistant turn between that message and the new user message is reprocessed.914* **Placement rules still apply**, cleared or not. A turn-scoped message must follow a `user` turn (or an `assistant` turn ending in a server tool result) and precede an `assistant` turn or end the array, like any mid-conversation system message. One that ends the array always renders. One followed directly by another `user` message is a 400 error, not a cleared message: put all of a tool round's results in one user message and the reminders after it.915* **Assistant turns don't clear it.** A prefilled or [paused](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#pause-turn) assistant turn after the message, or a server-side tool loop, adds no user message, so the message still renders on that continuation. To keep a reminder in view through a client-side tool loop, append it again after each `tool_result` message.916* **Token counting follows what renders.** A cleared message adds nothing to `usage.input_tokens` or to a [token count](https://platform.claude.com/docs/en/build-with-claude/token-counting).917* **Imported history.** In a transcript you construct in one step (few-shot examples, a migrated conversation), a turn-scoped message that already has an assistant turn and a user message after it is cleared from the first request and never renders. That is the right state for a per-turn reminder you are carrying over. Leave `clear_at` unset only on a message the model should see on every request.918919The validation errors are:920921```text wrap922messages.3.clear_at: Extra inputs are not permitted923messages.3.clear_at: clear_at is only permitted on role 'system' messages924messages.3.clear_at: Input should be 'next_user_message' or 'never'925messages.3: a turn-scoped system message supports text blocks only (clear_at: 'next_user_message')926messages.3: output_config is not permitted on a turn-scoped system message (clear_at: 'next_user_message')927messages.3.content.0: cache_control is not permitted on a turn-scoped system message (clear_at: 'next_user_message')928```929930The first is the error returned without the beta header. On Amazon Bedrock and Google Cloud, pass the beta value as described in [Beta headers](https://platform.claude.com/docs/en/api/beta-headers).931932Through the SDKs, set `clear_at` on the `role: "system"` entry in `messages` and send the beta header. The following example appends a turn-scoped reminder after the user turn; on the next request, once a later user message exists, the reminder stays in the array but no longer renders:933934<CodeGroup>935  ```bash cURL936  curl https://api.anthropic.com/v1/messages \937    -H "x-api-key: $ANTHROPIC_API_KEY" \938    -H "anthropic-version: 2023-06-01" \939    -H "anthropic-beta: mid-conversation-system-clear-at-2026-08-21" \940    -H "content-type: application/json" \941    -d '{942      "model": "claude-fable-5-1",943      "max_tokens": 4096,944      "messages": [945        {"role": "user", "content": "Draft a short status update on the database migration for the team channel."},946        {"role": "system", "clear_at": "next_user_message", "content": "The reader is on call: keep this reply under 50 words."}947      ]948    }'949  ```950951  ```bash CLI952  ant beta:messages create --beta mid-conversation-system-clear-at-2026-08-21 \953    --transform 'content.#(type=="text").text' --raw-output <<'YAML'954  model: claude-fable-5-1955  max_tokens: 4096956  messages:957    - role: user958      content: Draft a short status update on the database migration for the team channel.959    # Turn-scoped reminder: renders for this turn, then clears once a later user message exists.960    - role: system961      clear_at: next_user_message962      content: "The reader is on call: keep this reply under 50 words."963  YAML964  ```965966  ```python Python967  client = anthropic.Anthropic()968969  response = client.beta.messages.create(970      model="claude-fable-5-1",971      max_tokens=4096,972      messages=[973          {974              "role": "user",975              "content": "Draft a short status update on the database migration for the team channel.",976          },977          # Turn-scoped reminder: renders for this turn, then clears once a later user message exists.978          {979              "role": "system",980              "clear_at": "next_user_message",981              "content": "The reader is on call: keep this reply under 50 words.",982          },983      ],984      betas=["mid-conversation-system-clear-at-2026-08-21"],985  )986987  for block in response.content:988      if block.type == "text":989          print(block.text)990  ```991992  ```typescript TypeScript993  const client = new Anthropic();994995  const response = await client.beta.messages.create({996    model: "claude-fable-5-1",997    max_tokens: 4096,998    messages: [999      {1000        role: "user",1001        content: "Draft a short status update on the database migration for the team channel."1002      },1003      // Turn-scoped reminder: renders for this turn, then clears once a later user message exists.1004      {1005        role: "system",1006        clear_at: "next_user_message",1007        content: "The reader is on call: keep this reply under 50 words."1008      }1009    ],1010    betas: ["mid-conversation-system-clear-at-2026-08-21"]1011  });10121013  for (const block of response.content) {1014    if (block.type === "text") {1015      console.log(block.text);1016    }1017  }1018  ```10191020  ```csharp C#1021  using Anthropic.Models.Beta;1022  using Anthropic.Models.Beta.Messages;10231024  AnthropicClient client = new();10251026  var response = await client.Beta.Messages.Create(new MessageCreateParams1027  {1028      Model = "claude-fable-5-1",1029      MaxTokens = 4096,1030      Messages =1031      [1032          new() { Role = Role.User, Content = "Draft a short status update on the database migration for the team channel." },1033          // Turn-scoped reminder: renders for this turn, then clears once a later user message exists.1034          new()1035          {1036              Role = Role.System,1037              ClearAt = ClearAt.NextUserMessage,1038              Content = "The reader is on call: keep this reply under 50 words.",1039          },1040      ],1041      Betas = [AnthropicBeta.MidConversationSystemClearAt2026_08_21],1042  });10431044  foreach (var block in response.Content)1045  {1046      if (block.TryPickText(out var textBlock))1047      {1048          Console.WriteLine(textBlock.Text);1049      }1050  }1051  ```10521053  ```go Go1054  client := anthropic.NewClient()10551056  response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{1057  	Model:     "claude-fable-5-1",1058  	MaxTokens: 4096,1059  	Messages: []anthropic.BetaMessageParam{1060  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Draft a short status update on the database migration for the team channel.")),1061  		// Turn-scoped reminder: renders for this turn, then clears once a later user message exists.1062  		{1063  			Role:    anthropic.BetaMessageParamRoleSystem,1064  			ClearAt: anthropic.BetaMessageParamClearAtNextUserMessage,1065  			Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("The reader is on call: keep this reply under 50 words.")},1066  		},1067  	},1068  	Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMidConversationSystemClearAt2026_08_21},1069  })1070  if err != nil {1071  	log.Fatal(err)1072  }10731074  for _, block := range response.Content {1075  	if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {1076  		fmt.Println(textBlock.Text)1077  	}1078  }1079  ```10801081  ```java Java1082  import com.anthropic.models.beta.AnthropicBeta;1083  import com.anthropic.models.beta.messages.BetaMessage;1084  import com.anthropic.models.beta.messages.BetaMessageParam;1085  import com.anthropic.models.beta.messages.MessageCreateParams;10861087  void main() {1088      AnthropicClient client = AnthropicOkHttpClient.fromEnv();10891090      MessageCreateParams params = MessageCreateParams.builder()1091          .model("claude-fable-5-1")1092          .maxTokens(4096L)1093          .addBeta(AnthropicBeta.MID_CONVERSATION_SYSTEM_CLEAR_AT_2026_08_21)1094          .addUserMessage("Draft a short status update on the database migration for the team channel.")1095          // Turn-scoped reminder: renders for this turn, then clears once a later user message exists.1096          .addMessage(BetaMessageParam.builder()1097              .role(BetaMessageParam.Role.SYSTEM)1098              .clearAt(BetaMessageParam.ClearAt.NEXT_USER_MESSAGE)1099              .content("The reader is on call: keep this reply under 50 words.")1100              .build())1101          .build();11021103      BetaMessage response = client.beta().messages().create(params);1104      response.content().stream()1105          .flatMap(block -> block.text().stream())1106          .forEach(textBlock -> IO.println(textBlock.text()));1107  }1108  ```11091110  ```php PHP1111  use Anthropic\Beta\AnthropicBeta;1112  use Anthropic\Beta\Messages\BetaMessageParam;1113  use Anthropic\Client;11141115  $client = new Client();11161117  $response = $client->beta->messages->create(1118      model: 'claude-fable-5-1',1119      maxTokens: 4096,1120      messages: [1121          BetaMessageParam::with(role: 'user', content: 'Draft a short status update on the database migration for the team channel.'),1122          // Turn-scoped reminder: renders for this turn, then clears once a later user message exists.1123          BetaMessageParam::with(1124              role: 'system',1125              clearAt: 'next_user_message',1126              content: 'The reader is on call: keep this reply under 50 words.',1127          ),1128      ],1129      betas: [AnthropicBeta::MID_CONVERSATION_SYSTEM_CLEAR_AT_2026_08_21],1130  );11311132  foreach ($response->content as $block) {1133      if ($block->type === 'text') {1134          echo $block->text, PHP_EOL;1135      }1136  }1137  ```11381139  ```ruby Ruby1140  client = Anthropic::Client.new11411142  response = client.beta.messages.create(1143    model: "claude-fable-5-1",1144    max_tokens: 4096,1145    messages: [1146      {role: "user", content: "Draft a short status update on the database migration for the team channel."},1147      # Turn-scoped reminder: renders for this turn, then clears once a later user message exists.1148      {role: "system", clear_at: :next_user_message, content: "The reader is on call: keep this reply under 50 words."}1149    ],1150    betas: [Anthropic::AnthropicBeta::MID_CONVERSATION_SYSTEM_CLEAR_AT_2026_08_21]1151  )11521153  response.content.each do |block|1154    puts block.text if block.type == :text1155  end1156  ```1157</CodeGroup>11581159## Combining with prompt caching11601161Mid-conversation system messages and [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) are designed to be used together:11621163* **Enable caching explicitly.** Caching only happens when the request includes `cache_control`, either the top-level [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) field or an [explicit breakpoint](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) on a content block. A mid-conversation system message does not create a cache entry on its own, and without caching enabled there are no savings to preserve.1164* **Cache the stable prefix as usual.** Place `cache_control` on the last block that stays the same across requests, whether that is the end of the top-level `system` field, the end of your tool definitions, or a stable point in the message history.1165* **Append the system message after the breakpoint.** Because it comes after the cached prefix, it does not change the prefix hash and the cache still hits.1166* **A mid-conversation system message is itself cacheable.** Once it is in the conversation, it becomes part of the stable history. On the next turn you can move your cache breakpoint past it (or rely on [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) to do so) and the system message is read from cache like any other turn.11671168Avoid editing or removing a mid-conversation system message that has already been sent. Like any other change to earlier messages, that invalidates the cache from that point forward. On Claude Fable 5.1 it also invalidates the [thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation) in every later assistant turn. For guidance that should apply to one turn only, use a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) and leave it in place. If the instruction needs to evolve, append a new system message rather than rewriting the old one. Consecutive system messages are accepted and treated as a single system section, which follows the same placement rule as a whole.11691170## Limitations11711172* **Not for the first message.** A `system` message that carries content cannot be the first entry in `messages`. Use the top-level `system` field for instructions that apply from the very start.1173* **Placement is constrained.** A `system` message that carries content (`text`, `tool_addition`, or `tool_removal` blocks) must immediately follow a `user` turn (including a `user` turn that carries `tool_result` blocks) or an `assistant` turn ending in a server tool result, and must precede an `assistant` turn or end the array. It cannot sit between a `tool_use` block and its `tool_result`. Placing it elsewhere returns a 400 error. One exception: `tool_addition` and `tool_removal` blocks are not accepted immediately after a [paused](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#pause-turn) `assistant` turn (one ending in a server tool result), though `text` blocks are; resume the paused turn first, then send the tool change in the next `system` message. A message with empty `content` that only sets [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) renders nothing at its position and is accepted anywhere in `messages`, including first or between an `assistant` turn and a `user` turn. Consecutive `system` messages are judged together, so adding a text-carrying message next to an effort-only one makes the whole group follow the content rule.1174* **Turn-scoped messages are text-only and re-sent verbatim.** A `clear_at: "next_user_message"` message carries no `tool_addition`, `tool_removal`, `output_config`, or `cache_control`, and once cleared it must stay in `messages` byte-for-byte on later requests. See [Turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages).1175* **Not a place for untrusted content.** Claude treats system content as operator instructions and follows it. Do not place text from outside the conversation, such as raw tool output, retrieved documents, or web content, directly in a system message; doing so gives that text operator-level authority. Keep that data in `tool_result` blocks and continue to follow [Mitigate jailbreaks and prompt injections](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks).11761177## Related11781179<CardGroup cols={2}>1180  <Card title="Prompt caching" icon="bolt" href="https://platform.claude.com/docs/en/build-with-claude/prompt-caching">1181    How caching works, where to place breakpoints, and how to read cache usage fields.1182  </Card>11831184  <Card title="Cache diagnostics" icon="magnifying-glass" href="https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics">1185    Find out exactly where two requests diverged when a cache hit you expected does not happen.1186  </Card>11871188  <Card title="Using the Messages API" icon="message" href="https://platform.claude.com/docs/en/build-with-claude/working-with-messages">1189    Message structure, multi-turn conversations, and the `system` field.1190  </Card>11911192  <Card title="Prompting best practices" icon="text" href="https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices">1193    Writing effective prompts and system instructions.1194  </Card>11951196  <Card title="Tool use with Claude" icon="wrench" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview">1197    How `tool_use` and `tool_result` blocks are structured in the `messages` array.1198  </Card>1199</CardGroup>1200
Files main
Menu

Theme