fix(cursor): scope cursor-execute to file ops only; defer shell to caller

Cursor's `agent acp` mode has two distinct upstream bugs (no software fix
available, both confirmed by Cursor staff):

1. Windows shell auto-detection picks WSL bash instead of PowerShell, so
   Terminal/execute tool calls hang at tool_call_update[in_progress]
   forever. forum.cursor.com/t/.../155544
2. MCP tool calls silently stop emitting mcpToolCall events starting
   2026.04.17. forum.cursor.com/t/.../158988

Workarounds tried per forum: Legacy Terminal Tool, removing WSL from
PATH, disabling MCP. None help. Last known-good version is 2026.04.14
which the user does not have cached.

Practical fix: stop trying to use Cursor's Terminal tool. Cursor's role
in this marketplace is the fast-lane file writer (200+ lines, multi-file
patterns, mechanical implementation) — file ops via ACP work fine. Move
shell verification to the parent Claude thread, which has a reliable
Bash tool.

Changes:
- agents/cursor-execute.md framing: "DO NOT use Terminal/execute" + the
  ## Verification section is now "(deferred — caller runs)" instead of
  asking Cursor to run commands and report exit codes.
- cursor/commands/execute.md: scope note + post-dispatch instruction for
  the calling thread to run verification and surface results.
- adapters/cursor.mjs: expanded the known-bad-version warning to cover
  both bugs and broaden coverage (added 2026.04.29 to the affected set).

This unblocks daily use while we wait for upstream Cursor fixes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: greenpolo

plugins/cursor/commands/execute.md

@@ -6,7 +6,9 @@ allowed-tools: Bash(node:*), AskUserQuestion, Agent
 
 Invoke the `multi:cursor-execute` subagent via the `Agent` tool, forwarding the user's request as the prompt.
 
-The subagent runs Cursor in Agent mode on Auto model — give it a concrete, well-defined plan step and Cursor implements it with full tool access. Cursor is the fast lane: pick it over `/codex:execute` when the spec is clear, the work is mostly mechanical (long file writes, pattern application across many files, 200+ lines of code), and you want throughput over deep reasoning.
+The subagent runs Cursor in Agent mode on Auto model — give it a concrete, well-defined plan step and Cursor writes the files. **Scope: file operations only** (Read, Write, Edit, Apply Patch). Cursor's shell exec is unreliable in agent acp mode on Windows due to an upstream bug, so the subagent intentionally does not run verification commands. After it returns, run any listed verification yourself.
+
+Cursor is the fast lane: pick it over `/codex:execute` when the spec is clear, the work is mostly mechanical (long file writes, pattern application across many files, 200+ lines of code), and you want throughput over deep reasoning.
 
 Raw user request:
 $ARGUMENTS
@@ -18,4 +20,6 @@ Execution:
 - If the user passes `--resume`, the subagent will continue the latest Cursor execute thread for this repo.
 - If the request includes no prompt text, ask what Cursor should implement before proceeding.
 
-Return Cursor's output verbatim.
+After the subagent returns, read its `## Verification` section and run those commands via your own Bash tool. Then surface the report and the verification results to the user.
+
+Return Cursor's output verbatim, followed by your verification results.

plugins/multi/agents/cursor-execute.md

@@ -18,7 +18,9 @@ The forwarding contract — flag handling, runtime controls, safety rules, failu
 Prepend this framing block to the user's task text, then a blank line, then the user's task verbatim. Skip framing if the user already wrote outcome-style framing themselves.
 
 ```
-You are Cursor in Agent mode with full tool access. The task below is a well-defined plan step — implement it end-to-end without asking for confirmation. Batch file reads in parallel; batch edits per file. Skip upfront plans for clear tasks.
+You are Cursor in Agent mode. Use Read, Write, Edit, and Apply Patch — file ops are reliable. The task below is a well-defined plan step — implement it end-to-end without asking for confirmation. Batch file reads in parallel; batch edits per file. Skip upfront plans for clear tasks.
+
+DO NOT use the Terminal/execute tool. Cursor's shell exec in agent acp mode has an upstream Windows bug (WSL bash auto-detection) that hangs commands silently. Do not run python, pytest, git, ls, wc, or any other shell command. If the task asks for shell-based verification, leave it for the caller to run after — do not attempt it yourself.
 
 End your response with a structured final report in this exact format (verbatim markdown headers, no extra commentary after):
 
@@ -29,8 +31,7 @@ End your response with a structured final report in this exact format (verbatim
 - relative/path/to/file (created|modified|deleted) — one-line reason
 
 ## Verification
-- command run — exit code — one-line interpretation
-(or "no verification commands run" if none)
+- (deferred — caller runs verification commands after dispatch; list any commands the caller should run, one per line)
 
 ## Notes
 - (optional, only if anything surprised you, was deferred, or remains open)
@@ -39,7 +40,7 @@ Task:
 <user task verbatim>
 ```
 
-The structured final report is what main Claude surfaces to the user. Cursor's chain-of-thought stream gets discarded once the report is in place — this turns Cursor's verbose token streaming into a codex-shaped clean answer.
+The structured final report is what main Claude surfaces to the user. Cursor's chain-of-thought stream gets discarded once the report is in place — this turns Cursor's verbose token streaming into a codex-shaped clean answer. The caller (main Claude) is responsible for running the verification commands listed in `## Verification` after the dispatch returns.
 
 ## Companion invocation
 
