Skip to content

fix(claude): emit {} from the managed Windows hook so Claude-hooks-compat consumers don't fail closed - #14826

Closed
OrcaWin wants to merge 1 commit into
mainfrom
fix/win-claude-hook-empty-json-stdout
Closed

OrcaWin wants to merge 1 commit into
mainfrom
fix/win-claude-hook-empty-json-stdout

Conversation

@OrcaWin

@OrcaWin OrcaWin commented Aug 16, 2026 •

Copy link
Copy Markdown
Collaborator
Files Added Deleted Net
Test 1 +30 0 +30
Prod 2 +22 −8 +14

Root cause

The managed Windows Claude hook script (claude-hook.cmd) never writes anything to stdout on any path: the three env guards (ORCA_AGENT_HOOK_PORT/TOKEN/ORCA_PANE_KEY missing) exit silently, and the curl POST that reports the event to Orca is redirected to >nul 2>&1.

I checked the current hook documentation (code.claude.com/docs/en/hooks) for what that means: exit 0 with empty stdout is explicitly documented as a pass-through — "the hook has no decision to report, so the tool call continues through the normal permission flow." An empty JSON object {} is documented to mean the same thing for every event, including the permission-decision ones (PreToolUse, PermissionRequest): none of the decision fields (decision, hookSpecificOutput, permissionDecision) are set, so it's treated as "no decision," identically to no output at all. So for real Claude Code, "write nothing" and "write {}" are the same thing.

cursor-agent's third-party Claude-hooks-compat layer doesn't implement that convention. It treats PreToolUse as a permission hook that must return a JSON verdict, and empty stdout is invalid JSON to its parser — so it fails closed:

Error: Hook "C:\Windows\System32\conhost.exe" returned invalid JSON. The command was blocked for safety.

Every shell command in every cursor-agent session on Windows gets blocked, since Orca's own managed hook is registered on PreToolUse with matcher *.

Why this is the root-cause fix, not a workaround

Orca doesn't control cursor-agent's parser — there's no fix available there. What Orca does control is its own hook script, and that script currently relies on an implicit convention ("nothing on stdout means no opinion") instead of stating that opinion explicitly. {} is a valid, schema-passing JSON object with no fields set. By the documented contract, it is indistinguishable from no output for real Claude Code — so emitting it is not a behavior change for Claude Code itself. It just makes Orca's script an explicit, spec-compliant "no decision" instead of an implicit one, which happens to also be exactly what a strict but spec-following third-party consumer needs to not choke.

Fix

Added emitEmptyJsonStdout as an opt-in option (default false, unchanged behavior) on the two shared helpers in hook-stdin-contract.ts:

  • buildWindowsHookEnvironmentGuardLines({ emitEmptyJsonStdout: true }) — each of the three env guards becomes if "%VAR%"=="" (echo {}& exit /b 0) instead of if "%VAR%"=="" exit /b 0.
  • buildWindowsHookStdinDrainEpilogue({ emitEmptyJsonStdout: true }) — the stdin-drain epilogue (used both as the normal tail and as the Devin-skip landing point) emits echo {} before its exit /b 0.

Wired both into getManagedScript('local', ...) in hook-service.ts for the Claude .cmd, plus one echo {} before the main success-path exit /b 0 after the curl POST. That covers every exit path: the three early guards, the Devin-skip drain, and the normal success path.

The POSIX .sh branch and the statusline script are untouched — the statusline's stdout is the literal status line text shown in the UI, so emitting {} there would show {} in the UI. That script is not affected by any change in this PR.

Scope

