claude-code-cache-fix 3.7.0 → 3.8.0

package/README.md

@@ -29,7 +29,7 @@ That's it. The proxy applies all 7 cache-fix extensions automatically. No wrappe
 
 ### What the proxy does
 
-On every `/v1/messages` request, 7 extensions run in order:
+On every `/v1/messages` request, 9 extensions run in order (one opt-in):
 
 | Extension | What it fixes |
 |-----------|--------------|
@@ -40,6 +40,8 @@ On every `/v1/messages` request, 7 extensions run in order:
 | `fresh-session-sort` | Fixes non-deterministic ordering on first turn |
 | `cache-control-normalize` | Normalizes cache_control markers across messages |
 | `cache-telemetry` | Extracts cache stats from response headers → `~/.claude/quota-status/{account.json,sessions/<id>.json}` |
+| `session-health` | Observes per-session thinking-desync risk (context size + thinking-block count) and warns before a session reaches the danger zone. Read-only |
+| `thinking-block-sanitize` | Drops omitted (empty-text) thinking blocks to head off the CC thinking-desync `400` (#63147). **Opt-in** (`CACHE_FIX_THINKING_SANITIZE=on`) |
 
 Extensions are hot-reloadable — add, remove, or modify `.mjs` files in `proxy/extensions/` and changes apply to the next request without restarting. Configuration in `proxy/extensions.json`.
 
@@ -212,11 +214,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
@@ -713,6 +725,40 @@ Scoping rules baked into the extension:
 |---------|---------|---------|
 | `CACHE_FIX_THINKING_DISPLAY` | `summarized` (built-in) | One of `summarized` / `omitted` / `disabled`. `summarized` restores thinking summaries (default). `omitted` force-suppresses thinking blocks. `disabled` opts the extension out entirely. |
 
+## Session-health early-warning (proxy mode, thinking-desync risk)
+
+Long-running Opus 4.7 `[1m]` sessions accumulate interleaved thinking blocks and grow their live context until Claude Code's own history reconstruction desyncs a thinking-block signature, producing a permanent `400 … thinking blocks … cannot be modified` on every subsequent turn (upstream root cause: [anthropics/claude-code#63147](https://github.com/anthropics/claude-code/issues/63147)). The session dies abruptly with no prior signal.
+
+The `session-health` extension watches the conditions that correlate with the trip and warns **before** a session reaches the danger zone, so the operator can retire it deliberately (write a session-state handoff, `/clear`) instead of being surprised by a dead session. It is **read-only** — it never mutates the request/response body and never attempts to repair the desync (that is CC-side, #63147). It records numeric telemetry into the per-session file (`~/.claude/quota-status/sessions/<id>.json`) on each request and, when a session first crosses into `high` risk, emits a one-time stderr line. Counts only — no thinking text or signatures are ever logged.
+
+Fields added to the per-session JSON:
+
+- `context_tokens` — latest request's live context (`input + cache_read + cache_creation`)
+- `thinking_block_count` — `thinking`/`redacted_thinking` blocks in the latest request
+- `thinking_block_max` — session high-water mark (carried across proxy restarts)
+- `first_seen`, `request_count` — session age + request tally
+- `thinking_desync_risk` — `ok` / `warn` / `high` (omitted when the signal is disabled)
+
+Token thresholds are anchored to the observed ~382K-token trip with margin; the warning is conservative by design — a premature "retire soon" is far cheaper than a dead session. Block-count is recorded but does not yet gate the warning (it activates in a calibrated fast-follow once the failure distribution is known).
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CACHE_FIX_THINKING_RISK_WARN_TOKENS` | `250000` | Context-token level at which `thinking_desync_risk` becomes `warn`. |
+| `CACHE_FIX_THINKING_RISK_HIGH_TOKENS` | `340000` | Context-token level at which risk becomes `high` and the one-time stderr warn fires. |
+| `CACHE_FIX_THINKING_RISK` | unset (on) | Set to `off` to suppress the warning signal (stderr line + `thinking_desync_risk` field). Raw count telemetry keeps recording. |
+
+## Thinking-block sanitize (proxy mode, opt-in, thinking-desync mitigation)
+
+The *mitigate* half of the thinking-desync response (the *warn-before* half is session-health above). On history-replay paths (resume / `--continue` / auto-compaction / parallel-tool-cancel), Claude Code re-sends prior assistant turns' extended thinking in the **omitted** shape `{ "type":"thinking", "thinking":"", "signature":"<intact>" }`. The API rejects modified thinking in the **latest** assistant message with a permanent `400 … thinking … blocks cannot be modified`, which wedges the session on every subsequent turn (upstream root cause: [anthropics/claude-code#63147](https://github.com/anthropics/claude-code/issues/63147)).
+
+The `thinking-block-sanitize` extension drops those omitted blocks — which the API treats as optional history — from the request before it is forwarded. Empirically-resolved turn-selection rule: drop omitted thinking from **all prior assistant turns and the latest assistant turn, unless the latest turn is an active tool-continuation** (its last block is a `tool_use` answered by a following `tool_result`). In that one case the API requires the signed thinking intact and the proxy cannot restore the emptied text, so it leaves the turn untouched. **No env var both preserves thinking and avoids the wedge for that case:** `CLAUDE_CODE_DISABLE_THINKING=1` / `MAX_THINKING_TOKENS=0` stop the wedge only by disabling thinking entirely (lossy — no reasoning), and `DISABLE_INTERLEAVED_THINKING=1` does *not* stop the `400` — so there the answer is don't-resume + heal/retire the session. That is exactly why the proxy mitigation matters: **it is the only path that preserves reasoning while avoiding the wedge** for the history-replay paths it covers. Non-empty thinking is never touched; `redacted_thinking` is out of scope for v1.
+
+**Opt-in.** v1 ships behind `CACHE_FIX_THINKING_SANITIZE=on` (default off): it mutates request bodies and full live-coverage validation is pending. The transform is deterministic and cache-prefix-stable, and emits a per-request `thinking_blocks_dropped` count into the per-session JSON (counts only — never content) that complements the session-health signal.
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CACHE_FIX_THINKING_SANITIZE` | unset (off) | Set to `on` to enable the request-path drop of omitted thinking blocks. Off = no-op (no mutation, no telemetry). |
+
 ## System prompt rewrite (preload mode, optional)
 
 The interceptor can rewrite Claude Code's `# Output efficiency` system-prompt section. Disabled by default. Enable with `CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT`. See [docs/output-efficiency-prompts.md](docs/output-efficiency-prompts.md) for the three known prompt variants and usage instructions.
@@ -763,6 +809,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.8.0",
   "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,
+      }));
+    }
   },
 };

