Skip to content

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

Merged
don-petry merged 4 commits into
mainfrom
slice-0/session-hooks-check
Oct 15, 2026
Merged

don-petry merged 4 commits into
mainfrom
slice-0/session-hooks-check

Conversation

@don-petry

@don-petry don-petry commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

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.

Event Matcher Does Reports
PostToolUse Edit|Write|MultiEdit|NotebookEdit make 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 nothing Exit 2 with the end of the output; the edit stands. A branch with no fast target tells the person and does not fail
Stop make verify, unless the tree is clean and nothing is ahead of its upstream or origin/main Exit 2 with the failure. At the next stop the session ends and the person is told
PreToolUse Bash Every 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's Exit 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.

@don-petry
don-petry requested a review from a team as a code owner October 14, 2026 23:10
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@coderabbitai

coderabbitai Bot commented Oct 14, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration
  • Configuration used: Repository: combsmith/software-factory/.coderabbit.yaml
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: d3f77110-7607-497e-aae2-1a0bd5dfcf0e
📥 Commits

Reviewing files that changed from the base of the PR and between 15a767f and 8e33442.

📒 Files selected for processing: 20
  • .claude/settings.json
  • AGENTS.md
  • Makefile
  • config/AGENTS.md
  • config/hooks.json
  • examples/invalid/hooks.maintainer-with-no-email.json
  • schemas/hooks.schema.json
  • tests/AGENTS.md
  • tests/test_hooks.py
  • tests/test_tools.py
  • tools/AGENTS.md
  • tools/check_examples.py
  • tools/check_repo.py
  • tools/hooks/__init__.py
  • tools/hooks/after_edit.py
  • tools/hooks/before_stop.py
  • tools/hooks/identity.py
  • tools/hooks/make.py
  • tools/hooks/shell.py
  • tools/verify.py
+---------------------------------------------------+
| Stack Overflow called, they want their code back. |
+---------------------------------------------------+
  \
   \   (\__/)
       (•ㅅ•)
       /   づ
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

don-petry and others added 4 commits October 14, 2026 20:18
…e a stop, the Maintainer's identity

Three project hooks in .claude/settings.json, each a module under tools/hooks/ that
installs nothing:

- PostToolUse on Edit, Write, MultiEdit and NotebookEdit runs `make fast`, a new
  target: every check and every test module but the seeded simulation, about
  three seconds. A failure goes to the agent with exit 2; the edit stands.
- Stop runs `make verify` and refuses to stop while it fails. It sends the session
  back once; if verify still fails at the next stop, the session ends and the
  person is told, so the hook never cycles without a bound.
- PreToolUse on Bash refuses a command that commits or pushes unless git's author
  and committer, gh's active account, the remote and every commit being pushed
  are the Maintainer's. An identity set inside the command is refused, and so is
  anything the hook cannot read: no git or gh, a token in the environment, an SSH
  remote, a command it cannot split into words.

The Maintainer's identity is data, config/hooks.json, with its schema and a
counter-example. The machine user is the approver already in
config/defaults.json. tests/test_hooks.py feeds each hook a violation and a clean
case, and holds the wiring in the settings. make verify and tools.mutants pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The identity hook:

- No option from the command reaches the hook's own git. A refspec is read after
  its +, and one starting with '-' is refused. Each source is resolved first with
  rev-parse --verify --end-of-options, and git log gets the commits it resolved to.
- One deadline of 45 seconds covers every git and gh call. Running out refuses.
- No credential is shown: a URL loses its user and password before it is
  printed, and the credential helper's value is never echoed.
- A here-document's body is never read as commands, and a command substitution
  inside a quoted word is. A refspec with an expansion pushes the current
  branch, so `git push -u origin "$(git branch --show-current)"` passes.
- gh pr merge, gh release create, and gh api with a writing method or fields
  need gh's active account to be the Maintainer.
- Refused as unreadable: -c alias.* and -c http.*, an unknown git command or
  global option, text that names a commit or push in a command not read as one,
  and a write to .git/config in the same command. Every push URL is read
  (get-url --all).

The hooks run as `python3 -I` on their files, so nothing where they run can
shadow the standard library. make runs only in the project or a worktree under
its .claude/worktrees/. An edit elsewhere runs nothing, and a branch with no
fast target tells the person and does not fail.

The Stop hook skips verify when the tree is clean and nothing is unpushed. Its
message to the agent says only that verify fails, with the tail.

tools/verify.py discovers every test file again and filters for fast. A test
holds main([]) to the simulation, and holds both Makefile recipes word for word.
make verify and tools.mutants pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
After the rebase onto "Verify passes in a checkout that holds other worktrees",
two of this story's tests walked the tree themselves. The test that holds
`make verify` to every test file now finds them with walk.files. The hook tests
make each repo with git clone instead of copying one, and make a repo only once
for each configuration that no case changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…erified rules

After the rebase onto "How a platform trial is run and recorded", verify's main
prints each unverified rule of the fake GitHub. The test that holds `make
verify` to every test file calls main twice, and the list was printed into the
middle of every run. It now captures that output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@don-petry
don-petry force-pushed the slice-0/session-hooks-check branch from b6aaaaa to 8e33442 Compare October 15, 2026 01:46
@sonarqubecloud

Copy link
Copy Markdown

@don-petry
don-petry added this pull request to the merge queue Oct 15, 2026
Merged via the queue into main with commit a75b2e4 Oct 15, 2026
9 of 10 checks passed
@don-petry
don-petry deleted the slice-0/session-hooks-check branch October 20, 2026 17:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Session hooks that check: fast checks, a passing verify, the right identity

1 participant