Hook Configuration

Hook Configuration

Why hooks matter

Text rules and system prompts can be ignored, compacted away, or reasoned around in long sessions. Hooks execute as OS-level processes on every tool call — they are deterministic and cannot be bypassed by the model. If you have one safety measure to put in place, make it a hook.

Quick setup

Copy the template settings.json from hooks.md into your project:

mkdir -p .claude && cp hooks.md .claude/settings.json

Or paste the JSON block from hooks.md directly into .claude/settings.json. Hooks are active immediately — no restart required.

What the template blocks

PreToolUse — denied bash patterns:

Pattern	Why
rm -rf, rm --recursive --force	Recursive force-delete
git push --force, git push -f	Force-push (allows --force-with-lease)
--no-verify on any git command	Hook-skip attempts
chmod +s, chmod 777	Setuid/setgid and world-writable
bash -c, sh -c, fish -c, zsh -c	Nested shell execution
| bash, | sh, | fish, | zsh	Pipe-to-shell execution

Permissions — tool-level denies:

"deny": [
  "Read(.env)", "Read(.env.*)", "Read(secrets/**)",
  "Write(.env)", "Write(.env.*)", "Write(secrets/**)",
  "Edit(.env)", "Edit(.env.*)", "Edit(secrets/**)"
]

How to customize

Add a deny pattern — extend the PreToolUse command string with an additional grep check:

if printf "%s" "$CMD" | grep -qE "your-pattern-here"; then
  echo "BLOCKED: reason" >&2; exit 2
fi

Regex vs glob in settings.json:

• permissions.deny and permissions.allow use glob patterns — Read(.env.*) matches .env.local, .env.production, etc.
• Hook command grep patterns use POSIX extended regex (grep -E). Do not use grep -P — it silently fails on macOS.

Sandboxing (beyond hooks)

Hooks block known-bad patterns. For stronger isolation:

• Claude Code built-in sandbox — Anthropic's OS-level sandbox blocks filesystem writes and network calls outside allowed paths
• Trail of Bits devcontainer — for untrusted repos, open in a devcontainer to confine any damage to the container

---

See also: Customization Patterns | Rule Architecture | Setup.sh Reference