fix: normalize legacy exec_command/shell_command tool calls to declared exec

src/bridge.ts

@@ -19,6 +19,7 @@ import {
   awaitThoughtSignatureDurability,
 } from "./responses/thought-signature-replay";
 import { resolveStallTimeoutSec } from "./stall-timeout";
+import { normalizeDeclaredToolName } from "./types";
 import { usageDisplayTotalTokens } from "./usage/totals";
 import { appendSafeWebSearchSource, safeWebSearchSources } from "./web-search/sources";
 import {
@@ -1041,13 +1042,14 @@ export function bridgeToResponsesSSE(
                 rememberReasoningForCall(event.id, rawReasoningForNextToolCall, replayCacheScope);
               }
               if (currentToolCall) closeCurrentToolCall();
-              const mapped = toolNsMap?.get(event.name);
-              const realName = mapped?.name ?? event.name;
-              if (options?.declaredToolNames && !options.declaredToolNames.has(event.name)) {
+              const effectiveName = normalizeDeclaredToolName(event.name, options?.declaredToolNames);
+              const mapped = toolNsMap?.get(effectiveName);
+              const realName = mapped?.name ?? effectiveName;
+              if (options?.declaredToolNames && !options.declaredToolNames.has(effectiveName)) {
                 const failure = responseError(
                   502,
                   "upstream_error",
-                  `routed provider emitted undeclared client tool "${event.name}"; only request-declared tools may be called`,
+                  `routed provider emitted undeclared client tool "${effectiveName}"; only request-declared tools may be called`,
                 );
                 emit("response.failed", {
                   response: {
@@ -1783,30 +1785,32 @@ function buildResponseJSONWithBudget(
           ));
         }
         break;
-      case "tool_call_start":
+      case "tool_call_start": {
         if (currentText) flushText("commentary");
         if (currentSummaryReasoning) flushSummaryReasoning();
         if (currentRawReasoning) flushRawReasoning();
         if (rawReasoningForNextToolCall) {
           rememberReasoningForCall(e.id, rawReasoningForNextToolCall, replayCacheScope);
         }
         flushToolCall();
-        if (options?.declaredToolNames && !options.declaredToolNames.has(e.name)) {
+        const effectiveName = normalizeDeclaredToolName(e.name, options?.declaredToolNames);
+        if (options?.declaredToolNames && !options.declaredToolNames.has(effectiveName)) {
           errorEvent = {
             type: "error",
-            message: `routed provider emitted undeclared client tool "${e.name}"; only request-declared tools may be called`,
+            message: `routed provider emitted undeclared client tool "${effectiveName}"; only request-declared tools may be called`,
             status: 502,
             errorType: "upstream_error",
           };
           break;
         }
         currentToolCallId = e.id;
         budget?.openCall(e.id);
-        currentToolCallName = e.name;
+        currentToolCallName = effectiveName;
         currentToolCallArgs = "";
         currentToolCallArgsBytes = 0;
         currentToolCallProviderMetadata = e.providerMetadata;
         break;
+      }
       case "tool_call_delta":
         {
           ({ value: currentToolCallArgs, bytes: currentToolCallArgsBytes } = appendBatchString(

src/server/responses-undeclared-tool-guard.ts

@@ -1,4 +1,4 @@
-import { namespacedToolName } from "../types";
+import { namespacedToolName, normalizeDeclaredToolName } from "../types";
 import { sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
 
 /** Item types the client executes through a request-declared wire name. */
@@ -202,10 +202,14 @@ function undeclaredNameInItem(
   if (!CLIENT_EXECUTED_CALL_TYPES.has(item.type)) return undefined;
   const name = item.name;
   if (typeof name !== "string" || name.length === 0) return undefined;
-  if (declared.has(name)) return undefined;
-  if (typeof item.namespace === "string" && declared.has(namespacedToolName(item.namespace, name))) {
-    return undefined;
+  if (typeof item.namespace === "string") {
+    // Namespaced calls are matched by their full wire name only — never legacy-normalize
+    // them, or an undeclared namespaced `exec_command` could slip through as bare `exec`.
+    if (declared.has(namespacedToolName(item.namespace, name))) return undefined;
+    return name;
   }
+  const effectiveName = normalizeDeclaredToolName(name, declared);
+  if (declared.has(effectiveName)) return undefined;
   return name;
 }
 

src/types.ts

@@ -4,6 +4,7 @@
 export type { OcxTool, OcxToolChoice } from "./types/tools";
 export {
   namespacedToolName,
+  normalizeDeclaredToolName,
   toolChoiceAliases,
   createToolChoiceResolver,
   toolChoiceCandidates,

src/types/tools.ts

@@ -31,6 +31,33 @@ export function namespacedToolName(namespace: string | undefined, name: string):
   return namespace ? `${namespace}__${name}` : name;
 }
 
+/**
+ * Codex 0.149 unified-exec name normalization.
+ *
+ * Codex's code-mode shell tool is declared as `exec` (a freeform custom tool whose own
+ * description mentions the nested `await tools.exec_command(...)` helper). Routed models —
+ * DeepSeek in particular — sometimes echo that helper name as the tool-call name, emitting
+ * `exec_command` instead of the declared `exec`. Accept the legacy shell bridge names only
+ * when the request catalog actually declares `exec` and does not itself declare the legacy
+ * name (an MCP server may legitimately advertise `exec_command` under its own namespace).
+ */
+const LEGACY_SHELL_BRIDGE_TOOL_NAMES = ["exec_command", "shell_command"] as const;
+
+export function normalizeDeclaredToolName(
+  name: string,
+  declared: ReadonlySet<string> | undefined,
+): string {
+  if (!declared || !declared.has("exec")) return name;
+  if (declared.has(name)) return name;
+  // When the catalog explicitly declares any legacy shell bridge name, the environment
+  // genuinely exposes that tool — turn normalization off so a call is never mis-routed
+  // to `exec`.
+  if ((LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).some(legacy => declared.has(legacy))) {
+    return name;
+  }
+  return (LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).includes(name) ? "exec" : name;
+}
+
 export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
   const wireName = namespacedToolName(tool.namespace, tool.name);
   return tool.namespace ? [wireName, `${tool.namespace}.${tool.name}`] : [wireName];

tests/responses-undeclared-tool-guard.test.ts

@@ -1247,4 +1247,42 @@ describe("undeclaredToolCallNameInResponse", () => {
       new Set(["computer_call"]),
     )).toBeUndefined();
   });
+
+  test("accepts legacy shell bridge names when the catalog declares unified exec", () => {
+    // Codex 0.149 declares the code-mode shell tool as `exec`; routed models (DeepSeek)
+    // sometimes echo the nested helper name `exec_command` instead. The guard must accept
+    // it when the request catalog declares `exec` and does not itself declare the legacy
+    // name — but must still refuse it when the legacy name is a real declared tool.
+    const response = {
+      output: [
+        { type: "function_call", name: "exec_command" },
+        { type: "function_call", name: "shell_command" },
+      ],
+    };
+
+    expect(undeclaredToolCallNameInResponse(response, new Set(["exec"]))).toBeUndefined();
+    expect(undeclaredToolCallNameInResponse(response, new Set(["exec", "exec_command"]))).toBe(
+      "shell_command",
+    );
+    expect(undeclaredToolCallNameInResponse(response, new Set(["exec_command"]))).toBe(
+      "shell_command",
+    );
+    expect(undeclaredToolCallNameInResponse(response, new Set())).toBe("exec_command");
+  });
+
+  test("never legacy-normalizes a namespaced shell bridge call", () => {
+    // A namespaced call (e.g. an MCP server advertising its own exec_command) must be
+    // matched by its full wire name only — never normalized to bare `exec`.
+    const namespaced = {
+      output: [
+        { type: "function_call", name: "exec_command", namespace: "mcp__server" },
+        { type: "function_call", name: "exec_command" },
+      ],
+    };
+
+    expect(undeclaredToolCallNameInResponse(namespaced, new Set(["exec"]))).toBe(
+      "exec_command",
+    );
+    expect(undeclaredToolCallNameInResponse(namespaced, new Set(["exec", "mcp__server__exec_command"]))).toBeUndefined();
+  });
 });