fix(cursor): route native fallbacks through code mode

[luvyoun0224-beep]

Summary

• Preserve Codex 0.147's real Responses Lite tool shape: the reserved functions namespace now flattens ordinary client functions and its nested freeform custom exec into top-level internal tools.
• Detect those code-mode turns in the live Cursor transport and retain that mode in the native-exec context.
• Replace misleading top-level shell_command / exec_command fallback instructions with the real code-mode contract: top-level exec, then nested tools.exec_command(...) or tools.apply_patch(...), with text(...) output.
• Keep the existing flat-catalog guidance unchanged for non-code-mode requests and keep native local execution disabled by default.
• Add regression coverage for the captured Codex 0.147 additional_tools shape, filesystem, shell, fetch, MCP-resource, mutation, and live-transport propagation paths.

This follows #1844. That change fixed system guidance, but two gaps remained: Codex 0.147 groups custom exec under the reserved functions namespace, which the parser dropped, and Cursor-native rejection responses still directed models to top-level tools that do not exist in code mode.

Verification

• focused Cursor/native/parser/Responses Lite suites: 162 pass
• all tests/cursor-*.test.ts files: 602 pass
• bun run typecheck
• bun run privacy:scan
• git diff --check
• bounded local live probe through Codex 0.147 + Cursor: the model successfully executed Get-Content package.json and read version 2.22.0; the following model continuation hit the account's Cursor resource limit, so the probe did not receive its requested final formatted line.
• Full bun test was attempted on Windows; it stopped making progress during unrelated integration tests and was interrupted after more than 90 seconds without output.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. (No user-facing configuration changed.)
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

AI assistance was used for implementation and test preparation; the resulting diff and verification output were reviewed locally.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c6872267-8b86-4413-a69a-e2be5f22bbe7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[lidge-jun]

Reviewed as the candidate canonical PR for the #1887/#1896 consolidation. Do not close #1887
as superseded yet — one thing in it has to move here first, and it is not a nicety.

codeModeBridgeGuidance in this PR hardcodes the literal `exec` and the
mcp_opencodex-responses_* names whenever codeMode === true. That is a boolean, not a read
of what the request actually advertised. #1887 does the same job by asking the catalog:
cursorNativeExecUsesCodeModeBridge(catalog) checks hasAdvertisedName and returns
{kind:"none"} when exec is not advertised.

The reason this matters more than a style preference: #1895 exists specifically to remove
hardcoded tool names from the shared catalog nudge, on the grounds that hardcoding re-creates
per-provider drift. Landing this PR as canonical would re-introduce that defect one PR after
deleting it, in the same wave.

Four more things live only in #1887 and would be lost:

1. native-exec-bridge.ts — the rewrite engine that translates denied native args into
   cat/ls/rg/curl with shell quoting. This PR has no equivalent.
2. planNativeExecRewrite's finalize-vs-cancel ordering, with the documented failure mode:
   an immediate cancelCursorRun() sets expectedClose, scheduleClientToolFinalize becomes a
   no-op, turn 1 never emits done, the conversation id is dropped, and the rewritten result
   never comes back. That is expensive knowledge to rediscover.
3. Three cursor-native-exec-policy.test.ts cases — rewrite, defer-while-sibling-open, and
   non-code-mode fallthrough.
4. Windows PowerShell 5.1 guidance ([Bug] Cursor Auto repeats tool continuations on Windows PowerShell 5.1, causing excessive token usage #604): no cd /d, no heredocs, &&/|| are parser
   errors, one-retry cap. The guidance string here drops all of it.

Worth saying explicitly that these two PRs are not duplicates in kind. This one is
guidance — a denied op returns text asking the model to call exec itself, so it depends on
model compliance. #1887 is mechanical — it intercepts the denied frame and synthesizes a real
exec call, needing none. Guidance is the better default; the rewrite is the fallback for when
the model ignores it. Keeping both layers is the point of consolidating rather than choosing.

This PR is still draft, so nothing is blocked by this note. The parser fix here (flattening
Codex 0.147's reserved functions namespace so freeform custom children like code-mode exec
survive) is genuinely load-bearing and absent from #1887 — that, not scope, is the real case
for making this one canonical.

[lidge-jun]

Reviewed as the intended canonical of the #1887/#1896 pair, and it is the right choice — the
parser.ts fix here (flattening Codex 0.147's reserved functions namespace so freeform
custom children like code-mode exec survive) is load-bearing and absent from #1887.

But do not merge this and close #1887 as superseded, because one guard would be lost and
it is the one that matters most:

codeModeBridgeGuidance hardcodes the literal `exec` and the mcp_opencodex-responses_*
names whenever codeMode === true. #1887 instead derives them from the advertised catalog via
cursorNativeExecUsesCodeModeBridge, returning {kind:"none"} when the catalog does not
advertise exec.

That is the same defect #1895 was opened to remove — naming tools the turn may not actually
advertise. I have just fixed the shared-nudge version of it in #1951, which decides code mode
from freeform metadata rather than the name, precisely because a structured exec, or an
exec beside a visible shell bridge, is not code mode at all. Landing this as-is would
re-introduce that shape in the Cursor path one PR after deleting it from the shared one.

To become canonical, this needs #1887's:

1. cursorNativeExecUsesCodeModeBridge catalog detection replacing the hardcoded names — the blocker
2. the native-exec-bridge.ts rewrite engine, which synthesizes a real exec call instead of asking the model to make one
3. planNativeExecRewrite's finalize-vs-cancel ordering and its documented failure mode
4. the three cursor-native-exec-policy.test.ts cases
5. the Windows PowerShell 5.1 guidance from [Bug] Cursor Auto repeats tool continuations on Windows PowerShell 5.1, causing excessive token usage #604

Items 1 and 2 are the substantive ones: guidance depends on model compliance, the rewrite does
not, so they are complementary layers rather than two takes on one fix.

Merge mechanics: this branch is currently clean against dev after #1900 landed (2b12521ee).