claude-code-cache-fix 3.2.1 → 3.3.0

package/README.ko.md

@@ -254,6 +254,38 @@ export CACHE_FIX_IMAGE_KEEP_LAST=3
 
 최근 3개 사용자 메시지의 이미지를 유지하고 이전 것은 텍스트 자리 표시자로 대체합니다. `tool_result` 블록만 대상이며, 사용자가 직접 붙여넣은 이미지는 영향받지 않습니다.
 
+### 이미지 가드 파이프라인 (v3.3.0)
+
+Anthropic의 실제 이미지 규칙을 그대로 반영하는 조건부 파이프라인입니다. 단일 환경 변수로 명시적 활성화:
+
+```bash
+export CACHE_FIX_IMAGE_GUARD=1
+```
+
+활성화 시 프록시는 다음을 실행합니다:
+
+| 패스 | 트리거 | 동작 |
+|------|--------|------|
+| **Pass 0** (레거시) | `CACHE_FIX_IMAGE_KEEP_LAST=N` 설정 | 가장 최근 N개 이외 사용자 메시지의 tool_result 이미지 제거 |
+| **Pass 3** | `CACHE_FIX_IMAGE_PRESERVE_DETAIL=1` AND 긴 변 > 모델 네이티브 캡 | `sharp`를 통해 네이티브 캡(Opus 4.7은 2576px, 그 외는 1568px)으로 Lanczos 리사이즈, 종횡비와 미디어 타입 보존 |
+| **Pass 1** | 긴 변 > 활성 거부 캡 | 제거 후 forensic 자리 표시자로 대체. 활성 캡 = `MAX_DIM` 설정 시 그 값, 아니면 2000px (개수 > 20일 때) 또는 8000px (개수 ≤ 20) |
+| **Pass 2** | 요청 본문이 `CACHE_FIX_IMAGE_REQUEST_SIZE_MAX` (기본 30 MB) 초과 | 예산 이하가 될 때까지 가장 오래된 이미지부터 제거 |
+| **개수 캡** | 잔여 이미지 개수 > `CACHE_FIX_IMAGE_COUNT_MAX` (기본 100) | 캡까지 가장 오래된 이미지 제거 |
+
+실행 순서: **Pass 0 → Pass 3 → Pass 1 → Pass 2 → 개수 캡**. 각 패스는 독립적입니다 — Pass 1은 절대 리사이즈하지 않으며, Pass 3는 절대 제거하지 않습니다.
+
+#### 선택적 `sharp` 의존성
+
+Pass 3는 Lanczos 리사이즈를 위해 [sharp](https://www.npmjs.com/package/sharp)가 필요합니다. **선택적 peer dependency**로 선언되어 있으며, Pass 3를 사용하려면 별도로 설치하십시오:
+
+```bash
+npm install sharp
+```
+
+`sharp`가 없는 경우 Pass 3는 깨끗하게 건너뛰며 (telemetry에 `library_missing: true`), Pass 1 + Pass 2 + 개수 캡은 정상 실행됩니다.
+
+전체 우선순위 매트릭스(레거시 + 신규 환경 변수의 모든 조합) 및 튜닝 가능한 항목은 [README.md](README.md#image-guard-pipeline-v330)를 참조하십시오.
+
 ## 시스템 프롬프트 재작성 (프리로드 모드, 선택)
 
 인터셉터가 Claude Code의 `# Output efficiency` 시스템 프롬프트 섹션을 재작성할 수 있습니다. 기본 비활성화입니다. `CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT`로 활성화하십시오. 세 가지 알려진 프롬프트 변형과 사용법은 [docs/output-efficiency-prompts.md](docs/output-efficiency-prompts.md)를 참조하십시오.

package/README.md

@@ -334,7 +334,7 @@ export CACHE_FIX_IMAGE_KEEP_LAST=3
 
 Keeps images in the last 3 user messages, replaces older ones with a text placeholder. Only targets `tool_result` blocks — user-pasted images are never touched.
 
-### Oversized-image guard
+### Oversized-image guard (legacy, v3.2.1)
 
 ```bash
 export CACHE_FIX_IMAGE_MAX_DIM=2000
@@ -355,6 +355,60 @@ The two compose: with both set, `KEEP_LAST` runs first (drops the count), then `
 
 Pure-JS PNG and JPEG header parsing — no native deps. Other formats (GIF, WebP, AVIF, BMP) pass through unchanged regardless of dimension. Fail-open: images whose dimensions can't be parsed (truncated header, unsupported format) are kept rather than stripped — better to send a request that might error than to strip a valid image we just couldn't measure.
 
+### Image-guard pipeline (v3.3.0)
+
+A conditional pipeline that mirrors Anthropic's actual rules. Strictly opt-in via a single env var:
+
+```bash
+export CACHE_FIX_IMAGE_GUARD=1
+```
+
+When enabled, the proxy runs:
+
+| Pass | Trigger | Action |
+|------|---------|--------|
+| **Pass 0** (legacy) | `CACHE_FIX_IMAGE_KEEP_LAST=N` set | Strip tool_result images from user messages older than N most recent |
+| **Pass 3** | `CACHE_FIX_IMAGE_PRESERVE_DETAIL=1` AND image long edge > model native cap | Lanczos resize via `sharp` to native cap (2576 px for Opus 4.7, 1568 px otherwise), preserve aspect ratio and media type |
+| **Pass 1** | image long edge > active rejection cap | Strip and replace with forensic placeholder. Active cap = `MAX_DIM` if set, else 2000 px (when count > 20) or 8000 px (count ≤ 20) |
+| **Pass 2** | request body exceeds `CACHE_FIX_IMAGE_REQUEST_SIZE_MAX` (default 30 MB) | Drop oldest images until under budget |
+| **Count cap** | surviving image count > `CACHE_FIX_IMAGE_COUNT_MAX` (default 100) | Drop oldest images down to the cap |
+
+Execution order: **Pass 0 → Pass 3 → Pass 1 → Pass 2 → count cap**. Each pass is independent — Pass 1 never resizes; Pass 3 never strips.
+
+#### Optional `sharp` dependency
+
+Pass 3 requires [sharp](https://www.npmjs.com/package/sharp) for Lanczos resize. It's declared as an **optional peer dependency** — install separately if you want Pass 3:
+
+```bash
+npm install sharp
+```
+
+If `sharp` is missing, Pass 3 skips cleanly (telemetry records `library_missing: true`); Pass 1 + Pass 2 + the count cap still run.
+
+#### Precedence matrix
+
+| Env var combination | Behavior |
+|---|---|
+| Nothing set | No image processing (back-compat default; the extension short-circuits). |
+| `KEEP_LAST=N` only | Existing v3.2.1: count cap on tool_result images in user messages, runs first. No pipeline. |
+| `MAX_DIM=N` only | Existing v3.2.1: hard size cap, strip-only. No pipeline. |
+| `KEEP_LAST=N` + `MAX_DIM=N` | Existing v3.2.1 composition: `KEEP_LAST` runs first (drops count), then `MAX_DIM` runs on survivors (caps size). No pipeline, no Pass 2, no Pass 3. |
+| `IMAGE_GUARD=1` | New pipeline: Pass 1 (conditional cap) + Pass 2 (request-size guard) + image-count cap. |
+| `IMAGE_GUARD=1` + `MAX_DIM=N` | `MAX_DIM` overrides Pass 1's conditional cap (acts as the cap value); Pass 2 still runs. |
+| `IMAGE_GUARD=1` + `PRESERVE_DETAIL=1` | Adds Pass 3 (Lanczos resize via `sharp`). When `sharp` unavailable, falls back to strip behavior. |
+| `IMAGE_GUARD=1` + `KEEP_LAST=N` | `KEEP_LAST` runs first as count cap (Pass 0); pipeline runs on remainder. |
+| `IMAGE_GUARD=1` + `KEEP_LAST=N` + `MAX_DIM=N` | Three-way: `KEEP_LAST` runs first; pipeline runs on remainder, but `MAX_DIM` overrides Pass 1's conditional cap; Pass 2 still runs. |
+| `PRESERVE_DETAIL=1` without `IMAGE_GUARD=1` | Logs warning, treats as no-op. `PRESERVE_DETAIL` is meaningless without the pipeline running. |
+
+#### Tunables
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `CACHE_FIX_IMAGE_GUARD` | unset | Top-level pipeline gate (`=1` enables). |
+| `CACHE_FIX_IMAGE_PRESERVE_DETAIL` | unset | Enable Pass 3 Lanczos resize via `sharp`. |
+| `CACHE_FIX_IMAGE_REQUEST_SIZE_MAX` | 31457280 (30 MB) | Pass 2 byte budget. 2 MB headroom from Anthropic's 32 MB ceiling. |
+| `CACHE_FIX_IMAGE_COUNT_MAX` | 100 | Hard image-count cap. Set to 600 for legacy Claude 1/2.x/Instant if needed. |
+
 ## System prompt rewrite (preload mode, optional)
 
 The interceptor can rewrite Claude Code's `# Output efficiency` system-prompt section. Disabled by default. Enable with `CACHE_FIX_OUTPUT_EFFICIENCY_REPLACEMENT`. See [docs/output-efficiency-prompts.md](docs/output-efficiency-prompts.md) for the three known prompt variants and usage instructions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",
@@ -27,6 +27,11 @@
   "dependencies": {
     "hpagent": "^1.2.0"
   },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
+  },
   "keywords": [
     "claude-code",
     "claude",

package/proxy/extensions/image-strip.mjs

@@ -1,5 +1,26 @@
+// image-strip extension — back-compat for v3.2.1 KEEP_LAST/MAX_DIM behavior
+// PLUS the v3.3.0 image-guard pipeline.
+//
+// Activation pattern: `enabled: true` in extensions.json (the extension is
+// always loaded), runtime gates per-feature via env vars. Three independent
+// trigger surfaces:
+//
+//   - CACHE_FIX_IMAGE_KEEP_LAST=N        → legacy Pass 0 (count cap on
+//                                          tool_result images in user msgs)
+//   - CACHE_FIX_IMAGE_MAX_DIM=N          → legacy Pass 1 strip-only (back-compat)
+//   - CACHE_FIX_IMAGE_GUARD=1            → v3.3.0 pipeline (Pass 1 + 2 + count cap)
+//   - CACHE_FIX_IMAGE_GUARD=1 +
+//     CACHE_FIX_IMAGE_PRESERVE_DETAIL=1  → adds Pass 3 (Lanczos resize via sharp)
+//
+// Execution order: Pass 0 → Pass 3 → Pass 1 → Pass 2 → image-count cap.
+//
+// See `docs/directives/proxy-image-guard-pipeline.md` for full spec, including
+// the precedence matrix and per-pass trigger/action contracts.
+
 import { parseImageDimensions } from "../image-dimensions.mjs";
+import { resizeImageToCap } from "../image-resize.mjs";
 
+// --- Legacy v3.2.1 constants (back-compat) ---
 const KEEP_LAST = parseInt(process.env.CACHE_FIX_IMAGE_KEEP_LAST || "0", 10);
 const MAX_DIM = parseInt(process.env.CACHE_FIX_IMAGE_MAX_DIM || "0", 10);
 const PLACEHOLDER = "[image stripped from history — file may still be on disk]";
@@ -8,6 +29,34 @@ function oversizedPlaceholder(maxDim, w, h) {
   return `[image stripped — exceeded ${maxDim}px max dimension (was ${w}x${h}px)]`;
 }
 
+// --- v3.3.0 pipeline env helpers (read at call time, not at module load,
+// so per-test isolation works without re-importing the module) ---
+function isImageGuardEnabled() {
+  return process.env.CACHE_FIX_IMAGE_GUARD === "1";
+}
+function isPreserveDetailEnabled() {
+  return process.env.CACHE_FIX_IMAGE_PRESERVE_DETAIL === "1";
+}
+function getMaxDim() {
+  return parseInt(process.env.CACHE_FIX_IMAGE_MAX_DIM || "0", 10);
+}
+function getKeepLast() {
+  return parseInt(process.env.CACHE_FIX_IMAGE_KEEP_LAST || "0", 10);
+}
+function getRequestSizeMax() {
+  // Default 30 MB (31457280 bytes). 2 MB headroom from Anthropic's 32 MB body limit.
+  const v = parseInt(process.env.CACHE_FIX_IMAGE_REQUEST_SIZE_MAX || "31457280", 10);
+  return v > 0 ? v : 31457280;
+}
+function getImageCountMax() {
+  // Default 100 — single cap covering the only model family in active CC use.
+  // Users on legacy Claude 1/2.x/Instant who genuinely need 600 can override.
+  const v = parseInt(process.env.CACHE_FIX_IMAGE_COUNT_MAX || "100", 10);
+  return v > 0 ? v : 100;
+}
+
+// --- Legacy Pass 0: KEEP_LAST tool_result image strip ---
+// (Unchanged from v3.2.1 — only formatting tightened.)
 function stripOldToolResultImages(messages, keepLast) {
   if (!keepLast || keepLast <= 0 || !Array.isArray(messages)) {
     return { messages, stats: null };
@@ -65,15 +114,9 @@ function stripOldToolResultImages(messages, keepLast) {
   return { messages: strippedCount > 0 ? result : messages, stats };
 }
 
-// Strip oversized images from BOTH user-message direct content and
-// tool_result-nested content. Orthogonal to KEEP_LAST: scans every image
-// remaining in the message list and replaces any whose width or height
-// exceeds maxDim. Fail-open: images we can't measure (unsupported format,
-// truncated header) are kept rather than stripped.
-//
-// Stripping by oversize prevents the Anthropic API error:
-//   "An image in the conversation exceeds the dimension limit for many-image
-//    requests (2000px). Start a new session with fewer images."
+// --- Legacy Pass 1 (strip-only by max dim) ---
+// (Unchanged from v3.2.1.) The new pipeline's Pass 1 is a separate function
+// (`runPass1RejectionCapStrip`) that uses the conditional 2000/8000 logic.
 function stripOversizedImages(messages, maxDim) {
   if (!maxDim || maxDim <= 0 || !Array.isArray(messages)) {
     return { messages, stats: null };
@@ -87,7 +130,7 @@ function stripOversizedImages(messages, maxDim) {
     const src = item.source;
     if (!src || !src.data || !src.media_type) return item;
     const dims = parseImageDimensions(src.media_type, src.data);
-    if (!dims) return item; // can't measure → keep
+    if (!dims) return item;
     if (dims.width <= maxDim && dims.height <= maxDim) return item;
     strippedCount++;
     strippedBytes += src.data.length;
@@ -98,7 +141,6 @@ function stripOversizedImages(messages, maxDim) {
     if (!Array.isArray(msg.content)) return msg;
     let mutated = false;
     const newContent = msg.content.map((block) => {
-      // Direct image block on a user message
       if (block && block.type === "image") {
         const replaced = maybeStrip(block);
         if (replaced !== block) {
@@ -107,7 +149,6 @@ function stripOversizedImages(messages, maxDim) {
         }
         return block;
       }
-      // Image nested inside a tool_result.content array
       if (block && block.type === "tool_result" && Array.isArray(block.content)) {
         let toolMutated = false;
         const newToolContent = block.content.map((item) => {
@@ -132,49 +173,530 @@ function stripOversizedImages(messages, maxDim) {
   return { messages: strippedCount > 0 ? result : messages, stats };
 }
 
-export { stripOldToolResultImages, stripOversizedImages, PLACEHOLDER, oversizedPlaceholder };
+// =============================================================================
+// v3.3.0 pipeline
+// =============================================================================
+
+// --- Pure helpers (exported for tests) ---
+
+// Pass 1 cap selector. `maxDimOverride > 0` always wins over the conditional
+// rejection cap. Otherwise: count > 20 → 2000 px, else 8000 px.
+function pickPass1Cap(imageCount, maxDimOverride) {
+  if (maxDimOverride && maxDimOverride > 0) return maxDimOverride;
+  return imageCount > 20 ? 2000 : 8000;
+}
+
+// Pass 3 native-cap selector. Only Opus 4.7 has the higher cap.
+function pickPass3NativeCap(modelString) {
+  if (typeof modelString === "string" && modelString.startsWith("claude-opus-4-7")) {
+    return 2576;
+  }
+  return 1568;
+}
+
+// Anthropic's documented per-image token formula: `width * height / 750`,
+// capped at the model's native token cap. Diagnostic only (no enforcement).
+function estimateImageTokens(width, height, modelTokenCap) {
+  if (!width || !height) return 0;
+  const raw = Math.ceil((width * height) / 750);
+  if (modelTokenCap && raw > modelTokenCap) return modelTokenCap;
+  return raw;
+}
+
+function nativeTokenCap(modelString) {
+  if (typeof modelString === "string" && modelString.startsWith("claude-opus-4-7")) {
+    return 4784;
+  }
+  return 1568;
+}
+
+// Walker: enumerate every image in `body.messages`, both user-msg direct content
+// and tool_result.content. Returns a list of `{ msgIdx, blockIdx, itemIdx | null,
+// item }` references. `itemIdx === null` means the image is a direct user-msg
+// content block (not nested in tool_result).
+function walkImages(messages) {
+  const out = [];
+  if (!Array.isArray(messages)) return out;
+  for (let m = 0; m < messages.length; m++) {
+    const msg = messages[m];
+    if (!Array.isArray(msg.content)) continue;
+    for (let b = 0; b < msg.content.length; b++) {
+      const block = msg.content[b];
+      if (!block) continue;
+      if (block.type === "image") {
+        out.push({ msgIdx: m, blockIdx: b, itemIdx: null, item: block });
+      } else if (block.type === "tool_result" && Array.isArray(block.content)) {
+        for (let i = 0; i < block.content.length; i++) {
+          const item = block.content[i];
+          if (item && item.type === "image") {
+            out.push({ msgIdx: m, blockIdx: b, itemIdx: i, item });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// Mutate a single image at the given (msgIdx, blockIdx, itemIdx) reference,
+// either replacing it with a placeholder text block (strip) or updating its
+// source.data + dims (resize).
+function replaceImageInPlace(messages, ref, replacement) {
+  const msg = messages[ref.msgIdx];
+  if (!msg || !Array.isArray(msg.content)) return;
+  const block = msg.content[ref.blockIdx];
+  if (!block) return;
+  if (ref.itemIdx === null) {
+    msg.content[ref.blockIdx] = replacement;
+  } else {
+    if (!Array.isArray(block.content)) return;
+    block.content[ref.itemIdx] = replacement;
+  }
+}
+
+// Pure walker for Pass 1: returns the list of image refs whose long edge
+// exceeds `capPx`, alongside their measured dims. Unparseable images are not
+// included (fail-open). Exposed for tests.
+function walkImagesForPass1(messages, capPx) {
+  const refs = walkImages(messages);
+  const plan = [];
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data || !src.media_type) continue;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) {
+      plan.push({ ref, dims: null, action: "skip_unmeasurable" });
+      continue;
+    }
+    const longEdge = Math.max(dims.width, dims.height);
+    if (longEdge > capPx) {
+      plan.push({ ref, dims, action: "strip" });
+    }
+  }
+  return plan;
+}
+
+// Pure walker for Pass 3: returns refs whose long edge exceeds `nativeCapPx`,
+// plus the dims/cap so the caller can do the actual resize.
+function walkImagesForPass3(messages, nativeCapPx) {
+  const refs = walkImages(messages);
+  const plan = [];
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data || !src.media_type) continue;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) {
+      plan.push({ ref, dims: null, action: "skip_unmeasurable" });
+      continue;
+    }
+    const longEdge = Math.max(dims.width, dims.height);
+    if (longEdge > nativeCapPx) {
+      plan.push({ ref, dims, action: "resize", capPx: nativeCapPx });
+    }
+  }
+  return plan;
+}
+
+// Eviction order for Pass 2 / count cap: oldest first (low msgIdx wins),
+// within a message tool_result images are preferred over direct images at the
+// same age. Returns an ordered list of refs to drop.
+function pickEvictionTargets(messages) {
+  const refs = walkImages(messages);
+  // Stable sort: by msgIdx ascending, then prefer tool_result (itemIdx !== null)
+  // over direct (itemIdx === null) at the same msgIdx.
+  refs.sort((a, b) => {
+    if (a.msgIdx !== b.msgIdx) return a.msgIdx - b.msgIdx;
+    const aTool = a.itemIdx !== null ? 0 : 1;
+    const bTool = b.itemIdx !== null ? 0 : 1;
+    if (aTool !== bTool) return aTool - bTool;
+    if (a.blockIdx !== b.blockIdx) return a.blockIdx - b.blockIdx;
+    return (a.itemIdx ?? 0) - (b.itemIdx ?? 0);
+  });
+  return refs;
+}
+
+// --- Stats initializer (matches the directive's telemetry surface verbatim) ---
+function initStats() {
+  return {
+    total_images: 0,
+    count_axis_path: "few",
+    unsupported_format_count: 0,
+    dimension_probe_fail_count: 0,
+    resize_attempted: 0,
+    resize_succeeded: 0,
+    resize_failed: 0,
+    library_missing: false,
+    images_stripped_pass1: 0,
+    images_dropped_for_size: 0,
+    images_dropped_for_count_cap: 0,
+
+    request_bytes_before: 0,
+    request_bytes_after: 0,
+    request_bytes_headroom: 0,
+    image_bytes_total: 0,
+    image_bytes_dropped: 0,
+
+    estimated_image_tokens_total: 0,
+  };
+}
+
+// --- Pass 3 runtime: native-cap resize via sharp ---
+async function runPass3NativeCapResize(reqCtx, stats) {
+  if (stats.library_missing) return;
+
+  const messages = reqCtx.body.messages;
+  const model = reqCtx.body.model;
+  const nativeCap = pickPass3NativeCap(model);
+  const tokenCap = nativeTokenCap(model);
+
+  const plan = walkImagesForPass3(messages, nativeCap);
+  for (const step of plan) {
+    if (step.action === "skip_unmeasurable") {
+      // Tracked separately via the unsupported/probe counters at the top-level
+      // walker (we double-count if we touch them here too — leave it to the
+      // central counter pass).
+      continue;
+    }
+    if (step.action !== "resize") continue;
+
+    const src = step.ref.item.source;
+    stats.resize_attempted++;
+    const result = await resizeImageToCap(src.data, src.media_type, step.capPx);
+    if (result.ok) {
+      stats.resize_succeeded++;
+      // Mutate in place: keep the same content block shape, swap data + record dims.
+      const newImage = {
+        ...step.ref.item,
+        source: { ...src, data: result.base64 },
+      };
+      replaceImageInPlace(messages, step.ref, newImage);
+      const tokensBefore = estimateImageTokens(step.dims.width, step.dims.height, tokenCap);
+      const tokensAfter = estimateImageTokens(result.dims.width, result.dims.height, tokenCap);
+      stats.estimated_image_tokens_total += tokensAfter - tokensBefore;
+    } else if (result.reason === "library_missing") {
+      stats.library_missing = true;
+      // Sticky: stop attempting Pass 3 for the remainder of this request.
+      // (loadSharp() inside image-resize.mjs is also sticky for the process.)
+      return;
+    } else {
+      stats.resize_failed++;
+      // Leave image untouched; Pass 1 will evaluate it against its own cap.
+    }
+  }
+}
+
+// --- Pass 1 runtime: conditional rejection-cap strip ---
+function runPass1RejectionCapStrip(reqCtx, stats, opts) {
+  const { maxDimOverride } = opts || {};
+  const messages = reqCtx.body.messages;
+
+  const refs = walkImages(messages);
+  const imageCount = refs.length;
+  stats.total_images = Math.max(stats.total_images, imageCount);
+  stats.count_axis_path = imageCount > 20 ? "many" : "few";
+  const cap = pickPass1Cap(imageCount, maxDimOverride);
+
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data || !src.media_type) continue;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (!dims) {
+      // Distinguish unsupported format from probe failure on a known type.
+      const mt = (src.media_type || "").toLowerCase();
+      if (mt === "image/png" || mt === "image/jpeg" || mt === "image/jpg") {
+        stats.dimension_probe_fail_count++;
+      } else {
+        stats.unsupported_format_count++;
+      }
+      continue;
+    }
+    const longEdge = Math.max(dims.width, dims.height);
+    if (longEdge > cap) {
+      replaceImageInPlace(messages, ref, {
+        type: "text",
+        text: oversizedPlaceholder(cap, dims.width, dims.height),
+      });
+      stats.images_stripped_pass1++;
+    }
+  }
+}
+
+// --- Pass 2 runtime: request-size guard ---
+function runPass2RequestSizeGuard(reqCtx, stats) {
+  const budget = getRequestSizeMax();
+  const before = Buffer.byteLength(JSON.stringify(reqCtx.body));
+  if (stats.request_bytes_before === 0) stats.request_bytes_before = before;
+
+  if (before <= budget) {
+    stats.request_bytes_after = before;
+    stats.request_bytes_headroom = budget - before;
+    return;
+  }
+
+  // Build eviction queue once; drop one at a time, re-measuring after each drop.
+  const queue = pickEvictionTargets(reqCtx.body.messages);
+  let bytes = before;
+  for (const ref of queue) {
+    if (bytes <= budget) break;
+    const src = ref.item.source;
+    const droppedBytes = src && src.data ? src.data.length : 0;
+    replaceImageInPlace(reqCtx.body.messages, ref, {
+      type: "text",
+      text: "[image dropped to fit request-size budget]",
+    });
+    stats.images_dropped_for_size++;
+    stats.image_bytes_dropped += droppedBytes;
+    bytes = Buffer.byteLength(JSON.stringify(reqCtx.body));
+  }
+  stats.request_bytes_after = bytes;
+  stats.request_bytes_headroom = budget - bytes;
+  // If we exhausted the queue and bytes still exceed budget, the body is
+  // over-budget for non-image reasons; the request will fail upstream and we
+  // don't address that here. Telemetry already records the final bytes.
+}
+
+// --- Hard image-count cap ---
+function runImageCountCap(reqCtx, stats) {
+  const cap = getImageCountMax();
+  const queue = pickEvictionTargets(reqCtx.body.messages);
+  if (queue.length <= cap) return;
+  const toDrop = queue.length - cap;
+  for (let i = 0; i < toDrop; i++) {
+    const ref = queue[i];
+    const src = ref.item.source;
+    const droppedBytes = src && src.data ? src.data.length : 0;
+    replaceImageInPlace(reqCtx.body.messages, ref, {
+      type: "text",
+      text: "[image dropped — exceeded image-count cap]",
+    });
+    stats.images_dropped_for_count_cap++;
+    stats.image_bytes_dropped += droppedBytes;
+  }
+  // Recompute request_bytes_after after count-cap evictions so the final
+  // telemetry reflects the post-pipeline body. Without this, count-cap-only
+  // requests would report unchanged byte totals (Codex review note).
+  if (toDrop > 0) {
+    const budget = getRequestSizeMax();
+    const after = Buffer.byteLength(JSON.stringify(reqCtx.body));
+    stats.request_bytes_after = after;
+    stats.request_bytes_headroom = budget - after;
+  }
+}
+
+// --- Telemetry: walk surviving images for byte/token totals ---
+function finalizeTelemetry(reqCtx, stats) {
+  const refs = walkImages(reqCtx.body.messages);
+  let totalBytes = 0;
+  let totalTokens = 0;
+  const tokenCap = nativeTokenCap(reqCtx.body.model);
+  for (const ref of refs) {
+    const src = ref.item.source;
+    if (!src || !src.data) continue;
+    totalBytes += src.data.length;
+    const dims = parseImageDimensions(src.media_type, src.data);
+    if (dims) {
+      totalTokens += estimateImageTokens(dims.width, dims.height, tokenCap);
+    }
+  }
+  stats.image_bytes_total = totalBytes;
+  // estimated_image_tokens_total was decremented by Pass 3 deltas; for the
+  // baseline (Pass 3 disabled) recompute from surviving images.
+  if (stats.resize_attempted === 0) {
+    stats.estimated_image_tokens_total = totalTokens;
+  } else {
+    // Pass 3 mutated in place; re-measure surviving population to ground-truth.
+    stats.estimated_image_tokens_total = totalTokens;
+  }
+}
+
+// --- Top-level pipeline orchestrator ---
+async function runImageGuard(reqCtx) {
+  const stats = initStats();
+  const messages = reqCtx.body.messages;
+  if (!Array.isArray(messages)) return stats;
+
+  // Capture initial population count for the summary line.
+  stats.total_images = walkImages(messages).length;
+  stats.count_axis_path = stats.total_images > 20 ? "many" : "few";
+
+  const guardOn = isImageGuardEnabled();
+  const preserveOn = isPreserveDetailEnabled();
+  const maxDimOverride = getMaxDim();
+
+  // Warn if PRESERVE_DETAIL is set without IMAGE_GUARD (one-time per process).
+  if (!guardOn && preserveOn && !_preserveDetailWarned) {
+    process.stderr.write(
+      "[image-guard] CACHE_FIX_IMAGE_PRESERVE_DETAIL=1 has no effect without CACHE_FIX_IMAGE_GUARD=1\n"
+    );
+    _preserveDetailWarned = true;
+  }
+
+  // Pass 3: native-cap resize (only when both gates are on)
+  if (guardOn && preserveOn) {
+    await runPass3NativeCapResize(reqCtx, stats);
+  }
+
+  // Pass 1: rejection-cap strip — runs if IMAGE_GUARD=1 OR legacy MAX_DIM > 0
+  if (guardOn || maxDimOverride > 0) {
+    runPass1RejectionCapStrip(reqCtx, stats, { maxDimOverride });
+  }
+
+  // Pass 2: request-size guard — IMAGE_GUARD only
+  if (guardOn) {
+    runPass2RequestSizeGuard(reqCtx, stats);
+  }
+
+  // Hard image-count cap — IMAGE_GUARD only
+  if (guardOn) {
+    runImageCountCap(reqCtx, stats);
+  }
+
+  // Final telemetry sweep over surviving images
+  finalizeTelemetry(reqCtx, stats);
+
+  return stats;
+}
+
+// One-time warning state for PRESERVE_DETAIL-without-GUARD.
+let _preserveDetailWarned = false;
+
+// Test hook to reset warning flag.
+function _resetWarningStateForTests() {
+  _preserveDetailWarned = false;
+}
+
+export {
+  // Legacy v3.2.1 exports (kept stable for back-compat tests)
+  stripOldToolResultImages,
+  stripOversizedImages,
+  PLACEHOLDER,
+  oversizedPlaceholder,
+  // v3.3.0 pipeline pure functions (test seams)
+  pickPass1Cap,
+  pickPass3NativeCap,
+  estimateImageTokens,
+  walkImagesForPass1,
+  walkImagesForPass3,
+  pickEvictionTargets,
+  // Orchestrator (used by the extension default export and direct test calls)
+  runImageGuard,
+  // Test utilities
+  _resetWarningStateForTests,
+};
 
 export default {
   name: "image-strip",
   description:
-    "Strip base64 images from old tool results AND optionally strip oversized images that would trigger Anthropic's many-image dimension limit",
-  enabled: false,
+    "v3.2.1 KEEP_LAST/MAX_DIM legacy paths PLUS v3.3.0 image-guard pipeline " +
+    "(conditional rejection cap + request-size guard + optional Lanczos resize)",
+  enabled: false,        // overridden by extensions.json
   order: 150,
 
   async onRequest(ctx) {
-    const keepLast = parseInt(ctx.meta.imageKeepLast ?? KEEP_LAST, 10);
-    const maxDim = parseInt(ctx.meta.imageMaxDim ?? MAX_DIM, 10);
-    if ((!keepLast || keepLast <= 0) && (!maxDim || maxDim <= 0)) return;
-    if (!ctx.body.messages) return;
+    const guardOn = isImageGuardEnabled();
+    const preserveOn = isPreserveDetailEnabled();
+    // ctx.meta overrides allow tests to drive the legacy paths without env vars.
+    // Pipeline gates (IMAGE_GUARD, PRESERVE_DETAIL) remain env-only — tests that
+    // need to flip them set process.env directly.
+    const keepLast = parseInt(ctx.meta?.imageKeepLast ?? getKeepLast(), 10);
+    const maxDim = parseInt(ctx.meta?.imageMaxDim ?? getMaxDim(), 10);
 
-    let messages = ctx.body.messages;
-    const logParts = [];
+    // Short-circuit: nothing to do.
+    if (!guardOn && keepLast <= 0 && maxDim <= 0) {
+      // Surface the PRESERVE_DETAIL-without-GUARD warning even when the
+      // pipeline doesn't run otherwise.
+      if (preserveOn && !_preserveDetailWarned) {
+        process.stderr.write(
+          "[image-guard] CACHE_FIX_IMAGE_PRESERVE_DETAIL=1 has no effect without CACHE_FIX_IMAGE_GUARD=1\n"
+        );
+        _preserveDetailWarned = true;
+      }
+      return;
+    }
 
-    // Pass 1: existing keep_last behavior. Sets ctx.meta.imageStripStats with
-    // the same shape as before this PR — back-compat preserved.
-    if (keepLast > 0) {
-      const r = stripOldToolResultImages(messages, keepLast);
-      if (r.stats) {
-        messages = r.messages;
-        ctx.meta.imageStripStats = r.stats;
-        logParts.push(`keep_last: ${r.stats.strippedCount} stripped (~${r.stats.estimatedTokens} tokens saved)`);
+    if (!ctx.body || !ctx.body.messages) return;
+
+    // ========== Legacy path (v3.2.1 back-compat) ==========
+    // When IMAGE_GUARD=1 is OFF but legacy env vars are set, run the v3.2.1
+    // pipeline exactly as before — preserves bug-for-bug compatibility for
+    // existing users.
+    if (!guardOn) {
+      let messages = ctx.body.messages;
+      const logParts = [];
+
+      if (keepLast > 0) {
+        const r = stripOldToolResultImages(messages, keepLast);
+        if (r.stats) {
+          messages = r.messages;
+          ctx.meta.imageStripStats = r.stats;
+          logParts.push(
+            `keep_last: ${r.stats.strippedCount} stripped (~${r.stats.estimatedTokens} tokens saved)`
+          );
+        }
+      }
+
+      if (maxDim > 0) {
+        const r = stripOversizedImages(messages, maxDim);
+        if (r.stats) {
+          messages = r.messages;
+          ctx.meta.imageStripOversizedStats = r.stats;
+          logParts.push(
+            `max_dim: ${r.stats.strippedCount} oversized stripped ` +
+            `(~${r.stats.estimatedTokens} tokens saved)`
+          );
+        }
       }
+
+      if (logParts.length > 0) {
+        ctx.body.messages = messages;
+        process.stderr.write(`[image-strip] ${logParts.join("; ")}\n`);
+      }
+      return;
     }
 
-    // Pass 2: new max_dim behavior. Stats land on a new field so consumers
-    // already reading imageStripStats don't see a shape change.
-    if (maxDim > 0) {
-      const r = stripOversizedImages(messages, maxDim);
+    // ========== v3.3.0 pipeline path ==========
+    // KEEP_LAST runs first as Pass 0 (back-compat behavior preserved).
+    if (keepLast > 0) {
+      const r = stripOldToolResultImages(ctx.body.messages, keepLast);
       if (r.stats) {
-        messages = r.messages;
-        ctx.meta.imageStripOversizedStats = r.stats;
-        logParts.push(`max_dim: ${r.stats.strippedCount} oversized stripped (~${r.stats.estimatedTokens} tokens saved)`);
+        ctx.body.messages = r.messages;
+        ctx.meta.imageStripStats = r.stats;
       }
     }
 
-    if (logParts.length > 0) {
-      ctx.body.messages = messages;
-      process.stderr.write(`[image-strip] ${logParts.join("; ")}\n`);
+    const stats = await runImageGuard(ctx);
+    ctx.meta.imageGuardStats = stats;
+
+    // Emit summary only if the pipeline actually did anything observable.
+    const didSomething =
+      stats.images_stripped_pass1 > 0 ||
+      stats.images_dropped_for_size > 0 ||
+      stats.images_dropped_for_count_cap > 0 ||
+      stats.resize_attempted > 0 ||
+      stats.resize_succeeded > 0 ||
+      stats.unsupported_format_count > 0 ||
+      stats.dimension_probe_fail_count > 0;
+    if (didSomething) {
+      const parts = [];
+      if (stats.resize_succeeded > 0) parts.push(`resized=${stats.resize_succeeded}`);
+      if (stats.resize_failed > 0) parts.push(`resize_failed=${stats.resize_failed}`);
+      if (stats.library_missing) parts.push("sharp=missing");
+      if (stats.images_stripped_pass1 > 0) parts.push(`stripped=${stats.images_stripped_pass1}`);
+      if (stats.images_dropped_for_size > 0) parts.push(`evicted=${stats.images_dropped_for_size}`);
+      if (stats.images_dropped_for_count_cap > 0) {
+        parts.push(`count_capped=${stats.images_dropped_for_count_cap}`);
+      }
+      if (stats.unsupported_format_count > 0) parts.push(`unsupported=${stats.unsupported_format_count}`);
+      const summary = parts.join(" ") || "ran";
+      const finalImages = stats.total_images
+        - stats.images_stripped_pass1
+        - stats.images_dropped_for_size
+        - stats.images_dropped_for_count_cap;
+      process.stderr.write(
+        `[image-guard] ${summary} req_bytes=${stats.request_bytes_before}->${stats.request_bytes_after} ` +
+        `(headroom=${stats.request_bytes_headroom}) images=${stats.total_images}->${finalImages}\n`
+      );
     }
   },
 };
+

package/proxy/extensions.json

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

package/proxy/image-resize.mjs

@@ -0,0 +1,133 @@
+// Lazy `sharp` wrapper for the image-guard pipeline's Pass 3 (native-cap resize).
+//
+// `sharp` is declared as an OPTIONAL peer dependency in package.json. The proxy
+// must run without it. This module:
+//
+//   1. Lazy-imports `sharp` only when first needed (no module-load cost when
+//      Pass 3 is disabled or sharp is absent).
+//   2. Caches the import result (success or library-missing failure) so we
+//      don't pay the import cost or re-throw repeatedly.
+//   3. Returns a stable `{ ok, reason }` shape the caller can branch on
+//      without try/catch around every call.
+//
+// The actual resize uses Lanczos resampling (sharp's default kernel for
+// downscales), preserves aspect ratio, and re-encodes using the SAME media
+// type as the input. No transcoding in v1 — JPEG stays JPEG, PNG stays PNG.
+
+let _sharpModule = null;          // resolved sharp module (or null if missing)
+let _sharpResolved = false;       // have we attempted the import?
+let _sharpMissing = false;        // sticky flag — if first import fails, never retry
+
+// Reset hook for tests. Not exported in the default surface; tests import by name.
+export function _resetSharpCacheForTests() {
+  _sharpModule = null;
+  _sharpResolved = false;
+  _sharpMissing = false;
+}
+
+// Override hook for tests: inject a fake sharp without going through real import.
+// The fake should be callable as `fake(buffer)` returning an object with
+// `.resize()` and `.toBuffer()`/`.toFormat()` methods like real sharp.
+export function _setSharpForTests(fakeSharp) {
+  _sharpModule = fakeSharp;
+  _sharpResolved = true;
+  _sharpMissing = !fakeSharp;
+}
+
+async function loadSharp() {
+  if (_sharpResolved) {
+    return { ok: !_sharpMissing, sharp: _sharpModule };
+  }
+  try {
+    const mod = await import("sharp");
+    _sharpModule = mod.default || mod;
+    _sharpResolved = true;
+    _sharpMissing = false;
+    return { ok: true, sharp: _sharpModule };
+  } catch (err) {
+    _sharpResolved = true;
+    _sharpMissing = true;
+    _sharpModule = null;
+    return { ok: false, sharp: null, err };
+  }
+}
+
+// Re-encode media type → sharp output format name. Keep symmetric with the
+// dimension probe (PNG + JPEG only in v1).
+function mediaTypeToSharpFormat(mediaType) {
+  switch ((mediaType || "").toLowerCase()) {
+    case "image/png":
+      return "png";
+    case "image/jpeg":
+    case "image/jpg":
+      return "jpeg";
+    default:
+      return null;
+  }
+}
+
+// Resize a base64-encoded image to `capPx` on the long edge using Lanczos.
+// Returns:
+//   { ok: true, base64, dims: { width, height }, bytes }     on success
+//   { ok: false, reason: "library_missing" | "unsupported_media_type" | "decode_failed" | "resize_failed" }
+//
+// Caller is expected to:
+//   - skip Pass 3 entirely on `library_missing` (sticky for the process)
+//   - increment per-image telemetry counters on the other failure modes and
+//     leave the original image untouched for Pass 1 to evaluate.
+export async function resizeImageToCap(base64Data, mediaType, capPx) {
+  if (!base64Data || typeof base64Data !== "string") {
+    return { ok: false, reason: "decode_failed" };
+  }
+  const format = mediaTypeToSharpFormat(mediaType);
+  if (!format) {
+    return { ok: false, reason: "unsupported_media_type" };
+  }
+
+  const loaded = await loadSharp();
+  if (!loaded.ok) {
+    return { ok: false, reason: "library_missing" };
+  }
+  const sharp = loaded.sharp;
+
+  let inputBuffer;
+  try {
+    inputBuffer = Buffer.from(base64Data, "base64");
+  } catch {
+    return { ok: false, reason: "decode_failed" };
+  }
+  if (!inputBuffer || inputBuffer.length === 0) {
+    return { ok: false, reason: "decode_failed" };
+  }
+
+  try {
+    const pipeline = sharp(inputBuffer).resize({
+      width: capPx,
+      height: capPx,
+      fit: "inside",          // preserve aspect ratio, neither edge exceeds capPx
+      withoutEnlargement: true, // never upscale
+      kernel: "lanczos3",
+    });
+
+    // Re-encode using the SAME format as the input. No transcoding in v1.
+    const encoded = format === "png"
+      ? await pipeline.png().toBuffer({ resolveWithObject: true })
+      : await pipeline.jpeg().toBuffer({ resolveWithObject: true });
+
+    const newBase64 = encoded.data.toString("base64");
+    return {
+      ok: true,
+      base64: newBase64,
+      dims: { width: encoded.info.width, height: encoded.info.height },
+      bytes: encoded.data.length,
+    };
+  } catch {
+    return { ok: false, reason: "resize_failed" };
+  }
+}
+
+// Tiny helper for tests: returns whether sharp was successfully imported once.
+// Doesn't trigger an import — caller must have invoked resizeImageToCap first.
+export function _sharpStatusForTests() {
+  return { resolved: _sharpResolved, missing: _sharpMissing };
+}