Claude Code — Hooks

File format: JSON
Discovery path: .claude/settings.json
Syllago install method: JSON merge
Symlink support: No
Config file: .claude/settings.json
Handler types: command, http, prompt, agent

Hook events

Canonical Event	Native Name	Category
`after_compact`	`PostCompact`	Context
`after_tool_execute`	`PostToolUse`	Tool
`agent_stop`	`Stop`	Lifecycle
`before_compact`	`PreCompact`	Context
`before_prompt`	`UserPromptSubmit`	Lifecycle
`before_tool_execute`	`PreToolUse`	Tool
`config_change`	`ConfigChange`	Config
`elicitation`	`Elicitation`	Interaction
`elicitation_result`	`ElicitationResult`	Interaction
`error_occurred`	`ErrorOccurred`	Lifecycle
`file_changed`	`FileChanged`	Workspace
`instructions_loaded`	`InstructionsLoaded`	Context
`notification`	`Notification`	Output
`permission_request`	`PermissionRequest`	Security
`session_end`	`SessionEnd`	Lifecycle
`session_start`	`SessionStart`	Lifecycle
`stop_failure`	`StopFailure`	Lifecycle
`subagent_start`	`SubagentStart`	Lifecycle
`subagent_stop`	`SubagentStop`	Lifecycle
`task_completed`	`TaskCompleted`	Lifecycle
`teammate_idle`	`TeammateIdle`	Collaboration
`tool_use_failure`	`PostToolUseFailure`	Tool
`worktree_create`	`WorktreeCreate`	Workspace
`worktree_remove`	`WorktreeRemove`	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
`matcher`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	—	Matcher field accepts exact strings, pipe-separated lists, or JavaScript regex; per-event fields (tool_name, source, reason, notification_type) drive matching.
`type`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	—	Hooks can be command (shell), http (POST), prompt (LLM eval), or agent (subagent); prompt/agent restricted to a subset of events.
`async`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	Command hooks with async: true run in background; decisions ignored, systemMessage delivered on next turn.
`hooks`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	Hooks defined in skill/subagent frontmatter run only while the component is active; skills also support a once: true handler flag.
`updatedInput`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	PreToolUse hooks return updatedInput to replace tool params before execution; defer (CC v2.1.89+) exits Claude for external resume via -p.
`updatedMCPToolOutput`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	PostToolUse hooks for MCP tools return updatedMCPToolOutput to filter/transform/annotate tool results before Claude sees them.
`updatedPermissions`	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	PermissionRequest hooks return updatedPermissions with addRules/replaceRules/removeRules/setMode/addDirectories entries scoped to session/local/project/user destinations.

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
`async_execution`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	hook_async_execution: async: true on command handlers runs hook in background without blocking; decisions ignored; systemMessage delivered on next turn
`context_injection`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Hooks return systemMessage field in JSON output to inject context into agent's active session
Decision Control via Exit Codes and JSON Output	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Hooks decide via exit codes (0/2/other) or JSON fields (continue, stopReason, permissionDecision, decision, updatedInput, additionalContext).
`decision_control`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	block: exit code 2 or decision=block; allow: permissionDecision=allow in hookSpecificOutput; modify: updatedInput replaces tool input before execution
`handler_types`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Four types: command (shell), http (POST to URL), prompt (LLM evaluation), agent (subagent with tools); prompt/agent restricted to subset of events
Hook Event Set	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	24 hook events spanning session, turn, and tool-call cadences (SessionStart, PreToolUse, PostToolUse, PermissionRequest, FileChanged, etc.).
Hook Scopes and Locations	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Six hook scopes: user, project, local, managed policy, plugin, and component frontmatter; managed policy can lock down the others.
`hook_scopes`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Six scopes: user (~/.claude/settings.json), project (.claude/settings.json), local (.claude/settings.local.json), managed policy, plugin (hooks/hooks.json), component frontmatter
`input_modification`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	hook_input_modification: PreToolUse returns updatedInput in hookSpecificOutput; entire input object replaced; compatible with all permissionDecision values except defer
`json_io_protocol`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Command hooks receive event JSON on stdin; respond with JSON on stdout (exit 0); structured fields: continue, stopReason, suppressOutput, systemMessage, hookSpecificOutput
`matcher_patterns`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	hook_matcher_patterns: exact string, pipe-separated list, or JavaScript regex; matches on tool_name or event-specific fields
`permission_control`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	hook_permission_update_entries: PermissionRequest hooks return updatedPermissions with addRules/replaceRules/removeRules/setMode entries
Elicitation and ElicitationResult Hooks	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	Elicitation/ElicitationResult hooks intercept MCP server input requests, returning accept/decline/cancel actions or modifying the response.
Persistent Environment Variable Propagation via CLAUDE_ENV_FILE	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	SessionStart/CwdChanged/FileChanged hooks can write export statements to $CLAUDE_ENV_FILE that persist across subsequent Bash commands.
WorktreeCreate Hook Replaces Default Git Behavior	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	WorktreeCreate hook fully replaces Claude Code's git worktree creation, returning the new worktree path; enables non-git VCS support.

Sources

Source
https://code.claude.com/docs/en/hooks.md
https://code.claude.com/docs/en/hooks-guide.md
hooks-example-hooks.json
settings-strict-example.json
settings-lax-example.json