- 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 portableConversion type: Not portableUnique 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. |
powershell | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | — | Each hook accepts an optional `powershell` field for Windows-specific commands; on Windows, `powershell` takes priority over `command`. On macOS/Linux, `powershell` is ignored and `command` is used. |
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 | TranslatedConversion type: TranslatedActively 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 | TranslatedConversion type: TranslatedActively 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, execution_id, timestamp, model_name, tool_info) plus event-specific data. |
json_io_protocol | TranslatedConversion type: TranslatedActively 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 | TranslatedConversion type: TranslatedActively 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, cascade_response_with_transcript, setup_worktree); pre-hooks can block via exit code 2. |
| Cloud dashboard distribution for enterprise teams | Not portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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. |