49 * `prompt`: (For `type: "prompt"`) The prompt to send to the LLM for evaluation49 * `prompt`: (For `type: "prompt"`) The prompt to send to the LLM for evaluation
50 * `timeout`: (Optional) How long a hook should run, in seconds, before canceling that specific hook50 * `timeout`: (Optional) How long a hook should run, in seconds, before canceling that specific hook
51 51
52For events like `UserPromptSubmit`, `Notification`, `Stop`, and `SubagentStop`52For events like `UserPromptSubmit`, `Stop`, and `SubagentStop`
53that don't use matchers, you can omit the matcher field:53that don't use matchers, you can omit the matcher field:
54 54
55```json theme={null}55```json theme={null}
289* `Write` - File writing289* `Write` - File writing
290* `WebFetch`, `WebSearch` - Web operations290* `WebFetch`, `WebSearch` - Web operations
291 291
292Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, or ask for permission to use the tool.
293
294### PermissionRequest
295
296Runs when the user is shown a permission dialog.
297Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user.
298
299Recognizes the same matcher values as PreToolUse.
300
292### PostToolUse301### PostToolUse
293 302
294Runs immediately after a tool completes successfully.303Runs immediately after a tool completes successfully.
297 306
298### Notification307### Notification
299 308
300Runs when Claude Code sends notifications. Notifications are sent when:309Runs when Claude Code sends notifications. Supports matchers to filter by notification type.
301 310
3021. Claude needs your permission to use a tool. Example: "Claude needs your311**Common matchers:**
303 permission to use Bash"312
3042. The prompt input has been idle for at least 60 seconds. "Claude is waiting313* `permission_prompt` - Permission requests from Claude Code
305 for your input"314* `idle_prompt` - When Claude is waiting for user input (after 60+ seconds of idle time)
315* `auth_success` - Authentication success notifications
316* `elicitation_dialog` - When Claude Code needs input for MCP tool elicitation
317
318You can use matchers to run different hooks for different notification types, or omit the matcher to run hooks for all notifications.
319
320**Example: Different notifications for different types**
321
322```json theme={null}
323{
324 "hooks": {
325 "Notification": [
326 {
327 "matcher": "permission_prompt",
328 "hooks": [
329 {
330 "type": "command",
331 "command": "/path/to/permission-alert.sh"
332 }
333 ]
334 },
335 {
336 "matcher": "idle_prompt",
337 "hooks": [
338 {
339 "type": "command",
340 "command": "/path/to/idle-notification.sh"
341 }
342 ]
343 }
344 ]
345 }
346}
347```
306 348
307### UserPromptSubmit349### UserPromptSubmit
308 350
468 "cwd": "/Users/...",510 "cwd": "/Users/...",
469 "permission_mode": "default",511 "permission_mode": "default",
470 "hook_event_name": "Notification",512 "hook_event_name": "Notification",
471 "message": "Task completed successfully"513 "message": "Claude needs your permission to use Bash",
514 "notification_type": "permission_prompt"
472}515}
473```516```
474 517
625 668
626Additionally, hooks can modify tool inputs before execution using `updatedInput`:669Additionally, hooks can modify tool inputs before execution using `updatedInput`:
627 670
628* `updatedInput` allows you to modify the tool's input parameters before the tool executes. This is a `Record<string, unknown>` object containing the fields you want to change or add.671* `updatedInput` allows you to modify the tool's input parameters before the tool executes.
629* This is most useful with `"permissionDecision": "allow"` to modify and approve tool calls.672* This is most useful with `"permissionDecision": "allow"` to modify and approve tool calls.
630 673
631```json theme={null}674```json theme={null}
648 `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.691 `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.
649</Note>692</Note>
650 693
694#### `PermissionRequest` Decision Control
695
696`PermissionRequest` hooks can allow or deny permission requests shown to the user.
697
698* For `"behavior": "allow"` you can also optionally pass in an `"updatedInput"` that modifies the tool's input parameters before the tool executes.
699* For `"behavior": "deny"` you can also optionally pass in a `"message"` string that tells the model why the permission was denied, and a boolean `"interrupt"` which will stop Claude.
700
701```json theme={null}
702{
703 "hookSpecificOutput": {
704 "hookEventName": "PermissionRequest",
705 "decision": {
706 "behavior": "allow",
707 "updatedInput": {
708 "command": "npm run lint"
709 }
710 }
711 }
712}
713```
714
651#### `PostToolUse` Decision Control715#### `PostToolUse` Decision Control
652 716
653`PostToolUse` hooks can provide feedback to Claude after tool execution.717`PostToolUse` hooks can provide feedback to Claude after tool execution.
