- File format
- JSON
- Syllago install method
- JSON merge
- Symlink support
- No
- Config file
-
.windsurf/hooks.json - Handler types
-
command
Hook events
| Canonical Event | Native Name | Category |
agent_stop | post_cascade_response | Lifecycle |
before_prompt | pre_user_prompt | Lifecycle |
session_end | session_end | Lifecycle |
session_start | session_start | Lifecycle |
transcript_export | post_cascade_response_with_transcript | Output |
worktree_create | post_setup_worktree | Workspace |
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 |
|---|
post_cascade_response_with_transcript | Not portable
Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | — | A transcript-aware post-response hook variant writes structured JSONL to ~/.windsurf/transcripts/ and delivers the file path instead of inline markdown. |
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 |
|---|
hook_scopes | Translated
Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | three_config_scopes: global (user-wide), workspace, and managed/enterprise hook configuration scopes |
| JSON context delivered via stdin | Translated
Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Each hook receives a JSON object on stdin with common fields (agent_action_name, trajectory_id, tool_info) plus event-specific data. |
json_io_protocol | Translated
Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | json_stdin_context: Windsurf hooks receive event context as JSON on stdin |
| Twelve hook event types | Translated
Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Twelve named event types span the agent lifecycle (pre/post read, write, run, mcp_tool_use, user_prompt, cascade_response, setup_worktree); pre-hooks can block via exit code 2. |
| Cloud dashboard distribution for enterprise teams | Not portable
Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Enterprise teams configure hooks via the Windsurf Team Settings dashboard, distributed to all members and merged ahead of local scopes. |
| System, user, and workspace config scopes merged in order | Not portable
Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more → | Hook JSON files load from system, user, and workspace scopes (plus optional cloud dashboard) and merge in a fixed precedence order. |