Skip to content

fix(cursor): emit Cursor-contract JSON from managed hooks - #15651

Merged
brennanb2025 merged 3 commits into
mainfrom
brennanb2025/sta-4848-cursor-hook-stdout
Aug 27, 2026
Merged

brennanb2025 merged 3 commits into
mainfrom
brennanb2025/sta-4848-cursor-hook-stdout

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Aug 20, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 3 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​185 $\color{#cf222e}{\Huge{\mathbf{−}}}$​23 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​162
Prod 6 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​138 $\color{#cf222e}{\Huge{\mathbf{−}}}$​32 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​106

ELI5

Orca's Cursor status hooks reported activity to Orca but printed nothing back to Cursor. Cursor requires JSON on stdout, so every tool call was blocked. The hooks now return the documented allow/neutral JSON while still posting telemetry.

What Changed

  • Emit {"permission":"allow"} first for Cursor permission events (preToolUse, beforeShellExecution, beforeMCPExecution) and {} for the other subscribed events, on both the Windows and POSIX managed scripts.
  • Pass that response through ORCA_CURSOR_HOOK_RESPONSE on the shared PowerShell/POSIX launchers, and through fallbackStdout when the managed script is missing.
  • Teach wrapWindowsHookCommand the same fallbackStdout option POSIX wrap already had, so Windows missing-script cannot drift from POSIX.
  • Split Cursor hook events and script generation out of hook-service.ts so the installer stays focused.

Why

Blank stdout is not valid Cursor hook output. cursor-agent fails closed with Hook "..." returned invalid JSON, which blocked every gated tool call whenever Orca agent-status hooks were on (#15462). This is the Cursor-installer sibling of #14825: write the contract JSON first, and keep launcher fallbacks on the shared wrapper.

Linked Issue

Fixes #15462
STA-4848

Supersedes #15576

How this supersedes #15576

Carries forward sanshengai's per-event response env + fallbackStdout approach. Differences:

  1. Routes Windows missing-script through the shared wrapWindowsHookCommand fallback so it matches POSIX wrap and cannot drift from the fix(agent-hooks): make the Windows managed hook survive Claude-hooks-compat consumers #14825 launcher.
  2. Splits events/script generation into hook-events.ts / hook-script.ts instead of growing hook-service.ts.
  3. Consumer-observation tests run the registered hooks.json command (not installer-intent string checks) for every event, empty stdin, missing script, and a dead listener; Windows also covers cmd.exe and Git Bash like fix(agent-hooks): make the Windows managed hook survive Claude-hooks-compat consumers #14825.
  4. SSH remote install uses the same per-event mapping as local install.
  5. Based on current origin/main, not the community PR's stale base.

Visual Proof

N/A — this changes the hook subprocess protocol, not rendered UI.

Testing

  • Wrote the consumer-observation tests first; they failed on unfixed code with SyntaxError: Unexpected end of JSON input (empty stdout).
  • After the fix: src/main/cursor/hook-service.test.ts 5 passed / 2 skipped (Windows-only).
  • Neutered the stdout emission; the same tests failed again with the same SyntaxError. Restored the fix; tests passed.
  • Also ran installer-utils, remote-hook-service-installers, and managed-hook-stdin-lifecycle (100 passed / 7 skipped).
  • pnpm typecheck and targeted oxlint / oxfmt clean.
  • Windows cmd.exe + Git Bash test is present and skipIf not win32; CI Windows should exercise it. POSIX proven on macOS.

AI Disclosure

Review

Agent skill upstream boundary

  • Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

  • The unreachable :orca_agent_hook_drain_stdin label in cursor-hook.cmd is intentional after [Bug]: Codex managed hook leaves persistent cmd.exe windows outside Orca on Windows #11549: missing-Orca-env paths must exit /b 0 without more.com. Claude only gotos that label from the Devin skip. The shared epilogue stays because the cross-agent stdin-lifecycle suite requires it. Not a bug.
  • orca agent hooks off reporting managedHooksPresent: false while stale Claude entries remain is a separate defect (getStatus exact-matches the current command). Not in this PR.
  • Cursor caches hook config at agent start; repairing config does not unblock a running agent. Product suggestion, out of scope.

Checklist

  • This PR is small and focused
  • I explained what changed and why (including ELI5)
  • Before/after screenshots or videos attached for UI changes, or N/A with reason
  • Self-reviewed for correctness, security, and performance
  • Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
  • pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

Author

  • X: @BrennanKB5

@coderabbitai

coderabbitai Bot commented Aug 20, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e7fdd18c-19eb-40c7-b539-5f57eb7f8ac2

📥 Commits

Reviewing files that changed from the base of the PR and between 9062494 and f390129.

📒 Files selected for processing (9)
  • .github/workflows/pr.yml
  • config/tsconfig.cli.json
  • src/main/agent-hooks/installer-utils.test.ts
  • src/main/agent-hooks/installer-utils.ts
  • src/main/agent-hooks/remote-hook-service-installers.test.ts
  • src/main/cursor/hook-events.ts
  • src/main/cursor/hook-script.ts
  • src/main/cursor/hook-service.test.ts
  • src/main/cursor/hook-service.ts
🚧 Files skipped from review as they are similar to previous changes (6)
  • src/main/agent-hooks/installer-utils.ts
  • src/main/cursor/hook-events.ts
  • config/tsconfig.cli.json
  • src/main/agent-hooks/installer-utils.test.ts
  • src/main/cursor/hook-script.ts
  • src/main/cursor/hook-service.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 4 remain after this review.


📝 Walkthrough

Walkthrough

The change adds shared Cursor event definitions and event-specific response selection. It generates POSIX and Windows managed hook commands and local scripts with protocol fallbacks, environment checks, endpoint refresh, payload forwarding, and stdin draining. Cursor hook installation, status checks, and removal now use the shared generators. The CLI TypeScript configuration includes the new modules. Tests cover normal and empty input, missing scripts, unreachable listeners, fallback output, and Windows execution.

Merge Risk: 🟡 Moderate · up to f3901

A Windows managed hook can exit before consuming Cursor’s payload on affected paths, risking failed or stalled hook invocations. Merge readiness remains moderate until the stdin-drain behavior is fixed or explicitly accepted by the owner.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 7 files. (2 skipped: 2… Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: managed Cursor hooks now emit contract-compatible JSON.
Description check ✅ Passed The description follows the repository template. It explains the problem, changes, rationale, linked issue, testing, scope, and checklist status. It correctly marks visual proof as not applicable.
Linked Issues check ✅ Passed The implementation satisfies issue #15462. It emits allow responses for permission events and neutral JSON for other events across POSIX, Windows, local, and remote hook installations. Tests cover the…
Out of Scope Changes check ✅ Passed The changes remain within scope. Production changes, tests, TypeScript configuration, and Windows CI updates directly support Cursor hook response handling, fallback behavior, cross-platform coverage,…
Full details: Linked Issues check

Explanation

The implementation satisfies issue #15462. It emits allow responses for permission events and neutral JSON for other events across POSIX, Windows, local, and remote hook installations. Tests cover the required command and fallback behavior.

Full details: Out of Scope Changes check

Explanation

The changes remain within scope. Production changes, tests, TypeScript configuration, and Windows CI updates directly support Cursor hook response handling, fallback behavior, cross-platform coverage, and remote installation.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 7 files. (2 skipped: 2 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch

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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c5ad64bc-8dca-4018-91e2-83933476b1ef

📥 Commits

Reviewing files that changed from the base of the PR and between 4e058d4 and b460121.

📒 Files selected for processing (8)
  • config/tsconfig.cli.json
  • src/main/agent-hooks/installer-utils.test.ts
  • src/main/agent-hooks/installer-utils.ts
  • src/main/agent-hooks/remote-hook-service-installers.test.ts
  • src/main/cursor/hook-events.ts
  • src/main/cursor/hook-script.ts
  • src/main/cursor/hook-service.test.ts
  • src/main/cursor/hook-service.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 7 remain after this review.

Comment thread src/main/cursor/hook-script.ts Resolved
@OrcaWin

OrcaWin commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

STA-4848 Windows QA (dev-mode, not packaged)

Verdict: VALIDATED — managed Cursor hooks emit contract JSON on stdout. Windows runner is .cmd via PowerShell -EncodedCommand, not silent conhost.

Empty-profile PR-branch Orca (isDev: true, devRepoRoot = this win-val-15651 worktree) auto-installed managed Cursor hooks. Decoded command entries set ORCA_CURSOR_HOOK_RESPONSE and launch cursor-hook.cmd; none use conhost. Installed .cmd bytes match this PR’s getManagedScript().

Invoked the exact hooks.json command (not a reconstructed cmd /c) for all 8 events from PowerShell and from a second Windows shell feeding the same encoded command: 16/16 exit 0, stdout {"permission":"allow"} for preToolUse / beforeShellExecution / beforeMCPExecution and {} otherwise. Instrumented fire log = 16 (script actually ran). Fast ~41ms exit 0 with 0 fires did not occur. Missing-script fallback (cursor-hook.cmd renamed) still printed {"permission":"allow"}; fire log stayed 16.

STA-4848 QA second Electron, this worktree

@brennanb2025

Copy link
Copy Markdown
Contributor Author

Codex revision pass complete.

I reviewed the implementation, tests, description, issue context, and every PR review/comment from scratch. I kept the product diff unchanged: the per-event Cursor response mapping, event-scoped launcher environment, shared missing-script fallback, local/SSH parity, and registered-command tests are the implementation I would write for #15462. I also replied to the unresolved Windows stdin comment: curl --data-urlencode "payload@-" consumes stdin before connecting, and the early missing-context exits are deliberate under the shared hook lifecycle, so the proposed Cursor-only reorder would not fix a reproducible defect.

Non-vacuity proof: I temporarily removed the managed POSIX stdout response and reran the focused suite. It failed as expected:

src/main/cursor/hook-service.test.ts (7 tests | 2 failed | 2 skipped)
× emits protocol-valid JSON on stdout for every managed event, including empty stdin (#15462)
× keeps curl failure off stdout when the listener is unreachable (#15462)
SyntaxError: Unexpected end of JSON input

After restoring the PR implementation, the same suite passed with 5 passed / 2 skipped.

Final verification:

  • affected suites: 100 passed / 7 platform-skipped
  • pnpm typecheck
  • changed-code quality: 0 findings
  • React Doctor: 0 issues
  • oxfmt check: clean across all 8 changed files
  • git diff --check
  • checked-out HEAD matches live PR head b460121f

No product/test edits, empty commit, or push were warranted; the existing PR head is the correct focused fix.

@brennanb2025

Copy link
Copy Markdown
Contributor Author

macOS QA (isolated dev Electron, HEAD e6c9dcd6ef)

Verdict: settings/startup OK; live cursor-agent hook stdout not exercised. cursor-agent is not on PATH in this environment, so this cannot prove the subprocess JSON contract.

Isolated pnpm dev at this worktree (ORCA_DEV_USER_DATA_PATH + sandbox HOME, CDP 127.0.0.1:9440) started and opened Settings → Agents. Agent status hooks is on. Cursor is listed under Available to install (cursor-agent --yolo), not Installed; presence-gated install therefore skipped writing ~/.cursor/hooks.json / cursor-hook.sh in the sandbox home. That is expected without the CLI.

A screenshot of that settings surface is not proof of hook stdout. The stdout contract at this HEAD is covered by the focused suites already run, re-confirmed here: src/main/cursor/hook-service.test.ts, installer-utils.test.ts, remote-hook-service-installers.test.ts — 90 passed / 5 skipped (Windows-only skips). Those tests run the registered hooks.json command and require {"continue":true} for beforeSubmitPrompt, {"permission":"allow"} for preToolUse / beforeShellExecution / beforeMCPExecution, and {} for the other subscribed events.

Settings → Agents, Agent status hooks on

@brennanb2025

Copy link
Copy Markdown
Contributor Author

Review status: ready

Final reviewed head: a8bf65078918b515c5b70cbd8abd97991102b87a.

  • Review fix 1 (e6c9dcd6ef): beforeSubmitPrompt now emits the required {"continue":true} response, with literal local and SSH contract expectations rather than implementation-derived assertions.
  • Review fix 2 (a8bf650789): the Windows PR workflow now runs src/main/cursor/hook-service.test.ts, so the cmd.exe/Git Bash boundary is exercised in CI.
  • Same-model re-review returned clean: 110 focused tests passed, with formatting, lint, Node/CLI typechecks, and the max-lines ratchet also clean.
  • Electron QA validated isolated startup and Settings → Agents via CDP. cursor-agent was unavailable in that environment, so the screenshot is intentionally limited to startup/settings evidence; the stdout contract is covered by the focused suites and exact-head Windows CI.
  • Closing readiness found no remaining P0/P1/P2 issues. Exact-head CI completed successfully with 45 passed jobs and the unchanged E2E lane skipped; GitHub reports the PR merge state as clean.

@brennanb2025

brennanb2025 commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor Author

Review verification — exact head f3901295f0ff88db94435b7200444ca27abd4cc4

Rebased PR #15651 onto current origin/main and resolved the sole conflict in Cursor hook-service wiring. The resulting tree retains per-event Cursor JSON stdout, POSIX spool/retry behavior, Windows stdin-drain/cmd boundary, and local/SSH parity. Focused suites: 91 passed / 5 skipped; pnpm tc, direct changed-file oxlint, oxfmt, and git diff --check are clean. GitHub checks for this exact SHA are still running; no unresolved review findings are present.

Checks: PR checks · commit

@brennanb2025

brennanb2025 commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor Author

QA evidence — exact head f3901295f0ff88db94435b7200444ca27abd4cc4

The branch was rebased onto current origin/main; conflict repair only moved Cursor hook generation into shared modules while preserving the previously validated Windows cmd/Git Bash and remote SSH behavior. Focused local hook suites pass (91 passed / 5 skipped), including per-event JSON stdout and missing-script/dead-listener fallbacks. Prior Windows and SSH QA observations remain behaviorally applicable; exact-head GitHub checks are running for this SHA, so merge remains gated on their completion.

No visual UI change is in scope. Checks: PR checks · commit

brennanb2025 and others added 3 commits August 27, 2026 00:06
Cursor requires JSON on stdout when a hook exits 0. The managed Cursor
script POSTed telemetry and printed nothing, so cursor-agent denied
every gated tool call with "returned invalid JSON" (#15462).

Print the per-event response first on both Windows and POSIX branches
(permission events: {"permission":"allow"}; everything else: {}), and
give wrapWindowsHookCommand the same missing-script fallbackStdout that
POSIX wrap already has so the launchers cannot drift.

Co-authored-by: sanshengai <269852131+sanshengai@users.noreply.github.com>
@brennanb2025
brennanb2025 force-pushed the brennanb2025/sta-4848-cursor-hook-stdout branch from a8bf650 to f390129 Compare August 27, 2026 07:09
@coderabbitai

coderabbitai Bot commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

@brennanb2025
brennanb2025 merged commit f352e3e into main Aug 27, 2026
48 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cursor agent-status hooks emit no stdout, causing "returned invalid JSON" and blocking every tool call

2 participants