claude-code-cache-fix 3.7.0 → 3.7.1

package/README.md

@@ -212,11 +212,21 @@ Options (all optional; all fall back to the same env vars used by the CLI):
 
 **Cache-economics regressions.** The original purpose of cache-fix is to absorb the cache-handling behaviors in Claude Code that cost users real money and quota — TTL downgrades, cache-breaking header churn, identity-latching issues, and the rest of the regression catalog documented across our issue history. The proxy sits between CC and the Anthropic API, normalizes the request and response stream, and emits enough observability (via statusline integration and the quota-status files) that users can see what their session is actually doing. This is the load-bearing feature for almost every user today.
 
-**Bootstrap-channel observability.** Claude Code v2.1.150 introduced a prompt-section consumer that fetches a server-supplied string from `/api/claude_cli/bootstrap` and merges it into the agent's behavioral-instructions prompt path. We filed this behavior with Anthropic's security team in May 2026; Anthropic closed the report as *Informative*, treating TLS as the transport-integrity boundary and declining to add application-layer authenticity checks. Cache-fix v3.7.0 adds explicit handling for this path. Default mode is `audit` — bootstrap responses proxy through to CC and are logged to `~/.claude/cache-fix-bootstrap-log.jsonl` so users can inspect them locally. To opt into block mode instead, set `CACHE_FIX_BOOTSTRAP_MODE=block` in the proxy environment; block mode short-circuits the upstream call and returns a 200 with an empty JSON body, dropping bootstrap content before it reaches CC. (Note: cache-fix v3.6.2 and earlier returned 404 for this path because the proxy router did not include it — the practical effect was that bootstrap content was not previously reaching CC for cache-fix users. v3.7.0's default `audit` changes that behavior; explicit `CACHE_FIX_BOOTSTRAP_MODE=block` preserves it.) The full disclosure record, including Anthropic's verbatim close text, is in [`docs/disclosure/heron-brook-2026-05.md`](docs/disclosure/heron-brook-2026-05.md).
+**Bootstrap-channel observability.** Claude Code v2.1.150 introduced a prompt-section consumer that fetches a server-supplied string from `/api/claude_cli/bootstrap` and merges it into the agent's behavioral-instructions prompt path. We filed this behavior with Anthropic's security team in May 2026; Anthropic closed the report as *Informative*, treating TLS as the transport-integrity boundary and declining to add application-layer authenticity checks. Cache-fix v3.7.0 added explicit handling for this path. v3.7.1 extends it to also cover the env-var-selected GrowthBook prompt-injection surface that landed in CC v2.1.152 (remote-control mode: `CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE` names a flag key whose cached value is used as the system prompt body).
+
+Cache-fix's `bootstrap-defense` extension ships three modes, selected via `CACHE_FIX_BOOTSTRAP_MODE`:
+
+| Mode | Default? | Behavior |
+|---|---|---|
+| `audit` | yes | Bootstrap responses proxy through to CC. Each response is logged to `~/.claude/cache-fix-bootstrap-log.jsonl` with surface metadata: which prompt-source surfaces fired (`tengu_heron_brook` legacy and/or env-var-selected), the SHA-256 hash of the value (first 16 hex chars — never the value itself), and the `CLAUDE_CODE_REMOTE` flag. Multi-surface responses emit one record per surface, correlated by `request_id` + timestamp window. |
+| `block` | opt-in | `onRequest` returns a 200 with an empty JSON body. Upstream is never called, no flag map ever reaches the on-disk GrowthBook cache. Defeats both legacy and env-var-selected injection surfaces. |
+| `allowlist` | opt-in (experimental) | Bootstrap response proxies through, but prompt-source-eligible keys (legacy `tengu_heron_brook` + env-var-selected key) not in the allowlist are stripped from the response body before it reaches CC. Default allowlist is `tengu_heron_brook` (the only known-legitimate historical key); configure via `CACHE_FIX_BOOTSTRAP_ALLOWED_KEYS=comma,separated,list`. Pass `CACHE_FIX_BOOTSTRAP_ALLOWED_KEYS=` (explicit empty) for full deny-all. Other GrowthBook flag keys pass through untouched. May need updates if Anthropic adds legitimate prompt-source keys in future CC releases. |
+
+Note: cache-fix v3.6.2 and earlier returned 404 for the bootstrap path because the proxy router did not include it — the practical effect was that bootstrap content was not reaching CC for cache-fix users. v3.7.0's default `audit` changes that behavior; explicit `CACHE_FIX_BOOTSTRAP_MODE=block` preserves it. The full disclosure record, including Anthropic's verbatim close text, is in [`docs/disclosure/heron-brook-2026-05.md`](docs/disclosure/heron-brook-2026-05.md).
 
 **Reference material:**
 - [`docs/disclosure/heron-brook-2026-05.md`](docs/disclosure/heron-brook-2026-05.md) — full disclosure record
-- [`CHANGELOG.md`](CHANGELOG.md#370---2026-05-26) — v3.7.0 release entry (includes the behavior-change note for prior users)
+- [`CHANGELOG.md`](CHANGELOG.md#371---2026-05-27) — v3.7.1 release entry (extended surface coverage + allowlist mode); [v3.7.0 entry](CHANGELOG.md#370---2026-05-26) covers the prior behavior-change note
 - [`cnighswonger/heron-brook-poc`](https://github.com/cnighswonger/heron-brook-poc) — reproducer for the bootstrap-channel behavior
 
 ## Recommended CC operational config
@@ -763,6 +773,7 @@ We monitor 30+ upstream Claude Code issues related to cache, quota, and context
 - **[@deafsquad](https://github.com/deafsquad)** — Universal smoosh_split un-smoosh fix (PR #26), source-level function attribution of resume scatter bug (anthropics/claude-code#43657), OTEL telemetry discovery, proposed and built proxy architecture for v3.0.0
 - **[@vmfarms](https://github.com/vmfarms)** — Concurrent multi-runner production validation, surfaced proxy-mode resume-marker regex no-op (#96), TTL tier detection gap (#97), and image-strip stderr leak (#98)
 - **[@ojura](https://github.com/ojura)** — Opus 4.7 thinking-summaries root-cause analysis: filed [anthropics/claude-code#59844](https://github.com/anthropics/claude-code/issues/59844) with the CLI-binary decode (`!getIsNonInteractiveSession()` gate at offset 230510599 in v2.1.142) and the two-stacked-special-cases framing, which made the `thinking-display` extension (v3.6.1) a clean proxy-side complement to the proposed upstream fix
+- **[@schuay](https://github.com/schuay)** — `quota-statusline.sh` enhancements: 10-cell quota bar with elapsed-time tick and exhaust-vs-reset projection replacing the prior `%/min` burn-rate display (PR #140, v3.6.2), and d/h vs h/m time-format autoselect plus named time-unit and burn-warmup constants (PR #143, v3.7.0)
 
 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,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.7.0",
+  "version": "3.7.1",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": {

package/proxy/extensions/bootstrap-defense.mjs

@@ -1,10 +1,13 @@
 import { appendFileSync, statSync, renameSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 
 const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
-const SCHEMA_VERSION = 1;
-const EXTENSION_VERSION = "v3.6.3";
+const SCHEMA_VERSION = 2;
+const EXTENSION_VERSION = "v3.7.1";
+
+const LEGACY_PROMPT_KEY = "tengu_heron_brook";
 
 function logPath() {
   return process.env.CACHE_FIX_BOOTSTRAP_LOG_PATH || join(homedir(), ".claude", "cache-fix-bootstrap-log.jsonl");
@@ -40,19 +43,43 @@ function appendRecord(record) {
 
 function modeFromEnv(fallback) {
   const raw = process.env.CACHE_FIX_BOOTSTRAP_MODE;
-  if (raw === "audit" || raw === "block") return raw;
+  if (raw === "audit" || raw === "block" || raw === "allowlist") return raw;
   return fallback;
 }
 
+// Parse the allowlist env var. Distinguishes three states:
+//   - var unset            → default allowlist [LEGACY_PROMPT_KEY]
+//   - var = "" (explicit)  → empty allowlist (deny-all)
+//   - var = "a,b,c"        → [a, b, c] (trimmed, empty entries dropped)
+function allowedKeysFromEnv() {
+  const raw = process.env.CACHE_FIX_BOOTSTRAP_ALLOWED_KEYS;
+  if (raw === undefined) return new Set([LEGACY_PROMPT_KEY]);
+  if (raw === "") return new Set();
+  return new Set(raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0));
+}
+
+// Hash derivation contract (directive § Hash derivation): first 16 chars of
+// the lowercase hex SHA-256 digest over the UTF-8-encoded flag value. Pinned
+// here so a future refactor cannot silently change historical-record identity.
+function hashFlagValue(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex").slice(0, 16);
+}
+
 // PII discipline: the audit log MUST NOT include client headers (Authorization,
 // x-api-key, cookies, etc.) or request/response bodies. Callers pass only the
 // extracted scalar fields below — the full headers object is never threaded
 // through this function, so a future maintainer can't accidentally widen the
 // log surface by spreading the parameter object.
 //
-// v3.7.0 extension fields are emitted as null/defaulted so log readers don't
-// break when v3.7.0 starts populating baseline_hash, anomaly_status, etc.
-function recordShape({ phase, mode, status, body_bytes, upstream_host, request_id, error }) {
+// v3.7.0 extension fields (baseline_hash, anomaly_status) are emitted as null
+// so log readers from that schema don't break. v3.7.1 adds the prompt-source
+// surface fields (surface, prompt_key, prompt_value_hash, remote_mode,
+// stripped_keys) — consumers reading v1 records should treat these as
+// null/empty array.
+function recordShape({
+  phase, mode, status, body_bytes, upstream_host, request_id, error,
+  surface, prompt_key, prompt_value_hash, remote_mode, stripped_keys,
+}) {
   return {
     schema_version: SCHEMA_VERSION,
     extension_version: EXTENSION_VERSION,
@@ -66,6 +93,11 @@ function recordShape({ phase, mode, status, body_bytes, upstream_host, request_i
     baseline_hash: null,
     anomaly_status: null,
     error: error ?? null,
+    surface: surface ?? "bootstrap",
+    prompt_key: prompt_key ?? null,
+    prompt_value_hash: prompt_value_hash ?? null,
+    remote_mode: remote_mode ?? false,
+    stripped_keys: stripped_keys ?? [],
   };
 }
 
@@ -94,10 +126,32 @@ function extractAuditFields(meta, headers) {
   };
 }
 
+// Surface-activation logic (directive § Multi-surface records):
+//   - "bootstrap" surface fires when the legacy hardcoded key is in the body.
+//   - "prompt_injection_gb" surface fires when CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE
+//     is set, independent of whether that named key is in the body — this gives
+//     the audit log operator-visibility into env-configured intent even when
+//     the upstream did not deliver the value.
+function detectSurfaces(body) {
+  const surfaces = [];
+  const bodyIsObject = body !== null && typeof body === "object" && !Array.isArray(body);
+  if (bodyIsObject && Object.prototype.hasOwnProperty.call(body, LEGACY_PROMPT_KEY)) {
+    surfaces.push({ surface: "bootstrap", prompt_key: LEGACY_PROMPT_KEY });
+  }
+  const envKey = process.env.CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE;
+  if (envKey) {
+    surfaces.push({ surface: "prompt_injection_gb", prompt_key: envKey });
+  }
+  return surfaces;
+}
+
 export default {
   name: "bootstrap-defense",
   description:
-    "Audit (default) or block /api/claude_cli/bootstrap traffic. Audit mode proxies the response through to CC and logs metadata to ~/.claude/cache-fix-bootstrap-log.jsonl. Block mode returns empty 200, preserving v3.6.2's de-facto behavior in explicit form.",
+    "Audit (default), block, or allowlist server-controlled system-prompt injection through /api/claude_cli/bootstrap. " +
+    "Covers both the legacy tengu_heron_brook reader and the env-var-selected (CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE) reader. " +
+    "Audit mode logs surface metadata to ~/.claude/cache-fix-bootstrap-log.jsonl. Block mode returns empty 200 from onRequest. " +
+    "Allowlist mode strips non-allowlisted prompt-source-eligible keys from the response body before returning it to CC.",
   // Pipeline route scoping (pipeline.mjs:appliesToRoute) gates this extension
   // to the bootstrap path. The internal route guard below is belt-and-suspenders
   // in case a caller invokes the hook directly.
@@ -116,6 +170,7 @@ export default {
           phase: "request_blocked",
           mode,
           ...extractAuditFields(ctx.meta, ctx.headers),
+          remote_mode: Boolean(process.env.CLAUDE_CODE_REMOTE),
         }),
       );
       return {
@@ -130,7 +185,7 @@ export default {
   async onResponse(ctx) {
     if (ctx.meta?.route !== "bootstrap") return;
     const mode = ctx.meta._bootstrapDefenseMode || "audit";
-    if (mode !== "audit") return;
+    if (mode !== "audit" && mode !== "allowlist") return;
 
     // Prefer raw on-wire byte count from server.mjs (accurate even for
     // non-JSON / unparseable upstream responses). The fallback stringify path
@@ -142,20 +197,90 @@ export default {
     }
 
     const upstreamError = ctx.meta?._bootstrapUpstreamError ?? null;
-    // Request-side context (request_id, upstream_host) is captured at
-    // forward time and stashed on ctx.meta — we read from meta here rather
-    // than ctx.headers (which on onResponse contains the upstream RESPONSE
-    // headers, not the client request).
-    appendRecord(
-      recordShape({
-        phase: upstreamError ? "upstream_error_audited" : "response_audited",
-        mode,
-        status: ctx.status,
-        body_bytes: bodyBytes,
-        upstream_host: ctx.meta?._bootstrapUpstreamHost ?? null,
-        request_id: ctx.meta?._bootstrapRequestId ?? null,
+    const auditFields = extractAuditFields(ctx.meta, ctx.headers);
+    const remoteMode = Boolean(process.env.CLAUDE_CODE_REMOTE);
+    const baseRecord = {
+      mode,
+      status: ctx.status,
+      body_bytes: bodyBytes,
+      ...auditFields,
+      remote_mode: remoteMode,
+    };
+
+    // Anomaly path: upstream error or unparseable body. Single record with
+    // new fields defaulted; no multi-surface emission (directive § Multi-surface
+    // records, last paragraph).
+    if (upstreamError) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "upstream_error_audited",
         error: upstreamError,
-      }),
-    );
+      }));
+      return;
+    }
+    if (ctx.body === null || ctx.body === undefined) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "response_audited",
+      }));
+      return;
+    }
+
+    // Detect which prompt-source surfaces apply to this response.
+    const surfaces = detectSurfaces(ctx.body);
+
+    // No injection-detected baseline: single record preserving v3.7.0's
+    // record shape (surface defaults to "bootstrap", prompt_key null).
+    if (surfaces.length === 0) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "response_audited",
+      }));
+      return;
+    }
+
+    // Compute per-surface fields. Read from the original (unmutated) body
+    // for every surface BEFORE applying any allowlist strips, so multiple
+    // surfaces referencing the same key (env-var-aliases-legacy-key) both
+    // see the same value and emit identical prompt_value_hash.
+    const allowed = mode === "allowlist" ? allowedKeysFromEnv() : null;
+    const perSurface = surfaces.map((s) => {
+      const value = ctx.body[s.prompt_key];
+      const hash = typeof value === "string" ? hashFlagValue(value) : null;
+      const stripThis =
+        mode === "allowlist" &&
+        !allowed.has(s.prompt_key) &&
+        Object.prototype.hasOwnProperty.call(ctx.body, s.prompt_key);
+      return {
+        ...s,
+        prompt_value_hash: hash,
+        stripped_keys: stripThis ? [s.prompt_key] : [],
+      };
+    });
+
+    // Apply strips to ctx.body. Deletion is idempotent across multiple
+    // surfaces that target the same key (alias case).
+    if (mode === "allowlist") {
+      for (const r of perSurface) {
+        for (const k of r.stripped_keys) {
+          delete ctx.body[k];
+        }
+      }
+    }
+
+    // Emit one audit record per detected surface. Shared scalars
+    // (request_id, timestamp window, body_bytes, etc.) are duplicated across
+    // records emitted from a single response; consumers correlate by
+    // request_id + timestamp window.
+    for (const r of perSurface) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "response_audited",
+        surface: r.surface,
+        prompt_key: r.prompt_key,
+        prompt_value_hash: r.prompt_value_hash,
+        stripped_keys: r.stripped_keys,
+      }));
+    }
   },
 };