Cursor — Hooks

File format: JSON
Discovery path: .cursor/settings.json
Syllago install method: JSON merge
Symlink support: No
Config file: .cursor/settings.json
Handler types: command

Hook events

Canonical Event	Native Name	Category
`after_model`	`afterAgentResponse`	Model
`after_tool_execute`	`PostToolUse`	Tool
`agent_stop`	`Stop`	Lifecycle
`before_compact`	`PreCompact`	Context
`before_model`	`beforeAgentResponse`	Model
`before_prompt`	`UserPromptSubmit`	Lifecycle
`before_tool_execute`	`PreToolUse`	Tool
`before_tool_selection`	`beforeToolSelection`	Model
`file_changed`	`afterFileEdit`	Workspace
`session_end`	`SessionEnd`	Lifecycle
`session_start`	`SessionStart`	Lifecycle
`subagent_start`	`SubagentStart`	Lifecycle
`subagent_stop`	`SubagentStop`	Lifecycle
`tool_use_failure`	`postToolUseFailure`	Tool

Features

How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.

Fields

Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.

Provider field	Conversion	Canonical key	Summary
`type`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	—	Command-based hooks execute shell scripts that receive JSON via stdin; exit code 0 indicates success and exit code 2 blocks actions.
`failClosed`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	Matcher groups may set failClosed to treat hook failures as blocking (alias for the blocking semantic) rather than non-fatal warnings.
`loop_limit`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	Matcher groups may bound how many times the hook fires within a loop to guard against runaway tool sequences.
`statusMessage`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	Hooks may surface a short camelCase statusMessage to the agent to explain a decision or provide feedback.
`timeout`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	Hook entries accept a timeout in milliseconds that limits how long a command may run before being terminated.

Other features

Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.

Feature	Conversion	Summary
`context_injection`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Hooks can inject context at session initialization via the sessionStart event, enabling custom context to be added to the agent's active session at startup.
Cursor hook event set	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Cursor documents lifecycle events for both Agent (sessionStart, preToolUse, beforeShellExecution, afterFileEdit, stop, and related pre/post tool hooks) and Cursor Tab inline completions (beforeTabFileRead and related Tab-specific hooks).
`decision_control`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Exit codes drive decisions: exit code 2 blocks the action, exit code 0 allows it to proceed; JSON on stdout can also return structured decision fields.
`handler_types`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Two handler types documented: command (shell scripts communicating over stdio via JSON) and prompt (LLM-evaluated natural language conditions for policy enforcement without custom scripting).
`hook_scopes`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Four scopes documented in priority order: Enterprise (system-wide MDM-managed), Team (cloud-distributed for Enterprise plans), Project (.cursor/hooks/ in the repository), and User (global personal configuration at ~/.cursor/hooks/).
`json_io_protocol`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Command hooks receive event data as JSON on stdin and may return structured JSON on stdout to signal decisions and supply output fields.
`matcher_patterns`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Hook entries accept a matcher string that filters which tool or event fires the hook (for example a specific shell command or tool name).
Cursor Tab inline completion hooks	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Separate hook events (e.g., beforeTabFileRead) fire for Cursor Tab inline completion operations, distinct from Agent hook events, enabling separate control policies for inline vs. Agent-mode completions.
Enterprise and Team hook scopes	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Cursor supports Enterprise (MDM-managed system-wide) and Team (cloud-distributed for Enterprise plans) hook scopes above the Project and User levels, enabling organization-wide hook policy deployment.
Hooks wired through .cursor/settings.json	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Hook files under .cursor/hooks/ are activated via entries in .cursor/settings.json; enabling or disabling a hook means editing the settings file, not moving the hook file itself.
Partner ecosystem hooks	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Cursor partners with ecosystem vendors (MintMCP, Semgrep, Snyk, 1Password, and others) who have built pre-built hook integrations covering security scanning, governance, and secrets management.
Prompt (LLM) handler type	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Prompt-based hooks leverage an LLM to evaluate natural language conditions, enabling policy enforcement without custom scripting — the model determines whether to allow or block based on a natural language rule.

Sources

Source
https://cursor.com/docs/hooks