claude-code-cache-fix 3.5.5 → 3.6.1

package/README.md

@@ -43,6 +43,8 @@ On every `/v1/messages` request, 7 extensions run in order:
 
 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`.
 
+**Developing a new extension?** See [docs/parallel-proxy-test-harness.md](docs/parallel-proxy-test-harness.md) for the pattern we use to test extensions end-to-end against real `claude -p` traffic without disturbing the production proxy.
+
 ### Running as a service
 
 **Recommended (Linux/macOS) — `install-service` subcommand:**
@@ -167,6 +169,45 @@ node "$(npm root -g)\claude-code-cache-fix\proxy\server.mjs"
 
 Stderr will print `[upstream] using proxy http://proxy.corp.example:8080 ...` on first request when the agent is wired correctly. With no proxy/CA env vars set, behavior is unchanged from earlier versions (Node default agent, system trust store).
 
+### Embedding the proxy in your own process
+
+If you ship a Node or Bun binary that wants the cache-fix proxy in-process (e.g. a Bun-compiled agent that avoids forking a Node child), import the factory from `claude-code-cache-fix/proxy/server`:
+
+```js
+import { startProxy } from "claude-code-cache-fix/proxy/server";
+
+const handle = await startProxy({
+  port: 0,        // OS-assigned ephemeral port; pass a number to pin
+  bind: "127.0.0.1",
+  watch: false,   // skip fs.watch — recommended for compiled binaries
+});
+
+console.log(`proxy listening on ${handle.address}:${handle.port}`);
+
+// ...later...
+await handle.close();
+```
+
+**`createProxyServer()` → `http.Server`** builds the request handler wired into an `http.Server`. The returned server is *not* listening and the extension pipeline has not been loaded — use this when you want to manage the lifecycle yourself.
+
+**`startProxy(options?)` → `Promise<{ server, port, address, close }>`** loads the extension pipeline, optionally starts the file watcher, and starts listening. Returns a handle with the bound port (resolved when `port: 0` is requested) and a `close()` that releases the server and the watcher.
+
+Options (all optional; all fall back to the same env vars used by the CLI):
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `port` | `CACHE_FIX_PROXY_PORT` env, else `9801` | Listen port. Pass `0` for an OS-assigned ephemeral port. |
+| `bind` | `CACHE_FIX_PROXY_BIND` env, else `127.0.0.1` | Bind address. |
+| `extensionsDir` | package `proxy/extensions/` | Directory to load `.mjs` extensions from. |
+| `extensionsConfig` | package `proxy/extensions.json` | Path to extension config. |
+| `watch` | `true` | Whether to start `fs.watch` on the extensions config. Set `false` for embedded / compiled-binary use. |
+
+**One extension registry per process.** The pipeline maintains a single shared extension registry at module scope. Hosting two `startProxy()` instances in the same process is supported (different ports, different bind addresses), but they share that registry — a subsequent `loadExtensions` call replaces it for both. If you need divergent extension configs per instance, run them in separate processes.
+
+**CLI invocation is unchanged.** `node proxy/server.mjs`, `cache-fix-proxy server`, and the wrapper's child-fork path all auto-listen and install SIGTERM/SIGINT handlers as before. Library imports never trigger that behavior — the auto-listen is gated behind a main-module check.
+
+*The embeddable factory was contributed by [@bilby91](https://github.com/bilby91) at [Crunchloop DAP](https://dap.crunchloop.ai) — see [PR #123](https://github.com/cnighswonger/claude-code-cache-fix/pull/123).*
+
 ## Quick Start: Preload (CC v2.1.112 and earlier)
 
 If you're on a Node.js-based CC version (v2.1.112 or earlier), the preload interceptor works without a proxy:
@@ -576,6 +617,35 @@ The Mode A/B separation protects against cases where the sentinel might be follo
 | `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. |
 
+## Thinking summaries (proxy mode, opt-in, Opus 4.7+)
+
+On Opus 4.7, Anthropic flipped the API default for `thinking.display` from `"summarized"` to `"omitted"`. In parallel, Claude Code's CLI has a `!getIsNonInteractiveSession()` gate that propagates `display: "summarized"` only when the session is interactive. The combination means every CC subprocess spawned with `--input-format stream-json` — the VS Code chat panel, the Antigravity panel, the SDK, `claude --print` — sends a thinking-enabled request (`thinking.type` is either `"enabled"` or `"adaptive"` depending on CC version) without `display`, and the API responds with thinking blocks whose `thinking` field is empty (plus a multi-KB signature). The UI shows a static "Thinking" stub while the agent runs but never any reasoning content.
+
+Upstream root cause and patch proposed in [anthropics/claude-code#59844](https://github.com/anthropics/claude-code/issues/59844) (credit: [@ojura](https://github.com/ojura)). This extension is the proxy-side complement: when a request to an Opus 4.7 endpoint has thinking enabled but `display` unset, inject the configured mode at the API boundary. Works on any CC version routed through cache-fix-proxy, no waiting on Anthropic to ship the CLI fix.
+
+```sh
+# Restore summaries (the built-in default — non-interactive surfaces get reasoning content)
+export CACHE_FIX_THINKING_DISPLAY=summarized
+
+# Force-suppress override (agent runtimes that don't want thinking blocks at all)
+export CACHE_FIX_THINKING_DISPLAY=omitted
+
+# Explicit no-op (extension passes through unchanged)
+export CACHE_FIX_THINKING_DISPLAY=disabled
+```
+
+The extension is **default-on** as of v3.6.1. The cache-prefix test measured 0% absolute drop in steady-state `cache_read` ratio when injection is active on Opus 4.7 (5 sequential `claude -p` calls per window, baseline vs injected — both windows held 1.000 cache_read ratio from call 2 onward). Adding `thinking.display` to the request body changes the bytes Anthropic hashes, but Anthropic's cache layer accepts and indexes the injected-prefix the same way it does any other prefix. Users who want the older "no injection" behavior (e.g. to avoid any request-body mutation at all) explicitly set `CACHE_FIX_THINKING_DISPLAY=disabled`.
+
+Scoping rules baked into the extension:
+
+- **Model-gated.** Only fires on requests whose `model` matches `/^claude-opus-4-7/` — covers `claude-opus-4-7` and `claude-opus-4-7-1m`. Sonnet 4.7 needs separate verification (the API default-flip may differ); future versions (4.8+) require an explicit cache-fix bump rather than auto-applying unverified behavior.
+- **User opt-out preserved.** If the request already has `thinking.display` set (either `"summarized"` or `"omitted"`), the extension never overwrites. Explicit user choice always wins.
+- **Thinking-active types only.** The extension fires on `thinking.type` ∈ `{ "enabled", "adaptive" }` — the two active modes that produce thinking blocks on Opus 4.7. Other values (`"disabled"`, future modes) are skipped. Conservative: if Anthropic ships a new thinking type with different display semantics, we'd rather miss the fix than auto-apply incorrect behavior.
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CACHE_FIX_THINKING_DISPLAY` | `summarized` (built-in) | One of `summarized` / `omitted` / `disabled`. `summarized` restores thinking summaries (default). `omitted` force-suppresses thinking blocks. `disabled` opts the extension out entirely. |
+
 ## 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.
@@ -606,13 +676,13 @@ We monitor 30+ upstream Claude Code issues related to cache, quota, and context
 
 ## Used in production
 
-- **[Crunchloop DAP](https://dap.crunchloop.ai)** — Agent SDK / DAP development environment. First production team to merge the interceptor to trunk for team-wide deployment (2026-04-10). Identified two distinct cache regression patterns through real-world testing — tool ordering jitter and the fresh-session sort gap — and contributed debug traces that drove the v1.5.1 and v1.6.2 fixes.
+- **[Crunchloop DAP](https://dap.crunchloop.ai)** — Agent SDK / DAP development environment. First production team to merge the interceptor to trunk for team-wide deployment (2026-04-10). Identified two distinct cache regression patterns through real-world testing — tool ordering jitter and the fresh-session sort gap — and contributed debug traces that drove the v1.5.1 and v1.6.2 fixes. Contributed the embeddable proxy factory (v3.6.0) that lets the proxy run in-process inside Bun-compiled and DAP-style agent binaries without forking a Node child.
 - **[VM Farms](https://vmfarms.com)** ([@vmfarms](https://github.com/vmfarms)) — Agent development environment running concurrent multi-runner workloads with `--resume --fork-session`. Surfaced three cache-fix proxy-mode bugs: the resume-marker regex no-op (#96), TTL tier detection gap vs preload mode (#97), and image-strip stderr leak past `CACHE_FIX_DEBUG` (#98) — all addressed in the v3.4.0 release.
 
 ## Contributors
 
 - **[@VictorSun92](https://github.com/VictorSun92)** — Original monkey-patch fix for v2.1.88, identified partial scatter on v2.1.90, contributed forward-scan detection, correct block ordering, tighter block matchers, and the optional output-efficiency rewrite hook
-- **[@bilby91](https://github.com/bilby91)** ([Crunchloop DAP](https://dap.crunchloop.ai)) — Agent SDK / DAP production environment validation, 1h cache TTL confirmation, tool ordering jitter discovery via debug trace (fixed in v1.5.1), fresh-session sort bug discovery via SKILLS SORT diagnostic (fixed in v1.6.2). First production team to roll the interceptor to trunk.
+- **[@bilby91](https://github.com/bilby91)** ([Crunchloop DAP](https://dap.crunchloop.ai)) — Agent SDK / DAP production environment validation, 1h cache TTL confirmation, tool ordering jitter discovery via debug trace (fixed in v1.5.1), fresh-session sort bug discovery via SKILLS SORT diagnostic (fixed in v1.6.2). First production team to roll the interceptor to trunk. Designed and contributed the embeddable proxy factory (`startProxy()` / `createProxyServer()`) shipped in v3.6.0 (PR #123).
 - **[@jmarianski](https://github.com/jmarianski)** — Root cause analysis via MITM proxy capture and Ghidra reverse engineering, multi-mode cache test script
 - **[@cnighswonger](https://github.com/cnighswonger)** — Fingerprint stabilization, tool ordering fix, image stripping, monitoring features, overage TTL downgrade discovery, proxy architecture, package maintainer
 - **[@ArkNill](https://github.com/ArkNill)** — Microcompact mechanism analysis, GrowthBook flag documentation, false rate limiter identification, fingerprint verification fix for CC v2.1.108+ (PR #21), Korean README (PR #22), [claude-code-hidden-problem-analysis](https://github.com/ArkNill/claude-code-hidden-problem-analysis) research
@@ -625,6 +695,7 @@ We monitor 30+ upstream Claude Code issues related to cache, quota, and context
 - **[@X-15](https://github.com/X-15)** — VS Code extension validation, per-fix health status analysis confirming safety check behavior on v2.1.105 (#16)
 - **[@deafsquad](https://github.com/deafsquad)** — Universal smoosh_split un-smoosh fix (PR #26), source-level function attribution of resume scatter bug (anthropics/claude-code#43657), OTEL telemetry discovery, proposed and built proxy architecture for v3.0.0
 - **[@vmfarms](https://github.com/vmfarms)** — Concurrent multi-runner production validation, surfaced proxy-mode resume-marker regex no-op (#96), TTL tier detection gap (#97), and image-strip stderr leak (#98)
+- **[@ojura](https://github.com/ojura)** — Opus 4.7 thinking-summaries root-cause analysis: filed [anthropics/claude-code#59844](https://github.com/anthropics/claude-code/issues/59844) with the CLI-binary decode (`!getIsNonInteractiveSession()` gate at offset 230510599 in v2.1.142) and the two-stacked-special-cases framing, which made the `thinking-display` extension (v3.6.1) a clean proxy-side complement to the proposed upstream fix
 
 If you contributed to the community effort on these issues and aren't listed here, please open an issue or PR — we want to credit everyone properly.
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.5.5",
+  "version": "3.6.1",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
-  "exports": "./preload.mjs",
+  "exports": {
+    ".": "./preload.mjs",
+    "./proxy/server": "./proxy/server.mjs"
+  },
   "main": "./preload.mjs",
   "bin": {
     "cache-fix-proxy": "./bin/claude-via-proxy.mjs"

package/proxy/extensions/thinking-display.mjs

@@ -0,0 +1,79 @@
+// thinking-display extension
+//
+// Restores Opus 4.7 thinking summaries in non-interactive CC surfaces
+// (VS Code chat panel, SDK, `claude --print`, anything spawned with
+// `--input-format stream-json`).
+//
+// Background: Anthropic flipped the `thinking.display` default to `"omitted"`
+// on Opus 4.7. CC's CLI propagates `display: "summarized"` only when the
+// session is interactive (the `!getIsNonInteractiveSession()` gate); every
+// non-interactive subprocess gets the API default of omitted thinking, which
+// renders as an empty stub in the IDE. Upstream root cause and patch proposed
+// in anthropics/claude-code#59844 (credit: @ojura).
+//
+// This extension is the proxy-side workaround. When a request has thinking
+// enabled but `display` unset, inject the configured mode at the API
+// boundary. Works on any CC version routed through cache-fix-proxy without
+// waiting for Anthropic to ship the CLI fix.
+//
+// Config (env var; built-in default is "summarized"):
+//   CACHE_FIX_THINKING_DISPLAY=summarized — inject display: "summarized"
+//     (main case; restores summaries in IDE/SDK/--print). DEFAULT.
+//   CACHE_FIX_THINKING_DISPLAY=omitted    — inject display: "omitted"
+//     (force-suppress override; for agent runtimes that don't want thinking
+//     blocks at all, regardless of what their CLI sends)
+//   CACHE_FIX_THINKING_DISPLAY=disabled   — no injection; extension is a no-op
+//
+// Default flipped to "summarized" in v3.6.1 after the cache-prefix test on
+// Opus 4.7 measured 0% absolute drop in steady-state cache_read ratio with
+// injection enabled (well inside the ≤5% "preserved" threshold). Users who
+// want the older "no injection" behavior set CACHE_FIX_THINKING_DISPLAY=disabled.
+
+const MODEL_REGEX = /^claude-opus-4-7/;
+
+function resolveMode() {
+  const v = process.env.CACHE_FIX_THINKING_DISPLAY;
+  if (v === "summarized" || v === "omitted" || v === "disabled") return v;
+  return "summarized";
+}
+
+// Thinking types that produce thinking blocks. CC v2.1.131+ ships
+// `type: "adaptive"` (dynamic-budget mode) by default for the Bun binary's
+// non-interactive paths; older versions and explicit-budget configs may
+// still send `"enabled"`. Both produce the same empty-thinking symptom
+// when `display` is unset on Opus 4.7, so both are in scope.
+const ACTIVE_THINKING_TYPES = new Set(["enabled", "adaptive"]);
+
+function shouldInject(body) {
+  if (!body || typeof body !== "object") return false;
+  if (typeof body.model !== "string") return false;
+  if (!MODEL_REGEX.test(body.model)) return false;
+  if (!body.thinking || typeof body.thinking !== "object") return false;
+  if (!ACTIVE_THINKING_TYPES.has(body.thinking.type)) return false;
+  // Only inject when display is unset. Preserve any explicit user choice
+  // (including explicit "omitted" for compliance opt-out).
+  return body.thinking.display === undefined;
+}
+
+export { MODEL_REGEX, ACTIVE_THINKING_TYPES, resolveMode, shouldInject };
+
+export default {
+  name: "thinking-display",
+  description:
+    "Inject thinking.display on Opus 4.7 requests when unset, to restore " +
+    "thinking summaries lost to CC's non-interactive CLI gate (claude-code#59844)",
+  enabled: false,
+  order: 360,
+
+  async onRequest(ctx) {
+    const mode = resolveMode();
+    if (mode === "disabled") return;
+    if (!shouldInject(ctx.body)) return;
+
+    ctx.body.thinking.display = mode;
+
+    if (ctx.meta) {
+      ctx.meta.thinkingDisplayInjected = mode;
+    }
+  },
+};

package/proxy/extensions.json

@@ -9,6 +9,7 @@
   "content-strip": { "enabled": true, "order": 330 },
   "tool-input-normalize": { "enabled": true, "order": 340 },
   "microcompact-stability": { "enabled": true, "order": 350 },
+  "thinking-display": { "enabled": true, "order": 360 },
   "cache-control-normalize": { "enabled": true, "order": 400 },
   "messages-cache-breakpoint": { "enabled": true, "order": 410 },
   "ttl-management": { "enabled": true, "order": 500 },

package/proxy/server.mjs

@@ -1,4 +1,5 @@
 import http from "node:http";
+import { pathToFileURL } from "node:url";
 import config from "./config.mjs";
 import { forwardRequest } from "./upstream.mjs";
 import { streamResponse, createTelemetryRecord } from "./stream.mjs";
@@ -138,36 +139,106 @@ function handleNotFound(_req, res) {
   res.end(JSON.stringify({ error: "not_found" }));
 }
 
-const server = http.createServer((req, res) => {
-  if (req.method === "GET" && req.url === "/health") {
-    return handleHealth(req, res);
-  }
-  if (req.method === "POST" && req.url?.startsWith("/v1/messages")) {
-    return handleMessages(req, res);
-  }
-  handleNotFound(req, res);
-});
-
-function shutdown() {
-  server.close(() => process.exit(0));
-  setTimeout(() => process.exit(1), 5000);
+/**
+ * Builds an http.Server with the proxy's request handler wired in. The
+ * returned server is **not** listening and the extension pipeline has not
+ * been initialized — callers wanting a one-call setup should use
+ * `startProxy()` instead.
+ *
+ * Exposed so callers can embed the proxy in their own process (e.g.
+ * Bun-compiled binaries, test harnesses) without forking a child or
+ * shelling out to the `cache-fix-proxy` bin.
+ */
+export function createProxyServer() {
+  return http.createServer((req, res) => {
+    if (req.method === "GET" && req.url === "/health") {
+      return handleHealth(req, res);
+    }
+    if (req.method === "POST" && req.url?.startsWith("/v1/messages")) {
+      return handleMessages(req, res);
+    }
+    handleNotFound(req, res);
+  });
 }
 
-process.on("SIGTERM", shutdown);
-process.on("SIGINT", shutdown);
-
-async function initPipeline() {
+/**
+ * Builds the server, loads the extension pipeline, optionally starts the
+ * extensions-config file watcher, and starts listening. Returns a handle
+ * with the bound port (resolved when port 0 is requested) and a `close`
+ * function for graceful shutdown.
+ *
+ * All options fall back to the same env vars / defaults used by the CLI
+ * entrypoint, so existing deployments behave identically.
+ *
+ *   await startProxy()                               // env-driven, CLI parity
+ *   await startProxy({ port: 0 })                    // OS-assigned port
+ *   await startProxy({ port: 0, watch: false })      // embedded, no fs.watch
+ */
+export async function startProxy(options = {}) {
+  const port = options.port ?? config.port;
+  const bind = options.bind ?? config.bind;
+  const extensionsDir = options.extensionsDir ?? config.extensionsDir;
+  const extensionsConfig = options.extensionsConfig ?? config.extensionsConfig;
+  const watch = options.watch !== false;
+
+  let watcher = null;
   try {
-    await loadExtensions(config.extensionsDir, config.extensionsConfig);
-    startWatcher(config.extensionsDir, config.extensionsConfig);
+    await loadExtensions(extensionsDir, extensionsConfig);
+    if (watch) watcher = startWatcher(extensionsDir, extensionsConfig);
   } catch {}
-}
 
-initPipeline().then(() => {
-  server.listen(config.port, config.bind, () => {
-    const addr = server.address();
-    process.stdout.write(`proxy listening on ${addr.address}:${addr.port}\n`);
+  const server = createProxyServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, bind, () => {
+      server.off("error", reject);
+      resolve();
+    });
   });
-});
 
-export { server };
+  const addr = server.address();
+  return {
+    server,
+    port: addr.port,
+    address: addr.address,
+    close: () =>
+      new Promise((resolve, reject) => {
+        try {
+          if (watcher) watcher.close();
+        } catch {}
+        server.close((err) => (err ? reject(err) : resolve()));
+      }),
+  };
+}
+
+// CLI entrypoint — preserves the v3.x behavior of `node proxy/server.mjs`
+// (used by `cache-fix-proxy server` and by `fork(SERVER_PATH)` in the
+// wrapper). When this module is imported as a library, none of this runs.
+const invokedAsScript =
+  typeof process !== "undefined" &&
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedAsScript) {
+  let active;
+  startProxy()
+    .then((handle) => {
+      active = handle;
+      process.stdout.write(`proxy listening on ${handle.address}:${handle.port}\n`);
+    })
+    .catch((err) => {
+      process.stderr.write(`proxy failed to start: ${err.message}\n`);
+      process.exit(1);
+    });
+
+  const shutdown = () => {
+    if (!active) {
+      process.exit(0);
+      return;
+    }
+    active.close().finally(() => process.exit(0));
+    setTimeout(() => process.exit(1), 5000).unref();
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}