Hooks

Hooks are event-driven automation scripts triggered by AI tool lifecycle events. They let you run custom logic when specific events occur — before or after a tool call, on session start, on file change, and so on.

Supported by Claude Code, Gemini CLI, Copilot CLI, Cursor, Windsurf, Codex, Cline, and Kiro.

Canonical format

Syllago uses a provider-neutral canonical format for hooks, defined by the Hook Interchange Format Specification.

Handler types

Hooks support four handler types:

Type	Description
`command`	Shell command executed as a subprocess
`http`	HTTP POST to a URL
`prompt`	LLM-evaluated logic (not all providers support this)
`agent`	Delegated to an agent subprocess

Event names (canonical)

Hook events use provider-neutral names in the canonical format. The table below lists events supported by both Claude Code and Gemini CLI; see the Hook Event Matrix for every canonical event across all providers.

Canonical Event	Claude Code	Gemini CLI
`after_tool_execute`	`PostToolUse`	`AfterTool`
`agent_stop`	`Stop`	`AfterAgent`
`before_compact`	`PreCompact`	`PreCompress`
`before_prompt`	`UserPromptSubmit`	`BeforeAgent`
`before_tool_execute`	`PreToolUse`	`BeforeTool`
`notification`	`Notification`	`Notification`
`session_end`	`SessionEnd`	`SessionEnd`
`session_start`	`SessionStart`	`SessionStart`

Syllago translates event names automatically when converting between providers.

Matcher types

Hooks use matchers to target specific tools or events:

Bare string: Tool vocabulary lookup (e.g., "shell", "file_read")
Pattern object: Regex on tool name ({"pattern": "file_(read|write|edit)"})
MCP object: Server+tool targeting ({"mcp": {"server": "github", "tool": "create_issue"}})
Array: OR logic across multiple matchers

Exit code contract

Code	Meaning
`0`	Success — parse JSON output
`1`	Non-blocking warning
`2`	Block action (only if `blocking: true`)
Other	Treated as warning

Provider support

Provider	Hook Support	Notes
Claude Code	Full	Richest output contract, all event types
Gemini CLI	Full	Unique events: `before_model`, `after_model`, `before_tool_selection`
Copilot CLI	Full	Conservative safety design
Cursor	Yes	JSON merge into `.cursor/settings.json`
Windsurf	Yes	JSON merge
Codex	Yes	JSON hooks in `.codex/hooks.json`
Cline	Yes	File-based executables in `.clinerules/hooks/`
Kiro	Yes	Embedded in agent JSON files
Zed, Roo Code, OpenCode, Amp	No	—

Hook security

Syllago includes a hook security scanner that detects dangerous patterns when converting hooks:

Risk Level	Patterns Detected
High	`curl`, `rm -rf`, piped execution, network commands
Medium	Broad matchers, wildcard patterns
Low	System paths, environment variable access

Security warnings appear in syllago convert and syllago install output.

Portability warnings

When converting hooks between providers, syllago surfaces warnings for:

Unsupported events: e.g., Gemini’s before_model has no Claude Code equivalent
Capability mismatches: e.g., updated_input (input rewriting) not supported by target
Degradation applied: hooks that use the block, warn, or exclude degradation strategy