[ ABORT TO HUD ]
SEQ. 1
SEQ. 2
Hooks: Intercepting the Agent Lifecycle
Programmatic Guardrails
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.
Two Kinds of Hooks
| 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" |
Key Lifecycle Events
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 afollowup_messageto keep it iterating (loop limit defaults to 5)- Tab hooks (
beforeTabFileRead,afterTabFileEdit) - extend the same control to autocomplete
Configuration Hierarchy
Hooks are defined in hooks.json and merge across four levels - broader scopes take precedence:
- Enterprise - MDM-managed (e.g.
C:\ProgramData\Cursor\hooks.jsonon Windows) - Team - distributed from the cloud dashboard
- Project -
.cursor/hooks.json, runs from the project root - User -
~/.cursor/hooks.json
Enterprise Pattern: Security vendors ship ready-made hook integrations - Snyk, Semgrep, 1Password and others plug directly into the hook events. Cloud Agents also run your command-based project/team/enterprise hooks, so guardrails follow the agent into the cloud. Scaffold your first hook with
/create-hook.SYNAPSE VERIFICATION
QUERY 1 // 3
How does a command-based hook block an agent action?
It throws an exception
It exits with code 2
It deletes the request
It can't block actions