fix: feat: PreToolUse hook guards destructive operations in dev-agent sessions (#277)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

lib/agent-session.sh

@@ -45,6 +45,7 @@ agent_inject_into_session() {
 
 # Create a tmux session running Claude in the given workdir.
 # Installs a Stop hook for idle detection (see monitor_phase_loop).
+# Installs a PreToolUse hook to guard destructive Bash operations.
 # Optionally installs a PostToolUse hook for phase file write detection.
 # Args: session workdir [phase_file]
 # Returns 0 if session is ready, 1 otherwise.
@@ -120,6 +121,37 @@ create_agent_session() {
     fi
   fi
 
+  # Install PreToolUse hook for destructive operation guard: blocks force push
+  # to primary branch, rm -rf outside worktree, direct API merge calls, and
+  # checkout/switch to primary branch.  Claude sees the denial reason on exit 2
+  # and can self-correct.
+  local guard_hook_script="${FACTORY_ROOT}/lib/hooks/on-pretooluse-guard.sh"
+  if [ -x "$guard_hook_script" ]; then
+    local abs_workdir
+    abs_workdir=$(cd "$workdir" 2>/dev/null && pwd) || abs_workdir="$workdir"
+    local guard_hook_cmd="${guard_hook_script} ${PRIMARY_BRANCH:-main} ${abs_workdir}"
+    if [ -f "$settings" ]; then
+      jq --arg cmd "$guard_hook_cmd" '
+        if (.hooks.PreToolUse // [] | any(.[]; .hooks[]?.command == $cmd))
+        then .
+        else .hooks.PreToolUse = (.hooks.PreToolUse // []) + [{
+          matcher: "Bash",
+          hooks: [{type: "command", command: $cmd}]
+        }]
+        end
+      ' "$settings" > "${settings}.tmp" && mv "${settings}.tmp" "$settings"
+    else
+      jq -n --arg cmd "$guard_hook_cmd" '{
+        hooks: {
+          PreToolUse: [{
+            matcher: "Bash",
+            hooks: [{type: "command", command: $cmd}]
+          }]
+        }
+      }' > "$settings"
+    fi
+  fi
+
   # Install Stop hook for Matrix streaming: when MATRIX_THREAD_ID is set,
   # each Claude response is posted to the Matrix thread so humans can follow.
   local matrix_hook_script="${FACTORY_ROOT}/lib/hooks/on-stop-matrix.sh"

lib/hooks/on-pretooluse-guard.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# on-pretooluse-guard.sh — PreToolUse hook: guard destructive operations.
+#
+# Called by Claude Code before executing a Bash command in agent sessions.
+# Blocks:
+# - git push --force / -f to primary branch
+# - rm -rf targeting paths outside the worktree
+# - Direct Codeberg API merge calls (should go through phase protocol)
+# - git checkout / git switch to primary branch (stay on feature branch)
+#
+# Usage (in .claude/settings.json):
+#   {"type":"command","command":"this-script <primary_branch> <worktree_path>"}
+#
+# Args: $1 = primary branch (default: main), $2 = worktree absolute path
+#
+# Exit 0: allow (tool proceeds)
+# Exit 2: deny (reason on stdout — Claude sees it and can self-correct)
+
+primary_branch="${1:-main}"
+worktree_path="${2:-}"
+
+input=$(cat)
+
+# Extract the command string from hook JSON
+command_str=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$command_str" ] && exit 0
+
+# --- Guard 1: force push to primary branch ---
+if printf '%s' "$command_str" | grep -qE '\bgit\s+push\b' \
+   && printf '%s' "$command_str" | grep -qE '(--force|--force-with-lease|\s-[a-zA-Z]*f)\b' \
+   && printf '%s' "$command_str" | grep -qw "$primary_branch"; then
+  printf 'BLOCKED: Force-pushing to %s is not allowed. Push to your feature branch instead.\n' "$primary_branch"
+  exit 2
+fi
+
+# --- Guard 2: rm -rf outside worktree ---
+if [ -n "$worktree_path" ] \
+   && printf '%s' "$command_str" | grep -qE '\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)\b'; then
+  # Extract absolute paths from the command
+  abs_paths=$(printf '%s' "$command_str" | grep -oE "/[^[:space:];|&>\"']+" || true)
+  if [ -n "$abs_paths" ]; then
+    while IFS= read -r p; do
+      [ -z "$p" ] && continue
+      case "$p" in
+        "${worktree_path}"/*|"${worktree_path}") ;;  # Inside worktree — allow
+        /dev/*) ;;  # Device paths — allow
+        *)
+          printf 'BLOCKED: rm -rf targets %s which is outside the worktree (%s). Only delete files within your worktree.\n' "$p" "$worktree_path"
+          exit 2
+          ;;
+      esac
+    done <<< "$abs_paths"
+  fi
+fi
+
+# --- Guard 3: Direct Codeberg API merge calls ---
+if printf '%s' "$command_str" | grep -qE '/pulls/[0-9]+/merge'; then
+  printf 'BLOCKED: Direct API merge calls must go through the phase protocol. Push your changes and write PHASE:awaiting_ci — the orchestrator handles merges.\n'
+  exit 2
+fi
+
+# --- Guard 4: checkout/switch to primary branch ---
+# Blocks: git checkout main, git switch main
+# Allows: git checkout -b branch main, git checkout -- file
+if printf '%s' "$command_str" | grep -qE "\bgit\s+(checkout|switch)\s+${primary_branch}\b" \
+   && ! printf '%s' "$command_str" | grep -qE '\s--\s'; then
+  printf 'BLOCKED: Switching to %s is not allowed. Stay on your feature branch.\n' "$primary_branch"
+  exit 2
+fi
+
+exit 0