v4.0.0 — sanitize default-on + hot-reload opt-in

v4.0.0 is a major release because two long-standing defaults change. Both flips are backed by empirical data, both have explicit opt-out paths, and the upgrade flow now includes one supervisor-restart step you should be aware of before running npm install -g.

What changed

thinking-block-sanitize v1 is now ON by default (#162, #201). Was opt-in via CACHE_FIX_THINKING_SANITIZE=on in v3.8.0–v3.9.x. Seven days of prod dogfood across 37 sessions: zero cannot be modified 400s, cache hit-rate aggregate 94.66% vs 92.44% baseline (no prefix degradation), sanitize fired on ~35% of sessions with ~800 blocks dropped per day, max 938K context healthy. Set CACHE_FIX_THINKING_SANITIZE=off to explicitly disable. Credit to @yurukusa for the 13E cluster taxonomy work upstream.

In-process extension hot-reload is now OFF by default (#196, #200). Was on in v3.x. Eliminates the Node ESM stale-import race that silently broke thinking-block-sanitize v2 for 17 hours after PR #192's merge in v3.9.x. Set CACHE_FIX_HOT_RELOAD=on in your environment (or in the install-service env) to restore the prior behavior.

A supervisor-level proxy restart is now required after npm install -g claude-code-cache-fix@4 to pick up extension changes. See Upgrading from v3.x for per-platform restart commands (systemctl --user restart cache-fix-proxy on Linux, launchctl kickstart on macOS).

Embedder note (Bun hosts, DAP-style integrators using createProxyServer() / startProxy()): the sanitize default-on flip will run on every request body passing through the embedded proxy. If your host depends on the prior no-sanitization behavior, set CACHE_FIX_THINKING_SANITIZE=off in the host environment, or process.env.CACHE_FIX_THINKING_SANITIZE = "off" in your code at any point before request handling. The mode is read per-request via modeFromEnv(), not cached at module load.

Also new

• thinking-block-sanitize v2 ships as opt-in (#171, #192). Set CACHE_FIX_THINKING_SANITIZE=v2 (a strict superset of =on). Detects cross-request tools-surface change and strips ALL prior-turn signed thinking (both thinking blocks with non-empty text AND redacted_thinking blocks) when the hash flips. Targets yurukusa's 13E ToolSearch sub-pattern of #63147, where dynamically-loaded tools mid-conversation invalidate the prior assistant turn's thinking signature and produce a per-turn 400 + retry tax. v2 stays opt-in pending its own prod-dogfood window, now that #196 has closed the silent-load failure mode.
• /health extension-load observability (#197). When any extension fails to import, /health returns 503 + {status:"degraded", failed_extensions:[...], hint:"restart the proxy via your supervisor to recover..."} so monitoring catches load failures within seconds instead of leaving the operator to grep the journal. Healthy proxies still return 200 + {status:"ok"}. New getFailedExtensions() export on proxy/pipeline.mjs for operator-facing tooling.

Upgrade

npm install -g claude-code-cache-fix@4
# then restart your proxy via its supervisor — required to pick up the new code
systemctl --user restart cache-fix-proxy      # Linux
launchctl kickstart gui/$(id -u)/com.cnighswonger.cache-fix-proxy   # macOS

If you want hot-reload back: CACHE_FIX_HOT_RELOAD=on in env, or pass it to cache-fix-proxy install-service to bake into the unit/plist.

If you want sanitize off: CACHE_FIX_THINKING_SANITIZE=off in env.

See README.md § Upgrading from v3.x for the two-flow upgrade procedure (Flow 1: code-only npm upgrade; Flow 2: install-service rerun with rewritten unit/plist).

Contributors this release

• @yurukusa — #63147 13E cluster taxonomy and synthesis comment that made the v2 sanitize predicate tractable

References

• Directive: #198 (hot-reload opt-in)
• Implementation: #200 (hot-reload), #201 (sanitize default-on), #197 (observability), #202 (post-#201 wording sweep)
• Upstream context: anthropics/claude-code#63147

Full CHANGELOG.