claude-code-cache-fix 2.0.6 → 3.0.1

package/README.md

@@ -4,9 +4,76 @@
 
 English | [中文](./README.zh.md) | [한국어](./README.ko.md) | [Português](./docs/guia-pt-br.md)
 
-Fixes prompt cache regressions in [Claude Code](https://github.com/anthropics/claude-code) that cause **up to 20x cost increase** on resumed sessions, plus monitoring for silent context degradation. Confirmed through v2.1.112. Opus 4.7 compatible.
+Cache optimization proxy and interceptor for [Claude Code](https://github.com/anthropics/claude-code). Fixes prompt cache bugs that cause excessive quota burn, stabilizes the request prefix, and monitors for silent regressions. Works with all CC versions including the v2.1.113+ Bun binary.
 
-> **Opus 4.7 advisory:** Our metered data shows 4.7 burns Q5h quota at **~2.4x the rate of 4.6** for equivalent visible token counts. Two factors: a new tokenizer (up to 35% more tokens, [documented](https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7)) and adaptive thinking overhead (~105%, not documented in usage response). Workaround: `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` (may reduce quality). Image stripping (`CACHE_FIX_IMAGE_KEEP_LAST`) is even more important on 4.7 due to high-res image support increasing image token counts. See [Discussion #25](https://github.com/cnighswonger/claude-code-cache-fix/discussions/25) for full analysis.
+> **v3.0.0** adds a local HTTP proxy with hot-reloadable extensions. This is the recommended path for CC v2.1.113+ where the preload interceptor no longer works. A/B tested on v2.1.117: **95.5% cache hit rate through proxy vs 82.3% direct** on first warm turn. [Full release notes →](https://github.com/cnighswonger/claude-code-cache-fix/releases/tag/v3.0.0)
+
+> **Opus 4.7 advisory:** Metered data shows 4.7 burns Q5h quota at **~2.4x the rate of 4.6** for equivalent visible token counts. Two factors: a new tokenizer (up to 35% more tokens, [documented](https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7)) and adaptive thinking overhead (~105%, not documented in usage response). Workaround: `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` (may reduce quality). See [Discussion #25](https://github.com/cnighswonger/claude-code-cache-fix/discussions/25) for full analysis.
+
+## Quick Start: Proxy (recommended for CC v2.1.113+)
+
+The proxy works with any CC version — Node.js or Bun binary. It sits between Claude Code and the Anthropic API, applying cache fixes as hot-reloadable extensions.
+
+```bash
+# Install
+npm install -g claude-code-cache-fix
+
+# Start the proxy (runs on localhost:9801)
+node "$(npm root -g)/claude-code-cache-fix/proxy/server.mjs" &
+
+# Launch Claude Code through it
+ANTHROPIC_BASE_URL=http://127.0.0.1:9801 claude
+```
+
+That's it. The proxy applies all 7 cache-fix extensions automatically. No wrapper scripts, no `NODE_OPTIONS`, no preload.
+
+### What the proxy does
+
+On every request passing through, 7 extensions run in order:
+
+| Extension | What it fixes |
+|-----------|--------------|
+| `fingerprint-strip` | Removes unstable cc_version fingerprint from system prompt |
+| `sort-stabilization` | Deterministic ordering of tool and MCP definitions |
+| `ttl-management` | Detects server TTL tier, injects correct cache_control markers |
+| `identity-normalization` | Normalizes message identity fields for prefix stability |
+| `fresh-session-sort` | Fixes non-deterministic ordering on first turn |
+| `cache-control-normalize` | Normalizes cache_control markers across messages |
+| `cache-telemetry` | Extracts cache stats from response headers → `~/.claude/quota-status.json` |
+
+Extensions are hot-reloadable — add, remove, or modify `.mjs` files in `proxy/extensions/` and changes apply to the next request without restarting. Configuration in `proxy/extensions.json`.
+
+### Running as a service
+
+For persistent use, run the proxy in the background:
+
+```bash
+# Start in background with logging
+nohup node "$(npm root -g)/claude-code-cache-fix/proxy/server.mjs" > /tmp/cache-fix-proxy.log 2>&1 &
+
+# Add to your shell profile
+echo 'export ANTHROPIC_BASE_URL=http://127.0.0.1:9801' >> ~/.bashrc
+```
+
+### Health check
+
+```bash
+curl http://127.0.0.1:9801/health
+# {"status":"ok"}
+```
+
+## Quick Start: Preload (for CC v2.1.112 and earlier)
+
+If you're on a Node.js-based CC version (v2.1.112 or earlier), the preload interceptor still works and requires no proxy:
+
+```bash
+npm install -g claude-code-cache-fix
+NODE_OPTIONS="--import claude-code-cache-fix" claude
+```
+
+> **Note:** The preload does NOT work on CC v2.1.113+ (Bun binary). Use the proxy path above.
+
+See [Preload Setup Details](#preload-setup-details) below for wrapper scripts, shell aliases, and Windows instructions.
 
 ## Security model
 
@@ -34,7 +101,12 @@ Three bugs cause this:
 
 Additionally, images read via the Read tool persist as base64 in conversation history and are sent on every subsequent API call, compounding token costs silently.
 
-## Installation
+## Preload Setup Details
+
+<details>
+<summary>Expand for preload interceptor setup (CC v2.1.112 and earlier only)</summary>
+
+### Installation
 
 Requires Node.js >= 18 and Claude Code installed via npm (not the standalone binary).
 
@@ -42,9 +114,9 @@ Requires Node.js >= 18 and Claude Code installed via npm (not the standalone bin
 npm install -g claude-code-cache-fix
 ```
 
-## Usage
+### Usage
 
-The fix works as a Node.js preload module that intercepts API requests before they leave your machine.
+The preload works as a Node.js module that intercepts API requests before they leave your machine.
 
 ### Option A: Wrapper script (recommended)
 
@@ -184,6 +256,8 @@ Then set in VS Code `settings.json`:
 
 Credit: [@JEONG-JIWOO](https://github.com/JEONG-JIWOO) and [@X-15](https://github.com/X-15) for the VS Code extension investigation and C wrapper ([#16](https://github.com/cnighswonger/claude-code-cache-fix/issues/16)).
 
+</details>
+
 ## How it works
 
 The module intercepts `globalThis.fetch` before Claude Code makes API calls to `/v1/messages`. On each call it:

package/bin/claude-via-proxy.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { fork, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import http from "node:http";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SERVER_PATH = resolve(__dirname, "../proxy/server.mjs");
+
+const args = process.argv.slice(2);
+let proxyPort = 9801;
+let proxyUpstream = undefined;
+const claudeArgs = [];
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--proxy-port" && args[i + 1]) {
+    proxyPort = parseInt(args[++i], 10);
+  } else if (args[i] === "--proxy-upstream" && args[i + 1]) {
+    proxyUpstream = args[++i];
+  } else {
+    claudeArgs.push(args[i]);
+  }
+}
+
+const proxyEnv = { ...process.env, CACHE_FIX_PROXY_PORT: String(proxyPort) };
+if (proxyUpstream) proxyEnv.CACHE_FIX_PROXY_UPSTREAM = proxyUpstream;
+
+const proxyProc = fork(SERVER_PATH, [], {
+  stdio: ["ignore", "pipe", "pipe", "ipc"],
+  env: proxyEnv,
+});
+
+let claudeProc = null;
+let exiting = false;
+
+function cleanup() {
+  if (exiting) return;
+  exiting = true;
+  if (claudeProc && !claudeProc.killed) claudeProc.kill("SIGTERM");
+  if (proxyProc && !proxyProc.killed) proxyProc.kill("SIGTERM");
+}
+
+proxyProc.on("exit", (code) => {
+  if (!exiting) {
+    process.stderr.write(`proxy exited unexpectedly (code ${code})\n`);
+    cleanup();
+    process.exit(1);
+  }
+});
+
+proxyProc.stderr.on("data", (chunk) => {
+  process.stderr.write(chunk);
+});
+
+function waitForReady() {
+  return new Promise((resolve, reject) => {
+    let output = "";
+    proxyProc.stdout.on("data", (chunk) => {
+      output += chunk.toString();
+      const match = output.match(/listening on ([\d.]+):(\d+)/);
+      if (match) resolve(parseInt(match[2], 10));
+    });
+    proxyProc.on("exit", (code) => {
+      reject(new Error(`Proxy exited (code ${code}) before ready`));
+    });
+    setTimeout(() => reject(new Error("Proxy failed to start within 10s")), 10000);
+  });
+}
+
+let actualPort;
+try {
+  actualPort = await waitForReady();
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  cleanup();
+  process.exit(1);
+}
+
+const claudeEnv = {
+  ...process.env,
+  ANTHROPIC_BASE_URL: `http://127.0.0.1:${actualPort}`,
+};
+
+const spawnOpts = { stdio: ["inherit", "pipe", "pipe"], env: claudeEnv };
+if (process.env.CACHE_FIX_CLAUDE_CMD) {
+  const parts = process.env.CACHE_FIX_CLAUDE_CMD.split(" ");
+  claudeProc = spawn(parts[0], [...parts.slice(1), ...claudeArgs], spawnOpts);
+} else {
+  claudeProc = spawn("claude", claudeArgs, spawnOpts);
+}
+
+claudeProc.stdout.on("data", (chunk) => process.stdout.write(chunk));
+claudeProc.stderr.on("data", (chunk) => process.stderr.write(chunk));
+
+claudeProc.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    process.stderr.write("Error: 'claude' command not found. Is Claude Code installed?\n");
+  } else {
+    process.stderr.write(`Failed to start claude: ${err.message}\n`);
+  }
+  cleanup();
+  process.exit(1);
+});
+
+claudeProc.on("close", (code) => {
+  const exitCode = code ?? 0;
+  cleanup();
+  process.exit(exitCode);
+});
+
+process.on("SIGINT", () => { cleanup(); process.exit(130); });
+process.on("SIGTERM", () => { cleanup(); process.exit(143); });

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "2.0.6",
-  "description": "Fixes prompt cache regression in Claude Code that causes up to 20x cost increase on resumed sessions",
+  "version": "3.0.1",
+  "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",
   "main": "./preload.mjs",
+  "bin": {
+    "cache-fix-proxy": "./bin/claude-via-proxy.mjs"
+  },
   "files": [
     "preload.mjs",
     "postinstall.js",
     "tools/",
-    "claude-fixed.bat"
+    "claude-fixed.bat",
+    "proxy/",
+    "bin/"
   ],
   "engines": {
     "node": ">=18"

package/proxy/config.mjs

@@ -0,0 +1,23 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  const parsed = parseInt(raw, 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const config = {
+  port: envInt("CACHE_FIX_PROXY_PORT", 9801),
+  bind: process.env.CACHE_FIX_PROXY_BIND || "127.0.0.1",
+  upstream: process.env.CACHE_FIX_PROXY_UPSTREAM || "https://api.anthropic.com",
+  timeout: envInt("CACHE_FIX_PROXY_TIMEOUT", 600_000),
+  extensionsDir: process.env.CACHE_FIX_EXTENSIONS_DIR || join(__dirname, "extensions"),
+  extensionsConfig: process.env.CACHE_FIX_EXTENSIONS_CONFIG || join(__dirname, "extensions.json"),
+  debug: process.env.CACHE_FIX_DEBUG === "1",
+};
+
+export default config;

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

@@ -0,0 +1,59 @@
+function stripCacheControlMarkers(msg) {
+  if (!msg || msg.role !== "user" || !Array.isArray(msg.content)) return 0;
+  let n = 0;
+  for (let i = 0; i < msg.content.length; i++) {
+    const block = msg.content[i];
+    if (block && typeof block === "object" && block.cache_control) {
+      const { cache_control, ...rest } = block;
+      msg.content[i] = rest;
+      n++;
+    }
+  }
+  return n;
+}
+
+function countUserCacheControlMarkers(body) {
+  if (!body || !Array.isArray(body.messages)) return 0;
+  let n = 0;
+  for (const msg of body.messages) {
+    if (msg?.role !== "user" || !Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (block && typeof block === "object" && block.cache_control) n++;
+    }
+  }
+  return n;
+}
+
+export default {
+  name: "cache-control-normalize",
+  description: "Strip scattered cache_control markers from user messages and apply canonical placement",
+  order: 400,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+    if (!Array.isArray(body.messages)) return;
+
+    const markerCount = countUserCacheControlMarkers(body);
+    if (markerCount === 0) return;
+
+    for (const msg of body.messages) {
+      if (msg.role === "user") {
+        stripCacheControlMarkers(msg);
+      }
+    }
+
+    // Apply canonical cache_control at the last block of the last user message
+    for (let i = body.messages.length - 1; i >= 0; i--) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content) || msg.content.length === 0) continue;
+      const lastBlock = msg.content[msg.content.length - 1];
+      if (lastBlock && typeof lastBlock === "object") {
+        msg.content[msg.content.length - 1] = {
+          ...lastBlock,
+          cache_control: { type: "ephemeral" },
+        };
+      }
+      break;
+    }
+  },
+};

package/proxy/extensions/cache-telemetry.mjs

@@ -0,0 +1,24 @@
+export default {
+  name: "cache-telemetry",
+  description: "Extract cache hit/miss stats from response stream for monitoring",
+  order: 600,
+
+  async onStreamEvent(ctx) {
+    const { event, telemetry } = ctx;
+    if (!event || !telemetry) return;
+
+    if (event.type === "message_start" && event.message?.usage) {
+      const usage = event.message.usage;
+      ctx.meta.cacheStats = {
+        cacheRead: usage.cache_read_input_tokens || 0,
+        cacheCreation: usage.cache_creation_input_tokens || 0,
+        inputTokens: usage.input_tokens || 0,
+      };
+    }
+
+    if (event.type === "message_delta" && event.usage) {
+      if (!ctx.meta.cacheStats) ctx.meta.cacheStats = {};
+      ctx.meta.cacheStats.outputTokens = event.usage.output_tokens || 0;
+    }
+  },
+};

package/proxy/extensions/fingerprint-strip.mjs

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+
+const FINGERPRINT_SALT = "59cf53e54c78";
+const FINGERPRINT_INDICES = [4, 7, 20];
+
+function computeFingerprint(messageText, version) {
+  const chars = FINGERPRINT_INDICES.map((i) => messageText[i] || "0").join("");
+  const input = `${FINGERPRINT_SALT}${chars}${version}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 3);
+}
+
+function extractRealUserMessageText(messages) {
+  for (const msg of messages) {
+    if (msg.role !== "user") continue;
+    const content = msg.content;
+    if (!Array.isArray(content)) {
+      if (typeof content === "string" && !content.startsWith("<system-reminder>")) {
+        return content;
+      }
+      continue;
+    }
+    for (const block of content) {
+      if (block.type === "text" && typeof block.text === "string" && !block.text.startsWith("<system-reminder>")) {
+        return block.text;
+      }
+    }
+  }
+  return "";
+}
+
+function extractFirstMessageText(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return "";
+  const first = messages[0];
+  if (!first || first.role !== "user") return "";
+  const content = first.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  for (const block of content) {
+    if (block.type === "text" && typeof block.text === "string") {
+      return block.text;
+    }
+  }
+  return "";
+}
+
+function stabilizeFingerprint(system, messages) {
+  if (!Array.isArray(system)) return null;
+
+  const attrIdx = system.findIndex(
+    (b) => b.type === "text" && typeof b.text === "string" && b.text.includes("x-anthropic-billing-header:")
+  );
+  if (attrIdx === -1) return null;
+
+  const attrBlock = system[attrIdx];
+  const versionMatch = attrBlock.text.match(/cc_version=([^;]+)/);
+  if (!versionMatch) return null;
+
+  const fullVersion = versionMatch[1];
+  const dotParts = fullVersion.split(".");
+  if (dotParts.length < 4) return null;
+
+  const baseVersion = dotParts.slice(0, 3).join(".");
+  const oldFingerprint = dotParts[3];
+
+  const realText = extractRealUserMessageText(messages);
+  const realVerification = computeFingerprint(realText, baseVersion);
+  const legacyText = extractFirstMessageText(messages);
+  const legacyVerification = computeFingerprint(legacyText, baseVersion);
+
+  let verificationPassed = false;
+  if (realVerification === oldFingerprint) {
+    verificationPassed = true;
+  } else if (legacyVerification === oldFingerprint) {
+    verificationPassed = true;
+  }
+
+  if (!verificationPassed) return null;
+
+  const stableFingerprint = computeFingerprint(realText, baseVersion);
+  if (stableFingerprint === oldFingerprint) return null;
+
+  const newVersion = `${baseVersion}.${stableFingerprint}`;
+  const newText = attrBlock.text.replace(
+    `cc_version=${fullVersion}`,
+    `cc_version=${newVersion}`
+  );
+
+  return { attrIdx, newText, oldFingerprint, stableFingerprint };
+}
+
+export default {
+  name: "fingerprint-strip",
+  description: "Stabilize cc_version fingerprint in system prompt for cache prefix consistency",
+  order: 100,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+    if (!body.system || !body.messages) return;
+
+    const result = stabilizeFingerprint(body.system, body.messages);
+    if (result) {
+      body.system[result.attrIdx] = { ...body.system[result.attrIdx], text: result.newText };
+    }
+  },
+};

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

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+
+const SR = "<system-reminder>\n";
+
+function isSystemReminder(text) {
+  return typeof text === "string" && text.startsWith("<system-reminder>");
+}
+
+function isHooksBlock(text) {
+  return isSystemReminder(text) && text.substring(0, 200).includes("hook success");
+}
+
+function isSkillsBlock(text) {
+  return typeof text === "string" && text.startsWith(SR + "The following skills are available");
+}
+
+function isDeferredToolsBlock(text) {
+  return typeof text === "string" && text.startsWith(SR + "The following deferred tools are now available");
+}
+
+function isMcpBlock(text) {
+  return typeof text === "string" && text.startsWith(SR + "# MCP Server Instructions");
+}
+
+function isRelocatableBlock(text) {
+  return isHooksBlock(text) || isSkillsBlock(text) || isDeferredToolsBlock(text) || isMcpBlock(text);
+}
+
+function isClearArtifact(text) {
+  if (typeof text !== "string") return false;
+  return (
+    text.startsWith("<local-command-caveat>") ||
+    text.startsWith("<command-name>") ||
+    text.startsWith("<local-command-stdout>")
+  );
+}
+
+function sortSkillsBlock(text) {
+  const match = text.match(/^([\s\S]*?\n\n)(- [\s\S]+?)(\n<\/system-reminder>\s*)$/);
+  if (!match) return text;
+  const [, header, entriesText, footer] = match;
+  const entries = entriesText.split(/\n(?=- )/);
+  entries.sort();
+  return header + entries.join("\n") + footer;
+}
+
+function sortDeferredToolsBlock(text) {
+  const match = text.match(
+    /^(<system-reminder>\nThe following deferred tools are now available[^\n]*\n)([\s\S]+?)(\n<\/system-reminder>\s*)$/
+  );
+  if (!match) return text;
+  const [, header, toolsList, footer] = match;
+  const tools = toolsList.split("\n").map((t) => t.trim()).filter(Boolean);
+  tools.sort();
+  return header + tools.join("\n") + footer;
+}
+
+function stripSessionKnowledge(text) {
+  return text.replace(/\n<session_knowledge[^>]*>[\s\S]*?<\/session_knowledge>/g, "");
+}
+
+const _pinnedBlocks = new Map();
+
+function pinBlockContent(blockType, text) {
+  const normalized = text.replace(/\s+(<\/system-reminder>)\s*$/, "\n$1");
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  const pinned = _pinnedBlocks.get(blockType);
+  if (pinned && pinned.hash === hash) return pinned.text;
+  _pinnedBlocks.set(blockType, { hash, text: normalized });
+  return normalized;
+}
+
+function getBlockType(text) {
+  if (isSkillsBlock(text)) return "skills";
+  if (isDeferredToolsBlock(text)) return "deferred";
+  if (isMcpBlock(text)) return "mcp";
+  if (isHooksBlock(text)) return "hooks";
+  return null;
+}
+
+function fixBlockText(blockType, text) {
+  let fixed = text;
+  if (blockType === "skills") fixed = sortSkillsBlock(fixed);
+  else if (blockType === "deferred") fixed = sortDeferredToolsBlock(fixed);
+  else if (blockType === "hooks") fixed = stripSessionKnowledge(fixed);
+  return pinBlockContent(blockType, fixed);
+}
+
+export default {
+  name: "fresh-session-sort",
+  description: "Relocate scattered blocks to messages[0] in deterministic fresh-session order",
+  order: 250,
+
+  async onRequest(ctx) {
+    const { body } = ctx;
+    if (!Array.isArray(body.messages)) return;
+
+    let firstUserIdx = -1;
+    for (let i = 0; i < body.messages.length; i++) {
+      if (body.messages[i].role === "user") {
+        firstUserIdx = i;
+        break;
+      }
+    }
+    if (firstUserIdx === -1) return;
+
+    const firstMsg = body.messages[firstUserIdx];
+    if (!Array.isArray(firstMsg?.content)) return;
+
+    // Strip /clear artifacts from first user message
+    const beforeLen = firstMsg.content.length;
+    firstMsg.content = firstMsg.content.filter((b) => !isClearArtifact(b.text || ""));
+
+    // Check for scattered relocatable blocks outside first user message
+    let hasScatteredBlocks = false;
+    for (let i = firstUserIdx + 1; i < body.messages.length && !hasScatteredBlocks; i++) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+      for (const block of msg.content) {
+        if (isRelocatableBlock(block.text || "")) {
+          hasScatteredBlocks = true;
+          break;
+        }
+      }
+    }
+
+    if (!hasScatteredBlocks) {
+      // Still sort and pin blocks in-place for deterministic first-call baseline
+      let modified = false;
+      const newContent = firstMsg.content.map((block) => {
+        const text = block.text || "";
+        const blockType = getBlockType(text);
+        if (!blockType) return block;
+
+        const fixedText = fixBlockText(blockType, text);
+        if (fixedText !== text) {
+          modified = true;
+          const { cache_control, ...rest } = block;
+          return { ...rest, text: fixedText };
+        }
+        return block;
+      });
+
+      if (modified || firstMsg.content.length !== beforeLen) {
+        body.messages[firstUserIdx] = { ...firstMsg, content: newContent };
+      }
+      return;
+    }
+
+    // Scan backwards to find latest instance of each relocatable block type
+    const found = new Map();
+    for (let i = body.messages.length - 1; i >= firstUserIdx; i--) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+      for (let j = msg.content.length - 1; j >= 0; j--) {
+        const block = msg.content[j];
+        const text = block.text || "";
+        const blockType = getBlockType(text);
+        if (!blockType || found.has(blockType)) continue;
+
+        const fixedText = fixBlockText(blockType, text);
+        const { cache_control, ...rest } = block;
+        found.set(blockType, { ...rest, text: fixedText });
+      }
+    }
+
+    if (found.size === 0) return;
+
+    // Remove all relocatable blocks from all user messages
+    for (let i = 0; i < body.messages.length; i++) {
+      const msg = body.messages[i];
+      if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
+      const filtered = msg.content.filter((b) => !isRelocatableBlock(b.text || ""));
+      if (filtered.length !== msg.content.length) {
+        body.messages[i] = { ...msg, content: filtered };
+      }
+    }
+
+    // Prepend in deterministic order: deferred → mcp → skills → hooks
+    const ORDER = ["deferred", "mcp", "skills", "hooks"];
+    const toRelocate = ORDER.filter((t) => found.has(t)).map((t) => found.get(t));
+
+    body.messages[firstUserIdx] = {
+      ...body.messages[firstUserIdx],
+      content: [...toRelocate, ...body.messages[firstUserIdx].content],
+    };
+  },
+};