Gemini CLI — Hooks
- File format
- JSON
- Discovery path
.gemini/settings.json- Syllago install method
- JSON merge
- Symlink support
- No
- Config file
.gemini/settings.json- Handler types
command
Hook events
| Canonical Event | Native Name | Category |
|---|---|---|
after_model | AfterModel | Model |
after_tool_execute | AfterTool | Tool |
agent_stop | AfterAgent | Lifecycle |
before_compact | PreCompress | Context |
before_model | BeforeModel | Model |
before_prompt | BeforeAgent | Lifecycle |
before_tool_execute | BeforeTool | Tool |
before_tool_selection | BeforeToolSelection | Model |
notification | Notification | Output |
session_end | SessionEnd | Lifecycle |
session_start | SessionStart | Lifecycle |
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 |
|---|---|---|---|
hooks | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | — | Eleven lifecycle events configured per-event in settings.json under the hooks key: BeforeTool, AfterTool, BeforeAgent, AfterAgent, BeforeToolSelection, BeforeModel, AfterModel, SessionStart, SessionEnd, PreCompress, and Notification. |
matcher | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | — | Optional matcher field filters which tools or triggers fire a hook, using regex for tool events and exact strings for lifecycle events. |
sequential | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost.Learn more → | — | Boolean flag on a hook group that switches execution from parallel (default) to ordered, in-sequence runs. |
hookSpecificOutput | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | — | Per-event hookSpecificOutput fields (tool_input, additionalContext, clearContext, llm_request, toolConfig, etc.) extending the common output schema. |
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 |
|---|---|---|
decision_control | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | exit_code_semantics: Gemini CLI uses exit codes to signal block (non-zero) or allow (zero) decisions; no modify sub-capability documented |
json_io_protocol | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | hook_io_protocol: Gemini CLI hooks receive event data as JSON on stdin and return structured JSON responses on stdout |
matcher_patterns | TranslatedConversion type: TranslatedActively mapped to the target provider’s equivalent field during conversion.Learn more → | hook_matchers: Gemini CLI hooks support event and tool name matching to filter when hooks fire |
| Exit code semantics | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Three-tier exit code contract — 0 parses stdout as JSON, 2 blocks the action with stderr as reason, any other code is a non-fatal warning. |
| In-session hook management commands | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | /hooks slash commands (panel, enable-all, disable-all, enable, disable) toggle individual hooks or the whole system at runtime. |
| Project hook fingerprinting | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Project hooks are fingerprinted; changed name or command requires user re-approval before execution as a trust safeguard. |
| stdin/stdout JSON I/O protocol | Not portableConversion type: Not portableUnique to this provider — can’t be carried across providers.Learn more → | Hooks receive event JSON on stdin and return decision/reason/systemMessage JSON on stdout; stderr is safe for debug logs. |