package/proxy/extensions/cache-telemetry.mjs

@@ -49,6 +49,13 @@ export function sessionFilename(rawId) {
   return "inv-" + createHash("sha256").update(s).digest("hex").slice(0, 16);
 }
 
+// Full path to the per-session file for a raw session id. Exported so sibling
+// extensions (e.g. session-health) can READ the prior state this writer wrote,
+// using the identical filename rule — reuse, not duplicate.
+export function sessionFilePath(rawId) {
+  return join(paths().sessionsDir, `${sessionFilename(rawId)}.json`);
+}
+
 function resolveSessionId(headers) {
   if (!headers) return null;
   const sid =
@@ -222,6 +229,13 @@ export default {
             hit_rate: hitRate,
             timestamp,
           },
+          // Additive session-health fields (session-health extension, order
+          // 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.
+          ...(ctx.meta._thinkingSanitize || {}),
           timestamp,
           session_id: rawSid,
         },

package/proxy/extensions/session-health.mjs

@@ -0,0 +1,152 @@
+import { readFileSync } from "node:fs";
+import { sessionFilename, sessionFilePath } from "./cache-telemetry.mjs";
+
+// session-health — read-only early-warning for the CC thinking-desync wedge
+// (anthropics/claude-code#63147). Long-running Opus 4.7 [1m] sessions grow
+// their live context until CC's own history reconstruction desyncs a
+// thinking-block signature, producing a permanent 400 on every subsequent
+// turn. This extension OBSERVES (never mutates the body) and records the
+// conditions that correlate with the trip, plus emits a one-time stderr warn
+// so the operator can retire the session deliberately before it dies.
+//
+// It hands its computed fields to the existing per-session writer
+// (cache-telemetry, order 600) via ctx.meta._sessionHealth; cache-telemetry
+// merges them into the single per-session JSON write. This extension never
+// writes that file itself (single-writer invariant).
+
+const THINKING_TYPES = new Set(["thinking", "redacted_thinking"]);
+
+const DEFAULT_WARN_TOKENS = 250_000;
+const DEFAULT_HIGH_TOKENS = 340_000; // just under the observed ~382K trip
+
+// --- Module-scope state ---
+// Cross-request accumulators, seeded once-per-process from the prior persisted
+// file so first_seen / max / count stay accurate across the proxy restarts
+// that multi-week sessions inevitably span.
+const sessionState = new Map(); // key -> { firstSeen, max, count }
+// Sessions already given the one-time "high" stderr warn this process.
+const warnedSessions = new Set();
+
+function parseTokenEnv(raw, def) {
+  if (raw === undefined || raw === "") return def;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : def;
+}
+
+// Exported for unit testing.
+export function loadConfig(env = process.env) {
+  return {
+    warnTokens: parseTokenEnv(env.CACHE_FIX_THINKING_RISK_WARN_TOKENS, DEFAULT_WARN_TOKENS),
+    highTokens: parseTokenEnv(env.CACHE_FIX_THINKING_RISK_HIGH_TOKENS, DEFAULT_HIGH_TOKENS),
+    enabled: env.CACHE_FIX_THINKING_RISK !== "off",
+  };
+}
+
+export function countThinkingBlocks(body) {
+  if (!body || !Array.isArray(body.messages)) return 0;
+  let n = 0;
+  for (const msg of body.messages) {
+    if (!Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (block && THINKING_TYPES.has(block.type)) n++;
+    }
+  }
+  return n;
+}
+
+export function computeContextTokens(cacheStats) {
+  if (!cacheStats) return 0;
+  return (
+    (cacheStats.inputTokens || 0) +
+    (cacheStats.cacheRead || 0) +
+    (cacheStats.cacheCreation || 0)
+  );
+}
+
+export function computeRisk(contextTokens, { warnTokens, highTokens }) {
+  if (contextTokens >= highTokens) return "high";
+  if (contextTokens >= warnTokens) return "warn";
+  return "ok";
+}
+
+function seedFromFile(rawSid, now) {
+  let prev = null;
+  try {
+    prev = JSON.parse(readFileSync(sessionFilePath(rawSid), "utf8"));
+  } catch {}
+  return {
+    firstSeen: typeof prev?.first_seen === "string" ? prev.first_seen : now,
+    max: Number.isFinite(prev?.thinking_block_max) ? prev.thinking_block_max : 0,
+    count: Number.isFinite(prev?.request_count) ? prev.request_count : 0,
+  };
+}
+
+export default {
+  name: "session-health",
+  description:
+    "Observe per-session thinking-desync risk (context size + thinking-block count) and warn before the session reaches the danger zone. Read-only; never mutates the body.",
+  order: 590, // after request-body mutators (so the count is the forwarded body), before the writer (cache-telemetry, 600)
+
+  async onRequest(ctx) {
+    // Count thinking blocks in the (near-final) forwarded body. Session id is
+    // resolved by cache-telemetry's onRequest (order 600), which runs AFTER
+    // this hook — so we don't read the session id here; we read it in
+    // onStreamEvent, by which time it is set.
+    ctx.meta._thinkingBlockCount = countThinkingBlocks(ctx.body);
+  },
+
+  async onStreamEvent(ctx) {
+    const { event } = ctx;
+    if (!event || event.type !== "message_delta") return;
+    // Once per response, regardless of how many message_delta events arrive.
+    if (ctx.meta._sessionHealthDone) return;
+    ctx.meta._sessionHealthDone = true;
+
+    const now = new Date().toISOString();
+    const rawSid = ctx.meta._sessionId ?? null;
+    const key = sessionFilename(rawSid);
+    const thinkingBlockCount = ctx.meta._thinkingBlockCount || 0;
+    const contextTokens = computeContextTokens(ctx.meta.cacheStats);
+
+    let st = sessionState.get(key);
+    if (!st) {
+      st = seedFromFile(rawSid, now);
+      sessionState.set(key, st);
+    }
+    st.count += 1;
+    st.max = Math.max(st.max, thinkingBlockCount);
+
+    const health = {
+      context_tokens: contextTokens,
+      thinking_block_count: thinkingBlockCount,
+      thinking_block_max: st.max,
+      first_seen: st.firstSeen,
+      request_count: st.count,
+    };
+
+    const cfg = loadConfig();
+    if (cfg.enabled) {
+      const risk = computeRisk(contextTokens, cfg);
+      health.thinking_desync_risk = risk;
+      if (risk === "high" && !warnedSessions.has(key)) {
+        warnedSessions.add(key);
+        const sidLabel = rawSid || "unknown";
+        process.stderr.write(
+          `[session-health] session ${sidLabel} high thinking-desync risk: ` +
+            `context_tokens=${contextTokens} (>= ${cfg.highTokens}), ` +
+            `thinking_block_count=${thinkingBlockCount}. ` +
+            `Consider retiring this session (write SESSION_STATE + /clear).\n`,
+        );
+      }
+    }
+
+    // Hand off to cache-telemetry (order 600) to persist in its single write.
+    ctx.meta._sessionHealth = health;
+  },
+
+  // Test-only: reset module state between tests.
+  __resetForTests() {
+    sessionState.clear();
+    warnedSessions.clear();
+  },
+};

