Skip to content

Commit 0584267

Browse files
committed
fix(adapters): teach code-mode nested helpers in the shared catalog nudge
Routed providers were told the valid names were exactly the flat top-level catalog. In Codex code mode, deferred helpers such as tools.codex_app__list_threads stay callable inside exec even when they are omitted from the listed names and from exec description. Discover them from the isolate global ALL_TOOLS, not tools.ALL_TOOLS.
1 parent 3d67ac2 commit 0584267

4 files changed

Lines changed: 44 additions & 7 deletions

File tree

‎src/adapters/cursor/tool-definitions.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -615,7 +615,7 @@ export function buildCursorToolGuidanceSystemNote(
615615
// Code mode: shell/edit/MCP live inside freeform `exec` as nested helpers. Without this the
616616
// model probes for a top-level shell tool that is not there.
617617
codeMode
618-
? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description for the exact nested helpers this turn provides. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\`, \`shell_command\`, or \`apply_patch\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}.`
618+
? `\`${CODEX_UNIFIED_EXEC_TOOL}\` is Codex code mode: its body is JavaScript evaluated in a V8 isolate, not a shell command and not Node. Shell, file edits, and MCP are nested helpers called INSIDE that body as \`await tools.<name>(...)\`, for example \`await tools.exec_command({cmd: \"ls\"})\`. Read the tool description and the isolate global \`ALL_TOOLS\` (not \`tools.ALL_TOOLS\`) for helpers this turn provides; absence from the top-level catalog or from \`exec\`'s description is not absence. Those nested helpers are not themselves top-level tools, so do not call \`exec_command\`, \`shell_command\`, or \`apply_patch\` at the top level here${codeModeOtherTopLevelNames.length > 0 ? `; every other tool this turn lists, including ${quotedNames(codeModeOtherTopLevelNames)}, remains callable at the top level as usual` : ""}.`
619619
: undefined,
620620
codeMode
621621
? "In code mode the isolate returns nothing on its own: call `text(...)` (or `notify(...)`) on any value you need to see, or the call completes with empty output. There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers."

‎src/adapters/tool-catalog-nudge.ts‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,10 @@ import {
1616
// `python3` heredoc edits. The sibling list in `./cursor/tool-definitions.ts` never
1717
// included it either.
1818
const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
19+
const CODEX_CODE_MODE_EXEC_TOOL = "exec";
1920

2021
function quoteNames(names: readonly string[]): string {
21-
return names.map(name => `\`${name}\``).join(", ");
22+
return names.map(name => "`" + name + "`").join(", ");
2223
}
2324

2425
function uniqueNames(names: readonly string[]): string[] {
@@ -40,6 +41,13 @@ export function shouldInjectNonOpenAIToolCatalogNudge(provider: Pick<OcxProvider
4041
}
4142
}
4243

44+
function catalogListsCodeModeExec(
45+
advertised: ReadonlySet<string>,
46+
toWireName: (name: string) => string,
47+
): boolean {
48+
return advertised.has(CODEX_CODE_MODE_EXEC_TOOL) || advertised.has(toWireName(CODEX_CODE_MODE_EXEC_TOOL));
49+
}
50+
4351
export function buildNonOpenAIToolCatalogNudgeFromNames(
4452
wireNames: readonly string[] | undefined,
4553
toWireName: (name: string) => string = name => name,
@@ -50,21 +58,24 @@ export function buildNonOpenAIToolCatalogNudgeFromNames(
5058
const advertised = new Set(names);
5159
// Compare in the catalog's own coordinate system. `advertised` holds WIRE names, so a
5260
// provider that rewrites them (Claude OAuth `custom_`, Anthropic compat `cx_`) would never
53-
// match a bare neighbor name and would forbid tools the turn actually advertises — the
61+
// match a bare neighbor name and would forbid tools the turn actually advertises -- the
5462
// catalog would list `custom_apply_patch` while the same sentence banned `apply_patch`.
5563
const unavailableNeighborNames = NEIGHBOR_AGENT_TOOL_NAMES.filter(
5664
name => !advertised.has(name) && !advertised.has(toWireName(name)),
5765
);
66+
const codeMode = catalogListsCodeModeExec(advertised, toWireName);
5867

5968
return [
6069
"Tool contract: use the current tool catalog as ground truth.",
61-
`Valid tool names for this turn are exactly ${quoteNames(names)}.`,
70+
"Valid tool names for this turn are exactly " + quoteNames(names) + ".",
6271
"These listed names are the complete top-level tool-call surface for this turn.",
6372
"Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
6473
"Names mentioned only in instructions, tool descriptions, argument descriptions, or nested helper APIs are not additional top-level tools.",
65-
"If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
74+
codeMode
75+
? "If `exec` is listed, it is Codex code mode: its body is JavaScript evaluated in a V8 isolate. Nested helpers are called INSIDE that body as `await tools.<name>(...)`, for example `await tools.exec_command({cmd: \"ls\"})` or `await tools.codex_app__list_threads({})`. Absence from the top-level catalog or from `exec`'s description is not absence: deferred helpers stay callable on `tools.<name>`. Discover them from the isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`. Do not skip an available nested helper because it is omitted from the listed top-level names."
76+
: "If a listed tool exposes nested helpers such as a tools.* API, call the listed parent tool and use those helpers only inside that tool's input.",
6677
unavailableNeighborNames.length > 0
67-
? `Do not use neighboring-agent tool names ${quoteNames(unavailableNeighborNames)} unless this turn's catalog lists those exact names.`
78+
? "Do not use neighboring-agent tool names " + quoteNames(unavailableNeighborNames) + " unless this turn's catalog lists those exact names."
6879
: undefined,
6980
"If you need shell, file search, file read, edit, or discovery behavior, choose the listed tool that provides that capability.",
7081
"Count a tool call only after its tool result returns; batch independent read-only calls when the runtime supports it.",

‎tests/cursor-tool-definitions.test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -447,6 +447,9 @@ describe("Cursor code mode tool guidance", () => {
447447
expect(note).toContain("await tools.exec_command({cmd: " + "\"" + "ls" + "\"" + "})");
448448
expect(note).toContain("text(...)");
449449
expect(note).toContain("There is no `require`");
450+
expect(note).toContain("isolate global `ALL_TOOLS`");
451+
expect(note).toContain("not `tools.ALL_TOOLS`");
452+
expect(note).toContain("absence from the top-level catalog");
450453

451454
// The flat-catalog shell-bridge guidance must NOT appear: naming a top-level
452455
// `exec_command` in code mode sends the model after a tool that does not exist.

‎tests/tool-catalog-nudge.test.ts‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,33 @@ describe("non-OpenAI tool catalog nudge", () => {
5555
expect(note).toContain("Valid tool names for this turn are exactly `exec`, `wait`, `request_user_input`");
5656
expect(note).toContain("complete top-level tool-call surface");
5757
expect(note).toContain("nested helper APIs are not additional top-level tools");
58-
expect(note).toContain("call the listed parent tool");
58+
expect(note).toContain("If `exec` is listed, it is Codex code mode");
59+
expect(note).toContain("await tools.<name>(...)");
60+
expect(note).toContain("await tools.codex_app__list_threads({})");
61+
expect(note).toContain("isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`");
62+
expect(note).toContain("Do not skip an available nested helper");
63+
expect(note).not.toContain("call the listed parent tool and use those helpers only inside that tool's input");
5964
expect(note).not.toContain("apply_patch");
6065
});
6166

67+
test("keeps the generic nested-helper parent-tool rule when exec is not listed", () => {
68+
const note = buildNonOpenAIToolCatalogNudgeFromNames(["exec_command", "mcp__fs__read_file"]);
69+
70+
expect(note).toContain("call the listed parent tool and use those helpers only inside that tool's input");
71+
expect(note).not.toContain("If `exec` is listed, it is Codex code mode");
72+
expect(note).not.toContain("tools.ALL_TOOLS");
73+
});
74+
75+
test("detects a wire-renamed exec as code mode", () => {
76+
const note = buildNonOpenAIToolCatalogNudgeFromNames(
77+
["cx_exec", "cx_wait"],
78+
name => `cx_${name}`,
79+
);
80+
81+
expect(note).toContain("If `exec` is listed, it is Codex code mode");
82+
expect(note).toContain("isolate global `ALL_TOOLS`, not `tools.ALL_TOOLS`");
83+
});
84+
6285
// `advertised` holds WIRE names. A provider that rewrites them (Claude OAuth `custom_`,
6386
// Anthropic compat `cx_`) must not have every neighbor name declared unavailable while the
6487
// catalog plainly lists the prefixed form.

0 commit comments

Comments
 (0)