claude_hooks 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d82c5deaa5426bc2ca898300f7772fa58c56a2998fd00af4eb1a93de25d3336e
-  data.tar.gz: ffde711d996ad0f43f7f75a3002f5a1e74e84f28ed2197ddf9c53c8b982a5152
+  metadata.gz: c1803cc66c5f4c6e0d2ca706c4106654a2aa961e8a8e968d3198acab8ff95a7d
+  data.tar.gz: 5dba30b7bce90d4a420cb1c83be1b9e2e2c3a1b0b1dfc42f47b0edd01e08941c
 SHA512:
-  metadata.gz: 8256eeed53e717873271ea94b9d85610e741ade7d6009b41a9df6eccc8ea58ec4af3b4ab8883d8dfba3d0ef849afdcae6939786d7cb7ad4d000dd7dc749a73ab
-  data.tar.gz: 306144f71bd099d70df514ee21eb9e63a11389562322927465b1aecff447c78eaafc602aa973db8a925bf0885c4e212fbcbfacb410c6d34c30a7b56eb9e51145
+  metadata.gz: f5b394c9005bea73bdb66db595e3783fc7cb2e67889dbf2923b945899bd8c907edf0df241a534ac4a2679c887a07538ec9e1d65d58d24f2b9313cded33e5ca18
+  data.tar.gz: b9867904501454ef867f5be72a0c82e63de3d7bcfdfe6981c8cfbbf946fdd50cc2968671dfd341a1811736da51302c67e412e09302e295b61b30abca25790b23

