Skip to content

Commit 224f23d

Browse files
L-Y-Jliyongjie.103
andauthored
fix: normalize legacy exec_command/shell_command tool calls to declared exec (#2493)
Codex 0.149 declares its code-mode shell tool as `exec` (a freeform custom tool whose 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`. The undeclared-tool guard then fails the whole turn with a 502. Normalize the legacy shell bridge names to `exec` at the three guard sites (streaming bridge x2, terminal snapshot guard) only when the request catalog declares `exec` and declares no legacy shell bridge name itself, so an MCP server advertising its own `exec_command` keeps working. Namespaced calls are always matched by their full wire name and never legacy-normalized. Co-authored-by: liyongjie.103 <[email protected]>
1 parent b694268 commit 224f23d

5 files changed

Lines changed: 86 additions & 12 deletions

File tree

‎src/bridge.ts‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
awaitThoughtSignatureDurability,
2020
} from "./responses/thought-signature-replay";
2121
import { resolveStallTimeoutSec } from "./stall-timeout";
22+
import { normalizeDeclaredToolName } from "./types";
2223
import { usageDisplayTotalTokens } from "./usage/totals";
2324
import { appendSafeWebSearchSource, safeWebSearchSources } from "./web-search/sources";
2425
import {
@@ -1041,13 +1042,14 @@ export function bridgeToResponsesSSE(
10411042
rememberReasoningForCall(event.id, rawReasoningForNextToolCall, replayCacheScope);
10421043
}
10431044
if (currentToolCall) closeCurrentToolCall();
1044-
const mapped = toolNsMap?.get(event.name);
1045-
const realName = mapped?.name ?? event.name;
1046-
if (options?.declaredToolNames && !options.declaredToolNames.has(event.name)) {
1045+
const effectiveName = normalizeDeclaredToolName(event.name, options?.declaredToolNames);
1046+
const mapped = toolNsMap?.get(effectiveName);
1047+
const realName = mapped?.name ?? effectiveName;
1048+
if (options?.declaredToolNames && !options.declaredToolNames.has(effectiveName)) {
10471049
const failure = responseError(
10481050
502,
10491051
"upstream_error",
1050-
`routed provider emitted undeclared client tool "${event.name}"; only request-declared tools may be called`,
1052+
`routed provider emitted undeclared client tool "${effectiveName}"; only request-declared tools may be called`,
10511053
);
10521054
emit("response.failed", {
10531055
response: {
@@ -1783,30 +1785,32 @@ function buildResponseJSONWithBudget(
17831785
));
17841786
}
17851787
break;
1786-
case "tool_call_start":
1788+
case "tool_call_start": {
17871789
if (currentText) flushText("commentary");
17881790
if (currentSummaryReasoning) flushSummaryReasoning();
17891791
if (currentRawReasoning) flushRawReasoning();
17901792
if (rawReasoningForNextToolCall) {
17911793
rememberReasoningForCall(e.id, rawReasoningForNextToolCall, replayCacheScope);
17921794
}
17931795
flushToolCall();
1794-
if (options?.declaredToolNames && !options.declaredToolNames.has(e.name)) {
1796+
const effectiveName = normalizeDeclaredToolName(e.name, options?.declaredToolNames);
1797+
if (options?.declaredToolNames && !options.declaredToolNames.has(effectiveName)) {
17951798
errorEvent = {
17961799
type: "error",
1797-
message: `routed provider emitted undeclared client tool "${e.name}"; only request-declared tools may be called`,
1800+
message: `routed provider emitted undeclared client tool "${effectiveName}"; only request-declared tools may be called`,
17981801
status: 502,
17991802
errorType: "upstream_error",
18001803
};
18011804
break;
18021805
}
18031806
currentToolCallId = e.id;
18041807
budget?.openCall(e.id);
1805-
currentToolCallName = e.name;
1808+
currentToolCallName = effectiveName;
18061809
currentToolCallArgs = "";
18071810
currentToolCallArgsBytes = 0;
18081811
currentToolCallProviderMetadata = e.providerMetadata;
18091812
break;
1813+
}
18101814
case "tool_call_delta":
18111815
{
18121816
({ value: currentToolCallArgs, bytes: currentToolCallArgsBytes } = appendBatchString(

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

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { namespacedToolName } from "../types";
1+
import { namespacedToolName, normalizeDeclaredToolName } from "../types";
22
import { sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
33

44
/** Item types the client executes through a request-declared wire name. */
@@ -277,10 +277,14 @@ function undeclaredNameInItem(
277277
if (!CLIENT_EXECUTED_CALL_TYPES.has(item.type)) return undefined;
278278
const name = item.name;
279279
if (typeof name !== "string" || name.length === 0) return undefined;
280-
if (declared.has(name)) return undefined;
281-
if (typeof item.namespace === "string" && declared.has(namespacedToolName(item.namespace, name))) {
282-
return undefined;
280+
if (typeof item.namespace === "string") {
281+
// Namespaced calls are matched by their full wire name only — never legacy-normalize
282+
// them, or an undeclared namespaced `exec_command` could slip through as bare `exec`.
283+
if (declared.has(namespacedToolName(item.namespace, name))) return undefined;
284+
return name;
283285
}
286+
const effectiveName = normalizeDeclaredToolName(name, declared);
287+
if (declared.has(effectiveName)) return undefined;
284288
return name;
285289
}
286290

‎src/types.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
export type { OcxTool, OcxToolChoice } from "./types/tools";
55
export {
66
namespacedToolName,
7+
normalizeDeclaredToolName,
78
toolChoiceAliases,
89
createToolChoiceResolver,
910
toolChoiceCandidates,

‎src/types/tools.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,33 @@ export function namespacedToolName(namespace: string | undefined, name: string):
3131
return namespace ? `${namespace}__${name}` : name;
3232
}
3333

34+
/**
35+
* Codex 0.149 unified-exec name normalization.
36+
*
37+
* Codex's code-mode shell tool is declared as `exec` (a freeform custom tool whose own
38+
* description mentions the nested `await tools.exec_command(...)` helper). Routed models —
39+
* DeepSeek in particular — sometimes echo that helper name as the tool-call name, emitting
40+
* `exec_command` instead of the declared `exec`. Accept the legacy shell bridge names only
41+
* when the request catalog actually declares `exec` and does not itself declare the legacy
42+
* name (an MCP server may legitimately advertise `exec_command` under its own namespace).
43+
*/
44+
const LEGACY_SHELL_BRIDGE_TOOL_NAMES = ["exec_command", "shell_command"] as const;
45+
46+
export function normalizeDeclaredToolName(
47+
name: string,
48+
declared: ReadonlySet<string> | undefined,
49+
): string {
50+
if (!declared || !declared.has("exec")) return name;
51+
if (declared.has(name)) return name;
52+
// When the catalog explicitly declares any legacy shell bridge name, the environment
53+
// genuinely exposes that tool — turn normalization off so a call is never mis-routed
54+
// to `exec`.
55+
if ((LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).some(legacy => declared.has(legacy))) {
56+
return name;
57+
}
58+
return (LEGACY_SHELL_BRIDGE_TOOL_NAMES as readonly string[]).includes(name) ? "exec" : name;
59+
}
60+
3461
export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
3562
const wireName = namespacedToolName(tool.namespace, tool.name);
3663
return tool.namespace ? [wireName, `${tool.namespace}.${tool.name}`] : [wireName];

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1249,6 +1249,44 @@ describe("undeclaredToolCallNameInResponse", () => {
12491249
new Set(["computer_call"]),
12501250
)).toBeUndefined();
12511251
});
1252+
1253+
test("accepts legacy shell bridge names when the catalog declares unified exec", () => {
1254+
// Codex 0.149 declares the code-mode shell tool as `exec`; routed models (DeepSeek)
1255+
// sometimes echo the nested helper name `exec_command` instead. The guard must accept
1256+
// it when the request catalog declares `exec` and does not itself declare the legacy
1257+
// name — but must still refuse it when the legacy name is a real declared tool.
1258+
const response = {
1259+
output: [
1260+
{ type: "function_call", name: "exec_command" },
1261+
{ type: "function_call", name: "shell_command" },
1262+
],
1263+
};
1264+
1265+
expect(undeclaredToolCallNameInResponse(response, new Set(["exec"]))).toBeUndefined();
1266+
expect(undeclaredToolCallNameInResponse(response, new Set(["exec", "exec_command"]))).toBe(
1267+
"shell_command",
1268+
);
1269+
expect(undeclaredToolCallNameInResponse(response, new Set(["exec_command"]))).toBe(
1270+
"shell_command",
1271+
);
1272+
expect(undeclaredToolCallNameInResponse(response, new Set())).toBe("exec_command");
1273+
});
1274+
1275+
test("never legacy-normalizes a namespaced shell bridge call", () => {
1276+
// A namespaced call (e.g. an MCP server advertising its own exec_command) must be
1277+
// matched by its full wire name only — never normalized to bare `exec`.
1278+
const namespaced = {
1279+
output: [
1280+
{ type: "function_call", name: "exec_command", namespace: "mcp__server" },
1281+
{ type: "function_call", name: "exec_command" },
1282+
],
1283+
};
1284+
1285+
expect(undeclaredToolCallNameInResponse(namespaced, new Set(["exec"]))).toBe(
1286+
"exec_command",
1287+
);
1288+
expect(undeclaredToolCallNameInResponse(namespaced, new Set(["exec", "mcp__server__exec_command"]))).toBeUndefined();
1289+
});
12521290
});
12531291

12541292
/**

0 commit comments

Comments
 (0)