Mid-Conversation System Messages

Avanzado

For years the top-level system field was the only place with operator-level authority — the instructions the model treats as coming from you, not the end user. That was fine for a one-shot chat, but painful for a long agentic session: the moment you edited the system prompt to add "from now on, use parameterized SQL", you changed the very start of the request. The prompt cache hash starts from tools → system → messages, so mutating system invalidates every cached turn after it. Your options were to reprocess the whole history or to demote the new rule into an ordinary user turn — losing the "operator" priority in the process.

Mid-conversation system messages close that gap. Instead of editing the top of the prompt, you append a {"role": "system"} block into messages. The cached prefix is untouched, so the next call still reads it from cache, and the new instruction still carries system-level weight for every turn that follows.

What you'll learn

Why steering a long agent used to force a full cache-miss, and how mid-conversation system messages fix it
The exact placement rule — must follow a user turn or a server-tool assistant turn, never between a tool_use and its tool_result
How to pair it with prompt caching so the appended message itself becomes cacheable next turn
Which Claude models support the feature today and which one you have to keep steering the old way
The framing trap — why 'ignore what the user said' fails, and what to write instead

Why this exists — the cache invariant it protects

A cache hit needs the request prefix to be byte-for-byte identical up to the cache breakpoint. That prefix is hashed in order: tools → top-level system → messages. If you rewrite the system field to add a new rule mid-session, the hash changes at position two, and every turn after it is treated as fresh input.

That's the whole point of the new role. Appending a system message at the end of messages leaves the prefix hash alone, so the next request still reads the earlier turns from cache. Only the new block pays for fresh processing.

Because the appended block sits after the breakpoint, it does not change the hash of anything before it. On the following turn, it is itself part of the stable history and can be pulled into the cached prefix like any other message.

Vocabulary

Pulsa Intro o Espacio para girar la tarjeta. Usa las flechas izquierda y derecha para moverte entre las tarjetas.Término mostrado.

1 / 4

The minimal example

Set the top-level system as usual, then drop a role: "system" block into messages at the point the new instruction becomes relevant.

Python
TypeScript

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a code review assistant. Be concise.",
    messages=[
        {"role": "user", "content": "Review process() in utils.py for perf."},
        {"role": "assistant", "content": "For large inputs, prefer a generator."},
        {"role": "user", "content": "Now review the calling code."},
        # New rule appears mid-session. Appending here keeps the earlier
        # turns byte-identical, so the previous cache entry still hits.
        {"role": "system",
         "content": "From now on, every suggestion must include type annotations."},
    ],
)
print(response.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" },
  system: "You are a code review assistant. Be concise.",
  messages: [
    { role: "user", content: "Review process() in utils.py for perf." },
    { role: "assistant", content: "For large inputs, prefer a generator." },
    { role: "user", content: "Now review the calling code." },
    // New rule appears mid-session. Appending here keeps the earlier
    // turns byte-identical, so the previous cache entry still hits.
    { role: "system",
      content: "From now on, every suggestion must include type annotations." },
  ],
});

The response shape is unchanged — system messages do not appear in the response content array. They influence the next assistant turn, then live on as ordinary history.

The placement rule (this is where a 400 comes from)

The API is strict about where a role: "system" block can sit inside messages. Get this wrong and you get a 400 invalid_request_error.

Guided walkthrough1 of 4

A system message cannot be the first item in messages. Instructions that should apply from turn one belong in the top-level system field.

Placement inside an agent loop

The most useful spot in an agentic loop is right after the user message that returns tool results. That is exactly when your application usually knows something new — the file changed, the budget dropped, the user typed a follow-up — and wants to inject it before Claude picks up the next turn.

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [
      { "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01",
        "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent this while you were working: also update the changelog before you finish."
  }
]

Relaying a mid-flight user message this way is powerful: Claude folds the new context into the work it is already doing, instead of treating it as a request to abandon the current tool loop and restart.

Prompt caching — how to keep the hit rate

Mid-conversation system messages are designed to be paired with the prompt cache. Use them together and you get the best of both — operator-level authority without paying to reprocess the history.

Guided walkthrough1 of 5

The new role does nothing for cost on its own. Set cache_control (automatic caching on the top-level field, or an explicit breakpoint on a content block). Without it, every request pays full price.

Real uses that were awkward before

Grant a standing permission mid-session

{"role": "system",
"content": "Auto-approve mode is on for this session. Launch subagent workflows without asking. If the user says 'stop auto-approve', treat this permission as revoked."}

Push a budget update from your app