data/.agents/skills/ci-monitoring/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: ci-monitoring
+description: >
+  How to wait for GitHub Actions CI to finish on a PR after pushing commits,
+  without hanging forever or giving up too early. Use this skill whenever you
+  have pushed to a PR branch and need to confirm the checks pass before
+  reporting back or approving.
+triggers:
+  - ci
+  - checks
+  - status check
+  - wait for ci
+  - green
+  - pipeline
+---
+
+# Waiting for CI on a PR
+
+After you push commits to a PR branch, the PR's checks (`test.yml`, `ruby-gem.yml`)
+re-run. You often need to confirm they pass before you comment "done" or before a
+review approves. This is easy to get wrong in two opposite ways — hanging forever,
+or declaring success while checks are still pending. Follow this pattern.
+
+## Do NOT use the blocking watchers
+
+These hang until completion with no timeout and will burn the whole run's time
+budget (the agent's bash step is capped at ~10 minutes):
+
+```bash
+gh run watch          # ❌ blocks indefinitely
+gh pr checks --watch  # ❌ blocks indefinitely
+```
+
+## Poll `statusCheckRollup` in a bounded foreground loop
+
+Query the PR's aggregated check state and sleep between polls. Use
+`statusCheckRollup`, **not** `gh pr checks --required`: the latter only returns
+contexts that are *already registered*, so a check that registers late (a matrix
+job, or a summary job with a long `needs:` list) can make it exit green early and
+miss a failure.
+
+```bash
+PR=<pr-number>
+for i in $(seq 1 9); do
+  # One JSON blob with every check's name, status, and conclusion.
+  rollup=$(gh pr view "$PR" --json statusCheckRollup \
+    --jq '.statusCheckRollup[] | {name: .name, status: .status, conclusion: .conclusion}')
+
+  # Are any checks still running / queued?
+  pending=$(echo "$rollup" | jq -sr '[.[] | select(.status != "COMPLETED")] | length')
+
+  if [ "$pending" -eq 0 ]; then
+    echo "All checks completed."
+    break
+  fi
+  echo "Attempt $i/9: $pending check(s) still running; sleeping 60s…"
+  sleep 60
+done
+```
+
+That is 9 × 60s = ~9 minutes, which fits inside the bash step cap. If checks are
+still pending after the loop, say so explicitly ("CI was still running when I
+checked — see the PR checks tab") rather than claiming success.
+
+## Decide pass/fail from the final rollup
+
+A check passed only when `status == "COMPLETED"` **and**
+`conclusion == "SUCCESS"` (or `NEUTRAL`/`SKIPPED`). Treat `FAILURE`,
+`TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`, or `STALE` as failing.
+
+```bash
+failed=$(gh pr view "$PR" --json statusCheckRollup \
+  --jq '[.statusCheckRollup[]
+         | select(.conclusion != null and .conclusion != "SUCCESS"
+                  and .conclusion != "NEUTRAL" and .conclusion != "SKIPPED")]
+        | length')
+if [ "$failed" -gt 0 ]; then
+  echo "CI failed — inspect the failing job before reporting done."
+fi
+```
+
+Do **not** treat `mergeStateStatus == BLOCKED` as a CI failure — it's a catch-all
+(branch protection, pending review, etc.), not a check result.
+
+## When a check fails
+
+- Read the failing job's logs (`gh run view <run-id> --log-failed`) and fix the
+  cause. For this Ruby gem, most failures are the test suite — see the
+  `run-tests` skill.
+- Re-run only the failed jobs if the failure looks transient (rare here):
+  `gh run rerun <run-id> --failed`.
+- Never mark a PR done or approve over red CI. If you approve, the empty-body
+  approval reads as endorsing a broken build.
+
+## Notes specific to this repo
+
+- Relevant workflows on a PR: **`test.yml`** (Ruby 3.2 + 3.3 matrix — the one that
+  matters for correctness) and **`ruby-gem.yml`** (its publish job is gated on
+  `push` to `main`, so on a PR it only builds — a failure there is still worth
+  reading).
+- A PR the bot opened may **not** auto-run these workflows: the built-in
+  `GITHUB_TOKEN` does not retrigger other workflows. If the checks tab is empty on
+  a bot-opened PR, that's expected, not a hang — note it and move on.

data/.agents/skills/run-tests/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: run-tests
+description: >
+  How to install dependencies and run the claude_hooks test suite.
+  Use this skill whenever you need to verify that code changes pass the tests
+  before committing.
+triggers:
+  - test
+  - tests
+  - spec
+  - run_all_tests
+---
+
+# Running the claude_hooks Test Suite
+
+This is a **Ruby gem**. Always run the full test suite after any code change and
+before committing.
+
+## Install dependencies
+
+```bash
+bundle install
+```
+
+## Run all tests
+
+```bash
+ruby test/run_all_tests.rb
+```
+
+The suite must exit 0 before you commit. All files matching `test/test_*.rb` are
+included automatically.
+
+## Adding or updating tests
+
+- Place new test files in `test/` named `test_<feature>.rb`.
+- Use plain `Test::Unit` / `Minitest` — no RSpec.
+- Run the full suite, not just the new file, to catch regressions.
+
+## Common failure patterns
+
+- **Missing gem**: run `bundle install` again; check `Gemfile.lock` was updated.
+- **LoadError**: verify the `require` path matches the file under `lib/`.
+- **Unexpected output**: the hooks write to `$stderr`; redirect if your test
+  captures stdout only.

data/.claude/auto-fix.md

@@ -0,0 +1,7 @@
+Context: This gem is a wrapper around Claude Code Hooks system, providing a Ruby DSL to define hooks. The github repository has an automated system through github actions that automatically (weekly) creates a diff of the last known state of Claude Code's hook documentation vs the current (online) Claude Code's hooks documentation. It then generates a diff between those and create an issue with the diff.
+
+Intended goal: Take all those issues and all those diffs and evaluate if the gem / code needs to be updated to match the changes made by anthropic to their Claude Code Hooks system.
+
+First step: Retrieve all the issues at: https://github.com/gabriel-dehan/claude_hooks/issues
+And assess which issues may implement things that need to be changed (a lot of issues contain useless diff, with wording changes, link changes, etc that are not relevant).
+Second step: Take those relevant issues and look at the diff, then compare it with the current codebase / readme / documentation to see if there is a mismatch Third step: Create a plan to tackle those changes

data/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "env": {
+    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
+  },
+  "permissions": {
+    "allow": [
+      "Read(//Users/gdehan/**)",
+      "Read(//Users/gdehan/.config/**)",
+      "Bash(herdr --help)",
+      "Bash(herdr config *)",
+      "Bash(herdr api *)",
+      "Bash(python3 -m json.tool)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(list\\(d.keys\\(\\)\\)\\)\")",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(json.dumps\\(list\\(d.keys\\(\\)\\), indent=2\\)\\)\")",
+      "Bash(python3 -c ' *)",
+      "Bash(herdr server *)",
+      "WebFetch(domain:opencode.ai)",
+      "Bash(ruby *)"
+    ]
+  }
+}

data/AGENTS.md

@@ -0,0 +1,46 @@
+# Agent guidance — claude_hooks
+
+This file is loaded by the coding agents that run in this repo's GitHub Actions
+bots. It is picked up via `load_available_skills` (which internally calls
+`load_project_skills`, the loader that ingests `AGENTS.md`) in
+`agent_task.py` (issue and PR bots) and by the `pr-review` composite action.
+Keep it short and factual.
+
+## What this project is
+
+`claude_hooks` is a **Ruby gem** — a DSL for creating [Claude Code](https://docs.claude.com/en/docs/claude-code)
+hooks (logging, security checks, workflow automation) with composable hook scripts.
+Pure Ruby, no Rails. Public repo: https://github.com/gabriel-dehan/claude_hooks
+
+## Layout
+
+- `lib/claude_hooks/` — the gem. One file per hook type (`pre_tool_use.rb`,
+  `post_tool_use.rb`, `user_prompt_submit.rb`, `session_start.rb`, etc.), plus
+  `base.rb`, `configuration.rb`, `cli.rb`, `logger.rb`, `version.rb`.
+- `test/` — plain Ruby tests (`test_*.rb`), no RSpec.
+- `docs/` — human docs, including `docs/mitts/` for the bot setup itself.
+
+## Running tests
+
+```bash
+bundle install
+ruby test/run_all_tests.rb
+```
+
+Run this before committing any code change; it must pass. Add or update tests in
+`test/` when you change behavior.
+
+## Conventions
+
+- Match the surrounding code's style; this is a small, idiomatic Ruby gem.
+- Keep changes minimal and focused on the request.
+- Follow SemVer; note user-facing changes in `CHANGELOG.md`. `v1.0.0` introduced
+  breaking changes — check the changelog before assuming an API.
+- Never commit secrets; never modify `.github/workflows/` permissions or CI secrets
+  unless the task is explicitly about the workflows.
+
+## For PR review specifically
+
+Verify that behavior changes come with tests and that `ruby test/run_all_tests.rb`
+would still pass. Flag anything that breaks the documented DSL API without a
+CHANGELOG note.

data/CHANGELOG.md

@@ -5,6 +5,99 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-07-14
+
+### Added
+
+- **20 new hook event classes** bringing full parity with the Claude Code Hooks spec v1.2.0 (30 events total):
+  - **Context-only**: `Setup`, `SubagentStart`
+  - **Blocking (top-level `decision`)**: `UserPromptExpansion`, `PostToolBatch`, `ConfigChange`
+  - **Blocking (exit-2 / `continue:false`)**: `TaskCreated`, `TaskCompleted`, `TeammateIdle`
+  - **Non-blocking**: `PostToolUseFailure`, `StopFailure`, `PostCompact`, `CwdChanged`, `FileChanged`, `InstructionsLoaded`, `WorktreeRemove`
+  - **JSON-API special**: `PermissionDenied`, `Elicitation`, `ElicitationResult`, `WorktreeCreate`
+  - **Display**: `MessageDisplay`
+
+- **New common input readers** (available on all hook instances):
+  - `prompt_id`, `agent_id`, `agent_type`, `effort`
+  - `permission_mode` now documents `'auto'` as a valid value
+
+- **`terminal_sequence!(seq)`** builder on all hooks; `terminal_sequence` accessor on output objects; `terminalSequence` (last non-nil wins) in `Output::Base.merge`
+
+- **`PreToolUse` additions**: `defer_permission!`, `update_input!(hash)`, `add_additional_context!`; new output accessor `deferred?`
+
+- **`PostToolUse` additions**: `update_tool_output!(value)`, `update_mcp_tool_output!(value)`; output accessors `updated_tool_output`, `updated_mcp_tool_output`, `output_updated?`
+
+- **`SessionStart` additions**: builders `session_title!`, `initial_user_message!`, `watch_paths!(array)`, `reload_skills!(bool)`; matching output accessors `session_title`, `initial_user_message`, `watch_paths`, `reload_skills?`; input readers `model`, `session_title`
+
+- **`Stop` / `SubagentStop` additions**: input readers `last_assistant_message`, `background_tasks`, `session_crons`; `add_additional_context!` builder + `output.additional_context` accessor; `SubagentStop` gains `agent_transcript_path`
+
+- **`PreCompact` additions**: `block!(reason)` builder; `Output::PreCompact` gains `decision`, `reason`, `blocked?` accessors
+
+- **`PostToolBatch` convenience**: `succeeded_calls` / `failed_calls` partitions over `tool_calls` (success derived from the entry's `tool_response`)
+
+### Changed
+
+- **`PermissionRequest` emitted JSON shape** — builders now emit `hookSpecificOutput.decision = { behavior, message?, updatedInput?, updatedPermissions?, interrupt? }` instead of flat `permissionDecision`/`permissionDecisionReason` keys. **Backward-compatible: no hook code changes required** — builder signatures (`allow_permission!`, `deny_permission!`, `update_input_and_allow!`) are unchanged; read-side accessors (`permission_decision`, `allowed?`, `denied?`, etc.) retain legacy fallback for any stored flat JSON.
+
+- **`PreToolUse` merge precedence** corrected to `deny > defer > ask > allow` (was `deny > ask > allow`).
+
+### Notes
+
+- All changes are additive — existing hooks continue to work without modification
+- Ships as minor `1.2.0` (no source-level breaks for users)
+- Total hook event classes: 30 (added 20 new classes, including `MessageDisplay`)
+- All 13 test files pass (0 failures, 0 errors)
+
+## [1.1.0] - 2026-01-04
+
+### Added
+
+- **New PermissionRequest hook type** - Handles permission request events from Claude Code
+  - New `ClaudeHooks::PermissionRequest` hook class
+  - New `ClaudeHooks::Output::PermissionRequest` output class
+  - Methods: `allow_permission!`, `deny_permission!`, `update_input_and_allow!`
+  - Semantic helpers: `allowed?`, `denied?`, `input_updated?`
+  - Exit code 0 with stdout (JSON API pattern)
+  - Merge logic: deny > allow (most restrictive wins)
+
+- **permission_mode field** - Added to all hooks as common input field
+  - Values: `default`, `plan`, `acceptEdits`, `dontAsk`, `bypassPermissions`
+  - Accessible via `permission_mode` method on all hook instances
+  - Defaults to `'default'` when not provided
+  - Supports both snake_case (`permission_mode`) and camelCase (`permissionMode`)
+
+- **tool_use_id field** - Added to PreToolUse and PostToolUse hooks
+  - Unique identifier for each tool use event (e.g., `"toolu_01ABC123..."`)
+  - Accessible via `tool_use_id` method
+  - Supports both snake_case and camelCase input
+
+- **notification_type field** - Added to Notification hook
+  - Values: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`
+  - Accessible via `notification_type` method
+  - Enables filtering notifications by type using matchers
+
+- **updatedInput support** - Added to PreToolUse hook
+  - New method: `update_tool_input!(hash)` for modifying tool input before execution
+  - Output helpers: `input_updated?`, `updated_input`
+  - Automatically sets `permissionDecision` to `'allow'`
+  - Merge logic: last updatedInput wins (most recent transformation)
+  - Works seamlessly with existing approval/denial methods
+
+### Changed
+
+- Updated all hook classes to include new input fields where applicable
+- Enhanced PreToolUse output class with updatedInput merge logic
+- Updated main module to require PermissionRequest classes
+- Updated output factory to support PermissionRequest hook type
+
+### Notes
+
+- **All changes are backward compatible** - Existing hooks continue to work without modification
+- New fields are optional with sensible defaults
+- No breaking changes to existing APIs
+- Aligns with Anthropic's Claude Code Hooks documentation as of January 2026
+- Total hook types: 10 (added PermissionRequest)
+
 ## [1.0.2] - 2026-01-04
 
 ### Fixed

data/README.md

@@ -1,7 +1,7 @@
 # Ruby DSL for Claude Code hooks
 
 > [!IMPORTANT]
-> v1.0.0 just released and is introducing breaking changes. Please read the [CHANGELOG](CHANGELOG.md) for more information.
+> v1.2.0 just released and is introducing a great number of changes. Please read the [CHANGELOG](CHANGELOG.md) for more information.
 
 
 A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will hopefully make creating and configuring new hooks way easier.
@@ -24,6 +24,7 @@ A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will
   - [📝 Example: Tool usage monitor](#-example-tool-usage-monitor)
   - [🔄 Hook Output](#-hook-output)
   - [🔌 Plugin Hooks Support](#-plugin-hooks-support)
+  - [🛠️ MCP Tools Integration](#️-mcp-tools-integration)
   - [🚨 Advices](#-advices)
   - [⚠️ Troubleshooting](#️-troubleshooting)
   - [🧪 CLI Debugging](#-cli-debugging)
@@ -35,7 +36,11 @@ A Ruby DSL (Domain Specific Language) for creating Claude Code hooks. This will
 > [!TIP]
 > Examples are available in [`example_dotclaude/hooks/`](example_dotclaude/hooks/). The GithubGuard in particular is a good example of a solid hook. You can also check [Kyle's hooks for some great examples](https://github.com/kylesnowschwartz/dotfiles/blob/main/claude/hooks)
 
-Here's how to create a simple hook:
+Claude Code supports two types of hooks:
+- **Command hooks** (`type: "command"`) - Execute Ruby/bash scripts (what this DSL is for)
+- **Prompt-based hooks** (`type: "prompt"`) - Delegate decisions to an LLM ([see guide](docs/PROMPT_BASED_HOOKS.md))
+
+Here's how to create a simple command hook with this DSL:
 
 1. **Install the gem:**
 ```bash
@@ -261,15 +266,36 @@ The framework supports the following hook types:
 
 | Hook Type | Class | Description |
 |-----------|-------|-------------|
-| **[SessionStart](docs/API/SESSION_START.md)** | `ClaudeHooks::SessionStart` | Hooks that run when Claude Code starts a new session, resumes, or compacts |
-| **[UserPromptSubmit](docs/API/USER_PROMPT_SUBMIT.md)** | `ClaudeHooks::UserPromptSubmit` | Hooks that run before the user's prompt is processed |
-| **[Notification](docs/API/NOTIFICATION.md)** | `ClaudeHooks::Notification` | Hooks that run when Claude Code sends notifications |
-| **[PreToolUse](docs/API/PRE_TOOL_USE.md)** | `ClaudeHooks::PreToolUse` | Hooks that run before a tool is used |
-| **[PostToolUse](docs/API/POST_TOOL_USE.md)** | `ClaudeHooks::PostToolUse` | Hooks that run after a tool is used |
-| **[Stop](docs/API/STOP.md)** | `ClaudeHooks::Stop` | Hooks that run when Claude Code finishes responding |
-| **[SubagentStop](docs/API/SUBAGENT_STOP.md)** | `ClaudeHooks::SubagentStop` | Hooks that run when subagent tasks complete |
-| **[SessionEnd](docs/API/SESSION_END.md)** | `ClaudeHooks::SessionEnd` | Hooks that run when Claude Code sessions end |
-| **[PreCompact](docs/API/PRE_COMPACT.md)** | `ClaudeHooks::PreCompact` | Hooks that run before transcript compaction |
+| **[SessionStart](docs/API/SESSION_START.md)** | `ClaudeHooks::SessionStart` | Runs when Claude Code starts, resumes, or compacts a session |
+| **[Setup](docs/API/SETUP.md)** | `ClaudeHooks::Setup` | Runs once on Claude Code startup before any session |
+| **[UserPromptSubmit](docs/API/USER_PROMPT_SUBMIT.md)** | `ClaudeHooks::UserPromptSubmit` | Runs before the user's prompt is processed |
+| **[UserPromptExpansion](docs/API/USER_PROMPT_EXPANSION.md)** | `ClaudeHooks::UserPromptExpansion` | Runs when a slash command or prompt expansion is triggered |
+| **[Notification](docs/API/NOTIFICATION.md)** | `ClaudeHooks::Notification` | Runs when Claude Code sends a notification |
+| **[MessageDisplay](docs/API/MESSAGE_DISPLAY.md)** | `ClaudeHooks::MessageDisplay` | Runs when a message is about to be displayed |
+| **[PreToolUse](docs/API/PRE_TOOL_USE.md)** | `ClaudeHooks::PreToolUse` | Runs before a tool is used; can allow, deny, defer or ask |
+| **[PermissionRequest](docs/API/PERMISSION_REQUEST.md)** | `ClaudeHooks::PermissionRequest` | Runs when Claude requests an explicit permission |
+| **[PermissionDenied](docs/API/PERMISSION_DENIED.md)** | `ClaudeHooks::PermissionDenied` | Runs when a permission request is denied; can request a retry |
+| **[PostToolUse](docs/API/POST_TOOL_USE.md)** | `ClaudeHooks::PostToolUse` | Runs after a tool is used; can rewrite output |
+| **[PostToolBatch](docs/API/POST_TOOL_BATCH.md)** | `ClaudeHooks::PostToolBatch` | Runs after a full batch of tool calls completes |
+| **[PostToolUseFailure](docs/API/POST_TOOL_USE_FAILURE.md)** | `ClaudeHooks::PostToolUseFailure` | Runs when a tool call fails |
+| **[Stop](docs/API/STOP.md)** | `ClaudeHooks::Stop` | Runs when Claude Code finishes responding; can force continuation |
+| **[StopFailure](docs/API/STOP_FAILURE.md)** | `ClaudeHooks::StopFailure` | Runs when the stop phase itself errors; logging only |
+| **[SubagentStart](docs/API/SUBAGENT_START.md)** | `ClaudeHooks::SubagentStart` | Runs when a subagent task starts |
+| **[SubagentStop](docs/API/SUBAGENT_STOP.md)** | `ClaudeHooks::SubagentStop` | Runs when a subagent task completes |
+| **[TaskCreated](docs/API/TASK_CREATED.md)** | `ClaudeHooks::TaskCreated` | Runs when a teammate task is created |
+| **[TaskCompleted](docs/API/TASK_COMPLETED.md)** | `ClaudeHooks::TaskCompleted` | Runs when a teammate task completes |
+| **[TeammateIdle](docs/API/TEAMMATE_IDLE.md)** | `ClaudeHooks::TeammateIdle` | Runs when a teammate goes idle |
+| **[PreCompact](docs/API/PRE_COMPACT.md)** | `ClaudeHooks::PreCompact` | Runs before transcript compaction; can block it |
+| **[PostCompact](docs/API/POST_COMPACT.md)** | `ClaudeHooks::PostCompact` | Runs after transcript compaction completes |
+| **[ConfigChange](docs/API/CONFIG_CHANGE.md)** | `ClaudeHooks::ConfigChange` | Runs when Claude Code configuration changes; can block it |
+| **[CwdChanged](docs/API/CWD_CHANGED.md)** | `ClaudeHooks::CwdChanged` | Runs when the working directory changes |
+| **[FileChanged](docs/API/FILE_CHANGED.md)** | `ClaudeHooks::FileChanged` | Runs when a watched file is created, modified, or deleted |
+| **[InstructionsLoaded](docs/API/INSTRUCTIONS_LOADED.md)** | `ClaudeHooks::InstructionsLoaded` | Runs when a CLAUDE.md instructions file is loaded |
+| **[Elicitation](docs/API/ELICITATION.md)** | `ClaudeHooks::Elicitation` | Runs when an MCP server requests user input |
+| **[ElicitationResult](docs/API/ELICITATION_RESULT.md)** | `ClaudeHooks::ElicitationResult` | Runs after an elicitation response is provided |
+| **[WorktreeCreate](docs/API/WORKTREE_CREATE.md)** | `ClaudeHooks::WorktreeCreate` | Runs when Claude Code creates a git worktree |
+| **[WorktreeRemove](docs/API/WORKTREE_REMOVE.md)** | `ClaudeHooks::WorktreeRemove` | Runs when a git worktree is removed |
+| **[SessionEnd](docs/API/SESSION_END.md)** | `ClaudeHooks::SessionEnd` | Runs when a Claude Code session ends |
 
 ## 🚀 Claude Hook Flow
 
@@ -387,15 +413,36 @@ The framework supports all existing hook types with their respective input field
 
 | Hook Type | Input Fields |
 |-----------|--------------|
-| **Common**  | `session_id`, `transcript_path`, `cwd`, `hook_event_name` |
+| **Common (all hooks)**  | `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `permission_mode`, `prompt_id`, `agent_id`, `agent_type`, `effort` |
+| **SessionStart**  | `source`, `model`, `session_title` |
+| **Setup**  | `source` |
 | **UserPromptSubmit**  | `prompt` |
-| **PreToolUse**  | `tool_name`, `tool_input` |
-| **PostToolUse**  | `tool_name`, `tool_input`, `tool_response` |
-| **Notification**  | `message` |
-| **Stop**  | `stop_hook_active` |
-| **SubagentStop**  | `stop_hook_active` |
+| **UserPromptExpansion**  | `expansion_type`, `command_name`, `command_args`, `command_source`, `prompt` |
+| **Notification**  | `message`, `notification_type` |
+| **MessageDisplay**  | `turn_id`, `message_id`, `index`, `final`, `delta` |
+| **PreToolUse**  | `tool_name`, `tool_input`, `tool_use_id` |
+| **PermissionRequest**  | `tool_name`, `tool_input`, `tool_use_id`, `permission_suggestions` |
+| **PermissionDenied**  | `tool_name`, `tool_input`, `tool_use_id`, `reason` |
+| **PostToolUse**  | `tool_name`, `tool_input`, `tool_response`, `tool_use_id` |
+| **PostToolBatch**  | `tool_calls` |
+| **PostToolUseFailure**  | `tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`, `duration_ms` |
+| **Stop**  | `stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons` |
+| **StopFailure**  | `error`, `error_details`, `last_assistant_message` |
+| **SubagentStart**  | *(common only: `agent_id`, `agent_type`)* |
+| **SubagentStop**  | `stop_hook_active`, `agent_transcript_path` + common `agent_id`/`agent_type` |
+| **TaskCreated**  | `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` |
+| **TaskCompleted**  | `task_id`, `task_subject`, `task_description`, `teammate_name`, `team_name` |
+| **TeammateIdle**  | `teammate_name`, `team_name` |
 | **PreCompact**  | `trigger`, `custom_instructions` |
-| **SessionStart**  | `source` |
+| **PostCompact**  | `trigger`, `compact_summary` |
+| **ConfigChange**  | `source`, `file_path` |
+| **CwdChanged**  | `old_cwd`, `new_cwd` |
+| **FileChanged**  | `file_path`, `event` |
+| **InstructionsLoaded**  | `file_path`, `load_reason` |
+| **Elicitation**  | `mcp_server_name`, `message`, `mode`, `url`, `elicitation_id`, `requested_schema` |
+| **ElicitationResult**  | `mcp_server_name`, `action`, `mode`, `elicitation_id`, `content` |
+| **WorktreeCreate**  | `name` |
+| **WorktreeRemove**  | `worktree_path` |
 | **SessionEnd**  | `reason` |
 
 ### Hooks API
@@ -403,14 +450,35 @@ The framework supports all existing hook types with their respective input field
 **All hook types** inherit from `ClaudeHooks::Base` and share a common API, as well as hook specific APIs.
 
 - [📚 Common API Methods](docs/API/COMMON.md)
-- [🔔 Notification Hooks](docs/API/NOTIFICATION.md)
 - [🚀 Session Start Hooks](docs/API/SESSION_START.md)
+- [⚙️ Setup Hooks](docs/API/SETUP.md)
 - [🖋️ User Prompt Submit Hooks](docs/API/USER_PROMPT_SUBMIT.md)
+- [🔀 User Prompt Expansion Hooks](docs/API/USER_PROMPT_EXPANSION.md)
+- [🔔 Notification Hooks](docs/API/NOTIFICATION.md)
+- [💬 Message Display Hooks](docs/API/MESSAGE_DISPLAY.md)
 - [🛠️ Pre-Tool Use Hooks](docs/API/PRE_TOOL_USE.md)
+- [🔐 Permission Request Hooks](docs/API/PERMISSION_REQUEST.md)
+- [🚫 Permission Denied Hooks](docs/API/PERMISSION_DENIED.md)
 - [🔧 Post-Tool Use Hooks](docs/API/POST_TOOL_USE.md)
-- [📝 Pre-Compact Hooks](docs/API/PRE_COMPACT.md)
+- [📦 Post-Tool Batch Hooks](docs/API/POST_TOOL_BATCH.md)
+- [❌ Post-Tool Use Failure Hooks](docs/API/POST_TOOL_USE_FAILURE.md)
 - [⏹️ Stop Hooks](docs/API/STOP.md)
+- [💥 Stop Failure Hooks](docs/API/STOP_FAILURE.md)
+- [▶️ Subagent Start Hooks](docs/API/SUBAGENT_START.md)
 - [⏹️ Subagent Stop Hooks](docs/API/SUBAGENT_STOP.md)
+- [✅ Task Created Hooks](docs/API/TASK_CREATED.md)
+- [✅ Task Completed Hooks](docs/API/TASK_COMPLETED.md)
+- [💤 Teammate Idle Hooks](docs/API/TEAMMATE_IDLE.md)
+- [📝 Pre-Compact Hooks](docs/API/PRE_COMPACT.md)
+- [📄 Post-Compact Hooks](docs/API/POST_COMPACT.md)
+- [🔩 Config Change Hooks](docs/API/CONFIG_CHANGE.md)
+- [📂 Cwd Changed Hooks](docs/API/CWD_CHANGED.md)
+- [📄 File Changed Hooks](docs/API/FILE_CHANGED.md)
+- [📋 Instructions Loaded Hooks](docs/API/INSTRUCTIONS_LOADED.md)
+- [💬 Elicitation Hooks](docs/API/ELICITATION.md)
+- [💬 Elicitation Result Hooks](docs/API/ELICITATION_RESULT.md)
+- [🌳 Worktree Create Hooks](docs/API/WORKTREE_CREATE.md)
+- [🗑️ Worktree Remove Hooks](docs/API/WORKTREE_REMOVE.md)
 - [🔚 Session End Hooks](docs/API/SESSION_END.md)
 
 ### 📝 Logging
@@ -622,6 +690,13 @@ Claude Code hooks support multiple exit codes with different behaviors depending
 | SessionStart     | Operation continues<br/><br />**`STDOUT` added as context to Claude**       | Non-blocking error<br/><br />`STDERR` shown to user                | N/A<br/><br />`STDERR` shown to user only                                   |
 | SessionEnd       | Operation continues<br/><br />Logged to debug only (`--debug`) | Non-blocking error<br/><br />Logged to debug only (`--debug`)                | N/A<br/><br />Logged to debug only (`--debug`)                                   |
 
+> [!NOTE]
+> The 20 events added in `1.2.0` follow the same families. Their per-event exit-code behavior is documented on each API page under [`docs/API/`](docs/API/):
+> - **Blocking via top-level `decision`** (behave like `PreToolUse`/`Stop`): `UserPromptExpansion`, `PostToolBatch`, `ConfigChange`.
+> - **Blocking via `exit 2` / `continue: false`** (no `decision` field): `TaskCreated`, `TaskCompleted`, `TeammateIdle`.
+> - **JSON-API special** (always `exit 0`, decision in `hookSpecificOutput`): `PermissionDenied`, `Elicitation`, `ElicitationResult`, `WorktreeCreate` (bare-path stdout).
+> - **Non-blocking / context-only** (exit code effectively ignored): `Setup`, `SubagentStart`, `PostToolUseFailure`, `StopFailure`, `PostCompact`, `CwdChanged`, `FileChanged`, `InstructionsLoaded`, `WorktreeRemove`, `MessageDisplay`.
+
 
 #### Manually outputing and exiting example with success
 For the operation to continue for a `UserPromptSubmit` hook, you would `STDOUT.puts` structured JSON data followed by `exit 0`:
@@ -719,7 +794,70 @@ end
 - `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)
 - All standard environment variables and configuration options work the same way
 
-See the [plugin components reference](https://docs.claude.com/en/docs/claude-code/plugins-reference#hooks) for more details on creating plugin hooks.
+See the [plugin components reference](https://code.claude.com/docs/en/plugins-reference#hooks) for more details on creating plugin hooks.
+
+## 🛠️ MCP Tools Integration
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools can be used with Claude Code hooks. When MCP servers are configured, their tools become available and can be intercepted by hooks just like built-in tools.
+
+### MCP Tool Naming Convention
+
+MCP tools follow a specific naming pattern: `mcp__<server-name>__<tool-name>`
+
+**Example MCP tool names:**
+- `mcp__filesystem__read_file`
+- `mcp__github__create_issue`
+- `mcp__database__query`
+
+### Configuring Hooks for MCP Tools
+
+You can use matchers to target specific MCP tools or all tools from a server:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__github__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/entrypoints/github_guard.rb"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*__create.*|mcp__.*__delete.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/entrypoints/destructive_operation_guard.rb"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Common MCP Tool Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `mcp__*__*` | All MCP tools from all servers |
+| `mcp__github__*` | All tools from the github server |
+| `mcp__*__read*` | All read operations from any server |
+| `mcp__.*__create.*\|mcp__.*__delete.*` | All create/delete operations |
+
+### Best Practices for MCP Tools
+
+1. **Use regex matchers** - MCP tool names are predictable, making regex patterns very effective
+2. **Guard destructive operations** - Always review create/delete/update operations
+3. **Server-specific rules** - Different MCP servers may need different security policies
+4. **Log MCP tool usage** - Track which external tools are being used
+5. **Test with your MCP servers** - Tool names vary by server implementation
+
+See the [official MCP documentation](https://modelcontextprotocol.io/) for more information about MCP servers and tools.
 
 ## 🚨 Advices