fix(claude): never anchor cache breakpoint on defer_loading tools (#3567)

open-sse/translator/formats/claude.js

@@ -12,6 +12,18 @@ import { DEFAULT_MAX_TOKENS } from "../../config/runtimeConfig.js";
 const CACHE_CONTROL_5M = { type: "ephemeral" };
 const CACHE_CONTROL_1H = { type: "ephemeral", ttl: "1h" };
 
+// Anthropic rejects a tool carrying BOTH defer_loading:true and cache_control
+// ("Tools defer_loading cannot use prompt caching", #3567). MCP clients put
+// deferred tools at the tail, which is exactly where the cache anchor lands.
+// Anchor on the last tool that CAN be cached instead of dropping caching.
+export function lastCacheableToolIndex(tools) {
+  if (!Array.isArray(tools)) return -1;
+  for (let i = tools.length - 1; i >= 0; i--) {
+    if (tools[i]?.defer_loading !== true) return i;
+  }
+  return -1;
+}
+
 // Check if message has valid non-empty content
 export function hasValidContent(msg) {
   if (typeof msg.content === "string" && msg.content.trim()) return true;
@@ -270,7 +282,7 @@ export function anchorClaudeCache(body) {
   }
 
   if (Array.isArray(body.tools)) {
-    const last = body.tools.length - 1;
+    const last = lastCacheableToolIndex(body.tools);
     body.tools.forEach((tool, i) => {
       if (i === last) tool.cache_control = { ...CACHE_CONTROL_1H };
       else delete tool.cache_control;
@@ -464,9 +476,10 @@ export function prepareClaudeRequest(body, provider = null, apiKey = null, conne
         });
     }
 
+    const lastCacheable = lastCacheableToolIndex(body.tools);
     body.tools = body.tools.map((tool, i) => {
       const { cache_control, ...rest } = tool;
-      if (i === body.tools.length - 1) {
+      if (i === lastCacheable) {
         return { ...rest, cache_control: { type: "ephemeral", ttl: "1h" } };
       }
       return rest;

tests/unit/defer-loading-cache-control.test.js

@@ -0,0 +1,82 @@
+/**
+ * Regression: Anthropic rejects a tool that carries BOTH `defer_loading: true`
+ * and `cache_control`:
+ *
+ *   [400] Tool 'mcp__x__y' cannot both defer_loading=true cache_control set.
+ *         Tools defer_loading cannot use prompt caching.
+ *
+ * 9router anchors the 1h cache breakpoint on the LAST tool of the array with
+ * no guard. Clients that speak MCP (Claude Code) put deferred tools at the
+ * tail, so the anchor lands exactly on a tool that cannot be cached and the
+ * request 400s before combo fallback can try the next hop.
+ *
+ * The fix anchors on the last tool that is NOT deferred, so prompt caching is
+ * kept for the tools that can use it instead of being dropped wholesale.
+ *
+ * See: #3567.
+ */
+
+import { describe, it, expect } from "vitest";
+import { anchorClaudeCache } from "../../open-sse/translator/formats/claude.js";
+import { prepareClaudeRequest } from "../../open-sse/translator/formats/claude.js";
+
+const tool = (name, extra = {}) => ({
+  name,
+  description: "t",
+  input_schema: { type: "object", properties: {} },
+  ...extra,
+});
+
+describe("defer_loading tools never carry cache_control (#3567)", () => {
+  it("anchorClaudeCache: anchor moves to the last non-deferred tool", () => {
+    const body = anchorClaudeCache({
+      messages: [{ role: "user", content: "hi" }],
+      tools: [tool("a"), tool("b"), tool("mcp__x__y", { defer_loading: true })],
+    });
+
+    expect(body.tools[2].cache_control).toBeUndefined();
+    expect(body.tools[1].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
+    expect(body.tools[0].cache_control).toBeUndefined();
+  });
+
+  it("anchorClaudeCache: no tool is cached when every tool is deferred", () => {
+    const body = anchorClaudeCache({
+      messages: [{ role: "user", content: "hi" }],
+      tools: [tool("mcp__a", { defer_loading: true }), tool("mcp__b", { defer_loading: true })],
+    });
+
+    expect(body.tools.every(t => t.cache_control === undefined)).toBe(true);
+  });
+
+  it("anchorClaudeCache: strips a cache_control the client put on a deferred tool", () => {
+    const body = anchorClaudeCache({
+      messages: [{ role: "user", content: "hi" }],
+      tools: [tool("mcp__a", { defer_loading: true, cache_control: { type: "ephemeral" } })],
+    });
+
+    expect(body.tools[0].cache_control).toBeUndefined();
+  });
+
+  it("anchorClaudeCache: unchanged behaviour when no tool is deferred", () => {
+    const body = anchorClaudeCache({
+      messages: [{ role: "user", content: "hi" }],
+      tools: [tool("a"), tool("b")],
+    });
+
+    expect(body.tools[1].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
+    expect(body.tools[0].cache_control).toBeUndefined();
+  });
+
+  it("prepareClaudeRequest: deferred tail tool does not get the anchor", () => {
+    const out = prepareClaudeRequest({
+      model: "claude-sonnet-4.5",
+      messages: [{ role: "user", content: "hi" }],
+      tools: [tool("a"), tool("mcp__x__y", { defer_loading: true })],
+    }, "claude");
+
+    expect(out.tools).toHaveLength(2);
+    expect(out.tools[1].cache_control).toBeUndefined();
+    expect(out.tools[1].defer_loading).toBe(true);
+    expect(out.tools[0].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
+  });
+});