Add block-secret-files hook

[jackyraimond]

Adds the first hook to the repo: a PreToolUse guardrail that stops Claude from reading or writing files that look like secrets.

Why

Claude reads whatever a task seems to need, and "seems to need" regularly includes .env. Nothing in Claude Code stops that by default. Permission rules can, but they are per-project and easy to forget on the project where it matters. A hook applies everywhere, once.

The point is not that a leaked .env is catastrophic on its own — it is that the contents end up in a transcript, and transcripts get shared, summarised and stored.

What it does

Denies Read, Edit, Write and NotebookEdit when the target path matches a secret pattern: .env and its variants, *.pem, *.key, *.p12, *.pfx, keystores, id_rsa and friends, *.kdbx, credentials, service-account*.json, .npmrc, .pypirc, .netrc, .htpasswd, plus anything inside .ssh/, .gnupg/, .aws/ and the .docker/config.json / .kube/config files.

*.example, *.sample, *.template, *.dist and the .env.example family are allowed on purpose. Those are the files Claude should be reading.

It returns a permissionDecision of deny with a reason, so Claude gets told why and can ask for the single value it needs instead of giving up or retrying.

What it deliberately does not do

• It does not match Bash. cat .env still works. Blocking that reliably needs command parsing, not path matching, and the false-positive rate is not worth it. Stated plainly in the hook's README rather than left for someone to discover.
• It does not scan contents. A secret pasted into config.php goes through.
• It fails open. An unreadable payload or a tool without a path is allowed. A guardrail that crashes should not take the session down with it.

Seatbelt, not vault.

Testing

./scripts/validate.sh passes.

The script was exercised directly with ten payloads:

Payload	Expected	Result
.env	deny	✅
.env.local	deny	✅
.env.example	allow	✅
env.example	allow	✅
~/.ssh/id_ed25519	deny	✅
~/.kube/config	deny	✅
notebook_path = .env	deny	✅
src/app.ts	allow	✅
malformed JSON on stdin	allow	✅
empty payload {}	allow	✅

Reproduce with the two commands in the hook's README.

Review notes

This is shell that runs automatically on every matching file operation, so it is worth reading the script rather than trusting the description. It is 129 lines of dependency-free Python: three pattern lists at the top, one fnmatch check, no network, no writes, no reads beyond stdin.

🤖 Generated with Claude Code

[KainDitmer]

This branch has conflicts that must be resolved
Use the web editor or the command line to resolve conflicts before continuing.

.claude-plugin/marketplace.json
README.md