claude-code-cache-fix 3.8.0 → 4.0.0

package/bin/claude-via-proxy.mjs

@@ -55,6 +55,7 @@ async function dispatch() {
         "  CACHE_FIX_PROXY_PORT     Port for the proxy server\n" +
         "  CACHE_FIX_PROXY_UPSTREAM Upstream URL\n" +
         "  CACHE_FIX_DEBUG=1        Verbose proxy logging\n" +
+        "  CACHE_FIX_HOT_RELOAD=on  Enable in-process extension hot-reload (off by default; see #196)\n" +
         "  CACHE_FIX_CLAUDE_CMD     Override the `claude` command for the wrapper\n",
     );
     return 0;

package/bin/install-service.mjs

@@ -23,6 +23,11 @@ function getDefaults() {
     port: validatePort(process.env.CACHE_FIX_PROXY_PORT || "9801"),
     upstream: process.env.CACHE_FIX_PROXY_UPSTREAM || "",
     debug: process.env.CACHE_FIX_DEBUG || "",
+    // Hot-reload is opt-in as of v4.0.0 (#196). Capture from env at install
+    // time so the operator can bake `CACHE_FIX_HOT_RELOAD=on` into the
+    // generated unit/plist via `CACHE_FIX_HOT_RELOAD=on cache-fix-proxy
+    // install-service`. Strict "on" match — anything else renders nothing.
+    hotReload: process.env.CACHE_FIX_HOT_RELOAD === "on" ? "on" : "",
     workingDir: resolve(__dirname, ".."),
   };
 }