package/proxy/extensions/thinking-block-sanitize.mjs

@@ -0,0 +1,130 @@
+// thinking-block-sanitize — request-path mitigation for the CC thinking-desync
+// wedge (anthropics/claude-code#63147). On replay paths (resume / --continue /
+// auto-compaction / parallel-tool-cancel), CC re-sends prior assistant turns'
+// thinking in the OMITTED shape `{ type:"thinking", thinking:"", signature }`.
+// The API rejects modified thinking in the *latest* assistant message with a
+// permanent 400, which wedges the session. This extension drops the omitted
+// thinking blocks the API treats as optional, before the request is forwarded.
+//
+// Resolved turn-selection rule (directive Open Question 1, empirical capture):
+//   - drop omitted thinking from ALL prior assistant turns, AND
+//   - from the LATEST assistant turn UNLESS it is an active tool-continuation
+//     (last block is a tool_use with a following tool_result) — that case is
+//     uncoverable by the proxy (the API needs the signed thinking for the
+//     pending tool call; we can't restore the emptied text). No env var both
+//     preserves thinking and avoids the wedge there — CLAUDE_CODE_DISABLE_THINKING=1
+//     / MAX_THINKING_TOKENS=0 stop it only by disabling thinking entirely
+//     (lossy); DISABLE_INTERLEAVED_THINKING=1 does NOT stop the 400 — so the
+//     answer for that case is don't-resume + heal/retire.
+// Never touches non-empty thinking, and never touches redacted_thinking (v1).
+//
+// OPT-IN for v1: only runs when CACHE_FIX_THINKING_SANITIZE=on (default off) —
+// it mutates request bodies and its coverage is not yet live-validated.
+//
+// Order 550: after the request-body mutators (ttl-management 500) and before
+// session-health (590), so #160's thinking_block_count reflects the forwarded
+// body. The per-request drop count is exposed via ctx.meta._thinkingSanitize
+// for cache-telemetry (600) to merge into the per-session JSON.
+
+export function isOmittedThinking(block) {
+  return (
+    !!block &&
+    block.type === "thinking" &&
+    typeof block.thinking === "string" &&
+    block.thinking.trim() === ""
+  );
+}
+
+function answersToolUse(msg, toolUseId) {
+  return (
+    !!msg &&
+    Array.isArray(msg.content) &&
+    msg.content.some(
+      (b) => b && b.type === "tool_result" && b.tool_use_id === toolUseId,
+    )
+  );
+}
+
+// The latest assistant message is an active tool-continuation when its terminal
+// block is a `tool_use` that is *paired with* — i.e. answered by — a following
+// `tool_result` carrying the same `tool_use_id`. Only then does the API require
+// that turn's thinking intact, so only then must we leave it untouched. Matching
+// the id (not merely the presence of any later tool_result) keeps the guard as
+// narrow as the approved rule: an unanswered terminal tool_use, or a later
+// tool_result that answers a *different* call, is not the protected case.
+export function isActiveToolContinuation(messages, idx) {
+  const msg = messages[idx];
+  if (!msg || !Array.isArray(msg.content) || msg.content.length === 0) return false;
+  const last = msg.content[msg.content.length - 1];
+  if (!last || last.type !== "tool_use" || !last.id) return false;
+  for (let j = idx + 1; j < messages.length; j++) {
+    if (answersToolUse(messages[j], last.id)) return true;
+  }
+  return false;
+}
+
+function latestAssistantIndex(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i] && messages[i].role === "assistant") return i;
+  }
+  return -1;
+}
+
+// Pure planner: returns { messages, dropped }. Does not mutate the input.
+// `messages` is the new array (a message that loses all content is dropped).
+export function planSanitize(messages) {
+  if (!Array.isArray(messages)) return { messages, dropped: 0 };
+  const latestAsst = latestAssistantIndex(messages);
+  const protectLatest = latestAsst >= 0 && isActiveToolContinuation(messages, latestAsst);
+
+  let dropped = 0;
+  let changed = false;
+  const out = [];
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content)) {
+      out.push(msg);
+      continue;
+    }
+    if (i === latestAsst && protectLatest) {
+      out.push(msg); // active continuation — leave its thinking intact
+      continue;
+    }
+    const kept = msg.content.filter((b) => {
+      if (isOmittedThinking(b)) {
+        dropped++;
+        return false;
+      }
+      return true;
+    });
+    if (kept.length === msg.content.length) {
+      out.push(msg); // unchanged
+    } else if (kept.length === 0) {
+      changed = true; // message became empty → drop it entirely
+    } else {
+      out.push({ ...msg, content: kept });
+      changed = true;
+    }
+  }
+  return { messages: changed ? out : messages, dropped };
+}
+
+export default {
+  name: "thinking-block-sanitize",
+  description:
+    "Drop omitted (empty-text) thinking blocks from prior assistant turns and the latest non-continuation turn, to head off the CC thinking-desync 400 (#63147). Opt-in via CACHE_FIX_THINKING_SANITIZE=on.",
+  order: 550,
+
+  async onRequest(ctx) {
+    if (process.env.CACHE_FIX_THINKING_SANITIZE !== "on") return;
+    const body = ctx.body;
+    if (!body || !Array.isArray(body.messages)) return;
+
+    const { messages, dropped } = planSanitize(body.messages);
+    if (dropped > 0) body.messages = messages;
+
+    // Counts only — never content. Exposed for cache-telemetry to persist and
+    // for the #160 session-health signal.
+    ctx.meta._thinkingSanitize = { thinking_blocks_dropped: dropped };
+  },
+};

