Skip to content

v4.2.0 — eight features, default-off opt-ins + request_id flip

Choose a tag to compare

View all tags
@vsits-proxy-builder vsits-proxy-builder released this 23 Jun 10:29
· 56 commits to main since this release
v4.2.0
f3cecd9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v4.2.0 batches eight new features and one behavior flip into a single minor release. All new features are default-off opt-ins; one previously-default-off field flips on with a meter-version upgrade requirement.

Install or upgrade:

npm install -g claude-code-cache-fix@4.2.0

What's new

Default-off opt-in features

  • Proxy-owned OAuth refresh (#234, #236 directive, #237 implementation). The proxy can now be the single, proactive, lock-cooperative refresher of the OAuth credential shared by all concurrent Claude Code clients running as the same OS user. Closes the refresh-token rotation race that revokes the whole token family and 401s the entire fleet at once — a failure no client-side restart can recover (only an interactive /login). Acquires the same ~/.claude/.oauth_refresh.lock the client uses via proper-lockfile. Hard 8-second POST deadline (below the client's 10s stale-break) covering both headers AND response body read. Default OFF via CACHE_FIX_OAUTH_REFRESH=on. Threat-model discipline: token material never reaches any log/event writer.

  • cc-version-normalize extension (#238, #239). Rewrites the cc_version value inside the x-anthropic-billing-header to prevent per-build cache invalidation. The VS Code extension and other auto-updating distribution channels emit values like 2.1.185.<buildhash> where the hash mutates on auto-update, busting the cache for the rest of the session. Three modes via CACHE_FIX_NORMALIZE_CC_VERSION: off (default), strip (collapses suffix to X.Y.Z), pin:<value> (operator literal). Runs at order 90, before fingerprint-strip at 100; the two cooperate cleanly. Surfaced by @X-15.

  • upstream-error-log extension (#235, #240). Emits a structured JSONL record for every non-200 upstream response to ~/.claude/usage-log/upstream-errors.jsonl. Two distinct 429 classes look identical to a user — account/usage-limit (with anthropic-ratelimit-unified-* headers) vs infrastructure/capacity (Cloudflare-fronted, x-should-retry only, no ratelimit headers). The has_ratelimit_headers boolean is the discriminator. Default OFF via CACHE_FIX_UPSTREAM_ERROR_LOG=on.

  • workflow-agent-id-synthesis extension (#215, refs upstream anthropics/claude-code#66761). Closes the per-Workflow-leg cost-attribution gap CC#66761 left open. Stashes a derived agent_id on ctx.meta covering Task/Agent (canonical-present), Workflow (derived via stable hash), and top-level traffic. Cross-repo contract: claude-code-meter ≥ 0.8.0 accepts the optional agent_id + agent_id_source fields when CACHE_FIX_USAGE_LOG_AGENT_ID=on. Default OFF for first ship.

  • Statusline served-model divergence indicator (#223, refs upstream anthropics/claude-code#66728). First real-time operator surface for the classifier-driven swap pattern. proxy/extensions/cache-telemetry.mjs captures served vs requested model; tools/quota-statusline.sh renders red for recent divergence, black-on-yellow for sticky. Family-aware sticky heuristic (cross-family latches immediately; same-family requires 3 consecutive divergent turns).

  • image-retry-circuit-breaker extension (#217, refs upstream anthropics/claude-code#66815). Short-circuits the CC harness retry storm on permanent image could not be processed failures. Bounds the loss from CC#66815's reported 19-retries × 34 MB pattern to one upstream call. Three modes via CACHE_FIX_IMAGE_RETRY_BREAKER: off (default), on, dry-run. Default OFF pending sim-validation.

  • tools/gh-auth-status-shim/ (refs upstream anthropics/claude-code#67055). PATH-resolved gh wrapper that suppresses CC Desktop's false "GitHub CLI authentication expired" toast caused by spawn timeouts being mapped to the auth toast category. Install via tools/gh-auth-status-shim/install.sh.

  • jsonl-session-mirror extension (refs upstream anthropics/claude-code#66734 and anthropics/claude-code#66486). Belt-and-suspenders backup against CC's in-place transcript stub-rewrite and missing-transcript regressions. Mirrors every assistant message + tool result / user input into a per-session JSONL file, independent of CC's transcript writer. Envelope shape matches CC 2.1.148's verified transcript so existing readers parse mirror files unchanged. Default OFF via CACHE_FIX_SESSION_MIRROR=on.

Behavior change

  • CACHE_FIX_USAGE_LOG_REQID flipped default-on. Per the v4.1.0 release-ordering contract. The request_id field is now emitted on every ~/.claude/usage.jsonl row by default (when the upstream request-id header is present and ≤ 64 chars). The env-var becomes a kill-switch: =off omits the field. Upgrade requirement: operators running cache-fix v4.2.0 + claude-code-meter < v0.7.0 will see every meter row rejected by the strict-object validator until they either upgrade meter or set CACHE_FIX_USAGE_LOG_REQID=off. Meter v0.7.0, v0.7.1, and v0.8.0 are all published on npm.

Contributors

  • @X-15 — surfaced the cc_version per-build cache-bust pattern from VS Code extension auto-update (#238)

Plus the cross-LLM review chain that gated each PR through Codex review before merge.

Upgrade

npm install -g claude-code-cache-fix@4.2.0

Then restart your proxy (supervisor-level, per v4.0.0's hot-reload-off default):

systemctl --user restart cache-fix-proxy    # Linux / systemd
launchctl unload ~/Library/LaunchAgents/com.cnighswonger.cache-fix-proxy.plist && launchctl load ~/Library/LaunchAgents/com.cnighswonger.cache-fix-proxy.plist    # macOS / launchd

All new features are default-off, so the upgrade is behavior-neutral except for the request_id flip. If you run claude-code-meter and haven't upgraded to ≥ 0.7.0, set CACHE_FIX_USAGE_LOG_REQID=off before restarting, or upgrade meter first.

Full changelog

CHANGELOG.md

Assets 2
Loading