claude-code-cache-fix 3.8.0 → 3.9.0

package/hooks/README.md

@@ -0,0 +1,36 @@
+# cache-fix hook examples
+
+Standalone `PreToolUse` / `PostToolUse` / `SessionStart` hook scripts that address specific Claude Code behaviors. These are **examples** — you install them by pointing at them from your own `~/.claude/settings.json` (or per-project `.claude/settings.json`). cache-fix does not register them automatically.
+
+Independent of the proxy. Hooks run client-side via CC's hooks contract; they don't touch the API request path.
+
+## Available examples
+
+| Script | Event | Purpose | Docs |
+|---|---|---|---|
+| `examples/worktree-edit-guard.py` | `PreToolUse` | Block `Edit`/`Write`/`MultiEdit`/`NotebookEdit` calls whose target path falls outside the active git worktree root. Addresses [CC#59628](https://github.com/anthropics/claude-code/issues/59628). | [`docs/hooks/worktree-edit-guard.md`](../docs/hooks/worktree-edit-guard.md) |
+
+## Installing a hook
+
+Each script's docs page has its own settings.json snippet. The general shape:
+
+```jsonc
+{
+  "hooks": {
+    "<EventName>": [
+      {
+        "matcher": "<ToolName1>|<ToolName2>",
+        "hooks": [
+          { "type": "command", "command": "/abs/path/to/hooks/examples/<script>" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The `command` field must be an absolute path per CC's hooks contract. Make sure the script is executable.
+
+## CC hooks reference
+
+https://code.claude.com/docs/en/hooks — exit-code semantics, structured output schema, matcher patterns, the full event taxonomy.

package/hooks/examples/worktree-edit-guard.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: refuse Edit/Write/MultiEdit/NotebookEdit calls whose
+target path falls outside the active git worktree root.
+
+Addresses anthropics/claude-code#59628 (worktree sessions can corrupt the
+parent main checkout). See docs/hooks/worktree-edit-guard.md for install.
+
+Exit codes (per CC PreToolUse hook contract):
+  0  pass-through (allow)
+  2  block (CC feeds stderr back to the agent)
+Posture: environmental failures fail open (exit 0); protocol-shape failures
+(missing expected path field on an in-scope tool) fail closed (exit 2)."""
+
+import json
+import os
+import subprocess
+import sys
+
+IN_SCOPE = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+PATH_FIELD = {"Edit": "file_path", "Write": "file_path",
+              "MultiEdit": "file_path", "NotebookEdit": "notebook_path"}
+
+
+def git(*args, cwd):
+    """Run git; return stripped stdout on success, None on any failure."""
+    try:
+        r = subprocess.run(("git",) + args, cwd=cwd, timeout=2,
+                           capture_output=True, text=True, check=False)
+        return r.stdout.strip() if r.returncode == 0 else None
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def worktree_root(cwd):
+    """Return the worktree root if cwd is inside a linked worktree, else None.
+
+    Detection: realpath-equality of --git-dir and --git-common-dir. They are
+    equal in a regular checkout (from any depth) and differ inside a linked
+    worktree. Compare realpaths because --git-common-dir returns paths
+    relative to cwd, so raw string compare breaks below the repo root."""
+    top = git("rev-parse", "--show-toplevel", cwd=cwd)
+    gd = git("rev-parse", "--git-dir", cwd=cwd)
+    gcd = git("rev-parse", "--git-common-dir", cwd=cwd)
+    if not (top and gd and gcd):
+        return None
+    if os.path.realpath(os.path.join(cwd, gd)) == os.path.realpath(os.path.join(cwd, gcd)):
+        return None
+    return os.path.realpath(top)
+
+
+def resolved_target(target):
+    """Realpath the target. If the target exists (including as a broken
+    symlink), realpath it directly so a target that IS a symlink resolves
+    to its destination (not back to itself). If it doesn't exist, fall
+    back to realpath(parent_dir) + basename so a symlinked PARENT still
+    gets caught even when the leaf will be created by the tool."""
+    if os.path.lexists(target):
+        return os.path.realpath(target)
+    return os.path.join(os.path.realpath(os.path.dirname(target)),
+                        os.path.basename(target))
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0  # fail-open: malformed input is an environmental fault
+    tool = payload.get("tool_name")
+    if tool not in IN_SCOPE:
+        return 0
+    field = PATH_FIELD[tool]
+    target = (payload.get("tool_input") or {}).get(field)
+    if not isinstance(target, str) or not target:
+        sys.stderr.write(f"worktree-edit-guard: refusing {tool} — "
+                         f"missing tool_input.{field}.\n")
+        return 2  # fail-closed: protocol-shape mismatch
+    cwd = payload.get("cwd") or os.getcwd()
+    root = worktree_root(cwd)
+    if root is None:
+        return 0  # not in a linked worktree; nothing to enforce
+    if not os.path.isabs(target):
+        target = os.path.join(cwd, target)
+    abs_target = resolved_target(target)
+    if abs_target == root or abs_target.startswith(root + os.sep):
+        return 0
+    sys.stderr.write(f"worktree-edit-guard: refusing {tool} on {abs_target} — "
+                     f"outside worktree {root}. Use a path inside the worktree, "
+                     f"or disable this hook in settings.json.\n")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": {
@@ -15,6 +15,7 @@
     "preload.mjs",
     "postinstall.js",
     "tools/",
+    "hooks/",
     "claude-fixed.bat",
     "proxy/",
     "bin/",

package/proxy/extensions/auto-1m-guard.mjs

@@ -0,0 +1,117 @@
+// auto-1m-guard — detect/warn/strip the 1M-context beta token on outbound
+// requests. Addresses anthropics/claude-code#64919 (VS Code Extension forcing
+// 1M context on Pro Plan).
+//
+// Binary-walk (CC v2.1.148 / v2.1.161 — same code body, names churned):
+//   sL→kJ:  function strips /\[(1|2)m\]/gi from the model string
+//   W2→bZ:  gates 1M-beta inclusion on /\[1m\]/i.test(model)
+//   xKH→E9H: kill switch keys off CLAUDE_CODE_DISABLE_1M_CONTEXT
+// CC always applies the sanitizer at messages.create call sites:
+//   messages.create({...J, model: kJ(J.model)})
+// So req.body.model NEVER carries [1m] on the wire — the proxy-visible
+// signal is the anthropic-beta REQUEST HEADER carrying context-1m-2025-08-07.
+//
+// Three modes (env: CACHE_FIX_AUTO_1M_GUARD):
+//   off    no-op
+//   warn   (default) stash _auto1mGuard annotation + stderr line; no mutation
+//   strip  also remove context-1m-2025-08-07 from the anthropic-beta header
+//
+// Order 520: after ttl-management (500) and before thinking-block-sanitize
+// (550) / session-health (590) / cache-telemetry (600). The stashed flat
+// object at ctx.meta._auto1mGuard is spread top-level into the per-session
+// JSON by cache-telemetry, matching the _sessionHealth / _thinkingSanitize
+// pattern.
+//
+// See docs/directives/proxy-auto-1m-guard.md.
+
+const BETA_TOKEN_1M = "context-1m-2025-08-07";
+const HEADER_NAME = "anthropic-beta";
+const ADVICE =
+  "Outbound request carries the context-1m-2025-08-07 beta header, which enables 1M context. " +
+  "On Pro plans this consumes overage credits immediately. To prevent CC from auto-selecting 1M: " +
+  "set CLAUDE_CODE_DISABLE_1M_CONTEXT=1 in your env, or use /model with a non-[1m] model variant " +
+  "in-session. Strip mode (CACHE_FIX_AUTO_1M_GUARD=strip) intercepts the header at the proxy.";
+
+function modeFromEnv() {
+  const v = process.env.CACHE_FIX_AUTO_1M_GUARD;
+  if (v === "off" || v === "strip") return v;
+  return "warn";
+}
+
+// Case-insensitive read of the anthropic-beta header. Mirrors
+// upstream-change-detection.mjs:200-207. Returns { key, raw } where key is
+// the actual property name found (so the rewrite can replace in-place),
+// or null if absent.
+export function findBetaHeader(headers) {
+  if (!headers) return null;
+  for (const k of Object.keys(headers)) {
+    if (k.toLowerCase() === HEADER_NAME) {
+      return { key: k, raw: headers[k] };
+    }
+  }
+  return null;
+}
+
+// Parse the comma-separated header value into a trimmed token array.
+// Tolerates string or array input.
+export function parseBetaTokens(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.map(String).map((s) => s.trim()).filter(Boolean);
+  if (typeof raw === "string") return raw.split(",").map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+// Pure planner: returns { detected, stripped, tokensAfter } given the
+// parsed token array. Strip removes ALL occurrences (defensive against
+// duplicates introduced by intermediaries).
+export function planSanitizeBetaHeader(tokens, mode) {
+  const detected = tokens.includes(BETA_TOKEN_1M);
+  if (!detected || mode !== "strip") {
+    return { detected, stripped: false, tokensAfter: tokens };
+  }
+  const tokensAfter = tokens.filter((t) => t !== BETA_TOKEN_1M);
+  return { detected, stripped: true, tokensAfter };
+}
+
+// Rejoin tokens with the CC-canonical ", " separator. Empty array → "".
+export function joinBetaTokens(tokens) {
+  return tokens.join(", ");
+}
+
+export default {
+  name: "auto-1m-guard",
+  description:
+    "Detect (warn) or remove (strip) the context-1m-2025-08-07 token from the outbound anthropic-beta header. " +
+    "Addresses CC#64919 (VS Code Extension forcing 1M context on Pro Plan). " +
+    "Modes via CACHE_FIX_AUTO_1M_GUARD: off | warn (default) | strip.",
+  order: 520,
+
+  async onRequest(ctx) {
+    const mode = modeFromEnv();
+    if (mode === "off") return;
+
+    const found = findBetaHeader(ctx.headers);
+    if (!found) return;
+
+    const tokens = parseBetaTokens(found.raw);
+    const plan = planSanitizeBetaHeader(tokens, mode);
+    if (!plan.detected) return;
+
+    if (plan.stripped) {
+      ctx.headers[found.key] = joinBetaTokens(plan.tokensAfter);
+    }
+
+    ctx.meta._auto1mGuard = {
+      auto_1m_detected: true,
+      auto_1m_action: plan.stripped ? "stripped" : "warn",
+      auto_1m_advice: ADVICE,
+    };
+
+    process.stderr.write(
+      `[auto-1m-guard] ${BETA_TOKEN_1M} detected in outbound betas` +
+        (plan.stripped ? " — stripped" : "") +
+        ` — see CACHE_FIX_AUTO_1M_GUARD=strip to intercept. ` +
+        `Set CLAUDE_CODE_DISABLE_1M_CONTEXT=1 to prevent CC from sending it.\n`,
+    );
+  },
+};

package/proxy/extensions/cache-telemetry.mjs

@@ -236,6 +236,11 @@ export default {
           // Additive thinking-block-sanitize drop count (order 550, opt-in).
           // Optional — absent unless CACHE_FIX_THINKING_SANITIZE=on.
           ...(ctx.meta._thinkingSanitize || {}),
+          // Additive auto-1m-guard annotation (order 520). Optional — absent
+          // unless the outbound request carried context-1m-2025-08-07 and the
+          // mode wasn't off. Keys: auto_1m_detected / auto_1m_action /
+          // auto_1m_advice.
+          ...(ctx.meta._auto1mGuard || {}),
           timestamp,
           session_id: rawSid,
         },

package/tools/MANUAL-COMPACT.md

@@ -10,10 +10,10 @@ When using the 1M context window hack (`DISABLE_COMPACT=1` + `CLAUDE_CODE_MAX_CO
 
 1. Extracts conversation turns from the session JSONL transcript
 2. Splits turns into three weighted segments:
-   - **Foundational** (first 20%) — truncated to 200 chars each
-   - **Working** (middle 40%) — truncated to 400 chars each
-   - **Active** (last 40%) — preserved up to 2000 chars each
-3. Sends the weighted extract to Claude Sonnet for summarization
+   - **Foundational** (first 20%) — truncated to 300 chars each
+   - **Working** (middle 40%) — truncated to 1500 chars each
+   - **Active** (last 40%) — preserved up to 8000 chars each
+3. Sends the weighted extract to Claude Opus for summarization
 4. Produces a structured summary optimized for agent handoff
 
 The weighting ensures recent active work (the part you're most likely to need) gets full detail, while earlier completed work is compressed.
@@ -142,7 +142,7 @@ Use the user context file to fill known gaps.
 
 Two costs to account for:
 
-1. **Summarization call** — the `claude --print` call through Sonnet. At ~50K extract tokens, expect ~1-2% Q5h.
+1. **Summarization call** — the `claude --print` call through Opus. With the relaxed recent-turn caps the extract is larger (and Opus costs more per token than Sonnet), so expect a few % Q5h rather than ~1-2%. The tradeoff buys markedly higher-fidelity summaries; override with `MANUAL_COMPACT_MODEL=claude-sonnet-4-6` if you need to minimize cost.
 2. **Cold start after /clear** — the first API call rebuilds the full cache from scratch. Real-world example from a 954K-token session:
 
 ```
@@ -153,11 +153,18 @@ Second call:    cache_read=957,253  cache_creation=5,569   (warm again)
 
 The cold rebuild consumed ~15% Q5h in one call on our Max 5x account. After that single rebuild, the session is warm again and cache hits resume at 99%+.
 
-**Total cost of a manual compact cycle:** ~17% Q5h (2% summarization + 15% cold rebuild). Compare to hitting the 1M wall and losing the session entirely.
+**Total cost of a manual compact cycle:** roughly ~15% cold rebuild plus a few % for the Opus summarization. Compare to hitting the 1M wall and losing the session entirely.
 
-### Requires Claude Sonnet access
+### Summarizer model
 
-The tool uses `claude --print --model claude-sonnet-4-6` for summarization. Sonnet is used instead of Opus to minimize Q5h impact. If Sonnet is unavailable, change the model in the script.
+The tool defaults to `claude --print --model claude-opus-4-7` for the highest-fidelity summary. Override with the `MANUAL_COMPACT_MODEL` env var — e.g. `MANUAL_COMPACT_MODEL=claude-sonnet-4-6` to minimize Q5h impact, or to point at a different model if Opus is rate-limited or retired.
+
+### Troubleshooting: empty summary output
+
+If `$OUTPUT` comes back empty, the most likely cause is that the extract exceeded the summarizer's context window — this tool runs near the 1M wall, and the relaxed recent-turn caps (active turns up to 8000 chars) make the extract large on exactly those big sessions. The summarizer call swallows stderr, so an oversized-input rejection surfaces as an empty file rather than a visible error. Fixes, in order of preference:
+
+- Use a 1M-window model for the summarization: `MANUAL_COMPACT_MODEL='claude-opus-4-7[1m]' manual-compact.sh ...`
+- Or lower the per-turn caps in the script's extraction block (the `text[:8000]` / `text[:1500]` / `text[:300]` slices).
 
 ## Why the 1M Hack Disables /compact
 

package/tools/manual-compact.sh

@@ -145,31 +145,33 @@ if total == 0:
     sys.exit(1)
 
 # Split into three segments with different detail levels:
-# - First 20%: truncate to 200 chars each (foundational context)
-# - Middle 40%: truncate to 400 chars each (working context)
-# - Last 40%: full text up to 2000 chars each (active work — most important)
+# - First 20%: truncate to 300 chars each (foundational context)
+# - Middle 40%: truncate to 1500 chars each (working context)
+# - Last 40%: full text up to 8000 chars each (active work — most important)
+# Recent-turn caps were relaxed (was 200/400/2000) so the summarizer sees the
+# active work in near-full detail; the stronger model (Opus, below) handles it.
 seg1_end = int(total * 0.2)
 seg2_end = int(total * 0.6)
 
 with open("$EXTRACT", 'w') as f:
     f.write("=== FOUNDATIONAL CONTEXT (early session) ===\n\n")
     for role, text in conversation[:seg1_end]:
-        f.write(f"[{role}]: {text[:200]}\n\n")
+        f.write(f"[{role}]: {text[:300]}\n\n")
 
     f.write("\n=== WORKING CONTEXT (mid session) ===\n\n")
     for role, text in conversation[seg1_end:seg2_end]:
-        f.write(f"[{role}]: {text[:400]}\n\n")
+        f.write(f"[{role}]: {text[:1500]}\n\n")
 
     f.write("\n=== ACTIVE WORK (recent — preserve in full detail) ===\n\n")
     for role, text in conversation[seg2_end:]:
-        f.write(f"[{role}]: {text[:2000]}\n\n")
+        f.write(f"[{role}]: {text[:8000]}\n\n")
 
 import os
 size = os.path.getsize("$EXTRACT")
 print(f"Extracted {total} turns ({size:,} bytes, ~{size//4:,} est. tokens)")
-print(f"  Foundational: {seg1_end} turns (truncated to 200 chars)")
-print(f"  Working: {seg2_end - seg1_end} turns (truncated to 400 chars)")
-print(f"  Active: {total - seg2_end} turns (up to 2000 chars)")
+print(f"  Foundational: {seg1_end} turns (truncated to 300 chars)")
+print(f"  Working: {seg2_end - seg1_end} turns (truncated to 1500 chars)")
+print(f"  Active: {total - seg2_end} turns (up to 8000 chars)")
 PYEOF
 
 # Build the summarization prompt
@@ -199,10 +201,14 @@ ADDITIONAL USER CONTEXT TO PRESERVE:
 $USER_CONTEXT"
 fi
 
+# Summarizer model. Defaults to Opus for highest-fidelity summaries; override
+# with MANUAL_COMPACT_MODEL (e.g. when Opus is rate-limited or retired).
+COMPACT_MODEL="${MANUAL_COMPACT_MODEL:-claude-opus-4-7}"
+
 echo ""
-echo "Sending to Claude for summarization..."
+echo "Sending to Claude ($COMPACT_MODEL) for summarization..."
 
-cat "$EXTRACT" | claude --print --model claude-sonnet-4-6 "$PROMPT" > "$OUTPUT" 2>/dev/null
+cat "$EXTRACT" | claude --print --model "$COMPACT_MODEL" "$PROMPT" > "$OUTPUT" 2>/dev/null
 
 SIZE=$(wc -c < "$OUTPUT")
 echo ""

package/tools/quota-statusline.sh

@@ -115,11 +115,13 @@ def draw_bar(consumed_pct, elapsed_pct, width=BAR_WIDTH):
     # Tick overlays a fill cell when consumed > elapsed, keeping bar width
     # constant — that's what makes the over-pace state legible (┃ inside the
     # filled run) rather than just pushing fill cells around.
-    fill = int(round(max(0, min(100, consumed_pct)) / 100 * width))
+    def to_cells(pct):
+        return int(round(max(0, min(100, pct)) / 100 * width))
+    fill = to_cells(consumed_pct)
     if elapsed_pct is None:
         tick = -1
     else:
-        tick = min(int(max(0, min(100, elapsed_pct)) / 100 * width), width - 1)
+        tick = min(to_cells(elapsed_pct), width - 1)
     cells = []
     remaining = fill
     for i in range(width):