Community hooks to enforce research-before-infrastructure (working fix for #72651, #59515, #28469)

Summary

I built runtime enforcement hooks that block Claude Code from running infrastructure commands unless research (WebSearch, WebFetch, or Read) has been done first in the session. This compensates for the model's systematic failure to follow CLAUDE.md instructions.

Gist with installable hooks: https://gist.github.com/nvst18/891959a227f445b360c3e6af84dcf0ca

What this solves

Across Opus 4.5, 4.6, and 4.7, the model ignores explicit CLAUDE.md instructions to research before acting on infrastructure. Documented in:

• #72651 — Model ignores CLAUDE.md behavioral instructions
• #59515 — Model skips research before infrastructure actions
• #28469 — Regression from 4.5 to 4.6
• #41217 — Systematic failure to follow explicit behavioral constraints
• #20330 — Opus 4.5 instruction degradation

Every prompt-level enforcement has failed: CLAUDE.md rules, memory files, repeated corrections, uppercase warnings. The model acknowledges the rule, then ignores it. This has been reported independently by multiple users across multiple model versions.

How the hooks work

Three shell scripts using the existing hooks API:

1. research-gate.sh (PreToolUse/Bash) — Pattern-matches infrastructure commands (gcloud run deploy, aws ec2, kubectl apply, terraform apply, docker push, deploy scripts). If the session research ledger has fewer than 2 entries, outputs {"decision":"block","reason":"..."}. Safe commands (gcloud storage ls, aws s3 ls, gh issue, docker ps) always pass.

1. research-logger.sh (PostToolUse/WebSearch|WebFetch|Read) — Appends a JSONL entry to ~/.claude/research-ledger.jsonl for each research action.

1. research-session-reset.sh (SessionStart) — Truncates the ledger so each session starts at zero.

The model must read docs before it can deploy. No exceptions. No context-window tricks.

Why I'm posting this

The hooks API is the right layer for behavioral enforcement. The model's context window is the wrong layer. But building enforcement hooks requires understanding undocumented API contracts (stdin schema, blocking output format, hook event lifecycle) that most users won't figure out from the existing docs.

I'd like the community's help with:

1. Testing these hooks in different environments and workflows
2. Adding infrastructure patterns I missed
3. Identifying false positives
4. Pressure on Anthropic to either fix the underlying compliance issue or ship enforcement hooks as a first-class feature

I'd like Anthropic to consider:

1. Making behavioral enforcement hooks a documented, supported feature
2. Shipping a research-before-action gate as a built-in option in settings.json
3. Fixing the root cause: why does the model systematically ignore loaded instructions?

Install

Copy three files to ~/.claude/hooks/, add entries to ~/.claude/settings.json. Full instructions in the gist.

Dependencies

python3, optionally jq. No external packages.

Tested on

• Claude Code CLI on Ubuntu 22.04
• Opus 4.6
• Infrastructure: GCP Cloud Run, GCS, Compute Engine

— Nofyah