fix(cursor): preserve unified exec in generic tool filtering

[Ingwannu]

Summary

• preserve Codex Desktop unified exec in Cursor generic tool-use filtering, including the opencodex-responses namespace form
• keep legacy shell-alias guidance gated on an actual exec_command/shell_command alias, so Cursor is not instructed to call tools absent from the child catalog
• verify unified exec remains registered in mcp_tools and is surfaced back to Codex through the Responses client-tool suspension path instead of native local exec
• document why Desktop remains the execution/approval authority

Fixes #1661.

Verification

• bun test ./tests/cursor-tool-definitions.test.ts ./tests/cursor-blob.test.ts ./tests/cursor-tool-continuation.test.ts — 91 passed, 0 failed
• bun test ./tests/cursor-*.test.ts — 518 passed, 0 failed
• bun x tsc --noEmit — passed
• bun run privacy:scan — passed
• git diff --check — passed

Scope

Bug fix and architecture documentation only. No GUI or user-facing text direction change.

Summary by CodeRabbit

• Enhancements

  • Improved Cursor tool handling to support the unified Desktop exec tool alongside legacy shell aliases.
  • Preserved the unified exec tool during generic tool-use prompts while filtering unrelated tools.
  • Unified exec calls now continue through the client-tool flow with proper progress events and deferred completion.

• Documentation

  • Clarified how Cursor tool filtering and shell guidance work across supported execution tools.

• Tests

  • Added regression coverage for tool visibility, filtering, and unified exec continuation behavior.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8e0dc263-4987-488a-9be2-e3df590279fe

📥 Commits

Reviewing files that changed from the base of the PR and between c6688c7 and 8e8a649.

📒 Files selected for processing (5)

• src/adapters/cursor/tool-definitions.ts
• structure/04_transports-and-sidecars.md
• tests/cursor-blob.test.ts
• tests/cursor-tool-continuation.test.ts
• tests/cursor-tool-definitions.test.ts

---

📝 Walkthrough

Walkthrough

Cursor generic tool handling now recognizes unified Desktop exec as an execution-path tool. Filtering preserves supported exec tools, excludes unrelated tools, applies shell guidance only for present aliases, and validates Responses bridge continuation behavior.

Changes

Cursor unified exec bridge

Layer / File(s)	Summary
Execution-path detection and filtering src/adapters/cursor/tool-definitions.ts	Added cursorRequestHasExecutionPath. Generic tool-use detection and active-prompt filtering now preserve unified exec and legacy execution-path tools instead of requiring bare exec_command.
Unified exec bridge validation tests/cursor-blob.test.ts, tests/cursor-tool-definitions.test.ts, tests/cursor-tool-continuation.test.ts, structure/04_transports-and-sidecars.md	Tests verify tool visibility, namespace handling, filtered wait and js tools, conditional shell guidance, Responses client-tool events, and deferred finalization. Documentation records the same behavior.

Estimated code review effort: 3 (Moderate) | ~15 minutes

Merge Risk: ⚪ Minimal · up to 8e8a6

This localized Cursor tool-filtering fix preserves unified execution behavior and keeps legacy guidance appropriately gated; no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• lidge-jun/opencodex#402: Directly modifies Cursor shell-bridge aliasing and execution-path filtering.
• lidge-jun/opencodex#1583: Introduces related unified exec handling in Cursor tool detection.
• lidge-jun/opencodex#1228: Covers related Cursor blob and mcp_tools filtering behavior.

Suggested labels: documentation

Suggested reviewers: lidge-jun, wibias

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the Cursor generic tool-filtering fix and the preservation of unified exec, which is the main change.
Linked Issues check	✅ Passed	The changes preserve unified exec, gate shell-alias guidance, relay client-tool calls, and add regressions required by issue #1661.
Out of Scope Changes check	✅ Passed	The code, documentation, and regression tests directly support the unified exec filtering and Cursor bridge objectives in issue #1661.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/1661-cursor-unified-exec

---

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.}

[lidge-jun]

[Repository bug audit · 2026-08-14]

The reviewed logic is sound: generic tool-use filtering now recognizes every Cursor execution-path tool, preserves unified Desktop exec, keeps legacy alias guidance conditional on an alias actually being present, and routes execution back through the Responses client-tool suspension path rather than native local exec.

This PR is currently not mergeable against dev. Rebase onto the latest dev, resolve only the tool-definition/continuation overlap, and rerun the full tests/cursor-*.test.ts set plus typecheck. Do not fold the larger structured-edit work from #1634 into this focused fix.

[lidge-jun]

Cherry-picked onto dev as part of the bug resolution campaign (commit-and-merge loop). Changes verified with typecheck and focused tests.