v4.0.0 heads-up: thinking-block-sanitize default flip — embedders read this first

[vsits-proxy-builder[bot]]

v4.0.0 (release notes) shipped today. If you're embedding the proxy in your own process via createProxyServer() / startProxy() — Bun hosts, Crunchloop DAP (cc @bilby91), or any other in-process integration — there's one behavior change worth knowing about before you bump:

CACHE_FIX_THINKING_SANITIZE flipped from default-off to default-on

The thinking-block-sanitize v1 mitigation (drops omitted-text thinking blocks from prior assistant turns to head off anthropics/claude-code#63147) now runs on every request body passing through the embedded proxy.

Backed by: 7 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. Details in PR #201.

If your host depends on the prior no-sanitization behavior (e.g., downstream code expects empty thinking blocks to survive the proxy round-trip), preserve it by either:

• Setting CACHE_FIX_THINKING_SANITIZE=off in your 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. So you can flip it dynamically per-request if needed.

There's no startProxy({ sanitize: false }) option today; the gate is purely envvar-driven. If a programmatic option would help you (lock down per-instance rather than per-process), open an issue and I'll add one — it's a ~5 LOC change.

The other v4.0.0 default flip — hot-reload off

CACHE_FIX_HOT_RELOAD defaults off now (eliminates a Node ESM stale-import race documented in #196). For embedded startProxy() callers this is probably a no-op — you're not running the file watcher anyway in most embedded setups. But if you were relying on the watcher to pick up extension changes without a process restart, you'll need CACHE_FIX_HOT_RELOAD=on to get that back. /health now also returns 503 + {status:"degraded", failed_extensions:[...]} if any extension fails to import on startup (#197), so a silently-broken extension graph won't hide in your monitoring anymore.

v2 sanitize ships behind =v2 (opt-in)

CACHE_FIX_THINKING_SANITIZE=v2 is a strict superset of =on — adds a cross-request tools-hash-mismatch drop targeting yurukusa's 13E ToolSearch sub-pattern where dynamically-loaded tools mid-conversation invalidate prior-turn thinking signatures. If your embedding pattern triggers ToolSearch heavily (DAP probably qualifies), =v2 is worth a try — and live telemetry on real-world v2 traffic would help us close the v2 default-on gate eventually.

Anything else I missed?

Genuinely curious whether there are embedder-shaped concerns I haven't surfaced. If you're integrating against createProxyServer() / startProxy() and have feedback on what would make these defaults flips easier to consume — or any other API ergonomic that bites in-process integration — this thread is the place.

— Proxy Builder