claude-code-cache-fix 1.5.1 → 1.6.1

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](./README.zh.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.92.
+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.
 
 ## The problem
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](./README.md) | 中文
 
-修复 [Claude Code](https://github.com/anthropics/claude-code) 中导致恢复会话时**成本增加高达 20 倍**的提示缓存回归问题，同时监控静默上下文降级。已在 v2.1.92 至 v2.1.96 上验证。
+修复 [Claude Code](https://github.com/anthropics/claude-code) 中导致恢复会话时**成本增加高达 20 倍**的提示缓存回归问题，同时监控静默上下文降级。已在 v2.1.92 至 v2.1.97 上验证。
 
 ## 问题描述
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Fixes prompt cache regression in Claude Code that causes up to 20x cost increase on resumed sessions",
   "type": "module",
   "exports": "./preload.mjs",

package/preload.mjs

@@ -834,6 +834,41 @@ globalThis.fetch = async function (url, options) {
         }
       }
 
+      // Bug 5: 1h TTL enforcement
+      // The client gates 1h cache TTL behind a GrowthBook allowlist that checks
+      // querySource against patterns like "repl_main_thread*", "sdk", "auto_mode".
+      // Interactive CLI sessions may not match any pattern, causing the client to
+      // send cache_control without ttl (defaulting to 5m server-side).
+      // The server honors whatever TTL the client requests — so we inject it.
+      // Discovered by @TigerKay1926 on #42052 using our GrowthBook flag dump.
+      if (payload.system) {
+        let ttlInjected = 0;
+        payload.system = payload.system.map((block) => {
+          if (block.cache_control?.type === "ephemeral" && !block.cache_control.ttl) {
+            ttlInjected++;
+            return { ...block, cache_control: { ...block.cache_control, ttl: "1h" } };
+          }
+          return block;
+        });
+        // Also check messages for cache_control blocks (conversation history breakpoints)
+        if (payload.messages) {
+          for (const msg of payload.messages) {
+            if (!Array.isArray(msg.content)) continue;
+            for (let i = 0; i < msg.content.length; i++) {
+              const b = msg.content[i];
+              if (b.cache_control?.type === "ephemeral" && !b.cache_control.ttl) {
+                msg.content[i] = { ...b, cache_control: { ...b.cache_control, ttl: "1h" } };
+                ttlInjected++;
+              }
+            }
+          }
+        }
+        if (ttlInjected > 0) {
+          modified = true;
+          debugLog(`APPLIED: 1h TTL injected on ${ttlInjected} cache_control block(s)`);
+        }
+      }
+
       if (modified) {
         options = { ...options, body: JSON.stringify(payload) };
         debugLog("Request body rewritten");
@@ -927,12 +962,18 @@ globalThis.fetch = async function (url, options) {
     }
 
     // Clone response to extract TTL tier and usage telemetry from SSE stream.
-    // Pass the model from the request so we can log a complete usage record.
+    // Pass the model and quota headers so we can log a complete usage record.
     try {
       let reqModel = "unknown";
       try { reqModel = JSON.parse(options?.body)?.model || "unknown"; } catch {}
+      const quotaHeaders = {
+        q5h: parseFloat(response.headers.get("anthropic-ratelimit-unified-5h-utilization") || "0"),
+        q7d: parseFloat(response.headers.get("anthropic-ratelimit-unified-7d-utilization") || "0"),
+        status: response.headers.get("anthropic-ratelimit-unified-status") || null,
+        overage: response.headers.get("anthropic-ratelimit-unified-overage-status") || null,
+      };
       const clone = response.clone();
-      drainTTLFromClone(clone, reqModel).catch(() => {});
+      drainTTLFromClone(clone, reqModel, quotaHeaders).catch(() => {});
     } catch {
       // clone() failure is non-fatal
     }
@@ -953,7 +994,7 @@ globalThis.fetch = async function (url, options) {
  * Writes TTL tier to ~/.claude/quota-status.json (merges with existing data)
  * and logs to debug log.
  */
-async function drainTTLFromClone(clone, model) {
+async function drainTTLFromClone(clone, model, quotaHeaders) {
   if (!clone.body) return;
 
   const reader = clone.body.getReader();
@@ -1047,8 +1088,11 @@ async function drainTTLFromClone(clone, model) {
   if (startUsage) {
     try {
       const cc = startUsage.cache_creation || {};
+      const now = new Date();
+      const utcHour = now.getUTCHours();
+      const utcDay = now.getUTCDay();
       const record = {
-        timestamp: new Date().toISOString(),
+        timestamp: now.toISOString(),
         model: model || "unknown",
         input_tokens: startUsage.input_tokens ?? 0,
         output_tokens: deltaUsage?.output_tokens ?? 0,
@@ -1057,6 +1101,9 @@ async function drainTTLFromClone(clone, model) {
         ephemeral_1h_input_tokens: cc.ephemeral_1h_input_tokens ?? 0,
         ephemeral_5m_input_tokens: cc.ephemeral_5m_input_tokens ?? 0,
         ttl_tier: ttlTier,
+        q5h_pct: quotaHeaders ? Math.round(quotaHeaders.q5h * 100) : null,
+        q7d_pct: quotaHeaders ? Math.round(quotaHeaders.q7d * 100) : null,
+        peak_hour: utcDay >= 1 && utcDay <= 5 && utcHour >= 13 && utcHour < 19,
       };
       appendFileSync(USAGE_JSONL, JSON.stringify(record) + "\n");
     } catch {

package/tools/cache-test.sh

@@ -0,0 +1,249 @@
+#!/bin/bash
+# cache-test.sh — Test Claude Code cache behavior with and without interceptor.
+#
+# Runs four scenarios and captures cache stats for each:
+#   1. One-shot WITHOUT interceptor (baseline)
+#   2. One-shot WITH interceptor
+#   3. Multi-turn WITHOUT interceptor (conversation + resume)
+#   4. Multi-turn WITH interceptor (conversation + resume)
+#
+# Outputs a summary report comparing TTL tier, cache hit rates, and
+# whether the interceptor's fixes fired.
+#
+# Usage:
+#   ./cache-test.sh [--skip-resume]   # --skip-resume skips the resume tests
+#
+# Requires: Claude Code installed via npm, claude-code-cache-fix installed.
+
+set -euo pipefail
+
+CLAUDE_CLI="$HOME/.npm-global/lib/node_modules/@anthropic-ai/claude-code/cli.js"
+PRELOAD="$HOME/.claude/cache-fix-preload.mjs"
+QUOTA_FILE="$HOME/.claude/quota-status.json"
+USAGE_LOG="$HOME/.claude/usage.jsonl"
+DEBUG_LOG="$HOME/.claude/cache-fix-debug.log"
+REPORT_DIR="/tmp/cache-test-$(date +%Y%m%d_%H%M%S)"
+SKIP_RESUME=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --skip-resume) SKIP_RESUME=true ;;
+  esac
+done
+
+# Verify prerequisites
+if [ ! -f "$CLAUDE_CLI" ]; then
+  echo "ERROR: Claude Code not found at $CLAUDE_CLI" >&2
+  echo "Install with: npm install -g @anthropic-ai/claude-code" >&2
+  exit 1
+fi
+
+if [ ! -f "$PRELOAD" ]; then
+  echo "ERROR: cache-fix preload not found at $PRELOAD" >&2
+  echo "Install with: npm install -g claude-code-cache-fix" >&2
+  exit 1
+fi
+
+CC_VERSION=$(node "$CLAUDE_CLI" --version 2>/dev/null | head -1)
+echo "=========================================="
+echo "  CACHE BEHAVIOR TEST"
+echo "  Claude Code: $CC_VERSION"
+echo "  Report dir:  $REPORT_DIR"
+echo "=========================================="
+echo ""
+
+mkdir -p "$REPORT_DIR"
+
+# Helper: snapshot cache state from quota-status.json
+snapshot_cache() {
+  local label="$1"
+  local outfile="$REPORT_DIR/${label}.json"
+  if [ -f "$QUOTA_FILE" ]; then
+    cp "$QUOTA_FILE" "$outfile"
+    local tier=$(python3 -c "import json; d=json.load(open('$QUOTA_FILE')); print(d.get('cache',{}).get('ttl_tier','?'))" 2>/dev/null || echo "?")
+    local create=$(python3 -c "import json; d=json.load(open('$QUOTA_FILE')); print(d.get('cache',{}).get('cache_creation',0))" 2>/dev/null || echo "?")
+    local read=$(python3 -c "import json; d=json.load(open('$QUOTA_FILE')); print(d.get('cache',{}).get('cache_read',0))" 2>/dev/null || echo "?")
+    local e1h=$(python3 -c "import json; d=json.load(open('$QUOTA_FILE')); print(d.get('cache',{}).get('ephemeral_1h',0))" 2>/dev/null || echo "?")
+    local e5m=$(python3 -c "import json; d=json.load(open('$QUOTA_FILE')); print(d.get('cache',{}).get('ephemeral_5m',0))" 2>/dev/null || echo "?")
+    local hit=$(python3 -c "import json; d=json.load(open('$QUOTA_FILE')); print(d.get('cache',{}).get('hit_rate','?'))" 2>/dev/null || echo "?")
+    echo "  [$label] TTL=$tier  create=$create  read=$read  1h=$e1h  5m=$e5m  hit=$hit%"
+  else
+    echo "  [$label] No quota-status.json found"
+  fi
+}
+
+# Helper: count usage.jsonl entries
+count_usage() {
+  if [ -f "$USAGE_LOG" ]; then
+    wc -l < "$USAGE_LOG" | tr -d ' '
+  else
+    echo "0"
+  fi
+}
+
+# Helper: capture debug log entries
+snapshot_debug() {
+  local label="$1"
+  if [ -f "$DEBUG_LOG" ]; then
+    cp "$DEBUG_LOG" "$REPORT_DIR/${label}-debug.log"
+  fi
+}
+
+# ─── Test 1: One-shot WITHOUT interceptor ────────────────────────────────────
+
+echo "--- Test 1: One-shot WITHOUT interceptor ---"
+rm -f "$DEBUG_LOG"
+usage_before=$(count_usage)
+
+# Call 1: cold start
+node "$CLAUDE_CLI" -p "respond with exactly: cache-test-1a" --dangerously-skip-permissions > "$REPORT_DIR/test1a-output.txt" 2>&1
+snapshot_cache "test1a-no-interceptor"
+
+# Wait 2 seconds for any async writes
+sleep 2
+
+# Call 2: should get cache hit
+node "$CLAUDE_CLI" -p "respond with exactly: cache-test-1b" --dangerously-skip-permissions > "$REPORT_DIR/test1b-output.txt" 2>&1
+snapshot_cache "test1b-no-interceptor"
+
+usage_after=$(count_usage)
+echo "  Usage entries added: $((usage_after - usage_before))"
+echo ""
+
+# ─── Test 2: One-shot WITH interceptor ───────────────────────────────────────
+
+echo "--- Test 2: One-shot WITH interceptor ---"
+rm -f "$DEBUG_LOG"
+usage_before=$(count_usage)
+
+# Call 1: cold start with interceptor
+CACHE_FIX_DEBUG=1 NODE_OPTIONS="--import $PRELOAD" \
+  node "$CLAUDE_CLI" -p "respond with exactly: cache-test-2a" --dangerously-skip-permissions > "$REPORT_DIR/test2a-output.txt" 2>&1
+snapshot_cache "test2a-with-interceptor"
+snapshot_debug "test2a"
+
+sleep 2
+
+# Call 2: should get cache hit
+CACHE_FIX_DEBUG=1 NODE_OPTIONS="--import $PRELOAD" \
+  node "$CLAUDE_CLI" -p "respond with exactly: cache-test-2b" --dangerously-skip-permissions > "$REPORT_DIR/test2b-output.txt" 2>&1
+snapshot_cache "test2b-with-interceptor"
+snapshot_debug "test2b"
+
+usage_after=$(count_usage)
+echo "  Usage entries added: $((usage_after - usage_before))"
+echo ""
+
+# ─── Test 3 & 4: Multi-turn + Resume ────────────────────────────────────────
+
+if [ "$SKIP_RESUME" = true ]; then
+  echo "--- Tests 3 & 4: SKIPPED (--skip-resume) ---"
+  echo ""
+else
+  # Test 3: Multi-turn WITHOUT interceptor
+  echo "--- Test 3: Multi-turn + Resume WITHOUT interceptor ---"
+  rm -f "$DEBUG_LOG"
+  usage_before=$(count_usage)
+
+  # Start a session with a named session, do 2 turns, exit, then resume
+  SESSION_NAME="cache-test-no-fix-$$"
+
+  # Turn 1
+  node "$CLAUDE_CLI" -p "respond with exactly: turn1-done" \
+    --dangerously-skip-permissions -n "$SESSION_NAME" \
+    > "$REPORT_DIR/test3-turn1-output.txt" 2>&1
+  snapshot_cache "test3-turn1-no-interceptor"
+
+  sleep 2
+
+  # Turn 2 (resume)
+  node "$CLAUDE_CLI" -p "respond with exactly: turn2-done" \
+    --dangerously-skip-permissions -c \
+    > "$REPORT_DIR/test3-turn2-output.txt" 2>&1
+  snapshot_cache "test3-turn2-no-interceptor"
+
+  sleep 2
+
+  # Turn 3 (second resume — this is where scatter typically shows)
+  node "$CLAUDE_CLI" -p "respond with exactly: turn3-done" \
+    --dangerously-skip-permissions -c \
+    > "$REPORT_DIR/test3-turn3-output.txt" 2>&1
+  snapshot_cache "test3-turn3-no-interceptor"
+
+  usage_after=$(count_usage)
+  echo "  Usage entries added: $((usage_after - usage_before))"
+  echo ""
+
+  # Test 4: Multi-turn WITH interceptor
+  echo "--- Test 4: Multi-turn + Resume WITH interceptor ---"
+  rm -f "$DEBUG_LOG"
+  usage_before=$(count_usage)
+
+  SESSION_NAME="cache-test-with-fix-$$"
+
+  # Turn 1
+  CACHE_FIX_DEBUG=1 CACHE_FIX_PREFIXDIFF=1 NODE_OPTIONS="--import $PRELOAD" \
+    node "$CLAUDE_CLI" -p "respond with exactly: turn1-done" \
+    --dangerously-skip-permissions -n "$SESSION_NAME" \
+    > "$REPORT_DIR/test4-turn1-output.txt" 2>&1
+  snapshot_cache "test4-turn1-with-interceptor"
+  snapshot_debug "test4-turn1"
+
+  sleep 2
+
+  # Turn 2 (resume)
+  CACHE_FIX_DEBUG=1 CACHE_FIX_PREFIXDIFF=1 NODE_OPTIONS="--import $PRELOAD" \
+    node "$CLAUDE_CLI" -p "respond with exactly: turn2-done" \
+    --dangerously-skip-permissions -c \
+    > "$REPORT_DIR/test4-turn2-output.txt" 2>&1
+  snapshot_cache "test4-turn2-with-interceptor"
+  snapshot_debug "test4-turn2"
+
+  sleep 2
+
+  # Turn 3 (second resume)
+  CACHE_FIX_DEBUG=1 CACHE_FIX_PREFIXDIFF=1 NODE_OPTIONS="--import $PRELOAD" \
+    node "$CLAUDE_CLI" -p "respond with exactly: turn3-done" \
+    --dangerously-skip-permissions -c \
+    > "$REPORT_DIR/test4-turn3-output.txt" 2>&1
+  snapshot_cache "test4-turn3-with-interceptor"
+  snapshot_debug "test4-turn3"
+
+  usage_after=$(count_usage)
+  echo "  Usage entries added: $((usage_after - usage_before))"
+  echo ""
+fi
+
+# ─── Summary ────────────────────────────────────────────────────────────────
+
+echo "=========================================="
+echo "  SUMMARY"
+echo "=========================================="
+echo ""
+echo "All snapshots saved to: $REPORT_DIR"
+echo ""
+echo "Cache snapshots:"
+for f in "$REPORT_DIR"/*.json; do
+  label=$(basename "$f" .json)
+  tier=$(python3 -c "import json; d=json.load(open('$f')); print(d.get('cache',{}).get('ttl_tier','?'))" 2>/dev/null || echo "?")
+  create=$(python3 -c "import json; d=json.load(open('$f')); print(d.get('cache',{}).get('cache_creation',0))" 2>/dev/null || echo "?")
+  read=$(python3 -c "import json; d=json.load(open('$f')); print(d.get('cache',{}).get('cache_read',0))" 2>/dev/null || echo "?")
+  e1h=$(python3 -c "import json; d=json.load(open('$f')); print(d.get('cache',{}).get('ephemeral_1h',0))" 2>/dev/null || echo "?")
+  e5m=$(python3 -c "import json; d=json.load(open('$f')); print(d.get('cache',{}).get('ephemeral_5m',0))" 2>/dev/null || echo "?")
+  printf "  %-40s TTL=%-4s create=%-6s read=%-6s 1h=%-6s 5m=%-6s\n" "$label" "$tier" "$create" "$read" "$e1h" "$e5m"
+done
+
+# Check for interceptor actions in debug logs
+echo ""
+echo "Interceptor actions:"
+for f in "$REPORT_DIR"/*-debug.log; do
+  [ -f "$f" ] || continue
+  label=$(basename "$f" -debug.log)
+  applied=$(grep -c "APPLIED:" "$f" 2>/dev/null || echo 0)
+  skipped=$(grep -c "SKIPPED:" "$f" 2>/dev/null || echo 0)
+  pins=$(grep -c "CONTENT PIN:" "$f" 2>/dev/null || echo 0)
+  echo "  $label: $applied applied, $skipped skipped, $pins content pins"
+done
+
+echo ""
+echo "Done. Review $REPORT_DIR for full details."