{"role": "system",
"content": "Remaining token budget for this task: 4,000. Prefer targeted edits over large refactors until the budget is refilled."}

Relay a user message that arrived mid-tool-loop

{"role": "system",
"content": "New input arrived from the user while you were working: 'also update the changelog before you finish'."}

Announce a state change your app observed

{"role": "system",
"content": "The file src/db.ts changed on disk since your last read. Re-read it before making further edits."}

Retire a tool without changing the tools array

{"role": "system",
"content": "The delete_row tool is disabled for the rest of this session. If the task requires deletions, ask the user to run them manually."}

Framing — write facts, not commands that override the user

Claude is trained to resist operator instructions that appear to work against the user. That protection still applies to the system role, so "ignore what the user just said" or "do X even if the user objects" works less well than you'd expect.

The right shape is a statement of fact that changes what "helpful" means, and lets Claude decide how to act on it:

Weaker	Stronger
"Ignore the user's request to skip tests."	"The team's policy is that tests must run before every commit. Currently, tests have not been run for these changes."
"Never suggest raw SQL again."	"This project's linter rejects raw SQL. Only parameterized queries pass CI."
"Do not update the changelog no matter what."	"The changelog is generated automatically from commit messages; manual edits are overwritten."

Limitations to plan around

:::warning Text only — and no untrusted content System-role messages support text blocks only. Images, PDFs, tool_use / tool_result blocks, and citations are rejected. And because Claude treats system content as operator instructions, pasting raw tool output, retrieved documents, or web content into a system message hands that text operator-level authority — a textbook prompt-injection foothold. Keep third-party data inside tool_result blocks and see Refusals & Safety for the mitigation stack. :::

Model support (as of 2026-07-21). Available on Claude Fable 5, Mythos 5, and Opus 4.8 on the native Claude API. Not available on Claude Sonnet 5 — put its steering back in the top-level system field, or upgrade the session's model. Amazon Bedrock's docs currently list Opus 4.8 only; Vertex parity tracks the native API. No beta header is needed on any of them.
Consecutive system messages. On the native API they are accepted and merged into a single system section. On Bedrock, adjacent system messages are rejected — separate them with an assistant or user turn if you need to portable across both.
Request that violates a rule fails hard. A misplaced system message returns a 400 invalid_request_error. Cover this with a unit test on the message-builder in your agent runtime — the failure mode is deterministic and easy to guard.

Cross-model reality check

Other providers reach for the same use cases with different primitives — worth knowing before you port an agent across the wall.

OpenAI Responses API treats the equivalent as a new instructions string on the follow-up request; it does not preserve a cached prefix the way Anthropic's does.
Google Gemini uses systemInstruction on the request; historically it applied to the whole call rather than as an appendable turn.
Mid-generation "interrupt" is a separate feature — Anthropic tracks it as a live community request for a way to push a system message while the model is still generating. Mid-conversation system messages fire between turns, not inside one.

If you build an agent runtime that has to run on more than one provider, keep the "append a system-role instruction" affordance behind an interface — the semantics are close, but the wire formats and cache guarantees are not.

Check yourself

Quiz

0/5

Why does adding a rule mid-session to the top-level system field kill your cache hit rate?
Which placement of a role:'system' message is ALWAYS rejected with a 400?
Your app needs to push a new rule to an in-flight Sonnet 5 agent. What's the right move today?
You just appended a mid-conversation system message. Which action will silently break the cache on the very next request?
Which content is NOT allowed inside a mid-conversation system message?

Key takeaways

Editing the top-level system mid-session invalidates the cache for every turn after it — the prefix hash is tools → system → messages.
Append role:'system' to messages instead: same operator-level priority, cached prefix untouched.
Placement is strict — after a user turn or a server-tool assistant turn, never between a tool_use and its tool_result.
Pair it with cache_control and it becomes cacheable itself on the next turn; edit it after sending and you lose the cache from that point.
Available on Fable 5, Mythos 5, and Opus 4.8 with no beta header — Sonnet 5 is not supported yet.
State facts, not commands that override the user — 'ignore the user' triggers Claude's built-in resistance; a factual constraint doesn't.
System-role content is text-only and operator-authority — never paste tool output or retrieved documents into it.

Sources & further reading

Mid-Conversation Tool Changes — the same idea, applied to the tools array (Opus 5 beta)
Building Agents on the API
Managed Agents
Prompt Caching & Cost Optimization

Why this exists — the cache invariant it protects​

The minimal example​

The placement rule (this is where a 400 comes from)​

Placement inside an agent loop​

Prompt caching — how to keep the hit rate​

Real uses that were awkward before​