Files
claude-config/bin/rule_hook/main.py
T

124 lines
6.0 KiB
Python

"""Block a Claude Code tool call that breaks a checkable rule, unless the call overrides the rule.
usage: rule-hook (a PreToolUse hook: reads the call as JSON on stdin)
rule-hook overrides (prints this chunk's overrides)
settings.json runs it before each Agent, Bash, Edit, MultiEdit, Read, Skill and Write call, in every session and
subagent. The rules:
{rules}
A call overrides a rule with `# rule-override <rule>: <reason>`:
- anywhere in a Bash command, such as a trailing comment
- in a file, as a comment line in the text the edit writes
- in Markdown, as `<!-- rule-override <rule>: <reason> -->`
A file a Bash command writes, such as through `cat > Dockerfile`, is checked when a `git commit` runs, not when written.
The commit checks every file that differs from HEAD, in the index or the work tree, and every untracked file that is
not ignored, even one the commit leaves out. It holds each to the rules that name a file (action-pin, image-pin,
ignorefile-sorted, no-ai-attribution), judged on the lines the file adds. A marker among those lines, or in the commit
command, overrides the file's breach.
Each override that let a call through is appended to rule-overrides.tsv in the git directory of
the checkout it touched: UTC time, branch, the commit checked out, rule, reason, and the file
written or the command's first line. An override outside any git checkout is not logged.
`rule-hook overrides` prints the lines whose commit the current branch's reflog holds: those the
default branch lacks, and those logged under the branch's own name.
Run with no arguments in a terminal, it prints this help.
Exit 2 with the rule, why it holds and, where the rule takes an override, how to write one, when a rule blocks the call, or when an
override cannot be logged; 0 otherwise. `rule-hook overrides` exits 1 when git cannot read the
checkout or the branch's reflog. Exit 1, a non-blocking error to Claude Code, on input it
cannot read.
"""
import json
import os
import pathlib
import sys
import time
import typing
from rule_hook.call import applied, Call, FILE_TOOLS, parsed_call, text
from rule_hook.rules import Breach, check, Checked, command_breaches, file_breaches, rules_help
from git_cli.git_command import commits
from rule_hook.committed_files import committed_file_breaches
from failure import Failure
from rule_hook.override_log import Log, log_path, logged, print_overrides, write_override
from rule_hook.file_text import read
from rule_hook.repeat_read import read_breaches
from rule_hook.reviewer_report import report_breaches
from rule_hook.reviewer_rung import reviewer_breaches, skill_breaches
from rule_hook.round_cap import round_cap_breaches
from command_lines.shell_command import simple_commands
from rule_hook.todo_check import todo_breaches
def main(argv: list[str], stdin: str) -> int:
if argv in (["-h"], ["--help"]) or not argv and not stdin:
print(__doc__.strip().replace("{rules}", rules_help()))
return 0
if argv == ["overrides"]:
return print_overrides(os.getcwd())
if argv:
print(f"unknown arguments: {' '.join(argv)}; see rule-hook --help", file=sys.stderr)
return 1
try:
call = parsed_call(json.loads(stdin))
except json.JSONDecodeError as failure:
call = Failure(str(failure))
if isinstance(call, Failure):
print(f"rule-hook cannot read the hook input: {call.reason}", file=sys.stderr)
return 1
found = breaches_of(call, os.path.expanduser("~"), os.environ)
if found is None:
return 0
written, what, breaches = found
return answer(check(breaches, written, text(call.given, "file_path").endswith(".md"), call.tool == "Bash"), what, time.time())
def breaches_of(call: Call, home: str, environ: typing.Mapping[str, str]) -> tuple[str, str, list[Breach]] | None:
"""The text that may carry an override, what the log names the call by, and its breaches; None for a call no rule checks."""
if call.tool == "Agent":
return text(call.given, "prompt"), text(call.given, "subagent_type"), reviewer_breaches(call, environ, home)
if call.tool == "Skill":
return text(call.given, "args"), text(call.given, "skill"), skill_breaches(call, environ, home)
if call.tool == "Bash":
command = text(call.given, "command")
return command, command.split("\n", 1)[0], bash_breaches(command, call.cwd, home) + read_breaches(call, home)
if call.tool == "Read":
return "", text(call.given, "file_path"), read_breaches(call, home)
path = text(call.given, "file_path")
if call.tool not in FILE_TOOLS or not path:
return None
before = read(path)
added, after = applied(call, before)
return added, path, report_breaches(call, path, home) + file_breaches(path, before, added, after)
def answer(checked: Checked, what: str, now: float) -> int:
for message in checked.messages:
print(message, file=sys.stderr)
if checked.blocked:
return 2
logs = [(breach, reason, log_path(breach.directory)) for breach, reason in checked.overridden]
# Resolve every log before writing any, so a call that ends blocked hasn't logged anything.
unloggable = [f"{breach.rule}: {log.reason}" for breach, _, log in logs if isinstance(log, Failure)]
if not unloggable:
for breach, reason, log in logs:
unwritten = write_override(log, logged(log, breach, reason, what, now)) if isinstance(log, Log) else None
unloggable += [f"{breach.rule}: {unwritten.reason}"] if unwritten else []
for unlogged in unloggable:
print(f"rule-hook cannot log the override of {unlogged}; unlogged, it would escape review.", file=sys.stderr)
return 2 if unloggable else 0
def bash_breaches(command: str, cwd: str, home: str) -> list[Breach]:
simples = simple_commands(command, cwd, home)
found = commits(simples, home)
in_files = [breach for directory in dict.fromkeys(commit.directory for commit in found) for breach in committed_file_breaches(directory)]
round_cap = [breach for commit in found for breach in round_cap_breaches(commit)]
todo = [breach for commit in found for breach in todo_breaches(commit.directory, pathlib.Path(home))]
return command_breaches(command, simples, home) + round_cap + todo + in_files