Claude Code Hooks
Map of hook event names to arrays of matcher groups. Each matcher group optionally filters by a regex pattern and contains an array of hook handlers that execute when the event fires.
| Type | object |
|---|---|
| Schema URL | https://catalog.lintel.tools/schemas/claude-code/hooks/latest.json |
Validate with Lintel
npx @lintel/lintel checkMap of hook event names to arrays of matcher groups. Each matcher group optionally filters by a regex pattern and contains an array of hook handlers that execute when the event fires.
Properties
Definitions
A matcher group pairs an optional regex filter with an array of hook handlers. If matcher is omitted, the hooks fire on every occurrence of the event. See matcher patterns.
Regex pattern to filter when this group's hooks fire. Use | for OR (e.g. Edit|Write), .* for wildcards (e.g. mcp__.*). MCP tools follow the pattern mcp__<server>__<tool>. Omit to match all occurrences.
Runs a shell command or script. The command receives hook context as JSON on stdin, including session_id, transcript_path, cwd, permission_mode, hook_event_name, and event-specific fields. Exit 0: success — stdout is parsed as JSON for decision control. Exit 2: blocking error — stderr is fed back to Claude. Other exit codes: non-blocking error, logged in verbose mode.
Shell command or script path to execute. Runs in the project's working directory. Use $CLAUDE_PROJECT_DIR for the project root (always quote it: "$CLAUDE_PROJECT_DIR"/path) and ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths.
Max execution time in seconds.
Custom spinner message displayed while the hook runs.
Run in background without blocking. Only supported for PostToolUse and PostToolUseFailure events. Async hooks cannot block or return decisions. See async hooks.
Run once per session then remove. Primarily useful in skill-scoped hooks.
Sends the event's JSON input as an HTTP POST request to a URL. The endpoint communicates results back through the response body using the same JSON output format as command hooks. Non-2xx responses, connection failures, and timeouts produce non-blocking errors. To block a tool call or deny a permission, return a 2xx response with a JSON body containing the appropriate decision fields. HTTP hooks must be configured by editing settings JSON directly — the /hooks interactive menu only supports command hooks.
URL to send the POST request to. Must match an entry in allowedHttpHookUrls if that setting is configured.
Additional HTTP headers as key-value pairs. Values support environment variable interpolation using $VAR_NAME or ${VAR_NAME} syntax. Only variables listed in allowedEnvVars are resolved; references to unlisted variables are replaced with empty strings.
List of environment variable names that may be interpolated into header values. References to unlisted variables are replaced with empty strings. Required for any env var interpolation to work.
Max execution time in seconds.
Custom spinner message displayed while the hook runs.
Run once per session then remove. Primarily useful in skill-scoped hooks.
Evaluates a single-turn LLM prompt-based hook to make a pass/fail decision. A small, fast model receives the prompt and must respond with {ok: true} to allow the action, or {ok: false, reason: "explanation"} to block it. Cannot use tools — decides based solely on the prompt content.
The evaluation prompt sent to the LLM. Use $ARGUMENTS to interpolate the hook's full input context as JSON (includes session_id, cwd, tool_name, tool_input, and other event-specific fields). If $ARGUMENTS is not present, input JSON is appended to the prompt.
Model for evaluation. Defaults to a fast model for low latency.
Max execution time in seconds.
Custom spinner message displayed while the hook runs.
Run once per session then remove. Primarily useful in skill-scoped hooks.
Runs a multi-turn LLM agent-based hook that can use tools (Read, Grep, Glob, Bash, etc.) to gather additional context before making a decision. Unlike prompt hooks, agent hooks can explore the codebase and run commands to verify conditions. Must respond with {ok: true} or {ok: false, reason: "explanation"}.
The verification prompt sent to the agent. Use $ARGUMENTS to interpolate the hook's full input context as JSON. The agent can then use tools to investigate further before deciding. If $ARGUMENTS is not present, input JSON is appended to the prompt.
Model for the agent. Defaults to a fast model.
Max execution time in seconds.
Custom spinner message displayed while the hook runs.
Run once per session then remove. Primarily useful in skill-scoped hooks.