claude-code-cache-fix 3.3.0 → 3.4.0

package/README.md

@@ -409,6 +409,59 @@ If `sharp` is missing, Pass 3 skips cleanly (telemetry records `library_missing:
 | `CACHE_FIX_IMAGE_REQUEST_SIZE_MAX` | 31457280 (30 MB) | Pass 2 byte budget. 2 MB headroom from Anthropic's 32 MB ceiling. |
 | `CACHE_FIX_IMAGE_COUNT_MAX` | 100 | Hard image-count cap. Set to 600 for legacy Claude 1/2.x/Instant if needed. |
 
+## Cache breakpoints (proxy mode, opt-in)
+
+Anthropic's prompt cache supports up to **four** `cache_control` markers per request. Claude Code currently uses three of the four; the third (between auto-injected `messages[0]` content — hooks, skills, project CLAUDE.md, deferred tools, MCP server descriptions — and the first real user content) is missing entirely. Without that marker, every change inside the auto-injected span busts the cache for everything that follows. wadabum projected ~6,500 token savings per fresh-session first turn from adding it ([anthropics/claude-code#47098](https://github.com/anthropics/claude-code/issues/47098)).
+
+The proxy can inject the missing marker on opt-in. Default off until validated against community data.
+
+```sh
+export CACHE_FIX_INJECT_MESSAGES_BREAKPOINT=1
+```
+
+The injection is conservative: it only fires when the request already carries 1–3 markers (typical CC shape) and refuses if the request is at the 4-marker limit (would 400) or has zero markers (Agent SDK / API-direct shape this extension isn't built for). Boundary detection covers all five observed auto-injected block kinds — hooks, skills, CLAUDE.md, deferred-tools, MCP — and lands the marker on the LAST auto-injected block.
+
+A diagnostic-only env var dumps the structural shape of `messages[0]` for fixture sourcing without mutating the request:
+
+```sh
+export CACHE_FIX_DUMP_MESSAGES_HEAD=/tmp/messages-head.jsonl
+```
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CACHE_FIX_INJECT_MESSAGES_BREAKPOINT` | unset | Enable breakpoint #3 injection (`=1` opt-in). |
+| `CACHE_FIX_DUMP_MESSAGES_HEAD` | unset | Diagnostic JSONL dump of `messages[0].content` shape — read-only, no mutation. |
+
+## Microcompact stability (proxy mode, opt-in)
+
+After ~90 minutes idle, Claude Code's `time_based_microcompact` (and the cold-compact path triggered by `FDY()`) replaces old `tool_result` content with a sentinel string. The original content is gone for cache purposes; that part is unrecoverable from the proxy. But the sentinel itself can carry an embedded timestamp (`[Old tool result content cleared at 2026-04-30T13:42:11Z]`), which means a *second* microcompact pass against the same already-cleared position writes different bytes — busting the cache for everything after that position even though no new content was added.
+
+This extension addresses the recoverable half: normalize the sentinel to a byte-stable canonical form so repeat microcompacts don't churn the cache. **Phase 1 only** — diagnostic + opt-in normalization. Phase 2 (snapshot-and-restore of original tool_result content) is deferred to v3.5.0+ pending Phase 1 production data.
+
+```sh
+# Step 1 (diagnostic): characterize what CC's sentinel actually looks like.
+export CACHE_FIX_DUMP_MICROCOMPACT=/tmp/microcompact-dump.jsonl
+
+# Step 2 (normalize): once the sentinel format is confirmed, opt-in.
+export CACHE_FIX_NORMALIZE_MICROCOMPACT=1
+```
+
+Detection has two modes:
+- **Mode A** — exact match against confirmed CC sentinel patterns (the bare form and the ISO-8601 timestamp variant). Mode A matches are eligible for normalization.
+- **Mode B** — prefix-only match (text begins with `[Old tool result content cleared` but does not exactly match a Mode A pattern). Mode B is **diagnostic-only**: never normalized, dump records redact to a 64-char prefix only.
+
+The Mode A/B separation protects against cases where the sentinel might be followed by user-derived content (e.g., a tool that echoed user input back into its result) — the redaction guarantee on Mode B keeps that content out of the diagnostic dump.
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CACHE_FIX_DUMP_MICROCOMPACT` | unset | Path for diagnostic JSONL dump of detected sentinels. Read-only — no mutation. |
+| `CACHE_FIX_NORMALIZE_MICROCOMPACT` | unset | Enable normalization (`=1` opts in). Mutates Mode A matches to canonical form. |
+| `CACHE_FIX_MICROCOMPACT_NORMALIZED` | `[Old tool result content cleared]` | Override the canonical replacement string. |
+| `CACHE_FIX_MICROCOMPACT_SENTINEL_PATTERN_<N>` | unset | Add custom Mode A regex pattern(s). Numbered (1-indexed, sparse OK). |
+| `CACHE_FIX_MICROCOMPACT_SENTINEL_PREFIX_<N>` | unset | Custom Mode B literal prefix(es). Pair with a custom Mode A pattern from a non-default sentinel family so prefix-only variants of that family also get redacted Mode B capture. |
+| `CACHE_FIX_MICROCOMPACT_REDACT_LEN` | `64` | Mode B prefix length in dump records. Set to `0` to suppress the prefix entirely. |
+| `CACHE_FIX_DUMP_MICROCOMPACT_INCLUDE_NORMALIZED` | unset | Add post-normalization text alongside (not replacing) raw `sentinel_text` in dump records. |
+
 ## System prompt rewrite (preload mode, optional)
 
 The interceptor can rewrite Claude Code's `# Output efficiency` system-prompt section. Disabled by default. Enable with `CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT`. See [docs/output-efficiency-prompts.md](docs/output-efficiency-prompts.md) for the three known prompt variants and usage instructions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",
@@ -53,5 +53,5 @@
     "url": "https://buymeacoffee.com/vsits"
   },
   "license": "MIT",