@@ -93,6 +98,9 @@ function renderSystemdTemplate(template, vars) {
   const debugLine = vars.debug
     ? `Environment=CACHE_FIX_DEBUG=${vars.debug}`
     : "";
+  const hotReloadLine = vars.hotReload
+    ? `Environment=CACHE_FIX_HOT_RELOAD=${vars.hotReload}`
+    : "";
   // Allow callers to wire a Requires= line (e.g. another service the proxy
   // chains to). Empty string by default so the unit has no extra deps.
   const requiresLine = vars.requires
@@ -104,6 +112,7 @@ function renderSystemdTemplate(template, vars) {
     .replaceAll("{{PORT}}", vars.port)
     .replaceAll("{{UPSTREAM_LINE}}", upstreamLine)
     .replaceAll("{{DEBUG_LINE}}", debugLine)
+    .replaceAll("{{HOT_RELOAD_LINE}}", hotReloadLine)
     .replaceAll("{{REQUIRES_LINE}}", requiresLine)
     .replaceAll("{{WORKING_DIR}}", vars.workingDir)
     // Collapse triple newlines from empty optional lines down to single blank
@@ -117,12 +126,16 @@ function renderLaunchdTemplate(template, vars) {
   const debugPlist = vars.debug
     ? `        <key>CACHE_FIX_DEBUG</key>\n        <string>${vars.debug}</string>`
     : "";
+  const hotReloadPlist = vars.hotReload
+    ? `        <key>CACHE_FIX_HOT_RELOAD</key>\n        <string>${vars.hotReload}</string>`
+    : "";
   return template
     .replaceAll("{{NODE}}", vars.node)
     .replaceAll("{{SERVER_PATH}}", vars.serverPath)
     .replaceAll("{{PORT}}", vars.port)
     .replaceAll("{{UPSTREAM_PLIST}}", upstreamPlist)
     .replaceAll("{{DEBUG_PLIST}}", debugPlist)
+    .replaceAll("{{HOT_RELOAD_PLIST}}", hotReloadPlist)
     .replaceAll("{{WORKING_DIR}}", vars.workingDir)
     .replaceAll("{{LOG_DIR}}", vars.logDir)
     .replace(/\n\n+/g, "\n");
@@ -176,6 +189,7 @@ async function installSystemd({ paths, defaults, force = false } = {}) {
     port: defaults.port,
     upstream: defaults.upstream,
     debug: defaults.debug,
+    hotReload: defaults.hotReload,
     workingDir: defaults.workingDir,
     requires: "",
   });
@@ -275,6 +289,7 @@ async function installLaunchd({ paths, defaults, force = false } = {}) {
     port: defaults.port,
     upstream: defaults.upstream,
     debug: defaults.debug,
+    hotReload: defaults.hotReload,
     workingDir: defaults.workingDir,
     logDir: paths.logDir,
   });

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": "4.0.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

@@ -56,7 +56,12 @@ export function sessionFilePath(rawId) {
   return join(paths().sessionsDir, `${sessionFilename(rawId)}.json`);
 }
 
-function resolveSessionId(headers) {
+// Exported so sibling extensions can read the canonical session id from
+// REQUEST headers at their own onRequest time — they can't rely on
+// ctx.meta._sessionId being set, because this writer's onRequest is the
+// thing that populates it (and runs at order 600, after most extensions).
+// thinking-block-sanitize v2 (order 550) uses this for the same reason.
+export function resolveSessionId(headers) {
   if (!headers) return null;
   const sid =
     headers["x-claude-code-session-id"] ||
@@ -233,9 +238,21 @@ export default {
           // 590, stashes these before this writer runs). Optional — absent if
           // that extension is disabled or produced nothing this request.
           ...(ctx.meta._sessionHealth || {}),
-          // Additive thinking-block-sanitize drop count (order 550, opt-in).
-          // Optional — absent unless CACHE_FIX_THINKING_SANITIZE=on.
+          // Additive thinking-block-sanitize drop count (order 550). On by
+          // default since v4.0.0; present (possibly with thinking_blocks_dropped:0)
+          // whenever sanitize ran. Absent when CACHE_FIX_THINKING_SANITIZE=off
+          // or when the extension returned early before reaching the planner
+          // (e.g., body.messages not an array).
           ...(ctx.meta._thinkingSanitize || {}),
+          // Additive thinking-block-sanitize v2 fields (order 550, opt-in via
+          // CACHE_FIX_THINKING_SANITIZE=v2). Optional — absent unless v2 is
+          // enabled. Keys: thinking_blocks_dropped_v2 / tools_hash_baseline.
+          ...(ctx.meta._thinkingSanitizeV2 || {}),
+          // 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/proxy/extensions/signature-surface-hash.mjs

@@ -0,0 +1,60 @@
+// signature-surface-hash — hash helper for thinking-block-sanitize v2.
+//
+// Computes a deterministic 16-hex-char fingerprint of the inputs that
+// participate in the API's thinking-block signature: the tools surface,
+// and (forward-compat) optionally the system block or anthropic-beta
+// header value.
+//
+// v2 only passes `{ tools }`. The signature is left forward-compatible so
+// a future v3 directive can extend coverage without renaming this helper.
+//
+// Canonicalization rules (per directive proxy-thinking-block-sanitize-v2.md):
+//   - Each tool object: recursive stable JSON stringify with recursive key
+//     sorting at every nesting level. Nested JSON-schema objects (in
+//     input_schema, parameters, etc.) have their own keys, which also
+//     sort stably.
+//   - Preserve tools[] array order. Reordering tools changes which slot
+//     which tool occupies in the API's view; the hash MUST reflect that.
+//     (Note: sort-stabilization at order 200 currently locks the array
+//     order before v2 fires, so this rule is forward-compatibility against
+//     any future change in upstream ordering.)
+//   - Sentinel for empty/absent: if tools is undefined, null, or [], the
+//     hash input is the literal string "none". Rules out collision with
+//     other empty-shaped inputs in a future extension.
+//
+// Output: sha256(canonical_input).slice(0, 16) — 16 hex chars matches the
+// existing _sessionHealth / _thinkingSanitize precedent for in-JSON identifiers.
+
+import { createHash } from "node:crypto";
+
+// Recursive stable stringify: object keys sort, arrays preserve order,
+// primitives go through JSON.stringify as-is. Handles nested objects and
+// arrays to arbitrary depth.
+export function canonicalStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalStringify).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  const parts = keys.map((k) => JSON.stringify(k) + ":" + canonicalStringify(value[k]));
+  return "{" + parts.join(",") + "}";
+}
+
+// Compute the signature-surface hash. v2 passes only { tools }; system and
+// anthropic_beta are reserved for future versions.
+export function computeSignatureSurfaceHash({ tools, system, anthropic_beta } = {}) {
+  // Empty/absent tools → "none" sentinel (not the canonical-stringify of [],
+  // which would be "[]" and could collide with other empty-shaped inputs).
+  const toolsPart =
+    tools == null || (Array.isArray(tools) && tools.length === 0)
+      ? "none"
+      : canonicalStringify(tools);
+  // Reserved inputs — passed by future versions; v2 always omits them, so
+  // they contribute nothing to the hash today. Kept in the signature so
+  // existing call sites don't need to change when v3 adds them.
+  void system;
+  void anthropic_beta;
+  return createHash("sha256").update(toolsPart).digest("hex").slice(0, 16);
+}