fix: hook resilience for git ops, regex bypass, and worktree isolation (#153)

Three fixes to Claude Code hooks:

1. New post-git-ops.sh hook (PostToolUse on Bash) detects git rebase,
   revert, cherry-pick, merge, pull and automatically rebuilds the
   codegraph, logs changed files to session-edits.log, and clears
   stale entries from codegraph-checked.log.

2. Fix regex bypass in guard-git.sh: blocking patterns used ^\s*git
   which only matched git at command start. Commands like
   `cd foo && git add .` bypassed all blocks. Now uses
   (^|\s|&&\s*)git to match chained commands consistently.

3. Fix worktree isolation: session-local state files (session-edits.log,
   codegraph-checked.log) now use `git rev-parse --show-toplevel`
   instead of CLAUDE_PROJECT_DIR. This gives each worktree its own
   edit log, preventing cross-session leakage where session A could
   commit files only edited by session B.

Also adds docs/examples/claude-code-hooks/ with distributable hook
examples, settings.json, and setup README.

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: carlos-alm

.claude/hooks/guard-git.sh

@@ -43,34 +43,34 @@ deny() {
 # --- Block dangerous commands ---
 
 # git add . / git add -A / git add --all (broad staging)
-if echo "$COMMAND" | grep -qE '^\s*git\s+add\s+(\.\s*$|-A|--all)'; then
+if echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+add\s+(\.\s*$|-A|--all)'; then
   deny "BLOCKED: 'git add .' / 'git add -A' stages ALL changes including other sessions' work. Stage specific files instead: git add <file1> <file2>"
 fi
 
 # git reset (unstaging / hard reset)
-if echo "$COMMAND" | grep -qE '^\s*git\s+reset'; then
+if echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+reset'; then
   deny "BLOCKED: 'git reset' can unstage or destroy other sessions' work. To unstage your own files, use: git restore --staged <file>"
 fi
 
 # git checkout -- <file> (reverting files)
-if echo "$COMMAND" | grep -qE '^\s*git\s+checkout\s+--'; then
+if echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+checkout\s+--'; then
   deny "BLOCKED: 'git checkout -- <file>' reverts working tree changes and may destroy other sessions' edits. If you need to discard your own changes, be explicit about which files."
 fi
 
 # git restore (reverting) — EXCEPT git restore --staged (safe unstaging)
-if echo "$COMMAND" | grep -qE '^\s*git\s+restore'; then
-  if ! echo "$COMMAND" | grep -qE '^\s*git\s+restore\s+--staged'; then
+if echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+restore'; then
+  if ! echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+restore\s+--staged'; then
     deny "BLOCKED: 'git restore <file>' reverts working tree changes and may destroy other sessions' edits. To unstage files safely, use: git restore --staged <file>"
   fi
 fi
 
 # git clean (delete untracked files)
-if echo "$COMMAND" | grep -qE '^\s*git\s+clean'; then
+if echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+clean'; then
   deny "BLOCKED: 'git clean' deletes untracked files that may belong to other sessions."
 fi
 
 # git stash (hides all changes)
-if echo "$COMMAND" | grep -qE '^\s*git\s+stash'; then
+if echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+stash'; then
   deny "BLOCKED: 'git stash' hides all working tree changes including other sessions' work. In worktree mode, commit your changes directly instead."
 fi
 
@@ -115,7 +115,8 @@ fi
 # --- Commit validation against edit log ---
 
 if echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+commit'; then
-  PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+  # Use git worktree root so each worktree session has its own edit log
+  PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
   LOG_FILE="$PROJECT_DIR/.claude/session-edits.log"
 
   # If no edit log exists, allow (backward compat for sessions without tracking)

.claude/hooks/post-git-ops.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# post-git-ops.sh — PostToolUse hook for Bash tool calls
+# Detects git operations that change file state (rebase, revert, cherry-pick,
+# merge, pull) and:
+#   1. Rebuilds the codegraph incrementally (fixes stale dependency context)
+#   2. Logs changed files to session-edits.log (so commit validation works)
+#   3. Clears stale entries from codegraph-checked.log (so remind hook re-fires)
+# Always exits 0 (informational only, never blocks).
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Extract the command from tool_input JSON
+COMMAND=$(echo "$INPUT" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const p=JSON.parse(d).tool_input?.command||'';
+    if(p)process.stdout.write(p);
+  });
+" 2>/dev/null) || true
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Only act on git operations that change file content
+if ! echo "$COMMAND" | grep -qE '(^|\s|&&\s*)git\s+(rebase|revert|cherry-pick|merge|pull)\b'; then
+  exit 0
+fi
+
+# Use git worktree root so each worktree session has its own state
+PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+
+# --- 1. Rebuild codegraph ---
+DB_PATH="$PROJECT_DIR/.codegraph/graph.db"
+if [ -f "$DB_PATH" ]; then
+  if command -v codegraph &>/dev/null; then
+    codegraph build "$PROJECT_DIR" -d "$DB_PATH" 2>/dev/null || true
+  else
+    node "${CLAUDE_PROJECT_DIR:-$PROJECT_DIR}/src/cli.js" build "$PROJECT_DIR" -d "$DB_PATH" 2>/dev/null || true
+  fi
+fi
+
+# --- 2. Log changed files to session-edits.log ---
+# ORIG_HEAD is set by rebase, revert, cherry-pick, merge, and pull.
+# If the operation failed (conflicts), ORIG_HEAD may be stale — the
+# diff will either fail or return nothing, which is safe.
+CHANGED_FILES=$(git diff --name-only ORIG_HEAD HEAD 2>/dev/null) || true
+
+if [ -n "$CHANGED_FILES" ]; then
+  LOG_FILE="$PROJECT_DIR/.claude/session-edits.log"
+  mkdir -p "$(dirname "$LOG_FILE")"
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  while IFS= read -r rel_path; do
+    if [ -n "$rel_path" ]; then
+      echo "$TS $rel_path" >> "$LOG_FILE"
+    fi
+  done <<< "$CHANGED_FILES"
+fi
+
+# --- 3. Clear stale entries from codegraph-checked.log ---
+# After a git op that changes files, the remind-codegraph hook should
+# re-fire for those files so the agent re-checks context/impact.
+CHECKED_LOG="$PROJECT_DIR/.claude/codegraph-checked.log"
+if [ -n "$CHANGED_FILES" ] && [ -f "$CHECKED_LOG" ]; then
+  PATTERNS_FILE=$(mktemp)
+  echo "$CHANGED_FILES" > "$PATTERNS_FILE"
+  grep -vFf "$PATTERNS_FILE" "$CHECKED_LOG" > "${CHECKED_LOG}.tmp" 2>/dev/null || true
+  mv "${CHECKED_LOG}.tmp" "$CHECKED_LOG"
+  rm -f "$PATTERNS_FILE"
+fi
+
+exit 0

.claude/hooks/remind-codegraph.sh

@@ -39,8 +39,9 @@ case "$REL_PATH" in
   *.md|*.json|*.yml|*.yaml|*.toml|*.txt|*.lock|*.log|*.env*) exit 0 ;;
 esac
 