@@ -53,3 +54,7 @@ Role-specific defaults that override or extend the multi-cli-runtime contract:
 - Cursor does not support `--effort`; ignore that flag if present.
 - For prompts expected to take more than ~90 seconds (multi-file refactors, large scaffolding, anything with >5 file ops), prefer `--background` so progress is visible via `/multi:status` instead of blocking the parent agent. Bounded prompts (1–3 file ops) stay foreground.
 - Append `2>&1` to the Bash call so runtime diagnostics surface.
+
+## After the dispatch returns
+
+When you (the parent Claude thread receiving this subagent's output) read the structured report, run the commands listed in `## Verification` yourself via your own Bash tool. Cursor cannot run shell commands reliably in agent acp mode on Windows (upstream WSL bash detection bug — see cursor.mjs comments and forum.cursor.com/t/shell-commands-in-agent-mode-are-not-returning-output/155544). Cursor's job is file writing; verification is yours.

plugins/multi/scripts/lib/adapters/cursor.mjs

@@ -81,18 +81,37 @@ function buildPrompt(role, userTask) {
 
 // ─── Known-bad version warning ────────────────────────────────────────────────
 //
-// Cursor 2026.04.17-787b533 has a documented regression: MCP tool calls and
-// the Terminal (execute) tool both silently break in agent acp mode. We can't
-// fix it from the client; we just want users to know about it instead of
-// spending hours debugging mysterious hangs.
+// Cursor's `agent acp` mode has two distinct upstream bugs we have to live
+// with. Both are confirmed by Cursor staff with no published fix or ETA:
 //
-// Forum threads:
-//   https://forum.cursor.com/t/cursor-agent-cli-mcp-tool-calls-silently-stopped-working-in-2026-04-17/158988
-//   https://forum.cursor.com/t/acp-permission-rejection-not-reported-to-client/153825
+// Bug 1 — MCP tool-call regression starting in 2026.04.17.
+//   Tool descriptors are visible to the model but mcpToolCall events silently
+//   never fire. CLI/headless only; the IDE is fine.
+//   Forum:
+//     https://forum.cursor.com/t/cursor-agent-cli-mcp-tool-calls-silently-stopped-working-in-2026-04-17/158988
+//   Last known working version per Cursor staff: 2026.04.14-ee4b43a.
+//   Workaround: pin via CURSOR_AGENT_PATH if you have an older binary cached.
 //
-// Auto-quiet on any other version. Warning fires once per process.
-
-const KNOWN_BROKEN_CURSOR_VERSIONS = new Set(["2026.04.17-787b533"]);
+// Bug 2 — Windows shell auto-detection picks WSL bash (C:\Windows\System32\
+//   bash.exe) instead of PowerShell, so command output capture fails silently
+//   and Terminal/execute tool calls hang at tool_call_update[in_progress]
+//   forever. Confirmed Windows-only; Cursor IDE handles this differently.
+//   Forum:
+//     https://forum.cursor.com/t/shell-commands-in-agent-mode-are-not-returning-output/155544
+//     https://forum.cursor.com/t/acp-permission-rejection-not-reported-to-client/153825
+//   Tested workarounds that don't help: Legacy Terminal Tool, removing WSL
+//   from PATH, disabling MCP. No working software fix as of 2026-04-30.
+//
+// Our response: cursor-execute.md instructs Cursor to NOT use Terminal in agent
+// acp mode and defers shell verification to the parent Claude thread. File ops
+// (Read/Write/Edit/Apply Patch) work fine and that's what cursor-execute is
+// scoped to do. Warning below fires once per process if a known-affected
+// version is detected.
+
+const KNOWN_BROKEN_CURSOR_VERSIONS = new Set([
+  "2026.04.17-787b533",
+  "2026.04.29-c83a488"
+]);
 let warnedAboutCursorVersion = false;
 
 function maybeWarnAboutCursorVersion(versionString) {
@@ -102,11 +121,12 @@ function maybeWarnAboutCursorVersion(versionString) {
   if (!KNOWN_BROKEN_CURSOR_VERSIONS.has(v)) return;
   warnedAboutCursorVersion = true;
   process.stderr.write(
-    `[cursor] Note: agent ${v} has known ACP regressions — ` +
-    `Terminal/execute tool calls and MCP tools may stall in agent acp mode. ` +
-    `cli-config.json allowlist (auto-injected) keeps simple shell exec working; ` +
-    `complex multi-tool runs may still hang upstream. Pin an older build via ` +
-    `CURSOR_AGENT_PATH if needed; otherwise wait for the next Cursor release.\n`
+    `[cursor] Note: agent ${v} has known upstream ACP regressions — ` +
+    `Terminal/execute tool calls hang on Windows (WSL shell auto-detection) and ` +
+    `MCP tool calls silently fail (regression starting in 2026.04.17). ` +
+    `cursor-execute is scoped to file ops only and defers shell verification ` +
+    `to the parent thread. Pin 2026.04.14-ee4b43a via CURSOR_AGENT_PATH if ` +
+    `you need MCP tools through Cursor; otherwise wait for the next Cursor release.\n`
   );
 }