claude_hooks 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7cd63a0fbf165b912baa3fab487e056f05bc10d29b77123e2029ef1dce385a4
-  data.tar.gz: '054837c4d15be8b9d248aa81db5966d80c2c5e0f9a322c622bdf781bf8d0af20'
+  metadata.gz: 4ff845df334960263a1d36b01aeba57393609c59acbc63424572c9d7fdca7999
+  data.tar.gz: 70029c193102d9a63b6d6e5ff8361fcf42e506bff26435c907ec4a06010a571a
 SHA512:
-  metadata.gz: 38ef48d0b9cb24d30522f213302d5a3af48fca24ecd90af259b7d6a034fcbd8ddc706c0c2783db8b5372fb59c3d7a4429b7cc7523cd0299e7ed2a7b8cb8b023e
-  data.tar.gz: 82cdb4b713646492a92a1bae0143a7051fe2bc4f6afe0ad7394bb6f7d50704035a8ddd863bb1b4d12885867859cd6b5b743c618d2fc87682e26918150162b25a
+  metadata.gz: 28a4548cafd93c7f5d5c9d1f577399d8e90503c2e4ae1fa279a9723234045848c0b3bdbb1c41df9f0808d375eb5d345a5210d9db46fe74ba3332fb2394920530
+  data.tar.gz: e2555f3731aad5bacb7e572c9630fa9e39721b625684664bc2ea41d9b0579af146f697b10a6d99410368140ebb7cd37de53b2bd195e2a2c13a5100722502fcd2

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/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,70 @@ 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.1] - 2026-07-15
+
+### Added
+
+- **`CLI.run_hook` — new primary entrypoint method** replacing `CLI.entrypoint`. Reads JSON from STDIN, runs the hook, and exits with the correct code and stream for the hook type.
+  - Accepts `on_error: :allow` (default, exit 1 — non-blocking) or `on_error: :block` (exit 2 — blocking). Use `:block` for security/policy hooks where a crash should never silently pass through.
+  - Supports a class form (`CLI.run_hook(MyHook)`) and a block form for multi-handler merging.
+
+### Changed
+
+- **`CLI.entrypoint` deprecated** in favour of `CLI.run_hook`. It remains as a delegating alias with a deprecation warning and will be removed in a future minor version.
+- **`CLI.run_hook` (old)** — the previous public `run_hook(hook_class, input_data)` helper used internally by `test_runner`/`run_with_sample_data` has been renamed to `run_hook_with_data` and made private. It was never intended as part of the public API.
+- **Error output stream** — `CLI.run_hook` / `CLI.entrypoint` now write errors exclusively to stderr (previously the `:allow` path also wrote to stdout). On the `on_error: :block` (exit 2) path the message is written as **plain text**, not JSON, since Claude Code shows exit-2 stderr to the model verbatim and never parses it as JSON. The `:allow` (exit 1) path still writes the JSON error object to stderr.
+- **README and examples** updated throughout to use `CLI.run_hook`.
+
+### Notes
+
+- No hook class or output class changes — existing hook scripts continue to work without modification
+- `CLI.entrypoint` still works; only a deprecation warning is emitted
+- 3 new tests covering `on_error: :block` (hook error → exit 2, invalid JSON → exit 2) and the deprecation warning
+
+## [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