-# Check if we already reminded for this file
-CHECKED_LOG="${CLAUDE_PROJECT_DIR:-.}/.claude/codegraph-checked.log"
+# Use git worktree root so each worktree session has its own checked log
+WORK_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || WORK_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+CHECKED_LOG="$WORK_ROOT/.claude/codegraph-checked.log"
 if [ -f "$CHECKED_LOG" ] && grep -qF "$REL_PATH" "$CHECKED_LOG" 2>/dev/null; then
   exit 0
 fi
@@ -50,7 +51,7 @@ mkdir -p "$(dirname "$CHECKED_LOG")"
 echo "$REL_PATH" >> "$CHECKED_LOG"
 
 # Check if graph exists
-if [ ! -f "${CLAUDE_PROJECT_DIR:-.}/.codegraph/graph.db" ]; then
+if [ ! -f "$WORK_ROOT/.codegraph/graph.db" ]; then
   exit 0
 fi
 

.claude/hooks/track-edits.sh

@@ -23,7 +23,8 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# Use git worktree root so each worktree session has its own edit log
+PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 LOG_FILE="$PROJECT_DIR/.claude/session-edits.log"
 
 # Normalize to relative path with forward slashes

.claude/hooks/track-moves.sh

@@ -28,7 +28,8 @@ if ! echo "$COMMAND" | grep -qE '(^|\s|&&\s*)(mv|git\s+mv|cp)\s+'; then
   exit 0
 fi
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+# Use git worktree root so each worktree session has its own edit log
+PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) || PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 LOG_FILE="$PROJECT_DIR/.claude/session-edits.log"
 
 # Use node to parse the command and extract all file paths involved

