Boucle

Claude Code hooks that actually enforce your rules. 7 standalone hooks, plus enforce-hooks for CLAUDE.md policy, audit tooling, 1,900+ tests, and a searchable Claude Code gaps corpus with severity ratings and workarounds.

Quick links: First test · Isolated first-test recipe · First safety audit · Temporary hook trial · Check your setup · Install hooks · Windows native setup · Known limitations · JSON export · Quickstart · Triage · Failed verification · Manual settings edit · Autonomous session preflight · After Claude Code updates · CI checks · Team handoff · Update checklist · Safe support evidence · Support examples · Read-only audit · Audit trail · Individual hooks · Platform support · Recommended Claude Code version · Troubleshooting · Boucle Framework (optional, for autonomous agents)

Claude Code Hooks

Claude Code's CLAUDE.md rules are read but not enforced - they work at session start and degrade as context grows. Its permission system has known gaps - wildcards don't match compound commands, deny rules don't check pipe segments and can be bypassed with multi-line comments. These hooks enforce covered tool-call boundaries that text rules and permissions often miss.

What happens when a hook blocks a dangerous command:

Claude tries:  rm -rf ~/projects
bash-guard:    bash-guard: rm -rf targeting a critical system path. This would cause irreversible data loss.
Claude sees:   ⚠ Hook blocked this action. Suggesting safer alternative...

No prompts, no "are you sure" dialogs. The command never runs.

First 10 minutes:

1. If you want to avoid reading your real Claude Code settings first, run the temporary first test.
2. Run the audit from the same project root where you start Claude Code.
3. If the summary says no hooks found, 0 payload checks, or FAIL-OPEN, install the recommended hook set.
4. Run verification with --verify --strict.
5. Start a fresh Claude Code session from that same root. If you need help, share only the bounded Safety Summary (copy/paste) block.

Check your current setup from the project root:

Run this from the same project root where you start Claude Code. Project hooks are resolved from the current directory, so a subdirectory launch can miss .claude/settings.json at the repo root. If you are inside a git checkout, move to the repo root first; otherwise stay in the project directory you use for Claude Code:

repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$repo_root"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash

Audit boundary: this downloads tools/safety-check/check.sh from GitHub raw content and runs it locally on your current project and Claude Code settings. The checker does not upload your settings.json, hook files, shell history, repository contents, session logs, or safety summary output.

Scores your Claude Code safety configuration from A to F and shows one-liner fixes for each gap. Add --verify to send representative hook payloads to installed PreToolUse hooks and confirm they actually block covered cases. Other hook events are inventoried and reported, but skipped for payload verification because they do not receive PreToolUse tool payloads. Verification invokes the hook scripts with Claude-style JSON input; it does not execute the dangerous shell or git commands named in those payloads:

repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$repo_root"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify

For CI or a scripted workstation check, fail when verification finds a FAIL-OPEN hook, broken hook files, skipped PreToolUse checks, no hooks, or no payload checks:

repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$repo_root"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict

Use the scripted checks guide for GitHub Actions, developer workstation checks, exit codes, and the limits of what CI can prove.

Checks hook installation, hook health (missing/non-executable scripts), live verification (builds Claude-style JSON payloads for cases such as rm -rf / and git push --force, invokes the configured hook scripts, and confirms they block), enforce-hooks and CLAUDE.md @enforced rules, environment issues (IS_DEMO, JSONC settings, jq/python3 dependencies, Windows hook reliability), and known CLI version regressions. Scans both user-level (~/.claude/settings.json) and project-level (.claude/settings.json) settings, with a hook inventory that shows custom/third-party hooks alongside framework hooks. The summary counts 8 framework hook slots because it includes the enforce-hooks policy hook; install.sh all installs the 7 standalone hooks listed below. Also warns when deny rules are configured without bash-guard, since deny patterns can be bypassed by compound commands and multi-line scripts. No hook installation required for the audit. Covered by hundreds of tests.

For a 10-minute path from audit to verified hooks, see the safety-check quickstart. If verification fails, use the failed verification recipe or the detailed safety summary triage table before trusting the current session. After manual settings or hook edits, use the manual settings edit recipe to validate both settings files, run doctor, and strictly re-verify from the same project root before restarting Claude Code. After Claude Code updates itself, use the post-update recheck recipe or the longer update checklist before trusting hooks in a fresh session. If you want to try the checker before it reads your real Claude Code settings, use the temporary first test or the isolated first-test recipe. That path downloads check.sh from GitHub raw content, runs locally inside a temporary HOME and temporary project, and uploads no settings, hook files, shell history, repository contents, or summary output. If you are trying hooks on a borrowed machine, client repository, CI runner, or other temporary environment, use the temporary hook trial recipe to back up settings, install the smallest useful set, verify, uninstall, and confirm cleanup before leaving the environment. If you need to ask for help, use the safe support evidence guide to share the summary block without exposing private settings or secrets. To print only that bounded public block, run:

repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$repo_root"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --summary-only

For examples of safe public reports and unsafe snippets to avoid, see safe support examples. For PR comments, incident notes, or teammate reviews, use the team handoff report to record the command used, root checked, verification result, residual warnings, and recheck trigger.

For upstream Claude Code hook and permission gaps, use the searchable limitations page, the machine-readable JSON export, or the Atom feed.

macOS / Linux requirements: bash, python3, and jq. The installer uses python3 to manage Claude Code settings.json, safety-check uses python3 for its audit, and mos