From 37fa0bac051d055e6ddd973552d1f842b9a1cfc4 Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Thu, 16 Apr 2026 23:45:23 +0500 Subject: [PATCH] update hook property names and add PreCompact blocking output to hooks README Co-Authored-By: Claude --- .claude/hooks/HOOKS-README.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/.claude/hooks/HOOKS-README.md b/.claude/hooks/HOOKS-README.md index f725699..5d8d5ed 100644 --- a/.claude/hooks/HOOKS-README.md +++ b/.claude/hooks/HOOKS-README.md @@ -12,7 +12,7 @@ Claude Code provides several hook events that run at different points in the wor | 4 | `PostToolUseFailure` | Runs after tool calls fail | `async`, `timeout: 5000`, `error`, `is_interrupt`, `tool_use_id` | | 5 | `UserPromptSubmit` | Runs when the user submits a prompt, before Claude processes it | `async`, `timeout: 5000`, `prompt` | | 6 | `Notification` | Runs when Claude Code sends notifications | `async`, `timeout: 5000`, `notification_type`, `message`, `title` | -| 7 | `Stop` | Runs when Claude Code finishes responding | `async`, `timeout: 5000`, `last_assistant_message`, `stop_hook_active` | +| 7 | `Stop` | Runs when Claude Code finishes responding | `async`, `timeout: 5000`, `stop_reason`, `last_assistant_message`, `stop_hook_active` | | 8 | `SubagentStart` | Runs when subagent tasks start | `async`, `timeout: 5000`, `agent_id`, `agent_type` | | 9 | `SubagentStop` | Runs when subagent tasks complete | `async`, `timeout: 5000`, `agent_id`, `agent_type`, `last_assistant_message`, `agent_transcript_path`, `stop_hook_active` | | 10 | `PreCompact` | Runs before Claude Code is about to run a compact operation | `async`, `timeout: 5000`, `once`, `compact_trigger` | @@ -23,15 +23,15 @@ Claude Code provides several hook events that run at different points in the wor | 15 | `TeammateIdle` | Runs when a teammate agent becomes idle (experimental agent teams) | `async`, `timeout: 5000`, `teammate_name`, `team_name` | | 16 | `TaskCreated` | Runs when a task is being created via the TaskCreate tool (experimental agent teams) | `async`, `timeout: 5000`, `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` | | 17 | `TaskCompleted` | Runs when a background task completes (experimental agent teams) | `async`, `timeout: 5000`, `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` | -| 18 | `ConfigChange` | Runs when a configuration file changes during a session | `async`, `timeout: 5000`, `file_path`, `source` | -| 19 | `WorktreeCreate` | Runs when agent worktree isolation creates worktrees for custom VCS setup | `async`, `timeout: 5000`, `worktree_path`, `worktree_name`, `base_branch` | -| 20 | `WorktreeRemove` | Runs when agent worktree isolation removes worktrees for custom VCS teardown | `async`, `timeout: 5000`, `worktree_path`, `worktree_name` | +| 18 | `ConfigChange` | Runs when a configuration file changes during a session | `async`, `timeout: 5000`, `file_path`, `config_source` | +| 19 | `WorktreeCreate` | Runs when agent worktree isolation creates worktrees for custom VCS setup | `async`, `timeout: 5000`, `worktree_path`, `isolation_reason` | +| 20 | `WorktreeRemove` | Runs when agent worktree isolation removes worktrees for custom VCS teardown | `async`, `timeout: 5000`, `worktree_path`, `removal_reason` | | 21 | `InstructionsLoaded` | Runs when CLAUDE.md or `.claude/rules/*.md` files are loaded into context | `async`, `timeout: 5000`, `file_path`, `memory_type`, `load_reason`, `globs`, `trigger_file_path`, `parent_file_path` | -| 22 | `Elicitation` | Runs when an MCP server requests user input during a tool call | `async`, `timeout: 5000`, `mcp_server_name`, `tool_name`, `form_fields` | -| 23 | `ElicitationResult` | Runs after a user responds to an MCP elicitation, before the response is sent back to the server | `async`, `timeout: 5000`, `mcp_server_name`, `tool_name`, `user_response`, `form_fields` | -| 24 | `StopFailure` | Runs when the turn ends due to an API error (rate limit, auth failure, etc.) | `async`, `timeout: 5000`, `error`, `error_details`, `last_assistant_message` | +| 22 | `Elicitation` | Runs when an MCP server requests user input during a tool call | `async`, `timeout: 5000`, `server_name`, `tool_name`, `elicitation_schema` | +| 23 | `ElicitationResult` | Runs after a user responds to an MCP elicitation, before the response is sent back to the server | `async`, `timeout: 5000`, `server_name`, `tool_name`, `user_response` | +| 24 | `StopFailure` | Runs when the turn ends due to an API error (rate limit, auth failure, etc.) | `async`, `timeout: 5000`, `error_type`, `error_message`, `last_assistant_message` | | 25 | `CwdChanged` | Runs when the working directory changes during a session (reactive env management, e.g. direnv) | `async`, `timeout: 5000`, `old_cwd`, `new_cwd` | -| 26 | `FileChanged` | Runs when watched files change during a session (reactive env management, e.g. direnv). **Requires `matcher` with pipe-separated basenames** (e.g. `.envrc\|.env`) to specify which files to watch | `async`, `timeout: 5000`, `file_path`, `change_type` | +| 26 | `FileChanged` | Runs when watched files change during a session (reactive env management, e.g. direnv). **Requires `matcher` with pipe-separated basenames** (e.g. `.envrc\|.env`) to specify which files to watch | `async`, `timeout: 5000`, `file_path`, `changed_reason` | | 27 | `PermissionDenied` | Runs after auto mode classifier denies a tool call. Return `{retry: true}` to tell the model it can retry | `async`, `timeout: 5000`, `tool_name`, `tool_input`, `tool_use_id`, `reason` | > **Note:** Hooks 15-17 (`TeammateIdle`, `TaskCreated`, and `TaskCompleted`) require the experimental agent teams feature. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` when launching Claude Code to enable them. @@ -484,9 +484,9 @@ Matchers filter which events trigger a hook. Not all hooks support matchers — | `SessionEnd` | `reason` | `clear`, `resume`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` | `"matcher": "logout"` | | `PreCompact` | `compact_trigger` | `manual`, `auto` | `"matcher": "auto"` | | `PostCompact` | `compact_trigger` | `manual`, `auto` | `"matcher": "manual"` | -| `Elicitation` | `mcp_server_name` | MCP server name | `"matcher": "my-mcp-server"` | -| `ElicitationResult` | `mcp_server_name` | MCP server name | `"matcher": "my-mcp-server"` | -| `ConfigChange` | `source` | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | `"matcher": "project_settings"` | +| `Elicitation` | `server_name` | MCP server name | `"matcher": "my-mcp-server"` | +| `ElicitationResult` | `server_name` | MCP server name | `"matcher": "my-mcp-server"` | +| `ConfigChange` | `config_source` | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | `"matcher": "project_settings"` | | `UserPromptSubmit` | — | No matcher support | Always fires | | `Stop` | — | No matcher support | Always fires | | `TeammateIdle` | — | No matcher support | Always fires | @@ -555,6 +555,7 @@ Different hooks use different output schemas for blocking or controlling executi | PreToolUse | `hookSpecificOutput.autoAllow` | `true` — auto-approve future uses of this tool (since v2.0.76) | | PermissionRequest | `hookSpecificOutput.decision.behavior` | `allow`, `deny` | | Stop, SubagentStop, ConfigChange | Top-level `decision` | `block` | +| PreCompact | `decision` + exit code 2 | `{"decision": "block"}` or exit code 2 — blocks compaction (since v2.1.105) | | TeammateIdle, TaskCreated, TaskCompleted | `continue` + exit code 2 | `{"continue": false, "stopReason": "..."}` — JSON decision control added in v2.1.70. TaskCreated also uses exit code 2 to block task creation (stderr fed back to model) | | UserPromptSubmit | Can modify `prompt` field | Returns modified prompt via stdout | | WorktreeCreate | Non-zero exit + stdout path | Non-zero exit fails creation; stdout provides worktree path |