.claude/settings.json

@@ -70,6 +70,11 @@
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/track-moves.sh\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-git-ops.sh\"",
+            "timeout": 30
           }
         ]
       }

docs/examples/claude-code-hooks/README.md

@@ -0,0 +1,73 @@
+# Claude Code Hooks for Codegraph
+
+Ready-to-use [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) that keep the codegraph database fresh and provide automatic dependency context as Claude edits your codebase.
+
+## Quick setup
+
+```bash
+# 1. Copy hooks into your project
+mkdir -p .claude/hooks
+cp docs/examples/claude-code-hooks/*.sh .claude/hooks/
+chmod +x .claude/hooks/*.sh
+
+# 2. Copy settings (or merge into your existing .claude/settings.json)
+cp docs/examples/claude-code-hooks/settings.json .claude/settings.json
+
+# 3. Add session logs to .gitignore
+echo ".claude/session-edits.log" >> .gitignore
+echo ".claude/codegraph-checked.log" >> .gitignore
+```
+
+## Hooks
+
+### Core hooks (recommended for all projects)
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `enrich-context.sh` | PreToolUse on Read/Grep | Injects `codegraph deps` output (imports, importers, definitions) into Claude's context when it reads a file |
+| `remind-codegraph.sh` | PreToolUse on Edit/Write | Reminds Claude to run `codegraph where`, `explain`, `context`, and `fn-impact` before editing a file. Fires once per file per session |
+| `update-graph.sh` | PostToolUse on Edit/Write | Runs `codegraph build` incrementally after each source file edit to keep the graph fresh |
+| `post-git-ops.sh` | PostToolUse on Bash | Detects `git rebase/revert/cherry-pick/merge/pull` and rebuilds the graph, logs changed files, and resets the remind tracker |
+
+### Parallel session safety hooks (recommended for multi-agent workflows)
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `guard-git.sh` | PreToolUse on Bash | Blocks `git add .`, `git reset`, `git restore`, `git clean`, `git stash`; validates commits only include files the session actually edited |
+| `track-edits.sh` | PostToolUse on Edit/Write | Logs every file edited via Edit/Write to `.claude/session-edits.log` |
+| `track-moves.sh` | PostToolUse on Bash | Logs files affected by `mv`/`git mv`/`cp` commands to `.claude/session-edits.log` |
+
+## Git operation resilience
+
+Git operations like `rebase`, `revert`, `cherry-pick`, `merge`, and `pull` change file contents without going through Edit/Write tools. Without `post-git-ops.sh`, this causes three problems:
+
+1. **Stale graph** — `enrich-context.sh` provides outdated dependency info
+2. **Blocked commits** — `guard-git.sh` rejects commits with rebase-modified files not in the edit log
+3. **Stale reminders** — `remind-codegraph.sh` won't re-fire for files changed by the git operation
+
+`post-git-ops.sh` fixes all three by detecting these git commands after they run and:
+- Rebuilding the codegraph (`codegraph build`)
+- Appending changed files (via `git diff --name-only ORIG_HEAD HEAD`) to the session edit log
+- Removing changed files from the remind tracker so the agent re-checks context
+
+## Worktree isolation
+
+All session-local state files (`session-edits.log`, `codegraph-checked.log`) use `git rev-parse --show-toplevel` to resolve the working tree root, rather than `CLAUDE_PROJECT_DIR`. This ensures each git worktree gets its own isolated state — session A's edit log doesn't leak into session B's commit validation.
+
+Without this fix, `CLAUDE_PROJECT_DIR` (which always points to the main project root) causes all worktree sessions to share a single edit log, defeating the parallel session safety model.
+
+## Customization
+
+**Subset installation:** You don't need all hooks. The core hooks work independently of the parallel session hooks. Pick what fits your workflow:
+
+- **Solo developer:** `enrich-context.sh` + `update-graph.sh` + `post-git-ops.sh`
+- **With reminders:** Add `remind-codegraph.sh`
+- **Multi-agent / worktrees:** Add `guard-git.sh` + `track-edits.sh` + `track-moves.sh`
+
+**Branch name validation:** The `guard-git.sh` in this repo's `.claude/hooks/` validates branch names against conventional prefixes (`feat/`, `fix/`, etc.). The example version omits this — add your own validation if needed.
+
+## Requirements
+
+- Node.js >= 20
+- `codegraph` installed globally or available via `npx`
+- Graph built at least once (`codegraph build`)

