claude-code-cache-fix 3.6.2 → 3.7.1

package/README.md

@@ -208,6 +208,27 @@ Options (all optional; all fall back to the same env vars used by the CLI):
 
 *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).*
 
+## What this proxy defends against
+
+**Cache-economics regressions.** The original purpose of cache-fix is to absorb the cache-handling behaviors in Claude Code that cost users real money and quota — TTL downgrades, cache-breaking header churn, identity-latching issues, and the rest of the regression catalog documented across our issue history. The proxy sits between CC and the Anthropic API, normalizes the request and response stream, and emits enough observability (via statusline integration and the quota-status files) that users can see what their session is actually doing. This is the load-bearing feature for almost every user today.
+
+**Bootstrap-channel observability.** Claude Code v2.1.150 introduced a prompt-section consumer that fetches a server-supplied string from `/api/claude_cli/bootstrap` and merges it into the agent's behavioral-instructions prompt path. We filed this behavior with Anthropic's security team in May 2026; Anthropic closed the report as *Informative*, treating TLS as the transport-integrity boundary and declining to add application-layer authenticity checks. Cache-fix v3.7.0 added explicit handling for this path. v3.7.1 extends it to also cover the env-var-selected GrowthBook prompt-injection surface that landed in CC v2.1.152 (remote-control mode: `CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE` names a flag key whose cached value is used as the system prompt body).
+
+Cache-fix's `bootstrap-defense` extension ships three modes, selected via `CACHE_FIX_BOOTSTRAP_MODE`:
+
+| Mode | Default? | Behavior |
+|---|---|---|
+| `audit` | yes | Bootstrap responses proxy through to CC. Each response is logged to `~/.claude/cache-fix-bootstrap-log.jsonl` with surface metadata: which prompt-source surfaces fired (`tengu_heron_brook` legacy and/or env-var-selected), the SHA-256 hash of the value (first 16 hex chars — never the value itself), and the `CLAUDE_CODE_REMOTE` flag. Multi-surface responses emit one record per surface, correlated by `request_id` + timestamp window. |
+| `block` | opt-in | `onRequest` returns a 200 with an empty JSON body. Upstream is never called, no flag map ever reaches the on-disk GrowthBook cache. Defeats both legacy and env-var-selected injection surfaces. |
+| `allowlist` | opt-in (experimental) | Bootstrap response proxies through, but prompt-source-eligible keys (legacy `tengu_heron_brook` + env-var-selected key) not in the allowlist are stripped from the response body before it reaches CC. Default allowlist is `tengu_heron_brook` (the only known-legitimate historical key); configure via `CACHE_FIX_BOOTSTRAP_ALLOWED_KEYS=comma,separated,list`. Pass `CACHE_FIX_BOOTSTRAP_ALLOWED_KEYS=` (explicit empty) for full deny-all. Other GrowthBook flag keys pass through untouched. May need updates if Anthropic adds legitimate prompt-source keys in future CC releases. |
+
+Note: cache-fix v3.6.2 and earlier returned 404 for the bootstrap path because the proxy router did not include it — the practical effect was that bootstrap content was not reaching CC for cache-fix users. v3.7.0's default `audit` changes that behavior; explicit `CACHE_FIX_BOOTSTRAP_MODE=block` preserves it. The full disclosure record, including Anthropic's verbatim close text, is in [`docs/disclosure/heron-brook-2026-05.md`](docs/disclosure/heron-brook-2026-05.md).
+
+**Reference material:**
+- [`docs/disclosure/heron-brook-2026-05.md`](docs/disclosure/heron-brook-2026-05.md) — full disclosure record
+- [`CHANGELOG.md`](CHANGELOG.md#371---2026-05-27) — v3.7.1 release entry (extended surface coverage + allowlist mode); [v3.7.0 entry](CHANGELOG.md#370---2026-05-26) covers the prior behavior-change note
+- [`cnighswonger/heron-brook-poc`](https://github.com/cnighswonger/heron-brook-poc) — reproducer for the bootstrap-channel behavior
+
 ## Recommended CC operational config
 
 The proxy fixes what it can fix at the request layer. A handful of CC client-side env vars and `~/.claude/settings.json` knobs solve adjacent problems the proxy can't reach — silent model swaps on CC update, ambiguous model fallback, schema-strip side effects. Surfacing these here as a recommendation; users decide their own config.
@@ -242,6 +263,18 @@ If you've seen the `autoCompactWindow: 1000000` setting recommended elsewhere: i
 
 If you set this flag, CC strips any tool field outside `["name", "description", "input_schema", "cache_control"]` from outgoing requests. Custom tools relying on `defer_loading` or `eager_input_streaming` will silently lose those fields and behave differently. Worth knowing before turning the flag on.
 
+## Known CC behaviors that affect cache cost
+
+These aren't bugs cache-fix patches — they're upstream CC behaviors users should be aware of when sizing their session cost.
+
+### Diagnostic slash commands inflate conversation history ([#49335](https://github.com/anthropics/claude-code/issues/49335))
+
+Running `/context`, `/release-notes` (and likely other state-inspection commands) appends the diagnostic output to conversation history rather than rendering terminal-only. Subsequent turns replay the inflated payload via prompt cache, compounding token cost on a state-inspection action that should be free. Empirically measured at +3,480 `cache_creation_input_tokens` for a single `/context` invocation on v2.1.148; another user reports ~5K on a separate session. `/release-notes` is worse — defaults to dumping the full changelog.
+
+Worse for diagnosis: the inflated payload that bills against your cache isn't written to the local JSONL transcript, so you can't audit the cost source locally — you can only infer it from `cache_creation_input_tokens` jumps in response usage metadata. (Proxy-mode users can inspect the deltas in `~/.claude/quota-status/` files, which the proxy writes directly from response headers.)
+
+**Workaround until upstream fix:** use these commands sparingly in long sessions. If you need them frequently in a session, consider `/compact` after a diagnostic run to reset the bleed.
+
 ## 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:
@@ -358,7 +391,7 @@ The interceptor can only *help* or *do nothing*. It cannot make things worse.
 Both modes write quota state on every API call. Proxy mode (v3.5.0+) splits into `~/.claude/quota-status/account.json` (account-global fields: Q5h/Q7d, status, overage) plus `~/.claude/quota-status/sessions/<id>.json` (per-session cache fields: TTL tier, hit rate). Preload mode keeps the legacy `~/.claude/quota-status.json` (single-session by construction). The included `tools/quota-statusline.sh` script displays a live status line showing:
 
 - **Q5h** quota bar `[███░┃░░░░░]` + percent + `(exhaust X, reset Y)`. Filled cells are consumed quota; the heavy-vertical tick is wall-clock elapsed position in the window. Tick to the right of the fill = under pace; tick inside the fill = burning faster than time (over pace). `exhaust` is the projected time-to-100% at the current burn rate; `reset` is the wall-clock time until the window rolls over. When `exhaust < reset`, you will hit 100% before the window resets — back off.
-- **Q7d** same shape with day-scale durations (e.g. `(exhaust 3d 13h, reset 3d 0h)`).
+- **Q7d** same shape with day-scale durations (e.g. `(exhaust 3d13h, reset 3d0h)`). Below a day, the suffix auto-switches to `h/m` format (e.g. `(exhaust 1h41m, reset 0h30m)`).
 - **TTL tier** — `TTL:1h` when healthy, **`TTL:5m` in red when the server has downgraded you** (typically at Q5h ≥ 100%)
 - **PEAK** in yellow during weekday peak hours (13:00–19:00 UTC)
 - **Cache hit rate %**
@@ -367,10 +400,10 @@ Both modes write quota state on every API call. Proxy mode (v3.5.0+) splits into
 Example line (mid-window, healthy state):
 
 ```
-Q5h [███░┃░░░░░] 30% (exhaust 4h40m, reset 3h00m) | Q7d [█████┃░░░░] 53% (exhaust 3d 13h, reset 3d 0h) | TTL:1h 98.3%
+Q5h [███░┃░░░░░] 30% (exhaust 4h40m, reset 3h00m) | Q7d [█████┃░░░░] 53% (exhaust 3d13h, reset 3d0h) | TTL:1h 98.3%
 ```
 
-The `(exhaust …, reset …)` suffix is dropped piecewise when projection isn't meaningful: at 0% (fresh window) and 100% (already exhausted) only `reset` is shown; in the first minute (Q5h) or six minutes (Q7d) after window start the burn rate isn't stable enough to project, so `exhaust` is held back until then; a stale `resets_at` (the server-reported value sits in the past, before the next API call refreshes it) drops both.
+The `(exhaust …, reset …)` suffix is dropped piecewise when projection isn't meaningful: at 0% (fresh window) and 100% (already exhausted) only `reset` is shown; in the first 5 minutes after window start the burn rate isn't stable enough to project (a single early call dominates the rate), so `exhaust` is held back until then on both Q5h and Q7d; a stale `resets_at` (the server-reported value sits in the past, before the next API call refreshes it) drops both.
 
 The bar uses Unicode block characters (`█┃░`) — most modern terminals render these correctly. If your terminal substitutes boxes or replacement glyphs, configure a Unicode-capable font (any DejaVu, Fira, Iosevka, JetBrains Mono, etc.).
 
@@ -740,6 +773,7 @@ We monitor 30+ upstream Claude Code issues related to cache, quota, and context
 - **[@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
+- **[@schuay](https://github.com/schuay)** — `quota-statusline.sh` enhancements: 10-cell quota bar with elapsed-time tick and exhaust-vs-reset projection replacing the prior `%/min` burn-rate display (PR #140, v3.6.2), and d/h vs h/m time-format autoselect plus named time-unit and burn-warmup constants (PR #143, v3.7.0)
 
 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,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.6.2",
+  "version": "3.7.1",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": {

package/proxy/config.mjs

@@ -10,14 +10,15 @@ function envInt(name, fallback) {
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Existing fields are read once at module init (preserving prior behavior).
-// New corp-proxy/CA fields are getters so they reflect live env — important
-// for test isolation (see test/proxy-upstream-corp-proxy.test.mjs) and for
-// callers that legitimately want to flip env at runtime.
+// Most fields are read once at module init (preserving prior behavior).
+// Corp-proxy/CA fields and `upstream` are getters so they reflect live env —
+// important for test isolation (see test/proxy-upstream-corp-proxy.test.mjs
+// and test/proxy-server-bootstrap.test.mjs) and for callers that legitimately
+// want to flip env at runtime.
 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",
+  get upstream() { return 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"),

package/proxy/extensions/bootstrap-defense.mjs

@@ -0,0 +1,286 @@
+import { appendFileSync, statSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
+const SCHEMA_VERSION = 2;
+const EXTENSION_VERSION = "v3.7.1";
+
+const LEGACY_PROMPT_KEY = "tengu_heron_brook";
+
+function logPath() {
+  return process.env.CACHE_FIX_BOOTSTRAP_LOG_PATH || join(homedir(), ".claude", "cache-fix-bootstrap-log.jsonl");
+}
+
+// Single-tier rotation by design: any previous .1 gets overwritten. The audit
+// log is a forward-looking signal feed, not an archival record — if v3.7.0
+// anomaly detection wants long-term retention it can subscribe to the stream
+// directly. Keeping rotation to one tier bounds disk usage at 2×5MB = 10MB.
+function rotateIfNeeded(path) {
+  let size = 0;
+  try { size = statSync(path).size; } catch { return; }
+  if (size < LOG_ROTATE_BYTES) return;
+  try { renameSync(path, `${path}.1`); } catch {}
+}
+
+// Single-writer invariant: cache-fix-proxy is one Node process per host, and
+// every bootstrap response that needs logging flows through this extension.
+// All writes are appendFileSync from a single event loop, so no inter-process
+// or inter-extension locking is required. If that invariant ever changes
+// (e.g. multi-process proxy, sibling extension writing to the same file),
+// this writer needs to gain a lock.
+function appendRecord(record) {
+  const path = logPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    rotateIfNeeded(path);
+    appendFileSync(path, JSON.stringify(record) + "\n");
+  } catch (err) {
+    process.stderr.write(`[bootstrap-defense] log write failed: ${err.message}\n`);
+  }
+}
+
+function modeFromEnv(fallback) {
+  const raw = process.env.CACHE_FIX_BOOTSTRAP_MODE;
+  if (raw === "audit" || raw === "block" || raw === "allowlist") return raw;
+  return fallback;
+}
+
+// Parse the allowlist env var. Distinguishes three states:
+//   - var unset            → default allowlist [LEGACY_PROMPT_KEY]
+//   - var = "" (explicit)  → empty allowlist (deny-all)
+//   - var = "a,b,c"        → [a, b, c] (trimmed, empty entries dropped)
+function allowedKeysFromEnv() {
+  const raw = process.env.CACHE_FIX_BOOTSTRAP_ALLOWED_KEYS;
+  if (raw === undefined) return new Set([LEGACY_PROMPT_KEY]);
+  if (raw === "") return new Set();
+  return new Set(raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0));
+}
+
+// Hash derivation contract (directive § Hash derivation): first 16 chars of
+// the lowercase hex SHA-256 digest over the UTF-8-encoded flag value. Pinned
+// here so a future refactor cannot silently change historical-record identity.
+function hashFlagValue(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex").slice(0, 16);
+}
+
+// PII discipline: the audit log MUST NOT include client headers (Authorization,
+// x-api-key, cookies, etc.) or request/response bodies. Callers pass only the
+// extracted scalar fields below — the full headers object is never threaded
+// through this function, so a future maintainer can't accidentally widen the
+// log surface by spreading the parameter object.
+//
+// v3.7.0 extension fields (baseline_hash, anomaly_status) are emitted as null
+// so log readers from that schema don't break. v3.7.1 adds the prompt-source
+// surface fields (surface, prompt_key, prompt_value_hash, remote_mode,
+// stripped_keys) — consumers reading v1 records should treat these as
+// null/empty array.
+function recordShape({
+  phase, mode, status, body_bytes, upstream_host, request_id, error,
+  surface, prompt_key, prompt_value_hash, remote_mode, stripped_keys,
+}) {
+  return {
+    schema_version: SCHEMA_VERSION,
+    extension_version: EXTENSION_VERSION,
+    timestamp: new Date().toISOString(),
+    phase,
+    mode,
+    status: status ?? null,
+    body_bytes: body_bytes ?? null,
+    upstream_host: upstream_host ?? null,
+    request_id: request_id ?? null,
+    baseline_hash: null,
+    anomaly_status: null,
+    error: error ?? null,
+    surface: surface ?? "bootstrap",
+    prompt_key: prompt_key ?? null,
+    prompt_value_hash: prompt_value_hash ?? null,
+    remote_mode: remote_mode ?? false,
+    stripped_keys: stripped_keys ?? [],
+  };
+}
+
+// Extract audit-record scalars from the request context. Meta wins over
+// headers so that the canonical request-side fields stashed by the server
+// (handleBootstrap stashes `_bootstrapUpstreamHost` and `_bootstrapRequestId`
+// before the upstream call) are authoritative on the onResponse path, where
+// ctx.headers carries the upstream RESPONSE headers (no Host, no request-id).
+// On the onRequest block path, meta hasn't been populated yet — the helper
+// falls back to ctx.headers (the client request headers) so request_id is
+// still captured. Upstream_host falls back to null on the request path
+// because the resolved upstream isn't known until handleBootstrap runs.
+//
+// Signature is scalar-only by design: callers MUST NOT spread a headers
+// object into recordShape, so a future maintainer can't accidentally widen
+// the log surface to carry Authorization / x-api-key / cookies.
+function extractAuditFields(meta, headers) {
+  const requestId =
+    meta?._bootstrapRequestId ??
+    headers?.["request-id"] ??
+    headers?.["x-request-id"] ??
+    null;
+  return {
+    upstream_host: meta?._bootstrapUpstreamHost ?? null,
+    request_id: requestId,
+  };
+}
+
+// Surface-activation logic (directive § Multi-surface records):
+//   - "bootstrap" surface fires when the legacy hardcoded key is in the body.
+//   - "prompt_injection_gb" surface fires when CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE
+//     is set, independent of whether that named key is in the body — this gives
+//     the audit log operator-visibility into env-configured intent even when
+//     the upstream did not deliver the value.
+function detectSurfaces(body) {
+  const surfaces = [];
+  const bodyIsObject = body !== null && typeof body === "object" && !Array.isArray(body);
+  if (bodyIsObject && Object.prototype.hasOwnProperty.call(body, LEGACY_PROMPT_KEY)) {
+    surfaces.push({ surface: "bootstrap", prompt_key: LEGACY_PROMPT_KEY });
+  }
+  const envKey = process.env.CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE;
+  if (envKey) {
+    surfaces.push({ surface: "prompt_injection_gb", prompt_key: envKey });
+  }
+  return surfaces;
+}
+
+export default {
+  name: "bootstrap-defense",
+  description:
+    "Audit (default), block, or allowlist server-controlled system-prompt injection through /api/claude_cli/bootstrap. " +
+    "Covers both the legacy tengu_heron_brook reader and the env-var-selected (CLAUDE_CODE_SYSTEM_PROMPT_GB_FEATURE) reader. " +
+    "Audit mode logs surface metadata to ~/.claude/cache-fix-bootstrap-log.jsonl. Block mode returns empty 200 from onRequest. " +
+    "Allowlist mode strips non-allowlisted prompt-source-eligible keys from the response body before returning it to CC.",
+  // Pipeline route scoping (pipeline.mjs:appliesToRoute) gates this extension
+  // to the bootstrap path. The internal route guard below is belt-and-suspenders
+  // in case a caller invokes the hook directly.
+  routes: ["bootstrap"],
+  order: 45,
+
+  async onRequest(ctx) {
+    if (ctx.meta?.route !== "bootstrap") return;
+
+    const mode = modeFromEnv("audit");
+    ctx.meta._bootstrapDefenseMode = mode;
+
+    if (mode === "block") {
+      appendRecord(
+        recordShape({
+          phase: "request_blocked",
+          mode,
+          ...extractAuditFields(ctx.meta, ctx.headers),
+          remote_mode: Boolean(process.env.CLAUDE_CODE_REMOTE),
+        }),
+      );
+      return {
+        skip: true,
+        status: 200,
+        headers: { "content-type": "application/json" },
+        body: {},
+      };
+    }
+  },
+
+  async onResponse(ctx) {
+    if (ctx.meta?.route !== "bootstrap") return;
+    const mode = ctx.meta._bootstrapDefenseMode || "audit";
+    if (mode !== "audit" && mode !== "allowlist") return;
+
+    // Prefer raw on-wire byte count from server.mjs (accurate even for
+    // non-JSON / unparseable upstream responses). The fallback stringify path
+    // exists only for direct unit-test invocation of onResponse without going
+    // through handleBootstrap — production traffic always sets the meta field.
+    let bodyBytes = ctx.meta?._bootstrapBodyBytes ?? null;
+    if (bodyBytes === null) {
+      try { bodyBytes = Buffer.byteLength(JSON.stringify(ctx.body ?? {})); } catch {}
+    }
+
+    const upstreamError = ctx.meta?._bootstrapUpstreamError ?? null;
+    const auditFields = extractAuditFields(ctx.meta, ctx.headers);
+    const remoteMode = Boolean(process.env.CLAUDE_CODE_REMOTE);
+    const baseRecord = {
+      mode,
+      status: ctx.status,
+      body_bytes: bodyBytes,
+      ...auditFields,
+      remote_mode: remoteMode,
+    };
+
+    // Anomaly path: upstream error or unparseable body. Single record with
+    // new fields defaulted; no multi-surface emission (directive § Multi-surface
+    // records, last paragraph).
+    if (upstreamError) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "upstream_error_audited",
+        error: upstreamError,
+      }));
+      return;
+    }
+    if (ctx.body === null || ctx.body === undefined) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "response_audited",
+      }));
+      return;
+    }
+
+    // Detect which prompt-source surfaces apply to this response.
+    const surfaces = detectSurfaces(ctx.body);
+
+    // No injection-detected baseline: single record preserving v3.7.0's
+    // record shape (surface defaults to "bootstrap", prompt_key null).
+    if (surfaces.length === 0) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "response_audited",
+      }));
+      return;
+    }
+
+    // Compute per-surface fields. Read from the original (unmutated) body
+    // for every surface BEFORE applying any allowlist strips, so multiple
+    // surfaces referencing the same key (env-var-aliases-legacy-key) both
+    // see the same value and emit identical prompt_value_hash.
+    const allowed = mode === "allowlist" ? allowedKeysFromEnv() : null;
+    const perSurface = surfaces.map((s) => {
+      const value = ctx.body[s.prompt_key];
+      const hash = typeof value === "string" ? hashFlagValue(value) : null;
+      const stripThis =
+        mode === "allowlist" &&
+        !allowed.has(s.prompt_key) &&
+        Object.prototype.hasOwnProperty.call(ctx.body, s.prompt_key);
+      return {
+        ...s,
+        prompt_value_hash: hash,
+        stripped_keys: stripThis ? [s.prompt_key] : [],
+      };
+    });
+
+    // Apply strips to ctx.body. Deletion is idempotent across multiple
+    // surfaces that target the same key (alias case).
+    if (mode === "allowlist") {
+      for (const r of perSurface) {
+        for (const k of r.stripped_keys) {
+          delete ctx.body[k];
+        }
+      }
+    }
+
+    // Emit one audit record per detected surface. Shared scalars
+    // (request_id, timestamp window, body_bytes, etc.) are duplicated across
+    // records emitted from a single response; consumers correlate by
+    // request_id + timestamp window.
+    for (const r of perSurface) {
+      appendRecord(recordShape({
+        ...baseRecord,
+        phase: "response_audited",
+        surface: r.surface,
+        prompt_key: r.prompt_key,
+        prompt_value_hash: r.prompt_value_hash,
+        stripped_keys: r.stripped_keys,
+      }));
+    }
+  },
+};

