feat: require a session claim before commit/push on a PR branch (#4155)

[dem-extra1]

Closes #4155

What

Local half of #4155: a PreToolUse hook on Bash that makes a session claim a PR branch before it commits or pushes to it.
The incident was two sessions on #4132, #4134 and #4138 with no claim comment from either (PR #4134 lost 471 lines of memories/preferences.md).

hooks/no-pr-work-without-claim.py binds to PreToolUse (Bash) and fires on git commit and git push only (argv-split via scripts/lib/shellcmd.py, so quoted or heredoc mentions are silent; --dry-run, branch deletes, tag and ref-set pushes are skipped).
When the target branch has an open PR in a Morrison-Lab repo it reads the PR's comments:

PR state	Result
no claim comment	deny, with the claim text to post
only claims naming a different session, PR active in the last 2 h	deny (stand down)
only claims naming a different session, PR idle over 2 h	warn (treated as lapsed)
only claims naming no session (every emitter but claim-pr today, #4160)	warn
a claim naming this session (session id or worktree path), none newer from another session	allow
another session's claim newer than mine	deny (takeover)

A claim is a comment with the agent marker plus hold off / paws off wording; a session is named by a Session worktree: or Session id: line.
Before a push it also reads repos/<o>/<r>/activity?ref=refs/heads/<branch> and warns (never denies) about pushes since the claim whose commit is not in local history.
Every network or gh failure, an unresolvable cd, a commit inside bash -c, and a spent 20 s budget are visible fail-opens (stderr plus additionalContext).
Escape hatch: ALLOW_UNCLAIMED_PR_WORK=1 (env prefix, leading export, or process env).

Also: a Session worktree: line in the skills/claim-pr PR template, a Do/Don't pair in shared/workflow/claim-pr.md citing #4155 and PR #4134, README rows, and the hooks/hooks.json entry with its generated mirror.

Activation

Merging this PR activates the hook on the plugin path (the hooks.json entry is the activation); nothing was registered locally with install-hooks.py --fix.
On the non-plugin path, post-merge step 3.75 owns the registration.

Not done here

• The server-side half for cloud sessions (hooks are inert in remote and web sessions, Every PreToolUse and Stop hook is inert in remote/web sessions: the plugin is never installed #2004).
• The other claim emitters (ardi, handoff, gi, st, gip, pr-on-claim, ...) do not carry the session line yet: #4160.
• Known limits, listed in the hook docstring: an own claim's age and most release wordings are not evaluated, a fork PR is not seen, two sessions sharing one checkout cannot be told apart.

Verification

• hooks/test-no-pr-work-without-claim.py: 104 cases against real temporary git repos with a fake gh (a fixture, so these show the hook's decisions given canned responses, not forge behaviour; the activity and pulls response shapes were checked once against the live API).
• Mutation check: single-condition mutants of each decision branch (claim recognition, session matching, takeover, directory resolution, push-target parsing, dry-run grammar, pagination, fail-open paths), each killed by at least one case.
• Eight rounds of foreground adversarial review (adversarial-reviewer, sonnet) on the committed diff; findings addressed in the follow-up commits.
  The eighth round read 82ee03a0 and returned CLEAN with four non-blocking notes: a session that claims in one checkout and then commits from another reads its own claim as a peer's, /mnt/c/ and 8.3 path spellings do not match, the fragment's one-line summary omits the hold-off wording, and any claim containing the words "session id" counts as a peer's.
• The push of 82ee03a0 used ALLOW_UNREVIEWED_PUSH=1: the pre-push guard looks for the verdict in the Agent call's own result, and this harness returns a foreground reviewer's report as a message instead, so the guard could not see a verdict that exists.
• Heads-up for Add Session worktree line to every claim-comment emitter (follow-up to #4155) #4160: once every emitter carries the worktree line, a subagent committing in its own worktree on a parent-claimed branch is denied as a peer (documented in the hook docstring).

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.

_{2026-10-01 04:52 UTC}

[dem-extra1]

Claude Code CLI (local session, gia mwc daytb) is working on this. Please hold off on pushing to its branch until I'm done.

Posted by Claude Code (AI agent) --- not written by a human.

[github-actions]

Claude finished review — View run

---

Fully-clean instrument reading

Per the Stop hook's requirement, I ran the authoritative instrument rather than resting the verdict on gh pr checks:

python3 scripts/check-pr-fully-clean.py 4156 -R Morrison-Lab/ai-config

Output (exit 1, NOT fully clean, two - finding bullets):

✓ No review threads found.
❌ PR is NOT fully clean:
  - Check run 'review / claude-review' is still in status 'in_progress'
  - No automated review comments or reviews found on PR #4156

Both reasons are this review's own in-flight sibling run: the review / claude-review check is the workflow executing this very review, and the "no automated review found" condition is true only because this review has not been posted yet — posting it is what will resolve both. This is exactly the self-referential case the task's own Verdict semantics section calls out (the permanent-loop pattern tracked as ai-config#2475): the instrument cannot read clean while the review that gates it is still running, and a status-conditioned non-clean reading here is not a content finding about the diff. Per that explicit instruction, I do not defer the verdict to this reading. Independently, gh pr checks showed no check that finished red (validate and review were pending/in-progress, everything else — build, CodeQL, lint-markdown, lint-qmd, new-line-breaks — passed), and my own direct inspection of the diff (104/104 tests passing, both hooks.json registrations valid and consistent, structural hook validators clean, referenced issues real) found no content defect.

Verdict

Ready for merge — judged on the diff's content; the only non-clean signal from the fully-clean instrument is this review's own in-flight completion, not a defect in the change.

Structured Review Data (JSON)

{
  "schema_version": "1.1",
  "reviewer": "claude",
  "commit_sha": "82ee03a05c4a3da3c04bc6d66734ab224b010b8d",
  "verdict": "CLEAN",
  "findings": [],
  "detailed_assessment": "Traced hooks/no-pr-work-without-claim.py's claim-matching, argv-parsing, and fail-open paths against its 104-case test suite, which passes in full with no uncovered failure mode found.",
  "holistic_assessment": "Registration is consistent across both hooks.json files, referenced issues exist, the claim-pr skill template matches what the hook parses, and no CI check has failed."
}

Stopping Point: Clean stopping point reached --- session done; review posted with no blocking findings; no follow-up items pending.

Reviewed commit: 82ee03a

[github-actions]

💰 Cost: $1.7263 (review) — run