Why does Claude Code ignore an updated system prompt on resume?
AI Architect
Key takeaways
- Claude Code records a session's system prompt on its first request and reuses it after resume.
- An updated append or custom prompt reaches Claude only after compaction or a new session, unless you disable recording.
- Starting Claude Code in bare mode or with CLAUDE_CODE_SIMPLE=1 flips the snapshot default to off.
- Disabling recording so edits take effect immediately also breaks prompt cache reuse and, on some models, kept thinking.
- Platforms that skip Claude Code's feature-flag fetch ignored the snapshot field entirely before CLI v2.1.268.
Anthropic’s Agent SDK shipped a snapshot field on 15 September 2026 that
sounds like a minor caching knob. It is actually the answer to a bug report
that shows up constantly: an agent’s append text is edited, the session is
resumed, and Claude keeps acting on the old instructions with no error and no
warning that anything was ignored.
What does Claude Code record when a session starts?
Claude Code records the system prompt on a session’s first request and reuses
that record on every later request, including after resume or continue.
This has been the default behavior since CLI v2.1.265, bundled by the
TypeScript Agent SDK from v0.3.265 and the Python SDK from v0.2.153, according
to Anthropic’s documentation.
Before that CLI version, and still today on setups that skip Claude Code’s
feature-flag fetch, the prompt was rebuilt from scratch on every request
instead. Recording is the newer behavior rather than the original one. That is
why so much existing code assumes editing append and resuming just works: it
did, on every SDK release before this one, and nothing about the function
signature changed to signal that the assumption stopped holding.
The field lives on the preset and custom forms of systemPrompt in
TypeScript and system_prompt in Python, as an optional snapshot: bool.
Leave it unset and you get the new default. Setting it explicitly is the only
way to know, by reading your own code, which behavior a given session has.
Why doesn’t an edited append or system prompt reach Claude after resume?
Because the SDK never re-reads it. The docs state the mechanism plainly:
“Claude Code records the system prompt on a session’s first request and
reuses that record until the session is compacted.” A different append or
custom prompt you pass on resume is accepted by the call and then ignored,
silently, with the old text still driving the model.
What reaches Claude when you edit append and resume
Show as text
| # | From | To | Message |
|---|---|---|---|
| 1 | Your app | Claude Code session | First request, append v1. Recorded as the system prompt |
| 2 | Claude Code session | Your app | Reply |
| 3 | Your app | Claude Code session | Resume, append changed to v2. snapshot true by default |
| 4 | Claude Code session | Your app | Reply built from append v1. The recorded copy was sent rather than v2 |
| 5 | Your app | Your app | Session compacts, or a new one starts |
| 6 | Your app | Claude Code session | Next request. append v2 reaches Claude for the first time |
Two things reset the record: the session being compacted, or starting a new session instead of resuming. This is Claude Code’s own session compaction, and the documentation does not say whether it shares a mechanism with the on-demand and threshold compaction betas in the Messages API. Treat them as separate until Anthropic states otherwise.
What do you give up by turning recording off?
Setting snapshot: false on the preset or custom form of systemPrompt
makes every request rebuild the prompt from your current append or custom
text, so edits take effect on the next turn instead of waiting for compaction.
That fixes the staleness problem, at a real cost.
A resumed session with recording off cannot reuse the prompt cache entry from its first request, because the prefix it would match against no longer matches byte for byte once the prompt changes. On models with preserved thinking, the documentation adds that “Claude also loses its thinking from earlier turns.” Anthropic’s own guidance is to keep recording on in production and turn it off only while iterating on wording during development, which matches what the mechanism actually costs.
Why does bare mode flip the snapshot default?
Because bare mode is meant for short-lived, scripted invocations rather than long resumed sessions, and Anthropic picked the default that fits that case instead of the general one.
Which snapshot default applies to your session
Show as text
| # | Layer | Note |
|---|---|---|
| 1 | Default, launched without --bare | snapshot true, prompt recorded and reused |
| · | bare mode flips the default (breakpoint) | --bare or CLAUDE_CODE_SIMPLE=1 sets it false |
| 2 | Old CLI on Bedrock, Vertex, Foundry | snapshot ignored, prompt rebuilt every time |
| 3 | Claude Code v2.1.268 or later | snapshot works as documented everywhere |
Outside cloud sessions, starting Claude Code with --bare (passed through
extraArgs) or with CLAUDE_CODE_SIMPLE=1 set leaves recording off unless
you set snapshot: true explicitly. A team that runs the same agent code in
both an interactive CLI session and a bare scripted one, which is a common
pattern for a support bot that also has a debug mode, gets two different
caching and staleness behaviors from identical systemPrompt configuration,
purely because of how the process was launched.
Nothing in the SDK’s return values names which default applied to a given
run. A log line that prints your ClaudeAgentOptions verbatim will show
snapshot as unset in both cases, which is accurate and unhelpful at the
same time: the field really was left unset, and the two launch paths still
disagree about what that means.
Does snapshot actually work on Bedrock, Vertex or Microsoft Foundry?
Not always, and the failure mode is worse than the field having no effect.
Recording depends on Claude Code fetching feature flags, and before CLI
v2.1.268, sessions on platforms that skip that fetch, which the documentation
names as Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft
Foundry, rebuilt the prompt on every request no matter what snapshot was
set to. A team that read the changelog, set snapshot: true deliberately,
and confirmed it in a direct API test could still see stale-prompt symptoms
disappear for a reason that had nothing to do with the flag: a version
boundary being crossed. Checking the bundled CLI version is the only way to
know which behavior a given deployment actually has.
What should you actually do about Claude Code’s system prompt snapshot?
Leave recording on almost everywhere. The staleness it causes is real but
narrow: it only bites when you change append or a custom prompt and expect
a resumed session to notice, which is exactly the situation local iteration
creates and production traffic rarely does. For a live agent, the caching and
preserved-thinking gains outweigh a scenario that should not come up outside
a deploy.
Treat snapshot: false as a development-only setting, and treat bare mode as
a separate configuration surface that needs its own explicit value rather
than an inherited default. If your agent runs the same code path in both
bare and non-bare mode, set snapshot explicitly in both rather than relying
on either default, since the two defaults were chosen for different use cases
and will keep diverging as Claude Code adds more of them.
What is still unclear about session compaction resetting the prompt?
Whether Claude Code’s session compaction, the event that resets the recorded prompt, is implemented with the same Messages API compaction primitives covered elsewhere on this site, or is a separate CLI-side mechanism that only shares a name. The modifying-system-prompts page names the trigger without describing its mechanism, and Anthropic’s compaction documentation does not mention system prompt recording at all.
That gap matters because it decides whether the guidance in the compaction betas article, about signed blocks, billing on a failed summary, and cache breakpoints, applies to what resets your system prompt recording. Until Anthropic documents the relationship explicitly, the safer assumption is that they do not share implementation, and that testing one tells you nothing about the other.
Do this
Decide when to let Claude Code record your system prompt
The default is right for most agents, so the steps below are mainly about knowing when it silently stops matching your intent.
Keep recording on for any production agent
The default already does this. Every resumed session reuses the prompt cache entry from its first request and, on models with preserved thinking, keeps earlier turns' reasoning valid.
Set snapshot to false only while you iterate on wording
Recording off means each edited append or custom prompt reaches Claude on the next turn you send. Turn it back on once you settle on the wording, since every request now rebuilds the prompt and cannot reuse the previous cache entry.
Check whether you are launching in bare mode
--bare and CLAUDE_CODE_SIMPLE=1 flip the default to off outside cloud sessions. If you rely on recording, set snapshot to true explicitly rather than trusting the ambient default to match your intent.
Confirm your CLI version before trusting the flag on Bedrock, Vertex or Foundry
Sessions on those platforms ignored snapshot entirely before Claude Code v2.1.268, because they skip the feature-flag fetch recording relies on. Pin to v2.1.268 or later, or verify locally that an append change actually stops reaching Claude with recording on.
Force a refresh deliberately when you need the new prompt without disabling recording
Compaction or a new session both clear the recorded copy. If you cannot wait for either, restate the changed instruction in a user message or a hook's additionalContext instead of relying on systemPrompt to update itself.
Pin your SDK version in CI
The field does not exist before claude-agent-sdk v0.2.153 for Python or the matching TypeScript release. A downgrade silently drops snapshot and falls back to whichever default your CLI build carries.
Frequently asked questions
- What does the snapshot field do in the Claude Agent SDK?
- It controls whether Claude Code reuses the system prompt recorded on a session's first request, which is the default, or rebuilds the prompt from your current append or custom text on every request.
- Why doesn't my updated append text reach Claude after I resume a session?
- Because recording defaults to on. Claude Code keeps the prompt from the session's first request until that session compacts or you start a new one, so a changed append sits unused until then.
- Does snapshot behave differently in bare mode?
- Yes. Outside cloud sessions, starting Claude Code with --bare or CLAUDE_CODE_SIMPLE=1 flips the default to off, so recording is disabled unless you set snapshot to true explicitly.
- What do I lose by setting snapshot to false?
- A resumed session with recording off cannot reuse its prompt cache entry from earlier turns, and on models with preserved thinking, earlier turns' thinking is dropped. Keep recording on in production.
- Does the snapshot field work on Bedrock, Vertex or Microsoft Foundry?
- Only once the CLI is new enough to fetch feature flags. Before Claude Code v2.1.268, sessions on platforms that skip that fetch rebuilt the prompt on every request regardless of what snapshot was set to.