new-invariant

Write a PreToolUse hook that reads the JSON payload on stdin, returns exit code 2 with a stderr reason to block, and exit 0 to allow. Register it in .claude/settings.json under the matcher for the tools it guards, such as Write|Edit.

Feed the hook a synthetic JSON payload over stdin using node --test and assert exit codes. Cover four cases: blocking the violation, allowing the compliant form, allowing out-of-scope files, and allowing prose that merely mentions the rule.

Skip the hook when the rule cannot be decided from a single edit fragment, such as complexity or naming judgments. Those belong to a code reviewer, lint rule, or type check; forcing them into a hook produces guards people fight and disable.

The matcher is hitting prose that mentions the violation. Strip comments and string literals before matching, as the example hook does, because false positives on prose are the main reason guards get switched off.

The hook should fail open and return exit code 0 on malformed JSON or internal errors. A guard that crashes and blocks everything gets deleted quickly, so the template handles parse failures by allowing the action.