121 lines
5.8 KiB
Python
121 lines
5.8 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 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)
|
|
if call.tool == "Skill":
|
|
return text(call.given, "args"), text(call.given, "skill"), skill_breaches(call, environ)
|
|
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)]
|
|
return command_breaches(command, simples, home) + [breach for commit in found for breach in round_cap_breaches(commit) + todo_breaches(commit.directory)] + in_files
|