docs/examples/claude-code-hooks/enrich-context.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# enrich-context.sh — PreToolUse hook for Read and Grep tools
+# Provides dependency context from codegraph when reading/searching files.
+# Always exits 0 (informational only, never blocks).
+
+set -euo pipefail
+
+# Read the tool input from stdin
+INPUT=$(cat)
+
+# Extract file path and convert to relative — all in node to avoid
+# bash backslash issues on Windows/Git Bash
+REL_PATH=$(printf '%s' "$INPUT" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}" node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const o=JSON.parse(d).tool_input||{};
+    let p=(o.file_path||o.path||'').replace(/\\\\/g,'/');
+    if(!p)return;
+    let dir=(process.env.CLAUDE_PROJECT_DIR||'.').replace(/\\\\/g,'/');
+    if(p.startsWith(dir))p=p.slice(dir.length+1);
+    process.stdout.write(p);
+  });
+" 2>/dev/null) || true
+
+# Guard: no file path found
+if [ -z "$REL_PATH" ]; then
+  exit 0
+fi
+
+# Guard: codegraph DB must exist
+DB_PATH="${CLAUDE_PROJECT_DIR:-.}/.codegraph/graph.db"
+if [ ! -f "$DB_PATH" ]; then
+  exit 0
+fi
+
+# Run codegraph deps and capture output
+DEPS=""
+if command -v codegraph &>/dev/null; then
+  DEPS=$(codegraph deps "$REL_PATH" --json -d "$DB_PATH" 2>/dev/null) || true
+else
+  DEPS=$(npx --yes @optave/codegraph deps "$REL_PATH" --json -d "$DB_PATH" 2>/dev/null) || true
+fi
+
+# Guard: no output or error
+if [ -z "$DEPS" ] || [ "$DEPS" = "null" ]; then
+  exit 0
+fi
+
+# Output as additionalContext so it surfaces in Claude's context
+printf '%s' "$DEPS" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    try {
+      const o=JSON.parse(d);
+      const r=o.results?.[0]||{};
+      const imports=(r.imports||[]).map(i=>i.file).join(', ');
+      const importedBy=(r.importedBy||[]).map(i=>i.file).join(', ');
+      const defs=(r.definitions||[]).map(d=>d.kind+' '+d.name).join(', ');
+      const file=o.file||'unknown';
+      let ctx='[codegraph] '+file;
+      if(imports)ctx+='\n  Imports: '+imports;
+      if(importedBy)ctx+='\n  Imported by: '+importedBy;
+      if(defs)ctx+='\n  Defines: '+defs;
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+          additionalContext: ctx
+        }
+      }));
+    } catch(e) {}
+  });
+" 2>/dev/null || true
+
+exit 0