Cursor hooks: verify the event names and output schema against the current Cursor hooks documentation
Problem
The Cursor hook configuration in this repository (.cursor/hooks.json and .cursor/hooks.windows.json) was written against an early hooks preview. Cursor's current documentation at https://cursor.com/docs/agent/hooks describes a different surface, and two of our four hooks do not exist in that shape:
- There is no
userPromptSubmitevent. The prompt-time event isbeforeSubmitPrompt, and its output is onlycontinueanduser_message; it cannot inject context. The events that can inject context aresessionStart(additional_context, added to the conversation's initial context) andpostToolUse(additional_context, injected after the tool result). preToolUseanswers withpermission("allow"or"deny"), notdecision. The docs state that invalid JSON or a response that does not match the hook's schema blocks the action, so{"decision": "allow"}may block instead of allowing.stopstill answers withfollowup_message, which matches our stop hooks.sessionEnd,preCompact(user_messageoutput) andafterFileEditexist as well.
This was not verified against a running Cursor build, only against the documentation as of 2026-09-17. Pre-existing since the hooks were added in v2.23.1; PR #251 (Windows named-plan resolution) does not change the event names or the output shape, and its shared resolve-plan-context.ps1 helper is what a corrected set of hooks would reuse.
What a fix looks like
- Confirm the behaviour in a current Cursor build: does
userPromptSubmitfire at all, and does{"decision": "allow"}frompreToolUseblock the tool? - If the documentation is right, move the plan injection to
sessionStart(additional_contextwith the same framed plan block the other routes inject), keep the write reminder aspostToolUseadditional_context, keepstopwithfollowup_message, and considerpreCompactfor the flush-progress reminder. MakepreToolUsereturn{"permission": "allow"}or drop it (Cursor'spreToolUsecannot inject context, so the 30-line recitation has no channel there). - Keep both twins (
.shand.ps1) in step and keepPLANNING_DISABLED=1,PLAN_ID,PWF_PLAN_ROOTand the fail-closed rules fromresolve-plan-context.ps1. - Update
docs/cursor.mdand the tests undertests/test_cursor_*.pyto the confirmed schema.
Scope
Cursor only. No other host reads these files. Anyone with a current Cursor install who can run the two checks in step 1 would unblock this; a comment with the observed behaviour is enough to start.
Source: OthmanAdi/planning-with-files