package/proxy/extensions.json

@@ -1,70 +1,20 @@
 {
-  "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
-  },
-  "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
-  },
-  "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
-  },
-  "cache-telemetry": {
-    "enabled": true,
-    "order": 600
-  },
-  "overage-warning": {
-    "enabled": true,
-    "order": 610
-  },
-  "request-log": {
-    "enabled": false,
-    "order": 700
-  }
+  "bootstrap-defense": { "enabled": true, "order": 45 },
+  "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 },
+  "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 },
+  "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 },
+  "cache-telemetry": { "enabled": true, "order": 600 },
+  "overage-warning": { "enabled": true, "order": 610 },
+  "request-log": { "enabled": false, "order": 700 }
 }

package/proxy/pipeline.mjs

@@ -46,10 +46,27 @@ export function snapshotRegistry() {
   return [...registry];
 }
 
+// Route scoping: extensions default to messages-only so that adding a new
+// route (e.g. /api/claude_cli/bootstrap) doesn't drag every existing
+// message-mutating extension onto it — most throw on a null body because
+// they were never designed for non-messages traffic. Cross-cutting
+// extensions (cache-telemetry, usage-log, …) opt into additional routes
+// by declaring an explicit `routes` array on their default export.
+//
+// If ctx.meta.route is undefined we skip filtering entirely — preserves
+// back-compat for callers that don't tag routes (legacy tests, embedders).
+function appliesToRoute(ext, route) {
+  if (!route) return true;
+  const routes = ext.routes || ["messages"];
+  return routes.includes(route);
+}
+
 export async function runOnRequest(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onRequest) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       const result = await ext.onRequest(ctx);
       if (result && result.skip) return result;
