Claude Code Conversation History Invalidated: Cache Breaking on Subsequent Turns

// Inside HTTP header builder, after iterating request headers
if (has_anthropic_version_header) {
    // Check URL contains "/v1/messages"
    // Built on stack as u64 LE immediates:
    local_c0 = 0x7373656d2f31762f;  // "/v1/mess"
    local_b8 = 0x73656761;          // "ages"
    if (memmem(url_ptr, url_len, &local_c0, 12) != NULL) {

        // Search body for sentinel "cch=00000"
        // Also built on stack:
        local_c0 = 0x303030303d686363;  // "cch=0000" LE
        local_b8 = 0x30;               // "0"
        offset = memmem(body_ptr, body_len, &local_c0, 9);

        if (offset != NULL) {
            // Hash the entire body
            hash_state = init(seeds...);
            hash_update(hash_state, body_ptr, body_len);
            hash_value = hash_finalize(hash_state);

            // Convert 5 nibbles to hex (SIMD)
            hex_chars = simd_nibble_to_hex(hash_value);

            // Write in-place: body[offset+4..offset+9] = hex chars
            *(uint32_t*)(body_ptr + 4 + offset) = hex_chars[0..3];
            *(char*)(body_ptr + 8 + offset) = hex_char_5th;
        }
    }
}

How to Fix It

Solution 1: Use the npm Package Instead of the Standalone Binary (Most Effective)

According to the reverse engineering analysis, only the standalone binary (228MB ELF) performs the sentinel replacement. The npm package does not.

Confirmed experimentally:

Runtime	Replacement active?
Official standalone binary (228MB ELF)	YES
bun build --compile --bytecode cli.js (homebrew standalone)	NO
bun cli.js (standard Bun runtime)	NO
npx @anthropic-ai/claude-code (npm package)	NO

To switch to the npm package, run:

npx @anthropic-ai/claude-code

This runs the same JavaScript code but without the native sentinel replacement. The user who reported the bug confirmed this works: "Step to temporarily fix: npx @anthropic-ai/claude-code@2.1.34 // you need to fix it on older version to benefit from it."

Important caveat: The user noted that you may need to use an older version (e.g., 2.1.34) to fully benefit from the fix, as the sentinel was introduced in v2.1.36. However, using the npm package at any version avoids the native replacement entirely.

Solution 2: Downgrade to a Version Before the Sentinel Was Introduced

The sentinel cch=00000 was introduced in v2.1.36. Versions 2.1.0 through 2.1.34 have the billing header but no cch field. Versions 1.0.0 through 2.0.0 have no billing header at all.

To downgrade using the standalone binary, you would need to install an older version. The last working version reported by the user is 2.1.67, though the sentinel was present from 2.1.36 onward. The user noted that the issue may have been less noticeable in earlier versions due to other factors.

For Homebrew installations, you can install a specific version:

brew install --cask claude-code@2.1.34

Note that Homebrew offers two casks: claude-code tracks the stable release channel (typically about a week behind and skips releases with major regressions), and claude-code@latest tracks the latest channel. The stable channel may have the fix before the latest channel if Anthropic addresses this.

Solution 3: Avoid Having cch=00000 in Conversation Content

Since the sentinel replacement only breaks the cache when the sentinel appears in messages[] (not just in system[0]), you can prevent the issue by ensuring that cch=00000 never appears in your conversation content.

Specifically:

• Do not include cch=00000 in CLAUDE.md files
• Do not ask Claude Code to read or analyze files that contain the sentinel (like the JS bundle or binary)
• Do not type the sentinel literally in your prompts

If you have already triggered the issue, you can clear the conversation history and start fresh:

# Inside Claude Code session
/clear

This resets the conversation and removes any cached context that contains the sentinel.

Solution 4: Use claude -c to Continue the Most Recent Conversation

If you are resuming a session and the cache has been invalidated, you can try using the -c flag to continue the most recent conversation in the current directory:

claude -c

This may help if the cache invalidation is due to a session mismatch rather than the sentinel issue. According to the official documentation, claude -c continues the most recent conversation in the current directory, while claude -r resumes a previous conversation.

Solution 5: Use the Verification Script to Diagnose the Issue

The user who reported the bug created a verification script to detect the sentinel replacement:

# Download and run the verification script
curl -fsSL https://gitlab.com/treetank/cc-diag/-/raw/c126a7890f2ee12f76d91bfb1cc92612ae95284e/test_cache.py -o test_cache.py
python3 test_cache.py

This script checks whether the sentinel replacement is active in your Claude Code installation. The user also created a diagnostic tool:

