Skip to content

Commit cb48c2e

Browse files
committed
fix(cursor): teach the code-mode nested-helper contract in tool guidance
Absorbs #1801 onto the #1817 contract. Codex code mode advertises one freeform `exec` whose body is JavaScript in a V8 isolate; shell, file edits and MCP are nested `tools.<name>(...)` helpers described inside that tool, so the flat shell-bridge guidance sent the model after a top-level tool that does not exist. Fixes the mixed-catalog defect found while absorbing: code mode describes how `exec` works, it does not make the rest of the catalog nested. When other top-level tools are visible, the note now names them as still callable instead of declaring them "not separate top-level tools". Supersedes #1801.
1 parent 68f5308 commit cb48c2e

2 files changed

Lines changed: 119 additions & 0 deletions

File tree

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

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,38 @@ export function isCursorWaitTool(tool: Pick<OcxTool, "namespace" | "name">): boo
191191
return isCursorResponsesProvider(tool.namespace) && tool.name === CODEX_WAIT_TOOL;
192192
}
193193

194+
/**
195+
* True for Codex's unified-exec "code mode" tool: a freeform `exec` whose body is JavaScript
196+
* evaluated in a V8 isolate, not a shell command string.
197+
*/
198+
export function isCursorCodeModeExecTool(
199+
tool: Pick<OcxTool, "namespace" | "name" | "freeform">,
200+
): boolean {
201+
return isCursorResponsesProvider(tool.namespace)
202+
&& tool.name === CODEX_UNIFIED_EXEC_TOOL
203+
&& tool.freeform === true;
204+
}
205+
206+
/**
207+
* Codex code mode advertises ONE freeform `exec` tool and no bare shell bridge. Shell, file
208+
* edits, and MCP calls are reachable only as nested `tools.<name>(...)` helpers described inside
209+
* that tool's own description, so a flat catalog scan cannot see them.
210+
*
211+
* This matters because the shell-bridge guidance below is written for a flat catalog. Emitting
212+
* "call \`exec_command\`" into a code-mode turn names a top-level tool that does not exist: the
213+
* model calls it, gets nothing back, and burns turns rediscovering the real contract from error
214+
* messages (empty output until \`text()\` is called, \`require is not defined\` because the isolate
215+
* is not Node, \`apply_patch\` rejected because it too is only a nested helper here).
216+
*/
217+
export function cursorRequestUsesCodeMode(
218+
tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
219+
toolChoice?: OcxRequestOptions["toolChoice"],
220+
): boolean {
221+
const catalog = tools ?? [];
222+
const visible = catalog.filter(tool => cursorToolAllowedByChoice(tool, toolChoice, catalog));
223+
return visible.some(isCursorCodeModeExecTool) && !visible.some(isBareCodexShellBridgeTool);
224+
}
225+
194226
/** @deprecated Prefer isBareCodexShellBridgeTool; kept for older call sites/tests. */
195227
function isBareCodexExecCommandTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
196228
return isBareCodexShellBridgeTool(tool);
@@ -554,6 +586,14 @@ export function buildCursorToolGuidanceSystemNote(
554586
const listedNames = quotedNames(wireNames);
555587
const shellBridgeNames = wireNames.filter(isCodexShellBridgeToolName);
556588
const hasBareExec = shellBridgeNames.length > 0;
589+
const codeMode = cursorRequestUsesCodeMode(tools, toolChoice);
590+
// Code mode describes how the freeform exec tool works; it does not suppress the rest of the
591+
// catalog. A turn can advertise freeform `exec` AND ordinary top-level tools at once, and
592+
// telling the model those are "not separate top-level tools" would make it refuse tools that
593+
// are right there in its catalog. Name the ones that stay callable instead.
594+
const codeModeOtherTopLevelNames = codeMode
595+
? wireNames.filter(name => name !== CODEX_UNIFIED_EXEC_TOOL && !isCodexShellBridgeToolName(name))
596+
: [];
557597
const shellBridgeLabel = quotedNames(shellBridgeNames.length > 0 ? shellBridgeNames : [...CODEX_SHELL_BRIDGE_TOOL_NAMES]);
558598
const hasApplyPatch = cursorRequestAdvertisesApplyPatch(tools, toolChoice);
559599
const structuredEditNames = tools
@@ -572,6 +612,14 @@ export function buildCursorToolGuidanceSystemNote(
572612
unavailableNeighborNames.length > 0
573613
? `This turn does not expose neighboring-agent tool names ${quotedNames(unavailableNeighborNames)}; do not call or suggest them unless the catalog lists them.`
574614
: undefined,
615+
// Code mode: shell/edit/MCP live inside freeform `exec` as nested helpers. Without this the
616+
// model probes for a top-level shell tool that is not there.
617+
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` : ""}.`
619+
: undefined,
620+
codeMode
621+
? "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."
622+
: undefined,
575623
hasBareExec
576624
? `${shellBridgeLabel} is the Codex Responses shell bridge for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool. \`shell_command\` and \`exec_command\` are aliases of the same bridge.`
577625
: undefined,

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ import {
99
buildCursorToolGuidanceSystemNote,
1010
CURSOR_EXEC_COMMAND_INPUT_SCHEMA,
1111
cursorRequestAdvertisesApplyPatch,
12+
cursorRequestUsesCodeMode,
13+
isCursorCodeModeExecTool,
1214
cursorToolArgNormalizeSchema,
1315
cursorToolInputSchema,
1416
cursorToolWireName,
@@ -411,3 +413,72 @@ describe("Cursor tool definitions", () => {
411413
expect(allowedNote).not.toContain("`mcp__fs__read_file`");
412414
});
413415
});
416+
417+
describe("Cursor code mode tool guidance", () => {
418+
const codeModeExec = (): OcxTool => ({
419+
name: "exec",
420+
description: "Run JavaScript code to orchestrate tool calls. Nested tools are available on the global `tools` object.",
421+
parameters: {},
422+
freeform: true,
423+
});
424+
425+
test("detects code mode only when freeform exec has no bare shell bridge", () => {
426+
expect(cursorRequestUsesCodeMode([codeModeExec()])).toBe(true);
427+
expect(isCursorCodeModeExecTool(codeModeExec())).toBe(true);
428+
429+
// A non-freeform `exec` is not code mode.
430+
expect(cursorRequestUsesCodeMode([{ name: "exec", description: "Run", parameters: {} }])).toBe(false);
431+
// A bare shell bridge alongside it means the flat-catalog guidance still applies.
432+
expect(cursorRequestUsesCodeMode([codeModeExec(), { name: "exec_command", description: "Run", parameters: {} }])).toBe(false);
433+
expect(cursorRequestUsesCodeMode([{ name: "exec_command", description: "Run", parameters: {} }])).toBe(false);
434+
expect(cursorRequestUsesCodeMode(undefined)).toBe(false);
435+
// Tool choice that hides exec also hides code mode.
436+
expect(cursorRequestUsesCodeMode([codeModeExec(), { name: "read_file", namespace: "mcp__fs", description: "R", parameters: {} }], { name: "read_file" })).toBe(false);
437+
});
438+
439+
test("teaches the nested-helper contract instead of a top-level shell bridge", () => {
440+
const note = buildCursorToolGuidanceSystemNote([codeModeExec()]);
441+
expect(note).toBeDefined();
442+
if (!note) throw new Error("Expected Cursor tool guidance note");
443+
444+
expect(note).toContain("is Codex code mode");
445+
expect(note).toContain("V8 isolate");
446+
expect(note).toContain("await tools.<name>(...)");
447+
expect(note).toContain("await tools.exec_command({cmd: " + "\"" + "ls" + "\"" + "})");
448+
expect(note).toContain("text(...)");
449+
expect(note).toContain("There is no `require`");
450+
451+
// The flat-catalog shell-bridge guidance must NOT appear: naming a top-level
452+
// `exec_command` in code mode sends the model after a tool that does not exist.
453+
expect(note).not.toContain("is the Codex Responses shell bridge for this turn");
454+
expect(note).not.toContain("mcp_opencodex-responses_shell_command");
455+
expect(note).not.toContain("For file read/search/listing, use");
456+
});
457+
458+
test("keeps other visible top-level tools callable in code mode", () => {
459+
// Code mode is about how `exec` works, not a claim that the rest of the catalog is nested.
460+
// A turn can advertise freeform `exec` alongside ordinary top-level tools, and describing
461+
// those as non-top-level would make the model refuse tools it can actually call.
462+
const note = buildCursorToolGuidanceSystemNote([
463+
codeModeExec(),
464+
{ name: "mcp__fs__read_file", description: "Read a file", parameters: {} },
465+
]);
466+
expect(note).toBeDefined();
467+
if (!note) throw new Error("Expected Cursor tool guidance note");
468+
469+
expect(note).toContain("is Codex code mode");
470+
expect(note).toContain("remains callable at the top level as usual");
471+
expect(note).toContain("mcp__fs__read_file");
472+
expect(note).not.toContain("they are not separate top-level tools");
473+
});
474+
475+
test("keeps flat-catalog shell-bridge guidance when a bare bridge is advertised", () => {
476+
const note = buildCursorToolGuidanceSystemNote([{ name: "exec_command", description: "Run", parameters: {} }]);
477+
expect(note).toBeDefined();
478+
if (!note) throw new Error("Expected Cursor tool guidance note");
479+
480+
expect(note).toContain("is the Codex Responses shell bridge for this turn");
481+
expect(note).not.toContain("is Codex code mode");
482+
expect(note).not.toContain("V8 isolate");
483+
});
484+
});

0 commit comments

Comments
 (0)