Skip to content

v3.4.0 — three new extensions, two bug fixes

Choose a tag to compare

View all tags
@vsits-proxy-builder vsits-proxy-builder released this 04 May 20:41
· 104 commits to main since this release
v3.4.0
3eb5e7e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v3.4.0 ships three new extensions and two bug fixes for users on proxy mode. The new extensions broaden cache coverage (a fourth breakpoint on the messages[0] boundary, in-payload TTL-tier detection that survives downstream normalization) and lay Phase 1 groundwork for stabilizing CC's time_based_microcompact sentinel. The two bug fixes correct a silent no-op in the :resume → :startup rewrite and tighten image-strip debug-output gating.

What's new

messages-cache-breakpoint — fourth cache breakpoint on auto-injected blocks

Opt in via CACHE_FIX_INJECT_MESSAGES_BREAKPOINT=1. Anthropic's prompt cache supports up to 4 markers per request; CC currently uses 3, leaving the auto-injected messages[0] span (hooks, skills, project CLAUDE.md, deferred-tools, MCP server descriptions) uncached. This extension adds the missing marker at the boundary between those blocks and the first real user content. Conservative fail-open behavior on every block kind. Default off until validated against community data — see CACHE_FIX_DUMP_MESSAGES_HEAD=<path> for fixture sourcing. (Closes #12; thanks to @wadabum for the 4-breakpoint analysis.)

microcompact-stability — Phase 1: diagnostic + sentinel normalization

Opt in via CACHE_FIX_DUMP_MICROCOMPACT=<path> (capture) or CACHE_FIX_NORMALIZE_MICROCOMPACT=1 (normalize). When CC's time_based_microcompact runs, it replaces old tool_result content with a sentinel string; if that sentinel varies byte-wise between firings, the cache for everything after it is busted. Phase 1 captures the sentinel variants seen in production and offers an opt-in normalization to a stable canonical form. Phase 2 (snapshot-and-restore) is deferred pending Phase 1 data. (Closes #36.)

ttl-tier-detect — auto-detect 5m TTL markers in payload

Default-enabled. Detects cache_control.ttl="5m" markers in the incoming request payload before downstream extensions strip them. Records the result on ctx.meta._ttlTier for ttl-management to consume. Pure detection, no mutation. This restores parity with what preload.mjs mode has done since v1.9.0 — proxy mode was missing it. (Closes #97; @vmfarms surfaced this.)

ttl-management consumes detected tier

When the payload carries any ttl="5m" marker, all injected cache_control blocks now get ttl="5m", even if CACHE_FIX_TTL_MAIN / CACHE_FIX_TTL_SUBAGENT is set to 1h. Auto-upgrade prevents a 1h-pin from overriding what the server actually requested. Setting CACHE_FIX_TTL_*=none still suppresses injection entirely.

Bug fixes

  • identity-normalization resume-marker rewrite was a silent no-op. The marker constant matched the post-rewrite output instead of the input, so the :resume → :startup normalization never fired. Users on proxy mode silently lost the resume-block stabilization that preload mode performs correctly. Single-character fix; new tests mirror preload-side coverage. (Fixes #96; @vmfarms surfaced this.)
  • image-strip stderr summaries leaked past CACHE_FIX_DEBUG. The legacy [image-strip] and v3.3.0 [image-guard] summaries fired on every request that did observable work, regardless of the debug flag. Both now require CACHE_FIX_DEBUG=1. The PRESERVE_DETAIL-without-GUARD misconfiguration warning stays unconditional. (Fixes #98; @vmfarms surfaced this.)

Other

  • Author info and blog-link references migrated to vsits.co.
  • New canonical release procedure documented at docs/release-workflow.md.

Upgrade

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

No migration required. All new extensions are either default-enabled with safe behavior (ttl-tier-detect is pure detection) or opt-in via env var (messages-cache-breakpoint, microcompact-stability Phase 1).

Contributors

  • @vmfarms — surfaced these via a code review by Codex GPT prompted by their question
  • @wadabum — 4-breakpoint analysis that motivated messages-cache-breakpoint

Tests

597 → 698 (+101).

Architectural detail

For the directive-level design notes:

  • #90 — messages-cache-breakpoint directive + implementation
  • #91 — microcompact-stability directive + Phase 1 implementation
  • #100 — ttl-tier-detect directive + implementation
Assets 2
Loading