claude_hooks 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7cd63a0fbf165b912baa3fab487e056f05bc10d29b77123e2029ef1dce385a4
-  data.tar.gz: '054837c4d15be8b9d248aa81db5966d80c2c5e0f9a322c622bdf781bf8d0af20'
+  metadata.gz: c1803cc66c5f4c6e0d2ca706c4106654a2aa961e8a8e968d3198acab8ff95a7d
+  data.tar.gz: 5dba30b7bce90d4a420cb1c83be1b9e2e2c3a1b0b1dfc42f47b0edd01e08941c
 SHA512:
-  metadata.gz: 38ef48d0b9cb24d30522f213302d5a3af48fca24ecd90af259b7d6a034fcbd8ddc706c0c2783db8b5372fb59c3d7a4429b7cc7523cd0299e7ed2a7b8cb8b023e
-  data.tar.gz: 82cdb4b713646492a92a1bae0143a7051fe2bc4f6afe0ad7394bb6f7d50704035a8ddd863bb1b4d12885867859cd6b5b743c618d2fc87682e26918150162b25a
+  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/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,49 @@ 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

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,16 +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 |
-| **[PermissionRequest](docs/API/PERMISSION_REQUEST.md)** | `ClaudeHooks::PermissionRequest` | Hooks that run when Claude requests permission |
-| **[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
 
@@ -388,16 +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`, `permission_mode` |
+| **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` |
+| **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` |
+| **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` |
-| **Notification**  | `message`, `notification_type` |
-| **Stop**  | `stop_hook_active` |
-| **SubagentStop**  | `stop_hook_active` |
+| **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
@@ -405,15 +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
@@ -625,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`:
@@ -722,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
 

data/docs/API/COMMON.md

@@ -12,7 +12,11 @@ Input helpers to access the data provided by Claude Code through `STDIN`.
 | `transcript_path` | Get path to the transcript file |
 | `cwd` | Get current working directory |
 | `hook_event_name` | Get the hook event name |
-| `permission_mode` | Get the permission mode: `'default'`, `'plan'`, `'acceptEdits'`, `'dontAsk'`, `'bypassPermissions'` (defaults to `'default'`) |
+| `permission_mode` | Get the permission mode: `'default'`, `'plan'`, `'acceptEdits'`, `'auto'`, `'dontAsk'`, `'bypassPermissions'` (defaults to `'default'`) |
+| `prompt_id` | Get the current prompt ID |
+| `agent_id` | Get the agent ID (present in subagent contexts) |
+| `agent_type` | Get the agent type (present in subagent contexts) |
+| `effort` | Get the effort level string (reads `effort.level`) |
 | `read_transcript` | Read the transcript file |
 | `transcript` | Alias for `read_transcript` |
 
@@ -28,6 +32,7 @@ Hook state methods are helpers to modify the hook's internal state (`output_data
 | `clear_specifics!` | Clear hook-specific output |
 | `system_message!(message)` | Set a system message shown to the user (not to Claude) |
 | `clear_system_message!` | Clear the system message |
+| `terminal_sequence!(seq)` | Emit an ANSI/terminal escape sequence in the output |
 
 ## Output Helpers
 
@@ -45,6 +50,7 @@ This object provides helpers to access output data, for merging multiple outputs
 | `output.suppress_output?` | Check if output should be suppressed from transcript |
 | `output.hook_specific_output` | Get the hook-specific output data |
 | `output.system_message` | Get the system message if any |
+| `output.terminal_sequence` | Get the terminal escape sequence (if set) |
 
 ### Output data merging
 For each hook type, the `output` object provides a **class method** `merge` that will try to intelligently merge multiple hook results, e.g. `ClaudeHooks::Output::UserPromptSubmit.merge(output1, output2, output3)`.

data/docs/API/CONFIG_CHANGE.md

@@ -0,0 +1,39 @@
+# ConfigChange API
+
+Available when inheriting from `ClaudeHooks::ConfigChange`:
+
+Runs when Claude Code configuration changes. Can block the change for most sources (note: `policy_settings` changes cannot be blocked).
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `source` | The source of the config change (e.g. `'project'`, `'user'`, `'policy_settings'`) |
+| `file_path` | Path to the changed config file (optional) |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `block!(reason)` | Block the config change (ineffective for `policy_settings`) |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.blocked?` | Check if the change was blocked |
+| `output.decision` | Get the decision (`'block'` or nil) |
+| `output.reason` | Get the block reason |
+
+## Hook Exit Codes
+
+| Exit Code | Behavior |
+|-----------|----------|
+| `exit 0` | Config change proceeds |
+| `exit 2` | Blocks the change; `STDERR` shown to Claude |

data/docs/API/CWD_CHANGED.md

@@ -0,0 +1,34 @@
+# CwdChanged API
+
+Available when inheriting from `ClaudeHooks::CwdChanged`:
+
+Runs when the working directory changes. Can update the list of watched paths.
+
+## Input Helpers
+
+[📚 Shared input helpers](COMMON.md#input-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `old_cwd` | The previous working directory |
+| `new_cwd` | The new working directory |
+
+## Hook State Helpers
+
+[📚 Shared hook state methods](COMMON.md#hook-state-methods)
+
+| Method | Description |
+|--------|-------------|
+| `watch_paths!(paths)` | Set the list of paths Claude Code should watch for changes |
+
+## Output Helpers
+
+[📚 Shared output helpers](COMMON.md#output-helpers)
+
+| Method | Description |
+|--------|-------------|
+| `output.watch_paths` | Get the configured watch paths |
+
+## Hook Exit Codes
+
+Non-blocking. Only `watchPaths` output is consumed.