@@ -62,8 +79,10 @@ export async function runOnRequest(ctx, snapshot) {
 
 export async function runOnResponseStart(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onResponseStart) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       await ext.onResponseStart(ctx);
     } catch (err) {
@@ -74,8 +93,10 @@ export async function runOnResponseStart(ctx, snapshot) {
 
 export async function runOnStreamEvent(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onStreamEvent) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       await ext.onStreamEvent(ctx);
     } catch (err) {
@@ -86,8 +107,10 @@ export async function runOnStreamEvent(ctx, snapshot) {
 
 export async function runOnResponse(ctx, snapshot) {
   const exts = snapshot || registry;
+  const route = ctx.meta?.route;
   for (const ext of exts) {
     if (!ext.onResponse) continue;
+    if (!appliesToRoute(ext, route)) continue;
     try {
       await ext.onResponse(ctx);
     } catch (err) {

package/proxy/server.mjs

@@ -1,5 +1,5 @@
 import http from "node:http";
-import { pathToFileURL } from "node:url";
+import { pathToFileURL, URL } from "node:url";
 import config from "./config.mjs";
 import { forwardRequest } from "./upstream.mjs";
 import { streamResponse, createTelemetryRecord } from "./stream.mjs";
@@ -15,16 +15,15 @@ function collectBody(req) {
   });
 }
 
-async function handleMessages(clientReq, clientRes) {
-  const abortController = new AbortController();
-  const extSnapshot = snapshotRegistry();
-
-  clientReq.on("close", () => {
-    if (!clientRes.writableEnded) {
-      abortController.abort();
-    }
-  });
-
+// Run the pre-forward pipeline stages (collect body, parse, runOnRequest)
+// and either short-circuit with an extension-supplied response (block mode,
+// auth-failure synth, etc.) or return the inputs the caller needs to drive
+// forwarding and the post-response stages.
+//
+// `routeName` is stashed on ctx.meta.route so route-aware extensions
+// (bootstrap-defense, env-flag-detector) can discriminate without each
+// route needing its own pipeline hook.
+async function preForward(clientReq, clientRes, _abortController, extSnapshot, routeName, baseMeta = {}) {
   const rawBody = await collectBody(clientReq);
 
   let parsed;
@@ -35,23 +34,49 @@ async function handleMessages(clientReq, clientRes) {
   }
 
   let forwardBody = rawBody;
-  const meta = {};
+  // baseMeta lets routes pre-populate audit scalars (e.g. resolved upstream
+  // hostname, request_id) so they're available to onRequest hooks BEFORE the
+  // upstream call — block-mode short-circuits in onRequest, so a post-call
+  // stash would miss the block-path audit record.
+  const meta = { ...baseMeta, route: routeName };
 
-  if (parsed && extSnapshot.length > 0) {
+  if (extSnapshot.length > 0) {
     const reqCtx = { body: parsed, headers: { ...clientReq.headers }, meta };
     const skipResult = await runOnRequest(reqCtx, extSnapshot);
 
     if (skipResult && skipResult.skip) {
       const status = skipResult.status || 400;
-      const body = skipResult.body || { error: "blocked_by_extension" };
-      clientRes.writeHead(status, { "content-type": "application/json" });
-      clientRes.end(JSON.stringify(body));
-      return;
+      const headers = skipResult.headers || { "content-type": "application/json" };
+      const body = skipResult.body ?? { error: "blocked_by_extension" };
+      clientRes.writeHead(status, headers);
+      clientRes.end(typeof body === "string" ? body : JSON.stringify(body));
+      return { handled: true };
     }
 
-    forwardBody = Buffer.from(JSON.stringify(reqCtx.body));
+    if (parsed) {
+      forwardBody = Buffer.from(JSON.stringify(reqCtx.body));
+    }
   }
 
+  return { handled: false, parsed, forwardBody, meta };
+}
+
+async function handleMessages(clientReq, clientRes) {
+  const abortController = new AbortController();
+  const extSnapshot = snapshotRegistry();
+
+  // Streaming SSE: if the client gives up mid-stream, free the upstream.
+  // Bootstrap (handleBootstrap) doesn't install this because its response is
+  // a single non-SSE JSON payload — aborting on clientReq close prematurely
+  // would race the response write on fast-failure paths (e.g. ECONNREFUSED).
+  clientReq.on("close", () => {
+    if (!clientRes.writableEnded) abortController.abort();
+  });
+
+  const pre = await preForward(clientReq, clientRes, abortController, extSnapshot, "messages");
+  if (pre.handled) return;
+  const { parsed, forwardBody, meta } = pre;
+
   const requestedModel = parsed?.model || null;
 
   let upstreamRes, responseHeaders, statusCode, upstreamConnectionId;
@@ -129,6 +154,89 @@ async function handleMessages(clientReq, clientRes) {
   }
 }
 
+// Route handler for `/api/claude_cli/bootstrap` (CC v2.1.150+ system-prompt
+// injection channel). Same pipeline shape as handleMessages but without
+// the streaming branch — bootstrap is a single non-SSE JSON response.
+// The bootstrap-defense extension binds to onRequest/onResponse with
+// `ctx.meta.route === "bootstrap"` to drive audit/block behavior.
+async function handleBootstrap(clientReq, clientRes) {
+  const abortController = new AbortController();
+  const extSnapshot = snapshotRegistry();
+
+  // Resolve audit-record scalars BEFORE preForward so they're visible to
+  // onRequest hooks (block-mode short-circuits there). HTTP responses don't
+  // carry a Host header, so the audit log derives upstream_host from
+  // config.upstream — the actual destination requests were forwarded to.
+  let upstreamHost = null;
+  try {
+    upstreamHost = new URL(config.upstream).hostname;
+  } catch {}
+  const baseMeta = {
+    _bootstrapUpstreamHost: upstreamHost,
+    _bootstrapRequestId:
+      clientReq.headers["request-id"] ?? clientReq.headers["x-request-id"] ?? null,
+  };
+
+  const pre = await preForward(clientReq, clientRes, abortController, extSnapshot, "bootstrap", baseMeta);
+  if (pre.handled) return;
+  const { forwardBody, meta } = pre;
+
+  let upstreamRes, responseHeaders, statusCode, upstreamConnectionId;
+
+  try {
+    ({ upstreamRes, responseHeaders, statusCode, upstreamConnectionId } = await forwardRequest(
+      clientReq,
+      forwardBody,
+      abortController.signal,
+    ));
+  } catch (err) {
+    // Anomaly audit: bootstrap upstream errors are exactly the kind of event
+    // an attacker triggering DNS shenanigans or an outage would produce, so
+    // route them through the extension pipeline before responding 502.
+    if (extSnapshot.length > 0) {
+      meta._bootstrapUpstreamError = err.message;
+      meta._bootstrapBodyBytes = 0;
+      const errCtx = { status: 502, headers: {}, body: null, meta };
+      await runOnResponse(errCtx, extSnapshot);
+    }
+    clientRes.writeHead(502, { "content-type": "application/json" });
+    clientRes.end(JSON.stringify({ error: "upstream_error", message: err.message }));
+    return;
+  }
+
+  meta._upstreamConnectionId = upstreamConnectionId ?? null;
+
+  if (extSnapshot.length > 0) {
+    const resCtx = { status: statusCode, headers: responseHeaders, meta };
+    await runOnResponseStart(resCtx, extSnapshot);
+  }
+
+  const chunks = [];
+  for await (const chunk of upstreamRes) chunks.push(chunk);
+  const rawResponse = Buffer.concat(chunks);
+
+  if (extSnapshot.length > 0) {
+    let responseBody = null;
+    try {
+      responseBody = JSON.parse(rawResponse.toString());
+    } catch {}
+    // Stash raw byte count so bootstrap-defense (and future audit extensions)
+    // can record the on-wire payload size even when the body fails to parse.
+    // Non-JSON responses are exactly the anomaly audit mode needs to capture.
+    meta._bootstrapBodyBytes = rawResponse.length;
+    const resCtx = { status: statusCode, headers: responseHeaders, body: responseBody, meta };
+    await runOnResponse(resCtx, extSnapshot);
+    if (responseBody !== null) {
+      clientRes.writeHead(statusCode, resCtx.headers);
+      clientRes.end(JSON.stringify(resCtx.body));
+      return;
+    }
+  }
+
+  clientRes.writeHead(statusCode, responseHeaders);
+  clientRes.end(rawResponse);
+}
+
 function handleHealth(_req, res) {
   res.writeHead(200, { "content-type": "application/json" });
   res.end(JSON.stringify({ status: "ok" }));
@@ -157,6 +265,9 @@ export function createProxyServer() {
     if (req.method === "POST" && req.url?.startsWith("/v1/messages")) {
       return handleMessages(req, res);
     }
+    if (req.url?.startsWith("/api/claude_cli/bootstrap")) {
+      return handleBootstrap(req, res);
+    }
     handleNotFound(req, res);
   });
 }

package/tools/quota-statusline.sh

@@ -98,6 +98,17 @@ ts = sess.get('timestamp') or acc.get('timestamp', '')
 
 now = datetime.fromisoformat(ts.replace('Z', '+00:00')) if ts else datetime.now(timezone.utc)
 
+SECS_PER_MIN = 60
+MINS_PER_HR = 60
+HRS_PER_DAY = 24
+SECS_PER_HR = SECS_PER_MIN * MINS_PER_HR
+SECS_PER_DAY = SECS_PER_HR * HRS_PER_DAY
+
+# Minimum elapsed time in a window before we'll project an exhaust ETA from
+# its burn rate. Below this the rate is dominated by a single early call and
+# the projection is noise.
+BURN_WARMUP_SEC = 5 * SECS_PER_MIN
+
 BAR_WIDTH = 10
 
 def draw_bar(consumed_pct, elapsed_pct, width=BAR_WIDTH):
@@ -121,15 +132,15 @@ def draw_bar(consumed_pct, elapsed_pct, width=BAR_WIDTH):
             cells.append('░')
     return '[' + ''.join(cells) + ']'
 
-def fmt_hm(secs):
-    if secs is None or secs <= 0:
-        return ''
-    return '{}h{:02d}m'.format(int(secs // 3600), int((secs % 3600) // 60))
-
-def fmt_dh(secs):
+def fmt_time(secs):
+    # Autoselect scale: `{D}d{H}h` for >=1 day, `{H}h{MM}m` below that.
+    # One formatter so the Q5h (always h/m) and Q7d (h/m or d/h depending on
+    # how close to reset) callers don't need to pick.
     if secs is None or secs <= 0:
         return ''
-    return '{}d {}h'.format(int(secs // 86400), int((secs % 86400) // 3600))
+    if secs >= SECS_PER_DAY:
+        return '{}d{}h'.format(int(secs // SECS_PER_DAY), int((secs % SECS_PER_DAY) // SECS_PER_HR))
+    return '{}h{:02d}m'.format(int(secs // SECS_PER_HR), int((secs % SECS_PER_HR) // SECS_PER_MIN))
 
 def window_view(reset_ts, window_secs):
     # Returns (elapsed_sec, secs_left). elapsed_sec may be negative (server
@@ -150,7 +161,7 @@ def time_to_exhaust_sec(pct, elapsed_sec, min_elapsed_sec):
         return None
     return (100 - pct) * elapsed_sec / pct
 
-def format_window(name, pct, elapsed_sec, window_secs, secs_left, fmt_time, min_elapsed_sec):
+def format_window(name, pct, elapsed_sec, window_secs, secs_left, min_elapsed_sec):
     ep = None if elapsed_sec is None or elapsed_sec < 0 else elapsed_sec / window_secs * 100
     extras = []
     stale = secs_left is not None and secs_left <= 0
@@ -163,11 +174,11 @@ def format_window(name, pct, elapsed_sec, window_secs, secs_left, fmt_time, min_
     tail = ' (' + ', '.join(extras) + ')' if extras else ''
     return '{} {} {}%{}'.format(name, draw_bar(pct, ep), pct, tail)
 
-elapsed_5h, left_5h = window_view(q5h_reset, 5 * 3600)
-elapsed_7d, left_7d = window_view(q7d_reset, 7 * 86400)
+elapsed_5h, left_5h = window_view(q5h_reset, 5 * SECS_PER_HR)
+elapsed_7d, left_7d = window_view(q7d_reset, 7 * SECS_PER_DAY)
 
-label = format_window('Q5h', q5h, elapsed_5h, 5 * 3600, left_5h, fmt_hm, 60)
-label += ' | ' + format_window('Q7d', q7d, elapsed_7d, 7 * 86400, left_7d, fmt_dh, 360)
+label = format_window('Q5h', q5h, elapsed_5h, 5 * SECS_PER_HR, left_5h, BURN_WARMUP_SEC)
+label += ' | ' + format_window('Q7d', q7d, elapsed_7d, 7 * SECS_PER_DAY, left_7d, BURN_WARMUP_SEC)
 if overage == 'active':
     label += ' | OVERAGE'