claude-code-cache-fix 3.0.5 → 3.1.0

package/README.ko.md

@@ -125,7 +125,7 @@ VSIX 없이 수동 VS Code 래퍼를 설정하려면 [docs/preload-setup.md](doc
 
 **하는 것:** 캐시 버그 수정을 위해 발신 요청 구조(블록 순서, 핑거프린트, TTL, git-status)를 수정합니다. 모니터링을 위해 응답 헤더와 SSE 사용량 데이터를 읽습니다.
 
-**하지 않는 것:** 프록시 또는 인터셉터에서 네트워크 호출을 하지 않습니다. 모든 텔레메트리는 `~/.claude/` 아래 로컬 파일에 기록됩니다. [claude-code-meter](https://github.com/cnighswonger/claude-code-meter) 공유에 명시적으로 동의하지 않는 한 데이터가 외부로 전송되지 않습니다(별도 패키지, 대화형 동의 필요).
+**하지 않는 것:** 프록시 또는 인터셉터에서 네트워크 호출을 하지 않습니다. 모든 텔레메트리는 `~/.claude/` 아래 로컬 파일에 기록됩니다. 데이터는 사용자의 컴퓨터를 떠나지 않습니다.
 
 **공급망:** 프록시 모드: `proxy/extensions/`에 7개 소형 확장 모듈(각 200줄 미만). 프리로드 모드: 단일 비축소 파일(`preload.mjs`, ~1,700줄). 개발 의존성 1개(`zod`, 테스트 스키마 검증용). 설치 전 코드를 직접 검토하십시오. npm provenance로 각 버전이 소스 커밋에 연결됩니다.
 

package/README.md

@@ -162,7 +162,7 @@ For manual VS Code wrapper setup (without the VSIX), see [docs/preload-setup.md]
 
 **What it does:** Modifies outgoing request structure (block order, fingerprint, TTL, git-status) to fix cache bugs. Reads response headers and SSE usage data for monitoring.
 
-**What it does NOT do:** No network calls from the proxy or interceptor. All telemetry is written to local files under `~/.claude/`. No data leaves your machine unless you explicitly opt in to [claude-code-meter](https://github.com/cnighswonger/claude-code-meter) sharing (separate package, requires interactive consent).
+**What it does NOT do:** No network calls from the proxy or interceptor. All telemetry is written to local files under `~/.claude/`. No data leaves your machine.
 
 **Supply chain:** Proxy mode: 7 small extension modules in `proxy/extensions/` (each under 200 lines). Preload mode: single unminified file (`preload.mjs`, ~1,700 lines). One dev dependency (`zod` for schema validation in tests only). Review before installing. npm provenance links each published version to its source commit.
 
@@ -281,6 +281,8 @@ export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1
 
 Or add `"includeGitInstructions": false` to `~/.claude/settings.json`. Claude Code can still run `git status` via the Bash tool when it needs context. Community-validated by [@wadabum](https://github.com/cnighswonger/claude-code-cache-fix/issues/11): 18-token cache creation across git state changes (vs thousands without the flag).
 
+**Why we don't ship a proxy extension for this:** the proxy intercepts requests after Claude Code has already composed the system prompt — by then the volatile `git status` text is already part of the prefix that the model conditioned on in the previous turn, and stripping it post-hoc would itself bust the cache. The fix has to happen at the source. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1` prevents the injection before the prompt is composed, which is why the native flag is the right tool. Stripping post-hoc would also remove model-visible context that an explicit Bash call can recover, and would risk false-positive matches against assistant-written text.
+
 ## Image stripping (preload mode)
 
 Images read via the Read tool persist as base64 in conversation history, riding along on every subsequent API call. A single 500KB image costs ~62,500 tokens per turn on Opus 4.6, and **~85,000+ on Opus 4.7** due to the new tokenizer. Image stripping is strongly recommended on 4.7.

package/README.zh.md

@@ -137,7 +137,7 @@ NODE_OPTIONS="--import claude-code-cache-fix" claude
 
 **它做什么：** 修改出站请求结构（块排序、指纹、TTL、git-status）以修复缓存 bug。读取响应头和 SSE 使用量数据用于监控。
 
-**它不做什么：** 代理或拦截器不会发起网络调用。所有遥测数据写入 `~/.claude/` 下的本地文件。除非你明确选择加入 [claude-code-meter](https://github.com/cnighswonger/claude-code-meter) 共享（独立包，需要交互式同意），否则数据不会离开你的机器。
+**它不做什么：** 代理或拦截器不会发起网络调用。所有遥测数据写入 `~/.claude/` 下的本地文件。数据不会离开你的机器。
 
 **供应链：** 代理模式：7 个小型扩展模块在 `proxy/extensions/` 中（每个不到 200 行）。预加载模式：单个未压缩文件（`preload.mjs`，约 1,700 行）。一个开发依赖（`zod`，仅用于测试中的模式验证）。安装前请审查代码。npm 出处（provenance）将每个发布版本链接到其源代码提交。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.0.5",
+  "version": "3.1.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",

package/proxy/extensions/cache-control-normalize.mjs

@@ -24,6 +24,8 @@ function countUserCacheControlMarkers(body) {
   return n;
 }
 
+export { stripCacheControlMarkers, countUserCacheControlMarkers };
+
 export default {
   name: "cache-control-normalize",
   description: "Strip scattered cache_control markers from user messages and apply canonical placement",

package/proxy/extensions/content-strip.mjs

@@ -0,0 +1,89 @@
+const CONTINUE_TRAILER_TEXT = "Continue from where you left off.";
+
+const REMINDER_WRAP_REGEX = /^<system-reminder>\n([\s\S]*?)\n<\/system-reminder>\s*$/;
+const BOOKKEEPING_PATTERNS = [
+  /^Token usage: \d+\/\d+; \d+ remaining\s*$/,
+  /^Output tokens — turn: [^\n]+ · session: [^\n]+\s*$/,
+  /^USD budget: \$[\d.]+\/\$[\d.]+; \$[\d.]+ remaining\s*$/,
+  /^The task tools haven't been used recently\./,
+  /^The TodoWrite tool hasn't been used recently\./,
+  /^Remaining conversation turns: /,
+  /^Messages? until auto-compact: /,
+];
+
+function isContinueTrailerBlock(block) {
+  return (
+    !!block &&
+    typeof block === "object" &&
+    block.type === "text" &&
+    block.text === CONTINUE_TRAILER_TEXT
+  );
+}
+
+function isBookkeepingReminder(text) {
+  if (typeof text !== "string") return false;
+  const m = text.match(REMINDER_WRAP_REGEX);
+  if (!m) return false;
+  const inner = m[1];
+  for (const rx of BOOKKEEPING_PATTERNS) {
+    if (rx.test(inner)) return true;
+  }
+  return false;
+}
+
+function stripContentBlocks(messages) {
+  if (!Array.isArray(messages)) return { messages, stats: null };
+
+  let trailerCount = 0;
+  let reminderCount = 0;
+
+  const result = messages.map((msg) => {
+    if (msg.role !== "user" || !Array.isArray(msg.content)) return msg;
+
+    let msgTrailers = 0;
+    let msgReminders = 0;
+
+    const kept = msg.content.filter((block) => {
+      if (isContinueTrailerBlock(block)) {
+        msgTrailers++;
+        return false;
+      }
+      if (block.type === "text" && isBookkeepingReminder(block.text)) {
+        msgReminders++;
+        return false;
+      }
+      return true;
+    });
+
+    if (kept.length === 0 || kept.length === msg.content.length) return msg;
+
+    trailerCount += msgTrailers;
+    reminderCount += msgReminders;
+    return { ...msg, content: kept };
+  });
+
+  const total = trailerCount + reminderCount;
+  return {
+    messages: total > 0 ? result : messages,
+    stats: total > 0 ? { trailerCount, reminderCount } : null,
+  };
+}
+
+export { isContinueTrailerBlock, isBookkeepingReminder, stripContentBlocks };
+
+export default {
+  name: "content-strip",
+  description: "Strip continue trailers and bookkeeping system-reminders from user messages",
+  enabled: false,
+  order: 350,
+
+  async onRequest(ctx) {
+    if (!ctx.body.messages) return;
+
+    const { messages, stats } = stripContentBlocks(ctx.body.messages);
+    if (stats) {
+      ctx.body.messages = messages;
+      ctx.meta.contentStripStats = stats;
+    }
+  },
+};

package/proxy/extensions/deferred-tools-restore.mjs

@@ -0,0 +1,361 @@
+// deferred-tools-restore — preserve cache prefix across MCP reconnect race.
+//
+// PROBLEM (mirrored from preload.mjs ~429-518):
+// On `claude --continue`, if MCP servers haven't finished reconnecting before
+// CC fires the first post-resume request, the
+//   <system-reminder>The following deferred tools are now available via ToolSearch…</system-reminder>
+// block at msg[0] (or wherever the attachment lands post-compaction) shrinks
+// dramatically. ~40 tools collapse to a handful of CC built-ins, and CC
+// injects a trailing
+//   "The following deferred tools are no longer available (their MCP server
+//    disconnected). Do not search for them — ToolSearch will return no match:"
+// notice. That block change at the root of the message array busts the cache
+// at the very top — the entire ~940K prompt re-caches.
+//
+// FIX: Persist the clean (no-UNAVAILABLE-marker) form of the block. On a
+// subsequent request where the block has shrunk and contains the UNAVAILABLE
+// marker, substitute the persisted full bytes. Restore only if the snapshot
+// is STRICTLY LONGER than the current block — never downgrade to a stale
+// shorter snapshot.
+//
+// SNAPSHOT KEY (proxy-specific adaptation):
+// Preload uses process.cwd() because each preload runs in the CC process,
+// where cwd identifies the project. The proxy is a long-lived daemon; its
+// cwd is shared across all CC sessions on the host. To key per-project, the
+// proxy parses the cwd OUT of the system prompt content (CC injects
+// " - Primary working directory: <path>" in the # Environment section) and
+// keys on sha1("cwd:" + that path). Verified empirically against CC v2.1.117.
+//
+// FAIL-OPEN: If the cwd marker is absent (CC format drift, missing system
+// prompt), the extension no-ops the request entirely. Result: status quo
+// cache-bust, never silently restores the wrong block.
+
+import {
+  mkdir as _mkdir,
+  readFile as _readFile,
+  writeFile as _writeFile,
+  rename as _rename,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+const SKIP = process.env.CACHE_FIX_SKIP_DEFERRED_TOOLS_RESTORE === "1";
+const DEBUG = process.env.CACHE_FIX_DEBUG === "1";
+
+const AVAILABLE_MARKER =
+  "The following deferred tools are now available via ToolSearch";
+const UNAVAILABLE_MARKER =
+  "The following deferred tools are no longer available";
+
+const DEFAULT_FS = {
+  mkdir: _mkdir,
+  readFile: _readFile,
+  writeFile: _writeFile,
+  rename: _rename,
+};
+
+function getSnapshotDir() {
+  return join(homedir(), ".claude", "cache-fix-state");
+}
+
+function debug(msg) {
+  if (DEBUG) process.stderr.write(`[deferred-tools-restore] ${msg}\n`);
+}
+
+/**
+ * Extract the working-directory path from CC's system prompt.
+ * Returns the parsed path string, or null if the marker is not found OR
+ * the prompt structure is ambiguous (multiple valid env sections).
+ *
+ * STRICT STRUCTURAL PARSER (line-based, not regex-window):
+ *
+ * Recognizes a valid # Environment section ONLY when ALL of these hold:
+ *   1. A line that is exactly `# Environment` (whitespace-trimmed)
+ *   2. The next non-blank line is exactly the CC intro line:
+ *      `You have been invoked in the following environment:`
+ *   3. The marker appears in a bullet line (`- Primary working directory: ...`)
+ *      within the bullet list immediately following the intro line — bounded
+ *      by the first blank line or first non-bullet line.
+ *
+ * Only the conjunction of all three rejects the false positives Codex flagged:
+ *   - bare `# Environment` mention in narrative/code (fails rule 2)
+ *   - code-fenced `Primary working directory:` example without the env header
+ *     (fails rule 1)
+ *   - a fake marker line elsewhere in the same block but not in a bullet
+ *     list immediately following the intro (fails rule 3)
+ *
+ * AMBIGUITY GUARD: if MULTIPLE distinct valid env sections produce different
+ * cwd values (across blocks or within one block), refuse to pick — return
+ * null. The fail-open path (extension no-ops the request) is strictly safer
+ * than restoring with the wrong snapshot key.
+ *
+ * Accepts:
+ *   - array of content blocks (CC's normal shape): walks .text fields in order
+ *   - a single string (rare; older clients): scans directly
+ *   - anything else: returns null
+ */
+const ENV_HEADER_LINE = "# Environment";
+const ENV_INTRO_LINE = "You have been invoked in the following environment:";
+const CWD_BULLET_RE = /^-\s+Primary working directory:\s*(.+?)\s*$/;
+
+function parseAllCwdsFromBlock(text) {
+  const found = [];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() !== ENV_HEADER_LINE) continue;
+    // Skip blank lines after the header (CC emits exactly one intro line
+    // immediately following, but be tolerant of whitespace).
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() === "") j++;
+    if (j >= lines.length) continue;
+    if (lines[j].trim() !== ENV_INTRO_LINE) continue;
+    // Walk the bullet list following the intro line; first cwd bullet wins
+    // for this section. A blank line or non-bullet line ends the section.
+    for (let k = j + 1; k < lines.length; k++) {
+      const trimmed = lines[k].trimStart();
+      if (lines[k].trim() === "") break;
+      if (!trimmed.startsWith("-")) break;
+      const m = trimmed.match(CWD_BULLET_RE);
+      if (m && m[1]) {
+        found.push(m[1]);
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+function extractCwdFromSystem(system) {
+  if (!system) return null;
+  const texts = [];
+  if (typeof system === "string") {
+    texts.push(system);
+  } else if (Array.isArray(system)) {
+    for (const block of system) {
+      if (block && typeof block === "object" && typeof block.text === "string") {
+        texts.push(block.text);
+      }
+    }
+  } else {
+    return null;
+  }
+  const seen = new Set();
+  for (const t of texts) {
+    const matches = parseAllCwdsFromBlock(t);
+    for (const m of matches) {
+      seen.add(m);
+      if (seen.size > 1) return null; // ambiguous → no-op
+    }
+  }
+  if (seen.size === 1) return [...seen][0];
+  return null;
+}
+
+function deriveSnapshotKey(cwd) {
+  return createHash("sha1").update(`cwd:${cwd}`).digest("hex").slice(0, 16);
+}
+
+/**
+ * Locate the deferred-tools attachment block in body.messages.
+ * Only inspects user messages (skips assistant so the agent quoting the
+ * AVAILABLE marker verbatim doesn't trigger a false match).
+ * Returns { msgIdx, blockIdx, text } or null.
+ */
+function findDeferredToolsBlockInBody(body) {
+  if (!body || !Array.isArray(body.messages)) return null;
+  for (let m = 0; m < body.messages.length; m++) {
+    const msg = body.messages[m];
+    if (!msg || msg.role !== "user" || !Array.isArray(msg.content)) continue;
+    for (let i = 0; i < msg.content.length; i++) {
+      const b = msg.content[i];
+      if (
+        b &&
+        b.type === "text" &&
+        typeof b.text === "string" &&
+        b.text.includes(AVAILABLE_MARKER)
+      ) {
+        return { msgIdx: m, blockIdx: i, text: b.text };
+      }
+    }
+  }
+  return null;
+}
+
+// Atomic write (same lesson as prefix-diff): unique tmp per invocation so
+// concurrent calls don't collide on a shared .tmp path.
+async function atomicWriteText(finalPath, data, fs) {
+  const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.${Math.random()
+    .toString(36)
+    .slice(2, 10)}.tmp`;
+  await fs.writeFile(tmpPath, data);
+  await fs.rename(tmpPath, finalPath);
+}
+
+/**
+ * Persist a snapshot of the clean deferred-tools block.
+ *
+ * @param {string} text  The full block text to persist.
+ * @param {object} options
+ * @param {string} options.dir  Snapshot directory.
+ * @param {string} options.key  Snapshot key (from deriveSnapshotKey).
+ * @param {object} [options.fs] fs/promises overrides for tests.
+ * @returns {Promise<{persisted: boolean, bytes: number, path: string}>}
+ */
+async function persistDeferredTools(text, options) {
+  const dir = options.dir;
+  const key = options.key;
+  const fs = { ...DEFAULT_FS, ...(options.fs || {}) };
+  const path = join(dir, `deferred-tools-${key}.txt`);
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await atomicWriteText(path, text, fs);
+    return { persisted: true, bytes: Buffer.byteLength(text, "utf-8"), path };
+  } catch (err) {
+    debug(`persist failed at ${path}: ${err?.message ?? err}`);
+    return { persisted: false, bytes: 0, path };
+  }
+}
+
+/**
+ * Read and validate a snapshot. Returns the snapshot text on success, null
+ * otherwise. Validation:
+ *  - file exists and is readable
+ *  - byte length >= AVAILABLE_MARKER length (sanity floor)
+ *  - content contains the AVAILABLE marker (defense in depth against a
+ *    truncated-but-readable file passing only the length check)
+ */
+async function restoreDeferredTools(options) {
+  const dir = options.dir;
+  const key = options.key;
+  const fs = { ...DEFAULT_FS, ...(options.fs || {}) };
+  const path = join(dir, `deferred-tools-${key}.txt`);
+  let snapshot;
+  try {
+    snapshot = await fs.readFile(path, "utf-8");
+  } catch (err) {
+    if (err && err.code !== "ENOENT") {
+      debug(`snapshot read failed at ${path}: ${err?.message ?? err}`);
+    }
+    return null;
+  }
+  if (typeof snapshot !== "string") return null;
+  if (snapshot.length < AVAILABLE_MARKER.length) {
+    debug(`snapshot rejected (too short: ${snapshot.length} bytes) at ${path}`);
+    return null;
+  }
+  if (!snapshot.includes(AVAILABLE_MARKER)) {
+    debug(`snapshot rejected (missing AVAILABLE marker) at ${path}`);
+    return null;
+  }
+  // Defense in depth: persisted snapshots should be clean by construction
+  // (we only persist when !hasUnavail), but if a snapshot ever contains the
+  // UNAVAILABLE marker we refuse to restore it — restoring a "no longer
+  // available" block would be worse than no restore.
+  if (snapshot.includes(UNAVAILABLE_MARKER)) {
+    debug(`snapshot rejected (contains UNAVAILABLE marker, not a clean baseline) at ${path}`);
+    return null;
+  }
+  return snapshot;
+}
+
+export {
+  extractCwdFromSystem,
+  deriveSnapshotKey,
+  findDeferredToolsBlockInBody,
+  persistDeferredTools,
+  restoreDeferredTools,
+  AVAILABLE_MARKER,
+  UNAVAILABLE_MARKER,
+};
+
+export default {
+  name: "deferred-tools-restore",
+  description:
+    "Persist and restore the deferred-tools attachment block across sessions to prevent MCP-reconnect-race cache busts at resume time",
+  enabled: true,
+  order: 350,
+
+  async onRequest(ctx) {
+    if (SKIP) return;
+    if (!ctx || !ctx.body) return;
+    const body = ctx.body;
+
+    // 1. Parse cwd from system. No marker → no-op (honest degradation).
+    const cwd = extractCwdFromSystem(body.system);
+    if (!cwd) {
+      ctx.meta = ctx.meta || {};
+      ctx.meta.deferredToolsRestoreStats = { action: "skipped", reason: "no-cwd" };
+      return;
+    }
+    const key = deriveSnapshotKey(cwd);
+
+    // 2-4. Locate the deferred-tools block.
+    const found = findDeferredToolsBlockInBody(body);
+    if (!found) {
+      ctx.meta = ctx.meta || {};
+      ctx.meta.deferredToolsRestoreStats = { action: "skipped", reason: "no-block", key };
+      return;
+    }
+
+    const dir = getSnapshotDir();
+    const hasUnavail = found.text.includes(UNAVAILABLE_MARKER);
+
+    if (!hasUnavail) {
+      // 5. Clean baseline → persist.
+      const result = await persistDeferredTools(found.text, { dir, key });
+      ctx.meta = ctx.meta || {};
+      ctx.meta.deferredToolsRestoreStats = {
+        action: result.persisted ? "persisted" : "skipped",
+        bytes: result.bytes,
+        key,
+      };
+      if (result.persisted) {
+        process.stderr.write(
+          `[deferred-tools-restore] persisted ${result.bytes} bytes (key=${key})\n`,
+        );
+      }
+      return;
+    }
+
+    // 6. Block has UNAVAILABLE marker → attempt restore.
+    const snapshot = await restoreDeferredTools({ dir, key });
+    if (!snapshot) {
+      ctx.meta = ctx.meta || {};
+      ctx.meta.deferredToolsRestoreStats = { action: "skipped", reason: "no-snapshot", key };
+      return;
+    }
+
+    // Strictly-longer guard. Equal-length snapshots are not restored.
+    if (snapshot.length <= found.text.length) {
+      ctx.meta = ctx.meta || {};
+      ctx.meta.deferredToolsRestoreStats = {
+        action: "skipped",
+        reason: "snapshot-not-longer",
+        key,
+        snapshotBytes: snapshot.length,
+        currentBytes: found.text.length,
+      };
+      return;
+    }
+
+    // Substitute. Build new content array and new message; do not mutate
+    // the original arrays / objects.
+    const targetMsg = body.messages[found.msgIdx];
+    const newContent = targetMsg.content.slice();
+    newContent[found.blockIdx] = { ...newContent[found.blockIdx], text: snapshot };
+    body.messages[found.msgIdx] = { ...targetMsg, content: newContent };
+
+    ctx.meta = ctx.meta || {};
+    ctx.meta.deferredToolsRestoreStats = {
+      action: "restored",
+      bytes: snapshot.length,
+      previousBytes: found.text.length,
+      key,
+    };
+    process.stderr.write(
+      `[deferred-tools-restore] restored ${found.text.length}→${snapshot.length} bytes ` +
+        `at msg[${found.msgIdx}].content[${found.blockIdx}] (key=${key})\n`,
+    );
+  },
+};

package/proxy/extensions/fingerprint-strip.mjs

@@ -88,6 +88,8 @@ function stabilizeFingerprint(system, messages) {
   return { attrIdx, newText, oldFingerprint, stableFingerprint };
 }
 
+export { computeFingerprint, extractRealUserMessageText, extractFirstMessageText, stabilizeFingerprint };
+
 export default {
   name: "fingerprint-strip",
   description: "Stabilize cc_version fingerprint in system prompt for cache prefix consistency",

package/proxy/extensions/fresh-session-sort.mjs

@@ -86,6 +86,8 @@ function fixBlockText(blockType, text) {
   return pinBlockContent(blockType, fixed);
 }
 
+export { isSystemReminder, isHooksBlock, isSkillsBlock, isDeferredToolsBlock, isMcpBlock, isRelocatableBlock, isClearArtifact, sortSkillsBlock, sortDeferredToolsBlock, stripSessionKnowledge, pinBlockContent, getBlockType, fixBlockText };
+
 export default {
   name: "fresh-session-sort",
   description: "Relocate scattered blocks to messages[0] in deterministic fresh-session order",

package/proxy/extensions/identity-normalization.mjs

@@ -76,6 +76,8 @@ function isBookkeepingReminder(text) {
   return false;
 }
 
+export { pinBlockContent, stripSessionKnowledge, normalizeSessionStartText, isContinueTrailerBlock, isBookkeepingReminder };
+
 export default {
   name: "identity-normalization",
   description: "Normalize volatile identity fields (SessionStart, Continue trailers, bookkeeping) for cache stability",

package/proxy/extensions/image-strip.mjs

@@ -0,0 +1,83 @@
+const KEEP_LAST = parseInt(process.env.CACHE_FIX_IMAGE_KEEP_LAST || "0", 10);
+const PLACEHOLDER = "[image stripped from history — file may still be on disk]";
+
+function stripOldToolResultImages(messages, keepLast) {
+  if (!keepLast || keepLast <= 0 || !Array.isArray(messages)) {
+    return { messages, stats: null };
+  }
+
+  const userMsgIndices = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].role === "user") userMsgIndices.push(i);
+  }
+
+  if (userMsgIndices.length <= keepLast) {
+    return { messages, stats: null };
+  }
+
+  const cutoffIdx = userMsgIndices[userMsgIndices.length - keepLast];
+
+  let strippedCount = 0;
+  let strippedBytes = 0;
+
+  const result = messages.map((msg, msgIdx) => {
+    if (msg.role !== "user" || msgIdx >= cutoffIdx || !Array.isArray(msg.content)) {
+      return msg;
+    }
+
+    let msgModified = false;
+    const newContent = msg.content.map((block) => {
+      if (block.type === "tool_result" && Array.isArray(block.content)) {
+        let toolModified = false;
+        const newToolContent = block.content.map((item) => {
+          if (item.type === "image") {
+            strippedCount++;
+            if (item.source?.data) {
+              strippedBytes += item.source.data.length;
+            }
+            toolModified = true;
+            return { type: "text", text: PLACEHOLDER };
+          }
+          return item;
+        });
+        if (toolModified) {
+          msgModified = true;
+          return { ...block, content: newToolContent };
+        }
+      }
+      return block;
+    });
+
+    return msgModified ? { ...msg, content: newContent } : msg;
+  });
+
+  const stats = strippedCount > 0
+    ? { strippedCount, strippedBytes, estimatedTokens: Math.ceil(strippedBytes * 0.125) }
+    : null;
+
+  return { messages: strippedCount > 0 ? result : messages, stats };
+}
+
+export { stripOldToolResultImages, PLACEHOLDER };
+
+export default {
+  name: "image-strip",
+  description: "Strip base64 images from old tool results to reduce token waste",
+  enabled: false,
+  order: 150,
+
+  async onRequest(ctx) {
+    const keepLast = parseInt(ctx.meta.imageKeepLast ?? KEEP_LAST, 10);
+    if (!keepLast || keepLast <= 0) return;
+    if (!ctx.body.messages) return;
+
+    const { messages, stats } = stripOldToolResultImages(ctx.body.messages, keepLast);
+    if (stats) {
+      ctx.body.messages = messages;
+      ctx.meta.imageStripStats = stats;
+      process.stderr.write(
+        `[image-strip] stripped ${stats.strippedCount} images (~${stats.estimatedTokens} tokens saved)\n`
+      );
+    }
+  },
+};

package/proxy/extensions/output-efficiency-rewrite.mjs

@@ -0,0 +1,64 @@
+const SECTION_HEADER = "# Output efficiency";
+const REPLACEMENT_RAW = process.env.CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT || "";
+
+function normalizeReplacement(text) {
+  const trimmed = typeof text === "string" ? text.trim() : "";
+  if (!trimmed) return "";
+  return trimmed.startsWith(SECTION_HEADER) ? trimmed : `${SECTION_HEADER}\n\n${trimmed}`;
+}
+
+function replaceSection(text, replacement) {
+  const start = text.indexOf(SECTION_HEADER);
+  if (start === -1) return null;
+
+  const afterHeader = start + SECTION_HEADER.length;
+  const remainder = text.slice(afterHeader);
+  const nextHeadingMatch = remainder.match(/\n# [^\n]+/);
+
+  if (!nextHeadingMatch || nextHeadingMatch.index == null) {
+    return text.slice(0, start) + replacement;
+  }
+
+  const nextHeadingStart = afterHeader + nextHeadingMatch.index + 1;
+  return text.slice(0, start) + replacement + "\n\n" + text.slice(nextHeadingStart);
+}
+
+function rewriteOutputEfficiency(system, replacement) {
+  if (!Array.isArray(system) || !replacement) return null;
+
+  let changed = false;
+  const rewritten = system.map((block) => {
+    if (block?.type !== "text" || typeof block.text !== "string" || !block.text.includes(SECTION_HEADER)) {
+      return block;
+    }
+
+    const nextText = replaceSection(block.text, replacement);
+    if (!nextText || nextText === block.text) return block;
+
+    changed = true;
+    return { ...block, text: nextText };
+  });
+
+  return changed ? rewritten : null;
+}
+
+export { normalizeReplacement, replaceSection, rewriteOutputEfficiency, SECTION_HEADER };
+
+export default {
+  name: "output-efficiency-rewrite",
+  description: "Replace Claude Code's # Output efficiency system prompt section with custom text",
+  enabled: false,
+  order: 90,
+
+  async onRequest(ctx) {
+    const raw = ctx.meta.outputEfficiencyReplacement ?? REPLACEMENT_RAW;
+    const replacement = normalizeReplacement(raw);
+    if (!replacement) return;
+    if (!ctx.body.system) return;
+
+    const result = rewriteOutputEfficiency(ctx.body.system, replacement);
+    if (result) {
+      ctx.body.system = result;
+    }
+  },
+};

package/proxy/extensions/prefix-diff.mjs

@@ -0,0 +1,277 @@
+// prefix-diff — diagnostic extension for hunting cache-bust sources.
+//
+// On every request, snapshots a small projection of the prefix (system
+// prompt + tools + first 5 messages) and writes it to
+// `~/.claude/cache-fix-snapshots/<key>-last.json`. If a prior snapshot
+// exists and differs, also writes a `<key>-diff.json` and emits a
+// one-line stderr summary.
+//
+// No request mutation. The diagnostic is fail-open: any I/O error is
+// swallowed silently in production. Set CACHE_FIX_DEBUG=1 to also log
+// swallowed errors so silent failures stay observable.
+//
+// Adaptation from preload's `snapshotPrefix(payload)` (preload.mjs ~1656):
+// preload fired the diff once per process restart. The proxy is long-lived
+// and supports hot-reload, so we drop the "first call" gate and run the
+// diff per call. Trade-off: more disk writes, but each is tiny and the
+// diagnostic value is higher (drift visible across every turn, not just
+// at startup).
+
+import {
+  mkdir as _mkdir,
+  readFile as _readFile,
+  writeFile as _writeFile,
+  rename as _rename,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+const ENABLED = process.env.CACHE_FIX_PREFIXDIFF === "1";
+const DEBUG = process.env.CACHE_FIX_DEBUG === "1";
+
+const DEFAULT_FS = {
+  mkdir: _mkdir,
+  readFile: _readFile,
+  writeFile: _writeFile,
+  rename: _rename,
+};
+
+function getSnapshotDir() {
+  return join(homedir(), ".claude", "cache-fix-snapshots");
+}
+
+function debug(msg) {
+  if (DEBUG) process.stderr.write(`[prefix-diff] ${msg}\n`);
+}
+
+function computeSessionKey(system) {
+  return createHash("sha256")
+    .update(JSON.stringify(system).slice(0, 2000))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+function computeToolsHash(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return "none";
+  // Match preload behavior: hash unsorted tool names so order changes
+  // surface as hash mismatches (a real cache-bust signal).
+  return createHash("sha256")
+    .update(JSON.stringify(tools.map((t) => t?.name ?? "")))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+function computeSystemHash(system) {
+  if (!system) return "none";
+  return createHash("sha256")
+    .update(JSON.stringify(system))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+// Project the first 5 user/assistant messages: strip cache_control,
+// truncate text >500 chars with `...[N chars]` marker. Pure: returns
+// new objects, never mutates input.
+function truncatePrefixMessages(messages) {
+  if (!Array.isArray(messages)) return [];
+  return messages.slice(0, 5).map((msg) => {
+    if (!msg || !Array.isArray(msg.content)) {
+      return { role: msg?.role, content: msg?.content };
+    }
+    const cleanedContent = msg.content.map((block) => {
+      if (!block || typeof block !== "object") return block;
+      const { cache_control, ...rest } = block;
+      if (typeof rest.text === "string" && rest.text.length > 500) {
+        return {
+          ...rest,
+          text: rest.text.slice(0, 500) + `...[${rest.text.length} chars]`,
+        };
+      }
+      return rest;
+    });
+    return { role: msg.role, content: cleanedContent };
+  });
+}
+
+function buildSnapshot(payload) {
+  if (!payload || !payload.system) return null;
+  return {
+    timestamp: new Date().toISOString(),
+    messageCount: Array.isArray(payload.messages) ? payload.messages.length : 0,
+    toolsHash: computeToolsHash(payload.tools),
+    systemHash: computeSystemHash(payload.system),
+    prefixMessages: truncatePrefixMessages(payload.messages),
+  };
+}
+
+function computeDiff(prev, current) {
+  const diff = {
+    timestamp: current.timestamp,
+    prevTimestamp: prev.timestamp,
+    toolsMatch: prev.toolsHash === current.toolsHash,
+    systemMatch: prev.systemHash === current.systemHash,
+    messageCountPrev: prev.messageCount,
+    messageCountNow: current.messageCount,
+    prefixDiffs: [],
+  };
+  const prevMsgs = Array.isArray(prev.prefixMessages) ? prev.prefixMessages : [];
+  const nowMsgs = Array.isArray(current.prefixMessages) ? current.prefixMessages : [];
+  const maxIdx = Math.max(prevMsgs.length, nowMsgs.length);
+  for (let i = 0; i < maxIdx; i++) {
+    const prevSer = JSON.stringify(prevMsgs[i] ?? null);
+    const nowSer = JSON.stringify(nowMsgs[i] ?? null);
+    if (prevSer !== nowSer) {
+      diff.prefixDiffs.push({
+        index: i,
+        prev: prevMsgs[i] ?? null,
+        now: nowMsgs[i] ?? null,
+      });
+    }
+  }
+  return diff;
+}
+
+function diffHasChanges(diff) {
+  return (
+    diff.prefixDiffs.length > 0 ||
+    !diff.toolsMatch ||
+    !diff.systemMatch ||
+    diff.messageCountPrev !== diff.messageCountNow
+  );
+}
+
+// Atomic write: stage to a unique-per-invocation .tmp, then rename to
+// final path. The unique suffix is essential under concurrency — two
+// parallel callers writing to the same finalPath would otherwise share
+// a single .tmp and corrupt each other's content.
+//
+// On rename failure the prior final-path file (if any) remains intact.
+// The orphan .tmp persists on disk — because each invocation uses a
+// unique temp name, later calls do NOT implicitly overwrite it. This is
+// a small leak (accepted: failures are rare, files are tiny) rather than
+// a correctness issue. A follow-up could add best-effort cleanup.
+async function atomicWriteJson(finalPath, obj, fs) {
+  const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.${Math.random()
+    .toString(36)
+    .slice(2, 10)}.tmp`;
+  await fs.writeFile(tmpPath, JSON.stringify(obj, null, 2));
+  await fs.rename(tmpPath, finalPath);
+}
+
+/**
+ * Snapshot the prefix of `payload` and diff against the prior snapshot.
+ *
+ * Pure-ish: never throws, never mutates `payload`. All I/O is gated by
+ * try/catch; failures are debug-logged when CACHE_FIX_DEBUG=1.
+ *
+ * @param {object} payload  The request body (system, tools, messages).
+ * @param {object} options
+ * @param {string} [options.dir] Snapshot directory. Defaults to ~/.claude/cache-fix-snapshots.
+ * @param {object} [options.fs]  fs/promises overrides for tests:
+ *                               { mkdir, readFile, writeFile, rename }.
+ *                               Any subset replaces the corresponding default.
+ * @returns {Promise<{ key, wroteSnapshot, wroteDiff } | null>} Result for tests; null if no system.
+ */
+async function snapshotPrefix(payload, options = {}) {
+  const current = buildSnapshot(payload);
+  if (!current) return null;
+
+  const dir = options.dir || getSnapshotDir();
+  const fs = { ...DEFAULT_FS, ...(options.fs || {}) };
+
+  const sessionKey = computeSessionKey(payload.system);
+  const lastPath = join(dir, `${sessionKey}-last.json`);
+  const diffPath = join(dir, `${sessionKey}-diff.json`);
+
+  // Ensure directory exists. mkdir failure aborts — without dir, nothing
+  // else can succeed.
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch (err) {
+    debug(`mkdir failed for ${dir}: ${err?.message ?? err}`);
+    return { key: sessionKey, wroteSnapshot: false, wroteDiff: false };
+  }
+
+  // Read prior snapshot if it exists. Missing file is normal; corrupt
+  // file is treated as no prior (skip diff, proceed to overwrite).
+  let prev = null;
+  try {
+    const txt = await fs.readFile(lastPath, "utf-8");
+    prev = JSON.parse(txt);
+  } catch (err) {
+    if (err && err.code !== "ENOENT") {
+      debug(`prior snapshot unreadable at ${lastPath}: ${err?.message ?? err}`);
+    }
+  }
+
+  // Compute and write diff if anything changed.
+  let wroteDiff = false;
+  if (prev) {
+    const diff = computeDiff(prev, current);
+    if (diffHasChanges(diff)) {
+      try {
+        await atomicWriteJson(diffPath, diff, fs);
+        wroteDiff = true;
+        // Always log the summary line when a diff fires (not just under
+        // CACHE_FIX_DEBUG) — this is the diagnostic's whole purpose.
+        process.stderr.write(
+          `[prefix-diff] ${sessionKey}: ${diff.prefixDiffs.length} differences, ` +
+            `tools=${diff.toolsMatch ? "match" : "DIFFER"}, ` +
+            `system=${diff.systemMatch ? "match" : "DIFFER"}, ` +
+            `messages=${diff.messageCountPrev}→${diff.messageCountNow}\n`,
+        );
+      } catch (err) {
+        debug(`diff write failed at ${diffPath}: ${err?.message ?? err}`);
+      }
+    }
+  }
+
+  // Always write the new snapshot atomically so the next call has a
+  // fresh baseline. On failure, prior snapshot is intact.
+  let wroteSnapshot = false;
+  try {
+    await atomicWriteJson(lastPath, current, fs);
+    wroteSnapshot = true;
+  } catch (err) {
+    debug(`snapshot write failed at ${lastPath}: ${err?.message ?? err}`);
+  }
+
+  return { key: sessionKey, wroteSnapshot, wroteDiff };
+}
+
+// The named exports below are internal test seams, not part of the
+// proxy extension contract. Pipeline loading consumes only `default`.
+// They're exposed so tests can call the helpers directly with their own
+// options (tmpdir, failing fs mocks) instead of mutating process env or
+// monkey-patching node:fs/promises at module scope.
+export {
+  snapshotPrefix,
+  buildSnapshot,
+  computeDiff,
+  computeSessionKey,
+  truncatePrefixMessages,
+  diffHasChanges,
+};
+
+export default {
+  name: "prefix-diff",
+  description:
+    "Snapshot prefix (first 5 msgs + system + tools) and diff against previous run for cache-bust hunting",
+  // Always loaded; gated at runtime by CACHE_FIX_PREFIXDIFF=1 inside onRequest.
+  // This matches the acceptance criteria (env var alone activates) — the
+  // extension is cheap to load (one no-op check per request when disabled).
+  enabled: true,
+  order: 680,
+
+  async onRequest(ctx) {
+    if (!ENABLED) return;
+    if (!ctx || !ctx.body) return;
+    // snapshotPrefix never throws; double-belt try/catch is defense in depth.
+    try {
+      await snapshotPrefix(ctx.body);
+    } catch (err) {
+      debug(`onRequest unexpected: ${err?.message ?? err}`);
+    }
+  },
+};

package/proxy/extensions/smoosh-split.mjs

@@ -0,0 +1,68 @@
+const TRAILING_SMOOSH = /\n\n(<system-reminder>\n(?:(?!<\/system-reminder>)[\s\S])*?\n<\/system-reminder>)\s*$/;
+
+function splitSmooshedReminders(messages) {
+  if (!Array.isArray(messages)) return { messages, stats: null };
+
+  let totalPeeled = 0;
+
+  const result = messages.map((msg) => {
+    if (msg.role !== "user" || !Array.isArray(msg.content)) return msg;
+
+    const out = [];
+    const peeledReminders = [];
+    let mutated = false;
+
+    for (const block of msg.content) {
+      if (block?.type === "tool_result" && typeof block.content === "string") {
+        const reminders = [];
+        let s = block.content;
+        while (true) {
+          const m = s.match(TRAILING_SMOOSH);
+          if (!m) break;
+          reminders.unshift(m[1]);
+          s = s.slice(0, m.index);
+        }
+        if (reminders.length > 0) {
+          out.push({ ...block, content: s });
+          for (const r of reminders) peeledReminders.push({ type: "text", text: r });
+          totalPeeled += reminders.length;
+          mutated = true;
+          continue;
+        }
+      }
+      out.push(block);
+    }
+
+    if (mutated) {
+      return { ...msg, content: [...out, ...peeledReminders] };
+    }
+    return msg;
+  });
+
+  return {
+    messages: totalPeeled > 0 ? result : messages,
+    stats: totalPeeled > 0 ? { peeled: totalPeeled } : null,
+  };
+}
+
+export { splitSmooshedReminders, TRAILING_SMOOSH };
+
+export default {
+  name: "smoosh-split",
+  description: "Peel smooshed system-reminders from tool_result content into standalone blocks",
+  enabled: false,
+  order: 320,
+
+  async onRequest(ctx) {
+    if (!ctx.body.messages) return;
+
+    const { messages, stats } = splitSmooshedReminders(ctx.body.messages);
+    if (stats) {
+      ctx.body.messages = messages;
+      ctx.meta.smooshSplitStats = stats;
+      process.stderr.write(
+        `[smoosh-split] peeled ${stats.peeled} reminder(s) from tool_result.content\n`
+      );
+    }
+  },
+};

package/proxy/extensions/sort-stabilization.mjs

@@ -28,6 +28,8 @@ function isDeferredToolsBlock(text) {
   return typeof text === "string" && text.includes("deferred tools are now available");
 }
 
+export { sortSkillsBlock, sortDeferredToolsBlock, isSkillsBlock, isDeferredToolsBlock };
+
 export default {
   name: "sort-stabilization",
   description: "Deterministic ordering of skills, deferred tools, and tool definitions",

package/proxy/extensions/tool-input-normalize.mjs

@@ -0,0 +1,73 @@
+function normalizeToolUseInputs(body) {
+  if (!body || typeof body !== "object") return 0;
+  if (!Array.isArray(body.messages) || !Array.isArray(body.tools)) return 0;
+
+  const toolSchemas = Object.create(null);
+  for (const tool of body.tools) {
+    if (!tool || typeof tool !== "object") continue;
+    const name = tool.name;
+    if (typeof name !== "string") continue;
+    const props = tool.input_schema?.properties;
+    if (!props || typeof props !== "object") continue;
+    toolSchemas[name] = Object.keys(props);
+  }
+
+  let modified = 0;
+  for (const msg of body.messages) {
+    if (!msg || msg.role !== "assistant") continue;
+    if (!Array.isArray(msg.content)) continue;
+    for (let i = 0; i < msg.content.length; i++) {
+      const block = msg.content[i];
+      if (!block || block.type !== "tool_use") continue;
+      if (!block.input || typeof block.input !== "object" || Array.isArray(block.input)) continue;
+      const schemaKeys = toolSchemas[block.name];
+      if (!schemaKeys) continue;
+
+      const currentKeys = Object.keys(block.input);
+      const schemaKeySet = new Set(schemaKeys);
+      const hasExtras = currentKeys.some((k) => !schemaKeySet.has(k));
+
+      const presentSchemaKeys = schemaKeys.filter((k) =>
+        Object.prototype.hasOwnProperty.call(block.input, k)
+      );
+      const currentInSchema = currentKeys.filter((k) => schemaKeySet.has(k));
+
+      let orderDiffers = presentSchemaKeys.length !== currentInSchema.length;
+      if (!orderDiffers) {
+        for (let j = 0; j < presentSchemaKeys.length; j++) {
+          if (presentSchemaKeys[j] !== currentInSchema[j]) {
+            orderDiffers = true;
+            break;
+          }
+        }
+      }
+
+      if (!hasExtras && !orderDiffers) continue;
+
+      const newInput = {};
+      for (const k of presentSchemaKeys) {
+        newInput[k] = block.input[k];
+      }
+      msg.content[i] = { ...block, input: newInput };
+      modified++;
+    }
+  }
+  return modified;
+}
+
+export { normalizeToolUseInputs };
+
+export default {
+  name: "tool-input-normalize",
+  description: "Normalize tool_use input field ordering to match schema for cache stability",
+  enabled: false,
+  order: 280,
+
+  async onRequest(ctx) {
+    if (!ctx.body.messages || !ctx.body.tools) return;
+    const count = normalizeToolUseInputs(ctx.body);
+    if (count > 0) {
+      ctx.meta.toolInputNormalizeCount = count;
+    }
+  },
+};

package/proxy/extensions/ttl-management.mjs

@@ -17,6 +17,8 @@ function injectTtl(block, ttlParam) {
   return block;
 }
 
+export { detectRequestType, injectTtl };
+
 export default {
   name: "ttl-management",
   description: "Inject correct TTL on cache_control markers based on detected tier",

package/proxy/extensions/usage-log.mjs

@@ -0,0 +1,46 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const LOG_PATH = process.env.CACHE_FIX_USAGE_LOG || join(homedir(), ".claude", "usage.jsonl");
+
+function buildRecord(meta, telemetry, responseHeaders) {
+  const now = new Date();
+  const utcHour = now.getUTCHours();
+  const utcDay = now.getUTCDay();
+
+  const stats = meta.cacheStats || {};
+  const quota = meta._quotaData || {};
+
+  return {
+    timestamp: now.toISOString(),
+    model: telemetry.model || "unknown",
+    input_tokens: stats.inputTokens || 0,
+    output_tokens: stats.outputTokens || 0,
+    cache_read_input_tokens: stats.cacheRead || 0,
+    cache_creation_input_tokens: stats.cacheCreation || 0,
+    q5h_pct: quota.five_hour ? quota.five_hour.pct : null,
+    q7d_pct: quota.seven_day ? quota.seven_day.pct : null,
+    peak_hour: utcDay >= 1 && utcDay <= 5 && utcHour >= 13 && utcHour < 19,
+  };
+}
+
+export { buildRecord, LOG_PATH };
+
+export default {
+  name: "usage-log",
+  description: "Append per-call usage record to ~/.claude/usage.jsonl",
+  enabled: false,
+  order: 650,
+
+  async onStreamEvent(ctx) {
+    if (!ctx.event || ctx.event.type !== "message_delta" || !ctx.event.usage) return;
+
+    const record = buildRecord(ctx.meta, ctx.telemetry || {}, ctx.responseHeaders);
+
+    try {
+      await mkdir(join(homedir(), ".claude"), { recursive: true });
+      await appendFile(LOG_PATH, JSON.stringify(record) + "\n");
+    } catch {}
+  },
+};

package/proxy/extensions.json

@@ -3,6 +3,9 @@
   "sort-stabilization": { "enabled": true, "order": 200 },
   "fresh-session-sort": { "enabled": true, "order": 250 },
   "identity-normalization": { "enabled": true, "order": 300 },
+  "smoosh-split": { "enabled": true, "order": 320 },
+  "content-strip": { "enabled": true, "order": 330 },
+  "tool-input-normalize": { "enabled": true, "order": 340 },
   "cache-control-normalize": { "enabled": true, "order": 400 },
   "ttl-management": { "enabled": true, "order": 500 },
   "cache-telemetry": { "enabled": true, "order": 600 },