package/proxy/extensions/ttl-management.mjs

@@ -10,7 +10,17 @@ function detectRequestType(system) {
   return isSubagent ? "subagent" : "main";
 }
 
+// Thinking and redacted_thinking blocks must be returned to the API byte-identical
+// to the original model response — the API validates them and rejects any
+// modification with "thinking blocks ... cannot be modified" (a 400 on the whole
+// request). On Opus 4.7 interleaved thinking, CC can place a cache_control
+// breakpoint on a thinking block; injecting a ttl there would mutate the block
+// and break the request. Skip them — the marginal TTL benefit on one breakpoint
+// is never worth corrupting a thinking turn.
+const PROTECTED_BLOCK_TYPES = new Set(["thinking", "redacted_thinking"]);
+
 function injectTtl(block, ttlParam) {
+  if (block && PROTECTED_BLOCK_TYPES.has(block.type)) return block;
   if (block.cache_control?.type === "ephemeral" && !block.cache_control.ttl) {
     return { ...block, cache_control: { ...block.cache_control, ttl: ttlParam } };
   }

package/proxy/extensions.json

@@ -1,20 +1,82 @@
 {
-  "bootstrap-defense": { "enabled": true, "order": 45 },
-  "ttl-tier-detect": { "enabled": true, "order": 75 },
-  "fingerprint-strip": { "enabled": true, "order": 100 },
-  "image-strip": { "enabled": true, "order": 150 },
-  "sort-stabilization": { "enabled": true, "order": 200 },
-  "fresh-session-sort": { "enabled": true, "order": 250 },
-  "identity-normalization": { "enabled": true, "order": 300 },
-  "smoosh-split": { "enabled": true, "order": 320 },
-  "content-strip": { "enabled": true, "order": 330 },
-  "tool-input-normalize": { "enabled": true, "order": 340 },
-  "microcompact-stability": { "enabled": true, "order": 350 },
-  "thinking-display": { "enabled": true, "order": 360 },
-  "cache-control-normalize": { "enabled": true, "order": 400 },
-  "messages-cache-breakpoint": { "enabled": true, "order": 410 },
-  "ttl-management": { "enabled": true, "order": 500 },
-  "cache-telemetry": { "enabled": true, "order": 600 },
-  "overage-warning": { "enabled": true, "order": 610 },
-  "request-log": { "enabled": false, "order": 700 }
+  "bootstrap-defense": {
+    "enabled": true,
+    "order": 45
+  },
+  "ttl-tier-detect": {
+    "enabled": true,
+    "order": 75
+  },
+  "fingerprint-strip": {
+    "enabled": true,
+    "order": 100
+  },
+  "image-strip": {
+    "enabled": true,
+    "order": 150
+  },
+  "sort-stabilization": {
+    "enabled": true,
+    "order": 200
+  },
+  "fresh-session-sort": {
+    "enabled": true,
+    "order": 250
+  },
+  "identity-normalization": {
+    "enabled": true,
+    "order": 300
+  },
+  "smoosh-split": {
+    "enabled": true,
+    "order": 320
+  },
+  "content-strip": {
+    "enabled": true,
+    "order": 330
+  },
+  "tool-input-normalize": {
+    "enabled": true,
+    "order": 340
+  },
+  "microcompact-stability": {
+    "enabled": true,
+    "order": 350
+  },
+  "thinking-display": {
+    "enabled": true,
+    "order": 360
+  },
+  "cache-control-normalize": {
+    "enabled": true,
+    "order": 400
+  },
+  "messages-cache-breakpoint": {
+    "enabled": true,
+    "order": 410
+  },
+  "ttl-management": {
+    "enabled": true,
+    "order": 500
+  },
+  "cache-telemetry": {
+    "enabled": true,
+    "order": 600
+  },
+  "overage-warning": {
+    "enabled": true,
+    "order": 610
+  },
+  "request-log": {
+    "enabled": false,
+    "order": 700
+  },
+  "usage-log": {
+    "enabled": true,
+    "order": 650
+  },
+  "rate-limit-log": {
+    "enabled": true,
+    "order": 660
+  }
 }