Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
fix(claude): sanitize tool schemas + cloak third-party tool names on native Claude OAuth
NomenAK7e7faad07940
diff --git a/open-sse/executors/base.ts b/open-sse/executors/base.tsindex 084db6a919..f5a7e2829c 100644--- a/open-sse/executors/base.ts+++ b/open-sse/executors/base.ts@@ -21,8 +21,9 @@ import {modelSupportsContext1mBeta,} from "../services/claudeCodeCompatible.ts";import { getClaudeCodeCompatibleRequestDefaults } from "@/lib/providers/requestDefaults";-import { remapToolNamesInRequest } from "../services/claudeCodeToolRemapper.ts";+import { cloakThirdPartyToolNames, remapToolNamesInRequest } from "../services/claudeCodeToolRemapper.ts";import { obfuscateInBody } from "../services/claudeCodeObfuscation.ts";+import { sanitizeClaudeToolSchemas } from "../translator/helpers/schemaCoercion.ts";import { sanitizeResponsesInputItems } from "../services/responsesInputSanitizer.ts";import { applySystemTransformPipeline, PROVIDER_CLAUDE } from "../services/systemTransforms.ts";import {@@ -775,6 +776,15 @@ export class BaseExecutor {stripProxyToolPrefix(tb);remapToolNamesInRequest(tb);+ // Cloak third-party tool names + sanitize invalid tool schemas so+ // Anthropic does not refuse native Claude OAuth traffic with a+ // misleading "out of extra usage" placeholder. See Spec E.+ if (process.env.CLAUDE_DISABLE_TOOL_NAME_CLOAK !== "true") {+ cloakThirdPartyToolNames(tb);+ }+ if (Array.isArray(tb.tools)) {+ tb.tools = sanitizeClaudeToolSchemas(tb.tools);+ }obfuscateInBody(tb);// NOTE (issue #2260): This is the native `claude` provider OAuth path.diff --git a/open-sse/services/claudeCodeToolRemapper.ts b/open-sse/services/claudeCodeToolRemapper.tsindex 9b61b826f7..9b6cf7d9cf 100644--- a/open-sse/services/claudeCodeToolRemapper.ts+++ b/open-sse/services/claudeCodeToolRemapper.ts@@ -144,3 +144,121 @@ export function remapToolNamesInResponse(}export { TOOL_RENAME_MAP, REVERSE_MAP };++/**+ * Anthropic fingerprints third-party agent harnesses by their tool NAMES on the+ * first-party Messages API (native Claude OAuth). Two failure modes, both+ * surfaced as a misleading `400 out of extra usage` placeholder (the SSE stream+ * is refused, not a real billing event):+ * 1. Specific blacklisted names (e.g. `mixture_of_agents`) are refused even in+ * isolation.+ * 2. A large enough SET of recognizable snake_case agent tool names is+ * refused collectively, even though each name passes on its own.+ *+ * `remapToolNamesInRequest` only normalizes the fixed set of Claude Code tool+ * names. This generalizes that cloak: any tool name that does not already look+ * like a genuine Claude Code tool (PascalCase, no separators) is deterministically+ * aliased — to its Claude Code canonical equivalent when one exists, otherwise to+ * a PascalCase form of the original. The per-request alias is tracked in the+ * non-enumerable `_toolNameMap`, so `remapToolNamesInResponse` restores the+ * caller's original names transparently. Disable with+ * `CLAUDE_DISABLE_TOOL_NAME_CLOAK=true`.+ */+const CLAUDE_BUILTIN_TOOL_NAMES = new Set<string>(Object.values(TOOL_RENAME_MAP));++const HARNESS_CANONICAL_MAP: Record<string, string> = {+ read_file: "Read",+ write_file: "Write",+ search_files: "Grep",+ grep_search: "Grep",+ list_directory: "Glob",+ run_command: "Bash",+ terminal: "Bash",+ todo: "TodoWrite",+ todo_write: "TodoWrite",+ todo_read: "TodoRead",+ patch: "Edit",+ multi_edit: "MultiEdit",+};++function toPascalCaseToolName(name: string): string {+ const parts = name.split(/[_\s-]+/).filter(Boolean);+ const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");+ return pascal || name;+}++/**+ * A name is left untouched when it already reads as a genuine Claude Code tool:+ * a PascalCase single token with no separators (Bash, Read, TodoWrite).+ */+export function needsThirdPartyCloak(name: string): boolean {+ if (!name) return false;+ if (CLAUDE_BUILTIN_TOOL_NAMES.has(name)) return false;+ return /[a-z]/.test(name.charAt(0)) || name.includes("_") || name.includes("-");+}++export function cloakThirdPartyToolNames(body: Record<string, unknown>): Map<string, string> {+ const tools = body.tools as Array<Record<string, unknown>> | undefined;++ const used = new Set<string>();+ if (Array.isArray(tools)) {+ for (const tool of tools) {+ if (typeof tool.name === "string") used.add(tool.name);+ }+ }+ const existingMap =+ body._toolNameMap instanceof Map ? (body._toolNameMap as Map<string, string>) : null;+ if (existingMap) {+ for (const alias of existingMap.keys()) used.add(alias);+ }++ // Created lazily so genuine Claude Code traffic (nothing to cloak) does not+ // get an empty _toolNameMap attached to the request body.+ let nameMap: Map<string, string> | null = existingMap;+ const assigned = new Map<string, string>(); // original -> alias++ const aliasFor = (original: string): string => {+ const existing = assigned.get(original);+ if (existing) return existing;+ const base = HARNESS_CANONICAL_MAP[original] ?? toPascalCaseToolName(original);+ let alias = base;+ let suffix = 2;+ while (alias !== original && used.has(alias)) {+ alias = `${base}${suffix++}`;+ }+ used.delete(original);+ used.add(alias);+ assigned.set(original, alias);+ if (!nameMap) nameMap = getRequestToolNameMap(body);+ nameMap.set(alias, original);+ return alias;+ };++ if (Array.isArray(tools)) {+ for (const tool of tools) {+ if (typeof tool.name === "string" && needsThirdPartyCloak(tool.name)) {+ tool.name = aliasFor(tool.name);+ }+ }+ }++ const messages = body.messages as Array<Record<string, unknown>> | undefined;+ if (Array.isArray(messages)) {+ for (const message of messages) {+ const content = message.content as Array<Record<string, unknown>> | undefined;+ if (!Array.isArray(content)) continue;+ for (const block of content) {+ if (block?.type === "tool_use" && typeof block.name === "string" && needsThirdPartyCloak(block.name)) {+ block.name = aliasFor(block.name);+ }+ }+ }+ }++ const toolChoice = body.tool_choice as Record<string, unknown> | undefined;+ if (toolChoice?.type === "tool" && typeof toolChoice.name === "string" && needsThirdPartyCloak(toolChoice.name)) {+ toolChoice.name = aliasFor(toolChoice.name);+ }++ return nameMap ?? new Map<string, string>();+}diff --git a/open-sse/translator/helpers/schemaCoercion.ts b/open-sse/translator/helpers/schemaCoercion.tsindex eb47cb4483..e5d94100ae 100644--- a/open-sse/translator/helpers/schemaCoercion.ts+++ b/open-sse/translator/helpers/schemaCoercion.ts@@ -232,3 +232,122 @@ export function injectEmptyReasoningContentForToolCalls(return { ...message, reasoning_content: "" };});}++/**+ * Anthropic's first-party Messages API strictly validates tool `input_schema`+ * against JSON Schema draft 2020-12. IDE/SDK agent harnesses that deep-truncate+ * their schemas emit invalid constructs — most commonly an array keyword+ * (`enum`, `required`, …) replaced by a placeholder string such as+ * `"[MaxDepth]"`, or an index-keyed object (`{"0":"a","1":"b"}`) where an array+ * is expected. Anthropic rejects these with+ * `tools.N.custom.input_schema: JSON schema is invalid` (surfaced as a+ * misleading `400 out of extra usage` placeholder when streaming). Non-Anthropic+ * targets (OpenAI/Codex) tolerate them, which is why the same request succeeds+ * on a fallback provider. This sanitizer coerces or drops the invalid+ * constructs so legitimate native-Claude-OAuth traffic is not spuriously+ * rejected. See Spec E (Claude Code OAuth wire compatibility).+ */+const SCHEMA_PLACEHOLDER_PATTERN = /^\[(?:MaxDepth|Truncated|Circular|Object|Array)\]$/;+const ARRAY_SCHEMA_KEYS = ["enum", "required", "anyOf", "oneOf", "allOf", "prefixItems"];+const SCHEMA_ARRAY_OF_SCHEMAS = new Set(["anyOf", "oneOf", "allOf", "prefixItems"]);+const SCHEMA_SLOT_KEYS = [+ "items",+ "additionalProperties",+ "propertyNames",+ "contains",+ "not",+ "if",+ "then",+ "else",+ "unevaluatedProperties",+ "additionalItems",+];++function coerceIndexedObjectToArray(value: unknown): unknown[] | null {+ if (Array.isArray(value)) return value;+ if (isPlainObject(value)) {+ const keys = Object.keys(value);+ if (keys.length > 0 && keys.every((key, index) => String(index) === key)) {+ return keys.map((key) => value[key]);+ }+ }+ return null;+}++function isSchemaPlaceholder(value: unknown): boolean {+ return typeof value === "string" && SCHEMA_PLACEHOLDER_PATTERN.test(value.trim());+}++export function stripInvalidSchemaConstructs(schema: unknown): unknown {+ if (Array.isArray(schema)) {+ return schema.map((entry) => stripInvalidSchemaConstructs(entry));+ }+ if (!isPlainObject(schema)) {+ return isSchemaPlaceholder(schema) ? {} : schema;+ }++ const result: JsonRecord = {};+ for (const [key, value] of Object.entries(schema)) {+ if (ARRAY_SCHEMA_KEYS.includes(key)) {+ const array = coerceIndexedObjectToArray(value);+ if (array === null) continue; // drop invalid non-array keyword (e.g. enum: "[MaxDepth]")+ result[key] = SCHEMA_ARRAY_OF_SCHEMAS.has(key)+ ? array.map((entry) => stripInvalidSchemaConstructs(entry))+ : array;+ continue;+ }+ if (SCHEMA_SLOT_KEYS.includes(key)) {+ result[key] =+ isPlainObject(value) || Array.isArray(value) ? stripInvalidSchemaConstructs(value) : {};+ continue;+ }+ if (key === "const") {+ if (isSchemaPlaceholder(value)) continue;+ result[key] = value;+ continue;+ }+ if (key === "properties" && isPlainObject(value)) {+ const properties: JsonRecord = {};+ for (const [propName, propSchema] of Object.entries(value)) {+ properties[propName] = isPlainObject(propSchema)+ ? stripInvalidSchemaConstructs(propSchema)+ : {};+ }+ result[key] = properties;+ continue;+ }+ if (+ (key === "$defs" ||+ key === "definitions" ||+ key === "patternProperties" ||+ key === "dependentSchemas") &&+ isPlainObject(value)+ ) {+ const defs: JsonRecord = {};+ for (const [defName, defSchema] of Object.entries(value)) {+ defs[defName] = stripInvalidSchemaConstructs(defSchema);+ }+ result[key] = defs;+ continue;+ }+ if (isSchemaPlaceholder(value)) {+ result[key] = {};+ continue;+ }+ result[key] =+ isPlainObject(value) || Array.isArray(value) ? stripInvalidSchemaConstructs(value) : value;+ }+ return result;+}++export function sanitizeClaudeToolSchema(schema: unknown): unknown {+ return stripInvalidSchemaConstructs(coerceSchemaNumericFields(schema));+}++export function sanitizeClaudeToolSchemas(tools: unknown): unknown {+ if (!Array.isArray(tools)) return tools;+ return tools.map((tool) => {+ if (!isPlainObject(tool) || tool.input_schema === undefined) return tool;+ return { ...tool, input_schema: sanitizeClaudeToolSchema(tool.input_schema) };+ });+}diff --git a/tests/unit/claude-oauth-tool-cloak.test.ts b/tests/unit/claude-oauth-tool-cloak.test.tsnew file mode 100644index 0000000000..12740d0a0f--- /dev/null+++ b/tests/unit/claude-oauth-tool-cloak.test.ts@@ -0,0 +1,109 @@+/**+ * Native Claude OAuth tool cloak + schema sanitizer.+ *+ * Anthropic's first-party Messages API rejects native-Claude-OAuth requests+ * that carry (a) invalid tool input_schemas (truncation placeholders / non-array+ * keywords) or (b) tool names it fingerprints as a third-party agent harness —+ * both surfaced as a misleading `400 out of extra usage` placeholder. These+ * tests cover the request-side sanitizer + name cloak; the response side is+ * reversed via the existing per-request _toolNameMap.+ */+import { describe, it } from "node:test";+import assert from "node:assert/strict";+import {+ cloakThirdPartyToolNames,+ needsThirdPartyCloak,+} from "../../open-sse/services/claudeCodeToolRemapper.ts";+import {+ sanitizeClaudeToolSchema,+ sanitizeClaudeToolSchemas,+} from "../../open-sse/translator/helpers/schemaCoercion.ts";++type AnyRecord = Record<string, unknown>;+const schemaOf = (tools: unknown, i = 0): AnyRecord =>+ ((tools as AnyRecord[])[i].input_schema as AnyRecord);++describe("sanitizeClaudeToolSchemas", () => {+ it("drops a non-array enum placeholder", () => {+ const tools = [+ { name: "x", input_schema: { type: "object", properties: { m: { type: "string", enum: "[MaxDepth]" } } } },+ ];+ const props = (schemaOf(sanitizeClaudeToolSchemas(tools)).properties as AnyRecord).m as AnyRecord;+ assert.equal("enum" in props, false);+ });++ it("coerces an index-keyed object enum into an array", () => {+ const s = sanitizeClaudeToolSchema({+ type: "object",+ properties: { a: { type: "string", enum: { "0": "x", "1": "y" } } },+ }) as AnyRecord;+ assert.deepEqual(((s.properties as AnyRecord).a as AnyRecord).enum, ["x", "y"]);+ });++ it("replaces a placeholder property value with a permissive schema", () => {+ const s = sanitizeClaudeToolSchema({ type: "object", properties: { a: "[MaxDepth]" } }) as AnyRecord;+ assert.deepEqual((s.properties as AnyRecord).a, {});+ });++ it("leaves a valid schema intact", () => {+ const input = { type: "object", properties: { a: { type: "string" } }, required: ["a"] };+ assert.deepEqual(sanitizeClaudeToolSchema(input), input);+ });+});++describe("cloakThirdPartyToolNames", () => {+ it("aliases a blacklisted name and tracks the reverse map", () => {+ const body: AnyRecord = { tools: [{ name: "mixture_of_agents" }] };+ cloakThirdPartyToolNames(body);+ assert.equal((body.tools as AnyRecord[])[0].name, "MixtureOfAgents");+ assert.equal((body._toolNameMap as Map<string, string>).get("MixtureOfAgents"), "mixture_of_agents");+ });++ it("maps known harness names to Claude Code canonical names", () => {+ const body: AnyRecord = { tools: [{ name: "read_file" }, { name: "write_file" }, { name: "terminal" }] };+ cloakThirdPartyToolNames(body);+ assert.deepEqual((body.tools as AnyRecord[]).map((t) => t.name), ["Read", "Write", "Bash"]);+ });++ it("PascalCases unmapped snake_case names", () => {+ const body: AnyRecord = { tools: [{ name: "honcho_profile" }, { name: "lcm_expand_query" }] };+ cloakThirdPartyToolNames(body);+ assert.deepEqual((body.tools as AnyRecord[]).map((t) => t.name), ["HonchoProfile", "LcmExpandQuery"]);+ });++ it("leaves genuine Claude Code tool names untouched", () => {+ const body: AnyRecord = { tools: [{ name: "Bash" }, { name: "Read" }, { name: "TodoWrite" }] };+ cloakThirdPartyToolNames(body);+ assert.deepEqual((body.tools as AnyRecord[]).map((t) => t.name), ["Bash", "Read", "TodoWrite"]);+ assert.equal((body._toolNameMap as Map<string, string> | undefined)?.size ?? 0, 0);+ });++ it("dedupes canonical-name collisions", () => {+ const body: AnyRecord = { tools: [{ name: "search_files" }, { name: "grep_search" }] };+ cloakThirdPartyToolNames(body);+ assert.deepEqual((body.tools as AnyRecord[]).map((t) => t.name), ["Grep", "Grep2"]);+ });++ it("remaps tool_use blocks in message history consistently", () => {+ const body: AnyRecord = {+ tools: [{ name: "mixture_of_agents" }],+ messages: [{ role: "assistant", content: [{ type: "tool_use", name: "mixture_of_agents" }] }],+ };+ cloakThirdPartyToolNames(body);+ const block = ((body.messages as AnyRecord[])[0].content as AnyRecord[])[0];+ assert.equal(block.name, "MixtureOfAgents");+ });++ it("does not leak _toolNameMap into the serialized request body", () => {+ const body: AnyRecord = { tools: [{ name: "mixture_of_agents" }] };+ cloakThirdPartyToolNames(body);+ assert.equal(JSON.stringify(body).includes("_toolNameMap"), false);+ });++ it("needsThirdPartyCloak only flags non-Claude-Code names", () => {+ assert.equal(needsThirdPartyCloak("Bash"), false);+ assert.equal(needsThirdPartyCloak("TodoWrite"), false);+ assert.equal(needsThirdPartyCloak("read_file"), true);+ assert.equal(needsThirdPartyCloak("mixture_of_agents"), true);+ });+});