chore(hooks): add Claude Code hook guard, scrub legacy hooksPath refs (#312)

Add .claude/hooks/guard.sh PreToolUse hook, update settings.json with hook wiring and permissions, update docs.

Author: wphillipmoore

.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

.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": {

CLAUDE.md

@@ -104,8 +104,8 @@ Java wrapper for the IBM MQ administrative REST API, ported from `pymqrest` (Pyt
 
 - **Java**: 17+ (install via `brew install openjdk@17` or SDKMAN)
 - **Maven**: Provided by Maven Wrapper (`./mvnw`), no separate install needed
-- **Git hooks**: `git config core.hooksPath ../vergil-tooling/scripts/lib/git-hooks`
-- **VERGIL CLI tools (`vrg-commit`, `vrg-validate`, etc.) are pre-installed in the dev container images
+- **Hook guard**: The Claude Code PreToolUse hook guard (`.claude/hooks/guard.sh`) blocks raw `git`/`gh` — use `vrg-git`/`vrg-gh`
+- **VERGIL CLI tools** (`vrg-commit`, `vrg-validate`, etc.) are pre-installed in the dev container images
 
 ### CI
 

docs/repository-standards.md

@@ -14,7 +14,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
 

docs/site/docs/development/developer-setup.md

@@ -52,8 +52,8 @@ cd mq-rest-admin-java
 # Compile and run all quality checks
 ./mvnw verify
 
-# 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.
 ```
 
 ## Building
@@ -122,18 +122,11 @@ scripts/dev/mq_stop.sh
 See [local MQ container](local-mq-container.md) for full container configuration,
 credentials, gateway routing, and troubleshooting.
 
-## Git hooks
+## Claude Code hook guard
 
-Enable repository git hooks before committing:
-
-```bash
-git config core.hooksPath scripts/git-hooks
-```
-
-The hooks enforce:
-
-- **pre-commit**: Branch naming conventions and protected branch rules
-- **commit-msg**: Conventional Commits format and co-author trailer validation
+The `.claude/hooks/guard.sh` PreToolUse hook blocks raw `git` and
+`gh` commands in AI agent sessions — all operations must go through
+the `vrg-git` / `vrg-gh` wrappers.
 
 ## Documentation