Hooks let you observe, control, and extend the agent loop with your own logic. A hook is a script (or an LLM prompt) that fires at defined lifecycle events — perfect for security scanning, policy enforcement, audit logging, and code formatting.
| Kind | How It Works | Example |
|---|---|---|
| Command-based | Runs your script; JSON in/out over stdio; exit code 2 blocks the action | Run Semgrep on every file edit |
| Prompt-based | An LLM evaluates your natural-language policy | "Block any shell command that deletes files outside the repo" |
beforeShellExecution / afterShellExecution — gate or audit terminal commandsbeforeMCPExecution — control MCP tool calls before they runbeforeReadFile / afterFileEdit — redact secrets on read, auto-format on writebeforeSubmitPrompt, sessionStart / sessionEnd — inject context, log usagestop — inspect the agent's final state and optionally send a followup_message to keep it iterating (loop limit defaults to 5)beforeTabFileRead, afterTabFileEdit) — extend the same control to autocompleteHooks are defined in hooks.json and merge across four levels — broader scopes take precedence:
C:\ProgramData\Cursor\hooks.json on Windows).cursor/hooks.json, runs from the project root~/.cursor/hooks.json/create-hook.