The two shared helpers are used by seven other agent hook services (Grok, Gemini, Droid, Devin, Cursor's own installer, Command Code, Codex, Antigravity). None of them were reported to have this problem, and none of them call the new option — the default keeps their generated scripts byte-for-byte identical to before this PR. Verified by running each of their test suites (see below); only Claude's own test file changes shape.

Testing

  • npx tsc --noEmit -p config/tsconfig.node.json — clean.
  • hook-service.test.ts — 15/15 pass, including a new regression test asserting {} is emitted from every exit path of the generated .cmd (all three guards, the success path, and the drain epilogue).
  • Ran the full test suites for every other consumer of the shared helpers (antigravity, command-code, droid, devin, cursor, gemini, grok, codex, plus statusline-script.test.ts) — same 14 pre-existing failures as origin/main with no changes applied (codex-session-resume-home path tests + one Devin POSIX-assertion test, both environmental/pre-existing, unrelated to hook-stdin-contract.ts), confirming the opt-in default didn't regress any of them.
  • Confirmed curl's own stdout/stderr is redirected to nul (buildWindowsAgentHookCurlPostCommand), so echo {} really is the only thing written to the script's stdout — no risk of the HTTP response body contaminating the JSON a consumer parses.

Fixes #14818

…mpat consumers don't fail closed

#13443's managed Windows Claude hook never writes to stdout: the env
guards exit silently, and the curl POST is redirected to `>nul`. Real
Claude Code's documented contract treats that as "no decision" and lets
the tool call proceed - confirmed against the current hook docs, which
describe exit 0 with empty stdout as a pass-through, and an all-fields-
absent JSON object as functionally identical to no output at all for every
event, including the permission-decision ones (PreToolUse,
PermissionRequest).

cursor-agent's third-party Claude-hooks-compat layer doesn't implement
that "silence is fine" convention: it treats PreToolUse as a permission
hook that must return a JSON verdict, and empty stdout is invalid JSON to
it, so it fails closed - every shell command blocked with "Hook ...
returned invalid JSON" (#14818).

Orca can't fix a third-party consumer's parser. What it can fix is that
its own hook script relies on an implicit convention ("nothing on stdout
== no opinion") instead of stating that opinion explicitly. `{}` is a
valid, schema-passing JSON object with none of the decision fields set -
by the documented contract, indistinguishable from no output for real
Claude Code - so emitting it is not a behavior change for Claude, and it
gives any spec-following third-party consumer a parseable "no decision"
instead of nothing to choke on.

Added `emitEmptyJsonStdout` as an opt-in option on the shared
`buildWindowsHookEnvironmentGuardLines`/`buildWindowsHookStdinDrainEpilogue`
helpers (default off, unchanged behavior) and wired it into every exit path
of the Claude .cmd - the three env guards, the main success path after the
curl POST, and the Devin-skip stdin-drain epilogue - so no path can still
emit nothing. Left every other consumer of these shared helpers (Grok,
Gemini, Droid, Devin, Cursor's own installer, Command Code, Codex,
Antigravity) on the default, since none of them were reported to have this
problem and broadening the change would be an unrequested behavior change
for agents that don't need it.

Fixes #14818
@coderabbitai

coderabbitai Bot commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Windows hook environment guards and stdin-drain epilogues now accept an emitEmptyJsonStdout option. Claude Windows hooks enable this option and emit {} before successful exits, including missing-environment, curl-completion, and stdin-drain paths. A Windows-only regression test verifies the generated .cmd script, output behavior, exit status, and cleanup.

Merge Risk: ⚪ Minimal · up to b5365

This change emits valid empty JSON for the managed Windows hook without altering the intended permission behavior. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. 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 identifies the Windows Claude hook change and its purpose for Claude-hooks-compatible consumers.
Description check ✅ Passed The description explains the root cause, fix, scope, linked issue, and testing, although it does not reproduce every template heading.
Linked Issues check ✅ Passed The changes satisfy issue #14818 by emitting valid JSON from every Windows Claude hook exit path while preserving existing pass-through behavior.
Out of Scope Changes check ✅ Passed The changes remain within scope and limit the new behavior to the managed Windows Claude hook; other consumers and scripts retain existing behavior.
✨ 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.

🧹 Nitpick comments (1)
src/main/claude/hook-service.ts (1)

72-74: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reduce the duplicated multi-line rationale. Keep one concise comment at each site. The issue reference can remain.

  • src/main/claude/hook-service.ts#L72-L74: replace the three-line compatibility explanation with one short rationale.
  • src/main/claude/hook-service.test.ts#L403-L406: replace the four-line test rationale with one short test-intent comment.

As per coding guidelines, “Comments must be concise, non-obvious, and brief—prefer one line; do not explain obvious behavior or walk through code.”

Source: Coding guidelines


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e733bc19-892a-48c1-ab99-1467d3bba281

📥 Commits

Reviewing files that changed from the base of the PR and between 93ab6e1 and b536500.

📒 Files selected for processing (3)
  • src/main/agent-hooks/hook-stdin-contract.ts
  • src/main/claude/hook-service.test.ts
  • src/main/claude/hook-service.ts

@OrcaWin

OrcaWin commented Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

Superseding this with #14825, which now carries the {} fix. Closing rather than merging, for two substantive reasons found while re-reviewing both PRs together.

1. This fix cannot work on its own. The {} written here never reaches any consumer, because the shipped conhost.exe --headless wrapper swallows stdout. Measured directly on Windows 11:

conhost --headless cmd /d /c "echo HELLO& exit /b 42"   → stdout: (empty)   exit code: (none)
powershell -WindowStyle Hidden -EncodedCommand …        → stdout: HELLO     exit code: 42

conhost --headless implements the ConPTY server protocol — it doesn't wait for the hosted process and relays neither exit code nor stdout. So merging this alone would have produced a green test suite, a closed issue, and a still-broken cursor-agent. Removing conhost is #14825's change, which is why the two had to land together.

2. The emission strategy here misses a path and can drift. This PR adds emitEmptyJsonStdout to two shared helpers in hook-stdin-contract.ts and enumerates five emission sites (three env guards, the success path, the drain epilogue). #14825 instead emits {} once as the script's first line, which:

  • covers every exit path by construction, so a future path can't miss it;
  • guarantees {} is the first non-whitespace byte on stdout, which matters — the hooks docs specify stdout is parsed as JSON only when it starts with {;
  • needs no change to a module shared by eight other agents, keeping their scripts byte-identical without an opt-in flag;
  • covers the POSIX .sh branch too. cursor-agent imports ~/.claude/settings.json on macOS and Linux as well, so the Windows-only scope here left the same bug reachable there.

There was also a third gap neither PR caught: the launcher's own missing-script fallback returns empty stdout without ever entering the script, reproducing #14818 whenever ~/.orca is cleaned or an install is half-finished. #14825 fixes that too, and adds a regression test that executes the real registered command through both cmd.exe and Git Bash — verified to fail if conhost --headless is reintroduced.

The analysis in this PR's description was sound and is carried over; only the mechanism changed. #14818 is fixed by #14825.

@OrcaWin OrcaWin closed this Aug 16, 2026
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.

[Bug]: Windows shell command failures

1 participant