Agent hooks
Version 1.0.0 · MIT licensed
Unofficial community project by Scalably. Not affiliated with or endorsed by
Anthropic or OpenAI. Claude, Claude Code and Codex are trademarks of their
respective owners.
Eight guardrails that run in front of a coding agent. They are the command-hook
form of guards we run in our own agent platform, where agents do real work on
real systems all day.
They are boring on purpose. Each one is a shell script that reads JSON on
standard input and answers with an exit code. No daemon, no network calls, no
telemetry, nothing to sign up for. jq is the only dependency.
What each one does
| Hook | Event | What it does |
|---|
bash-guard | PreToolUse (Bash) | Triages destructive commands. Denies the unrecoverable ones, asks a human about the rest, stays silent on ordinary work. |
verify-before-commit | PreToolUse (Bash) | Runs a repository's own verification before a commit, and blocks the commit if it fails. Allowlisted repositories only. |
guard-agent-nesting | PreToolUse (Agent, Task) | One level of delegation. A subagent may not spawn its own subagent. |
guard-agent-background | PreToolUse (Agent, Task) | A spawned subagent must say foreground explicitly, because omitting the flag means background. |
web-fetch-guard | Pre and PostToolUse (WebFetch) | Stops asking a site that has already refused. |
stuck-detector | PostToolUseFailure | Catches an agent retrying the same call with the same error. Warns on the second, blocks on the third. |
pre-compact-state | PreCompact | Writes a small snapshot of session and repository state before the context is compacted. |
tidy-scan | Stop | Surfaces uncommitted files, unpushed commits and stale worktrees at the end of a turn. Never changes anything. |
Install
claude plugin marketplace add scalably-io/agent-skills
claude plugin install agent-hooks@scalably-agent-skills
To install by hand instead, clone the repository and copy the entries from
hooks/hooks.json into your own settings, replacing ${CLAUDE_PLUGIN_ROOT}
with the path you cloned to.
Either way, run ./tests/run-all.sh afterwards. It feeds each hook the payload
the client actually sends and asserts what comes back, so a pass means the hooks
work, not merely that the files are present.
For Codex, the event names and the input and exit-code contract are the same.
The scripts are shared; only the registration file differs. See
docs/codex-hooks.md.
Add .claude/ to your .gitignore. pre-compact-state writes its snapshot
there, and it records absolute paths.
The contract every hook follows
exit 0 allow
exit 2 block; whatever the hook wrote to stderr is shown to the model
other non-blocking error
Every hook exits 0 on malformed or unexpected input. A guard that blocks a
session because it could not parse something is worse than no guard.
Two things worth knowing before you install
The bash guard's pattern list is public on purpose. It guards against an
agent doing something destructive by accident. It is not an access control and
does not depend on anyone not knowing what is in it. Read it, and change it to
suit your own blast radius.
It also matches patterns in the command string it is given, and it cannot tell
code from prose. Writing a document that quotes a dangerous command through a
shell heredoc will trip it. Use a file-writing tool for that, and do not reword
the command to slip past the guard.
verify-before-commit runs a script your repository supplies, at
.claude/verify.sh. That is fine for repositories you wrote and not fine by
default: clone a hostile repository that ships its own verify script, commit
once, and you have run its author's code. So the hook runs nothing until you
allowlist that repository, by exact path:
printf '%s\n' "$(git rev-parse --show-toplevel)" >> ~/.claude/verify-allowlist
A parent directory does not allowlist the repositories beneath it.
Configuration
| Variable | Default | Meaning |
|---|
BASH_GUARD_SAFE_PATHS | unset | Colon-separated paths where recursive deletes are allowed silently, in addition to temp, build and dependency directories. |
VERIFY_ALLOWLIST | ~/.claude/verify-allowlist | Repositories whose verification script may run. |
WEB_FETCH_SCORES | .claude/web-fetch-scores.json | Where the fetch guard remembers which domains refused. |
Tests
./tests/run-all.sh
Every hook has a test that feeds it fixture input and asserts the exit code.
The guards that matter are mutation-checked: the test suite has been run with
each guard deliberately removed, and confirmed to fail. A guard test that still
passes with its guard deleted certifies the absence of protection, which is
worse than having no test at all.
Related
Contributing
Issues and pull requests are welcome. A new hook needs a test that feeds it
fixture input and asserts the exit code, and it must exit 0 on junk input. See
CONTRIBUTING.md.