-  "author": "Chris Nighswonger <chris@veritassuperaitsolutions.com> (https://veritassuperaitsolutions.com)"
+  "author": "Chris Nighswonger <dev@vsits.co> (https://vsits.co)"
 }

package/proxy/extensions/identity-normalization.mjs

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 
 const _pinnedBlocks = new Map();
 
-const SESSION_START_RESUME_MARKER = /SessionStart:startup hook success:/g;
+const SESSION_START_RESUME_MARKER = /SessionStart:resume hook success:/g;
 const SESSION_START_ID_TAG = /\n?<session-id>[^<]*<\/session-id>/g;
 const SESSION_START_LAST_ACTIVE_LINE = /\nLast active:[^\n]*/g;
 const CONTINUE_TRAILER_TEXT = "Continue from where you left off.";

package/proxy/extensions/image-strip.mjs

@@ -48,6 +48,9 @@ function getRequestSizeMax() {
   const v = parseInt(process.env.CACHE_FIX_IMAGE_REQUEST_SIZE_MAX || "31457280", 10);
   return v > 0 ? v : 31457280;
 }
+function isDebug() {
+  return process.env.CACHE_FIX_DEBUG === "1";
+}
 function getImageCountMax() {
   // Default 100 — single cap covering the only model family in active CC use.
   // Users on legacy Claude 1/2.x/Instant who genuinely need 600 can override.
@@ -649,7 +652,9 @@ export default {
 
       if (logParts.length > 0) {
         ctx.body.messages = messages;
-        process.stderr.write(`[image-strip] ${logParts.join("; ")}\n`);
+        if (isDebug()) {
+          process.stderr.write(`[image-strip] ${logParts.join("; ")}\n`);
+        }
       }
       return;
     }
@@ -676,7 +681,7 @@ export default {
       stats.resize_succeeded > 0 ||
       stats.unsupported_format_count > 0 ||
       stats.dimension_probe_fail_count > 0;
-    if (didSomething) {
+    if (didSomething && isDebug()) {
       const parts = [];
       if (stats.resize_succeeded > 0) parts.push(`resized=${stats.resize_succeeded}`);
       if (stats.resize_failed > 0) parts.push(`resize_failed=${stats.resize_failed}`);

package/proxy/extensions/messages-cache-breakpoint.mjs

@@ -0,0 +1,314 @@
+// messages-cache-breakpoint — inject the missing breakpoint #3 cache_control
+// at the boundary between Claude Code's auto-injected blocks (hooks, skills,
+// project CLAUDE.md, deferred-tools, MCP server descriptions) and the first
+// real user content inside `messages[0]`.
+//
+// Activation: `enabled: true` in extensions.json (always loaded), runtime
+// gates per env var:
+//
+//   - CACHE_FIX_INJECT_MESSAGES_BREAKPOINT=1 → opt-in injection
+//   - CACHE_FIX_DUMP_MESSAGES_HEAD=<path>    → diagnostic-only JSONL dump
+//                                              of messages[0].content shape
+//
+// Order 410 — runs immediately after `cache-control-normalize` (400), so we
+// count markers and place breakpoint #3 against a normalized baseline.
+//
+// See `docs/directives/proxy-messages-cache-breakpoint.md` for the full
+// design (boundary detection algorithm, marker-count guard, telemetry surface).
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+// --- Env gates (read per-call so tests can flip without re-importing) ---
+
+function isInjectEnabled() {
+  return process.env.CACHE_FIX_INJECT_MESSAGES_BREAKPOINT === "1";
+}
+function getDumpPath() {
+  const v = process.env.CACHE_FIX_DUMP_MESSAGES_HEAD;
+  return v && v.length > 0 ? v : null;
+}
+function isDebug() {
+  return process.env.CACHE_FIX_DEBUG === "1";
+}
+
+function debug(msg) {
+  if (isDebug()) process.stderr.write(`[messages-breakpoint] DEBUG: ${msg}\n`);
+}
+
+// --- Block classification ---
+//
+// Auto-injected block kinds that CC writes into `messages[0].content` ahead of
+// the real user content. Order matters: each block runs through these checks
+// in declaration order and the first match wins. Tightening notes:
+//
+//   - Hooks: requires both `<system-reminder>` opening AND `hook success`
+//     substring — narrow enough that user prose discussing hook semantics
+//     won't false-positive.
+//   - Skills: anchored on `<system-reminder>` opening tag; won't match user
+//     messages that quote `<available-skills>` from documentation.
+//   - CLAUDE.md: regex anchored on absolute-path prefix (`/`); won't match
+//     "see CLAUDE.md in the docs".
+//   - Deferred-tools: exact `<deferred-tools>` tag substring; won't match
+//     user prose about "deferred tools".
+//   - MCP: two specific sentinels (`<mcp-resources>` tag OR
+//     `Available MCP servers:` literal); won't match generic MCP prose.
+
+const CLAUDE_MD_RE = /Contents of \/[^\n]*?CLAUDE\.md/;
+
+function getBlockText(block) {
+  if (!block || typeof block !== "object") return null;
+  if (block.type !== "text") return null;
+  if (typeof block.text !== "string") return null;
+  return block.text;
+}
+
+export function classifyBlock(block) {
+  const text = getBlockText(block);
+  if (text === null) return "user";
+
+  // Hooks: <system-reminder> + "hook success"
+  if (text.startsWith("<system-reminder>") && text.includes("hook success")) {
+    return "hooks";
+  }
+  // Skills: <system-reminder> + (<available-skills> OR <plugin-skills>)
+  if (
+    text.startsWith("<system-reminder>") &&
+    (text.includes("<available-skills>") || text.includes("<plugin-skills>"))
+  ) {
+    return "skills";
+  }
+  // Project CLAUDE.md: <system-reminder> wrapper + absolute-path Contents-of
+  // marker. The system-reminder wrapper is required to keep user prose that
+  // happens to mention "Contents of /path/to/CLAUDE.md" from matching.
+  if (text.includes("<system-reminder>") && CLAUDE_MD_RE.test(text)) {
+    return "claude_md";
+  }
+  // Deferred tools: exact <deferred-tools> tag
+  if (text.includes("<deferred-tools>")) {
+    return "deferred_tools";
+  }
+  // MCP: either sentinel
+  if (text.includes("<mcp-resources>") || text.includes("Available MCP servers:")) {
+    return "mcp_resources";
+  }
+  return "user";
+}
+
+const AUTO_INJECTED_KINDS = new Set([
+  "hooks",
+  "skills",
+  "claude_md",
+  "deferred_tools",
+  "mcp_resources",
+]);
+
+// Return the LAST index in `content` whose block classifies as auto-injected,
+// or -1 if no auto-injected block is found. Walking the full array (rather
+// than stopping at the first user block) keeps us correct in the defensive
+// case where auto-injected and user blocks are interleaved.
+export function detectAutoInjectedBoundary(content) {
+  if (!Array.isArray(content)) return -1;
+  let lastIdx = -1;
+  for (let i = 0; i < content.length; i++) {
+    const kind = classifyBlock(content[i]);
+    if (AUTO_INJECTED_KINDS.has(kind)) lastIdx = i;
+  }
+  return lastIdx;
+}
+
+// --- Marker counting ---
+
+export function countAllCacheControlMarkers(body) {
+  if (!body || typeof body !== "object") return 0;
+  let n = 0;
+  if (Array.isArray(body.system)) {
+    for (const block of body.system) {
+      if (block && typeof block === "object" && block.cache_control) n++;
+    }
+  }
+  if (Array.isArray(body.messages)) {
+    for (const msg of body.messages) {
+      if (!msg || !Array.isArray(msg.content)) continue;
+      for (const block of msg.content) {
+        if (block && typeof block === "object" && block.cache_control) n++;
+      }
+    }
+  }
+  return n;
+}
+
+// --- Stats shape (also used as telemetry on ctx.meta) ---
+
+function initStats() {
+  return {
+    enabled: true,
+    injected: false,
+    boundary_idx: -1,
+    boundary_block_kind: null,
+    blocks_examined: 0,
+    existing_marker_count: 0,
+    skip_reason: null,
+  };
+}
+
+// --- Orchestrator (pure on body — no I/O) ---
+
+export function injectMessagesBreakpoint(reqCtx) {
+  const stats = initStats();
+  if (!reqCtx || !reqCtx.body) {
+    stats.skip_reason = "unexpected_role_or_shape";
+    return stats;
+  }
+  const body = reqCtx.body;
+  const messages = body.messages;
+  if (!Array.isArray(messages) || messages.length === 0) {
+    stats.skip_reason = "unexpected_role_or_shape";
+    return stats;
+  }
+  const first = messages[0];
+  if (!first || first.role !== "user" || !Array.isArray(first.content)) {
+    stats.skip_reason = "unexpected_role_or_shape";
+    return stats;
+  }
+
+  const existingMarkers = countAllCacheControlMarkers(body);
+  stats.existing_marker_count = existingMarkers;
+
+  if (existingMarkers === 0) {
+    stats.skip_reason = "no_existing_markers";
+    return stats;
+  }
+  if (existingMarkers >= 4) {
+    stats.skip_reason = "at_marker_limit";
+    if (existingMarkers > 4) {
+      process.stderr.write(
+        `[messages-breakpoint] warn: existing_markers=${existingMarkers} exceeds Anthropic's documented max of 4\n`,
+      );
+    }
+    return stats;
+  }
+
+  stats.blocks_examined = first.content.length;
+  const boundaryIdx = detectAutoInjectedBoundary(first.content);
+  stats.boundary_idx = boundaryIdx;
+  if (boundaryIdx === -1) {
+    stats.skip_reason = "boundary_not_found";
+    return stats;
+  }
+
+  const target = first.content[boundaryIdx];
+  stats.boundary_block_kind = classifyBlock(target);
+
+  if (target && target.cache_control) {
+    stats.skip_reason = "boundary_already_marked";
+    return stats;
+  }
+
+  first.content[boundaryIdx] = {
+    ...target,
+    cache_control: { type: "ephemeral", ttl: "1h" },
+  };
+  stats.injected = true;
+  return stats;
+}
+
+// --- Diagnostic dump ---
+//
+// Dumps the structural shape of messages[0].content (per-block kind, first
+// 200 chars of text, cache_control presence flag) to a JSONL file. Read-only
+// — no body mutation. Independent of injection: a user can enable the dump
+// without enabling injection to gather fixture data first.
+
+const DUMP_TEXT_PREFIX_CHARS = 200;
+
+export function buildDumpRecord(body, ts = new Date().toISOString()) {
+  const messages = body?.messages;
+  const first = Array.isArray(messages) ? messages[0] : null;
+  const content = first && Array.isArray(first.content) ? first.content : null;
+  const blocks = content
+    ? content.map((block, idx) => {
+        const kind = classifyBlock(block);
+        const text = getBlockText(block);
+        return {
+          idx,
+          type: block?.type ?? null,
+          kind,
+          text_prefix: text === null ? null : text.slice(0, DUMP_TEXT_PREFIX_CHARS),
+          has_cache_control: !!(block && block.cache_control),
+        };
+      })
+    : [];
+  return {
+    ts,
+    role: first?.role ?? null,
+    block_count: blocks.length,
+    existing_marker_count: countAllCacheControlMarkers(body),
+    blocks,
+  };
+}
+
+async function writeDump(path, record) {
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, JSON.stringify(record) + "\n");
+}
+
+// --- Stderr summary ---
+
+function emitStderrSummary(stats) {
+  if (stats.injected) {
+    process.stderr.write(
+      `[messages-breakpoint] injected boundary_idx=${stats.boundary_idx} kind=${stats.boundary_block_kind} existing_markers=${stats.existing_marker_count}\n`,
+    );
+  } else {
+    process.stderr.write(
+      `[messages-breakpoint] skipped reason=${stats.skip_reason} existing_markers=${stats.existing_marker_count}\n`,
+    );
+  }
+}
+
+// --- Extension contract ---
+
+export default {
+  name: "messages-cache-breakpoint",
+  description:
+    "Inject the missing breakpoint #3 cache_control marker at the boundary " +
+    "between Claude Code's auto-injected messages[0] blocks (hooks, skills, " +
+    "CLAUDE.md, deferred-tools, MCP) and the first real user content",
+  enabled: false, // overridden by extensions.json
+  order: 410,
+
+  async onRequest(ctx) {
+    const dumpPath = getDumpPath();
+    const inject = isInjectEnabled();
+
+    // Both gates off → no-op. Avoid even building stats so the disabled path
+    // is essentially free.
+    if (!dumpPath && !inject) return;
+
+    if (!ctx || !ctx.body) return;
+
+    // Diagnostic dump runs first and is independent of injection. We dump
+    // BEFORE injection so the recorded shape is the request as CC sent it,
+    // not as we mutated it.
+    if (dumpPath) {
+      try {
+        const record = buildDumpRecord(ctx.body);
+        await writeDump(dumpPath, record);
+      } catch (err) {
+        debug(`dump write failed: ${err?.message ?? err}`);
+      }
+    }
+
+    if (!inject) return;
+
+    try {
+      const stats = injectMessagesBreakpoint(ctx);
+      ctx.meta = ctx.meta || {};
+      ctx.meta.messagesBreakpointStats = stats;
+      emitStderrSummary(stats);
+    } catch (err) {
+      debug(`onRequest unexpected: ${err?.message ?? err}`);
+    }
+  },
+};

package/proxy/extensions/microcompact-stability.mjs

@@ -0,0 +1,428 @@
+// microcompact-stability — detect, optionally dump, and optionally normalize
+// CC's `time_based_microcompact` sentinel string in tool_result content.
+//
+// Order 350: between `tool-input-normalize` (340) and `cache-control-normalize`
+// (400). Runs BEFORE cache-control-normalize so the latter sees post-normalized
+// content when computing sticky-marker hashes.
+//
+// Two independent runtime gates:
+//   - CACHE_FIX_DUMP_MICROCOMPACT=<path>   → diagnostic JSONL dump (read-only).
+//   - CACHE_FIX_NORMALIZE_MICROCOMPACT=1   → mutate matched sentinels to a
+//                                            canonical byte-stable form.
+//
+// Two detection modes:
+//   - Mode A (exact match against confirmed patterns) → eligible for
+//     normalization. `sentinel_text` captured in full in dump records.
+//   - Mode B (prefix-only match) → diagnostic-only, NEVER normalized. Records
+//     redact to a configurable prefix length (default 64).
+//
+// The diagnostic dump always captures the **raw pre-normalization** bytes —
+// this is the rule. Setting CACHE_FIX_DUMP_MICROCOMPACT_INCLUDE_NORMALIZED=1
+// additionally records the post-normalized form alongside the raw text.
+//
+// See `docs/directives/proxy-microcompact-cache-stability.md` for the full
+// design (Mode A/B contract, privacy guarantees, Phase 2 deferral).
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+
+// --- Env gates (read per-call so tests can flip without re-importing) ---
+
+function getDumpPath() {
+  const v = process.env.CACHE_FIX_DUMP_MICROCOMPACT;
+  return v && v.length > 0 ? v : null;
+}
+function isNormalizeEnabled() {
+  return process.env.CACHE_FIX_NORMALIZE_MICROCOMPACT === "1";
+}
+function isIncludeNormalizedEnabled() {
+  return process.env.CACHE_FIX_DUMP_MICROCOMPACT_INCLUDE_NORMALIZED === "1";
+}
+function getCanonicalText() {
+  const v = process.env.CACHE_FIX_MICROCOMPACT_NORMALIZED;
+  return typeof v === "string" && v.length > 0 ? v : DEFAULT_CANONICAL_TEXT;
+}
+function getRedactLen() {
+  const v = process.env.CACHE_FIX_MICROCOMPACT_REDACT_LEN;
+  if (v === undefined || v === null || v === "") return DEFAULT_REDACT_LEN;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_REDACT_LEN;
+}
+function getCustomPatterns() {
+  // CACHE_FIX_MICROCOMPACT_SENTINEL_PATTERN_<N>=<regex>  (1-indexed, sparse OK)
+  const out = [];
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!k.startsWith("CACHE_FIX_MICROCOMPACT_SENTINEL_PATTERN_")) continue;
+    if (typeof v !== "string" || v.length === 0) continue;
+    try {
+      out.push({ source: v, re: new RegExp(v) });
+    } catch {
+      process.stderr.write(`[microcompact] invalid regex in ${k}: ${v}\n`);
+    }
+  }
+  return out;
+}
+
+// Custom Mode B literal prefixes, paired with custom Mode A regex patterns.
+// A user who configures CACHE_FIX_MICROCOMPACT_SENTINEL_PATTERN_<N> for a
+// non-default sentinel family should also set CACHE_FIX_MICROCOMPACT_SENTINEL_PREFIX_<N>
+// to the LITERAL string the family begins with — that's what enables Mode B
+// (redacted prefix capture) for variants that don't exact-match the regex.
+//
+// We can't safely derive a prefix from an arbitrary regex, so we accept the
+// prefix as a separate input. The two env-var families don't have to agree
+// on numeric suffixes; we collect all prefixes regardless of index.
+function getCustomPrefixes() {
+  // CACHE_FIX_MICROCOMPACT_SENTINEL_PREFIX_<N>=<literal>  (1-indexed, sparse OK)
+  const out = [];
+  for (const [k, v] of Object.entries(process.env)) {
+    if (!k.startsWith("CACHE_FIX_MICROCOMPACT_SENTINEL_PREFIX_")) continue;
+    if (typeof v !== "string" || v.length === 0) continue;
+    out.push(v);
+  }
+  return out;
+}
+function isDebug() {
+  return process.env.CACHE_FIX_DEBUG === "1";
+}
+function debug(msg) {
+  if (isDebug()) process.stderr.write(`[microcompact] DEBUG: ${msg}\n`);
+}
+
+// --- Constants ---
+
+const DEFAULT_CANONICAL_TEXT = "[Old tool result content cleared]";
+const DEFAULT_REDACT_LEN = 64;
+
+// Default Mode A patterns (confirmed sentinel forms eligible for normalization).
+// Adding a new exact form here promotes it from Mode B prefix capture to
+// Mode A normalization-eligibility. Keep the list narrow.
+const DEFAULT_EXACT_PATTERNS = [
+  {
+    source: "^\\[Old tool result content cleared\\]\\s*$",
+    re: /^\[Old tool result content cleared\]\s*$/,
+  },
+  {
+    source:
+      "^\\[Old tool result content cleared at \\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?Z\\]\\s*$",
+    re: /^\[Old tool result content cleared at \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z\]\s*$/,
+  },
+];
+
+// Mode B prefix — anything beginning with this is a candidate for redacted
+// diagnostic capture, even if it doesn't match an exact pattern.
+const SENTINEL_PREFIX = "[Old tool result content cleared";
+
+// --- Pattern matching (pure) ---
+
+// Returns the source string of the first matching exact pattern, or null.
+// `extraPatterns` are user-supplied patterns from env vars; they're appended
+// to the defaults so a custom regex doesn't silently disable a default.
+export function matchesSentinelPattern(text, extraPatterns = []) {
+  if (typeof text !== "string") return null;
+  const all = DEFAULT_EXACT_PATTERNS.concat(extraPatterns);
+  for (const p of all) {
+    if (p.re.test(text)) return p.source;
+  }
+  return null;
+}
+
+function isPartialMatch(text, extraPrefixes = []) {
+  if (typeof text !== "string") return false;
+  if (text.startsWith(SENTINEL_PREFIX)) return true;
+  for (const p of extraPrefixes) {
+    if (text.startsWith(p)) return true;
+  }
+  return false;
+}
+
+// --- Walking tool_result content ---
+//
+// Returns { exact_matches, partial_matches, total_tool_results }.
+//
+// Match record shape (exact_matches[]):
+//   { msg_idx, block_idx, content_kind: "string"|"array_item",
+//     item_idx?, text, matched_pattern }
+// Match record shape (partial_matches[]):
+//   { msg_idx, block_idx, content_kind: "string"|"array_item",
+//     item_idx?, text, byte_length }
+//
+// `text` on partial_matches is kept on the in-memory record for redaction at
+// serialize time (the dump never persists the full text).
+
+export function walkToolResultsForSentinels(messages, extraPatterns = [], extraPrefixes = []) {
+  const exact_matches = [];
+  const partial_matches = [];
+  let total_tool_results = 0;
+  if (!Array.isArray(messages)) {
+    return { exact_matches, partial_matches, total_tool_results };
+  }
+
+  for (let mi = 0; mi < messages.length; mi++) {
+    const msg = messages[mi];
+    if (!msg || !Array.isArray(msg.content)) continue;
+    for (let bi = 0; bi < msg.content.length; bi++) {
+      const block = msg.content[bi];
+      if (!block || block.type !== "tool_result") continue;
+      total_tool_results++;
+
+      const content = block.content;
+      if (typeof content === "string") {
+        classify(mi, bi, "string", undefined, content);
+      } else if (Array.isArray(content)) {
+        for (let ii = 0; ii < content.length; ii++) {
+          const item = content[ii];
+          if (!item || item.type !== "text" || typeof item.text !== "string") continue;
+          classify(mi, bi, "array_item", ii, item.text);
+        }
+      }
+    }
+  }
+  return { exact_matches, partial_matches, total_tool_results };
+
+  function classify(msg_idx, block_idx, content_kind, item_idx, text) {
+    const matched = matchesSentinelPattern(text, extraPatterns);
+    if (matched !== null) {
+      exact_matches.push({
+        msg_idx,
+        block_idx,
+        content_kind,
+        ...(item_idx !== undefined ? { item_idx } : {}),
+        text,
+        matched_pattern: matched,
+      });
+      return;
+    }
+    if (isPartialMatch(text, extraPrefixes)) {
+      partial_matches.push({
+        msg_idx,
+        block_idx,
+        content_kind,
+        ...(item_idx !== undefined ? { item_idx } : {}),
+        text,
+        byte_length: Buffer.byteLength(text, "utf8"),
+      });
+    }
+  }
+}
+
+// --- Normalization (mutates the message block in place) ---
+//
+// `match` is an entry from `exact_matches` (Mode A). We use its msg_idx /
+// block_idx / content_kind / item_idx to find the exact place to rewrite.
+// Mode B matches are NEVER passed to this function.
+
+export function normalizeToolResultContent(messages, match, canonicalText) {
+  const block = messages?.[match.msg_idx]?.content?.[match.block_idx];
+  if (!block || block.type !== "tool_result") return false;
+  if (match.content_kind === "string") {
+    block.content = canonicalText;
+    return true;
+  }
+  if (match.content_kind === "array_item" && Array.isArray(block.content)) {
+    const item = block.content[match.item_idx];
+    if (!item || item.type !== "text") return false;
+    item.text = canonicalText;
+    return true;
+  }
+  return false;
+}
+
+// --- Session ID hashing ---
+
+function hashSessionId(reqCtx) {
+  const sid =
+    reqCtx?.meta?.session_id ||
+    reqCtx?.headers?.["x-session-id"] ||
+    reqCtx?.headers?.["x-anthropic-session-id"] ||
+    null;
+  if (!sid) return null;
+  return createHash("sha256").update(String(sid)).digest("hex").slice(0, 8);
+}
+
+// --- Diagnostic record build (pure) ---
+
+function serializeExactMatch(m, includeNormalizedText) {
+  const rec = {
+    msg_idx: m.msg_idx,
+    block_idx: m.block_idx,
+    content_kind: m.content_kind,
+    matched_pattern: m.matched_pattern,
+    sentinel_text: m.text,
+    byte_length: Buffer.byteLength(m.text, "utf8"),
+  };
+  if (m.item_idx !== undefined) rec.item_idx = m.item_idx;
+  if (typeof includeNormalizedText === "string") {
+    rec.normalized_text = includeNormalizedText;
+  }
+  return rec;
+}
+
+function serializePartialMatch(m, redactLen) {
+  const rec = {
+    msg_idx: m.msg_idx,
+    block_idx: m.block_idx,
+    content_kind: m.content_kind,
+    byte_length: m.byte_length,
+  };
+  if (m.item_idx !== undefined) rec.item_idx = m.item_idx;
+  if (redactLen > 0) {
+    rec.prefix_64 = m.text.slice(0, redactLen);
+  }
+  return rec;
+}
+
+export function buildDiagnosticRecord(reqCtx, exact_matches, partial_matches, totalToolResults, opts = {}) {
+  const includeNormalized = opts.includeNormalized === true;
+  const canonicalText = opts.canonicalText;
+  const redactLen = typeof opts.redactLen === "number" ? opts.redactLen : DEFAULT_REDACT_LEN;
+  return {
+    ts: opts.ts || new Date().toISOString(),
+    session_id_hash: hashSessionId(reqCtx),
+    exact_matches: exact_matches.map((m) =>
+      serializeExactMatch(m, includeNormalized && typeof canonicalText === "string" ? canonicalText : null),
+    ),
+    partial_matches: partial_matches.map((m) => serializePartialMatch(m, redactLen)),
+    total_messages: Array.isArray(reqCtx?.body?.messages) ? reqCtx.body.messages.length : 0,
+    total_tool_results: totalToolResults,
+    model: reqCtx?.body?.model ?? null,
+  };
+}
+
+// --- I/O ---
+
+export async function appendDiagnosticRecord(path, record) {
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, JSON.stringify(record) + "\n");
+}
+
+// --- Stats shape ---
+
+function initStats() {
+  return {
+    diagnostic_enabled: false,
+    normalization_enabled: false,
+    sentinel_pattern_used: null, // first matched pattern source (Mode A only)
+    total_tool_results_scanned: 0,
+    exact_matches_count: 0,
+    partial_matches_count: 0,
+    sentinels_matched: 0, // exact + partial
+    sentinels_normalized: 0,
+    bytes_original: 0,
+    bytes_normalized: 0,
+    bytes_saved: 0,
+    diagnostic_records_written: 0,
+  };
+}
+
+// --- Stderr summary ---
+
+function emitStderrSummary(stats, dumpPath) {
+  const parts = [`matched=${stats.sentinels_matched}`];
+  if (stats.normalization_enabled) {
+    parts.push(`normalized=${stats.sentinels_normalized}`);
+    parts.push(`bytes=${stats.bytes_original}->${stats.bytes_normalized}`);
+    if (stats.sentinel_pattern_used) {
+      parts.push(`sentinel_pattern=${stats.sentinel_pattern_used === DEFAULT_EXACT_PATTERNS[0].source || stats.sentinel_pattern_used === DEFAULT_EXACT_PATTERNS[1].source ? "default" : "custom"}`);
+    }
+  }
+  if (stats.diagnostic_enabled) {
+    parts.push(`dump=${dumpPath}`);
+    if (!stats.normalization_enabled) parts.push("(normalize disabled)");
+  }
+  process.stderr.write(`[microcompact] ${parts.join(" ")}\n`);
+}
+
+// --- Orchestrator ---
+
+export async function runMicrocompactStability(reqCtx) {
+  const stats = initStats();
+  const dumpPath = getDumpPath();
+  const normalize = isNormalizeEnabled();
+  stats.diagnostic_enabled = !!dumpPath;
+  stats.normalization_enabled = normalize;
+
+  if (!dumpPath && !normalize) return stats;
+  if (!reqCtx || !reqCtx.body || !Array.isArray(reqCtx.body.messages)) return stats;
+
+  const extraPatterns = getCustomPatterns();
+  const extraPrefixes = getCustomPrefixes();
+  const { exact_matches, partial_matches, total_tool_results } = walkToolResultsForSentinels(
+    reqCtx.body.messages,
+    extraPatterns,
+    extraPrefixes,
+  );
+  stats.total_tool_results_scanned = total_tool_results;
+  stats.exact_matches_count = exact_matches.length;
+  stats.partial_matches_count = partial_matches.length;
+  stats.sentinels_matched = exact_matches.length + partial_matches.length;
+  if (exact_matches.length > 0) {
+    stats.sentinel_pattern_used = exact_matches[0].matched_pattern;
+  }
+
+  // Diagnostic dump runs FIRST (raw pre-normalization bytes). Mode B is
+  // redacted to prefix_64 by the serializer; Mode A captures full text.
+  if (dumpPath && (exact_matches.length > 0 || partial_matches.length > 0)) {
+    try {
+      const canonicalText = normalize ? getCanonicalText() : null;
+      const record = buildDiagnosticRecord(reqCtx, exact_matches, partial_matches, total_tool_results, {
+        includeNormalized: isIncludeNormalizedEnabled(),
+        canonicalText,
+        redactLen: getRedactLen(),
+      });
+      await appendDiagnosticRecord(dumpPath, record);
+      stats.diagnostic_records_written = 1;
+    } catch (err) {
+      debug(`dump write failed: ${err?.message ?? err}`);
+    }
+  }
+
+  // Normalization runs AFTER dump. Only Mode A matches are eligible.
+  if (normalize && exact_matches.length > 0) {
+    const canonicalText = getCanonicalText();
+    for (const m of exact_matches) {
+      stats.bytes_original += Buffer.byteLength(m.text, "utf8");
+      const ok = normalizeToolResultContent(reqCtx.body.messages, m, canonicalText);
+      if (ok) {
+        stats.bytes_normalized += Buffer.byteLength(canonicalText, "utf8");
+        stats.sentinels_normalized++;
+      }
+    }
+    stats.bytes_saved = stats.bytes_original - stats.bytes_normalized;
+  }
+
+  return stats;
+}
+
+// --- Extension contract ---
+
+export default {
+  name: "microcompact-stability",
+  description:
+    "Phase 1 microcompact cache stability — diagnostic capture of CC's " +
+    "time_based_microcompact sentinel + opt-in normalization to a canonical " +
+    "byte-stable form. Phase 2 (snapshot/restore) deferred to v3.5.0+.",
+  enabled: false, // overridden by extensions.json
+  order: 350,
+
+  async onRequest(ctx) {
+    try {
+      const stats = await runMicrocompactStability(ctx);
+      // Only attach telemetry / emit summary if we did something observable.
+      if (stats.diagnostic_enabled || stats.normalization_enabled) {
+        ctx.meta = ctx.meta || {};
+        ctx.meta.microcompactStats = stats;
+        if (stats.sentinels_matched > 0 || stats.diagnostic_enabled) {
+          // Summary on enabled invocations: always when we matched, or when
+          // diagnostic is on (so users can verify it's running with no matches).
+          if (stats.sentinels_matched > 0) {
+            emitStderrSummary(stats, getDumpPath());
+          }
+        }
+      }
+    } catch (err) {
+      debug(`onRequest unexpected: ${err?.message ?? err}`);
+    }
+  },
+};

