claude_hooks 1.2.1 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +47 -0
  3. data/README.md +21 -15
  4. data/docs/API/COMMON.md +4 -3
  5. data/docs/API/DIRECTORY_ADDED.md +34 -0
  6. data/docs/API/NOTIFICATION.md +5 -4
  7. data/docs/API/PERMISSION_DENIED.md +4 -0
  8. data/docs/API/PERMISSION_REQUEST.md +3 -3
  9. data/docs/API/POST_MODEL_SWITCH.md +53 -0
  10. data/docs/API/POST_TOOL_USE.md +7 -0
  11. data/docs/API/POST_TOOL_USE_FAILURE.md +1 -0
  12. data/docs/API/PRE_MODEL_SWITCH.md +67 -0
  13. data/docs/API/PRE_TOOL_USE.md +1 -0
  14. data/docs/API/SESSION_START.md +7 -1
  15. data/docs/API/SETUP.md +3 -3
  16. data/docs/API/STOP.md +6 -0
  17. data/docs/API/SUBAGENT_STOP.md +10 -0
  18. data/docs/API/TASK_CREATED.md +9 -7
  19. data/docs/API/USER_PROMPT_SUBMIT.md +14 -0
  20. data/docs/API/WORKTREE_REMOVE.md +9 -4
  21. data/docs/external/claude-hooks-reference.md +1188 -345
  22. data/docs/mitts/prd.md +8 -0
  23. data/docs/mitts/setup.md +5 -3
  24. data/lib/claude_hooks/base.rb +12 -0
  25. data/lib/claude_hooks/directory_added.rb +24 -0
  26. data/lib/claude_hooks/output/base.rb +6 -0
  27. data/lib/claude_hooks/output/directory_added.rb +21 -0
  28. data/lib/claude_hooks/output/notification.rb +10 -1
  29. data/lib/claude_hooks/output/post_model_switch.rb +50 -0
  30. data/lib/claude_hooks/output/post_tool_batch.rb +10 -0
  31. data/lib/claude_hooks/output/post_tool_use.rb +23 -5
  32. data/lib/claude_hooks/output/pre_model_switch.rb +121 -0
  33. data/lib/claude_hooks/output/pre_tool_use.rb +8 -0
  34. data/lib/claude_hooks/output/task_created.rb +34 -1
  35. data/lib/claude_hooks/output/user_prompt_expansion.rb +10 -0
  36. data/lib/claude_hooks/output/user_prompt_submit.rb +19 -6
  37. data/lib/claude_hooks/output/worktree_remove.rb +4 -2
  38. data/lib/claude_hooks/permission_denied.rb +7 -0
  39. data/lib/claude_hooks/permission_request.rb +10 -1
  40. data/lib/claude_hooks/post_model_switch.rb +70 -0
  41. data/lib/claude_hooks/post_tool_use.rb +14 -0
  42. data/lib/claude_hooks/post_tool_use_failure.rb +7 -0
  43. data/lib/claude_hooks/pre_model_switch.rb +90 -0
  44. data/lib/claude_hooks/pre_tool_use.rb +7 -0
  45. data/lib/claude_hooks/session_start.rb +18 -0
  46. data/lib/claude_hooks/setup.rb +3 -0
  47. data/lib/claude_hooks/task_created.rb +17 -0
  48. data/lib/claude_hooks/user_prompt_submit.rb +26 -5
  49. data/lib/claude_hooks/version.rb +1 -1
  50. data/lib/claude_hooks.rb +6 -0
  51. metadata +11 -2
data/docs/API/WORKTREE_REMOVE.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Available when inheriting from `ClaudeHooks::WorktreeRemove`:
4
4
 
5
- Runs when a git worktree is removed. Non-blocking — only `suppressOutput` is honored.
5
+ Runs when a worktree is removed. Pair it with a `WorktreeCreate` hook to control cleanup of the worktrees that hook creates. For those worktrees, **the hook does the cleanup**: Claude Code reads only its exit code and doesn't fall back to `git worktree remove` (it only does that when no `WorktreeRemove` hook is configured). Claude Code discards this hook's JSON output (`systemMessage`, `continue`, …); only the exit code matters, so `prevent_continue!` is what produces the non-zero exit. Claude Code never deletes a branch belonging to a hook-created worktree — if your `WorktreeCreate` hook created a branch, delete it here.
6
6
 
7
7
  ## Input Helpers
8
8
 
@@ -18,7 +18,7 @@ Runs when a git worktree is removed. Non-blocking — only `suppressOutput` is h
18
18
 
19
19
  | Method | Description |
20
20
  |--------|-------------|
21
- | `suppress_output!` | Hide this hook's `STDOUT` from transcript mode (the only honored output control) |
21
+ | `prevent_continue!(reason)` | Report that removal failed (results in exit 2) |
22
22
 
23
23
  ## Output Helpers
24
24
 
@@ -26,8 +26,13 @@ Runs when a git worktree is removed. Non-blocking — only `suppressOutput` is h
26
26
 
27
27
  | Method | Description |
28
28
  |--------|-------------|
29
- | `output.suppress_output?` | Whether output is suppressed |
29
+ | `output.continue?` | `false` when the hook reports failure (exit 2) |
30
+ | `output.stop_reason` | The failure reason |
30
31
 
31
32
  ## Hook Exit Codes
32
33
 
33
- Non-blocking. Exit code is ignored; only `suppressOutput` affects behavior.
34
+ | Exit Code | Behavior |
35
+ |-----------|----------|
36
+ | `exit 0` | The worktree **counts as removed** — make sure your hook deleted the directory |
37
+ | `exit 2` | **The removal fails** if the directory at `worktree_path` still exists; it stays on disk with no git fallback. A hook that deleted the directory before exiting non-zero still counts as removed |
38
+ | `exit 1` | Same as `exit 2` — Claude Code fails the removal on **any** non-zero exit. This includes a hook that raises: `CLI.run_hook` exits 1 on an error (even with the default `on_error: :allow`), so a crashing `WorktreeRemove` hook leaves the worktree on disk |