claude-code-cache-fix 1.9.1 → 1.10.0

package/README.md

@@ -2,7 +2,19 @@
 
 English | [中文](./README.zh.md) | [Português](./docs/guia-pt-br.md)
 
-Fixes prompt cache regressions in [Claude Code](https://github.com/anthropics/claude-code) that cause **up to 20x cost increase** on resumed sessions, plus monitoring for silent context degradation. Confirmed through v2.1.97.
+Fixes prompt cache regressions in [Claude Code](https://github.com/anthropics/claude-code) that cause **up to 20x cost increase** on resumed sessions, plus monitoring for silent context degradation. Confirmed through v2.1.107.
+
+## Security model
+
+> **This interceptor patches `globalThis.fetch`.** By design, it has full read/write access to all API requests and responses in the Claude Code process. This is inherent to the approach — any fetch interceptor, proxy, or gateway has this position.
+
+**What it does:** Modifies outgoing request structure (block order, fingerprint, TTL, git-status) to fix cache bugs. Reads response headers and SSE usage data for monitoring.
+
+**What it does NOT do:** No network calls from the interceptor. All telemetry is written to local files under `~/.claude/`. No data leaves your machine unless you explicitly opt in to [claude-code-meter](https://github.com/cnighswonger/claude-code-meter) sharing (separate package, requires interactive consent).
+
+**Supply chain:** Single unminified file (`preload.mjs`, ~1,700 lines). One dependency (`zod` for schema validation in tests only). Review before installing. npm provenance links each published version to its source commit.
+
+**Independent audit:** [Assessed as "LEGITIMATE TOOL"](https://github.com/anthropics/claude-code/issues/38335#issuecomment-4244413605) by @TheAuditorTool (2026-04-14).
 
 ## The problem
 
@@ -104,29 +116,69 @@ The wrapper dynamically resolves your npm global root, constructs a `file:///` U
 
 Credit: [@TomTheMenace](https://github.com/anthropics/claude-code/issues/38335) contributed the Windows wrapper and validated the interceptor across a 7.5-hour, 536-call Opus 4.6 session on Windows — 98.4% cache hit rate, 81% of calls had fingerprint instability that the interceptor corrected.
 
-## VS Code Extension (experimental)
+## VS Code Extension
+
+### Option A: VSIX extension (recommended)
+
+The easiest path — a VS Code extension that handles everything automatically:
+
+1. Install the interceptor: `npm install -g claude-code-cache-fix`
+2. Download the VSIX from [GitHub Releases](https://github.com/cnighswonger/claude-code-cache-fix-vscode/releases/latest)
+3. Install: `code --install-extension claude-code-cache-fix-0.1.0.vsix`
+   (or in VS Code: Extensions → `...` menu → "Install from VSIX...")
+4. Restart any active Claude Code session
+
+The extension auto-configures `claudeCode.claudeProcessWrapper` on activation. No manual settings needed. Works on Windows, macOS, and Linux.
+
+Commands available in the VS Code command palette:
+- **Claude Code Cache Fix: Enable** / **Disable** / **Show Status**
+
+### Option B: Manual wrapper (if you prefer not to install the VSIX)
+
+The VS Code Claude Code extension spawns `claude.exe` / `claude` as a subprocess. The `claude-code.environmentVariables` setting does **not** propagate `NODE_OPTIONS`, so a process wrapper is required.
+
+**Linux / macOS** — create `~/bin/claude-vscode-wrapper`:
 
-If you use Claude Code through the VS Code extension rather than the CLI, you may be able to load the interceptor via VS Code settings:
+```bash
+#!/bin/bash
+NPM_ROOT="$(npm root -g 2>/dev/null)"
+PRELOAD="$NPM_ROOT/claude-code-cache-fix/preload.mjs"
+shift  # VS Code passes the original claude path as $1
+export NODE_OPTIONS="--import $PRELOAD"
+exec node "$NPM_ROOT/@anthropic-ai/claude-code/cli.js" "$@"
+```
+
+```bash
+chmod +x ~/bin/claude-vscode-wrapper
+```
+
+Add to VS Code `settings.json`:
 
 ```json
 {
-  "claude-code.environmentVariables": {
-    "NODE_OPTIONS": "--import /path/to/claude-code-cache-fix/preload.mjs"
-  }
+  "claudeCode.claudeProcessWrapper": "/home/YOUR_USERNAME/bin/claude-vscode-wrapper"
 }
 ```
 
-Replace `/path/to` with your npm global root (`npm root -g`). Example for a typical Linux setup:
+**Windows** — `.bat`/`.cmd` wrappers fail because the extension uses `child_process.spawn()` without `shell: true`. Use the C wrapper source included in this package (`tools/claude-vscode-wrapper.c`):
+
+```cmd
+cl tools\claude-vscode-wrapper.c /Fe:claude-vscode-wrapper.exe
+```
+
+Then set in VS Code `settings.json`:
 
 ```json
 {
-  "claude-code.environmentVariables": {
-    "NODE_OPTIONS": "--import /home/username/.npm-global/lib/node_modules/claude-code-cache-fix/preload.mjs"
-  }
+  "claudeCode.claudeProcessWrapper": "C:\\path\\to\\claude-vscode-wrapper.exe"
 }
 ```
 
-**Status: needs community testing.** We've confirmed the `claude-code.environmentVariables` setting exists but haven't verified it propagates `NODE_OPTIONS` to the CC subprocess. If you test this, please report back on [#16](https://github.com/cnighswonger/claude-code-cache-fix/issues/16).
+### Known limitations (VS Code)
+
+- **Fingerprint fix auto-disables**: The VS Code extension constructs `messages[0]` differently than the CLI, causing the fingerprint safety check to trip. Use `CACHE_FIX_SKIP_FINGERPRINT=1` as a workaround. All other fixes (relocate, tool sort, TTL, /clear artifact strip) work normally.
+
+Credit: [@JEONG-JIWOO](https://github.com/JEONG-JIWOO) and [@X-15](https://github.com/X-15) for the VS Code extension investigation and C wrapper ([#16](https://github.com/cnighswonger/claude-code-cache-fix/issues/16)).
 
 ## How it works
 
@@ -226,6 +278,7 @@ Add to `~/.claude/settings.json`:
 ```json
 {
   "statusLine": {
+    "type": "command",
     "command": "~/.claude/hooks/quota-statusline.sh"
   }
 }
@@ -547,6 +600,8 @@ measurable signature of cache-efficiency degradation.
 - **[@TomTheMenace](https://github.com/TomTheMenace)** — Windows `.bat` wrapper for the interceptor, first Windows platform validation (7.5h/536-call Opus 4.6 session, 98.4% cache hit rate, 81% fingerprint instability corrected)
 - **[@arjansingh](https://github.com/arjansingh)** — nvm-compatible wrapper script with dynamic `npm root -g` path resolution (PR #15)
 - **[@beekamai](https://github.com/beekamai)** — Windows URL-encoding fix for `claude-fixed.bat` when npm root contains spaces (PR #17)
+- **[@JEONG-JIWOO](https://github.com/JEONG-JIWOO)** — VS Code extension investigation: discovered `claudeCode.claudeProcessWrapper` as the working integration path, wrote the C wrapper for Windows (#16)
+- **[@X-15](https://github.com/X-15)** — VS Code extension validation, per-fix health status analysis confirming safety check behavior on v2.1.105 (#16)
 
 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.
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "1.9.1",
+  "version": "1.10.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",
+    "postinstall.js",
     "tools/",
     "claude-fixed.bat"
   ],
@@ -14,7 +15,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "postinstall": "node postinstall.js"
   },
   "keywords": [
     "claude-code",
@@ -32,6 +34,10 @@
     "url": "https://github.com/cnighswonger/claude-code-cache-fix/issues"
   },
   "homepage": "https://github.com/cnighswonger/claude-code-cache-fix#readme",
+  "funding": {
+    "type": "individual",
+    "url": "https://buymeacoffee.com/vsits"
+  },
   "license": "MIT",
-  "author": "Chris Nighswonger"
+  "author": "Chris Nighswonger <chris@veritassuperaitsolutions.com> (https://veritassuperaitsolutions.com)"
 }

package/postinstall.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+console.log(`
+┌─────────────────────────────────────────────────────────────────────┐
+│  claude-code-cache-fix — SECURITY NOTICE                           │
+│                                                                     │
+│  This interceptor patches globalThis.fetch to fix prompt cache      │
+│  bugs in Claude Code. By design, it has full read/write access      │
+│  to all API requests and responses in the Claude Code process.      │
+│                                                                     │
+│  • All telemetry is LOCAL ONLY (no network calls from interceptor)  │
+│  • Source is a single unminified file: preload.mjs (~1,700 lines)   │
+│  • Review before use: github.com/cnighswonger/claude-code-cache-fix │
+│                                                                     │
+│  Independent audit: github.com/anthropics/claude-code/issues/38335  │
+│  (search "TheAuditorTool" — assessed as LEGITIMATE TOOL)            │
+└─────────────────────────────────────────────────────────────────────┘
+`);

package/preload.mjs

@@ -189,6 +189,20 @@ function isRelocatableBlock(text) {
     isMcpBlock(text)
   );
 }
+/**
+ * Detect /clear command artifacts that bleed into the next session's messages[0].
+ * These blocks break prefix cache because a post-/clear session has different
+ * messages[0] content than a truly fresh session.
+ * Bug: anthropics/claude-code#47756
+ */
+function isClearArtifact(text) {
+  if (typeof text !== "string") return false;
+  return (
+    text.startsWith("<local-command-caveat>") ||
+    text.startsWith("<command-name>") ||
+    text.startsWith("<local-command-stdout>")
+  );
+}
 
 /**
  * Sort skill listing entries for deterministic ordering (prevents cache bust
@@ -332,6 +346,18 @@ function normalizeResumeMessages(messages) {
   const firstMsg = messages[firstUserIdx];
   if (!Array.isArray(firstMsg?.content)) return messages;
 
+  // FIX: Strip /clear command artifacts from messages[0] (anthropics/claude-code#47756).
+  // After /clear, CC leaves <local-command-caveat>, <command-name>/clear, and
+  // <local-command-stdout> blocks in messages[0] of the new session, breaking
+  // prefix match vs a truly fresh session.
+  const beforeClearStrip = firstMsg.content.length;
+  firstMsg.content = firstMsg.content.filter((block) => !isClearArtifact(block.text || ""));
+  if (firstMsg.content.length < beforeClearStrip) {
+    const stripped = beforeClearStrip - firstMsg.content.length;
+    debugLog(`APPLIED: stripped ${stripped} /clear artifact block(s) from messages[0]`);
+    recordFixResult("relocate", "applied");
+  }
+
   // FIX: Check if ANY relocatable blocks are scattered outside first user msg.
   // The old check (firstAlreadyHas → skip) missed partial scatter where some
   // blocks stay in messages[0] but others drift to later messages (v2.1.89+).
@@ -844,6 +870,7 @@ function printHealthLine() {
   if (FIXES_DISABLED) {
     debugLog("HEALTH: all fixes disabled via CACHE_FIX_DISABLED=1 (monitoring active)");
   }
+  debugLog("SECURITY: This interceptor has full read/write access to API requests. All telemetry is local only — no network calls. Source: github.com/cnighswonger/claude-code-cache-fix");
 }
 
 // --------------------------------------------------------------------------
@@ -1677,6 +1704,7 @@ export {
   isHooksBlock,
   isMcpBlock,
   isRelocatableBlock,
+  isClearArtifact,
   rewriteOutputEfficiencyInstruction,
   normalizeOutputEfficiencyReplacement,
   _pinnedBlocks,  // exported so tests can reset between runs

package/tools/claude-vscode-wrapper.c

@@ -0,0 +1,76 @@
+/*
+ * claude-vscode-wrapper.c — Native wrapper for Claude Code + cache-fix on VS Code (Windows)
+ *
+ * The VS Code Claude extension uses child_process.spawn() without shell: true,
+ * so .bat/.cmd wrappers fail with EINVAL. This native exe sets NODE_OPTIONS
+ * and spawns node cli.js with the interceptor loaded.
+ *
+ * Compile: cl claude-vscode-wrapper.c /Fe:claude-vscode-wrapper.exe
+ *     or:  gcc -o claude-vscode-wrapper.exe claude-vscode-wrapper.c
+ *
+ * Usage in VS Code settings.json:
+ *   { "claudeCode.claudeProcessWrapper": "C:\\path\\to\\claude-vscode-wrapper.exe" }
+ *
+ * Credit: @JEONG-JIWOO (original implementation, #16)
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <process.h>
+#include <windows.h>
+
+int main(int argc, char *argv[]) {
+    char *appdata = getenv("APPDATA");
+    if (!appdata) {
+        fprintf(stderr, "APPDATA not set\n");
+        return 1;
+    }
+
+    /* Build the preload path with forward slashes for file:// URL */
+    char preload[MAX_PATH];
+    snprintf(preload, sizeof(preload),
+        "%s\\npm\\node_modules\\claude-code-cache-fix\\preload.mjs", appdata);
+
+    char preload_url[MAX_PATH];
+    strcpy(preload_url, preload);
+    for (char *p = preload_url; *p; p++) {
+        if (*p == '\\') *p = '/';
+    }
+
+    /* URL-encode spaces for NODE_OPTIONS parsing */
+    char encoded_url[MAX_PATH * 3];
+    char *dst = encoded_url;
+    for (const char *src = preload_url; *src && dst < encoded_url + sizeof(encoded_url) - 4; src++) {
+        if (*src == ' ') {
+            *dst++ = '%'; *dst++ = '2'; *dst++ = '0';
+        } else {
+            *dst++ = *src;
+        }
+    }
+    *dst = '\0';
+
+    char node_opts[MAX_PATH * 4];
+    snprintf(node_opts, sizeof(node_opts),
+        "NODE_OPTIONS=--import file:///%s", encoded_url);
+    _putenv(node_opts);
+
+    /* Path to Claude Code CLI */
+    char cli_path[MAX_PATH];
+    snprintf(cli_path, sizeof(cli_path),
+        "%s\\npm\\node_modules\\@anthropic-ai\\claude-code\\cli.js", appdata);
+
+    /* Build argv: skip argv[1] (original claude path passed by extension) */
+    char **new_argv = malloc(sizeof(char *) * (argc + 2));
+    if (!new_argv) return 1;
+
+    new_argv[0] = "node";
+    new_argv[1] = cli_path;
+    int j = 2;
+    for (int i = 2; i < argc; i++) {
+        new_argv[j++] = argv[i];
+    }
+    new_argv[j] = NULL;
+
+    return _spawnvp(_P_WAIT, "node", (const char *const *)new_argv);
+}

package/tools/quota-statusline.sh

@@ -6,9 +6,33 @@
 input=$(cat)
 
 JSONL="$HOME/.claude/claude-meter.jsonl"
+QS="$HOME/.claude/quota-status.json"
 
+# Primary source: claude-meter.jsonl (requires claude-code-meter package)
+# Fallback: quota-status.json (written by claude-code-cache-fix interceptor)
 if [ -f "$JSONL" ]; then
   last=$(tail -1 "$JSONL" 2>/dev/null)
+elif [ -f "$QS" ]; then
+  # Translate quota-status.json into the same shape the Python expects
+  last=$(python3 -c "
+import json, pathlib
+qs = json.load(open(pathlib.Path.home() / '.claude' / 'quota-status.json'))
+fh = qs.get('five_hour', {})
+sd = qs.get('seven_day', {})
+print(json.dumps({
+    'q5h': fh.get('utilization', 0),
+    'q7d': sd.get('utilization', 0),
+    'q5h_reset': fh.get('resets_at', 0),
+    'q7d_reset': sd.get('resets_at', 0),
+    'qoverage': qs.get('overage_status', ''),
+    'ts': qs.get('timestamp', ''),
+}))
+" 2>/dev/null)
+else
+  exit 0
+fi
+
+if [ -z "$last" ]; then exit 0; fi
 
   result=$(echo "$last" | python3 -c "
 import sys, json
@@ -83,4 +107,3 @@ print(label)
 " 2>/dev/null)
 
   [ -n "$result" ] && echo "$result"
-fi