# Clone the diagnostic tool
git clone https://gitlab.com/treetank/cc-diag
cd cc-diag
# Follow the instructions in the repository

If Nothing Works

Escalation Paths

1. GitHub Issues: File a new bug report at https://github.com/anthropics/claude-code/issues. Make sure to:

   • Search existing issues first (the user confirmed they searched before filing)
   • Use the bug report template
   • Include your Claude Code version (claude --version)
   • Include token usage logs if possible
   • Specify your platform (OS, terminal, API provider)

2. Anthropic Documentation: Check the troubleshooting section at https://docs.anthropic.com/en/docs/claude-code/troubleshooting for any updates on this issue.

3. Community Support: Join the Anthropic Discord (linked from the documentation) for tips and support from other users.

4. Workaround: Use the Desktop App or Web Interface: If the CLI continues to have cache issues, you can use Claude Code on other surfaces:

   • Desktop app: Download from the Anthropic website (macOS Intel and Apple Silicon, Windows x64 and ARM64)
   • Web: Start coding at claude.ai/code
   • VS Code extension: Search for "Claude Code" in the Extensions view (Cmd+Shift+X on Mac, Ctrl+Shift+X on Windows/Linux)
   • JetBrains plugin: Install from the JetBrains Marketplace

   These surfaces may use different HTTP client code that doesn't have the sentinel replacement.

5. Workaround: Use a Third-Party Provider: If you have access through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, try switching providers. The sentinel replacement may be specific to the Anthropic API path.

Monitoring Token Usage

To monitor whether the cache is being invalidated, you can use the diagnostic tool created by the community:

# Run the diagnostic tool
git clone https://gitlab.com/treetank/cc-diag
cd cc-diag
python3 cc_diag.py

Look for patterns in the output:

• Cache reads dropping to 0 after a few turns
• Cache writes spiking (e.g., from 1000 to 200000)
• The model switching to a cheaper model (haiku) for resume attempts
• The cache_cr (cache creation) column showing high values

How to Prevent It

Use the npm Package

The most reliable prevention is to use the npm package instead of the standalone binary:

npx @anthropic-ai/claude-code

This avoids the native sentinel replacement entirely. The npm package uses standard Bun runtime, which does not have the injected replacement logic.

Keep Your CLAUDE.md Clean

Do not include cch=00000 or any discussion of the billing mechanism in your CLAUDE.md files. Claude Code reads CLAUDE.md at the start of every session, and if it contains the sentinel, the cache will break on the first turn.

Avoid Reading Files Containing the Sentinel

If you need to analyze the Claude Code binary or JS bundle, do so in a separate session or use a different tool. The Read and Grep tools can introduce the sentinel into the conversation history, triggering the cache invalidation.

Use Session Commands to Manage Context

The official documentation lists several session commands that can help manage conversation history:

• /clear - Clear conversation history (use this if you suspect the sentinel has been introduced)
• /help - Show available commands
• /exit or Ctrl+D twice - Exit Claude Code

Stay on the Stable Release Channel

If you use Homebrew, install the stable release channel instead of the latest:

brew install --cask claude-code

The stable channel (claude-code) is typically about a week behind and skips releases with major regressions. The latest channel (claude-code@latest) receives new versions as soon as they ship. If Anthropic fixes this issue, the stable channel will get the fix after it has been validated.

Update Regularly

Keep your Claude Code installation up to date. For the standalone binary, native installations automatically update in the background. For Homebrew, run:

brew upgrade claude-code

For WinGet:

winget upgrade Anthropic.ClaudeCode

For npm:

npx @anthropic-ai/claude-code@latest

Use the Verification Script Before Long Sessions

Before starting a long coding session, run the verification script to check if the sentinel replacement is active:

curl -fsSL https://gitlab.com/treetank/cc-diag/-/raw/c126a7890f2ee12f76d91bfb1cc92612ae95284e/test_cache.py -o test_cache.py
python3 test_cache.py

If the script detects the replacement, switch to the npm package before proceeding.

Monitor Token Usage Proactively

Keep an eye on your token usage during sessions. The user who reported the bug noticed the issue because of "huge token usage." If you see cache reads dropping to 0 and cache writes spiking, clear the conversation and start fresh, or switch to the npm package.

For Enterprise Users

If you are using Claude Code through an enterprise cloud provider (Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry), the sentinel replacement may not apply, as the HTTP client code may be different. Check with your provider for specific guidance.

For Self-Hosted Deployments

If your organization runs a self-hosted Claude apps gateway, the sentinel replacement is in the client binary, not the server. Using the npm package or a different surface (web, desktop app) should avoid the issue regardless of the gateway configuration.