claude-code-cache-fix 3.6.1 → 3.6.2

package/README.md

@@ -208,6 +208,40 @@ Options (all optional; all fall back to the same env vars used by the CLI):
 
 *The embeddable factory was contributed by [@bilby91](https://github.com/bilby91) at [Crunchloop DAP](https://dap.crunchloop.ai) — see [PR #123](https://github.com/cnighswonger/claude-code-cache-fix/pull/123).*
 
+## Recommended CC operational config
+
+The proxy fixes what it can fix at the request layer. A handful of CC client-side env vars and `~/.claude/settings.json` knobs solve adjacent problems the proxy can't reach — silent model swaps on CC update, ambiguous model fallback, schema-strip side effects. Surfacing these here as a recommendation; users decide their own config.
+
+These findings come from [@fgrosswig](https://github.com/fgrosswig)'s binary analysis of CC v2.1.91. Methodology is public PowerShell + ASCII string extraction; he shared the resulting punch list privately as a courtesy.
+
+### Suggested `~/.claude/settings.json` env block
+
+The model IDs below are illustrative — replace with your preferred main and small-fast models. The point is that pinning *something* explicit beats relying on CC's defaults.
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP": "1",
+    "ANTHROPIC_MODEL": "claude-opus-4-7",
+    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001"
+  }
+}
+```
+
+**`CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP=1`** — single most impactful flag. CC has a legacy code path that silently remaps your pinned model to a different one after certain version updates. Setting this to `1` disables the remap; the model you pin is the model you get. (If you don't pin, CC's defaults apply as usual.)
+
+**`ANTHROPIC_MODEL`** — pins the primary model. Keeping this explicit means the cache prefix hash stays stable across CC version bumps that would otherwise swap your default. Adjust to whichever model you actually want.
+
+**`ANTHROPIC_SMALL_FAST_MODEL`** — pins the side-channel "fast" model CC uses for short auxiliary calls (e.g., title generation, classification). Without an explicit pin, this can silently fall back to a different family on update.
+
+### `autoCompactWindow=1000000` caveat
+
+If you've seen the `autoCompactWindow: 1000000` setting recommended elsewhere: it only takes effect when the active model qualifies for 1M-context (currently `claude-sonnet-4-6` or `claude-opus-4-6` with the appropriate beta header). Without those preconditions it caps at the hardcoded 200K regardless of what you set.
+
+### `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` schema-strip side effect
+
+If you set this flag, CC strips any tool field outside `["name", "description", "input_schema", "cache_control"]` from outgoing requests. Custom tools relying on `defer_loading` or `eager_input_streaming` will silently lose those fields and behave differently. Worth knowing before turning the flag on.
+
 ## Quick Start: Preload (CC v2.1.112 and earlier)
 
 If you're on a Node.js-based CC version (v2.1.112 or earlier), the preload interceptor works without a proxy:
@@ -246,7 +280,7 @@ For manual VS Code wrapper setup (without the VSIX), see [docs/preload-setup.md]
 
 **What it does NOT do:** No network calls from the proxy or interceptor. All telemetry is written to local files under `~/.claude/`. No data leaves your machine.
 
-**Supply chain:** Proxy mode: 7 small extension modules in `proxy/extensions/` (each under 200 lines). Preload mode: single unminified file (`preload.mjs`, ~1,700 lines). One dev dependency (`zod` for schema validation in tests only). Review before installing. npm provenance links each published version to its source commit.
+**Supply chain:** Proxy mode: 7 small extension modules in `proxy/extensions/` (each under 200 lines). Preload mode: single unminified file (`preload.mjs`, ~1,700 lines). One dev dependency (`zod` for schema validation in tests only). Review before installing. Published builds carry npm's default registry signatures; sigstore provenance attestation is not currently published — tracked as a follow-up.
 
 **Independent audit:** [Assessed as "LEGITIMATE TOOL"](https://github.com/anthropics/claude-code/issues/38335#issuecomment-4244413605) by @TheAuditorTool (2026-04-14).
 
@@ -323,13 +357,23 @@ The interceptor can only *help* or *do nothing*. It cannot make things worse.
 
 Both modes write quota state on every API call. Proxy mode (v3.5.0+) splits into `~/.claude/quota-status/account.json` (account-global fields: Q5h/Q7d, status, overage) plus `~/.claude/quota-status/sessions/<id>.json` (per-session cache fields: TTL tier, hit rate). Preload mode keeps the legacy `~/.claude/quota-status.json` (single-session by construction). The included `tools/quota-statusline.sh` script displays a live status line showing:
 
-- **Q5h %** with burn rate (%/min)
-- **Q7d %** with burn rate (%/hr)
+- **Q5h** quota bar `[███░┃░░░░░]` + percent + `(exhaust X, reset Y)`. Filled cells are consumed quota; the heavy-vertical tick is wall-clock elapsed position in the window. Tick to the right of the fill = under pace; tick inside the fill = burning faster than time (over pace). `exhaust` is the projected time-to-100% at the current burn rate; `reset` is the wall-clock time until the window rolls over. When `exhaust < reset`, you will hit 100% before the window resets — back off.
+- **Q7d** same shape with day-scale durations (e.g. `(exhaust 3d 13h, reset 3d 0h)`).
 - **TTL tier** — `TTL:1h` when healthy, **`TTL:5m` in red when the server has downgraded you** (typically at Q5h ≥ 100%)
 - **PEAK** in yellow during weekday peak hours (13:00–19:00 UTC)
 - **Cache hit rate %**
 - **OVERAGE** flag when active
 
+Example line (mid-window, healthy state):
+
+```
+Q5h [███░┃░░░░░] 30% (exhaust 4h40m, reset 3h00m) | Q7d [█████┃░░░░] 53% (exhaust 3d 13h, reset 3d 0h) | TTL:1h 98.3%
+```
+
+The `(exhaust …, reset …)` suffix is dropped piecewise when projection isn't meaningful: at 0% (fresh window) and 100% (already exhausted) only `reset` is shown; in the first minute (Q5h) or six minutes (Q7d) after window start the burn rate isn't stable enough to project, so `exhaust` is held back until then; a stale `resets_at` (the server-reported value sits in the past, before the next API call refreshes it) drops both.
+
+The bar uses Unicode block characters (`█┃░`) — most modern terminals render these correctly. If your terminal substitutes boxes or replacement glyphs, configure a Unicode-capable font (any DejaVu, Fira, Iosevka, JetBrains Mono, etc.).
+
 ### Setup
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.6.1",
+  "version": "3.6.2",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": {

package/proxy/extensions.json

@@ -1,19 +1,70 @@
 {
-  "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 }
+  "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
+  }
 }

package/tools/quota-statusline.sh

@@ -41,7 +41,7 @@ fi
 # through os.environ, never via a shell-substituted string.
 result=$(python3 <<'PYEOF' 2>/dev/null
 import sys, json, os, re, hashlib
-from datetime import datetime, timezone, timedelta
+from datetime import datetime, timezone
 
 home = os.path.expanduser('~')
 account_path = os.path.join(home, '.claude', 'quota-status', 'account.json')
@@ -98,28 +98,76 @@ ts = sess.get('timestamp') or acc.get('timestamp', '')
 
 now = datetime.fromisoformat(ts.replace('Z', '+00:00')) if ts else datetime.now(timezone.utc)
 
-# Q5h burn rate
-rate5 = ''
-if q5h_reset > 0 and q5h > 0:
-    window_start = datetime.fromtimestamp(q5h_reset, tz=timezone.utc) - timedelta(hours=5)
-    elapsed_min = (now - window_start).total_seconds() / 60
-    if elapsed_min > 1:
-        rate5 = '{:+.1f}'.format(q5h / elapsed_min)
-
-# Q7d burn rate
-rate7 = ''
-if q7d_reset > 0 and q7d > 0:
-    window_start_7d = datetime.fromtimestamp(q7d_reset, tz=timezone.utc) - timedelta(days=7)
-    elapsed_hr = (now - window_start_7d).total_seconds() / 3600
-    if elapsed_hr > 0.1:
-        rate7 = '{:+.1f}'.format(q7d / elapsed_hr)
-
-label = 'Q5h: {}%'.format(q5h)
-if rate5:
-    label += ' ({}%/m)'.format(rate5)
-label += ' | Q7d: {}%'.format(q7d)
-if rate7:
-    label += ' ({}%/hr)'.format(rate7)
+BAR_WIDTH = 10
+
+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))
+    if elapsed_pct is None:
+        tick = -1
+    else:
+        tick = min(int(max(0, min(100, elapsed_pct)) / 100 * width), width - 1)
+    cells = []
+    remaining = fill
+    for i in range(width):
+        if i == tick:
+            cells.append('┃')
+        elif remaining > 0:
+            cells.append('█')
+            remaining -= 1
+        else:
+            cells.append('░')
+    return '[' + ''.join(cells) + ']'
+
+def fmt_hm(secs):
+    if secs is None or secs <= 0:
+        return ''
+    return '{}h{:02d}m'.format(int(secs // 3600), int((secs % 3600) // 60))
+
+def fmt_dh(secs):
+    if secs is None or secs <= 0:
+        return ''
+    return '{}d {}h'.format(int(secs // 86400), int((secs % 86400) // 3600))
+
+def window_view(reset_ts, window_secs):
+    # Returns (elapsed_sec, secs_left). elapsed_sec may be negative (server
+    # gave us a reset_at past the window head — invalid) or exceed window_secs
+    # (stale reset_at not yet refreshed by the next API call). Callers handle
+    # both; downstream rendering clamps the tick to the bar edges.
+    if reset_ts <= 0:
+        return None, None
+    window_start = datetime.fromtimestamp(reset_ts - window_secs, tz=timezone.utc)
+    return (now - window_start).total_seconds(), reset_ts - now.timestamp()
+
+def time_to_exhaust_sec(pct, elapsed_sec, min_elapsed_sec):
+    # (100 - pct) divided by current burn rate (pct / elapsed_sec). Gated on
+    # min_elapsed_sec so very-fresh windows don't project off noise.
+    if elapsed_sec is None or elapsed_sec <= min_elapsed_sec:
+        return None
+    if pct <= 0 or pct >= 100:
+        return None
+    return (100 - pct) * elapsed_sec / pct
+
+def format_window(name, pct, elapsed_sec, window_secs, secs_left, fmt_time, min_elapsed_sec):
+    ep = None if elapsed_sec is None or elapsed_sec < 0 else elapsed_sec / window_secs * 100
+    extras = []
+    stale = secs_left is not None and secs_left <= 0
+    if not stale:
+        exhaust = time_to_exhaust_sec(pct, elapsed_sec, min_elapsed_sec)
+        if exhaust is not None:
+            extras.append('exhaust ' + fmt_time(exhaust))
+        if secs_left is not None and secs_left > 0:
+            extras.append('reset ' + fmt_time(secs_left))
+    tail = ' (' + ', '.join(extras) + ')' if extras else ''
+    return '{} {} {}%{}'.format(name, draw_bar(pct, ep), pct, tail)
+
+elapsed_5h, left_5h = window_view(q5h_reset, 5 * 3600)
+elapsed_7d, left_7d = window_view(q7d_reset, 7 * 86400)
+
+label = format_window('Q5h', q5h, elapsed_5h, 5 * 3600, left_5h, fmt_hm, 60)
+label += ' | ' + format_window('Q7d', q7d, elapsed_7d, 7 * 86400, left_7d, fmt_dh, 360)
 if overage == 'active':
     label += ' | OVERAGE'