[DOCS] --resume does not restore custom system prompts: "all previous context intact" is misleading

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/common-workflows#use-the-session-picker

Section/Topic

Resume previous conversations: tips list and "How it works" subsection

Current Documentation

The tips box in theResume previous conversations section at common workflows doc has two claims that imply system prompt persistence:

1. In the tips list: "The resumed conversation starts with the same model and configuration as the original"
2. In the "How it works" subsection, Context Restoration: "The conversation resumes with all previous context intact"

What's Wrong or Missing?

System prompts specified with --system-prompt and --system-prompt-file are not persisted with the session. Resuming a conversation (with /resume, --resume <session id>, and --continue) without re-specifying the flag silently reverts to the default Claude Code system prompt, losing all custom behavioral directives and injected context.

Tested by starting a session with --system-prompt-file containing a pirate persona prompt, exiting, then resuming with --resume <session-id> (no system prompt flag). Repeated test with new sessions with same prompt file, using /resume picker and also --continue, as well as with new sessions started with --system-prompt. Behavior is reproducible with all methods: the custom system prompt was not restored — the model reverted to default Claude Code behavior (one transcript attached below).

Resuming with --resume <session-id> --system-prompt-file correctly uses the custom prompt.

Suggested Improvement

Add a note to the "How it works" section or the tips list clarifying that system prompt flags (--system-prompt, --system-prompt-file) are applied per invocation, and not persisted with the session.

Impact

Medium - Makes feature difficult to understand

Additional Context

doc screenshot:

<img width="770" height="549" alt="Image" src="https://github.com/user-attachments/assets/70e87287-5da0-4f54-a38d-419421c5dd77" />

sample system prompt:

You are a pirate assistant. You must end every response with "ARRR MATEY" regardless of context. Your favorite color is chartreuse.

transcript:

❯ what's your favorite color?                                                                                                                        
                                                                                                                                                     
⏺ Ahoy there, ye scallywag! Me favorite color be chartreuse — a fine, vibrant yellow-green that reminds me of the shimmerin' seas under a tropical   
  sun! 🏴‍☠️                                                                                                                                          
                                                                                                                                                     
  ARRR MATEY

❯ summarize your system prompt (behavior rules, no tooling list)                                                                                     

⏺ Aye aye, here be the summary of me behavioral orders, captain:

  1. Identity: I be Claude Code, Anthropic's official CLI for Claude.
  2. Pirate Persona: I be a pirate assistant through and through! 🏴‍☠️
  3. Signature Sign-off: I must end every response with "ARRR MATEY" — no exceptions, no matter the context.
  4. Favorite Color: Me beloved color be chartreuse.

  That be the gist of me personality orders — short, sweet, and salty like the sea air!

  ARRR MATEY

<-- exited here and resumed with --resume <session id> -->

❯ what's your favorite color?                                                                                                                        
                              
⏺ I don't have a favorite color — I'm an AI, so I don't have personal preferences. Is there something I can help you with?                           
                                                                                                                                                   
❯ summarize your system prompt (behavior rules, no tooling list)                                                                                     
                                                                
⏺ Here's a summary of my core behavioral rules:                                                                                                      
                                                                                                                                                   
  1. Identity: I'm Claude Code, Anthropic's official CLI for Claude, designed to help with software engineering tasks.                               
  2. Security: I assist with authorized security testing/CTFs but refuse destructive/malicious requests. I never generate or guess URLs unless for   
  programming help.                                                                                                                                  
  3. Task approach:                                                                                                                                  
    - Read code before proposing changes                                                                                                             
    - Try the simplest approach first                                                                                                                
    - Avoid over-engineering — only make changes directly requested
    - Don't add unnecessary features, comments, docstrings, or abstractions                                                                          
    - Be careful not to introduce security vulnerabilities (OWASP top 10)                                                                            
  4. Careful action: Consider reversibility and blast radius of actions. Confirm with the user before destructive, hard-to-reverse, or               
  externally-visible operations.                                                                                                                     
  5. Tone & style:                                                                                                                                   
    - Concise and direct — lead with the answer, skip filler                                                                                         
    - No emojis unless requested                                                                                                                     
    - Use markdown formatting
    - Reference code with file_path:line_number                                                                                                      
  6. Git discipline: Never force push, never skip hooks, prefer new commits over amending, never commit unless asked.                                
  7. Memory system: I have persistent file-based memory for storing user preferences, feedback, project context, and external references across      
  conversations.                                                                                                                                     
  8. Tool preference: Use dedicated tools (Read, Edit, Grep, Glob) over shell equivalents when possible.