--- title: Why does Claude Code ignore an updated system prompt on resume? url: https://deepthinkingai.org/claude-agent-sdk-system-prompt-snapshot/ published: 2026-09-21 author: Shekhar Singh topic: AI Engineering tags: claude-agent-sdk, claude-code, system-prompt, prompt-caching, agents site: DeepThinking AI --- # Why does Claude Code ignore an updated system prompt on resume? **Summary:** Claude Code and the Agent SDK record a session's system prompt on its first request and keep reusing that copy after resume, so a changed append or custom prompt has no effect until the session compacts or you start a new one. The snapshot field controls this, and it defaults to off in bare mode. ## 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](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts). 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** ```mermaid sequenceDiagram participant Yourapp as Your app participant ClaudeCodesession as Claude Code session Yourapp->>ClaudeCodesession: First request, append v1 ClaudeCodesession-->>Yourapp: Reply Yourapp->>ClaudeCodesession: Resume, append changed to v2 ClaudeCodesession-->>Yourapp: Reply built from append v1 Yourapp->>Yourapp: Session compacts, or a new one starts Yourapp->>ClaudeCodesession: Next request ``` - First request, append v1: Recorded as the system prompt - Resume, append changed to v2: snapshot true by default - Reply built from append v1: The recorded copy was sent rather than v2 - Next request: append v2 reaches Claude for the first time Recording pins the system prompt to what the session's first request sent. An edited append does not reach Claude until the session compacts or you start a new one, even though the SDK call looks identical. 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](/claude-compaction-modes/) 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](/prompt-caching-economics/) 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** 1. Default, launched without --bare snapshot true, prompt recorded and reused --- bare mode flips the default --- (--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 Which default applies depends on how the session was launched and which CLI build it bundles. A session on Bedrock, Vertex or Foundry with an old CLI ignores the flag in either direction, so checking the version matters more than checking the code. 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](/claude-compaction-modes/), 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. ## 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. 1. **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. 2. **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. 3. **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. 4. **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. 5. **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. 6. **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. ## Sources - [Modifying system prompts](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts). Anthropic, 2026-09-21 - [Python Agent SDK reference, SystemPromptPreset](https://code.claude.com/docs/en/agent-sdk/python). Anthropic, 2026-09-21 - [feat: add snapshot option for system prompts (#1268)](https://github.com/anthropics/claude-agent-sdk-python/pull/1268). Anthropic, 2026-09-15 - [claude-agent-sdk 0.2.153 release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.153). Anthropic, 2026-09-15 --- Canonical HTML: https://deepthinkingai.org/claude-agent-sdk-system-prompt-snapshot/