Repository navigation
Releases
Releases · nrzz/claude-hook-bench
1.2.0
claude-hook-bench list,run --httpand/hook-bench:checkwarn when anhttphook's header uses an environment variable thatallowedEnvVarsdoes not list, which Claude Code fills with an empty string. There is one warning for each reference, naming the header and the variable (the header "X-Team" uses $TEAM, which allowedEnvVars does not list: Claude Code sends an empty string for it), so$TOKEN-$SECRETgives two. A hook with noallowedEnvVarsat all keeps its earlier warning, and anallowedEnvVarsentry that no header uses is a note, not a warning.- The check and the request share one pattern for a reference (
ENV_REFinsrc/http.mjs), so they cannot disagree about what counts as one. The README's findings table has a row for http hooks. - Contributed by @madhavidayma21 in #4, for the good first issue #3. The pull request's tests ran on Windows, macOS and Linux with Node 18 to 24, and the real-binary checks against Claude Code on Ubuntu and macOS, before the merge.
The next good first issue is #5: a finding for an allowedEnvVars entry that is not a bare variable name ("$POLICY_TOKEN" instead of "POLICY_TOKEN"), which can never match a header.
See the README to set it up, and CHANGELOG.md for every version.
1.1.0
claude-hook-bench run --httprunshttphooks, which were listed and checked but not run: it posts the event's JSON to each hook'surland judges the response as Claude Code does. A 2xx with an empty body is success with no output; a 2xx with a JSON object goes through the same parsing, validation and verdict as a command hook's stdout; a 2xx with any other body, a non-2xx status and a connection failure are non-blocking errors. Header values fill$VARand${VAR}only for the variables the hook lists inallowedEnvVars, and the hook'stimeoutapplies.- It is off by default, because it opens a connection. Without
--httpanhttphook is listed and checked, as before.src/http.mjsis the only file that may open a connection, and only to the hook's ownurl; the README, CONTRIBUTING.md and SECURITY.md say so where they used to say the bench makes no network request. - With
onFailure: "block", a 2xx whose body is neither empty nor a JSON object blocks, as invalid output, which is what the hooks reference says. - "Not verified" says that the response rules follow the hooks reference, not a recording from the binary; that an administrator's
allowedHttpHookUrlsandhttpHookAllowedEnvVarsare not applied; and that a redirect is not followed here. - Contributed by @yoreva-01 in #2, for the good first issue #1. The pull request's tests ran on Windows, macOS and Linux with Node 18 to 24, and the real-binary checks against Claude Code 2.1.312 on Ubuntu and macOS, before the merge.
The next good first issue is #3: a list finding for an http hook whose header uses an environment variable that allowedEnvVars does not list, so the empty header is found before the hook runs.
See the README to set it up, and CHANGELOG.md for every version.
claude-hook-bench 1.0.0
- First release.
runruns every command hook of a Claude Code setup (the managed, user, project and local settings files, the enabled plugins'hooks/hooks.json, and folders given with--plugin-dir) once per matching event value, with the JSON Claude Code sends for that event on stdin, from a throwaway session folder, and reports per run: did it run, exit code, time, stdout and stderr, whether the output is valid for the event, and what Claude Code would do with it (denies,allows,asks,keeps Claude working,adds context,shows a message,silent,non-blocking error,timed out,cannot start).--commandand--filechange the shell and file fixtures,--inputsends your own JSON,--event Event:valueand--hookpick a run,--timeoutcaps a run.listshows every hook with its source and the findings of the static checks.explaindescribes one hook (when it fires, how it runs, the exact JSON it gets, how its answer is read) or one event.--jsoneverywhere,--markdownfor the skill,--fail-on error|warnfor a build. - A plugin with one user-only skill,
/hook-bench:check. - The event table covers the 33 events of the hooks reference. The JSON for 17 of them was recorded from Claude Code 2.1.295 through its own binary and a fake API, and the fixtures pin the recorded keys, order and types; 86 hook outputs were put to the binary to see what it does with each, and the verdicts follow the binary where it and the reference differ (README "What was verified").
test/e2e-claude.test.mjsrepeats the recording and 17 of the outputs against the binary; CI runs it on Linux and macOS with the newest npm release.