| allowedEnvVars |
string |
|
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 |
|
docs ↗
|
| args |
string |
|
Argument list. When present, `command` is resolved as an executable and spawned directly with `args` as the argument vector, with no shell involved. See Exec form and shell form |
|
docs ↗
|
| async |
string |
|
If `true`, runs in the background without blocking. See Run hooks in the background |
|
docs ↗
|
| asyncRewake |
string |
|
If `true`, runs in the background and wakes Claude on exit code 2. Implies `async`. The hook's stderr, or stdout if stderr is empty, is shown to Claude as a system reminder so it can react to a long-running background failure |
|
docs ↗
|
| command |
string |
yes |
Shell command to execute. With `args`, the executable to spawn directly. See Exec form and shell form |
|
docs ↗
|
| headers |
string |
|
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 |
|
docs ↗
|
| if |
string |
|
Permission rule syntax to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook command only runs if the tool call matches the pattern. See the Bash matching table below for how Bash patterns evaluate against su... |
|
docs ↗
|
| input |
string |
|
Arguments passed to the tool. String values support `${path}` substitution from the hook's JSON input, such as `"${tool_input.file_path}"` |
|
docs ↗
|
| model |
string |
|
Model to use for evaluation. Defaults to a fast model |
|
docs ↗
|
| once |
string |
|
If `true`, runs once per session then is removed. Only honored for hooks declared in skill frontmatter; ignored in settings files and agent frontmatter |
|
docs ↗
|
| prompt |
string |
yes |
Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON. Escape with a backslash to include literal text: `\$1.00` renders as `$1.00` |
|
docs ↗
|
| server |
string |
yes |
Name of a configured MCP server. For a plugin-bundled server, this is the scoped name `plugin:<plugin-name>:<server-name>`, such as `plugin:my-plugin:db`, not the bare server key. The server must already be connected; the hook never trig... |
|
docs ↗
|
| shell |
string |
|
Shell to use for this hook. Accepts `"bash"` or `"powershell"`. Defaults to `"bash"`, or to `"powershell"` on Windows when Git Bash isn't installed. Setting `"powershell"` runs the command via PowerShell on Windows. Does not require `CLA... |
|
docs ↗
|
| statusMessage |
string |
|
Custom spinner message displayed while the hook runs |
|
docs ↗
|
| timeout |
string |
|
Seconds before canceling. Defaults: 600 for `command`, `http`, and `mcp_tool`; 30 for `prompt`; 60 for `agent`. `UserPromptSubmit` lowers the `command`, `http`, and `mcp_tool` default to 30, and `MessageDisplay` lowers it to 10 |
|
docs ↗
|
| tool |
string |
yes |
Name of the tool to call on that server |
|
docs ↗
|
| type |
string |
yes |
`"command"`, `"http"`, `"mcp_tool"`, `"prompt"`, or `"agent"` |
|
docs ↗
|
| url |
string |
yes |
URL to send the POST request to |
|
docs ↗
|