Repository navigation
v2.9.1 — a lighter hook layer
A lighter hook layer. The two guard hooks that ran before every Bash call, and a third that ran after it, slowed everyday work and refused ordinary commands too often. They are gone. Claude Code's own permission deny rules now refuse destructive git, and one small hook, started only for a merge, pull or rebase, refuses those while tracked files have uncommitted changes. The template also stops setting the block that kept Claude from editing its own settings files.
Upgrading — read this before you pull into a fork
This release deletes git-guardrails.py, root-of-trust-guard.py and context-monitor.py from .claude/hooks/.
- If you never changed
.claude/settings.json, the pull updates it along with the hooks, and nothing else is needed. - If you changed it, make the same changes by hand:
- remove the
git-guardrails.pyandroot-of-trust-guard.pyentries underPreToolUse, and thecontext-monitor.pyentry underPostToolUse; - add the three
dirty-tree-guard.pyentries ("if": "Bash(git merge *)","Bash(git pull *)"and"Bash(git rebase *)"; noonFailure); - add the
permissions.denylist; - remove
"blockWritesOutsideWorkingDirectories": truefrompermissions, unless you want to keep that block.
- remove the
- Why it matters: an old registration of a deleted guard has
"onFailure": "block", so Claude Code refuses every Bash, Edit and Write until it is fixed. Claude cannot fix it from inside that session, because its own edit is refused too. Edit the file in a terminal or an editor. Claude Code picks up the change without a restart. - Restart once after the pull. Claude Code keeps the write block in a running session after its key is removed.
Removed
git-guardrails.py(1,800 lines, on every Bash, Edit and Write).- Its deny list is replaced by native deny rules (below), and its clean-tree rule by
dirty-tree-guard.py. - Its
CLAUDE_STRICT_PATHScheck on code edits is gone.scripts/quality_score.pystill deducts 20 points per hardcoded path in an.Rfile, so a script with one such path still passes the commit gate.confidential-data.mdnow says so.
- Its deny list is replaced by native deny rules (below), and its clean-tree rule by
root-of-trust-guard.py(2,200 lines, on every Bash call).- Nothing replaces its tripwire on shell writes into
.claude/settings*.json,.claude/hooks/and.githooks/, andALLOW_ROOT_OF_TRUST_WRITEis gone. - The write block that refused file-tool writes to the settings files is removed too (below), so nothing refuses a write to these paths now.
- Nothing replaces its tripwire on shell writes into
context-monitor.py(after every Bash call). The status line shows Claude Code's owncontext_window.used_percentage, and/context-statuspoints to it and to/context.permissions.blockWritesOutsideWorkingDirectories: true(added in v2.7.0).- While it is on, Claude Code's file tools refuse every Claude Code settings file, even inside the repository, so every allow rule, deny rule or hook change had to be made by hand.
- A
truein any settings file applies and a localfalsedoes not lift it, so it could not be turned off for one machine while the committed file kept it. - To keep it in a fork, add the key back under
permissions(Claude Code ≥ 2.1.314). It also removes theEnterWorktreeandExitWorktreetools from the session.
- Restoring a hook: each file is at tag
v2.9.0(git show v2.9.0:.claude/hooks/<file>), with its registration in that tag's.claude/settings.json. The guide's hook section says how.
Added
- Native deny rules in
.claude/settings.json. Claude Code checks them itself, with no process and no delay.- What they refuse:
git reset --hard, everygit clean,git push --forceand-f(--force-with-leasestill runs),git add -A,--alland.wherever they appear among the arguments, and a checkout or restore of the whole tree (git checkout .,git checkout -- .,git checkout HEAD -- .,git restore .,git restore -- .; alsogit restore --staged ., which only unstages). Also reads and edits of.envfiles, and reads of*.pem,*.keyandcredentials*. - Coverage: a deny rule applies to every part of a compound command, including a subshell and a
$(…)substitution, and holds in every permission mode. - Limit: it does not match a rewritten spelling, such as
git -C . push --force,git -c x=y pushorbash -c '…'. Anthropic's permissions docs call Bash deny rules a guard on the usual invocation, not a security boundary. - Verified live in a scratch repository after the settings change. Every rule refused its command, including
(git reset --hard)andecho "$(git reset --hard)". The controls ran. The.envrules also refused a shell command that would have written one. Recorded in the qualification ledger. - Extended after review. An independent Codex CLI review found variants the removed hook had caught and the first list missed (
git restore -- .,git checkout HEAD -- .,git add -v -A,git add file .), and two refusals of ordinary commands (git push origin feature--force,git reset -- tracked--hard.txt). The list now matches each option as a whole word in any argument position. The extended list was verified live the same way.
- What they refuse:
dirty-tree-guard.py. It refuses a merge, pull or rebase while tracked files have uncommitted changes.- Untracked files do not count, because git refuses an overwrite itself.
--abort,--continue,--skip,--quitand--edit-todopass.ALLOW_DIRTY_MERGE=1overrides it. - Claude Code starts it only for those three commands, through
iffilters. Because a filter that names more than the program also starts it for any command containing$(), it checks first that a real merge, pull or rebase is present. - It reads the command the way the shell splits it, so quoted text, comments and heredoc bodies are not commands, and a
--abortinside a-mmessage is not a resume step. Because theiffilter also starts it for any command with$(…), backticks or$VAR, this is what keeps ordinary commands from being refused. - It fails open: a missing
python3lets the command run, and its registration starts it through a one-line launcher (sh -c '[ -f "$1" ] || exit 0; exec python3 "$1"') that exits 0 when the file is missing. Without the launcher, Python's exit 2 for a missing script would refuse every command the filter starts the hook for. - It reads the session's directory, so it misses a repository reached by
cd elsewhere &&orgit -C. - Twenty-nine battery cases (section j) pin it. Fifteen mutants each fail their own cases. The Windows code-page cases that protected git-guardrails now protect it, and the one meant to catch a locale-decoded
git statusnow uses a dirty tree, so it can fail.
- Untracked files do not count, because git refuses an overwrite itself.
Changed
issue-guard.pyis the only hook left with"onFailure": "block", and it runs only forghcommands. A missingpython3or hook file no longer refuses every Bash, Edit and Write, so #179 and #180 are resolved by the removal. The launcher patch drafted on #180 is not needed.- The hook battery drops the 228 cases of the removed hooks and gains section (j): 123 cases. Grading the grader was re-measured: each remaining decision hook, stubbed to always allow, reddens exactly its own cases.
- The qualification ledger moves the removed hooks' rows, reproduction notes and drift record, unedited, to a Retired at v2.9.1 section. Their counts now read "at the time".
- Updated to match: README, the guide, TROUBLESHOOTING,
docs/index.html,MEMORY.md,AGENTS.md(what Codex and Antigravity must do by hand),.github/SECURITY.md,confidential-data.md, thecommit,context-statusanddiagnoseskills, and the status line.
Fixed
- Destructive git inside a subshell or a command substitution ran unchecked (#172). git-guardrails parsed the command line itself and missed
(git reset --hard)and$(git reset --hard). Native deny rules apply inside both, verified live.
Inventory at release: 62 skills, 18 agents, 37 rules, 9 hooks, 11 gates
(standing hook battery: 123 cases, seconds to run; portability suite: 130 cases).