One change
Hooks reference
hooks
hooks Changed · +16 / -8 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 1783
Runs when Claude Code is about to ask you for permission. In sessions that can't show a prompt, such as background subagents in [non-interactive mode](/docs/en/headless), Claude Code still runs these hooks, and if no hook returns a decision, it denies the tool call. Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user. -Use this event when you need a signal the moment Claude asks for permission. The [Notification](#notification) event's `permission_prompt` type reaches you only after about 6 seconds without terminal input. +Use this event when you need a signal the moment Claude asks for permission. The [Notification](#notification) event's `permission_prompt` type reaches you only after the prompt has waited about six seconds. Matches on tool name, same values as PreToolUse.
from line 2117
| Matcher | When it fires | | :----------------------- | :--------------------------------------------------------------------------------------------------------------------- | -| `permission_prompt` | Claude needs you to approve a tool use and you haven't typed for about 6 seconds | +| `permission_prompt` | Claude needs you to approve a tool use and the prompt has waited about six seconds | | `idle_prompt` | Claude finished responding about 60 seconds ago and you haven't typed since | | `auth_success` | Authentication completes | -| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about 6 seconds | -| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about 6 seconds | +| `elicitation_dialog` | An MCP server opens an elicitation form and you haven't typed for about six seconds | +| `elicitation_url_dialog` | An MCP server asks you to open a browser URL and you haven't typed for about six seconds | | `elicitation_complete` | An MCP elicitation form is submitted or dismissed | | `elicitation_response` | An MCP elicitation response is sent back to the server | | `agent_needs_input` | A background session starts waiting on your input. Fires only while [agent view](/docs/en/agent-view) is open in a terminal |
from line 2130
The `agent_needs_input` and `agent_completed` types require Claude Code v2.1.198 or later. <Note> - The `permission_prompt`, `idle_prompt`, `elicitation_dialog`, and `elicitation_url_dialog` types share their timing with desktop notifications, so you only see them when you appear to be away from the terminal: + The `permission_prompt`, `idle_prompt`, `elicitation_dialog`, and `elicitation_url_dialog` types share their timing with desktop notifications, so in terminal sessions you only see them when you appear to be away from the terminal: - * Expect `permission_prompt` once you haven't typed for about 6 seconds. The timer starts when the permission prompt appears, and each keystroke defers it. To run a hook immediately on every permission ask, use [PermissionRequest](#permissionrequest) instead. + * Expect `permission_prompt` once you haven't typed for about six seconds. The timer starts when the permission prompt appears, and each keystroke defers it. To run a hook immediately on every permission ask, use [PermissionRequest](#permissionrequest) instead. * Expect `idle_prompt` about 60 seconds after Claude finishes responding, and only if you haven't typed since. - * Expect `elicitation_dialog` for an elicitation form, or `elicitation_url_dialog` for a browser URL request, once you haven't typed for about 6 seconds. Both share the same 6-second gate as `permission_prompt`: the timer starts when the dialog appears, and each keystroke defers it. + * Expect `elicitation_dialog` for an elicitation form, or `elicitation_url_dialog` for a browser URL request, once you haven't typed for about six seconds. Both share the same six-second gate as `permission_prompt`: the timer starts when the dialog appears, and each keystroke defers it. </Note> +Claude Code times `permission_prompt` differently in sessions where it sends permission requests to the Agent SDK's [`canUseTool` callback](/docs/en/agent-sdk/user-input), which is how Claude Desktop and the VS Code extension host Claude Code: + +* Expect `permission_prompt` about six seconds after Claude asks for permission. Claude Code doesn't defer it while you type. +* If you or a [PermissionRequest](#permissionrequest) hook answer sooner, Claude Code doesn't run `permission_prompt`. +* Set [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/en/env-vars) to `1` to turn `permission_prompt` off in these sessions. + +Before v2.1.233, `permission_prompt` didn't fire in these sessions. + Use separate matchers to run different handlers depending on the notification type. This configuration triggers a permission-specific alert script when Claude needs permission approval and a different notification when Claude has been idle: ```json theme={null}
from line 3223
Set `type` to `"agent"` and provide a `prompt` string. The configuration fields are the same as [prompt hooks](#prompt-hook-configuration), except that agent hooks have a longer default timeout and no `continueOnBlock` field: | Field | Required | Description | -| :-------- | :------- | :------------------------------------------------------------------------------------------ | -| `type` | yes | Must be `"agent"` | -| `prompt` | yes | Prompt describing what to verify. Use `$ARGUMENTS` as a placeholder for the hook input JSON | -| `model` | no | Model to use. Defaults to a fast model | -| `timeout` | no | Timeout in seconds. Default: 60 | - -The response schema is `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block. On `ok: false`, Claude Code handles an agent hook the way it handles a [prompt hook with `continueOnBlock: true`](#response-schema) on t +| :-------- | :------- | :-----------------------------------------------------------------------------