A catalogue of every hook in cc-safe-setup: which event each runs on, and whether it can refuse (Chapter 10)

What follows is every hook script in the repository’s examples/ directory as of 2026-09-20: 916 of them. It is here because the collection is large enough that browsing the directory is not a way to find anything, and because the two facts you most want before installing something — when it runs, and whether it can refuse — are not visible from the filename.

Each line reads:

name · refuses or witness · event — what it does

The second field is refuses if the script contains a refusal on some path (exit 2, a permission decision, "decision": "block", "deny", or an exit with a variable that may hold 2) and witness if it does not. Witness does not mean broken; most of these are meant to warn, count or log. It means the script has no way to stop a tool call.

refuses is necessary, not sufficient. It says the file contains a refusal, not that the refusal works where the file is registered: 18 of the scripts marked refuses refuse only by exit 2, on an event that cannot be blocked (10 on PostToolUse, 8 on SessionStart). Scripts declaring more than one event are not in that 18 — one of their events still honours exit 2. PreCompact is not on that list: exit 2 does block a compaction. Chapter 8 works through why, and through getting that row wrong the first time.

The refuses field ignores comments. A script whose only exit 2 sits in a sentence about exit 2 is a witness, and 19 files here are exactly that — fifteen of them say so in the very comment that used to be counted. Chapter 8 gives the one-line check that gets this right, and the reason the first version of it did not.

The event is the one declared in the script’s own header. unstated means the header does not say and you should open the file before installing it.

How this list was made, and what is wrong with it. Nothing here was written to describe a script whose source did not already describe itself. The description is taken, in this order, from: the script’s own header comment; failing that, the hand-maintained list inside the repository’s installer; failing that, the first message the script actually prints, quoted verbatim after says:. Where all three are missing the line says so instead of guessing, which happens 41 times. Descriptions that are not in English are dropped rather than translated, for the same reason — a translation is my sentence, not the author’s. So a wrong line here is a wrong line in the repository, and worth an issue.

Install any one of them with:

1 npx github:yurukusa/cc-safe-setup --install-example <name>

Safety Guards

Refusals and warnings on the way in. This is the largest group and the one most people install first.

318 scripts, of which 132 can refuse a call.

