claude-code-cache-fix 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Chris Nighswonger, Victor Sun (@VictorSun92), @jmarianski
+
+If you contributed to this work and are not listed above, please open an issue
+or pull request — we want to credit everyone properly.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# claude-code-cache-fix
+
+Fixes a prompt cache regression in [Claude Code](https://github.com/anthropics/claude-code) that causes **up to 20x cost increase** on resumed sessions. Confirmed broken through v2.1.92.
+
+## The problem
+
+When you use `--resume` or `/resume` in Claude Code, the prompt cache breaks silently. Instead of reading cached tokens (cheap), the API rebuilds them from scratch on every turn (expensive). A session that should cost ~$0.50/hour can burn through $5–10/hour with no visible indication anything is wrong.
+
+Three bugs cause this:
+
+1. **Partial block scatter** — Attachment blocks (skills listing, MCP servers, deferred tools, hooks) are supposed to live in `messages[0]`. On resume, some or all of them drift to later messages, changing the cache prefix.
+
+2. **Fingerprint instability** — The `cc_version` fingerprint (e.g. `2.1.92.a3f`) is computed from `messages[0]` content including meta/attachment blocks. When those blocks shift, the fingerprint changes, the system prompt changes, and cache busts.
+
+3. **Non-deterministic tool ordering** — Tool definitions can arrive in different orders between turns, changing request bytes and invalidating the cache key.
+
+## Installation
+
+Requires Node.js >= 18 and Claude Code installed via npm (not the standalone binary).
+
+```bash
+npm install -g claude-code-cache-fix
+```
+
+## Usage
+
+The fix works as a Node.js preload module that intercepts API requests before they leave your machine.
+
+### Option A: Wrapper script (recommended)
+
+Create a wrapper script (e.g. `~/bin/claude-fixed`):
+
+```bash
+#!/bin/bash
+CLAUDE_NPM_CLI="$HOME/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js"
+
+if [ ! -f "$CLAUDE_NPM_CLI" ]; then
+  echo "Error: Claude Code npm package not found at $CLAUDE_NPM_CLI" >&2
+  echo "Install with: npm install -g @anthropic-ai/claude-code" >&2
+  exit 1
+fi
+
+exec env NODE_OPTIONS="--import claude-code-cache-fix" node "$CLAUDE_NPM_CLI" "$@"
+```
+
+```bash
+chmod +x ~/bin/claude-fixed
+```
+
+Adjust `CLAUDE_NPM_CLI` if your npm global prefix differs. Find it with:
+```bash
+npm root -g
+```
+
+### Option B: Shell alias
+
+```bash
+alias claude='NODE_OPTIONS="--import claude-code-cache-fix" node "$(npm root -g)/@anthropic-ai/claude-code/cli.js"'
+```
+
+### Option C: Direct invocation
+
+```bash
+NODE_OPTIONS="--import claude-code-cache-fix" claude
+```
+
+> **Note**: This only works if `claude` points to the npm/Node installation. The standalone binary uses a different execution path that bypasses Node.js preloads.
+
+## How it works
+
+The module intercepts `globalThis.fetch` before Claude Code makes API calls to `/v1/messages`. On each call it:
+
+1. **Scans all user messages** for relocated attachment blocks (skills, MCP, deferred tools, hooks) and moves the latest version of each back to `messages[0]`, matching fresh session layout
+2. **Sorts tool definitions** alphabetically by name for deterministic ordering
+3. **Recomputes the cc_version fingerprint** from the real user message text instead of meta/attachment content
+
+All fixes are idempotent — if nothing needs fixing, the request passes through unmodified. The interceptor is read-only with respect to your conversation; it only normalizes the request structure before it hits the API.
+
+## Debug mode
+
+Enable debug logging to verify the fix is working:
+
+```bash
+CACHE_FIX_DEBUG=1 claude-fixed
+```
+
+Logs are written to `~/.claude/cache-fix-debug.log`. Look for:
+- `APPLIED: resume message relocation` — block scatter was detected and fixed
+- `APPLIED: tool order stabilization` — tools were reordered
+- `APPLIED: fingerprint stabilized from XXX to YYY` — fingerprint was corrected
+- `SKIPPED: resume relocation (not a resume or already correct)` — no fix needed (fresh session or already correct)
+
+## Limitations
+
+- **npm installation only** — The standalone Claude Code binary has Zig-level attestation that bypasses Node.js. This fix only works with the npm package (`npm install -g @anthropic-ai/claude-code`).
+- **Overage TTL downgrade** — Exceeding 100% of the 5-hour quota triggers a server-enforced TTL downgrade from 1h to 5m. This is a server-side decision and cannot be fixed client-side. The interceptor prevents the cache instability that can push you into overage in the first place.
+- **Version coupling** — The fingerprint salt and block detection heuristics are derived from Claude Code internals. A major refactor could require an update to this package.
+
+## Tracked issues
+
+- [#34629](https://github.com/anthropics/claude-code/issues/34629) — Original resume cache regression report
+- [#40524](https://github.com/anthropics/claude-code/issues/40524) — Within-session fingerprint invalidation
+- [#42052](https://github.com/anthropics/claude-code/issues/42052) — Community interceptor development and testing
+- [#43044](https://github.com/anthropics/claude-code/issues/43044) — Resume loads 0% context on v2.1.91
+- [#43657](https://github.com/anthropics/claude-code/issues/43657) — Resume cache invalidation confirmed on v2.1.92
+- [#44045](https://github.com/anthropics/claude-code/issues/44045) — SDK-level reproduction with token measurements
+
+## Contributors
+
+- **[@VictorSun92](https://github.com/VictorSun92)** — Original monkey-patch fix for v2.1.88, identified partial scatter on v2.1.90, contributed forward-scan detection, correct block ordering, and tighter block matchers
+- **[@jmarianski](https://github.com/jmarianski)** — Root cause analysis via MITM proxy capture and Ghidra reverse engineering, multi-mode cache test script
+- **[@cnighswonger](https://github.com/cnighswonger)** — Fingerprint stabilization, tool ordering fix, debug logging, overage TTL downgrade discovery, package maintainer
+
+If you contributed to the community effort on these issues and aren't listed here, please open an issue or PR — we want to credit everyone properly.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "claude-code-cache-fix",
+  "version": "1.0.0",
+  "description": "Fixes prompt cache regression in Claude Code that causes up to 20x cost increase on resumed sessions",
+  "type": "module",
+  "exports": "./preload.mjs",
+  "main": "./preload.mjs",
+  "files": [
+    "preload.mjs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "prompt-cache",
+    "cache-fix",
+    "anthropic",
+    "cost-optimization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cnighswonger/claude-code-cache-fix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cnighswonger/claude-code-cache-fix/issues"
+  },
+  "homepage": "https://github.com/cnighswonger/claude-code-cache-fix#readme",
+  "license": "MIT",
+  "author": "Chris Nighswonger"
+}

package/preload.mjs

@@ -0,0 +1,464 @@
+// claude-code-cache-fix — Node.js fetch interceptor for Claude Code prompt cache bugs.
+//
+// Fixes three bugs that cause prompt cache misses in Claude Code, resulting in
+// up to 20x cost increase on resumed sessions:
+//
+// Bug 1: Partial block scatter on resume
+//   On --resume, attachment blocks (hooks, skills, deferred-tools, MCP) land in
+//   later user messages instead of messages[0]. This breaks the prompt cache
+//   prefix match. Fix: relocate them to messages[0] on every API call.
+//   (github.com/anthropics/claude-code/issues/34629)
+//   (github.com/anthropics/claude-code/issues/43657)
+//   (github.com/anthropics/claude-code/issues/44045)
+//
+// Bug 2: Fingerprint instability
+//   The cc_version fingerprint in the attribution header is computed from
+//   messages[0] content INCLUDING meta/attachment blocks. When those blocks
+//   change between turns, the fingerprint changes -> system prompt bytes
+//   change -> cache bust. Fix: recompute fingerprint from real user text.
+//   (github.com/anthropics/claude-code/issues/40524)
+//
+// Bug 3: Non-deterministic tool schema ordering
+//   Tool definitions can arrive in different orders between turns, changing
+//   request bytes and busting cache. Fix: sort tools alphabetically by name.
+//
+// Based on community work by @VictorSun92 (original monkey-patch + partial
+// scatter fixes) and @jmarianski (MITM proxy root cause analysis).
+//
+// Usage: NODE_OPTIONS="--import claude-code-cache-fix" claude
+
+import { createHash } from "node:crypto";
+import { appendFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Debug logging (writes to ~/.claude/cache-fix-debug.log)
+// Set CACHE_FIX_DEBUG=1 to enable
+// ---------------------------------------------------------------------------
+
+const DEBUG = process.env.CACHE_FIX_DEBUG === "1";
+const LOG_PATH = join(homedir(), ".claude", "cache-fix-debug.log");
+
+function debugLog(...args) {
+  if (!DEBUG) return;
+  const line = `[${new Date().toISOString()}] ${args.join(" ")}\n`;
+  try {
+    appendFileSync(LOG_PATH, line);
+  } catch {}
+}
+
+// ---------------------------------------------------------------------------
+// Fingerprint stabilization (Bug 2)
+// ---------------------------------------------------------------------------
+
+// Must match Claude Code src/utils/fingerprint.ts exactly.
+const FINGERPRINT_SALT = "59cf53e54c78";
+const FINGERPRINT_INDICES = [4, 7, 20];
+
+/**
+ * Recompute the 3-char hex fingerprint the same way the source does:
+ *   SHA256(SALT + msg[4] + msg[7] + msg[20] + version)[:3]
+ * but using the REAL user message text, not the first (possibly meta) message.
+ */
+function computeFingerprint(messageText, version) {
+  const chars = FINGERPRINT_INDICES.map((i) => messageText[i] || "0").join("");
+  const input = `${FINGERPRINT_SALT}${chars}${version}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 3);
+}
+
+/**
+ * Find the first REAL user message text (not a <system-reminder> meta block).
+ * The original bug: extractFirstMessageText() grabs content from messages[0]
+ * which may be a synthetic attachment message, not the actual user prompt.
+ */
+function extractRealUserMessageText(messages) {
+  for (const msg of messages) {
+    if (msg.role !== "user") continue;
+    const content = msg.content;
+    if (!Array.isArray(content)) {
+      if (
+        typeof content === "string" &&
+        !content.startsWith("<system-reminder>")
+      ) {
+        return content;
+      }
+      continue;
+    }
+    for (const block of content) {
+      if (
+        block.type === "text" &&
+        typeof block.text === "string" &&
+        !block.text.startsWith("<system-reminder>")
+      ) {
+        return block.text;
+      }
+    }
+  }
+  return "";
+}
+
+/**
+ * Extract current cc_version from system prompt blocks and recompute with
+ * stable fingerprint. Returns { attrIdx, newText, oldFingerprint, stableFingerprint }
+ * or null if no fix needed.
+ */
+function stabilizeFingerprint(system, messages) {
+  if (!Array.isArray(system)) return null;
+
+  const attrIdx = system.findIndex(
+    (b) =>
+      b.type === "text" &&
+      typeof b.text === "string" &&
+      b.text.includes("x-anthropic-billing-header:")
+  );
+  if (attrIdx === -1) return null;
+
+  const attrBlock = system[attrIdx];
+  const versionMatch = attrBlock.text.match(/cc_version=([^;]+)/);
+  if (!versionMatch) return null;
+
+  const fullVersion = versionMatch[1]; // e.g. "2.1.92.a3f"
+  const dotParts = fullVersion.split(".");
+  if (dotParts.length < 4) return null;
+
+  const baseVersion = dotParts.slice(0, 3).join("."); // "2.1.92"
+  const oldFingerprint = dotParts[3]; // "a3f"
+
+  const realText = extractRealUserMessageText(messages);
+  const stableFingerprint = computeFingerprint(realText, baseVersion);
+
+  if (stableFingerprint === oldFingerprint) return null; // already correct
+
+  const newVersion = `${baseVersion}.${stableFingerprint}`;
+  const newText = attrBlock.text.replace(
+    `cc_version=${fullVersion}`,
+    `cc_version=${newVersion}`
+  );
+
+  return { attrIdx, newText, oldFingerprint, stableFingerprint };
+}
+
+// ---------------------------------------------------------------------------
+// Resume message relocation (Bug 1)
+// ---------------------------------------------------------------------------
+
+function isSystemReminder(text) {
+  return typeof text === "string" && text.startsWith("<system-reminder>");
+}
+
+const SR = "<system-reminder>\n";
+
+function isHooksBlock(text) {
+  return (
+    isSystemReminder(text) && text.substring(0, 200).includes("hook success")
+  );
+}
+function isSkillsBlock(text) {
+  return (
+    typeof text === "string" &&
+    text.startsWith(SR + "The following skills are available")
+  );
+}
+function isDeferredToolsBlock(text) {
+  return (
+    typeof text === "string" &&
+    text.startsWith(SR + "The following deferred tools are now available")
+  );
+}
+function isMcpBlock(text) {
+  return (
+    typeof text === "string" &&
+    text.startsWith(SR + "# MCP Server Instructions")
+  );
+}
+function isRelocatableBlock(text) {
+  return (
+    isHooksBlock(text) ||
+    isSkillsBlock(text) ||
+    isDeferredToolsBlock(text) ||
+    isMcpBlock(text)
+  );
+}
+
+/**
+ * Sort skill listing entries for deterministic ordering (prevents cache bust
+ * from non-deterministic iteration order).
+ */
+function sortSkillsBlock(text) {
+  const match = text.match(
+    /^([\s\S]*?\n\n)(- [\s\S]+?)(\n<\/system-reminder>\s*)$/
+  );
+  if (!match) return text;
+  const [, header, entriesText, footer] = match;
+  const entries = entriesText.split(/\n(?=- )/);
+  entries.sort();
+  return header + entries.join("\n") + footer;
+}
+
+/**
+ * Strip session_knowledge from hooks blocks — ephemeral content that differs
+ * between sessions and would bust cache.
+ */
+function stripSessionKnowledge(text) {
+  return text.replace(
+    /\n<session_knowledge[^>]*>[\s\S]*?<\/session_knowledge>/g,
+    ""
+  );
+}
+
+/**
+ * Core fix: on EVERY API call, scan the entire message array for the LATEST
+ * relocatable blocks (skills, MCP, deferred tools, hooks) and ensure they
+ * are in messages[0]. This matches fresh session behavior where attachments
+ * are always prepended to messages[0].
+ *
+ * The v2.1.90 native fix has a remaining detection gap: it bails early if
+ * it sees *some* relocatable blocks in messages[0], missing the case where
+ * others have scattered elsewhere (partial scatter).
+ *
+ * This version scans backwards to find the latest instance of each
+ * relocatable block type, removes them from wherever they are, and
+ * prepends them to messages[0] in fresh-session order. Idempotent.
+ */
+function normalizeResumeMessages(messages) {
+  if (!Array.isArray(messages) || messages.length < 2) return messages;
+
+  let firstUserIdx = -1;
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].role === "user") {
+      firstUserIdx = i;
+      break;
+    }
+  }
+  if (firstUserIdx === -1) return messages;
+
+  const firstMsg = messages[firstUserIdx];
+  if (!Array.isArray(firstMsg?.content)) return messages;
+
+  // Check if ANY relocatable blocks are scattered outside first user msg.
+  let hasScatteredBlocks = false;
+  for (
+    let i = firstUserIdx + 1;
+    i < messages.length && !hasScatteredBlocks;
+    i++
+  ) {
+    const msg = messages[i];
+    if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (isRelocatableBlock(block.text || "")) {
+        hasScatteredBlocks = true;
+        break;
+      }
+    }
+  }
+  if (!hasScatteredBlocks) return messages;
+
+  // Scan ALL user messages in reverse to collect the LATEST version of each
+  // block type. This handles both full and partial scatter.
+  const found = new Map();
+
+  for (let i = messages.length - 1; i >= firstUserIdx; i--) {
+    const msg = messages[i];
+    if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+
+    for (let j = msg.content.length - 1; j >= 0; j--) {
+      const block = msg.content[j];
+      const text = block.text || "";
+      if (!isRelocatableBlock(text)) continue;
+
+      let blockType;
+      if (isSkillsBlock(text)) blockType = "skills";
+      else if (isMcpBlock(text)) blockType = "mcp";
+      else if (isDeferredToolsBlock(text)) blockType = "deferred";
+      else if (isHooksBlock(text)) blockType = "hooks";
+      else continue;
+
+      if (!found.has(blockType)) {
+        let fixedText = text;
+        if (blockType === "hooks") fixedText = stripSessionKnowledge(text);
+        if (blockType === "skills") fixedText = sortSkillsBlock(text);
+
+        const { cache_control, ...rest } = block;
+        found.set(blockType, { ...rest, text: fixedText });
+      }
+    }
+  }
+
+  if (found.size === 0) return messages;
+
+  // Remove ALL relocatable blocks from ALL user messages
+  const result = messages.map((msg) => {
+    if (msg.role !== "user" || !Array.isArray(msg.content)) return msg;
+    const filtered = msg.content.filter(
+      (b) => !isRelocatableBlock(b.text || "")
+    );
+    if (filtered.length === msg.content.length) return msg;
+    return { ...msg, content: filtered };
+  });
+
+  // Order must match fresh session layout: deferred -> mcp -> skills -> hooks
+  const ORDER = ["deferred", "mcp", "skills", "hooks"];
+  const toRelocate = ORDER.filter((t) => found.has(t)).map((t) => found.get(t));
+
+  result[firstUserIdx] = {
+    ...result[firstUserIdx],
+    content: [...toRelocate, ...result[firstUserIdx].content],
+  };
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Tool schema stabilization (Bug 3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Sort tool definitions by name for deterministic ordering.
+ */
+function stabilizeToolOrder(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return tools;
+  return [...tools].sort((a, b) => {
+    const nameA = a.name || "";
+    const nameB = b.name || "";
+    return nameA.localeCompare(nameB);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Fetch interceptor
+// ---------------------------------------------------------------------------
+
+const _origFetch = globalThis.fetch;
+
+globalThis.fetch = async function (url, options) {
+  const urlStr = typeof url === "string" ? url : url?.url || String(url);
+
+  const isMessagesEndpoint =
+    urlStr.includes("/v1/messages") &&
+    !urlStr.includes("batches") &&
+    !urlStr.includes("count_tokens");
+
+  if (
+    isMessagesEndpoint &&
+    options?.body &&
+    typeof options.body === "string"
+  ) {
+    try {
+      const payload = JSON.parse(options.body);
+      let modified = false;
+
+      debugLog("--- API call to", urlStr);
+      debugLog("message count:", payload.messages?.length);
+
+      // Bug 1: Relocate scattered attachment blocks
+      if (payload.messages) {
+        if (DEBUG) {
+          let firstUserIdx = -1;
+          let lastUserIdx = -1;
+          for (let i = 0; i < payload.messages.length; i++) {
+            if (payload.messages[i].role === "user") {
+              if (firstUserIdx === -1) firstUserIdx = i;
+              lastUserIdx = i;
+            }
+          }
+          if (firstUserIdx !== -1) {
+            const firstContent = payload.messages[firstUserIdx].content;
+            const lastContent = payload.messages[lastUserIdx].content;
+            debugLog(
+              "firstUserIdx:",
+              firstUserIdx,
+              "lastUserIdx:",
+              lastUserIdx
+            );
+            debugLog(
+              "first user msg blocks:",
+              Array.isArray(firstContent) ? firstContent.length : "string"
+            );
+            if (Array.isArray(firstContent)) {
+              for (const b of firstContent) {
+                const t = (b.text || "").substring(0, 80);
+                debugLog(
+                  "  first[block]:",
+                  isRelocatableBlock(b.text) ? "RELOCATABLE" : "keep",
+                  JSON.stringify(t)
+                );
+              }
+            }
+            if (firstUserIdx !== lastUserIdx) {
+              debugLog(
+                "last user msg blocks:",
+                Array.isArray(lastContent) ? lastContent.length : "string"
+              );
+              if (Array.isArray(lastContent)) {
+                for (const b of lastContent) {
+                  const t = (b.text || "").substring(0, 80);
+                  debugLog(
+                    "  last[block]:",
+                    isRelocatableBlock(b.text) ? "RELOCATABLE" : "keep",
+                    JSON.stringify(t)
+                  );
+                }
+              }
+            } else {
+              debugLog("single user message (fresh session)");
+            }
+          }
+        }
+
+        const normalized = normalizeResumeMessages(payload.messages);
+        if (normalized !== payload.messages) {
+          payload.messages = normalized;
+          modified = true;
+          debugLog("APPLIED: resume message relocation");
+        } else {
+          debugLog(
+            "SKIPPED: resume relocation (not a resume or already correct)"
+          );
+        }
+      }
+
+      // Bug 3: Stabilize tool ordering
+      if (payload.tools) {
+        const sorted = stabilizeToolOrder(payload.tools);
+        const changed = sorted.some(
+          (t, i) => t.name !== payload.tools[i]?.name
+        );
+        if (changed) {
+          payload.tools = sorted;
+          modified = true;
+          debugLog("APPLIED: tool order stabilization");
+        }
+      }
+
+      // Bug 2: Stabilize fingerprint in attribution header
+      if (payload.system && payload.messages) {
+        const fix = stabilizeFingerprint(payload.system, payload.messages);
+        if (fix) {
+          payload.system = [...payload.system];
+          payload.system[fix.attrIdx] = {
+            ...payload.system[fix.attrIdx],
+            text: fix.newText,
+          };
+          modified = true;
+          debugLog(
+            "APPLIED: fingerprint stabilized from",
+            fix.oldFingerprint,
+            "to",
+            fix.stableFingerprint
+          );
+        }
+      }
+
+      if (modified) {
+        options = { ...options, body: JSON.stringify(payload) };
+        debugLog("Request body rewritten");
+      }
+    } catch (e) {
+      debugLog("ERROR in interceptor:", e?.message);
+      // Parse failure — pass through unmodified
+    }
+  }
+
+  return _origFetch.apply(this, [url, options]);
+};