Session hooks that check: the fast checks after an edit, verify before a stop, the Maintainer's identity

Merged
DO
1mo ago
+1262-14

Part of the epic "Epic: slice 0, foundations. The repo holds the line, its context is tested, and the platform facts are recorded". Until slice 2 every line is written in the Maintainer's sessions, and an instruction is a request; a hook is enforcement (§9.12, "Hooks hold the line").

What this story now holds:

  • After an edit, the fast checks run and a failure is shown to the agent.
  • A session is sent back once while make verify fails on work it has not pushed; at the next stop the person is told.
  • A commit, a push or a write to GitHub as the machine user, or with a commit identity that is not the Maintainer's, is refused.

Three project hooks in .claude/settings.json. Each is a script under tools/hooks/, run as python3 -I so nothing where it runs can shadow the standard library. They install nothing.

EventMatcherDoesReports
PostToolUseEdit|Write|MultiEdit|NotebookEditmake fast, which is every check and every test but the seeded simulation, in the project or the worktree under .claude/worktrees/ that holds the edit. An edit anywhere else runs nothingExit 2 with the end of the output; the edit stands. A branch with no fast target tells the person and does not fail
Stopmake verify, unless the tree is clean and nothing is ahead of its upstream or origin/mainExit 2 with the failure. At the next stop the session ends and the person is told
PreToolUseBashEvery commit, push, pull request, merge, release or writing gh api: git's author and committer, gh's active account, every push URL, and every commit being pushed must be the Maintainer'sExit 2, one code: sentence per problem

The identity hook reads what is configured, so an identity set inside the command is refused: --author, -c user.*, -c alias.*, -c http.*, GIT_AUTHOR_*, git config, gh auth, or a write to .git/config in the same command. It refuses what it cannot read:

  • no git or gh, a token in the environment, an SSH remote, or a credential helper other than gh's;
  • an unknown git command or option, or text that names a commit or push in a command it did not read as one;
  • a check that has not finished within 45 seconds.

It never hands its own git an option from the command, and it shows no credential. Here-document bodies are data. A refspec with an expansion, such as "$(git branch --show-current)", pushes the current branch.

The Maintainer is data, config/hooks.json, with a schema and a counter-example. The machine user is the approver already in config/defaults.json (decision 0005). tools/hooks/shell.py reads a shell command as words. The story "Session hooks that refuse: protected paths, merging, and the repo's own rules" can reuse it, and should add .claude/settings.json, tools/hooks/ and config/hooks.json to its protected paths.

The branch is rebased onto main after "Verify passes in a checkout that holds other worktrees" and "How a platform trial is run and recorded". make verify keeps check_trials and its list of unverified rules, and the hook tests walk the tree only through tools/walk.py.

What is given up

  • A session sent back once ends at its next stop even if verify still fails, and the person is told. A hook that never released it would cycle with no bound and no person.
  • A push over SSH is refused, because the account behind a key cannot be read offline. Pushes go over HTTPS through gh.
  • What the hooks do not see: a commit or push made by a script file the command runs, gh's own aliases, the Monitor and terminal tools, and a subagent's stop.
  • These hooks guard the Maintainer's sessions against mistakes; they are not the boundary. Signed commits and push restrictions on the machine user, held by GitHub, are, and belong to the story "The Factory repo's rulesets hold the Release tags and each required check's App".
  • A sed or awk script whose text names a commit or a push is refused, since either program can run commands.

Verification

  • make verify: 198 tests OK (2 expected failures), every check ok.
  • python3 -m tools.mutants: 33 of 33 mutants killed.
  • make verify passes in a checkout that holds a nested worktree, which the Stop hook depends on.
  • tests/test_hooks.py, 29 tests:
    • feeds each hook violations and clean cases, and runs each once as the settings run it, from a directory holding a json.py that must not load;
    • holds the wiring in .claude/settings.json;
    • covers the review's cases: refspec injection writes no file, credentials are not shown, the deadline refuses, heredoc bodies are skipped, expanded refspecs pass, gh writes, aliases and unknown options are refused, a wrong committer on a pushed commit is refused, and each verb that makes a commit is checked.
  • tests/test_tools.py holds make verify to every test file, the simulation included, through tools.verify.main([]), and holds both Makefile recipes word for word.
  • Each hook rule was broken by hand in a scratch copy (32 breaks, including the review's two survivors); a test caught every one.
  • Run against this machine's real git, gh and make: a commit, git push -u origin "$(git branch --show-current)", gh pr create and gh pr merge as the Maintainer pass; git -c user.email=… commit is refused; an edit outside the project runs nothing.

Closes #7

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Repository edits now trigger a fast verification check, and sessions with unpushed work run full verification before ending.
    • Git commits, pushes, and GitHub writes are checked against the configured Maintainer identity; actions that cannot be verified are refused.
    • Added a fast verification mode that runs checks while excluding designated slow tests.