absolute-rule-enforcer · witness · Stop — Enforce CLAUDE.md “ABSOLUTE RULE” markers
allowlist · refuses · PreToolUse — Only allow explicitly approved commands
ansible-vault-guard · witness · PreToolUse — says: “WARNING: Decrypting Ansible vault”
api-endpoint-guard · refuses · PreToolUse — Warn on requests to internal/sensitive APIs
api-key-in-url-guard · refuses · PreToolUse — Block API keys embedded in URLs
api-overload-backoff · witness · PostToolUse — Track API overload errors and enforce backoff
api-rate-limit-guard · witness · PreToolUse — Throttle rapid API calls to prevent rate limiting
api-retry-limiter · witness · PostToolUse — Limit API error retries to prevent token waste
aws-production-guard · refuses · PreToolUse — Block dangerous AWS CLI operations
aws-region-guard · witness · PreToolUse — Warn when AWS commands target unexpected regions
banned-command-guard · refuses · PreToolUse — Block commands that are explicitly banned
bash-domain-allowlist · refuses · PreToolUse — Block curl/wget to unauthorized domains
bash-timeout-guard · witness · PreToolUse — Warn on commands likely to hang or run indefinitely without a timeout
bash-trace-guard · refuses · PreToolUse — Block debug tracing that exposes secrets
bg-task-cooldown-guard · refuses · PreToolUse — Cooldown after background task notifications
binary-upload-guard · refuses · PreToolUse — Block committing binary files to git
block-database-wipe · refuses · PreToolUse — Block destructive database commands
bulk-file-delete-guard · refuses · PreToolUse — Block commands that delete many files at once
cargo-publish-guard · refuses · PreToolUse — says: “BLOCKED: cargo publish to crates.io”
case-sensitive-guard · refuses · PreToolUse — Case-Insensitive Filesystem Safety Guard
cch-cache-guard · refuses · PreToolUse — Block reads of Claude session files to prevent cache poisoning
check-csrf-protection · witness · PreToolUse — says: “NOTE: Form without CSRF protection”
chmod-guard · refuses · PreToolUse — Block overly permissive chmod commands
chown-guard · refuses · PreToolUse — Block dangerous ownership changes
ci-workflow-guard · witness · PostToolUse — Prevent dangerous CI/CD workflow modifications
claude-cache-gc · witness · unstated — no description in the file header; open it before installing
claudeignore-enforce-guard · refuses · PreToolUse — Enforce .claudeignore at the tool level
claudemd-enforcer · witness · PostToolUse — no description in the file header; open it before installing
clear-command-confirm-guard · witness · unstated — DOES NOT FIRE. Kept as a record, not as a guard
cloud-cli-guard · refuses · PreToolUse — Block destructive GCP/Azure CLI operations
compact-blocker · refuses · PreCompact — Block auto-compaction entirely
compaction-transcript-guard · witness · PreCompact — Save conversation state before compaction
composer-guard · refuses · PreToolUse — Block dangerous Composer operations
compound-command-allow · refuses · PreToolUse — Auto-approve compound commands when all parts are safe
compound-command-approver · refuses · PreToolUse — Auto-approve safe compound commands
compound-inject-guard · refuses · PreToolUse — Block destructive commands hidden in compound statements
concurrent-edit-lock · refuses · PreToolUse — Prevent file corruption from concurrent Claude sessions
conversation-history-guard · refuses · PreToolUse — Block modifications to conversation history
core-file-protect-guard · refuses · PreToolUse — Block edits to core/config/rules files
credential-exfil-guard · refuses · PreToolUse — Block credential hunting commands
credential-file-cat-guard · refuses · PreToolUse — Block cat/read of package manager credential files
cron-modification-guard · refuses · PreToolUse — Block unreviewed cron job modifications
crontab-guard · witness · PreToolUse — Warn before modifying crontab
cwd-project-boundary-guard · witness · CwdChanged — Warn when cd leaves the project directory
db-connect-guard · refuses · PreToolUse — Warn on direct database connections
denied-action-retry-guard · refuses · PreToolUse — Block re-attempts of denied tool calls
dependency-install-guard · refuses · PreToolUse — Blocks unintended dependency installations (npm install, pip install, gem install, cargo add, go get). Prevents: - Supply chain attacks from unknown packages - Dependency bloat from unnecessary installations - Breaking lockfiles with unplanned additions
dependency-version-pin · witness · PostToolUse — Warn on unpinned dependency versions
deploy-guard · refuses · PreToolUse — Block deploy commands when uncommitted changes exist
deploy-path-verify-guard · witness · PreToolUse — Verify deployment target path before writes
deployment-verify-guard · witness · PreToolUse — Warn if committing without post-deploy verification
disk-partition-guard · refuses · PreToolUse — Block disk partitioning and mount operations
django-migrate-guard · refuses · PreToolUse — Block destructive Django DB operations
dns-config-guard · refuses · PreToolUse — Block DNS/hosts file modifications
docker-dangerous-guard · refuses · PreToolUse — Block dangerous Docker operations
docker-prune-guard · witness · PreToolUse — Warn before docker system prune
docker-volume-guard · witness · PreToolUse — says: “WARNING: Docker volume deletion detected”
dockerfile-latest-guard · witness · PreToolUse — says: “WARNING: :latest tag in Dockerfile:”
dotenv-commit-guard · refuses · PreToolUse — Prevent committing .env files with secrets
drizzle-migrate-guard · refuses · PreToolUse — Block destructive Drizzle ORM operations
edit-guard · refuses · PreToolUse — Block Edit/Write to protected files
edit-retry-loop-guard · witness · PreToolUse — Detect Edit tool stuck retrying the same file
encoding-preserve-guard · witness · PreToolUse — Warn when file encoding changes
env-inherit-guard · witness · PreToolUse — Claude Code’s bash environment
env-inline-secret-guard · refuses · PreToolUse — API keys, database URLs, and tokens get embedded in bash commands, potentially leaking to logs, history, or screen recordings
env-prod-guard · witness · PreToolUse — says: “WARNING: Production env detected in command”
env-source-guard · refuses · PreToolUse — Claude Code sometimes sources .env files directly into bash, causing environment variables to leak across commands
env-var-check · refuses · PreToolUse — that end up in shell history and process environment
expo-eject-guard · refuses · PreToolUse — says: “BLOCKED: Expo eject is irreversible”
export-overwrite-guard · witness · PreToolUse — Prevent /export from overwriting existing files
file-age-guard · witness · PreToolUse — Warn before editing files not modified in 30+ days
firewall-guard · refuses · PreToolUse — Block firewall rule modifications
flask-debug-guard · witness · PreToolUse — Warn when Flask runs with debug=True
gem-push-guard · refuses · PreToolUse — says: “BLOCKED: gem push to RubyGems.org”
gh-cli-destructive-guard · refuses · PreToolUse — Block destructive GitHub CLI operations
git-checkout-safety-guard · refuses · PreToolUse — Prevent file loss from careless branch switching
git-checkout-uncommitted-guard · refuses · PreToolUse — Block branch switching with uncommitted changes
git-config-guard · refuses · PreToolUse — Block git config —global modifications
git-crypt-worktree-guard · refuses · PreToolUse — Block worktree creation in git-crypt repos
git-history-rewrite-guard · refuses · PreToolUse — Block git history rewriting commands
git-hook-bypass-guard · witness · PreToolUse — says: “WARNING: —no-verify bypasses git hooks”
git-index-lock-cleanup · witness · PostToolUse — Remove stale .git/index.lock after git commands
git-merge-conflict-prevent · witness · PreToolUse — says: “NOTE: Check if target branch is ahead before merging”
git-operations-require-approval · refuses · PreToolUse — Block git write operations
git-remote-guard · witness · PreToolUse — Block push/fetch to unknown git remotes
git-signed-commit-guard · witness · PreToolUse — Warn on unsigned git commits
git-submodule-guard · refuses · PreToolUse — Block the data-destroying variant of git submodule deinit before it runs
git-tag-guard · refuses · PreToolUse — says: “WARNING: Creating git tag. Verify version number”
github-actions-guard · witness · PostToolUse — Validate GitHub Actions workflow changes
github-actions-secret-guard · witness · PostToolUse — Prevent hardcoded secrets in GitHub Actions workflows
gitops-drift-guard · witness · PreToolUse — Warn when editing infrastructure files without PR
hardcoded-ip-guard · witness · PreToolUse — says: “Consider: use env vars or config files for IPs”
headless-empty-result-guard · witness · Stop — Detect empty results in headless mode
headless-stop-guard · refuses · Stop — Skip Stop hooks in headless (-p) mode
helm-install-guard · witness · PreToolUse — says: “WARNING: Helm deploy to production namespace”
hook-permission-fixer · witness · SessionStart — Claude Code’s plugin manager and some extraction tools strip execute permissions from shell scripts. This hook runs at session start and ensures all .sh files in the hooks directory are executable
hook-tamper-guard · refuses · PreToolUse — (#32376 — “Who watches the watchmen?”)
image-file-validator · witness · PreToolUse — Block Read of fake image files that corrupt sessions
issue-draft-redact-guard · witness · PreToolUse — Redact sensitive info from public issue drafts
k8s-production-guard · refuses · PreToolUse — Block destructive Kubernetes operations on production
kill-process-guard · refuses · PreToolUse — Block dangerous process termination commands
kubernetes-guard · refuses · PreToolUse — Block destructive kubectl commands
laravel-artisan-guard · refuses · PreToolUse — says: “BLOCKED: Destructive Laravel command”
large-file-guard · witness · PostToolUse — Warn when Write tool creates oversized files
large-file-write-guard · witness · PostToolUse — Warn when writing large files
line-ending-guard · witness · PreToolUse — Warn on CRLF/LF mismatch
log-level-guard · witness · PreToolUse — says: “NOTE: Debug logging in production code”
log-truncation-guard · refuses · PreToolUse — Block log file truncation/deletion
max-edit-size-guard · refuses · PreToolUse — says: “Break the edit into smaller chunks or use Write to replace the entire file”
max-file-delete-count · witness · PreToolUse — no description in the file header; open it before installing
memory-write-guard · refuses · PreToolUse — See, approve, or block silent memory writes
migration-safety · witness · PreToolUse — Require backup before database migrations
migration-verify-guard · refuses · PreToolUse — Require verification before destructive migrations
monorepo-scope-guard · witness · PreToolUse — Restrict edits to the current package in a monorepo
network-exfil-guard · refuses · PreToolUse — Block data exfiltration via network commands
network-guard · witness · PreToolUse — Warn on network commands that send file contents
network-interface-guard · refuses · PreToolUse — Block network interface modifications
nextjs-env-guard · witness · PostToolUse — Prevent exposing server secrets in Next.js client code
no-absolute-import · witness · PreToolUse — says: “NOTE: Absolute import path detected”
no-alert-confirm-prompt · witness · PreToolUse — says: “WARNING: alert/confirm/prompt in code”
no-anonymous-default-export · witness · PostToolUse — says: “NOTE: Anonymous default export — name for better debugging”
no-any-type · witness · PreToolUse — says: “NOTE: TypeScript any detected — add proper types”
no-any-typescript · witness · PreToolUse — says: “Consider: use specific types or unknown”
no-ask-human · refuses · PreToolUse — Block commands that require human input
no-assignment-in-condition · witness · PreToolUse — says: “NOTE: Assignment in condition (use ===)”
no-base64-exfil · refuses · PreToolUse — Block base64 encoding of sensitive files
no-callback-hell · witness · PreToolUse — no description in the file header; open it before installing
no-catch-all-route · witness · PreToolUse — says: “NOTE: Warn on catch-all routes without 404”
no-circular-dependency · witness · PreToolUse — says: “NOTE: Check for circular peer deps”
no-class-in-functional · witness · PreToolUse — says: “NOTE: Warn on class patterns in functional”
no-cleartext-storage · witness · PreToolUse — says: “WARNING: Storing secrets in browser storage”
no-commented-code · witness · PreToolUse — says: “NOTE: Large block of commented code — delete or uncomment”
no-commit-fixup · witness · PreToolUse — says: “WARNING: Branch contains uncommitted fixup/WIP commits:”
no-cors-wildcard · witness · PreToolUse — says: “cors(*) allows any website to call your API”
no-curl-upload · witness · PreToolUse — says: “WARNING: curl upload/POST detected. Verify no sensitive data”
no-dangerouslySetInnerHTML · witness · PreToolUse — says: “WARNING: XSS risk via dangerouslySetInnerHTML”
no-dangling-await · witness · PreToolUse — no description in the file header; open it before installing
no-debug-commit · witness · PreToolUse — Block commits containing debug artifacts
no-debug-in-commit · witness · PreToolUse — says: “WARNING: Debug in staged”
no-deep-nesting · witness · PreToolUse — no description in the file header; open it before installing
no-deep-relative-import · witness · PreToolUse — says: “Consider: use path aliases (@/ or ~/) for cleaner imports”
no-default-credentials · witness · PreToolUse — says: “WARNING: Default credentials”
no-deploy-friday · refuses · PreToolUse — Block deploys on Fridays
no-deprecated-api · witness · PreToolUse — says: “NOTE: Warn on deprecated Node.js APIs”
no-direct-dom-manipulation · witness · PreToolUse — says: “NOTE: Warn on direct DOM in React”
no-disabled-test · witness · PreToolUse — says: “WARNING: Disabled/focused test detected”
no-document-cookie · witness · PreToolUse — says: “NOTE: Warn on direct document.cookie access”
no-document-write · witness · PreToolUse — says: “WARNING: document.write XSS risk”
no-empty-function · witness · PreToolUse — says: “NOTE: Empty function body”
no-exec-user-input · witness · PreToolUse — says: “WARNING: exec with user input — command injection”
no-expose-internal-ids · witness · PreToolUse — says: “NOTE: Warn on exposing database IDs”
no-exposed-port-in-dockerfile · witness · PostToolUse — Warn about exposing port 22 in Dockerfile
no-fixme-ship · witness · PreToolUse — Block git push when FIXME/HACK comments exist
no-floating-promises · witness · PreToolUse — says: “NOTE: Check for unhandled promises”
no-force-flag · refuses · PreToolUse — Block dangerous —force flags
no-force-install · witness · PreToolUse — says: “WARNING: —force install bypasses dependency checks”
no-git-amend · refuses · PreToolUse — Block git commit —amend to prevent overwriting previous commits
no-git-amend-push · witness · PreToolUse — Block amending already-pushed commits
no-git-rebase-public · witness · PreToolUse — says: “WARNING: Rebasing pushed branch”
no-global-install · refuses · PreToolUse — Block global package installations
no-global-state · witness · PreToolUse — says: “NOTE: Module-level mutable state — consider encapsulation”
no-hardcoded-ip · witness · PreToolUse — Detect hardcoded IP addresses in code
no-hardcoded-port · witness · PreToolUse — says: “Consider: use PORT env var for deployment flexibility”
no-hardcoded-url · witness · PreToolUse — says: “NOTE: Hardcoded localhost URL — use env var instead”
no-hardlink · witness · PreToolUse — Warn on hard link creation
no-helmet-missing · witness · PreToolUse — says: “NOTE: Express without helmet()”
no-http-in-code · witness · PreToolUse — Warn about http:// URLs in code (should be https://)
no-http-url · witness · PreToolUse — says: “Use https:// for security”
no-http-without-https · witness · PreToolUse — says: “NOTE: http:// without TLS”
no-index-as-key · witness · PreToolUse — says: “NOTE: Warn on using index as React key”
no-infinite-scroll-mem · witness · PreToolUse — says: “NOTE: Warn on infinite scroll without virtualization”
no-inline-event-handler · witness · PreToolUse — says: “NOTE: Warn on onclick= in HTML”
no-inline-handler · witness · PreToolUse — says: “NOTE: Warn on inline event handlers”
no-inline-style · witness · PreToolUse — says: “NOTE: Inline styles detected. Consider CSS classes”
no-inline-styles · witness · PreToolUse — says: “Consider: use CSS modules, Tailwind, or styled-components”
no-innerhtml · witness · PreToolUse — says: “WARNING: innerHTML XSS risk”
no-install-global · refuses · PreToolUse — says: “BLOCKED: Global npm install. Use npx or local install”
no-jwt-in-url · witness · PreToolUse — says: “WARNING: JWT in URL params”
no-large-commit · witness · PreToolUse — says: “Consider splitting into smaller, focused commits”
no-localhost-expose · witness · PreToolUse — says: “WARNING: Binding to all interfaces exposes service to network”
no-long-switch · witness · PreToolUse — says: “NOTE: Warn on switch with 10+ cases”
no-magic-number · witness · PreToolUse — says: “NOTE: Magic number detected. Consider using a named constant”
no-md5-sha1 · witness · PreToolUse — says: “WARNING: Weak hash (md5/sha1)”
no-memory-leak-interval · witness · PreToolUse — says: “NOTE: Warn on setInterval without clearInterval”
no-mixed-line-endings · witness · PreToolUse — says: “NOTE: Mixed line endings (CRLF + LF)”
no-mutation-in-reducer · witness · PreToolUse — says: “WARNING: Direct state mutation in reducer”
no-mutation-observer-leak · witness · PreToolUse — says: “NOTE: Warn on MutationObserver without disconnect”
no-nested-subscribe · witness · PreToolUse — says: “NOTE: Warn on nested event subscriptions”
no-nested-ternary · witness · PreToolUse — says: “NOTE: Nested ternary detected — use if/else”
no-network-exfil · witness · PreToolUse — no description in the file header; open it before installing
no-new-array-fill · witness · PreToolUse — says: “NOTE: Warn on Array constructor pitfalls”
no-object-freeze-mutation · witness · PreToolUse — says: “NOTE: Warn on mutating frozen objects”
no-open-redirect · witness · PreToolUse — says: “WARNING: Open redirect risk”
no-output-truncation · refuses · PreToolUse — Block piped tail/head that discards command output
no-package-downgrade · witness · PreToolUse — says: “WARNING: Possible package downgrade”
no-package-lock-edit · refuses · PreToolUse — says: “BLOCKED: Manual lockfile edits. Use package manager instead”
no-path-join-user-input · witness · PreToolUse — says: “WARNING: Path traversal risk”
no-port-bind · witness · PreToolUse — says: “WARNING: Command may bind to a network port”
no-process-exit · witness · PreToolUse — says: “NOTE: process.exit() may cause issues in library code”
no-prototype-pollution · witness · PreToolUse — says: “WARNING: Potential prototype pollution”
no-push-without-ci · witness · PreToolUse — says: “WARNING: Pushing without recent test run”
no-push-without-tests · witness · PreToolUse — Block git push if tests haven’t been run
no-raw-password-in-url · witness · PostToolUse — says: “WARNING: Password in URL — use env vars”
no-raw-ref · witness · PreToolUse — says: “NOTE: Warn on raw DOM refs in React”
no-redundant-fragment · witness · PreToolUse — says: “NOTE: Warn on unnecessary React fragments”
no-render-in-loop · witness · PreToolUse — says: “NOTE: Warn on render calls in loops”
no-root-user-docker · witness · PreToolUse — says: “NOTE: Dockerfile runs as root (no USER directive)”
no-root-write · refuses · PreToolUse — says: “BLOCKED: Write to system directory”
no-secrets-in-args · witness · PreToolUse — says: “WARNING: Possible secret in command arguments”
no-secrets-in-logs · witness · PostToolUse — says: “WARNING: Secret in output”
no-self-signed-cert · witness · PreToolUse — Warn when generating self-signed certificates
no-side-effects-in-render · witness · PreToolUse — says: “NOTE: Warn on side effects in render”
no-sleep-in-hooks · witness · PreToolUse — says: “Sleep in hooks causes Claude Code to hang or timeout”
no-star-import-python · witness · PreToolUse — says: “Star imports pollute namespace and hide dependencies”
no-string-concat-sql · witness · PreToolUse — says: “WARNING: String concatenation in SQL — use parameterized queries”
no-sudo-guard · refuses · PreToolUse — says: “BLOCKED: sudo command detected”
no-sync-external-call · witness · PreToolUse — says: “NOTE: Warn on sync external API calls”
no-sync-fs · witness · PreToolUse — says: “NOTE: Sync fs in hot path — consider async”
no-table-layout · witness · PreToolUse — says: “NOTE: Warn on table for layout”
no-throw-string · witness · PreToolUse — says: “NOTE: Warn on throwing strings”
no-todo-in-merge · witness · PreToolUse — says: “WARNING: TODO markers in merge target”
no-todo-in-production · witness · PreToolUse — says: “Consider resolving before shipping”
no-todo-without-issue · witness · PreToolUse — says: “NOTE: TODO without issue reference”
no-triple-slash-ref · witness · PreToolUse — says: “NOTE: Warn on TS triple-slash references”
no-unreachable-code · witness · PreToolUse — says: “NOTE: Warn on code after return”
no-unused-import · witness · PreToolUse — says: “NOTE: Many imports — check for unused ones”
no-unused-state · witness · PreToolUse — says: “NOTE: Warn on unused state in components”
no-var-keyword · witness · PreToolUse — says: “NOTE: var keyword — use const/let”
no-verify-blocker · refuses · PreToolUse — Block —no-verify on git commands
no-wget-piped-bash · refuses · PreToolUse — Block curl/wget piped directly to bash
no-window-location · witness · PreToolUse — says: “NOTE: Warn on window.location assignment”
no-with-statement · witness · PreToolUse — says: “WARNING: with statement is deprecated”
no-write-outside-src · witness · PreToolUse — no description in the file header; open it before installing
no-xml-external-entity · witness · PreToolUse — says: “WARNING: Possible XXE in XML parsing”
npm-global-install-guard · refuses · PreToolUse — Block npm global installs
npm-publish-guard · refuses · PreToolUse — says: “BLOCKED: npm publish requires manual confirmation”
npm-script-injection · witness · PreToolUse — says: “WARNING: package.json script may contain shell injection”
npm-supply-chain-guard · witness · PreToolUse — Detect npm supply chain attack patterns
nuxt-config-guard · witness · PreToolUse — says: “NOTE: nuxt.config modified. Dev server restart required”
output-credential-scan · witness · PostToolUse — Detect credentials in command output
output-secret-mask · witness · PostToolUse — Warn when tool output looks like it contained a secret
overwrite-guard · witness · PreToolUse — Warn before overwriting existing files
package-json-guard · refuses · PreToolUse — says: “BLOCKED: Deleting package.json”
package-lock-frozen · refuses · PreToolUse — Block modifications to lockfiles
parallel-session-guard · witness · PreToolUse — Warn when multiple Claude sessions edit the same project simultaneously
path-deny-bash-guard · refuses · PreToolUse — Enforce path deny rules on Bash commands
path-traversal-guard · refuses · PreToolUse — Block path traversal in Edit/Write operations
permission-denial-enforcer · refuses · PostToolUse+PreToolUse — Block alternative write methods after permission denial
pip-publish-guard · refuses · PreToolUse — says: “BLOCKED: PyPI upload”
pip-requirements-guard · refuses · PreToolUse — Enforce pip install from requirements.txt only
pip-venv-guard · witness · PreToolUse — Warn when pip install runs outside a virtual environment
pip-venv-required · refuses · PreToolUse — Block pip install outside of a virtual environment
polyglot-rm-guard · refuses · PreToolUse — Block file deletion via any language, not just rm
post-compact-safety · refuses · PreToolUse — Guard against autonomous actions after compaction
prisma-migrate-guard · refuses · PreToolUse — Block destructive Prisma operations
prompt-injection-guard · witness · PostToolUse — Detect prompt injection in tool output
protect-claudemd · refuses · PreToolUse — Block edits to CLAUDE.md and settings files
protect-commands-dir · witness · SessionStart — Backup .claude/commands/ on session start
protect-dotfiles · refuses · PreToolUse — Block destructive operations on home directory config files
public-repo-push-guard · refuses · PreToolUse — Block pushing proprietary code to public repos
rails-migration-guard · refuses · PreToolUse — Block destructive Rails migrations
read-all-files-enforcer · witness · PostToolUse — Track which files have been read in a directory
read-budget-guard · refuses · PreToolUse — Limit excessive file reading to prevent token waste
read-only-mode · refuses · PreToolUse — Block all file modifications and destructive commands
redis-flushall-guard · refuses · PreToolUse — says: “BLOCKED: Redis FLUSHALL/FLUSHDB destroys all data”
registry-publish-guard · refuses · PreToolUse — Block publishing to package registries
relative-path-guard · witness · PreToolUse — Warn on relative file paths in Edit/Write
replace-all-guard · refuses · PreToolUse — Warn when Edit uses replace_all: true
response-budget-guard · refuses · PreToolUse — Track and limit tool calls per response
resume-context-guard · witness · Notification — Warn when resuming large sessions
rm-safety-net · refuses · PreToolUse — Extra layer of rm protection beyond destructive-guard
role-tool-guard · refuses · PreToolUse — Restrict tools based on current agent role
schema-migration-guard · witness · PreToolUse — Warn on database schema migrations without backup
scope-guard · refuses · PreToolUse — Block file operations outside the project directory
secret-file-read-guard · refuses · PreToolUse — Block Read/Grep of files containing secrets
self-modify-bypass-guard · witness · PermissionRequest — Auto-allow .claude/ writes in bypass mode
sensitive-file-read-guard · refuses · PreToolUse — Block reading sensitive system/user files
sensitive-log-guard · witness · PreToolUse — says: “Never log passwords, tokens, or API keys”
session-drift-guard · refuses · PreToolUse — Progressive safety as session ages
session-duration-guard · witness · PostToolUse — Warn on long-running sessions
session-permission-reset-guard · refuses · PreToolUse — Override session-cached permissions
shell-wrapper-guard · refuses · PreToolUse — Detect destructive commands hidden in shell wrappers
spec-file-scope-guard · witness · PreToolUse — Restrict edits to files mentioned in a spec document
spring-profile-guard · witness · PreToolUse — says: “WARNING: Running Spring with production profile”
ssh-key-protect · refuses · PreToolUse — Block reading/copying SSH private keys
staged-secret-scan · refuses · PreToolUse — Block git commit if staged diff contains secrets
strict-allowlist · refuses · PreToolUse — Only allow explicitly permitted commands
strip-coauthored-by · refuses · PreToolUse — Warn about (or block) unwanted commit-message trailers
symlink-guard · refuses · PreToolUse — Detect symlink/junction traversal before rm
symlink-protect · witness · unstated — no description in the file header; open it before installing
system-package-guard · refuses · PreToolUse — Block system-level package installations
systemd-service-guard · refuses · PreToolUse — Block dangerous systemd service operations
task-integrity-guard · refuses · PreToolUse — Prevent Claude from deleting tasks to hide unfinished work
terraform-guard · refuses · PreToolUse — Warn before terraform/tofu destroy/apply Covers OpenTofu (tofu), the drop-in fork, and the apply -destroy form, which is the same teardown as destroy (a Terraform destroy has wiped a production database in the wild — DataTalks, and the class in anthropics/claude-code#27063)
timeout-guard · witness · PreToolUse — Warn before long-running commands
timezone-guard · witness · PreToolUse — says: “NOTE: Non-UTC timezone in command”
tmp-output-size-guard · witness · SessionStart — Monitor and warn about large tmp output files
turbo-cache-guard · witness · PreToolUse — Warn before clearing Turborepo cache
typosquat-guard · witness · PreToolUse — Detect potential typosquatting in npm install
uncommitted-changes-stop · witness · Stop — says: “Consider: git add -A && git commit -m ‘session checkpoint’”
uncommitted-discard-guard · refuses · PreToolUse — Block commands that discard uncommitted changes
uncommitted-work-guard · refuses · PreToolUse — Block destructive git when dirty
uncommitted-work-shield · witness · PreToolUse — Auto-stash before destructive git operations
user-account-guard · refuses · PreToolUse — Block user/group account modifications
variable-expansion-guard · refuses · PreToolUse — Block destructive commands with shell variable expansion
windows-path-guard · refuses · PreToolUse — Prevent NTFS junction/symlink traversal destruction
work-hours-guard · refuses · PreToolUse — Restrict risky operations outside work hours
working-directory-fence · refuses · PreToolUse — Block file operations outside CWD
worktree-cleanup-guard · witness · PreToolUse — Warn on worktree removal with unmerged commits
worktree-delete-guard · refuses · PreToolUse — Block git worktree removal
worktree-guard · witness · PreToolUse — Warn when operating in a git worktree
worktree-memory-guard · witness · PreToolUse — Warn when memory path resolves to main worktree
worktree-path-validator · witness · PreToolUse — Warn when file operations target main workspace instead of worktree
worktree-project-unify · witness · unstated — no description in the file header; open it before installing
worktree-unmerged-guard · refuses · PreToolUse — Prevent worktree cleanup with unmerged commits
write-overwrite-confirm · refuses · PreToolUse — Warn when Write destroys content nobody looked at
write-secret-guard · refuses · PreToolUse — Block secrets from being written to files
write-shrink-guard · refuses · PreToolUse — Block writes that drastically shrink files

Auto-Approve

The opposite direction: answering the permission prompt with yes, so that read-only and obviously safe calls stop interrupting you.

35 scripts, of which 18 can refuse a call.

allow-claude-settings · witness · PermissionRequest — Auto-approves writes to .claude/ configuration files
allow-git-hooks-dir · witness · PermissionRequest — Bypasses the built-in protected-directory prompt for .git/hooks/
allow-protected-dirs · witness · PermissionRequest — Auto-approves writes to ALL protected directories (.claude/, .git/, .vscode/, .idea/). Equivalent to full bypassPermissions for file edits
auto-approve-build · witness · PreToolUse — Auto-approve build and test commands
auto-approve-cargo · refuses · PreToolUse — Auto-approve Rust cargo commands
auto-approve-compound-git · refuses · PermissionRequest — Auto-approves compound git commands that the built-in permission system fails to match. The wildcard pattern Bash(git:*) only matches simple commands like “git status” but not “cd src && git log” or “git add file.txt && git commit -m ‘fix’”
auto-approve-docker · witness · PreToolUse — no description in the file header; open it before installing
auto-approve-git-read · refuses · PermissionRequest — Auto-approve read-only git commands
auto-approve-go · refuses · PreToolUse — Auto-approve Go build/test/vet commands
auto-approve-gradle · refuses · PreToolUse — Auto-approve Gradle build/test commands
auto-approve-make · refuses · PreToolUse — Auto-approve common Make targets
auto-approve-maven · refuses · PreToolUse — Auto-approve Maven build/test commands
auto-approve-python · refuses · PreToolUse — Auto-approve Python development commands
auto-approve-readonly · witness · PreToolUse — Auto-approve all read-only commands
auto-approve-readonly-tools · refuses · PermissionRequest — no description in the file header; open it before installing
auto-approve-ssh · refuses · PermissionRequest — Auto-approve safe SSH commands
auto-approve-test · witness · PreToolUse — no description in the file header; open it before installing
auto-compact-prep · witness · PreToolUse — Save checkpoint before context compaction
auto-mode-safe-commands · refuses · PreToolUse — Fix Auto Mode false positives on safe commands
auto-push-worktree · witness · Stop — Auto-push worktree branches before session end
bash-heuristic-approver · witness · PermissionRequest — Auto-approve bash safety heuristic prompts
bash-safety-auto-deny · refuses · PreToolUse — Auto-deny commands that trigger safety prompts
classifier-fallback-allow · refuses · PermissionRequest — Allow read-only commands when Auto Mode classifier is unavailable
direnv-auto-reload · witness · CwdChanged — Auto-reload environment when directory changes
edit-always-allow · refuses · PermissionRequest — Auto-approve all Edit prompts in configured directories
gitignore-auto-add · witness · PostToolUse — Suggest .gitignore entries for common patterns
heredoc-backtick-approver · refuses · PermissionRequest — Auto-approve backtick warnings in heredoc strings
multiline-command-approver · refuses · PreToolUse — Auto-approve multiline commands safely
permission-audit-log · witness · PostToolUse — Log all tool invocations for permission debugging
permission-cache · witness · PreToolUse — Remember approved commands in session
permission-entry-validator · witness · Stop — Clean broken permission entries from settings
permission-mode-drift-guard · witness · PermissionRequest — Detect permission mode changes mid-session
permission-pattern-auto-allow · witness · PreToolUse — Auto-allow commands matching user-defined patterns
quoted-flag-approver · refuses · PermissionRequest — Auto-approve commands with quoted flag values
webfetch-domain-allow · refuses · PreToolUse — Auto-approve WebFetch for allowed domains

Quality

Checks on what was produced — syntax, tests, formatting, diff size, the things you would otherwise find out about at review time.

174 scripts, of which 13 can refuse a call.

bash-secret-output-detector · refuses · PostToolUse — Warn when Bash output contains secrets
bashrc-safety-check · witness · SessionStart — Warn about .bashrc lines that hang in non-interactive shells
branch-name-check · witness · PostToolUse — Warn when creating branches with non-standard names
branch-naming-convention · witness · PreToolUse — says: “Use: feat/, fix/, chore/, docs/, test/, refactor/”
changelog-reminder · witness · PostToolUse — Remind to update CHANGELOG on version bump
check-abort-controller · witness · PreToolUse — says: “NOTE: fetch() without AbortController/signal — the request cannot be cancelled”
check-accessibility · witness · PreToolUse — says: “NOTE: img without alt attribute”
check-aria-labels · witness · PreToolUse — says: “NOTE: Interactive element without ARIA”
check-async-await-consistency · witness · PreToolUse — says: “NOTE: Warn on mixing callbacks and async”
check-before-act-enforcer · refuses · PreToolUse — Require Read before Edit/Write
check-charset-meta · witness · PreToolUse — says: “NOTE: Missing charset meta”
check-cleanup-effect · witness · PreToolUse — says: “NOTE: Warn on useEffect without cleanup”
check-content-type · witness · PreToolUse — says: “NOTE: Warn on missing Content-Type headers”
check-controlled-input · witness · PreToolUse — says: “NOTE: Warn on uncontrolled form inputs”
check-cookie-flags · witness · PreToolUse — says: “NOTE: Cookie without secure flag”
check-cors-config · witness · PreToolUse — says: “NOTE: Permissive CORS config”
check-csp-headers · witness · PreToolUse — says: “NOTE: Consider adding CSP headers”
check-debounce · witness · PreToolUse — says: “NOTE: high-frequency event listener without debounce/throttle”
check-dependency-age · witness · PreToolUse — says: “NOTE: Run npm outdated to check dependency age”
check-dependency-license · witness · PreToolUse — says: “NOTE: Check dependency license before adding”
check-dockerfile-best-practice · witness · PreToolUse — says: “NOTE: Clean apt cache in Dockerfile”
check-error-boundaries · witness · PreToolUse — says: “NOTE: Consider adding ErrorBoundary”
check-error-class · witness · PreToolUse — says: “NOTE: throwing a string literal — use throw new Error(…) to preserve the stack”
check-error-handling · witness · PreToolUse — says: “NOTE: Promise without .catch()”
check-error-logging · witness · PreToolUse — says: “NOTE: catch block without any logging”
check-error-message · witness · PreToolUse — says: “NOTE: Generic error message — be specific”
check-error-page · witness · PreToolUse — says: “NOTE: Warn on missing error page routes”
check-error-stack · witness · PreToolUse — says: “WARNING: Exposing error details to client”
check-favicon · witness · PreToolUse — says: “NOTE: Missing favicon link”
check-form-validation · witness · PreToolUse — says: “NOTE: Warn on forms without validation”
check-git-hooks-compat · witness · PreToolUse — says: “Ensure CC hooks and git hooks don’t duplicate checks”
check-gitattributes · witness · PreToolUse — says: “NOTE: Binary file without .gitattributes LFS config”
check-https-redirect · witness · PreToolUse — says: “NOTE: HTTP redirect without HTTPS”
check-image-optimization · witness · PreToolUse — says: “NOTE: Warn on unoptimized images in web code”
check-input-validation · witness · PreToolUse — says: “NOTE: User input without validation”
check-key-prop · witness · PreToolUse — says: “NOTE: Warn on missing key prop in map”
check-lang-attribute · witness · PreToolUse — says: “NOTE: Missing lang attribute”
check-lazy-loading · witness · PreToolUse — says: “NOTE: Suggest lazy loading for large imports”
check-loading-state · witness · PreToolUse — says: “NOTE: Warn on missing loading states”
check-memo-deps · witness · PreToolUse — says: “NOTE: Warn on missing useMemo/useCallback deps”
check-meta-description · witness · PreToolUse — says: “NOTE: Warn on missing meta description”
check-npm-scripts-exist · witness · PreToolUse — says: “NOTE: Verify referenced npm scripts exist”
check-null-check · witness · PreToolUse — says: “NOTE: Warn on missing null checks”
check-package-size · witness · PreToolUse — no description in the file header; open it before installing
check-pagination · witness · PreToolUse — says: “NOTE: Warn on unbounded data queries”
check-port-availability · witness · PreToolUse — says: “NOTE: Check port availability before starting server”
check-promise-all · witness · PreToolUse — says: “NOTE: Promise.all() without .catch()/try — one rejection fails the whole batch”
check-prop-types · witness · PreToolUse — says: “NOTE: Warn on missing PropTypes/interface”
check-rate-limiting · witness · PreToolUse — says: “NOTE: API endpoint without rate limiting”
check-responsive-design · witness · PreToolUse — says: “NOTE: Warn on fixed widths in CSS”
check-retry-logic · witness · PreToolUse — says: “NOTE: Warn on API calls without retry”
check-return-types · witness · PreToolUse — says: “NOTE: Missing return type annotation”
check-semantic-html · witness · PreToolUse — says: “NOTE: Warn on div soup without semantic tags”
check-semantic-versioning · witness · PreToolUse — says: “NOTE: Non-semver version string”
check-suspense-fallback · witness · PreToolUse — says: “NOTE: without a fallback prop”
check-test-exists · witness · PostToolUse — Warn when editing code without a test file
check-test-naming · witness · PreToolUse — says: “NOTE: Non-descriptive test name”
check-timeout-cleanup · witness · PreToolUse — says: “NOTE: setTimeout() without clearTimeout — may fire after teardown/unmount”
check-tls-version · witness · PreToolUse — says: “WARNING: Weak TLS version”
check-type-coercion · witness · PreToolUse — says: “NOTE: Warn on loose equality (==)”
check-unsubscribe · witness · PreToolUse — says: “NOTE: addEventListener without a matching removeEventListener”
check-viewport-meta · witness · PreToolUse — says: “NOTE: Missing viewport meta”
check-worker-terminate · witness · PreToolUse — says: “NOTE: new Worker() without .terminate() — the worker leaks”
ci-skip-guard · witness · PreToolUse — Warn when commit message skips CI
claudemd-violation-detector · witness · PostToolUse — Remind critical CLAUDE.md rules after tool use
commit-message-check · witness · PostToolUse — Warn when commit messages don’t follow conventions
commit-message-quality · witness · PreToolUse — Warn about low-quality commit messages
commit-quality-gate · witness · PreToolUse — Enforce commit message quality
commit-scope-guard · witness · PreToolUse — Warn when committing too many files
conflict-marker-guard · refuses · PreToolUse — Block commits with conflict markers
console-log-count · witness · PreToolUse — says: “Consider cleaning up debug logs before committing”
context-warning-verifier · witness · PostToolUse — Verify context warnings are genuine
cors-star-warn · witness · PreToolUse — PostToolUse matcher: Edit|Write
cwd-drift-detector · witness · PreToolUse — Warn when destructive commands run outside project root
debug-leftover-guard · witness · PreToolUse — Detect debug code in commits
detect-mixed-indentation · witness · PostToolUse — Warn about mixed tabs/spaces
dockerfile-lint · witness · PostToolUse — Basic Dockerfile validation after editing
dotenv-example-sync · witness · PostToolUse — Warn when .env changes but .env.example doesn’t
dotenv-validate · witness · PostToolUse — Validate .env syntax after edits
dotenv-watch · witness · FileChanged — Alert when .env files change on disk
dotnet-build-on-edit · witness · PostToolUse — Run dotnet build after C#/F# edits
edit-old-string-validator · refuses · PreToolUse — Pre-validate Edit tool old_string exists
edit-verify · witness · PreToolUse — no description in the file header; open it before installing
enforce-tests · witness · PreToolUse — Warn when source files are edited without tests
env-drift-guard · witness · PostToolUse — When Claude edits .env.example (adding new required vars), warn if .env is missing those variables. Prevents deploy failures from missing environment configuration
env-file-gitignore-check · witness · Notification — Prevents: Accidental commit of .env files containing secrets
env-naming-convention · witness · PostToolUse — says: “NOTE: Lowercase env var name — convention is UPPER_CASE”
env-required-check · witness · PreToolUse — says: “NOTE: Env var without default — add fallback”
fact-check-gate · witness · PostToolUse — Warn when docs reference unread source files
file-reference-check · witness · PostToolUse — Verify referenced file paths exist
git-author-guard · witness · PreToolUse — Verify commit author is configured correctly
git-blame-context · witness · PreToolUse — Show file ownership before major edits
git-lfs-guard · witness · PreToolUse — Suggest Git LFS for large binary files
git-message-length · witness · PreToolUse — no description in the file header; open it before installing
git-message-length-check · witness · PostToolUse — Warn on too-short commit messages
gitignore-check · witness · PreToolUse — says: “WARNING: .gitignore is missing or empty”
go-mod-tidy-warn · witness · PostToolUse — says: “NOTE: go mod tidy will remove unused dependencies from go.mod”
go-vet-after-edit · refuses · PostToolUse — Run go vet after editing Go files
grep-nul-false-negative-guard · witness · PostToolUse — The registration was missing from this header. The installer reads TRIGGER and MATCHER from here and falls back to PreToolUse / Bash when both are absent, so this hook was being registered at a moment where the field it reads is always empty: it installed, it appeared in the settings, and it did nothing. Measured 2026-08-04 across examples/: 14 files were like this
hallucination-url-check · witness · PostToolUse — Detect potentially hallucinated URLs in generated code and documentation
hardcoded-secret-detector · witness · PostToolUse — Detect hardcoded secrets in edits
import-cycle-warn · witness · PostToolUse — Detect potential circular imports
java-compile-on-edit · witness · PostToolUse — Check Java compilation after edits
json-syntax-check · witness · PostToolUse — Validate JSON files after editing
license-check · witness · PostToolUse — Warn when creating files without a license header
lockfile-guard · witness · PreToolUse — Warn when lockfiles are modified unexpectedly
magic-number-warn · witness · PreToolUse — says: “Consider: extract to named constants”
main-branch-warn · witness · PreToolUse — Warn when working directly on main/master
markdown-link-check · witness · PostToolUse — Verify local file links in markdown
max-function-length · witness · PreToolUse — no description in the file header; open it before installing
max-import-count · witness · PreToolUse — no description in the file header; open it before installing
max-line-length-check · witness · PostToolUse — Warn on lines exceeding max length after edit
no-console-assert · witness · PreToolUse — says: “NOTE: console.assert in code”
no-console-error-swallow · witness · PermissionRequest — says: “WARNING: Empty catch/except block swallows errors”
no-console-in-prod · witness · PreToolUse — says: “NOTE: console statement in non-test file”
no-console-log-commit · refuses · PreToolUse — Block commits containing console.log
no-console-time · witness · PreToolUse — says: “NOTE: console.time left in code”
no-eval · witness · PreToolUse — no description in the file header; open it before installing
no-eval-in-template · witness · PreToolUse — says: “WARNING: eval in template”
no-eval-template · witness · PreToolUse — says: “WARNING: eval() or new Function() with template literal”
no-todo-ship · witness · PreToolUse — Block commits with TODO/FIXME/HACK markers
no-wildcard-cors · witness · PreToolUse — says: “WARNING: Wildcard CORS origin”
no-wildcard-delete · witness · PreToolUse — says: “WARNING: rm with wildcard pattern”
no-wildcard-import · witness · PreToolUse — says: “WARNING: Wildcard import detected. Import specific names”
npm-audit-warn · witness · PreToolUse — says: “NOTE: Run npm audit after install”
output-explosion-detector · witness · PostToolUse — Detect abnormally large tool outputs
output-pii-detect · witness · PostToolUse — Detect PII/sensitive data in tool output
output-token-env-check · witness · Notification — Warn if max output tokens is not configured
package-script-guard · witness · PreToolUse — Warn when package.json scripts change
php-lint-on-edit · witness · PostToolUse — Run PHP syntax check after editing PHP files
plain-language-danger-warn · witness · PreToolUse — Add plain-language warnings to dangerous commands
port-conflict-check · witness · PreToolUse — Warn before starting a server on an occupied port
pr-description-check · witness · PreToolUse — says: “WARNING: PR created without —body description”
prefer-builtin-tools · refuses · PreToolUse — Deny bash commands that have dedicated built-in tool equivalents
prefer-const · witness · PreToolUse — says: “NOTE: Consider const if not reassigned”
prefer-dedicated-tools · refuses · PreToolUse — Force use of dedicated tools instead of Bash equivalents
prefer-optional-chaining · witness · PreToolUse — says: “NOTE: Consider optional chaining (?.) instead”
push-requires-test-pass · refuses · PreToolUse — Block git push to main/production without test verification
push-requires-test-pass-record · witness · PreToolUse — Record when tests pass (companion to push-requires-test-pass.sh)
python-import-check · witness · PostToolUse — Detect unused imports in Python files
python-ruff-on-edit · witness · PostToolUse — Run ruff lint after editing Python files
react-key-warn · witness · PostToolUse — Warn about missing key props in JSX lists
readme-exists-check · witness · PreToolUse — says: “NOTE: No README.md in project”
readme-update-reminder · witness · PreToolUse — Remind to update README when APIs change
require-issue-ref · witness · PreToolUse — Warn when commit message lacks issue reference
ruby-lint-on-edit · witness · PostToolUse — Run RuboCop after editing Ruby files
rust-clippy-after-edit · witness · PostToolUse — Run cargo clippy after editing Rust files
sandbox-write-verify · refuses · PreToolUse — Verify file existence before overwrite in sandbox mode
sensitive-regex-guard · witness · PostToolUse — Warn on ReDoS-vulnerable regex patterns
session-start-safety-check · witness · SessionStart — Warn about uncommitted changes on session start
settings-mutation-detector · witness · PostToolUse — Detect unauthorized changes to Claude settings files
skill-injection-detector · witness · PreToolUse — Detect silently injected skills/plugins
sql-injection-detect · witness · PreToolUse — says: “WARNING: Possible SQL injection pattern”
svelte-lint-on-edit · witness · PostToolUse — says: “Svelte check errors:”
swift-build-on-edit · witness · PostToolUse — Run swift build check after editing Swift files
test-after-edit · witness · PostToolUse — Remind to run tests after editing test files
test-before-commit · witness · unstated — says: “WARNING: No test commands detected since last commit”
test-before-push · refuses · PreToolUse — Block git push when tests haven’t passed
test-coverage-guard · witness · PreToolUse — Warn when code grows without tests
test-coverage-reminder · witness · PostToolUse — Remind to run tests after code changes
test-deletion-guard · witness · PreToolUse — Block deletion of test assertions
test-exit-code-verify · witness · PostToolUse — Verify test command exit codes match results
todo-check · witness · PostToolUse — Warn when committing files with TODO/FIXME/HACK comments
todo-deadline-warn · witness · PostToolUse — Warn about expired TODO deadlines in edited files
typescript-lint-on-edit · witness · PostToolUse — Run TypeScript type check after editing .ts/.tsx files
typescript-strict-check · witness · PostToolUse — Warn when TypeScript strict mode is disabled
typescript-strict-guard · witness · PostToolUse — Warn when tsconfig.json strict mode is disabled
unicode-corruption-check · witness · PostToolUse — Detect Unicode corruption after Edit/Write
usage-warn · witness · PreToolUse — no description in the file header; open it before installing
verify-before-commit · refuses · PreToolUse — Block git commit unless tests passed recently
verify-before-done · witness · PreToolUse — Warn when committing without running tests
vue-lint-on-edit · witness · PostToolUse — no description in the file header; open it before installing
write-test-ratio · witness · PreToolUse — no description in the file header; open it before installing
yaml-syntax-check · refuses · PostToolUse — Validate YAML after editing

Agent Controls

Limits on subagents and parallel work: how many, how deep, how long.

15 scripts, of which 9 can refuse a call.

max-concurrent-agents · refuses · PreToolUse — Limit number of simultaneous subagents
max-subagent-count · witness · PreToolUse — no description in the file header; open it before installing
mcp-config-freeze · refuses · PreToolUse — Prevent MCP configuration changes during session
mcp-data-boundary · witness · PostToolUse — Prevent MCP tools from accessing sensitive paths
mcp-orphan-process-guard · witness · Stop — Detect orphaned MCP server processes
mcp-server-allowlist · refuses · PreToolUse — Restrict MCP tool calls to allowed servers
mcp-server-guard · refuses · PreToolUse — Block unauthorized MCP server configuration changes
mcp-tool-guard · refuses · PreToolUse — Guard destructive / side-effecting MCP tool calls
subagent-budget-guard · refuses · PreToolUse — says: “Wait for existing agents to complete before spawning more”
subagent-claudemd-inject · witness · PreToolUse — Inject CLAUDE.md rules into subagent prompts
subagent-context-size-guard · witness · PreToolUse — Warn on thin subagent prompts
subagent-forged-system-reminder-guard · refuses · SubagentStop — Quarantine forged / “System:” control markup smuggled out of a sub-agent’s own result before it can impersonate a real system message in the parent agent’s trusted channel
subagent-scope-guard · refuses · PreToolUse — Limit subagent file access scope
subagent-scope-validator · witness · PreToolUse — Warn on vague subagent delegation
subagent-tool-call-limiter · refuses · PreToolUse — Limit total tool calls per session

Monitoring

Counters and meters. Context left, tokens spent, errors in a row, calls per minute.

28 scripts, of which 2 can refuse a call.

api-rate-limit-tracker · refuses · PreToolUse — Track API call frequency and warn on burst
compact-alert-notification · witness · Notification — Warn when compaction is imminent
cost-tracker · witness · PostToolUse — Estimate session token cost
cross-session-error-log · witness · PostToolUse — Persist error patterns across sessions
daily-usage-tracker · witness · PostToolUse — Track daily tool call count
edit-counter-test-gate · witness · PostToolUse — Require testing after N consecutive edits
edit-error-counter · witness · PostToolUse — Warn when Edit tool fails repeatedly
file-change-monitor · witness · PostToolUse — Track all files modified during a session
file-change-tracker · witness · PostToolUse — Track all file modifications in a session
mcp-tool-audit-log · witness · PostToolUse — Log all MCP tool calls for security auditing
model-version-alert · witness · unstated — Every 50th hook run, read the newest session log and alert when the active model is an older Opus 4.7 build
no-console-log · witness · PreToolUse — no description in the file header; open it before installing
no-sensitive-log · witness · PreToolUse — says: “WARNING: Logging sensitive data”
prompt-usage-logger · witness · UserPromptSubmit — Log every prompt with timestamps
read-audit-log · witness · PostToolUse — Log all file read operations for forensics
session-budget-alert · witness · SessionStart — Show session budget status on start
session-end-logger · witness · SessionEnd — Log session activity at exit
session-error-rate-monitor · witness · PostToolUse — Detect session quality degradation
session-health-monitor · witness · PreToolUse — Monitor session health metrics
session-memory-watchdog · witness · unstated — no description in the file header; open it before installing
session-quota-tracker · witness · PostToolUse — Track cumulative tool calls per session
session-token-counter · witness · PostToolUse — Track tool usage count per session
subagent-error-detector · witness · PostToolUse — Detect failed subagent results
token-usage-tracker · witness · unstated — no description in the file header; open it before installing
tool-call-rate-limiter · refuses · PreToolUse — Prevent runaway tool calls
tool-file-logger · witness · PostToolUse — Log file paths from Read/Write/Edit to stderr
usage-cache-local · witness · PostToolUse — This hook tracks tool calls locally so you can check usage without making an API call
worktree-create-log · witness · unstated — Append branch and path to ~/.claude/worktree-audit.log whenever a worktree is created

Recovery

Checkpoints, handoffs, and state written down before it can be lost.

32 scripts, of which 2 can refuse a call.

auto-checkpoint · witness · PostToolUse — Auto-commit after every edit for rollback protection
auto-git-checkpoint · witness · PreToolUse — no description in the file header; open it before installing
auto-push-session-branch · witness · unstated — Push the current branch to its upstream after each turn, skipping main/master/develop/release and detached HEAD; never fails the turn if the push is rejected
auto-snapshot · witness · PreToolUse — Automatic file snapshots before every edit
auto-stash-before-pull · witness · PreToolUse — Suggest stash before git pull/merge
backup-before-refactor · witness · PreToolUse — says: “NOTE: Stashed changes as pre-refactor backup”
checkpoint-tamper-guard · refuses · PreToolUse — Block manipulation of hook state/checkpoint files
context-compact-advisor · witness · unstated — no description in the file header; open it before installing
context-snapshot · witness · Stop — Save session state before context loss
file-change-undo-tracker · witness · FileChanged — Track file changes for easy undo
file-edit-backup · witness · PreToolUse — Auto-backup files before they are overwritten
file-recycle-bin · witness · PreToolUse — Move deleted files to recycle bin instead of permanent deletion
git-stash-before-checkout · refuses · PreToolUse — Auto-stash before risky git checkouts
git-stash-before-danger · witness · PreToolUse — Auto-stash before risky git operations
post-compact-restore · witness · Stop — Restore context after /compact
pre-compact-checkpoint · witness · PreCompact — Auto-save before context compaction
pre-compact-knowledge-save · witness · PreCompact — Save critical context before compaction
pre-compact-transcript-backup · witness · PreCompact — Backup transcript before compaction
pre-compact-transcript-export · witness · PreCompact — Export conversation before compaction
revert-helper · witness · Stop — Show revert command when session ends badly
ripgrep-permission-fix · witness · SessionStart — Auto-fix ripgrep execute permission on start
session-backup-on-start · witness · SessionStart — Backup session JSONL files on start
session-checkpoint · witness · Stop — Auto-save session state on every stop
session-handoff · witness · Stop — Auto-save session state for next session
session-index-repair · witness · Stop — Rebuild sessions-index.json on exit
session-resume-env-fix · witness · SessionStart — Fix CLAUDE_ENV_FILE path on session resume
session-resume-guard · witness · Notification — Verify context is loaded after session resume
session-state-saver · witness · PreToolUse — no description in the file header; open it before installing
session-summary · witness · PreToolUse — no description in the file header; open it before installing
session-summary-stop · witness · Stop — Print session change summary on stop
settings-auto-backup · witness · Notification — Auto-backup settings on session start
terminal-state-restore · witness · unstated — terminal-state-restore — restore terminal to clean state on session exit Fixes: bracketed paste mode, application cursor keys, cursor visibility, line wrapping, Kitty keyboard protocol left enabled after exit

UX

Everything that makes the session easier to sit through rather than safer.

51 scripts, of which 14 can refuse a call.

auto-answer-question · refuses · PreToolUse — Auto-answer AskUserQuestion for headless/autonomous mode
binary-file-guard · witness · PreToolUse — Warn when Write creates binary/large files
compact-reminder · witness · Stop — Remind to /compact when context is low
consecutive-error-breaker · witness · PostToolUse — Stop after N consecutive errors
consecutive-failure-circuit-breaker · witness · PostToolUse — Stop after repeated failures
context-threshold-alert · refuses · PostToolUse — Alert at configurable context usage thresholds
cwd-reminder · witness · PreToolUse — Remind Claude of the current working directory
dangling-process-guard · witness · Stop — Detect background processes left running
dependency-audit · witness · PreToolUse — Warn before installing unknown packages
diff-size-guard · refuses · PreToolUse — Warn on large uncommitted changes
disk-space-check · witness · Notification — Warn if disk space is low at session start
disk-space-guard · witness · PreToolUse — Warn when disk space is running low
encoding-guard · witness · PreToolUse — Warn when writing to non-UTF-8 files
error-memory-guard · refuses · PostToolUse — Detect repeated failed commands
file-size-limit · refuses · PreToolUse — no description in the file header; open it before installing
fish-shell-wrapper · refuses · PreToolUse — Run Bash tool commands in fish shell
five-hundred-milestone · witness · Notification — no description in the file header; open it before installing
git-show-flag-sanitizer · refuses · PreToolUse — Strip invalid —no-stat from git show
hook-debug-wrapper · refuses · unstated — Wraps any existing hook script and logs its input, output,
hook-stdout-sanitizer · refuses · unstated — When a hook writes to stdout (instead of stderr), the output gets concatenated into tool results like file paths, causing corruption (e.g., worktree path becomes “/path/to/repo{hookJSON}”)
large-read-guard · witness · PreToolUse — Warn before reading large files
long-session-reminder · witness · PostToolUse — Warn when session runs too long
loop-detector · refuses · PreToolUse — Detect and break command repetition loops
max-file-count-guard · witness · PreToolUse — no description in the file header; open it before installing
max-session-duration · witness · PostToolUse — Warn when session exceeds time limit
node-version-check · witness · Notification — Warn if Node.js version is too old
node-version-guard · witness · PreToolUse — Warn when Node.js version doesn’t match .nvmrc
notify-waiting · witness · Notification — Desktop notification when Claude needs input
output-length-guard · witness · PostToolUse — Warn when tool output is very large
parallel-edit-guard · witness · PreToolUse — Detect concurrent edits to same file
plan-mode-edit-guard · witness · PreToolUse — Warn when editing non-plan files during plan mode
plan-mode-enforcer · refuses · PreToolUse — Hard-enforce Plan Mode read-only constraint
plan-mode-strict-guard · refuses · PreToolUse — Hard-block all write operations during plan mode
plan-repo-sync · witness · PostToolUse — Sync plan files from ~/.claude/ into your repo
plugin-process-cleanup · witness · SessionEnd — Kill leaked plugin subprocesses on session end
prompt-injection-detector · witness · UserPromptSubmit — Detects common prompt injection patterns in user prompts
prompt-length-guard · witness · UserPromptSubmit — Warns when a user prompt exceeds a character threshold
rate-limit-guard · witness · PreToolUse — no description in the file header; open it before installing
read-before-edit · witness · PreToolUse — Warn when editing files not recently read
reinject-claudemd · witness · SessionStart — Re-inject CLAUDE.md content after compact
session-time-limit · witness · PostToolUse — Warn when session exceeds time limit
skill-gate · refuses · PreToolUse — no description in the file header; open it before installing
stale-branch-guard · witness · PostToolUse — Warn when working on a stale branch
stale-env-guard · witness · PreToolUse — Warn when .env files are very old
system-message-workaround · witness · PreToolUse — Get a non-blocking hook warning in front of the user
temp-file-cleanup · witness · Stop — Cleans up temporary files created by Claude Code sessions
temp-file-cleanup-stop · witness · Stop — Clean up tmpclaude-* files on session end
tmp-cleanup · witness · Stop — Clean up /tmp/claude-*-cwd temp files
token-budget-guard · refuses · PostToolUse — Estimate and limit session token cost
token-budget-per-task · witness · PostToolUse — Track and warn on per-task token usage
virtual-cwd-helper · witness · PreToolUse — Remind about virtual working directory

Other

Scripts that did not fit the groups above.

2 scripts, of which 0 can refuse a call.

mcp-warmup-wait · witness · SessionStart — Wait for MCP servers to be ready on start
token-spike-alert · witness · PostToolUse — Alert on abnormal token consumption per turn

Uncategorised

261 scripts, of which 116 can refuse a call.

account-billing-log · witness · Stop — Append per-session line to a billing log indexed by Anthropic account label
account-routing-preflight · refuses · SessionStart — Refuse session when the active Anthropic account doesn’t match the project’s declared expectation
activity-logger · witness · unstated — Log all tool uses to JSONL for audit and debugging
agent-sdk-credit-pool-monitor · witness · unstated — track claude -p usage against the June 15 credit pool cliff
agent-view-quota-decrement · witness · PostToolUse — Decrement Task counter on completion
agent-view-quota-warn · witness · PreToolUse — Warn on parallel Task spawn quota burn
agents-md-edit-drift-warner · witness · PostToolUse — Warn at the moment CLAUDE.md (or AGENTS.md) is edited that the sibling instruction file is now stale. Complements the SessionStart-only agents-md-sync-checker (PR #377) with a PostToolUse signal at the actual drift event
agents-md-loader · witness · SessionStart — Detect AGENTS.md in the project tree at session start and surface its contents to Claude Code as a system-reminder, so the agent reads it alongside (or in place of) CLAUDE.md
agents-md-sync-checker · witness · SessionStart — Warn when AGENTS.md and CLAUDE.md drift apart
ai-slop-punctuation-arrest · refuses · PreToolUse — Refuse Write/Edit to public-text files that contain AI-slop punctuation patterns the operator has chosen to exclude — em-dash (—) and the double-hyphen substitute the model often emits when prose-instructed to “stop using em dashes”
always-allow-pattern-suggester · witness · PreToolUse — Suggest wildcard patterns instead of verbatim “Always Allow” rules
anthropic-base-url-guard · refuses · PreToolUse — Block execution when ANTHROPIC_BASE_URL is suspicious
api-busyloop-guard · refuses · PreToolUse — Stop a single Bash command that busy-polls a rate-limited API in an unbounded loop with no delay
articulated-scope-capture · witness · UserPromptSubmit — Capture user prompt’s sha256 + byte length as the operator-instrumented Mode 2.6 (Action-Reasoning Mismatch) primitive
askuserquestion-autonomy-gate · refuses · PreToolUse — Block AskUserQuestion in autonomy mode
attachment-traversal-guard · refuses · UserPromptSubmit — Block @../ attachment bypass
aup-block-pattern-logger · witness · PostToolUse — Persist Usage Policy classifier blocks across sessions
aup-false-positive-helper · witness · unstated — Surface the AUP false-positive cluster awareness when Opus models are pinned
aup-large-tool-output-warner · witness · unstated — Warn before Bash commands that may produce large sensitive-looking outputs that can trigger the Cluster 9 Usage Policy classifier
aup-retry-loop-guard · witness · unstated — Detect retry-loop pattern during Cluster 9 blocks and recommend exit
auth-expiry-reminder · witness · unstated — Daily checkpoint reminder for authentication-state verification in long-running Claude Code sessions (Cluster 19 candidate, axes 19C / 19G)
auth-macos-sleep-detector · witness · unstated — Detect recent macOS sleep/wake and advise auth re-verification (Cluster 19 candidate, axis 19B — macOS sleep/wake silent auth invalidation)
auth-path-detector · refuses · PreToolUse — Warn before driving an auth/login flow, especially on a resource that the user did not explicitly authorize
auth-status-checker · witness · unstated — Surface the Cluster 19 candidate (Authentication Silent Failure) situation at session start for operators running long sessions or 3P credential chains
authorized-reconfirmation-detector · witness · Stop — Measure how often AskUserQuestion fires on an action that the operator’s prior turn already authorized
auto-compact-context-monitor · witness · PostToolUse — Detect unexpected auto-compaction via context size drops
auto-mode-safety-enforcer · refuses · PreToolUse — Block dangerous operations in auto/acceptEdits mode
background-cost-launch-guard · refuses · PreToolUse — Block a background Bash launch that can incur ongoing API/compute cost and would keep running after the model says “Done”
background-task-guard · refuses · PreToolUse — Audit background Bash execution
bash-allowlist-secondary-check · refuses · PreToolUse — Re-check Bash commands against the user’s settings.json allowlist
bash-fanout-bounded-rewriter · refuses · PreToolUse — Detect and refuse unbounded bash fan-out patterns that can spawn thousands of subprocesses
bash-project-fence · refuses · PreToolUse — Block Bash commands that reach outside the project root
bg-permission-prompt-warner · witness · unstated — Warn operators dispatching claude --bg that background sessions stall on permission prompts even under acceptEdits (Cluster 24 candidate, axis 24A — non-interactive permission gap)
binary-read-detector · refuses · UserPromptSubmit — Surface image / PDF / binary path references in user prompts before they reach the vision dispatch bus that bypasses PreToolUse hooks
broad-find-guard · refuses · PreToolUse — Block overly broad find/locate commands that scan the entire home directory
broad-prefix-session-trap-warner · witness · PreToolUse — Cluster 6 Axis 8 Warn before a broad static ask rule is session-approved
bypass-mode-effective-verifier · witness · SessionStart — Warn when bypass mode is actually in effect
cache-creation-drift-detector · witness · PostToolUse — alert when per-request cache_creation drifts above baseline
cache-creation-spike-detector · witness · unstated — no description in the file header; open it before installing
cache-residue-detector · witness · SessionStart — Detect leftover server-side injection caches that persist after opt-out env vars are set
cache-tier-logger · witness · PostToolUse — cache TTL regression detector (Incident 1) Why: March 2026 regression silently downgraded the prompt-cache TTL from 1h to 5m (ephemeral_5m), causing cache re-creation every turn. Users saw quota burn at 4-5x without any client-side change. Issue #46829 (119,866-call dataset), #46917 (cache_creation inflation)
cache-ttl-eviction-detector · witness · PostToolUse — alert when long idle gaps cause prompt-cache TTL eviction
case-insensitive-path-guard · refuses · PreToolUse — Detect path case mismatches on case-insensitive filesystems
cch-sentinel-precommit-guard · witness · unstated — native sentinel content guard (Incident 3) Why: The standalone Bun Claude Code binary substitutes the literal string cch=00000 at the native layer — below anything the JavaScript hook surface can intercept. Committing the literal into a file Claude reads triggers cache invalidation patterns and a 10-20x cost multiplier on
cjk-punctuation-guard · witness · PostToolUse — Detect CJK punctuation corruption after Write/Edit
claim-verify-detector · refuses · Stop — detect decisive language without verification
claim-vs-caveat-checker · refuses · Stop — Detect confident claims that may contradict earlier caveats in the same session
claude-code-version-pin-advisor · witness · SessionStart — SessionStart advisory for Cluster 16 (v2.1.154+ messages role ‘system’ API 400)
claude-md-reinjector · witness · PreToolUse — Re-inject CLAUDE.md to counter instruction drift
claude-md-size-monitor · witness · SessionStart — Warn when CLAUDE.md exceeds the token budget
claude-update-budget-guard · refuses · unstated — warn/block claude update when 5h quota is tight
claude-update-smart · refuses · unstated — skip 226 MB tarball download when already up-to-date Why: claude update downloads the full ~226 MB release tarball on every invocation, even when the installed version is already latest (Issue #51243, opened 2026-04-20, platform:wsl, status:open). A typical connection sees ~30 s wall time per update check and silently burns
claudemd-tool-prohibition · refuses · PreToolUse — Block tool calls that the operator’s CLAUDE.md explicitly prohibits
cli-config-pinning-detector · witness · unstated — Detect Anthropic CLI config that silently pins organization_id and overrides Claude Code auth routing (Cluster 19 candidate, axis 19H — local-side credential override)
cliff-countdown-advisor · witness · unstated — cliff-countdown-advisor.sh
clipboard-secret-guard · refuses · PreToolUse — Block secrets from being copied to clipboard
closure-word-verify-gate · refuses · Stop — Stop the turn if a closure word (“done”, “shipped”, “complete”, “production ready”, “bitti”, “finished”) was used without a corresponding verification tool call in the same turn
commit-all-scope-guard · witness · PreToolUse — Surface the full scope before a “commit everything” so in-progress work isn’t swept into a commit
commitment-carry-forward-arrest · refuses · Stop — Row 7 operator-side substrate
compact-circuit-breaker · refuses · PreCompact — Prevent auto-compact death spirals
compact-dispatch-watchdog · witness · Stop — Warn when context usage crosses a configurable threshold without a recent compact_boundary
completion-claim-without-verification-detector · witness · Stop — done without testing — 12 days, 51 commits, still broken (Opus 4.x)“. Across approximately fifty sessions over twelve days, the agent repeatedly said “done, ready to test” without running any verification step. Approximately 70% of the period’s commits were fix-of-prior-commit rather than progress. The user’s
compound-bash-permission-resolver · witness · PreToolUse — Per-component allow-rule check for compound bash
compound-command-deny-enforcer · refuses · PreToolUse — Enforce deny rules across compound commands
context-length-budget · witness · unstated — long-context retrieval regression guard (Incident 6) Why: Opus 4.7 shows significant retrieval accuracy regressions above 200K tokens of context (MRCR -46pt, 256k-8-needle -32.7pt). This hook tracks cumulative input-token usage across a session and emits an advisory when the budget threshold is crossed, so you can split the
context-size-alert · witness · PostToolUse — Warn when context window usage exceeds threshold
context-usage-drift-alert · witness · unstated — says: “Save important state to files NOW. Run /compact manually to control what’s kept”
cost-incident-self-audit · witness · unstated — Tell me which real Claude Code cost accidents my current setup is still exposed to
cowork-claude-md-load-checker · witness · SessionStart — Surface ~/.claude/CLAUDE.md at SessionStart
cowork-fuse-staleness-watcher · witness · PreToolUse — Warn before bash git ops in Cowork FUSE mounts
cowork-hook-absence-warner · witness · SessionStart — Warn CLI operators with a non-trivial ~/.claude/settings.json hook stack that the Cowork sandbox silently drops every one of those hooks
cowork-model-picker-advisor · witness · SessionStart — Surface the Cowork Sonnet 4.6 [1m] silent default at SessionStart so CLI users do not accidentally burn usage credits
cron-create-receipt · witness · PostToolUse — Log every CronCreate registration
cross-product-mcp-spawn-detector · refuses · SessionStart — Warn when MCP server spawn configs exist in cross-product state paths outside Claude Code
daemon-zombie-worker-surfacer · witness · SessionStart — Surface orphaned / zombie background workers at session start via claude daemon status
daily-cost-guard · refuses · Stop — Track per-day API-equivalent token cost and warn / block when the daily budget is exceeded
dangerous-pip-flag-guard · refuses · PreToolUse — Block dangerous pip flags that bypass safety
decision-warn · witness · unstated — Warn and log irreversible operations
deny-bypass-detector · refuses · PostToolUse+PreToolUse — Detect when Claude circumvents a hook denial
deny-rule-integrity-verifier · refuses · PreToolUse — Catch deny-rule bypasses through whitespace normalization
deployment-readback-gate · refuses · Stop — Refuse a deployment-completion claim unless an authority confirms it, recently
deployment-readback-gh-adapter · witness · Stop — gh deployments provider adapter for deployment-readback-gate
destructive-db-script-write-guard · refuses · PreToolUse — Catch a destructive DB operation written into an application SCRIPT, before the script is ever run
destructive-migration-write-guard · refuses · PreToolUse — Catch a destructive schema migration at the moment it is WRITTEN, before it is run
disabled-feature-toggle-advisor · witness · SessionStart — SessionStart advisory that surfaces feature DISABLE / opt-out toggles set in your settings.json env block, so you notice one a plugin installer flipped without telling you
dispatch-allowlist-preflight · refuses · PreToolUse — Pre-flight MCP tool allowlist propagation check for background sub-agent dispatches
dispatch-liveness-watchdog · refuses · PreToolUse — Surface in-flight sub-agent dispatches that have been running longer than a configurable threshold, so operators see the hang before they have to kill the session at the OS level
dispatch-receipt · refuses · PreToolUse — Receipt-and-refuse layer for agent dispatch operations
dotenv-anthropic-key-billing-guard · refuses · SessionStart — Warn when project .env contains ANTHROPIC_API_KEY
dotenv-read-guard · refuses · PreToolUse — Block Read/Glob/Grep of .env files
dotfile-protection-guard · refuses · PreToolUse — Block writes to critical dotfiles
echo-probe-spam-detector · refuses · unstated — Block Opus 4.8 echo-probe spam bursts (Cluster 25 candidate, axis 25B — tool-result delivery compensation)
edit-quote-ambiguity-guard · witness · PreToolUse — Block an Edit that is ambiguous under the tool’s own quote-normalization, so it can’t silently change the wrong line
effort-tracking-logger · witness · unstated — no description in the file header; open it before installing
ephemeral-container-detector · witness · SessionStart — Warn operators when Claude Code is starting inside an ephemeral container where MCP approval state will not persist across container recreations
evidence-claim-gate · refuses · Stop — Stop the turn when the assistant claims that evidence was collected (“I tested”, “verified”, “tests pass”, “confirmed”, “checked that”, “validated”) without a corresponding evidence-gathering tool call in the same turn
exploration-budget-guard · refuses · PreToolUse — Stop excessive exploration from draining tokens
extended-thinking-loop-guard · refuses · SessionStart — Hard-block a Cluster 13A resume when the session is running under an autonomous-loop / headless-resume harness
extended-thinking-resume-warning · witness · SessionStart — Warn before resuming a session whose transcript carries the 13A precursor
extended-thinking-tool-use-mismatch-detector · witness · PostToolUse — Warn when the structural 12B pattern is detected in the trailing transcript: assistant turns with stop_reason=“tool_use” but no parseable tool_use block in content (only thinking and/or text blocks)
fabricated-command-detector · refuses · Stop — Detect command-shaped tokens in the final assistant response that were never invoked as Bash tool calls in the session
false-disk-full-guard · witness · PostToolUse — flag the #65880 false “temp filesystem is full” / ENOSPC report
feature-deprecation-detector · witness · PostToolUse — Detect Claude Code feature deprecations from tool output
financial-operation-guard · refuses · PreToolUse — Block unauthorized financial operations
flask-static-route-guard · witness · PreToolUse — Warn when a catch-all static route would expose .env / .git / source / db files to the web
forbidden-response-phrase-detector · refuses · Stop — Detect operator-declared forbidden phrases in the assistant’s final response
full-rewrite-detector · witness · PostToolUse — Warn on full-file rewrites
git-filter-repo-guard · refuses · PreToolUse — Block git history rewriting tools
git-maintenance-guard · refuses · PreToolUse — Block automatic git maintenance
git-pack-temp-cleanup-guard · refuses · PreToolUse — Stop tmp_pack_* explosion
git-push-blast-radius-guard · witness · PreToolUse — Cap a runaway fan-out of git pushes that burns CI minutes
git-rm-orphan-wipe-guard · refuses · PreToolUse — Block whole-working-tree deletion via git
goal-iteration-limit-warner · refuses · UserPromptSubmit — Warn before /goal command without iteration termination
growthbook-flag-monitor · witness · SessionStart — Surface server-pushed GrowthBook flag changes that silently override client-side state
halt-signal-detector · refuses · PreToolUse — no description in the file header; open it before installing
handoff-on-clear · witness · SessionEnd — Write a handoff note at /clear, before the context goes
home-critical-bash-guard · refuses · PreToolUse — Block Bash commands that delete/modify critical home files
hook-self-disable-detector · witness · SessionStart — Background: Claude Code sessions can edit settings.json and remove hooks that were previously active. Over weeks of accumulation this can silently disable safeguards. One documented case: a Claude Code session disabled its own early-detection hook, and 193 GB of WSL bloat accumulated before the operator noticed. See drafts/active/2026-05-16-self-disabled-safeguard-wsl-bloat.md
idle-session-cost-alert · witness · unstated — Warn when session has been idle too long An idle session can still consume tokens via background processes
image-dimension-guard · witness · PreToolUse — Block Read of oversized images that trigger a costly retry loop
iteration-quality-degradation-detector · refuses · PostToolUse — Warn when the same file is being edited repeatedly across turns
long-session-malformed-tool-call-detector · witness · PostToolUse — Warn when a “malformed and could not be parsed” marker is detected in the trailing transcript window, surfacing sub-pattern 12A (in-context few-shot poisoning) before the operator hits the “retry also failed” terminal state
mcp-config-poisoning-audit · witness · SessionStart — Read-only audit for supply-chain poisoning of your Claude Code config (NOT prevention of Claude’s own edits — that’s hook-tamper-guard / mcp-config-freeze)
mcp-misdiagnosis-arrest · refuses · Stop — Catch the assistant misdiagnosing a silently- dropped MCP connector as “the connector isn’t installed”, and surface the actual recovery path before the operator wastes a reinstall round-trip
mcp-orphan-leak-warner · witness · SessionStart — At session start, warn if leaked MCP / sub-agent server processes from earlier sessions are still alive and piling up, before they exhaust RAM/swap into an OOM / kernel panic
mcp-permissions-ask-warner · refuses · SessionStart — Warn when permissions.ask has MCP entries
mcp-routine-approval-detector · witness · PostToolUse — Surface the May 2026 routine-approval cluster
mcp-startup-bloat-detector · witness · SessionStart — Warn when claude.ai connector sync inflates the System tools context at session start
mcp-stdio-compatibility-test · refuses · unstated — MCP regression test harness (Incident 8) Why: v2.1.105 changed PreToolUse additionalContext + stdio framing and broke MCP servers that had worked on v2.1.104. The regression was largely fixed by v2.1.118 but custom MCP servers still need re-validation after every Claude Code upgrade. This harness
memory-chain-audit · witness · unstated — extractMemories double-cache detector (Incident 7) Why: Claude Code’s extractMemories feature fires a background call at the end of each turn to update persistent memory. When the default is ON, this background call carries its own cache chain that roughly doubles the API cost per turn. Users who have not set
memory-orphan-detector · witness · SessionStart — Detect Claude Code memory that may have been orphaned when the working directory was renamed
model-swap-suggester · witness · unstated — Evidence-driven swap recommendation for the AUP false-positive cluster
model-version-change-alert · witness · unstated — says: “Your model was switched. This affects token consumption, quality, and hook behavior”
model-version-lock · witness · unstated — silent mid-session downgrade detector (Incident 4) Why: Opus 4.7 sessions sometimes migrate mid-session to a different model (for example the 1M-context automatic switch, #49541) with no client- visible announcement. The downgrade silently changes token accounting, context window, and quality. This hook writes a lock file containing
move-delete-sequence-guard · refuses · PreToolUse — Detect move+delete sequences that cause data loss
multi-file-plan-routing-gate · refuses · PreToolUse — Refuse Write/Edit when the current session has touched N or more distinct files without a written plan, route the work through plan-mode before further writes land
multi-vendor-concurrent-warner · witness · SessionStart — Warn when another AI coding CLI (Codex, Gemini, Cursor, Aider, Amp, …) is running at the same time as Claude Code, so concurrent edits to the same repo do not silently collide
multi-window-auth-drift-detector · witness · unstated — Detect on-disk credentials drift mid-session (Cluster 19 candidate, axis 19E — multi-window /account state inconsistency)
nested-background-agent-guard · refuses · PreToolUse — Refuse background agent spawns from inside a sub-agent
nested-spawn-inflight-guard · refuses · unstated — Refuse Task/SendMessage dispatch when too many subagents are already in flight
non-english-quality-warner · witness · unstated — Surface the Cluster 15 non-English output quality regression at session start for operators working in non-English languages with Opus 4.7
oauth-refresh-monitor · witness · PostToolUse — Detect OAuth refresh corruption patterns in tool output and warn before the operator hits the persistent 401 loop (Cluster 19 candidate, axis 19A)
opus-degradation-tracker · witness · unstated — Personal Opus 4.7 pass-rate tracker that alerts on statistical degradation
opus48-routine-task-warning · witness · unstated — Surface the Cluster 23 candidate (Opus 4.8 effort-budget regression) at session start for operators running Opus 4.8 on routine coding workflows
opus48-thinking-wedge-advisor · witness · Notification — Warn when a mid-conversation model swap from Opus 4.7 to Opus 4.8 is about to hit the Cluster 13 Axis G hard 400
output-token-spike-detector · witness · PostToolUse — alert when per-request output_tokens spikes above baseline
parallel-batch-size-limiter · witness · PreToolUse — Surface large parallel batches
parallel-cascade-detector · witness · PostToolUse — Detect parallel-batch cascade
partial-view-claim-arrest · refuses · Stop — Stop the turn when the model claims about the whole file after Read returned a “PARTIAL view” notice
per-prompt-token-cap · refuses · PostToolUse — Detect single-prompt quota burnout
persisted-1m-model-advisor · witness · SessionStart — Warn at SessionStart when a 1M-context model is PINNED in your settings or default-model env vars (the reason /clear and restarts don’t reduce your usage)
pii-upload-guard · witness · PreToolUse — Detect PII in outbound data before upload
plugin-hooks-json-bloat-detector · witness · SessionStart — Detect duplicated hook registrations inside plugin hooks.json files (additive growth from the multi-agent dispatch path)
post-edit-disk-verify · refuses · unstated — Catch “Edit/Write reported success but didn’t persist to disk” silent failures at the tool boundary
powershell-remove-item-guard · refuses · PreToolUse — Block PowerShell recursive deletion that traverses junctions
pr-duplicate-guard · refuses · unstated — says: “Update the existing PR instead of creating a new one”
pre-bash-sed-line-ending-windows · refuses · PreToolUse — Block sed -i on Windows/Git Bash
pre-execution-claim-detector · witness · unstated — Surface the Cluster 22 candidate (Opus 4.8 pre-execution tool-output fabrication, Axis 22A) at PreToolUse, by scanning the last assistant text block for specific-value claim signatures that precede the tool call about to fire
production-port-kill-guard · refuses · PreToolUse — Block commands that kill processes by port number
proof-log-session · witness · unstated — Generate session summary on Stop event
proxy-capture-suggester · witness · unstated — Surface HTTPS proxy capture path for compliance-bound operators
public-artefact-socratic-narrowing · refuses · PreToolUse — Inject a Socratic-narrowing prompt at the public-artefact emission boundary, asking the agent to re-engage the gradient on decisions in the artefact before it ships
quota-anomaly-detector · witness · PostToolUse — alert when token consumption rate diverges from your personal baseline
quota-reset-audit · witness · unstated — weekly quota reset cluster logger (Incident 9) Why: On 2026-04-23 users reported /usage showing quota available while sessions were being rate-limited. Client-side vs server-side timezone handling of the weekly reset diverged. The dashboard’s resets_at value is the only ground truth available to users, and
quota-reset-cycle-monitor · witness · unstated — says: “Known issue: reset cycle may change without notice (#49599)”
read-loop-detector · witness · PostToolUse — Surface same-file Read loops within a session
read-once-guard · refuses · PreToolUse — Warn when Claude re-reads a file already in context
record-read-coverage · witness · PostToolUse — Record how much of each file was read
redirect-fragment-warner · refuses · unstated — Warn / block Bash commands using 2>&1 (Cluster 25 candidate, axis 25C — permission-engine & fragmentation hang)
redundant-read-blocker · refuses · PreToolUse — Prevent the model from re-reading files it has already read recently in the same session
refusal-arrest-gate · refuses · PreToolUse — Block the next tool call if the assistant’s prose in the same turn explicitly refused that action (“I won’t modify X”, “I’ll skip X”, “I’ll preserve X”) and the tool call contradicts the refusal
remote-control-billing-classifier · witness · SessionStart — Warn at session start when the parent process tree includes claude remote-control, so the operator knows the spawned claude --print child will draw from the new Agent SDK monthly credit (Pool 2) starting June 15, 2026, separate from interactive usage limits
repo-visibility-guard · refuses · unstated — Block repository visibility changes Prevents Claude Code from making private repos public (or vice versa)
reroute-after-block-guard · refuses · PreToolUse — Stop “reroute after a block”
resume-drift-watcher · witness · unstated — resume attachment relocation detector (Incident 2) Why: v2.1.69–v2.1.89 had a bug where —resume would relocate the original attachment payload out of messages[0] and into a later turn. The bug was marked fixed but residual drift still shows a tiny messages[0] (~350 bytes) when a resumed session is working correctly. A session
rg-replace-flag-detector · refuses · PreToolUse — Warn when Claude reaches for rg -r thinking it means recursive
rhetorical-verification-prompt-detector · witness · UserPromptSubmit — confirmed“. User asked a verification question; agent emitted an unconditional confirmation without running any verification step
route-handler-emptiness-gate · refuses · PreToolUse — Refuse Write/Edit when a route handler method body would ship with the surface form of a handler (auth + redirect + return) but with no data-mutation line (no save, update, create, insert, delete)
runtime-binary-change-detector · witness · SessionStart — Alert when the Claude Code binary changes between sessions
same-command-repeat-detector · refuses · unstated — Block Opus 4.8 same-command repeat-execution (Cluster 25 candidate, axis 25F — non-no-op compensation repeat)
same-correction-arrest · witness · UserPromptSubmit — Arrest drift by detecting the user repeating the same correction N times in a session, then refusing further code-writing tool calls until a Plan has been written
sandbox-denywrite-enforcer · refuses · PreToolUse — Enforce denyWrite rules for Write/Edit tools
sandbox-relative-path-audit · witness · PreToolUse — Catch sandbox filesystem rules that look set but do nothing
scope-expansion-receipt · refuses · PreToolUse — Receipt-and-refuse layer for destructive operations outside scope
secret-file-write-guard · refuses · PreToolUse — Block writing to secret files via Bash
server-side-prompt-injection-detector · witness · unstated — Detect missing opt-outs for v2.1.150+ server-side system prompt injection
session-agent-cost-limiter · refuses · PreToolUse — Cap total subagent spawns per session
session-cost-alert · refuses · PostToolUse — Alert when estimated session cost exceeds threshold
session-persistence-verifier · refuses · unstated — no description in the file header; open it before installing
session-plugin-pin-watch · witness · SessionStart — Detect when a marketplace plugin’s pinned hooks silently die
session-rate-monitor · witness · PostToolUse — alert when a single session’s token burn rate exceeds an absolute ceiling
session-start-quota-status · witness · SessionStart — Compute a real-time approximation of the operator’s recent token usage from local JSONL transcripts and surface it to Claude Code at session start, so the operator sees their quota posture before issuing the first prompt
settings-hooks-key-restorer · witness · SessionStart — Detect silent loss of top-level hooks key in settings.json
settings-integrity-monitor · witness · PreToolUse — Detect unexpected settings.json changes
settings-json-health-check · refuses · unstated — settings corruption guard (Incident 10) Why: A malformed settings.json can silently break the session (hook definitions ignored, permissions reset to defaults) and the built-in /doctor diagnostic can be dismissed by the user, leaving no warning
settings-json-model-guard · witness · PreToolUse+PostToolUse — Backup settings.json before /model changes
settings-regression-tester · refuses · SessionStart — Detect Claude Code version bumps that may have silently reset permission rules
shell-config-truncation-guard · refuses · PreToolUse — Block writes that would truncate shell config files
skill-cumulative-size-detector · witness · SessionStart — Detect cumulative skill descriptions size approaching the silent-drop threshold
skill-description-drop-detector · witness · SessionStart — Detect silent SKILL.md description drops above cumulative-size threshold
skill-truncation-detector · witness · SessionStart — Restore the Skill-listing truncation warning that v2.1.144 silently removed
skills-context-recorder · witness · UserPromptSubmit — Record active skill at each user prompt for hook integration
skills-load-verifier · witness · SessionStart — Warn when a SKILL.md cannot be loaded
skills-settings-validator · witness · SessionStart — Detect fabricated Skills-related settings fields in settings.json with no validation
sonnet-45-deprecation-helper · witness · unstated — Surface model lifecycle awareness when Claude.ai removes Sonnet 4.5
spurious-malformed-notice-detector · witness · PostToolUse — Warn when “malformed and could not be parsed” notices co-occur with successful tool executions in the trailing transcript window, signalling sub-pattern 12C (the harness-layer spurious notice)
sql-bulk-delete-warn · refuses · PreToolUse — sql-bulk-delete-warn: warn when a SQL DELETE/UPDATE statement is about to run via psql / mysql / sqlite3 / sqlcmd without a row-count safeguard
stale-temp-settings-detector · witness · SessionStart — Warn when /tmp holds a stale claude-settings file owned by a different local user
standing-rule-session-surfacer · witness · SessionStart — Surface standing rules from user’s auto-memory files on every SessionStart so the model cannot “load but forget” them across a long session
stop-hook-sigterm-wrapper · refuses · unstated — Wrap the claude CLI so an external supervisor can distinguish “completed” from “killed mid-work” when SIGTERM (e.g. timeout exit code 124) bypasses the configured Stop hook
stop-transcript-write-health · witness · Stop — Detect a silently stalled or reverted transcript
subagent-blast-radius-guard · refuses · PreToolUse — Surface and gate the files a sub-agent actually writes, at the moment it writes them
subagent-boundary-precheck · refuses · PreToolUse — Warn when Task delegation lacks explicit boundary statements
subagent-closure-verify-gate · refuses · Stop — Refuse the Stop event if the assistant narrates sub-agent completion (“the sub-agent completed”, “all agents returned”, “I dispatched X sub-agents and they finished”) without a corresponding Agent-tool call in the same turn
subagent-destructive-git-guard · refuses · PreToolUse — Warn when subagent prompt lacks destructive-git boundary
subagent-identity-leak-guard · refuses · PreToolUse — Warn when subagent delegation lacks identity boundary enforcement
subagent-identity-reassertion · witness · PreToolUse — Re-assert subagent identity to mitigate parent-context leak
subagent-inheritance-tester · refuses · SessionStart — Audit subagent frontmatter for missing tool boundaries and non-functional memory directives
subagent-permission-mode-guard · refuses · PreToolUse — Warn when Agent tool’s mode parameter conflicts with sub-agent frontmatter permissionMode
subagent-spawn-rate-monitor · witness · unstated — says: “Each spawn costs ~4.7K tokens at 1.25x rate (no cache_control)”
subagent-spawn-verification-enforcer · refuses · PreToolUse — Warn when subagent prompt lacks output verification
subagent-tool-allowlist-enforcer · refuses · PreToolUse — Warn when subagent prompt lacks tool allowlist boundary
subcommand-chain-guard · refuses · PreToolUse — Block commands with excessive subcommand chains
subscription-api-billing-warner · witness · SessionStart — Warn at session start when the active configuration will silently bill API / purchased credits above a Claude Pro/Max subscription, so a subscriber does not keep draining pay-per-token credits while subscription quota sits unused
subscription-bypass-detector · witness · SessionStart — subscription accumulated approximately USD 1,050 in API charges across nine auto-refills over three days (2026-05-05 to 2026-05-07) because a dotenv-loaded ANTHROPIC_API_KEY silently overrode the subscription path. The UI displayed “Sonnet” throughout while billing routed through API-key Opus pricing. The operator had no
system-dir-protection-guard · refuses · PreToolUse — Block destructive operations on system directories
temporal-suggestion-detector · refuses · Stop — Stop hook. Detects “rest / break / sleep” suggestions Claude inserts at inappropriate times-of-day, and logs them to disk for later inspection. Does NOT block. Advisory only
thinking-budget-effort-mismatch-detector · witness · PostToolUse — Alert when output_tokens for a single turn exceeds the budget that the declared effort tier should imply
thinking-display-enforcer · witness · unstated — no description in the file header; open it before installing
thinking-stall-detector · witness · PreToolUse — Detect when Claude’s thinking phase stalls
tokenizer-ratio-alert · witness · UserPromptSubmit — Opus 4.7 tokenizer inflation monitor (Incident 5) Why: Opus 4.7 encodes the same prompt 1.35-1.46x larger than Opus 4.6 (Anthropic stated ceiling 1.35, Simon Willison independent verification 1.46 for system prompts). If you have pinned 4.6 but want to verify token accounting is actually on 4.6, this hook measures the ratio by
tokenizer-ratio-alert-corpus · witness · PostToolUse — no description in the file header; open it before installing
tool-result-correlation-checker · witness · PostToolUse — Detect tool-result misattribution
tool-result-size-guard · refuses · PreToolUse — Block or warn on Bash commands likely to produce oversized output
tool-retry-budget-guard · refuses · PreToolUse — Stop Claude from wasting tokens on repeated failures
transcript-contamination-detector · witness · SessionStart — Detect synthetic entries injected into session transcript .jsonl files by the /resume contamination bug
trustfall-mcp-injection-guard · refuses · SessionStart — Detect TrustFall-style MCP injection settings
ultrareview-large-diff-advisor · witness · SessionStart — SessionStart advisory for Cluster 18 candidate (/ultrareview crash burns credit on large PRs)
unbounded-output-guard · refuses · PreToolUse — Block commands that generate unbounded output before they run (PreToolUse)
userprompt-submit-receipt · witness · UserPromptSubmit — Companion log for the operator’s articulated scope at the prompt boundary, joinable to dispatch / bash / edit receipts
verify-after-publish-reminder · witness · PostToolUse — Remind to verify persisted state after publish commands
version-bump-detector · witness · SessionStart — at SessionStart and surface them so the operator can correlate quota or behavior anomalies with the version change
version-regression-warner · witness · SessionStart — for the currently-running Claude Code version on SessionStart
warn-cron-cost-trap · witness · PostToolUse — Warn on cost-trap scheduled tasks
webfetch-runaway-guard · witness · PreToolUse — Cap a runaway sequence of WebFetch tool calls that burns cost
wellness-break-reminder · witness · PostToolUse — Remind the user to take a body break
windows-destructive-command-guard · refuses · PreToolUse — Block Windows-side destructive command escalation chains
windows-python-stub-detector · witness · SessionStart — Detect Microsoft Store python3 stub at session start
workspace-lease-guard · refuses · PreToolUse — Out-of-process workspace ownership lease, with compare-and-delete release and heartbeat takeover for crashed siblings
worktree-branch-pollution-detector · witness · unstated — says: “This may be caused by a worktree or subagent switching your branch”
worktree-edit-boundary-guard · refuses · PreToolUse — Warn or block when Edit/Write/NotebookEdit targets a path outside the active git worktree boundary
worktree-escape-write-guard · refuses · PreToolUse — Block Edit/Write that escape the active worktree and silently land on the main checkout
worktree-hook-linker · witness · Notification — Auto-link settings to worktrees
worktree-hooks-path-fix · witness · SessionStart — Unset bogus per-worktree core.hooksPath that Claude Code’s EnterWorktree harness writes, so Husky / lefthook / pre-commit hooks fire in worktrees the same way they do in the main checkout
worktree-parent-write-guard · refuses · unstated — says: “BLOCKED: write target is in the PARENT repo, not the active worktree”
worktree-remove-uncommitted-guard · refuses · unstated — says: “Commit or stash changes before removing”
write-byte-integrity-verifier · refuses · PostToolUse — Detect silent file truncation after Write/Edit
write-empty-content-guard · refuses · PreToolUse — Block clearing an existing non-empty file with empty content
write-nul-corruption-detector · refuses · PostToolUse — Detect NUL-byte corruption after Write/Edit
wsl-host-disk-space-guard · refuses · PreToolUse — Watch the WSL host (Windows C:) too
xml-format-leak-detector · witness · PostToolUse — Warn when legacy XML tool-use format markers leak into tool_use input fields in the trailing transcript, signalling sub-pattern 12D (the long-payload attention-dilution decoder flip)

What happens when a Claude Code hook is broken or not working (Chapter 9)

Up next

What —dangerously-skip-permissions actually skips, and what still stops you (Chapter 11)