@imdeadpool/guardex 7.0.0 → 7.0.2

package/bin/multiagent-safety.js

@@ -54,6 +54,7 @@ const TEMPLATE_FILES = [
   'githooks/pre-commit',
   'githooks/pre-push',
   'githooks/post-merge',
+  'githooks/post-checkout',
   'codex/skills/guardex/SKILL.md',
   'codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   'claude/commands/guardex.md',
@@ -97,6 +98,7 @@ const EXECUTABLE_RELATIVE_PATHS = new Set([
   '.githooks/pre-commit',
   '.githooks/pre-push',
   '.githooks/post-merge',
+  '.githooks/post-checkout',
 ]);
 
 const CRITICAL_GUARDRAIL_PATHS = new Set([
@@ -104,6 +106,7 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   '.githooks/pre-commit',
   '.githooks/pre-push',
   '.githooks/post-merge',
+  '.githooks/post-checkout',
   'scripts/agent-branch-start.sh',
   'scripts/agent-branch-finish.sh',
   'scripts/agent-worktree-prune.sh',
@@ -131,6 +134,7 @@ const MANAGED_GITIGNORE_PATHS = [
   '.githooks/pre-commit',
   '.githooks/pre-push',
   '.githooks/post-merge',
+  '.githooks/post-checkout',
   'oh-my-codex/',
   '.codex/skills/guardex/SKILL.md',
   '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.0",
+  "version": "7.0.2",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,

package/templates/AGENTS.multiagent-safety.md

@@ -1,7 +1,7 @@
 <!-- multiagent-safety:START -->
 ## Multi-Agent Safety Contract
 
-**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `scripts/agent-branch-start.sh "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active.
+**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `scripts/agent-branch-start.sh "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions — bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 
 **Ownership.** Before editing, claim files: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
 

package/templates/githooks/post-checkout

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# post-checkout <prev_head> <new_head> <branch_checkout_flag>
+branch_checkout="${3:-0}"
+[[ "$branch_checkout" == "1" ]] || exit 0
+
+if [[ "${GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Skip in secondary worktrees — only the primary checkout is guarded.
+git_dir_abs="$(cd "$(git rev-parse --git-dir)" && pwd -P)"
+common_dir_abs="$(cd "$(git rev-parse --git-common-dir)" && pwd -P)"
+if [[ "$git_dir_abs" != "$common_dir_abs" ]]; then
+  exit 0
+fi
+
+new_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+# Parse the latest reflog entry; post-checkout writes "checkout: moving from <prev> to <new>".
+prev_branch="$(git reflog -1 HEAD 2>/dev/null | sed -n 's/.*checkout: moving from \([^ ]*\) to .*/\1/p' || true)"
+
+[[ -n "$prev_branch" && -n "$new_branch" && "$prev_branch" != "$new_branch" ]] || exit 0
+
+protected_raw="${GUARDEX_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
+[[ -n "$protected_raw" ]] || protected_raw="dev main master"
+protected_raw="${protected_raw//,/ }"
+
+is_protected() {
+  local branch="$1"
+  for p in $protected_raw; do
+    [[ "$branch" == "$p" ]] && return 0
+  done
+  return 1
+}
+
+# Only guard when moving AWAY from a protected primary branch.
+is_protected "$prev_branch" || exit 0
+
+is_agent=0
+if [[ -n "${CLAUDECODE:-}" \
+   || -n "${CLAUDE_CODE_SESSION_ID:-}" \
+   || -n "${CODEX_THREAD_ID:-}" \
+   || -n "${OMX_SESSION_ID:-}" \
+   || "${CODEX_CI:-0}" == "1" ]]; then
+  is_agent=1
+fi
+
+echo "" >&2
+echo "[agent-primary-branch-guard] Primary checkout switched branches." >&2
+echo "[agent-primary-branch-guard]   from: $prev_branch (protected)" >&2
+echo "[agent-primary-branch-guard]   to:   $new_branch" >&2
+echo "[agent-primary-branch-guard] The primary working tree must stay on its base/protected branch." >&2
+echo "[agent-primary-branch-guard] Use 'git worktree add' (or scripts/agent-branch-start.sh) for feature work." >&2
+
+if [[ "$is_agent" == "1" ]]; then
+  echo "[agent-primary-branch-guard] Agent session detected — reverting to '$prev_branch'." >&2
+  echo "[agent-primary-branch-guard] Bypass with GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1 if truly intentional." >&2
+  if git diff --quiet && git diff --cached --quiet; then
+    GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1 git checkout "$prev_branch" >/dev/null 2>&1 || true
+    echo "[agent-primary-branch-guard] Reverted to '$prev_branch'." >&2
+  else
+    echo "[agent-primary-branch-guard] Working tree dirty — auto-revert skipped." >&2
+    echo "[agent-primary-branch-guard] Fix manually: git stash && git checkout $prev_branch" >&2
+  fi
+else
+  echo "[agent-primary-branch-guard] Bypass with GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1 if intentional." >&2
+fi

package/templates/scripts/agent-branch-finish.sh

@@ -194,6 +194,20 @@ is_clean_worktree() {
 source_worktree="$(get_worktree_for_branch "$SOURCE_BRANCH")"
 created_source_probe=0
 source_probe_path=""
+integration_worktree=""
+
+cleanup() {
+  if [[ -n "$integration_worktree" && -d "$integration_worktree" ]]; then
+    git -C "$repo_root" worktree remove "$integration_worktree" --force >/dev/null 2>&1 || true
+  fi
+  if [[ "$created_source_probe" -eq 1 && -n "$source_probe_path" && -d "$source_probe_path" ]]; then
+    # Abort any in-progress git op so `worktree remove --force` succeeds on conflict-stuck probes.
+    git -C "$source_probe_path" rebase --abort >/dev/null 2>&1 || true
+    git -C "$source_probe_path" merge --abort >/dev/null 2>&1 || true
+    git -C "$repo_root" worktree remove "$source_probe_path" --force >/dev/null 2>&1 || true
+  fi
+}
+trap cleanup EXIT
 
 if [[ -z "$source_worktree" ]]; then
   source_probe_path="${agent_worktree_root}/__source-probe-${SOURCE_BRANCH//\//__}-$(date +%Y%m%d-%H%M%S)"
@@ -261,16 +275,6 @@ mkdir -p "$(dirname "$integration_worktree")"
 git -C "$repo_root" worktree add "$integration_worktree" "$start_ref" >/dev/null
 git -C "$integration_worktree" checkout -b "$integration_branch" >/dev/null
 
-cleanup() {
-  if [[ -d "$integration_worktree" ]]; then
-    git -C "$repo_root" worktree remove "$integration_worktree" --force >/dev/null 2>&1 || true
-  fi
-  if [[ "$created_source_probe" -eq 1 && -n "$source_probe_path" && -d "$source_probe_path" ]]; then
-    git -C "$repo_root" worktree remove "$source_probe_path" --force >/dev/null 2>&1 || true
-  fi
-}
-trap cleanup EXIT
-
 if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
   git -C "$source_worktree" fetch origin "$BASE_BRANCH" --quiet