package/proxy/extensions/ttl-management.mjs

@@ -33,7 +33,8 @@ export default {
 
     if (ttlValue === "none") return;
 
-    const ttlParam = ttlValue === "5m" ? "5m" : "1h";
+    const detectedTier = ctx.meta?._ttlTier || "1h";
+    const ttlParam = ttlValue === "5m" || detectedTier === "5m" ? "5m" : "1h";
 
     if (Array.isArray(body.system)) {
       body.system = body.system.map((block) => injectTtl(block, ttlParam));

package/proxy/extensions/ttl-tier-detect.mjs

@@ -0,0 +1,33 @@
+// ttl-tier-detect — port of preload.mjs:1815-1828 in-payload tier detection.
+//
+// Runs at order 75 (between read-only upstream-change-detection at 50 and
+// every cache_control mutator) so that downstream strips by fresh-session-sort
+// (250) and cache-control-normalize (400) cannot hide a ttl="5m" signal from
+// ttl-management at order 500.
+//
+// Pure detection. Sets ctx.meta._ttlTier. Does not mutate ctx.body.
+
+function detectExistingTier(body) {
+  const blocks = [
+    ...(Array.isArray(body?.system) ? body.system : []),
+    ...(Array.isArray(body?.messages)
+      ? body.messages.flatMap((m) => (Array.isArray(m?.content) ? m.content : []))
+      : []),
+  ];
+  for (const block of blocks) {
+    if (block?.cache_control?.ttl === "5m") return "5m";
+  }
+  return "1h";
+}
+
+export { detectExistingTier };
+
+export default {
+  name: "ttl-tier-detect",
+  description: "Detect existing TTL tier from incoming payload before cache_control normalization",
+  order: 75,
+
+  async onRequest(ctx) {
+    ctx.meta._ttlTier = detectExistingTier(ctx.body);
+  },
+};

package/proxy/extensions.json

@@ -1,4 +1,5 @@
 {
+  "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 },
@@ -7,7 +8,9 @@
   "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 },
   "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 },