One change
Automate actions with hooks
hooks-guide
Nearest release: v2.1.243, published under an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
hooks-guide Changed · +35 / -30 lines
from line 177
The empty `matcher` fires on all notification types. To fire only on specific events, set it to one of these values: -| Matcher | Fires when | -| :----------------------- | :------------------------------------------------------------------------------------------------------- | -| `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 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 | -| `agent_completed` | A background session finishes or fails. Fires only while [agent view](/docs/en/agent-view) is open | +| Matcher | Fires when | +| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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 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 | +| `agent_completed` | A background session finishes or fails. Fires only while [agent view](/docs/en/agent-view) is open | +| `quota_auto_resume_fired` | Claude Code continues your task after a claude.ai usage limit paused it: at the reset, or sooner when something you do in Claude Code during the wait, such as adding usage credits, upgrading your plan, or switching models, makes usage available again, with the [model-setting exception](/docs/en/interactive-mode#wait-for-a-usage-limit-to-reset) | +| `quota_auto_resume_stale` | A claude.ai usage limit reset while your computer slept for more than about 30 minutes. Claude Code waits for you to press `Enter` instead of continuing. After a shorter sleep it continues and fires `quota_auto_resume_fired` instead | +| `quota_auto_resume_disabled` | Claude Code ends its wait for a claude.ai usage limit without continuing your task: [`autoContinueAtUsageLimit`](/docs/en/settings-reference#autocontinueatusagelimit) turned off or the reset moved more than 24 hours away during a wait Claude Code started on its own, the continued task kept hitting the limit, or the continuation was blocked before it reached the model. Doesn't fire when you press `Esc` or `Ctrl+C`, or pick **Don't continue automatically** | Claude Code times `permission_prompt` differently in a terminal and in Claude Desktop, the VS Code extension, and other hosts that answer permission requests through the Agent SDK. See [when each notification type fires](/docs/en/hooks#notification) for both timings. The `agent_needs_input` and `agent_completed` matchers require Claude Code v2.1.198 or later. +The `quota_auto_resume_fired`, `quota_auto_resume_stale`, and `quota_auto_resume_disabled` matchers require Claude Code v2.1.234 or later. + Type `/hooks` and select `Notification` to confirm the hook is registered. For the full event schema, see the [Notification reference](/docs/en/hooks#notification). ### Auto-format code after edits
from line 668
Each event type matches on a specific field: -| Event | What the matcher filters | Example matcher values | -| :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` | -| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact`, `fork` | -| `Setup` | which CLI flag triggered setup | `init`, `maintenance` | -| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` | -| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed` | -| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, or custom agent names | -| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` | -| `SubagentStop` | agent type | same values as `SubagentStart` | -| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | -| `DirectoryAdded` | how the directory was added | `slash_command`, `register_repo_root` | -| `StopFailure` | error type | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` | -| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` | -| `Elicitation` | MCP server name | your configured MCP server names | -| `ElicitationResult` | MCP server name | same values as `Elicitation` | -| `FileChanged` | literal filenames to watch (see [FileChanged](/docs/en/hooks#filechanged)) | `.envrc\|.env` | -| `UserPromptExpansion` | command name | your skill or command names | -| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | no matcher support | always fires on every occurrence | +| Event | What the matcher filters | Example matcher values | +| :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | tool name | `Bash`, `Edit\|Write`, `mcp__.*` | +| `SessionStart` | how the session started | `startup`, `resume`, `clear`, `compact`, `fork` | +| `Setup` | which CLI flag triggered setup | `init`, `maintenance` | +| `SessionEnd` | why the session ended | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` | +| `Notification` | notification type | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled` | +| `SubagentStart` | agent type | `general-purpose`, `Explore`, `Plan`, or custom agent names | +| `PreCompact`, `PostCompact` | what triggered compaction | `manual`, `auto` | +| `SubagentStop` | agent type | same values as `SubagentStart` | +| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | +| `DirectoryAdded` | how the directory was added | `slash_command`, `register_repo_root` | +| `StopFailure` | error type | `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `unknown` | +| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` | +| `Elicitation` | MCP server name | your configured MCP server names | +| `ElicitationResult` | MCP server name | same values as `Elicitation` | +| `FileChanged` | literal filenames to watch (see [FileChanged](/docs/en/hooks#filechanged)) | `.envrc\|.env` | +| `UserPromptExpansion` | command name | your skill or command names | +| `UserPromptSubmit`, `PostToolBatch`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `MessageDisplay` | no matcher support | always fires on every occurrence | The tabs below show a few more matchers on different event types.