From e08e4600e48bbc2a0ec5c32d8dc20d6954485e67 Mon Sep 17 00:00:00 2001
From: Phillip Moore <w.phillip.moore@gmail.com>
Date: Tue, 26 May 2026 15:20:24 -0400
Subject: [PATCH] chore(hooks): add Claude Code hook guard, scrub legacy
 hooksPath refs

Add .claude/hooks/guard.sh PreToolUse hook, update settings.json with hook wiring and permissions, update docs.
---
 .claude/hooks/guard.sh                        | 30 +++++++++++++++++++
 .claude/settings.json                         | 18 +++++++++++
 CLAUDE.md                                     |  6 ++--
 docs/repository-standards.md                  |  2 +-
 docs/site/docs/development/developer-setup.md |  4 +--
 docs/standards-compliance-gates.md            |  2 +-
 6 files changed, 55 insertions(+), 7 deletions(-)
 create mode 100755 .claude/hooks/guard.sh

diff --git a/.claude/hooks/guard.sh b/.claude/hooks/guard.sh
new file mode 100755
index 0000000..f3548fe
--- /dev/null
+++ b/.claude/hooks/guard.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Claude Code PreToolUse hook shim.
+# Delegates to vrg-hook-guard if available; falls back to a
+# jq-based git/gh check that hard-denies when vergil-tooling
+# is not installed.
+set -euo pipefail
+
+if command -v vrg-hook-guard &>/dev/null; then
+  exec vrg-hook-guard
+fi
+
+input=$(cat)
+command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
+bin=$(printf '%s' "$command" | awk '{print $1}')
+base=$(basename "$bin" 2>/dev/null || printf '%s' "$bin")
+
+case "$base" in
+  git|gh)
+    jq -n '{
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "vergil-tooling is not available. This repository requires a correctly configured environment — all git/gh operations are blocked until resolved."
+      }
+    }'
+    exit 0
+    ;;
+esac
+
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
index 7a82d46..b39e710 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -1,4 +1,22 @@
 {
+  "permissions": {
+    "allow": [
+      "Bash(vrg-*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh"
+          }
+        ]
+      }
+    ]
+  },
   "extraKnownMarketplaces": {
     "vergil-marketplace": {
       "source": {
diff --git a/CLAUDE.md b/CLAUDE.md
index dfb320f..aefca2a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,9 +98,9 @@ All fields are required.
 
 ### Standard Tooling
 
-```bash
-git config core.hooksPath ../vergil-tooling/scripts/lib/git-hooks  # Enable git hooks
-```
+The Claude Code PreToolUse hook guard (`.claude/hooks/guard.sh`)
+blocks raw `git` and `gh` commands — use `vrg-git` / `vrg-gh`
+wrappers.
 
 VERGIL CLI tools (`vrg-commit`, `vrg-validate`, etc.) are
 pre-installed in the dev container images. No local setup required.
diff --git a/docs/repository-standards.md b/docs/repository-standards.md
index 8689122..3f3933a 100644
--- a/docs/repository-standards.md
+++ b/docs/repository-standards.md
@@ -15,7 +15,7 @@
 - Before modifying any files, check the current branch with `git status -sb`.
 - If on `develop`, create a short-lived `feature/*` branch or ask for explicit approval to proceed on `develop`.
 - If approval is granted to work on `develop`, call it out in the response and proceed only for that user-approved scope.
-- Enable repository git hooks before committing: `git config core.hooksPath .githooks`.
+- The Claude Code hook guard (`.claude/hooks/guard.sh`) blocks raw `git`/`gh` — use `vrg-git`/`vrg-gh`.
 
 ## Local validation
 
diff --git a/docs/site/docs/development/developer-setup.md b/docs/site/docs/development/developer-setup.md
index 6dd4580..65ca8bd 100644
--- a/docs/site/docs/development/developer-setup.md
+++ b/docs/site/docs/development/developer-setup.md
@@ -55,8 +55,8 @@ cd pymqrest
 # Install all dependencies including dev group
 uv sync --group dev
 
-# Enable repository git hooks
-git config core.hooksPath scripts/git-hooks
+# The Claude Code hook guard (.claude/hooks/guard.sh) blocks raw
+# git/gh commands — use vrg-git / vrg-gh wrappers.
 ```
 
 ## Running validation
diff --git a/docs/standards-compliance-gates.md b/docs/standards-compliance-gates.md
index 858f38c..b3473cf 100644
--- a/docs/standards-compliance-gates.md
+++ b/docs/standards-compliance-gates.md
@@ -34,7 +34,7 @@ Blocks commits on protected branches (`develop`, `release`, `main`,
 `release/*`) and enforces branch naming prefixes (`feature/*`, `bugfix/*`,
 `hotfix/*`).
 
-Enable with: `git config core.hooksPath scripts/git-hooks`
+Enforcement is now handled by the Claude Code hook guard (`.claude/hooks/guard.sh`).
 
 ### Commit message hook