fix(cursor): teach code-mode nested-helper contract in tool guidance

src/adapters/cursor/tool-definitions.ts

@@ -191,6 +191,38 @@ export function isCursorWaitTool(tool: Pick<OcxTool, "namespace" | "name">): boo
   return isCursorResponsesProvider(tool.namespace) && tool.name === CODEX_WAIT_TOOL;
 }
 
+/**
+ * True for Codex's unified-exec "code mode" tool: a freeform `exec` whose body is JavaScript
+ * evaluated in a V8 isolate, not a shell command string.
+ */
+export function isCursorCodeModeExecTool(
+  tool: Pick<OcxTool, "namespace" | "name" | "freeform">,
+): boolean {
+  return isCursorResponsesProvider(tool.namespace)
+    && tool.name === CODEX_UNIFIED_EXEC_TOOL
+    && tool.freeform === true;
+}
+
+/**
+ * Codex code mode advertises ONE freeform `exec` tool and no bare shell bridge. Shell, file
+ * edits, and MCP calls are reachable only as nested `tools.<name>(...)` helpers described inside
+ * that tool's own description, so a flat catalog scan cannot see them.
+ *
+ * This matters because the shell-bridge guidance below is written for a flat catalog. Emitting
+ * "call \`exec_command\`" into a code-mode turn names a top-level tool that does not exist: the
+ * model calls it, gets nothing back, and burns turns rediscovering the real contract from error
+ * messages (empty output until \`text()\` is called, \`require is not defined\` because the isolate
+ * is not Node, \`apply_patch\` rejected because it too is only a nested helper here).
+ */
+export function cursorRequestUsesCodeMode(
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): boolean {
+  const catalog = tools ?? [];
+  const visible = catalog.filter(tool => cursorToolAllowedByChoice(tool, toolChoice, catalog));
+  return visible.some(isCursorCodeModeExecTool) && !visible.some(isBareCodexShellBridgeTool);
+}
+
 /** @deprecated Prefer isBareCodexShellBridgeTool; kept for older call sites/tests. */
 function isBareCodexExecCommandTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
   return isBareCodexShellBridgeTool(tool);
@@ -554,6 +586,7 @@ export function buildCursorToolGuidanceSystemNote(
   const listedNames = quotedNames(wireNames);
   const shellBridgeNames = wireNames.filter(isCodexShellBridgeToolName);
   const hasBareExec = shellBridgeNames.length > 0;
+  const codeMode = cursorRequestUsesCodeMode(tools, toolChoice);
   const shellBridgeLabel = quotedNames(shellBridgeNames.length > 0 ? shellBridgeNames : [...CODEX_SHELL_BRIDGE_TOOL_NAMES]);
   const hasApplyPatch = cursorRequestAdvertisesApplyPatch(tools, toolChoice);
   const structuredEditNames = tools
@@ -572,6 +605,14 @@ export function buildCursorToolGuidanceSystemNote(
     unavailableNeighborNames.length > 0
       ? `This turn does not expose neighboring-agent tool names ${quotedNames(unavailableNeighborNames)}; do not call or suggest them unless the catalog lists them.`
       : undefined,
+    // Code mode: the ONLY callable tool is freeform `exec`, and shell/edit/MCP live inside it as
+    // nested helpers. Without this the model probes for a top-level shell tool that is not there.
+    codeMode
+      ? `\`${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; they are not separate top-level tools, so do not call \`exec_command\`, \`shell_command\`, or \`apply_patch\` at the top level here.`
+      : undefined,
+    codeMode
+      ? "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."
+      : undefined,
     hasBareExec
       ? `${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.`
       : undefined,

tests/cursor-tool-definitions.test.ts

@@ -9,6 +9,8 @@ import {
   buildCursorToolGuidanceSystemNote,
   CURSOR_EXEC_COMMAND_INPUT_SCHEMA,
   cursorRequestAdvertisesApplyPatch,
+  cursorRequestUsesCodeMode,
+  isCursorCodeModeExecTool,
   cursorToolArgNormalizeSchema,
   cursorToolInputSchema,
   cursorToolWireName,
@@ -411,3 +413,55 @@ describe("Cursor tool definitions", () => {
     expect(allowedNote).not.toContain("`mcp__fs__read_file`");
   });
 });
+
+describe("Cursor code mode tool guidance", () => {
+  const codeModeExec = (): OcxTool => ({
+    name: "exec",
+    description: "Run JavaScript code to orchestrate tool calls. Nested tools are available on the global `tools` object.",
+    parameters: {},
+    freeform: true,
+  });
+
+  test("detects code mode only when freeform exec has no bare shell bridge", () => {
+    expect(cursorRequestUsesCodeMode([codeModeExec()])).toBe(true);
+    expect(isCursorCodeModeExecTool(codeModeExec())).toBe(true);
+
+    // A non-freeform `exec` is not code mode.
+    expect(cursorRequestUsesCodeMode([{ name: "exec", description: "Run", parameters: {} }])).toBe(false);
+    // A bare shell bridge alongside it means the flat-catalog guidance still applies.
+    expect(cursorRequestUsesCodeMode([codeModeExec(), { name: "exec_command", description: "Run", parameters: {} }])).toBe(false);
+    expect(cursorRequestUsesCodeMode([{ name: "exec_command", description: "Run", parameters: {} }])).toBe(false);
+    expect(cursorRequestUsesCodeMode(undefined)).toBe(false);
+    // Tool choice that hides exec also hides code mode.
+    expect(cursorRequestUsesCodeMode([codeModeExec(), { name: "read_file", namespace: "mcp__fs", description: "R", parameters: {} }], { name: "read_file" })).toBe(false);
+  });
+
+  test("teaches the nested-helper contract instead of a top-level shell bridge", () => {
+    const note = buildCursorToolGuidanceSystemNote([codeModeExec()]);
+    expect(note).toBeDefined();
+    if (!note) throw new Error("Expected Cursor tool guidance note");
+
+    expect(note).toContain("is Codex code mode");
+    expect(note).toContain("V8 isolate");
+    expect(note).toContain("await tools.<name>(...)");
+    expect(note).toContain("await tools.exec_command({cmd: " + "\"" + "ls" + "\"" + "})");
+    expect(note).toContain("text(...)");
+    expect(note).toContain("There is no `require`");
+
+    // The flat-catalog shell-bridge guidance must NOT appear: naming a top-level
+    // `exec_command` in code mode sends the model after a tool that does not exist.
+    expect(note).not.toContain("is the Codex Responses shell bridge for this turn");
+    expect(note).not.toContain("mcp_opencodex-responses_shell_command");
+    expect(note).not.toContain("For file read/search/listing, use");
+  });
+
+  test("keeps flat-catalog shell-bridge guidance when a bare bridge is advertised", () => {
+    const note = buildCursorToolGuidanceSystemNote([{ name: "exec_command", description: "Run", parameters: {} }]);
+    expect(note).toBeDefined();
+    if (!note) throw new Error("Expected Cursor tool guidance note");
+
+    expect(note).toContain("is the Codex Responses shell bridge for this turn");
+    expect(note).not.toContain("is Codex code mode");
+    expect(note).not.toContain("V8 isolate");
+  });
+});