Summary

Create a Claude Code hook that intercepts git commands and verifies the current branch matches the expected PR context before executing commit operations.

Background

From PR co-mingling retrospective (PR #669): Agents made commits without branch awareness, leading to cross-PR contamination. This hook provides runtime verification during agent execution.

Specification

Category: Agent automation protection
Integration: Claude Code PreToolUse hook

Verification Logic

Before any git commit or git push command:

1. Check current branch: git branch --show-current
2. Compare with session context (from session log JSON branch field)
3. Block on mismatch with actionable remediation paths
4. Fail open on missing context (no session log, no branch field)

Example Flow

Agent: git commit -m "fix: update..."
Hook: [BLOCKED] Current branch 'feat/other-pr' does not match session context 'feat/current-pr'
Hook: Remediation options:
  1. Switch to expected branch: git checkout feat/current-pr
  2. Update session log to match current branch
  3. Start a new session for current branch

Architecture Constraint

Claude Code PreToolUse hooks are non-interactive subprocesses. Stdin carries a JSON payload from Claude Code. The hook cannot prompt for user input. Exit codes are the only communication channel:

• Exit 0: allow the command
• Exit 2: block the command (with message shown to agent)

The hook provides just-in-time documentation through its block message, giving the agent actionable remediation paths at the moment of failure.

Testing

• Simulate commit on wrong branch (should block)
• Test with session context variable set
• Test remediation paths provided in block message
• Verify no false positives on correct branch
• Verify fail-open on missing session context

Related

• PR docs(retrospective): PR co-mingling root cause analysis #669: Root cause analysis
• Issue feat(git-hooks): add pre-commit branch validation hook #681: Pre-commit hook (static validation)
• PR feat(hooks): add branch context verification hook #1208: Implementation

Acceptance Criteria

• Hook intercepts git commit/push commands
• Hook verifies branch against session context
• Hook blocks on mismatch and provides remediation paths in block message
• Agent can resolve by switching branch, updating session, or starting new session
• Hook output serves as just-in-time documentation with actionable remediation steps

Notes

This complements #681 (pre-commit hook) by adding runtime verification during agent execution. The pre-commit hook catches errors at commit time; this hook catches them before the agent even attempts the commit.