diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index fc7716508..3bc996ba3 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -54,6 +54,12 @@
       "source": "./plugins/actionlint",
       "category": "formatting",
       "tags": ["actionlint", "github-actions", "workflow", "yaml", "linter", "hook"]
+    },
+    {
+      "name": "guardrails",
+      "source": "./plugins/guardrails",
+      "category": "security",
+      "tags": ["guard", "security", "secrets", "hardcoded-paths", "git", "cli-flags", "hook"]
     }
   ]
 }
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 07665c0ac..00878f629 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -148,6 +148,10 @@ jobs:
           persist-credentials: false
       - name: Check for machine-specific paths
         uses: melodic-software/ci-workflows/.github/actions/machine-specific-paths@2275e82c502d29b468e3ee2b9c11b2de69b1677f # b6431a1 2026-06-26
+        with:
+          # The guardrails plugin bundles a path-detection pattern lib whose
+          # regex bodies self-match this lane's own detector.
+          exclude: ':(exclude)plugins/guardrails/lib/path-detection/**'
 
   eol-renormalize:
     runs-on: ubuntu-latest
diff --git a/README.md b/README.md
index eb40a784b..201383641 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 | [`desktop-notification`](plugins/desktop-notification) | Hook | Alerts you when Claude Code needs input via an audible bell, an OSC 9 terminal notification, and an OS-native toast (macOS/Linux) on permission and idle prompts. |
 | [`powershell-format`](plugins/powershell-format) | Hook | Formats and lints PowerShell on edit via PSScriptAnalyzer, only when the repo opts in with a `PSScriptAnalyzerSettings.psd1`, using the consuming repo's own analyzer settings. |
 | [`actionlint`](plugins/actionlint) | Hook | Lints GitHub Actions workflow files (`.github/workflows/*.yml`/`.yaml`) on edit via the `actionlint` already on your `PATH` — advisory findings, never blocking. |
+| [`guardrails`](plugins/guardrails) | Hook | Bundles four independently-toggleable PreToolUse safety guards: secret-pattern detection, hardcoded machine-path check, git hook-bypass blocking (`--no-verify`, `core.hooksPath`, `LEFTHOOK=0`), and advisory CLI-flag verification. |
 
 Install one: `/plugin install <plugin-name>@melodic-software`.
 
diff --git a/docs/conventions/hook-telemetry/README.md b/docs/conventions/hook-telemetry/README.md
index a90cc3164..4096c381c 100644
--- a/docs/conventions/hook-telemetry/README.md
+++ b/docs/conventions/hook-telemetry/README.md
@@ -154,3 +154,7 @@ producers without coordinating with them or each other.
 |----------|--------------|-------------|
 | `markdown-formatter` plugin | `markdown-format` | `data/markdown-format.schema.json` |
 | `desktop-notification` plugin | `desktop-notification` | `data/desktop-notification.schema.json` |
+| `guardrails` plugin | `secret-pattern-detection` | `data/secret-pattern-detection.schema.json` |
+| `guardrails` plugin | `hardcoded-path-check` | `data/hardcoded-path-check.schema.json` |
+| `guardrails` plugin | `cli-flag-verify` | `data/cli-flag-verify.schema.json` |
+| `guardrails` plugin | `block-no-verify` | `data/block-no-verify.schema.json` |
diff --git a/docs/conventions/hook-telemetry/data/block-no-verify.schema.json b/docs/conventions/hook-telemetry/data/block-no-verify.schema.json
new file mode 100644
index 000000000..1bc45100a
--- /dev/null
+++ b/docs/conventions/hook-telemetry/data/block-no-verify.schema.json
@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/hook-telemetry/data/block-no-verify.schema.json",
+  "title": "block-no-verify telemetry data",
+  "description": "Per-hook `data` payload for the block-no-verify guard. Discovered from the envelope `hook` value \"block-no-verify\". Evolves additive-only. Carries NO full command string.",
+  "type": "object",
+  "required": ["tool", "subject", "form"],
+  "additionalProperties": true,
+  "properties": {
+    "tool": {
+      "type": "string",
+      "description": "Always \"Bash\" — this guard matches only Bash tool calls."
+    },
+    "subject": {
+      "type": "string",
+      "description": "Privacy-safe command subject `Bash:<first-token>` with leading sudo / env-assignment prefixes stripped and the token basenamed. NEVER the full command or its arguments."
+    },
+    "form": {
+      "type": "string",
+      "description": "The bypass form when blocked: \"no-verify\" | \"hooksPath\" | \"hook-manager-env\" | \"too-long\" (command exceeded the parse cap and was blocked fail-closed). Empty string when the command was allowed (status ok)."
+    }
+  }
+}
diff --git a/docs/conventions/hook-telemetry/data/cli-flag-verify.schema.json b/docs/conventions/hook-telemetry/data/cli-flag-verify.schema.json
new file mode 100644
index 000000000..dbd52c3ac
--- /dev/null
+++ b/docs/conventions/hook-telemetry/data/cli-flag-verify.schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/hook-telemetry/data/cli-flag-verify.schema.json",
+  "title": "cli-flag-verify telemetry data",
+  "description": "Per-hook `data` payload for the cli-flag-verify advisory hook. Discovered from the envelope `hook` value \"cli-flag-verify\". Evolves additive-only.",
+  "type": "object",
+  "required": ["tool", "file", "findings"],
+  "additionalProperties": true,
+  "properties": {
+    "tool": {
+      "type": "string",
+      "description": "Claude Code tool that triggered the hook. May be an empty string — this advisory hook resolves only the file path, not the tool name."
+    },
+    "file": {
+      "type": "string",
+      "description": "Path of the scanned file, relative to the consuming repo root when resolvable."
+    },
+    "findings": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Unknown (likely-hallucinated) CLI invocations, each `<bin> [<subcmd>...] <flag>` (public CLI identifiers, not secret). Empty array when every scanned flag verified (status ok)."
+    }
+  }
+}
diff --git a/docs/conventions/hook-telemetry/data/hardcoded-path-check.schema.json b/docs/conventions/hook-telemetry/data/hardcoded-path-check.schema.json
new file mode 100644
index 000000000..b98b4cfc6
--- /dev/null
+++ b/docs/conventions/hook-telemetry/data/hardcoded-path-check.schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/hook-telemetry/data/hardcoded-path-check.schema.json",
+  "title": "hardcoded-path-check telemetry data",
+  "description": "Per-hook `data` payload for the hardcoded-path-check guard. Discovered from the envelope `hook` value \"hardcoded-path-check\". Evolves additive-only. Carries NO matched path — only category labels.",
+  "type": "object",
+  "required": ["tool", "file", "violations"],
+  "additionalProperties": true,
+  "properties": {
+    "tool": {
+      "type": "string",
+      "description": "Claude Code tool that triggered the hook (Write, Edit, or NotebookEdit)."
+    },
+    "file": {
+      "type": "string",
+      "description": "Path of the write target, relative to the consuming repo root when resolvable."
+    },
+    "violations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Path-category labels detected in the new content (e.g. \"Linux user path detected\", \"Windows user path detected\"), one per category. NEVER the matched machine-specific path. Empty array on a clean scan (status ok)."
+    }
+  }
+}
diff --git a/docs/conventions/hook-telemetry/data/secret-pattern-detection.schema.json b/docs/conventions/hook-telemetry/data/secret-pattern-detection.schema.json
new file mode 100644
index 000000000..505f28f45
--- /dev/null
+++ b/docs/conventions/hook-telemetry/data/secret-pattern-detection.schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/hook-telemetry/data/secret-pattern-detection.schema.json",
+  "title": "secret-pattern-detection telemetry data",
+  "description": "Per-hook `data` payload for the secret-pattern-detection guard. Discovered from the envelope `hook` value \"secret-pattern-detection\". Evolves additive-only. Carries NO secret material — only category labels.",
+  "type": "object",
+  "required": ["tool", "file", "violations"],
+  "additionalProperties": true,
+  "properties": {
+    "tool": {
+      "type": "string",
+      "description": "Claude Code tool that triggered the hook (Write, Edit, or NotebookEdit)."
+    },
+    "file": {
+      "type": "string",
+      "description": "Path of the write target, relative to the consuming repo root when resolvable."
+    },
+    "violations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Secret-category labels detected in the new content (e.g. \"AWS Access Key\", \"GitHub PAT\"), one per matched pattern. NEVER the secret value or the matched line. Empty array on a clean scan (status ok)."
+    }
+  }
+}
diff --git a/docs/conventions/hook-telemetry/examples/block-no-verify.json b/docs/conventions/hook-telemetry/examples/block-no-verify.json
new file mode 100644
index 000000000..0281c962a
--- /dev/null
+++ b/docs/conventions/hook-telemetry/examples/block-no-verify.json
@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "timestamp": "2026-07-10T14:26:55Z",
+  "hook": "block-no-verify",
+  "hook_event": "PreToolUse",
+  "status": "blocked",
+  "duration_ms": 9,
+  "data": {
+    "tool": "Bash",
+    "subject": "Bash:git",
+    "form": "no-verify"
+  }
+}
diff --git a/docs/conventions/hook-telemetry/examples/cli-flag-verify.json b/docs/conventions/hook-telemetry/examples/cli-flag-verify.json
new file mode 100644
index 000000000..736c6c1a5
--- /dev/null
+++ b/docs/conventions/hook-telemetry/examples/cli-flag-verify.json
@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "timestamp": "2026-07-10T14:25:12Z",
+  "hook": "cli-flag-verify",
+  "hook_event": "PostToolUse",
+  "status": "ok",
+  "duration_ms": 512,
+  "data": {
+    "tool": "",
+    "file": "docs/setup.md",
+    "findings": ["claude --max-turns"]
+  }
+}
diff --git a/docs/conventions/hook-telemetry/examples/hardcoded-path-check.json b/docs/conventions/hook-telemetry/examples/hardcoded-path-check.json
new file mode 100644
index 000000000..372617468
--- /dev/null
+++ b/docs/conventions/hook-telemetry/examples/hardcoded-path-check.json
@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "timestamp": "2026-07-10T14:23:41Z",
+  "hook": "hardcoded-path-check",
+  "hook_event": "PreToolUse",
+  "status": "blocked",
+  "duration_ms": 74,
+  "data": {
+    "tool": "Edit",
+    "file": "scripts/deploy.sh",
+    "violations": ["Linux user path detected"]
+  }
+}
diff --git a/docs/conventions/hook-telemetry/examples/secret-pattern-detection.json b/docs/conventions/hook-telemetry/examples/secret-pattern-detection.json
new file mode 100644
index 000000000..aa35ffeb4
--- /dev/null
+++ b/docs/conventions/hook-telemetry/examples/secret-pattern-detection.json
@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "timestamp": "2026-07-10T14:22:07Z",
+  "hook": "secret-pattern-detection",
+  "hook_event": "PreToolUse",
+  "status": "blocked",
+  "duration_ms": 260,
+  "data": {
+    "tool": "Write",
+    "file": "src/config.env",
+    "violations": ["AWS Access Key", "GitHub PAT"]
+  }
+}
diff --git a/plugins/guardrails/.claude-plugin/plugin.json b/plugins/guardrails/.claude-plugin/plugin.json
new file mode 100644
index 000000000..3fbeb68f3
--- /dev/null
+++ b/plugins/guardrails/.claude-plugin/plugin.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "guardrails",
+  "version": "0.1.0",
+  "description": "Four PreToolUse safety guards that block secret/credential writes, hardcoded machine-specific paths, git hook-bypass attempts, and (advisory) hallucinated CLI flags — each independently toggleable.",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "keywords": ["guard", "security", "secrets", "hooks", "pretooluse", "git", "hardcoded-paths", "cli-flags"]
+}
diff --git a/plugins/guardrails/README.md b/plugins/guardrails/README.md
new file mode 100644
index 000000000..8edf88e17
--- /dev/null
+++ b/plugins/guardrails/README.md
@@ -0,0 +1,109 @@
+# guardrails
+
+A Claude Code plugin bundling four **PreToolUse safety guards** that catch
+risky agent actions the moment they happen — before a write lands or a bash
+command runs. Each guard is independently toggleable, so you run exactly the
+subset you want.
+
+## The guards
+
+| Guard | Event / matcher | Behavior | What it catches |
+|-------|-----------------|----------|-----------------|
+| **secret-pattern-detection** | PreToolUse · Write \| Edit \| NotebookEdit | **Blocks** (exit 2) | High-confidence secret/credential patterns (AWS/GitHub/GitLab/Slack/Stripe/OpenAI keys, PEM private keys) in new file content. |
+| **hardcoded-path-check** | PreToolUse · Write \| Edit \| NotebookEdit | **Blocks** (exit 2) | Hardcoded machine-specific paths — Windows drive-letter homes, macOS/Linux user homes, machine-specific repo checkout roots. |
+| **block-no-verify** | PreToolUse · Bash | **Blocks** (exit 2) | Git hook-bypass attempts on `git commit` / `git push`: `--no-verify` / `-n`, `core.hooksPath=` assignment, and `LEFTHOOK=0` / `LEFTHOOK_*=false` env-var prefixes (including inside compound `cd … && …` commands). |
+| **cli-flag-verify** | PostToolUse · Write \| Edit | **Advisory** (exit 0) | Hallucinated CLI flags — a `--flag` written as a command that does not exist in the binary's actual `--help` output. Surfaces via `additionalContext`, never blocks. |
+
+The three blocking guards feed their stderr message back to Claude as
+actionable fix guidance. The advisory guard surfaces its findings the same way
+but always allows the edit.
+
+### Scope notes
+
+- **Hook-manager coverage.** `block-no-verify` recognizes the **lefthook**
+  env-var disable prefix (`LEFTHOOK=0` / `LEFTHOOK_*=false`). Other managers'
+  disable env vars (husky, pre-commit, …) are **not** matched — but the
+  manager-agnostic `--no-verify` / `-n` and `core.hooksPath=` checks catch those
+  bypasses regardless of which manager runs the hooks.
+- **Argv-grammar-faithful matching (and its residual).** `block-no-verify`
+  parses the command the way the shell builds argv — segmenting on unquoted
+  operators and tokenizing each segment honoring `'…'`, `"…"`, `$'…'` (ANSI-C),
+  and backslash escapes. It detects literal `git commit`/`git push`
+  `--no-verify` / `-n` / `core.hooksPath=` across quoting, escaping, wrappers
+  (`env -i git …`, `nice git …`, `sudo -u x git …`), and git global options
+  (`git -C <dir> commit …`). A `--no-verify` inside a quoted `-m` value stays a
+  message, not a flag. It does **not** evaluate shell variable / command
+  substitution (`$VAR`, `$(…)`, `$IFS`) — a determined author can construct an
+  expansion-based bypass. **This is a friction guard against accidental/casual
+  bypass, not a sandbox.** (A command longer than 16 KB is not parsed and is
+  blocked fail-closed.)
+
+## Per-hook kill switches
+
+Each guard is toggled by its own env var (default **on**; set to `false` for a
+clean no-op). This per-hook control is the bundle's core contract — disable one
+guard without touching the others.
+
+| Guard | Kill switch |
+|-------|-------------|
+| secret-pattern-detection | `HOOK_SECRET_PATTERN_DETECTION_ENABLED` |
+| hardcoded-path-check | `HOOK_HARDCODED_PATH_CHECK_ENABLED` |
+| block-no-verify | `HOOK_BLOCK_NO_VERIFY_ENABLED` |
+| cli-flag-verify | `HOOK_CLI_FLAG_VERIFY_ENABLED` |
+
+Set them in your settings `env` block:
+
+```json
+{ "env": { "HOOK_HARDCODED_PATH_CHECK_ENABLED": "false" } }
+```
+
+## Consumer seams
+
+The guards scope and tune themselves to **your** repository — they ship no
+repo-specific policy of their own:
+
+- **Project scoping.** `secret-pattern-detection` and `hardcoded-path-check`
+  only police files under `$CLAUDE_PROJECT_DIR`; a write into a sibling repo is
+  that repo's concern. Secret scanning fails **closed** — if the project root
+  cannot be resolved, it scans anyway.
+- **Gitignore is the allowlist.** `hardcoded-path-check` skips any file
+  `git check-ignore` matches against your `$CLAUDE_PROJECT_DIR` — put
+  machine-local files (`settings.local.json`, `.venv/`, …) in your
+  `.gitignore` and they are exempt automatically.
+- **Secret allowlist.** A generic built-in allowlist exempts dependency caches
+  (`.venv/`, `node_modules/`), `.env.example` / `.sample` / `.template`
+  placeholders, `tests/fixtures` / `tests/testdata` trees, `settings.local.json`,
+  `CLAUDE.local.md`, and hook scripts.
+- **CLI-flag tuning.** `cli-flag-verify` checks a default binary set
+  (`claude gh dotnet docker npm kubectl terraform az aws`); override with
+  `HOOK_CLI_FLAG_VERIFY_BINS=bin1,bin2,…` and skip specific binaries with
+  `HOOK_CLI_FLAG_VERIFY_SKIP_BINS=bin1,bin2`.
+
+## Telemetry (opt-in)
+
+Every guard emits one structured [hook-telemetry](../../docs/conventions/hook-telemetry/README.md)
+envelope per run to whatever `HOOK_TELEMETRY_SINK` names — carrying `status`
+(`blocked` on a guard block, `ok` otherwise), `duration_ms`, and a privacy-safe
+`data` payload (category **labels** only — never a secret value, matched path,
+or full command). Unset `HOOK_TELEMETRY_SINK` → no-op; the guards behave exactly
+as before.
+
+## Requirements
+
+- **bash 5.0+** and **jq** — the guards' runtime. Without **jq**, each guard
+  fails **open** (disabled) and prints a one-line stderr notice — never a silent
+  disable.
+- On Windows, **Git Bash** (the hooks run via Git Bash's bash).
+- `cli-flag-verify` runs `<bin> --help` for the binaries it scans; findings
+  require those binaries on PATH (missing binaries are skipped, never flagged).
+
+## Install
+
+```shell
+/plugin marketplace add melodic-software/claude-code-plugins
+/plugin install guardrails@melodic-software
+```
+
+## License
+
+[MIT](../../LICENSE).
diff --git a/plugins/guardrails/hooks/block-no-verify.sh b/plugins/guardrails/hooks/block-no-verify.sh
new file mode 100755
index 000000000..42f26ed52
--- /dev/null
+++ b/plugins/guardrails/hooks/block-no-verify.sh
@@ -0,0 +1,488 @@
+#!/usr/bin/env bash
+# PreToolUse hook: block git hook-bypass attempts on git commit and git push.
+# Triggered on Bash tool calls.
+#
+# Catches three bypass surfaces on a real `git commit` / `git push`:
+#   1. --no-verify / -n on git commit (skips pre-commit + commit-msg hooks)
+#      and --no-verify on git push (skips pre-push hook)
+#   2. core.hooksPath assignment on git commit/push (disables all git hooks)
+#   3. hook-manager env-var prefix (LEFTHOOK=0 / LEFTHOOK_*=0|false) on git
+#      commit/push (disables the hook manager for one invocation)
+#
+# Detection is ARGV-GRAMMAR-FAITHFUL: the command is parsed the way the shell
+# builds argv — top-level segments split on unquoted control operators, each
+# tokenized into argv words honoring '…', "…", $'…' (ANSI-C), and backslash
+# escapes — then a real git executable (basename `git`, case/.exe-folded on
+# Windows) is found at the segment's command position — after leading env-var
+# assignments and known wrappers (`env -i git …`, `nice git …`, `sudo -u x git …`
+# are transparent) — its subcommand resolved
+# past git global options (including arg-consuming ones like `-C <dir>`), and
+# the bypass tokens matched on the parsed argv.
+#
+# SCOPE (documented residual): this is a static matcher over the literal
+# command string. It does NOT evaluate shell variable / command substitution
+# ($VAR, $(…), $IFS) — a determined author can construct an expansion-based
+# bypass. It is a friction guard against accidental/casual bypass, not a
+# sandbox. The ONLY supported deliberate bypass is the kill switch
+# (HOOK_BLOCK_NO_VERIFY_ENABLED=false).
+#
+# BLOCKING: exits 2 on any detected bypass form.
+
+set -uo pipefail
+
+# shellcheck source=hook-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/hook-utils.sh"
+
+hook::check_enabled "BLOCK_NO_VERIFY"
+
+# High-res start stamp for the telemetry envelope. EPOCHREALTIME is Bash 5.0+;
+# on older bash it is unset, so default to empty and skip telemetry (the block
+# still fires). Referencing it bare under `set -u` would abort before exit.
+start=${EPOCHREALTIME:-}
+
+# jq is required to parse the tool payload. Fail OPEN when it is absent, but make
+# the degraded state visible rather than silently disabling the guard.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "guardrails/block-no-verify: jq not found on PATH — guard disabled (install jq to enable)." >&2
+  exit 0
+fi
+
+# Read inherited fd0 directly (bare cat) — NEVER `</dev/stdin`: on Windows Git
+# Bash, CC spawns hooks with stdin = a Win32 pipe that `/dev/stdin` cannot
+# resolve (ENOENT → silent no-op).
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null | tr -d '\r')
+[[ -n "$COMMAND" ]] || exit 0
+
+# Above this length the command is not parsed — a pathologically long command is
+# assumed to be obfuscation and blocked FAIL-CLOSED (generous cap; real git
+# commands are well under it). The linear parser keeps normal commands cheap.
+MAX_COMMAND_LEN=16384
+
+# Privacy-safe telemetry subject: `Bash:<first-token>` with leading `sudo` /
+# env-assignment prefixes stripped and the token basenamed. Never the full
+# command.
+bash_subject() {
+  local cmd="$1" tok
+  tok="${cmd%%[[:space:]]*}"
+  while [[ "$tok" == "sudo" || "$tok" == *=* ]] \
+    && [[ -n "$cmd" && "$cmd" == *[[:space:]]* ]]; do
+    cmd="${cmd#*[[:space:]]}"
+    cmd="${cmd#"${cmd%%[![:space:]]*}"}"
+    tok="${cmd%%[[:space:]]*}"
+  done
+  printf 'Bash:%s' "${tok##*/}"
+}
+
+SUBJECT=$(bash_subject "$COMMAND")
+
+# Emit one telemetry envelope: $1 status, $2 form ("" when not blocked). Gated
+# on the high-res start stamp and the opt-in sink, so the unwired default path
+# spawns no telemetry-only subprocess.
+emit_tel() {
+  [[ -n "$start" ]] || return 0
+  hook::telemetry_enabled || return 0
+  local data
+  data=$(jq -n --arg subject "$SUBJECT" --arg form "$2" \
+    '{tool:"Bash",subject:$subject,form:$form}' 2>/dev/null) || data='{"tool":"Bash","subject":"","form":""}'
+  hook::emit_telemetry "block-no-verify" "PreToolUse" "$1" "$start" "$data" "${CLAUDE_PROJECT_DIR:-}"
+}
+
+block() {
+  local form="$1" msg1="$2" msg2="$3"
+  echo "$msg1" >&2
+  echo "$msg2" >&2
+  emit_tel "blocked" "$form"
+  exit 2
+}
+
+# Does an argv word name the git executable? Basename compared exactly on POSIX;
+# on Windows/MSYS also case-folded and `.exe`-stripped (mirrors the OS-gate in
+# hook-utils normalize_path) so `GIT` / `git.exe` are caught there but a
+# case-variant stays distinct on a case-sensitive POSIX filesystem.
+is_git_bin() {
+  local b="${1##*/}"
+  b="${b##*\\}"
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32)
+    local lc="${b,,}"
+    lc="${lc%.exe}"
+    [[ "$lc" == "git" ]]
+    ;;
+  *) [[ "$b" == "git" ]] ;;
+  esac
+}
+
+# Decode an ANSI-C `$'…'` body to its literal bytes (\xHH, \NNN octal, \uHHHH,
+# \n, \\, …). %-escaped so the body can never act as a printf format specifier;
+# `--` guards a body that begins with `-`. Errors are swallowed (fail-open on a
+# malformed body — the raw text still flows through the caller unchanged).
+ansi_c_decode() {
+  local b="${1//%/%%}"
+  # shellcheck disable=SC2059  # the body IS the format — that is how ANSI-C escapes decode; %-escaped above so it cannot inject a specifier
+  printf -- "$b" 2>/dev/null
+}
+
+# Locate a real `git` executable at the segment's command position (after
+# env-var prefixes and known wrappers), or return 1 when absent. Results go in
+# globals, NOT a $( ) echo: `env -S` splicing rewrites the argv, and the caller
+# must match on the rewritten words, so the index alone is not enough.
+#   RESOLVED_GI    — index of git in RESOLVED_WORDS
+#   RESOLVED_WORDS — the (possibly rewritten) segment argv
+# shellcheck disable=SC1003  # '\' compares a literal backslash char, not a quote escape
+resolve_git_index() {
+  RESOLVED_WORDS=("$@")
+  RESOLVED_GI=-1
+  local -n w=RESOLVED_WORDS
+  local n=${#w[@]} i=0 tok
+
+  while ((i < n)); do
+    tok="${w[i]}"
+    if [[ "$tok" == *=* ]]; then
+      ((i++))
+      continue
+    fi
+
+    case "${tok##*/}" in
+    env)
+      ((i++))
+      while ((i < n)) && [[ "${w[i]}" == -* ]]; do
+        case "${w[i]}" in
+        # -S/--split-string re-splits its operand into argv (GNU env), so a
+        # quoted 'git commit --no-verify' would otherwise hide from the
+        # resolver as one non-git word. Splice the split words back into the
+        # scan and restart at the command position.
+        -S | --split-string)
+          local sval=""
+          ((i + 1 < n)) && sval="${w[i + 1]}"
+          local -a sw=()
+          read -r -a sw <<<"$sval"
+          w=("${sw[@]}" "${w[@]:i+2}")
+          n=${#w[@]}
+          i=0
+          continue 2
+          ;;
+        -S* | --split-string=*)
+          local sval="${w[i]#-S}"
+          sval="${sval#--split-string=}"
+          local -a sw=()
+          read -r -a sw <<<"$sval"
+          w=("${sw[@]}" "${w[@]:i+1}")
+          n=${#w[@]}
+          i=0
+          continue 2
+          ;;
+        -u | -C | --chdir) ((i += 2)) ;;
+        -*) ((i++)) ;;
+        *) ((i++)) ;;
+        esac
+      done
+      continue
+      ;;
+    nice | nohup)
+      ((i++))
+      while ((i < n)) && [[ "${w[i]}" == -* ]]; do
+        case "${w[i]}" in
+        -n | --adjustment) ((i += 2)) ;;
+        --adjustment=*) ((i++)) ;;
+        -*) ((i++)) ;;
+        *) break ;;
+        esac
+      done
+      if ((i < n)) && [[ "${w[i]}" =~ ^-?[0-9]+$ ]]; then
+        ((i++))
+      fi
+      continue
+      ;;
+    sudo)
+      ((i++))
+      while ((i < n)) && [[ "${w[i]}" == -* ]]; do
+        case "${w[i]}" in
+        -u | -g | -h | -p | -C | -D | -R | -T | --user | --group | --chdir) ((i += 2)) ;;
+        -*) ((i++)) ;;
+        *) ((i++)) ;;
+        esac
+      done
+      continue
+      ;;
+    timeout)
+      ((i++))
+      while ((i < n)) && [[ "${w[i]}" == -* ]]; do
+        case "${w[i]}" in
+        -s | --signal | -k | --kill-after) ((i += 2)) ;;
+        --preserve-status | --foreground | --verbose) ((i++)) ;;
+        -*) ((i++)) ;;
+        *) break ;;
+        esac
+      done
+      if ((i < n)) && [[ "${w[i]}" =~ ^[0-9]+([.][0-9]+)?(s|m|h|d)?$ ]]; then
+        ((i++))
+      fi
+      continue
+      ;;
+    # eval concatenates and re-executes its arguments, so for the unquoted
+    # form (`eval git commit ...`) scanning the following words is exact.
+    command | exec | builtin | eval | !)
+      ((i++))
+      continue
+      ;;
+    time)
+      ((i++))
+      if ((i < n)) && [[ "${w[i]}" == "-p" ]]; then
+        ((i++))
+      fi
+      continue
+      ;;
+    if | while | until | for | case | select | coproc | '{' | '}')
+      ((i++))
+      continue
+      ;;
+    *)
+      if is_git_bin "$tok"; then
+        RESOLVED_GI=$i
+        return 0
+      fi
+      return 1
+      ;;
+    esac
+  done
+  return 1
+}
+
+# Inspect one already-tokenized segment (its argv words passed as "$@"). Blocks
+# when the segment is a real `git commit`/`git push` carrying a bypass token.
+# shellcheck disable=SC1003  # '\' compares a literal backslash char, not a quote escape
+check_segment() {
+  local -a w=("$@")
+  local nseg=${#w[@]} gi j k x lc ch rest sub sub_idx gw
+
+  resolve_git_index "${w[@]}" || return 0
+  gi=$RESOLVED_GI
+  # env -S splicing may have rewritten the argv — match on the resolved words.
+  w=("${RESOLVED_WORDS[@]}")
+  nseg=${#w[@]}
+
+  # Resolve the subcommand: walk words after the git executable, skipping git
+  # global options. The listed options consume the FOLLOWING word as their
+  # value (two-word form); their =-forms and every other option are single
+  # words handled by the generic `-*` skip. core.hooksPath is checked only on
+  # git config arguments (-c/--config/--config-env), not commit messages or
+  # pathspecs.
+  sub=""
+  sub_idx=-1
+  j=$((gi + 1))
+  while ((j < nseg)); do
+    gw="${w[j]}"
+    case "$gw" in
+    -c | --config | --config-env)
+      if ((j + 1 < nseg)); then
+        lc="${w[j + 1],,}"
+        [[ "$lc" == *core.hookspath=* ]] && block "hooksPath" \
+          "BLOCKED: core.hooksPath assignment is not allowed with git commit/push." \
+          "Fix the hook failure instead of bypassing git hooks."
+      fi
+      ((j += 2))
+      ;;
+    --config=*|--config-env=*)
+      lc="${gw#*=}"
+      lc="${lc,,}"
+      [[ "$lc" == *core.hookspath=* ]] && block "hooksPath" \
+        "BLOCKED: core.hooksPath assignment is not allowed with git commit/push." \
+        "Fix the hook failure instead of bypassing git hooks."
+      ((j++))
+      ;;
+    -C | --git-dir | --work-tree | --namespace | --super-prefix | --attr-source | --exec-path)
+      ((j += 2))
+      ;;
+    -*)
+      ((j++))
+      ;;
+    *)
+      sub="$gw"
+      sub_idx=$j
+      break
+      ;;
+    esac
+  done
+  [[ "$sub" == "commit" || "$sub" == "push" ]] || return 0
+
+  # Form 2: hook-manager env-var prefix (commit OR push) — only leading env
+  # assignments before the git executable (not commit messages or pathspecs).
+  for ((k = 0; k < gi; k++)); do
+    lc="${w[k],,}"
+    [[ "$lc" =~ ^lefthook[_a-z0-9]*=(0|false)$ ]] && block "hook-manager-env" \
+      "BLOCKED: hook-manager env-var bypass is not allowed with git commit/push." \
+      "Fix the hook lane failure instead of bypassing."
+  done
+
+  # Form 1: --no-verify / -n (commit or push) — words after the subcommand,
+  # skipping values consumed by commit/push options (e.g. -m message text).
+  # In a short-option bundle, `n` counts only when it precedes the first
+  # argument-taking short (m/F/c/C/t/u/S/G) — so `-nm msg` blocks but `-mn`
+  # (m takes value "n") does not.
+  if [[ "$sub" == "commit" || "$sub" == "push" ]]; then
+    k=$((sub_idx + 1))
+    while ((k < nseg)); do
+      x="${w[k]}"
+      case "$x" in
+      -m | --message | -F | --file | -t | --template | -c | -C | --author | --date)
+        ((k += 2))
+        continue
+        ;;
+      --message=* | --file=* | --template=* | --author=* | --date=*)
+        ((k++))
+        continue
+        ;;
+      *) ;;
+      esac
+      [[ "$x" == "--no-verify" ]] && block "no-verify" \
+        "BLOCKED: --no-verify / -n flags are not allowed with git $sub." \
+        "Fix the issues that caused the hook failure instead of bypassing."
+      if [[ "$sub" == "commit" && "$x" =~ ^-[A-Za-z]+$ ]]; then
+        rest="${x#-}"
+        for ((ch = 0; ch < ${#rest}; ch++)); do
+          case "${rest:ch:1}" in
+          n) block "no-verify" \
+            "BLOCKED: --no-verify / -n flags are not allowed with git commit." \
+            "Fix the issues that caused the hook failure instead of bypassing." ;;
+          m | F | c | C | t | u | S | G)
+            if ((ch + 1 < ${#rest})); then
+              ((k++))
+            elif ((k + 1 < nseg)); then
+              ((k += 2))
+            else
+              ((k++))
+            fi
+            continue 2
+            ;;
+          *) ;;
+          esac
+        done
+      fi
+      ((k++))
+    done
+  fi
+
+  return 0
+}
+
+# Single linear pass: read the command into a char array once (O(n)), then walk
+# it splitting top-level segments on UNQUOTED control operators and tokenizing
+# each segment into argv words honoring '…', "…", $'…', and backslash escapes
+# (including backslash-newline continuation). Each completed segment is checked
+# as it closes, so no full segment list is retained.
+# shellcheck disable=SC1003  # '\' compares a literal backslash char, not a quote escape
+parse_and_check() {
+  local -a chars=()
+  local c nx
+  while IFS= read -rN1 c; do chars+=("$c"); done < <(printf '%s' "$COMMAND")
+  local n=${#chars[@]} i
+  local word="" have=0
+  local -a seg=()
+
+  for ((i = 0; i < n; i++)); do
+    c="${chars[i]}"
+    case "$c" in
+    "'")
+      ((i++))
+      while ((i < n)) && [[ "${chars[i]}" != "'" ]]; do
+        word+="${chars[i]}"
+        ((i++))
+      done
+      have=1
+      ;;
+    '"')
+      ((i++))
+      while ((i < n)) && [[ "${chars[i]}" != '"' ]]; do
+        if [[ "${chars[i]}" == '\' ]] && ((i + 1 < n)); then
+          nx="${chars[i + 1]}"
+          case "$nx" in
+          '"' | '\' | '$' | '`')
+            word+="$nx"
+            ((i += 2))
+            continue
+            ;;
+          $'\n')
+            ((i += 2))
+            continue
+            ;;
+          *) ;;
+          esac
+        fi
+        word+="${chars[i]}"
+        ((i++))
+      done
+      have=1
+      ;;
+    '$')
+      if ((i + 1 < n)) && [[ "${chars[i + 1]}" == "'" ]]; then
+        i=$((i + 2))
+        local body=""
+        while ((i < n)) && [[ "${chars[i]}" != "'" ]]; do
+          if [[ "${chars[i]}" == '\' ]] && ((i + 1 < n)); then
+            body+="${chars[i]}${chars[i + 1]}"
+            ((i += 2))
+            continue
+          fi
+          body+="${chars[i]}"
+          ((i++))
+        done
+        word+="$(ansi_c_decode "$body")"
+        have=1
+      else
+        word+="$c"
+        have=1
+      fi
+      ;;
+    '\')
+      if ((i + 1 < n)); then
+        nx="${chars[i + 1]}"
+        if [[ "$nx" == $'\n' ]]; then
+          ((i++))
+        else
+          word+="$nx"
+          ((i++))
+          have=1
+        fi
+      else
+        have=1
+      fi
+      ;;
+    ' ' | $'\t')
+      if ((have)); then
+        seg+=("$word")
+        word=""
+        have=0
+      fi
+      ;;
+    ';' | '&' | '|' | '(' | ')' | '`' | $'\n')
+      if ((have)); then
+        seg+=("$word")
+        word=""
+        have=0
+      fi
+      if ((${#seg[@]})); then
+        check_segment "${seg[@]}"
+        seg=()
+      fi
+      ;;
+    *)
+      word+="$c"
+      have=1
+      ;;
+    esac
+  done
+  if ((have)); then seg+=("$word"); fi
+  if ((${#seg[@]})); then check_segment "${seg[@]}"; fi
+}
+
+if ((${#COMMAND} > MAX_COMMAND_LEN)); then
+  block "too-long" \
+    "BLOCKED: command too long to parse safely (> $MAX_COMMAND_LEN chars)." \
+    "Shorten the command, or set HOOK_BLOCK_NO_VERIFY_ENABLED=false to bypass."
+fi
+
+parse_and_check
+
+emit_tel "ok" ""
+exit 0
diff --git a/plugins/guardrails/hooks/block-no-verify.test.sh b/plugins/guardrails/hooks/block-no-verify.test.sh
new file mode 100755
index 000000000..d2ebbc8d8
--- /dev/null
+++ b/plugins/guardrails/hooks/block-no-verify.test.sh
@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# Contract test for block-no-verify.sh (guardrails plugin).
+#
+# Black-box: invokes the hook as a subprocess, pipes PreToolUse Bash JSON on
+# stdin, asserts on exit code (2 = blocked, 0 = allowed). Self-contained — no
+# host-repo assertion library.
+
+set -uo pipefail
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$HOOK_DIR/block-no-verify.sh"
+TEST_TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+# shellcheck source=guardrails-test-helpers.sh
+source "$HOOK_DIR/guardrails-test-helpers.sh"
+
+# run <label> <command> <expected-exit> [extra-env NAME=VAL ...]
+run() {
+  local label="$1" command="$2" expected="$3"
+  shift 3
+  local rc
+  env "$@" bash "$HOOK" <<<"$(command_json "$command")" >/dev/null 2>&1
+  rc=$?
+  assert_exit "$label" "$expected" "$rc"
+}
+
+# --- Form 1: --no-verify / -n on git commit ---------------------------------
+run "git commit --no-verify (blocked)" "git commit --no-verify -m test" 2
+run "git commit -n (blocked)" "git commit -n -m test" 2
+run "cd foo && git commit --no-verify (compound, blocked)" "cd foo && git commit --no-verify -m test" 2
+run "git commit -m test (allowed)" "git commit -m test" 0
+run "git push --no-verify (blocked)" "git push --no-verify" 2
+run "quoted --no-verify prose (allowed)" 'echo "git commit --no-verify is banned"' 0
+run "echo git commit --no-verify (git as arg, allowed)" 'echo git commit --no-verify' 0
+
+# --- Form 1b: core.hooksPath assignment -------------------------------------
+run "git -c core.hooksPath=/dev/null commit (blocked)" "git -c core.hooksPath=/dev/null commit -m test" 2
+run "git -c core.hookspath=/dev/null push (blocked)" "git -c core.hookspath=/dev/null push" 2
+run "git commit -m core.hooksPath=/tmp (message literal, allowed)" \
+  "git commit -m 'core.hooksPath=/tmp'" 0
+run "cd foo && git -c core.hooksPath commit (compound, blocked)" "cd foo && git -c core.hooksPath=/dev/null commit -m test" 2
+run "quoted core.hooksPath prose (allowed)" 'echo "git -c core.hooksPath=/dev/null commit"' 0
+
+# --- Argv-faithful gate regressions (P3) ------------------------------------
+# The shell removes quotes/escapes before git parses argv, so quoting the git
+# executable, the subcommand, OR the flag must all still be caught.
+run "git commit \"--no-verify\" (quoted flag, blocked)" \
+  'git commit "--no-verify" -m test' 2
+run "git commit --no-ver'ify' (partial-quote flag, blocked)" \
+  "git commit --no-ver'ify' -m test" 2
+run "git commit \"-n\" (quoted short flag, blocked)" \
+  'git commit "-n" -m test' 2
+run "git commit --no-\\verify (escaped flag, blocked)" \
+  'git commit --no-\verify -m test' 2
+run "\"git\" commit --no-verify (quoted executable, blocked)" \
+  '"git" commit --no-verify -m test' 2
+run "git \"commit\" --no-verify (quoted subcommand, blocked)" \
+  'git "commit" --no-verify -m test' 2
+run "g'i't commit --no-verify (split-quoted executable, blocked)" \
+  "g'i't commit --no-verify -m test" 2
+run "git -c \"core.hooksPath=…\" commit (quoted config, blocked)" \
+  'git -c "core.hooksPath=/dev/null" commit -m test' 2
+run "\"git\" -c core.hooksPath=… commit (quoted exec + config, blocked)" \
+  '"git" -c core.hooksPath=/dev/null commit -m test' 2
+run "git -c 'core.hooksPath=…' push (single-quoted config, blocked)" \
+  "git -c 'core.hooksPath=/dev/null' push" 2
+
+# --- Argv-faithful negatives — must NOT block (exit 0) ----------------------
+run "echo \"git commit --no-verify\" (quoted arg, allowed)" \
+  'echo "git commit --no-verify"' 0
+run "echo 'use git commit --no-verify never' (quoted arg, allowed)" \
+  "echo 'use git commit --no-verify never'" 0
+run "echo \"a && git commit --no-verify\" (operator in quotes, allowed)" \
+  'echo "a && git commit --no-verify"' 0
+run "\"git commit\" --no-verify (command-not-found form, allowed)" \
+  '"git commit" --no-verify -m test' 0
+run "git commit -m \"explain --no-verify\" (flag in message value, allowed)" \
+  'git commit -m "explain --no-verify"' 0
+
+# --- [P2] git global options that consume an argument -----------------------
+run "git -C . commit --no-verify (arg-consuming -C, blocked)" \
+  'git -C . commit --no-verify -m test' 2
+run "git --git-dir=/x commit --no-verify (=-form global, blocked)" \
+  'git --git-dir=/x commit --no-verify -m test' 2
+run "git --work-tree /tmp commit --no-verify (two-word global, blocked)" \
+  'git --work-tree /tmp commit --no-verify -m test' 2
+run "git -C . -c core.hooksPath=/dev/null push (blocked)" \
+  'git -C . -c core.hooksPath=/dev/null push' 2
+
+# --- [P2] short-option bundle -n --------------------------------------------
+run "git commit -nm msg (n before arg-taking m, blocked)" \
+  'git commit -nm msg' 2
+run "git commit -vn (n after non-arg short, blocked)" \
+  'git commit -vn -m test' 2
+run "git commit -mn (m takes value 'n', allowed)" \
+  'git commit -mn' 0
+run "git commit -am fix (no n-flag, allowed)" \
+  'git commit -am fix' 0
+
+# --- [P2] wrappers (with options) transparently pass through ----------------
+run "env -i git commit --no-verify (env + option, blocked)" \
+  'env -i git commit --no-verify -m test' 2
+run "nice git commit --no-verify (blocked)" \
+  'nice git commit --no-verify -m test' 2
+run "timeout 5 git commit --no-verify (positional-arg wrapper, blocked)" \
+  'timeout 5 git commit --no-verify -m test' 2
+run "timeout -s KILL 5 git commit --no-verify (option + duration, blocked)" \
+  'timeout -s KILL 5 git commit --no-verify -m test' 2
+run "command git commit --no-verify (builtin prefix, blocked)" \
+  'command git commit --no-verify -m test' 2
+run "if git commit --no-verify (shell keyword prefix, blocked)" \
+  'if git commit --no-verify -m test; then echo ok; fi' 2
+run "sudo -u x git commit --no-verify (wrapper option, blocked)" \
+  'sudo -u x git commit --no-verify -m test' 2
+run "nice -n 10 git commit --no-verify (nice -n option, blocked)" \
+  'nice -n 10 git commit --no-verify -m test' 2
+run "time -p git commit --no-verify (time -p option, blocked)" \
+  'time -p git commit --no-verify -m test' 2
+run "git commit -m --no-verify (message value, allowed)" \
+  'git commit -m --no-verify' 0
+run "git commit -m 'LEFTHOOK=0' (message literal, allowed)" \
+  "git commit -m 'LEFTHOOK=0'" 0
+run "env -S 'git commit --no-verify' (split-string operand, blocked)" \
+  "env -S 'git commit --no-verify -m test'" 2
+run "env -S'git commit --no-verify' (attached split-string, blocked)" \
+  "env -S'git commit --no-verify -m test'" 2
+run "env --split-string='git commit --no-verify' (long form, blocked)" \
+  "env --split-string='git commit --no-verify -m test'" 2
+run "eval git commit --no-verify (eval prefix, blocked)" \
+  'eval git commit --no-verify -m test' 2
+run "env -S 'ls -la' (split-string non-git, allowed)" \
+  "env -S 'ls -la'" 0
+
+# --- [P3] case-insensitive executable + .exe strip (OS-gated) ----------------
+case "${OSTYPE:-}" in
+msys* | cygwin* | win32) exp_win=2 ;; # Windows/MSYS folds case + strips .exe
+*) exp_win=0 ;;                        # POSIX stays case-sensitive
+esac
+run "GIT commit --no-verify (uppercase exec, OS-gated)" \
+  'GIT commit --no-verify -m test' "$exp_win"
+run "git.exe commit --no-verify (.exe strip, OS-gated)" \
+  'git.exe commit --no-verify -m test' "$exp_win"
+
+# --- [P5 subset] ANSI-C $'…' + backslash-newline continuation ---------------
+run "git commit \$'--no-verify' (ANSI-C plain, blocked)" \
+  "git commit \$'--no-verify' -m test" 2
+run "git commit \$'\\x2d\\x2dno-verify' (ANSI-C hex, blocked)" \
+  "git commit \$'\\x2d\\x2dno-verify' -m test" 2
+lc_cmd=$(printf 'git commit --no-\\\nverify -m test')
+run "git commit --no-<backslash-newline>verify (continuation, blocked)" \
+  "$lc_cmd" 2
+
+# --- [P4] over-length command fails CLOSED (blocked) ------------------------
+long_cmd="echo $(printf 'a%.0s' {1..20000})"
+run "command over the parse cap (fail-closed, blocked)" \
+  "$long_cmd" 2
+
+# --- Form 2: hook-manager env-var bypass on git commit / push ---------------
+run "LEFTHOOK=0 git commit (blocked)" "LEFTHOOK=0 git commit -m test" 2
+run "LEFTHOOK=false git push (blocked)" "LEFTHOOK=false git push" 2
+run "LEFTHOOK=FALSE git commit (blocked, uppercase)" "LEFTHOOK=FALSE git commit -m test" 2
+run "LEFTHOOK=False git push (blocked, mixed case)" "LEFTHOOK=False git push origin main" 2
+run "LEFTHOOK_SUFFIX=false git push (blocked, suffix var)" "LEFTHOOK_VERIFY_GATE_ENABLED=false git push" 2
+run "cd foo && LEFTHOOK=0 git commit (compound, blocked)" "cd foo && LEFTHOOK=0 git commit -m test" 2
+
+# --- Form 2 negatives — env-var alone or with non-git command must NOT block -
+run "LEFTHOOK=0 echo foo (not git, allowed)" "LEFTHOOK=0 echo foo" 0
+run "LEFTHOOK=false ls (not git, allowed)" "LEFTHOOK=false ls" 0
+run "LEFTHOOK=1 git commit (truthy value, allowed)" "LEFTHOOK=1 git commit -m test" 0
+run "LEFTHOOK=true git push (truthy value, allowed)" "LEFTHOOK=true git push" 0
+
+# --- Unrelated commands — always no-op --------------------------------------
+run "git status (read-only, allowed)" "git status" 0
+run "empty command (allowed)" "" 0
+run "git push (no env-var, allowed)" "git push" 0
+
+# --- Kill switch — disabled path is a clean no-op even on a bypass -----------
+run "kill switch off → no-op despite --no-verify" "git commit --no-verify -m test" 0 \
+  HOOK_BLOCK_NO_VERIFY_ENABLED=false
+
+# --- Telemetry: block emits a `blocked` envelope ----------------------------
+TEL="$(mktemp -p "$TEST_TMPDIR")"
+SINK="$(make_sink "cat >\"$TEL\"")"
+env HOOK_TELEMETRY_SINK="$SINK" CLAUDE_PROJECT_DIR="$TEST_TMPDIR" \
+  bash "$HOOK" <<<"$(command_json 'git commit --no-verify -m test')" >/dev/null 2>&1 || true
+if wait_for_sink "$TEL"; then
+  assert_contains "telemetry: hook id" "$(jq -r '.hook' "$TEL")" "block-no-verify"
+  assert_contains "telemetry: status blocked" "$(jq -r '.status' "$TEL")" "blocked"
+  assert_contains "telemetry: subject Bash:git" "$(jq -r '.data.subject' "$TEL")" "Bash:git"
+  assert_contains "telemetry: form no-verify" "$(jq -r '.data.form' "$TEL")" "no-verify"
+else
+  bad "telemetry: no envelope written on block"
+fi
+
+report
diff --git a/plugins/guardrails/hooks/cli-flag-verify.sh b/plugins/guardrails/hooks/cli-flag-verify.sh
new file mode 100755
index 000000000..b4d6f0a9a
--- /dev/null
+++ b/plugins/guardrails/hooks/cli-flag-verify.sh
@@ -0,0 +1,312 @@
+#!/usr/bin/env bash
+# PostToolUse hook: verify CLI flags in newly-written shell/PowerShell/markdown
+# files against `<bin> [<subcmd>...] --help` output via the bundled
+# lib/verification/verify-cli-flag.sh.
+# Triggered on Write|Edit of *.sh, *.bash, *.ps1, *.psm1, *.md files.
+#
+# Catches subagent / training-recall hallucinations — a CLI flag written AS a
+# command that does not exist in the binary's actual --help output.
+#
+# Subcommand-aware + code-span-scoped: each `--flag` is bound to the bin heading
+# its OWN command span and verified against `<bin> [<subcmd>...] --help` (the
+# verifier accepts a subcommand chain). For markdown, only code is scanned —
+# inline-code spans + fenced code blocks — because a flag is a real
+# copy/paste/exec hazard only when written AS a command. This eliminates two
+# false-positive classes a naive line-scan produces: subcommand-flag blindness
+# (checking `<bin> --help` only) and cross-pairing a bin with every `--flag` on
+# a line.
+#
+# NON-BLOCKING (advisory): exits 0 with hookSpecificOutput additionalContext
+# on unknown flags (exit 1 stderr is not shown to the agent per hook contract).
+#
+# Per-binary opt-out via HOOK_CLI_FLAG_VERIFY_SKIP_BINS=bin1,bin2 (e.g. for
+# extension-heavy CLIs like gh where --help is non-exhaustive). Disable entirely
+# with HOOK_CLI_FLAG_VERIFY_ENABLED=false.
+
+set -uo pipefail
+
+# High-res start stamp for telemetry (Bash 5.0+; empty on older bash → skip).
+start=${EPOCHREALTIME:-}
+
+# shellcheck source=hook-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/hook-utils.sh"
+
+hook::check_enabled "CLI_FLAG_VERIFY"
+
+# jq is required to parse the tool payload. Fail OPEN when it is absent, but make
+# the degraded state visible rather than silently disabling the hook.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "guardrails/cli-flag-verify: jq not found on PATH — hook disabled (install jq to enable)." >&2
+  exit 0
+fi
+
+hook::ctx_reset
+
+# Bundled verifier — resolved under the plugin root (CC sets CLAUDE_PLUGIN_ROOT;
+# the BASH_SOURCE fallback keeps the contract tests working when it is unset).
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+VERIFIER="$PLUGIN_ROOT/lib/verification/verify-cli-flag.sh"
+
+FILE=$(hook::read_file_path) || exit 0
+IS_MD=false
+case "$FILE" in
+  *.md) IS_MD=true ;;
+  *.sh | *.bash | *.ps1 | *.psm1) ;;
+  *) exit 0 ;;
+esac
+
+[[ -x "$VERIFIER" ]] || exit 0 # Verifier not present — fail open, don't block
+
+# Repo root for telemetry data.file + relative sink resolution (file-anchored).
+REPO_ROOT="$(hook::repo_root "$(dirname "$FILE")")"
+
+# Known binaries to check. Add via env: HOOK_CLI_FLAG_VERIFY_BINS=bin1,bin2,...
+# `git` and `npx` are intentionally EXCLUDED — both are unreliable `--help`
+# flag lists whose residuals are all real-flag false positives:
+#   - `git <subcmd> --help` routes to the man page (or a short synopsis under
+#     timeout), not a parseable per-subcommand flag list, AND the flaky output
+#     poisons the 24h --help cache → persistent FPs.
+#   - `npx <pkg> --help` runs an ARBITRARY package's help (reliability is the
+#     package's, not npx's) and an uninstalled `<pkg>` can trigger a network
+#     fetch. Working cases produce no residual (invisible benefit); failing
+#     cases produce visible FPs — same shape that excludes git.
+# Re-add either via the env var if it ever ships a stdout-parseable flag list.
+DEFAULT_BINS="claude gh dotnet docker npm kubectl terraform az aws"
+BINS_RAW="${HOOK_CLI_FLAG_VERIFY_BINS:-$DEFAULT_BINS}"
+# Normalize: comma OR space separated → space separated.
+BINS="${BINS_RAW//,/ }"
+
+# Per-binary opt-outs. Comma-separated. Common case: gh extensions, docker plugin
+# subcommands where --help is not exhaustive.
+SKIP_RAW="${HOOK_CLI_FLAG_VERIFY_SKIP_BINS:-}"
+SKIP="${SKIP_RAW//,/ }"
+
+is_skipped() {
+  local bin="$1" skip
+  for skip in $SKIP; do
+    [[ "$bin" == "$skip" ]] && return 0
+  done
+  return 1
+}
+
+# Emit candidate command fragments (one per line) from the file.
+#   - Markdown: scan CODE only — inline-code spans (one combined grep, then
+#     strip the delimiting backticks) + fenced code-block bodies. Fenced content
+#     carries no inline backticks, so the inline grep naturally excludes it.
+#   - Shell/PowerShell: every line is code.
+emit_fragments() {
+  if [[ "$IS_MD" == "true" ]]; then
+    # Inline-code spans (strip the delimiting backticks).
+    # shellcheck disable=SC2016  # backticks are literal ERE/sed data, not expansions
+    grep -oE '`[^`]+`' "$FILE" 2>/dev/null | sed -E 's/^`+//; s/`+$//'
+    # Fenced code-block bodies, skipping in-fence comment lines (a backtick-
+    # wrapped example inside a `#` comment would otherwise split into a segment).
+    awk '
+      /^[[:space:]]*```/ { f = !f; next }
+      /^[[:space:]]*~~~/ { f = !f; next }
+      f && $0 !~ /^[[:space:]]*#/ { print }
+    ' "$FILE" 2>/dev/null
+  else
+    # Shell/PowerShell: every non-comment line is code. Drop full-line comments
+    # BEFORE separator-splitting — otherwise a backtick-wrapped CLI example in a
+    # comment is split on its backticks into a spurious bin-led command segment
+    # (the comment's leading `#` lands in a different segment). `|| true`: grep
+    # exits 1 when every line is a comment.
+    grep -vE '^[[:space:]]*#' "$FILE" 2>/dev/null || true
+  fi
+}
+
+# Split fragments into command segments on shell command separators and
+# command-substitution / subshell boundaries, one segment per line. `$(` is
+# rewritten first so its `(` isn't double-counted by the class below.
+split_segments() {
+  sed -E 's/\$\(/\n/g; s/(\|\||&&|[;|&`()])/\n/g'
+}
+
+# Populate CANDIDATES with "bin|subcmd-chain|flag" keys. The chain is the
+# non-flag tokens between the bin and the first long flag (short options are
+# skipped, not chain-breaking); every long flag in the segment binds to it.
+declare -A CANDIDATES=()
+
+extract_candidates() {
+  local seg
+  while IFS= read -r seg; do
+    local -a toks=()
+    read -ra toks <<<"$seg"
+    ((${#toks[@]})) || continue
+
+    # Skip leading command wrappers + env-assignment prefixes to reach the bin.
+    local idx=0 lead
+    while ((idx < ${#toks[@]})); do
+      lead="${toks[idx]#[\`\'\"\(\!]}"
+      case "$lead" in
+        sudo | command | env | time | exec | xargs | then | do | else | "!")
+          ((idx++))
+          continue
+          ;;
+        *)
+          if [[ "$lead" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; then
+            ((idx++))
+            continue
+          fi
+          break
+          ;;
+      esac
+    done
+    ((idx < ${#toks[@]})) || continue
+
+    # Candidate bin: strip surrounding quotes/parens/backticks/bang.
+    local bin="${toks[idx]}"
+    bin="${bin#[\`\'\"\(\!]}"
+    bin="${bin%[\`\'\"\):;,]}"
+    [[ " $BINS " == *" $bin "* ]] || continue
+    is_skipped "$bin" && continue
+
+    # Walk remaining tokens: collect the subcommand chain (real-subcommand-shaped
+    # tokens before the first long flag) + every long flag bound to that chain.
+    #   - `--` ends option parsing — everything after is program args, not flags.
+    #   - A short option before the subcommand is skipped (it does not break the
+    #     chain); after the subcommand it ends the chain.
+    #   - A non-subcommand-shaped token (path, var, csproj, value) is skipped but
+    #     does NOT end the chain — a positional can sit mid-chain (e.g.
+    #     `dotnet list <SLN> package`). Only shaped lowercase words join the chain,
+    #     keeping junk out of the verified `<bin> <chain> --help` invocation.
+    local -a chain=() seg_flags=()
+    local chain_done=0 k tk fl ct
+    for ((k = idx + 1; k < ${#toks[@]}; k++)); do
+      tk="${toks[k]}"
+      case "$tk" in
+        --)
+          break
+          ;;
+        --*)
+          chain_done=1
+          fl="${tk%%=*}" # drop =VALUE
+          if [[ "$fl" =~ ^(--[a-zA-Z][a-zA-Z0-9-]*) ]]; then
+            fl="${BASH_REMATCH[1]}"
+            case "$fl" in
+              --help | --version) ;;
+              *) seg_flags+=("$fl") ;;
+            esac
+          fi
+          ;;
+        -?*)
+          # short option: before the subcommand, skip it (chain keeps looking);
+          # after the subcommand, options have begun → chain ends.
+          ((chain_done == 0 && ${#chain[@]} > 0)) && chain_done=1
+          ;;
+        *)
+          ct="${tk%[\`\'\"\):;,]}"
+          ct="${ct#[\`\'\"\(]}"
+          # A second known bin starts a NESTED command whose flags are not this
+          # bin's — `docker run <img> dotnet restore --force-evaluate`,
+          # `xargs gh issue … --json`. Everything from here belongs to it; stop.
+          [[ " $BINS " == *" $ct "* ]] && break
+          # Only shaped lowercase words join the chain; a non-shaped positional
+          # (path, csproj, var, SLN file) is skipped without ending the chain so
+          # `dotnet list <SLN> package --flag` still resolves the full subcommand.
+          if ((chain_done == 0)) && [[ "$ct" =~ ^[a-z][a-z0-9-]*$ ]] && ((${#chain[@]} < 4)); then
+            chain+=("$ct")
+          fi
+          ;;
+      esac
+    done
+
+    ((${#seg_flags[@]})) || continue
+    local chainstr="${chain[*]}" f
+    for f in "${seg_flags[@]}"; do
+      CANDIDATES["$bin|$chainstr|$f"]=1
+    done
+  done < <(emit_fragments | split_segments)
+}
+
+extract_candidates
+
+# Verify each unique (bin, chain, flag). Collect failures (keys, formatted later).
+FAILURES=()
+for key in "${!CANDIDATES[@]}"; do
+  bin="${key%%|*}"
+  rest="${key#*|}"
+  chainstr="${rest%|*}"
+  flag="${rest##*|}"
+  # Skip if binary not on PATH (verifier exit 2). Avoids spurious failures on
+  # systems missing tools the file references for documentation purposes.
+  command -v "$bin" >/dev/null 2>&1 || continue
+  read -ra chainarr <<<"$chainstr"
+  "$VERIFIER" --quiet "$bin" "${chainarr[@]}" "$flag" 2>/dev/null
+  rc=$?
+  # Exit 1 = flag absent (likely hallucinated); 2 = unverifiable, treat as
+  # neutral (don't flag — could be tool not on this machine, transient
+  # --help failure, or a subcommand whose --help is not parseable). Only
+  # collect exit-1 cases as failures.
+  if [[ "$rc" -eq 1 ]]; then
+    FAILURES+=("$key")
+  fi
+done
+
+# Build the telemetry findings array + repo-relative file path, both gated on a
+# wired sink so the unwired default path spawns no telemetry-only subprocess.
+emit_tel() {
+  [[ -n "$start" ]] || return 0
+  hook::telemetry_enabled || return 0
+  local file_rel="$FILE" findings_json="[]"
+  if command -v cygpath >/dev/null 2>&1; then
+    local _file_lm _root_lm
+    _file_lm=$(cygpath -lm "$FILE" 2>/dev/null)
+    _root_lm=$(cygpath -lm "$REPO_ROOT" 2>/dev/null)
+    [[ -n "$_file_lm" && -n "$_root_lm" ]] && file_rel="${_file_lm#"$_root_lm"/}"
+  else
+    file_rel="${FILE#"$REPO_ROOT"/}"
+  fi
+  # Redaction: if the path could not be made repo-relative, emit the basename
+  # only — never an absolute path (it would embed the developer's username).
+  case "$file_rel" in
+    /* | [A-Za-z]:*) file_rel="${file_rel##*/}"; file_rel="${file_rel##*\\}" ;;
+    *) ;;
+  esac
+  if ((${#FAILURES[@]} > 0)); then
+    local f raw="" bin rest chainstr flag disp
+    for f in "${FAILURES[@]}"; do
+      bin="${f%%|*}"
+      rest="${f#*|}"
+      chainstr="${rest%|*}"
+      flag="${rest##*|}"
+      [[ -n "$chainstr" ]] && disp="$bin $chainstr $flag" || disp="$bin $flag"
+      raw+="$disp"$'\n'
+    done
+    findings_json=$(printf '%s' "$raw" | jq -R . | jq -s . 2>/dev/null) || findings_json="[]"
+  fi
+  local data
+  data=$(jq -n --arg file "$file_rel" --argjson findings "$findings_json" \
+    '{tool:"",file:$file,findings:$findings}' 2>/dev/null) \
+    || data='{"tool":"","file":"","findings":[]}'
+  hook::emit_telemetry "cli-flag-verify" "PostToolUse" "ok" "$start" "$data" "$REPO_ROOT"
+}
+
+if ((${#FAILURES[@]} > 0)); then
+  hook::ctx_append "cli-flag-verify: ${#FAILURES[@]} unknown flag(s) in $FILE"
+  hook::ctx_append "Possible hallucination — verify against the binary's actual --help output:"
+  for f in "${FAILURES[@]}"; do
+    bin="${f%%|*}"
+    rest="${f#*|}"
+    chainstr="${rest%|*}"
+    flag="${rest##*|}"
+    if [[ -n "$chainstr" ]]; then
+      disp="$bin $chainstr $flag"
+      helpref="$bin $chainstr --help"
+    else
+      disp="$bin $flag"
+      helpref="$bin --help"
+    fi
+    hook::ctx_append "  UNKNOWN_FLAG: $disp (not found in '$helpref')"
+    hook::ctx_append "    fix:   run '$helpref' and confirm the flag exists"
+    hook::ctx_append "    skip:  HOOK_CLI_FLAG_VERIFY_SKIP_BINS=$bin (env override)"
+  done
+  hook::ctx_append ""
+  hook::ctx_append "Subagent / training-recall flag claims are unverified — confirm"
+  hook::ctx_append "against the binary's --help before relying on the flag."
+  hook::ctx_flush PostToolUse
+fi
+
+emit_tel
+exit 0
diff --git a/plugins/guardrails/hooks/cli-flag-verify.test.sh b/plugins/guardrails/hooks/cli-flag-verify.test.sh
new file mode 100755
index 000000000..767cc112d
--- /dev/null
+++ b/plugins/guardrails/hooks/cli-flag-verify.test.sh
@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Contract test for cli-flag-verify.sh (guardrails plugin).
+#
+# A PATH-stubbed `faketool` with controlled `--help` output exercises the
+# subcommand-aware, code-span-scoped extraction deterministically — no
+# dependence on any real CLI being installed. Self-contained.
+#
+# shellcheck disable=SC2016  # backticks / $ inside fixture strings are literal data
+
+set -uo pipefail
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$HOOK_DIR/cli-flag-verify.sh"
+TEST_TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+# shellcheck source=guardrails-test-helpers.sh
+source "$HOOK_DIR/guardrails-test-helpers.sh"
+
+# Extract the hook's additionalContext JSON and assert a substring is present.
+ctx_contains() {
+  local ctx
+  ctx=$(printf '%s' "$2" | jq -r '.hookSpecificOutput.additionalContext // empty' 2>/dev/null)
+  assert_contains "$1" "$ctx" "$3"
+}
+
+# Fake CLI double: `--help` (always the verifier's last arg) prints top-level
+# flags; when `sub` appears in the chain it also exposes the subcommand flag.
+FAKE_BIN_DIR="$TEST_TMPDIR/fakebin"
+mkdir -p "$FAKE_BIN_DIR"
+cat >"$FAKE_BIN_DIR/faketool" <<'FAKE'
+#!/usr/bin/env bash
+last=""
+for a in "$@"; do last="$a"; done
+if [[ "$last" == "--help" ]]; then
+  echo "Usage: faketool [subcmd] [options]"
+  echo "  --toplevel    a real top-level flag"
+  for a in "$@"; do
+    [[ "$a" == "sub" ]] && echo "  --real        a real subcommand flag"
+  done
+  exit 0
+fi
+exit 0
+FAKE
+chmod +x "$FAKE_BIN_DIR/faketool"
+
+# run_fake: invoke the hook with faketool as the only scanned bin and an
+# isolated per-case verifier cache so a stale 24h --help cache never leaks.
+run_fake() {
+  local content="$1" ext="${2:-sh}"
+  local case_dir="$TEST_TMPDIR/fake-$((PASS + FAIL + 1))"
+  mkdir -p "$case_dir/cache"
+  local target="$case_dir/target.$ext"
+  printf '%s\n' "$content" >"$target"
+  PATH="$FAKE_BIN_DIR:$PATH" \
+    HOOK_CLI_FLAG_VERIFY_BINS=faketool \
+    LOCALAPPDATA="$case_dir/cache" \
+    XDG_CACHE_HOME="$case_dir/cache" \
+    bash "$HOOK" <<<"$(MSYS_NO_PATHCONV=1 jq -n --arg fp "$target" '{tool_input:{file_path:$fp}}')" 2>&1
+}
+
+OUT=$(run_fake 'faketool sub --real'); RC=$?
+assert_exit "subcmd real flag → exit 0" 0 "$RC"
+assert_silent "subcmd real flag → no output" "$OUT"
+
+OUT=$(run_fake 'faketool sub --fake'); RC=$?
+assert_exit "subcmd fake flag → exit 0" 0 "$RC"
+ctx_contains "subcmd fake flag → UNKNOWN_FLAG w/ chain" "$OUT" "UNKNOWN_FLAG: faketool sub --fake"
+
+OUT=$(run_fake 'faketool --toplevel'); RC=$?
+assert_exit "top-level real flag → exit 0" 0 "$RC"
+
+OUT=$(run_fake 'faketool --bogus'); RC=$?
+assert_exit "top-level fake flag → exit 0" 0 "$RC"
+ctx_contains "top-level fake flag → UNKNOWN_FLAG no chain" "$OUT" "UNKNOWN_FLAG: faketool --bogus"
+
+OUT=$(run_fake 'echo hi && faketool sub --real | cat'); RC=$?
+assert_exit "subcmd flag after && / before | → exit 0" 0 "$RC"
+
+OUT=$(run_fake 'faketool -x sub --real'); RC=$?
+assert_exit "short opt before subcmd → chain preserved → exit 0" 0 "$RC"
+
+OUT=$(run_fake 'FOO=bar faketool sub --real'); RC=$?
+assert_exit "env-assignment prefix stripped → exit 0" 0 "$RC"
+
+OUT=$(run_fake 'faketool sub --real img faketool other --bogusflag'); RC=$?
+assert_exit "nested second-bin flag not paired → exit 0" 0 "$RC"
+assert_absent "nested second-bin flag → no inner FP" "$OUT" "bogusflag"
+
+OUT=$(run_fake 'Run `faketool sub --real` then note the `--orphanflag` elsewhere.' md); RC=$?
+assert_exit "cross-span flag not paired → exit 0" 0 "$RC"
+assert_absent "cross-span flag → no orphan FP" "$OUT" "orphanflag"
+
+OUT=$(run_fake 'The faketool --bogus flag is discussed only in prose here.' md); RC=$?
+assert_exit "prose flag (no code span) → exit 0" 0 "$RC"
+
+OUT=$(run_fake "$(printf '%s\n%s\n%s\n' '```bash' 'faketool sub --fake' '```')" md); RC=$?
+assert_exit "fenced block fake flag → exit 0" 0 "$RC"
+ctx_contains "fenced block fake flag → reported" "$OUT" "UNKNOWN_FLAG: faketool sub --fake"
+
+OUT=$(run_fake "$(printf '%s\n%s\n%s\n' '```bash' '# faketool sub --fake' '```')" md); RC=$?
+assert_exit "fenced comment line → exit 0" 0 "$RC"
+
+OUT=$(run_fake '| faketool sub --fake | hallucinated |' md); RC=$?
+assert_exit "table cell no-backtick → exit 0" 0 "$RC"
+
+OUT=$(run_fake '| `faketool sub --fake` | hallucinated |' md); RC=$?
+assert_exit "table cell w/ backticks fake flag → exit 0" 0 "$RC"
+ctx_contains "table cell w/ backticks → reported" "$OUT" "UNKNOWN_FLAG: faketool sub --fake"
+
+OUT=$(run_fake 'the `faketool` directory holds --bogus notes' md); RC=$?
+assert_exit "bin as non-command word → exit 0" 0 "$RC"
+
+OUT=$(run_fake "$(printf '%s\n%s\n' '# example: faketool sub --fake' 'faketool sub --real')"); RC=$?
+assert_exit "shell comment line skipped → exit 0" 0 "$RC"
+
+OUT=$(run_fake 'faketool sub --help'); RC=$?
+assert_exit "--help universally skipped → exit 0" 0 "$RC"
+OUT=$(run_fake 'faketool --version'); RC=$?
+assert_exit "--version universally skipped → exit 0" 0 "$RC"
+
+OUT=$(run_fake 'faketool sub --fake' cs); RC=$?
+assert_exit "non-target ext (.cs) → exit 0" 0 "$RC"
+
+# Kill switch — disabled path is a clean no-op despite a hallucinated flag.
+dis_dir="$TEST_TMPDIR/fake-disabled"
+mkdir -p "$dis_dir/cache"
+printf 'faketool sub --fake\n' >"$dis_dir/target.sh"
+dis_input=$(MSYS_NO_PATHCONV=1 jq -n --arg fp "$dis_dir/target.sh" '{tool_input:{file_path:$fp}}')
+OUT=$(PATH="$FAKE_BIN_DIR:$PATH" HOOK_CLI_FLAG_VERIFY_BINS=faketool \
+  LOCALAPPDATA="$dis_dir/cache" XDG_CACHE_HOME="$dis_dir/cache" \
+  HOOK_CLI_FLAG_VERIFY_ENABLED=false bash "$HOOK" <<<"$dis_input" 2>&1); RC=$?
+assert_exit "disabled via env → exit 0" 0 "$RC"
+assert_silent "disabled via env → no output" "$OUT"
+
+OUT=$(PATH="$FAKE_BIN_DIR:$PATH" HOOK_CLI_FLAG_VERIFY_BINS=faketool \
+  LOCALAPPDATA="$dis_dir/cache" XDG_CACHE_HOME="$dis_dir/cache" \
+  HOOK_CLI_FLAG_VERIFY_SKIP_BINS=faketool bash "$HOOK" <<<"$dis_input" 2>&1); RC=$?
+assert_exit "per-binary skip → exit 0" 0 "$RC"
+
+# ============================ TELEMETRY ====================================
+TEL="$(mktemp -p "$TEST_TMPDIR")"
+SINK="$(make_sink "cat >\"$TEL\"")"
+tel_dir="$TEST_TMPDIR/fake-tel"
+mkdir -p "$tel_dir/cache"
+printf 'faketool sub --fake\n' >"$tel_dir/target.sh"
+tel_input=$(MSYS_NO_PATHCONV=1 jq -n --arg fp "$tel_dir/target.sh" '{tool_input:{file_path:$fp}}')
+PATH="$FAKE_BIN_DIR:$PATH" HOOK_CLI_FLAG_VERIFY_BINS=faketool \
+  LOCALAPPDATA="$tel_dir/cache" XDG_CACHE_HOME="$tel_dir/cache" \
+  HOOK_TELEMETRY_SINK="$SINK" bash "$HOOK" <<<"$tel_input" >/dev/null 2>&1 || true
+if wait_for_sink "$TEL"; then
+  assert_contains "telemetry: hook id" "$(jq -r '.hook' "$TEL")" "cli-flag-verify"
+  assert_contains "telemetry: status ok" "$(jq -r '.status' "$TEL")" "ok"
+  assert_contains "telemetry: findings name the flag" "$(jq -r '.data.findings[]' "$TEL")" "faketool sub --fake"
+else
+  bad "telemetry: no envelope written"
+fi
+
+# ================= VERIFIER OPTION PARSING (positional guard) ===============
+# Verifier options are recognized only before <bin>; a TARGET flag spelled
+# --quiet/--verbose must be verified as a positional, not consumed (the old
+# whole-argv scan returned rc 3 and the hook silently skipped those flags).
+VERIFIER="$HOOK_DIR/../lib/verification/verify-cli-flag.sh"
+opt_dir="$TEST_TMPDIR/verifier-opts"
+mkdir -p "$opt_dir/cache"
+run_verifier() {
+  PATH="$FAKE_BIN_DIR:$PATH" LOCALAPPDATA="$opt_dir/cache" \
+    XDG_CACHE_HOME="$opt_dir/cache" bash "$VERIFIER" "$@" >/dev/null 2>&1
+}
+run_verifier --quiet faketool --toplevel
+assert_exit "verifier: leading --quiet still parsed as option" 0 $?
+run_verifier --quiet faketool --verbose
+assert_exit "verifier: target --verbose verified, not consumed (absent -> 1)" 1 $?
+run_verifier --quiet faketool --quiet
+assert_exit "verifier: target --quiet verified, not consumed (absent -> 1)" 1 $?
+
+report
diff --git a/plugins/guardrails/hooks/guardrails-test-helpers.sh b/plugins/guardrails/hooks/guardrails-test-helpers.sh
new file mode 100644
index 000000000..75eb1c970
--- /dev/null
+++ b/plugins/guardrails/hooks/guardrails-test-helpers.sh
@@ -0,0 +1,92 @@
+# shellcheck shell=bash
+# Self-contained test helpers for the guardrails plugin hook contract tests.
+# Sourced (never *.test.sh-named, so a test runner's glob ignores it) by each
+# hook's *.test.sh after that file sets up its own TEST_TMPDIR + trap. No
+# dependency on any host-repo assertion library — the plugin is standalone.
+
+: "${PASS:=0}"
+: "${FAIL:=0}"
+
+ok() {
+  echo "ok: $*"
+  PASS=$((PASS + 1))
+}
+bad() {
+  echo "FAIL: $*" >&2
+  FAIL=$((FAIL + 1))
+}
+
+# assert_exit <label> <expected> <actual>
+assert_exit() {
+  if [[ "$3" == "$2" ]]; then ok "$1 (exit $3)"; else bad "$1: expected exit $2, got $3"; fi
+}
+# assert_contains <label> <haystack> <needle>
+assert_contains() {
+  if [[ "$2" == *"$3"* ]]; then ok "$1"; else bad "$1: '$3' not in output: $2"; fi
+}
+# assert_absent <label> <haystack> <needle>
+assert_absent() {
+  if [[ "$2" != *"$3"* ]]; then ok "$1"; else bad "$1: unexpected '$3' in output"; fi
+}
+# assert_silent <label> <output>
+assert_silent() {
+  if [[ -z "$2" ]]; then ok "$1"; else bad "$1: expected empty output, got: $2"; fi
+}
+# assert_file_absent <label> <path>
+assert_file_absent() {
+  if [[ ! -e "$2" ]]; then ok "$1"; else bad "$1: file exists: $2"; fi
+}
+
+# PreToolUse JSON builders. jq -n --arg escapes quotes/backslashes/newlines.
+# MSYS_NO_PATHCONV=1 stops Git Bash translating POSIX file paths for jq's exe.
+write_json() {
+  MSYS_NO_PATHCONV=1 jq -n --arg fp "$1" --arg c "$2" \
+    '{tool_name:"Write",tool_input:{file_path:$fp,content:$c}}'
+}
+edit_json() {
+  MSYS_NO_PATHCONV=1 jq -n --arg fp "$1" --arg s "$2" \
+    '{tool_name:"Edit",tool_input:{file_path:$fp,new_string:$s}}'
+}
+notebook_json() {
+  MSYS_NO_PATHCONV=1 jq -n --arg fp "$1" --arg s "$2" \
+    '{tool_name:"NotebookEdit",tool_input:{file_path:$fp,new_source:$s}}'
+}
+other_tool_json() {
+  MSYS_NO_PATHCONV=1 jq -n --arg t "$1" --arg fp "$2" \
+    '{tool_name:$t,tool_input:{file_path:$fp}}'
+}
+command_json() {
+  jq -n --arg cmd "$1" '{tool_name:"Bash",tool_input:{command:$cmd}}'
+}
+
+# make_sink <body> -> path to an executable single-command stub sink running
+# <body> (which reads the telemetry envelope on stdin). HOOK_TELEMETRY_SINK
+# must be a single executable path, so tests point it at a stub.
+make_sink() {
+  local s
+  # shellcheck disable=SC2154  # TEST_TMPDIR is a caller contract (set by each test file)
+  s="$(mktemp -p "$TEST_TMPDIR" sink.XXXXXX)"
+  {
+    printf '#!/usr/bin/env bash\n'
+    printf '%s\n' "$1"
+  } >"$s"
+  chmod +x "$s"
+  printf '%s' "$s"
+}
+
+# wait_for_sink <file> [tries] -> block until <file> is non-empty (the
+# fire-and-forget sink flushed) or the bound elapses, polling in 20ms steps.
+wait_for_sink() {
+  local f="$1" tries="${2:-150}"
+  while ((tries-- > 0)); do
+    [[ -s "$f" ]] && return 0
+    sleep 0.02
+  done
+  return 1
+}
+
+report() {
+  echo
+  echo "PASS=$PASS FAIL=$FAIL"
+  [[ $FAIL -eq 0 ]]
+}
diff --git a/plugins/guardrails/hooks/hardcoded-path-check.sh b/plugins/guardrails/hooks/hardcoded-path-check.sh
new file mode 100755
index 000000000..bc9e22780
--- /dev/null
+++ b/plugins/guardrails/hooks/hardcoded-path-check.sh
@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# PreToolUse hook: detect hardcoded machine-specific paths before file writes.
+# Triggered on Write|Edit|NotebookEdit of any file.
+#
+# BLOCKING: exits 2 when hardcoded user home directories or drive-letter paths
+# are detected in new content. Stderr feedback tells Claude what was found and
+# how to fix it.
+#
+# Cross-platform: detects Windows drive-letter user homes, macOS user homes,
+# and Linux user homes. Excludes dynamic references, documentation
+# placeholders, and legitimate system paths.
+#
+# Detection patterns live in the bundled lib/path-detection/hardcoded-path-patterns.sh.
+# This script keeps the tool-specific I/O glue: kill switch, JSON stdin parsing,
+# exemption set, exit-code mapping.
+#
+# Consumer seams: gitignored files are skipped (git check-ignore against
+# $CLAUDE_PROJECT_DIR) — designate machine-local files there. Disable entirely
+# with HOOK_HARDCODED_PATH_CHECK_ENABLED=false.
+
+set -uo pipefail
+
+# shellcheck source=hook-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/hook-utils.sh"
+
+# Bundled pattern lib — resolved under the plugin root (CC sets
+# CLAUDE_PLUGIN_ROOT; the BASH_SOURCE fallback keeps the contract tests working
+# when it is unset).
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+# shellcheck source=../lib/path-detection/hardcoded-path-patterns.sh
+source "$PLUGIN_ROOT/lib/path-detection/hardcoded-path-patterns.sh"
+
+hook::check_enabled "HARDCODED_PATH_CHECK"
+
+# High-res start stamp for telemetry (Bash 5.0+; empty on older bash → skip).
+start=${EPOCHREALTIME:-}
+
+# jq is required to parse the tool payload. Fail OPEN when it is absent, but make
+# the degraded state visible rather than silently disabling the guard.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "guardrails/hardcoded-path-check: jq not found on PATH — guard disabled (install jq to enable)." >&2
+  exit 0
+fi
+
+# Read inherited fd0 directly (bare cat) — NEVER `</dev/stdin` (Windows Git Bash
+# Win32-pipe ENOENT → silent no-op). Buffer once; parse each field from it.
+INPUT=$(cat)
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null | tr -d '\r')
+
+case "$TOOL" in
+  Write | Edit | NotebookEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null | tr -d '\r')
+[[ -n "$FILE" ]] || exit 0
+
+# Normalize path separators for cross-platform case matching.
+NORM_FILE="${FILE//\\//}"
+
+# --- Scope guard: police only files inside THIS project ---
+# A PreToolUse Write|Edit hook fires on every file write regardless of which
+# repo the target lives in. A file outside the project root is not ours to scan
+# — that repo owns its own path policy. Fail OPEN: when CLAUDE_PROJECT_DIR is
+# unset, fall through and scan rather than skip.
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  _scope_file="$(hook::normalize_path "$FILE")"
+  _scope_project="$(hook::normalize_path "${CLAUDE_PROJECT_DIR}")"
+  _scope_project="${_scope_project%/}"
+  case "$_scope_file" in
+    "$_scope_project"/*) ;; # inside the project — proceed
+    *) exit 0 ;;           # outside the project — not this hook's concern
+  esac
+fi
+
+# Skip files that legitimately contain path patterns (regex strings). These
+# cannot rely on the gitignore check below because they are tracked.
+case "$NORM_FILE" in
+  # Hook / hook-manager scripts contain path-detection patterns as regex strings.
+  *.claude/hooks/* | *.lefthook/*) exit 0 ;;
+  # Claude Code session/workflow state (under ~/.claude/projects/) lives OUTSIDE
+  # any repo working tree and is never committed; absolute paths there are expected
+  # machine-local glue. The gitignore check below cannot catch it — the path is
+  # outside $CLAUDE_PROJECT_DIR, so `git check-ignore` errors rather than matching.
+  *.claude/projects/*) exit 0 ;;
+  *) ;;
+esac
+
+# Skip gitignored files — designated for machine-specific state (settings.local.json,
+# CLAUDE.local.md, .venv/, node_modules/, etc.). git check-ignore does not require
+# the file to exist on disk, so this works for new Write operations too.
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]] \
+  && git -C "$CLAUDE_PROJECT_DIR" check-ignore -q "$FILE" 2>/dev/null; then
+  exit 0
+fi
+
+# Extract content to check — Write has .content, Edit has .new_string,
+# NotebookEdit has .new_source.
+case "$TOOL" in
+  Write) CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null | tr -d '\r') ;;
+  Edit) CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null | tr -d '\r') ;;
+  NotebookEdit) CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_source // empty' 2>/dev/null | tr -d '\r') ;;
+  *) exit 0 ;; # unreachable — $TOOL filtered to Write|Edit|NotebookEdit above
+esac
+[[ -n "${CONTENT:-}" ]] || exit 0
+
+# Resolve current repo root for the machine-specific-path check. Comments are
+# NOT exempt — examples and "do not use" comments still ship as hardcoded paths
+# in fresh clones, get copy-pasted, and rot. Use placeholders in comments too.
+PROJECT_ROOT=""
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  PROJECT_ROOT=$CLAUDE_PROJECT_DIR
+elif PROJECT_ROOT=$(git -C "$(dirname "$FILE")" rev-parse --show-toplevel 2>/dev/null); then
+  :
+else
+  PROJECT_ROOT=""
+fi
+
+# Repo-relative file for telemetry data.file (best-effort prefix strip).
+FILE_REL="$FILE"
+if [[ -n "$PROJECT_ROOT" ]]; then
+  _root="${PROJECT_ROOT//\\//}"
+  _root="${_root%/}"
+  _fwd="${FILE//\\//}"
+  FILE_REL="${_fwd#"$_root"/}"
+fi
+# Redaction: if the path could not be made repo-relative, emit the basename only
+# — never an absolute path (it would embed the developer's username) into telemetry.
+case "$FILE_REL" in
+  /* | [A-Za-z]:*) FILE_REL="${FILE_REL##*/}"; FILE_REL="${FILE_REL##*\\}" ;;
+  *) ;;
+esac
+
+# Emit one telemetry envelope: $1 status, $2 labels JSON array. Gated on the
+# high-res start stamp and the opt-in sink — the unwired path spawns nothing.
+emit_tel() {
+  [[ -n "$start" ]] || return 0
+  hook::telemetry_enabled || return 0
+  local data
+  data=$(jq -n --arg file "$FILE_REL" --argjson violations "$2" \
+    '{tool:"'"$TOOL"'",file:$file,violations:$violations}' 2>/dev/null) \
+    || data='{"tool":"","file":"","violations":[]}'
+  hook::emit_telemetry "hardcoded-path-check" "PreToolUse" "$1" "$start" "$data" "${CLAUDE_PROJECT_DIR:-}"
+}
+
+VIOLATIONS=$(hpp::scan_text "$CONTENT" "$PROJECT_ROOT" "$FILE")
+if [[ -n "$VIOLATIONS" ]]; then
+  {
+    printf 'Hardcoded machine-specific path(s) in %s:\n\n' "$FILE"
+    printf '%s' "$VIOLATIONS"
+    # shellcheck disable=SC2016
+    printf 'Use portable alternatives: ~/,  $HOME, $(pwd), $TMPDIR, '
+    printf 'git rev-parse --show-toplevel, or <placeholder> notation.\n'
+  } >&2
+  # Telemetry labels = the block headers only (e.g. "Linux user path detected"),
+  # never the matched lines — those carry the actual machine-specific path.
+  labels_json=$(grep -E 'detected:$' <<<"$VIOLATIONS" 2>/dev/null | sed 's/:$//' | jq -R . | jq -s . 2>/dev/null) || labels_json='[]'
+  emit_tel "blocked" "$labels_json"
+  exit 2
+fi
+
+emit_tel "ok" '[]'
+exit 0
diff --git a/plugins/guardrails/hooks/hardcoded-path-check.test.sh b/plugins/guardrails/hooks/hardcoded-path-check.test.sh
new file mode 100755
index 000000000..95384475b
--- /dev/null
+++ b/plugins/guardrails/hooks/hardcoded-path-check.test.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# Contract test for hardcoded-path-check.sh (guardrails plugin).
+#
+# Black-box subprocess invocation. Machine-path fixtures are assembled at
+# runtime from separator + segment fragments so no contiguous machine-path
+# literal appears in this file's source bytes — a path-shape scanner sees a
+# clean test file.
+
+set -uo pipefail
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$HOOK_DIR/hardcoded-path-check.sh"
+TEST_TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+# shellcheck source=guardrails-test-helpers.sh
+source "$HOOK_DIR/guardrails-test-helpers.sh"
+
+# Neutralize ambient CLAUDE_PROJECT_DIR so default cases hit the intended path.
+unset CLAUDE_PROJECT_DIR
+
+# Runtime-assembled machine paths (no contiguous path literal in source).
+SL='/'
+# shellcheck disable=SC1003  # BS is a literal single backslash, not a quote escape
+BS='\'
+LINUX_HOME="${SL}home${SL}jdoe${SL}project"
+MAC_HOME="${SL}Users${SL}alice${SL}dev${SL}repo"
+MAC_SHARED="${SL}Users${SL}Shared${SL}output"
+WIN_HOME="C:${BS}Users${BS}bob${BS}repo"
+
+FIXTURE="$TEST_TMPDIR/fixture.txt"
+PS1_FIXTURE="$TEST_TMPDIR/script.ps1"
+
+# ============================ DETECT (exit 2) ================================
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "cd ${LINUX_HOME} && ls")" 2>&1); RC=$?
+assert_exit "linux home → exit 2" 2 "$RC"
+assert_contains "linux home → message" "$OUT" "Linux user path"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "cd ${MAC_HOME} && ls")" 2>&1); RC=$?
+assert_exit "macos home → exit 2" 2 "$RC"
+assert_contains "macos → message" "$OUT" "macOS user path"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "cd ${WIN_HOME} && dir")" 2>&1); RC=$?
+assert_exit "windows home → exit 2" 2 "$RC"
+assert_contains "windows → message" "$OUT" "Windows user path"
+
+# Cross-OS leak: a Linux path inside a .ps1 still fires (only Windows is suppressed).
+OUT=$(bash "$HOOK" <<<"$(write_json "$PS1_FIXTURE" "Set-Location ${LINUX_HOME}")" 2>&1); RC=$?
+assert_exit "Linux leak in .ps1 → exit 2" 2 "$RC"
+assert_contains "cross-OS leak → linux message" "$OUT" "Linux user path"
+
+OUT=$(bash "$HOOK" <<<"$(edit_json "$FIXTURE" "new path ${LINUX_HOME}")" 2>&1); RC=$?
+assert_exit "Edit new_string → exit 2" 2 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(notebook_json "$FIXTURE" "cd ${MAC_HOME}")" 2>&1); RC=$?
+assert_exit "NotebookEdit new_source → exit 2" 2 "$RC"
+
+# ============================ ALLOW (exit 0) ================================
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" 'echo "hello world"')" 2>&1); RC=$?
+assert_exit "clean content → exit 0" 0 "$RC"
+assert_silent "clean content → no stderr" "$OUT"
+
+# shellcheck disable=SC2016
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" 'cd $HOME/project && cd ~/dev')" 2>&1); RC=$?
+assert_exit "dynamic \$HOME / ~ → exit 0" 0 "$RC"
+assert_silent "dynamic refs → no stderr" "$OUT"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "cp file ${MAC_SHARED}")" 2>&1); RC=$?
+assert_exit "macos Shared dir → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$PS1_FIXTURE" "\$cfg = '${WIN_HOME}'")" 2>&1); RC=$?
+assert_exit "Windows path in .ps1 → suppressed → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(other_tool_json "Read" "$FIXTURE")" 2>&1); RC=$?
+assert_exit "Read tool → exit 0" 0 "$RC"
+
+# Outside CLAUDE_PROJECT_DIR → exit 0 (another repo's concern).
+OUT=$(CLAUDE_PROJECT_DIR="$TEST_TMPDIR" bash "$HOOK" <<<"$(write_json "/tmp/other/file.txt" "$LINUX_HOME")" 2>&1); RC=$?
+assert_exit "outside CLAUDE_PROJECT_DIR → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "/some/repo/.claude/hooks/foo.sh" "pattern ${LINUX_HOME}")" 2>&1); RC=$?
+assert_exit ".claude/hooks/ self-exemption → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "/some/repo/.lefthook/pre-commit/foo.sh" "pattern ${LINUX_HOME}")" 2>&1); RC=$?
+assert_exit ".lefthook/ self-exemption → exit 0" 0 "$RC"
+
+# CC session/workflow state under ~/.claude/projects/ (outside any repo tree).
+projects_fp="C:${BS}Users${BS}bob${BS}.claude${BS}projects${BS}my-repo${BS}wf.js"
+OUT=$(bash "$HOOK" <<<"$(write_json "$projects_fp" "const out = '${WIN_HOME}'")" 2>&1); RC=$?
+assert_exit ".claude/projects/ CC-state self-exemption → exit 0" 0 "$RC"
+
+# Gitignored file → exit 0 (consumer seam via .gitignore + git check-ignore).
+GITREPO="$TEST_TMPDIR/gitrepo"
+mkdir -p "$GITREPO"
+git -C "$GITREPO" init -q
+printf 'ignored.txt\n' >"$GITREPO/.gitignore"
+OUT=$(CLAUDE_PROJECT_DIR="$GITREPO" bash "$HOOK" <<<"$(write_json "$GITREPO/ignored.txt" "$LINUX_HOME")" 2>&1); RC=$?
+assert_exit "gitignored file → exit 0 (consumer seam)" 0 "$RC"
+
+# Kill switch — disabled path is a clean no-op even on a real machine path.
+OUT=$(HOOK_HARDCODED_PATH_CHECK_ENABLED=false bash "$HOOK" <<<"$(write_json "$FIXTURE" "$LINUX_HOME")" 2>&1); RC=$?
+assert_exit "kill switch off → exit 0" 0 "$RC"
+assert_silent "kill switch off → no stderr" "$OUT"
+
+# ============================ TELEMETRY ====================================
+TEL="$(mktemp -p "$TEST_TMPDIR")"
+SINK="$(make_sink "cat >\"$TEL\"")"
+env HOOK_TELEMETRY_SINK="$SINK" CLAUDE_PROJECT_DIR="$TEST_TMPDIR" \
+  bash "$HOOK" <<<"$(write_json "$FIXTURE" "cd ${LINUX_HOME}")" >/dev/null 2>&1 || true
+if wait_for_sink "$TEL"; then
+  assert_contains "telemetry: hook id" "$(jq -r '.hook' "$TEL")" "hardcoded-path-check"
+  assert_contains "telemetry: status blocked" "$(jq -r '.status' "$TEL")" "blocked"
+  assert_contains "telemetry: violation label" "$(jq -r '.data.violations[]' "$TEL")" "Linux user path detected"
+  assert_absent "telemetry: no matched path in envelope" "$(cat "$TEL")" "jdoe"
+else
+  bad "telemetry: no envelope written on block"
+fi
+
+report
diff --git a/plugins/guardrails/hooks/hook-utils.sh b/plugins/guardrails/hooks/hook-utils.sh
new file mode 100644
index 000000000..1c003435a
--- /dev/null
+++ b/plugins/guardrails/hooks/hook-utils.sh
@@ -0,0 +1,247 @@
+# shellcheck shell=bash
+# Shared hook utility library for this marketplace's hook plugins. Sourced
+# (not executed): kill switch, file_path parsing + path normalization,
+# repo-root resolution, additionalContext accumulator, telemetry envelope.
+#
+# SINGLE SOURCE OF TRUTH: lib/hook-utils.sh at the marketplace repo root. The
+# copies at plugins/*/hooks/hook-utils.sh exist because installed plugins are
+# cache-isolated and must be self-contained — never edit a copy. Edit the
+# source and run scripts/sync-hook-utils.sh; CI rejects drifted copies.
+
+# Guard against double-sourcing.
+[[ -n "${_HOOK_UTILS_LOADED:-}" ]] && return 0
+readonly _HOOK_UTILS_LOADED=1
+
+# Per-hook kill switch via HOOK_<NAME>_ENABLED env var. Exits 0 (allow) if
+# disabled. Place after source, before stdin parsing.
+#   hook::check_enabled "MARKDOWN_FORMAT"  # checks HOOK_MARKDOWN_FORMAT_ENABLED
+hook::check_enabled() {
+  local var_name="HOOK_${1}_ENABLED"
+  if [[ "${!var_name:-true}" != "true" ]]; then
+    exit 0
+  fi
+}
+
+# Normalize a path for the membership comparison below: backslashes → forward
+# slashes, and — only on Windows/MSYS, whose filesystem is case-insensitive —
+# fold a leading drive (POSIX `/c/...` or `c:/...`) to an upper-case drive
+# letter + lower-cased remainder so the byte-exact comparison is effectively
+# case-insensitive. The fold is gated on the host (OSTYPE), NOT on the path
+# shape: on a case-sensitive POSIX filesystem a real single-letter top-level
+# directory such as `/c/Repo` must pass through unchanged, otherwise it would
+# collapse with `/c/repo` and the membership guard would admit a sibling
+# outside CLAUDE_PROJECT_DIR. The result is used ONLY for comparison; the
+# emitted path is always the caller's original.
+hook::normalize_path() {
+  local p="${1//\\//}"
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32)
+    if [[ "$p" =~ ^/([a-zA-Z])/ || "$p" =~ ^([a-zA-Z]):/ ]]; then
+      local rest="${p:2}"
+      printf '%s' "${BASH_REMATCH[1]^}:${rest,,}"
+      return
+    fi
+    ;;
+  *) ;; # POSIX hosts: case-sensitive FS, no drive fold — pass through below
+  esac
+  printf '%s' "$p"
+}
+
+# Canonicalize to a physical path — symlinks resolved — for the membership
+# comparison below, so an in-project symlink pointing outside the project root
+# cannot defeat the guard (the lexical path would pass the prefix check while
+# the write lands elsewhere). GNU realpath ships with Git Bash and Linux
+# coreutils; readlink -f covers the BSD/macOS hosts that have no realpath.
+# When neither resolver exists the caller falls back to comparing the lexical
+# path as before — the guard is defense-in-depth scoping for a file the agent
+# already wrote via its own tools, so degrading to the historical comparison
+# beats silently disabling the hook on those hosts.
+hook::physical_path() {
+  local resolved
+  if resolved=$(realpath -- "$1" 2>/dev/null) || resolved=$(readlink -f -- "$1" 2>/dev/null); then
+    if [[ -n "$resolved" ]]; then
+      printf '%s' "$resolved"
+      return
+    fi
+  fi
+  printf '%s' "$1"
+}
+
+# Parse file_path from PostToolUse JSON on stdin; validate existence and (when
+# CLAUDE_PROJECT_DIR is set) project membership. Both sides of the membership
+# comparison are canonicalized (symlinks resolved) first, so neither an
+# escaping symlink nor a project root reached via a symlinked path (e.g.
+# macOS /tmp) skews the verdict. Outputs the path on success. Returns 1 to skip.
+#   FILE=$(hook::read_file_path) || exit 0
+hook::read_file_path() {
+  local file
+  file=$(jq -r '(.tool_input.file_path // empty) | gsub("\r";"")' 2>/dev/null)
+  [[ -n "$file" ]] || return 1
+  [[ -f "$file" ]] || return 1
+  if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+    local norm_file norm_project
+    norm_file=$(hook::normalize_path "$(hook::physical_path "$file")")
+    norm_project=$(hook::normalize_path "$(hook::physical_path "${CLAUDE_PROJECT_DIR}")")
+    norm_project="${norm_project%/}"
+    # Anchor on a path-segment boundary: accept the project root itself or a
+    # child under it, but not a sibling whose name merely shares the prefix
+    # (e.g. /c/repo must not admit /c/repo-backup/...).
+    if [[ "$norm_file" != "$norm_project" && "$norm_file" != "$norm_project"/* ]]; then
+      return 1
+    fi
+  fi
+  printf '%s' "$file"
+}
+
+# Resolve the repository root (working-tree top) for a path inside the tree.
+# markdownlint config auto-discovery is CWD-anchored, so the hook cd's here
+# before linting. File-anchored (`git -C "$hint" rev-parse --show-toplevel`)
+# so it is correct for clones, linked worktrees, and bare-hub clones; falls
+# back to the hint (with a trailing /.claude stripped) when git cannot resolve.
+#   ROOT=$(hook::repo_root "$some_path")
+hook::repo_root() {
+  local hint="${1:-.}"
+  local root
+  root=$(git -C "$hint" rev-parse --show-toplevel 2>/dev/null | tr -d '\r')
+  if [[ -z "$root" ]]; then
+    root="$hint"
+    root="${root%/.claude}"
+    root="${root%\\.claude}"
+  fi
+  printf '%s' "$root"
+}
+
+# Per-hook stdout context accumulator. ctx_reset at entry, ctx_append per line,
+# ctx_flush once at exit with the hook event name.
+_HOOK_CTX_BUFFER=""
+
+hook::ctx_reset() {
+  _HOOK_CTX_BUFFER=""
+}
+
+hook::ctx_append() {
+  _HOOK_CTX_BUFFER+="$1"$'\n'
+}
+
+# Emit the accumulated context as hookSpecificOutput JSON, then clear the buffer.
+hook::ctx_flush() {
+  local event_name="$1"
+  local trimmed="${_HOOK_CTX_BUFFER%"${_HOOK_CTX_BUFFER##*[![:space:]]}"}"
+  trimmed="${trimmed#"${trimmed%%[![:space:]]*}"}"
+  hook::emit_additional_context "$event_name" "$trimmed"
+  hook::ctx_reset
+}
+
+# Cheap telemetry opt-in probe — true iff a consumer wired a sink. Producers
+# gate telemetry-payload construction on this (repo-relative path
+# normalization, data JSON) so the unwired default path spawns zero
+# telemetry-only subprocesses. Pure shell test, no subprocess.
+# hook::emit_telemetry re-checks the sink itself, so skipping this probe
+# costs only wasted payload work, never correctness.
+hook::telemetry_enabled() {
+  [[ -n "${HOOK_TELEMETRY_SINK:-}" ]]
+}
+
+# Emit one telemetry envelope per hook run to the consumer-set sink.
+# Fire-and-forget: sink is dispatched in the background; the hook never waits
+# on it and its failure never affects the hook's own exit code or stdout.
+# Opt-in guard: HOOK_TELEMETRY_SINK unset or empty → return 0 immediately.
+# Fail-open: jq absent → return 0 immediately.
+#
+# Usage:
+#   hook::emit_telemetry <hook_id> <hook_event> <status> <start_epoch> <data_json> [repo_root]
+#
+# <start_epoch>  Value of $EPOCHREALTIME captured by the caller before work began.
+#               Handles both '.' and ',' as the decimal separator (LC_NUMERIC).
+# <data_json>   Pre-built JSON object for the `data` field.
+# <repo_root>   Optional consuming-repo root, used to resolve a RELATIVE
+#               HOOK_TELEMETRY_SINK. The caller passes the root it already
+#               resolved for data.file; ignored when the sink is absolute.
+#
+# Sink path resolution: HOOK_TELEMETRY_SINK may be absolute OR relative to the
+# consuming repo root. Absolute (POSIX /… or Windows X:\ / X:/) is used as-is; a
+# relative value is joined onto <repo_root> (or $CLAUDE_PROJECT_DIR when no root
+# is passed), and skipped fail-open if neither is available. Relative is the
+# portable, team-shared wiring form: CC injects settings.json env values
+# literally (no ${VAR} expansion), so a relative path tracked in settings.json is
+# the only clone-portable, worktree-safe option.
+#
+# NEVER writes to fd1 (the hook's stdout / additionalContext channel).
+hook::emit_telemetry() {
+  # Opt-in guard.
+  [[ -n "${HOOK_TELEMETRY_SINK:-}" ]] || return 0
+  # Fail-open when jq is absent.
+  command -v jq >/dev/null 2>&1 || return 0
+
+  local hook_id="$1"
+  local hook_event="$2"
+  local status="$3"
+  local start_epoch="$4"
+  local data_json="$5"
+  local repo_root="${6:-}"
+
+  # Compute duration_ms from caller's $EPOCHREALTIME snapshot to now.
+  # Both '.' and ',' separators handled; 10# prefix prevents octal misreading
+  # of fractional parts with leading zeros (e.g. .045123 → 10#045123 = 45123).
+  local now=$EPOCHREALTIME
+  local s_s="${start_epoch%[.,]*}" s_f="${start_epoch#*[.,]}"
+  local e_s="${now%[.,]*}" e_f="${now#*[.,]}"
+  local duration_ms=$(((e_s * 1000000 + 10#$e_f - s_s * 1000000 - 10#$s_f) / 1000))
+
+  # True UTC timestamp (TZ= prefix overrides LC_ALL / local TZ; the Z is not a lie).
+  local timestamp
+  timestamp=$(TZ=UTC printf '%(%Y-%m-%dT%H:%M:%SZ)T' -1)
+
+  # Build the envelope. Redirect jq stderr to /dev/null; output goes to a local
+  # variable — never to fd1.
+  local envelope
+  envelope=$(jq -n \
+    --arg schema_version "1.0" \
+    --arg timestamp "$timestamp" \
+    --arg hook "$hook_id" \
+    --arg hook_event "$hook_event" \
+    --arg status "$status" \
+    --argjson duration_ms "$duration_ms" \
+    --argjson data "$data_json" \
+    '{schema_version:$schema_version,timestamp:$timestamp,hook:$hook,hook_event:$hook_event,status:$status,duration_ms:$duration_ms,data:$data}' \
+    2>/dev/null) || return 0
+
+  # Resolve the sink path. A relative HOOK_TELEMETRY_SINK is joined onto the
+  # consuming repo root (portable, tracked wiring); absolute is used as-is. A
+  # relative value with no anchor is skipped fail-open — never exec a path the
+  # drifted hook CWD would resolve incorrectly.
+  local sink="$HOOK_TELEMETRY_SINK"
+  case "$sink" in
+  /* | [A-Za-z]:[/\\]*) ;;
+  *)
+    local root="${repo_root:-${CLAUDE_PROJECT_DIR:-}}"
+    [[ -n "$root" ]] || return 0
+    sink="${root%/}/$sink"
+    ;;
+  esac
+
+  # Fire-and-forget: pipe the envelope to the sink in a background subshell.
+  # The subshell's stdout AND stderr are redirected to /dev/null so the sink
+  # cannot write to the hook's fd1 (the additionalContext channel) and the
+  # backgrounded subshell does not hold a copy of the hook's fd1 open — which
+  # would block any command substitution wrapping the hook until the sink exits
+  # (the "C1 fd1-inheritance blocker"). The sink is quoted — it is a single
+  # executable path (wrap in a script to pass arguments).
+  printf '%s\n' "$envelope" | ("$sink" >/dev/null 2>&1) &
+}
+
+# Print cross-host hook JSON to stdout (exit 0). No-op when context is empty.
+# Shape: { hookSpecificOutput: { hookEventName[, additionalContext] } }.
+hook::emit_additional_context() {
+  local event_name="$1"
+  local context="$2"
+  [[ -n "$context" ]] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+  jq -n \
+    --arg event "$event_name" \
+    --arg ctx "$context" \
+    '{hookSpecificOutput: (
+      {hookEventName: $event}
+      + (if $ctx != "" then {additionalContext: $ctx} else {} end)
+    )}'
+}
diff --git a/plugins/guardrails/hooks/hooks.json b/plugins/guardrails/hooks/hooks.json
new file mode 100644
index 000000000..7b8684ad9
--- /dev/null
+++ b/plugins/guardrails/hooks/hooks.json
@@ -0,0 +1,43 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/secret-pattern-detection.sh",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/hardcoded-path-check.sh",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/block-no-verify.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/cli-flag-verify.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/guardrails/hooks/secret-pattern-detection.sh b/plugins/guardrails/hooks/secret-pattern-detection.sh
new file mode 100755
index 000000000..4e70a1b95
--- /dev/null
+++ b/plugins/guardrails/hooks/secret-pattern-detection.sh
@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# PreToolUse hook: detect secret/credential patterns before file writes.
+# Triggered on Write|Edit|NotebookEdit of any file.
+#
+# BLOCKING: exits 2 when high-confidence secret patterns (API keys, tokens,
+# private keys) are detected in new content. Stderr feedback tells Claude what
+# was found and how to fix it.
+#
+# Pattern selection: only HIGH-confidence patterns with distinctive prefixes
+# and fixed lengths. Generic patterns (password=, api_key=, secret=) are
+# excluded — too many false positives for a real-time blocking hook. Sourced
+# from gitleaks, TruffleHog, and secrets-patterns-db.
+#
+# Cross-platform: uses grep -E (POSIX ERE) only — no grep -P (macOS lacks it).
+#
+# Consumer seams: scoped to $CLAUDE_PROJECT_DIR (files outside it are another
+# repo's concern); a generic allowlist exempts dependency caches, .env
+# examples, test fixtures, and machine-local CC state. Disable entirely with
+# HOOK_SECRET_PATTERN_DETECTION_ENABLED=false.
+
+set -uo pipefail
+
+# shellcheck source=hook-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/hook-utils.sh"
+
+hook::check_enabled "SECRET_PATTERN_DETECTION"
+
+# High-res start stamp for telemetry (Bash 5.0+; empty on older bash → skip).
+start=${EPOCHREALTIME:-}
+
+# jq is required to parse the tool payload. Fail OPEN when it is absent, but make
+# the degraded state visible rather than silently disabling the guard.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "guardrails/secret-pattern-detection: jq not found on PATH — guard disabled (install jq to enable)." >&2
+  exit 0
+fi
+
+# Read inherited fd0 directly (bare cat) — NEVER `</dev/stdin` (Windows Git Bash
+# Win32-pipe ENOENT → silent no-op). Buffer once; parse each field from it.
+INPUT=$(cat)
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null | tr -d '\r')
+
+case "$TOOL" in
+  Write | Edit | NotebookEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null | tr -d '\r')
+[[ -n "$FILE" ]] || exit 0
+
+NORM_FILE="$(hook::normalize_path "$FILE")"
+
+# Case-preserved, slash-normalized path for the allowlist globs below. On
+# Windows hook::normalize_path lower-cases the remainder so the membership
+# comparison is effectively case-insensitive; reusing that folded value for the
+# case-sensitive allowlist would silently break the upper-case patterns
+# (CLAUDE.local.md). The allowlist globs are suffix/substring matches, so a
+# plain backslash→slash fixup is enough — the drive letter never participates.
+ALLOW_FILE="${FILE//\\//}"
+
+# --- Scope guard: police only files inside THIS project ---
+# A PreToolUse Write|Edit hook fires on every file write regardless of which
+# repo the target lives in. A file outside the project root is not ours to scan
+# — that repo owns its own secret policy. Fail CLOSED: when the root cannot be
+# resolved (CLAUDE_PROJECT_DIR unset), fall through and scan rather than skip.
+PROJECT_DIR="$(hook::normalize_path "${CLAUDE_PROJECT_DIR:-}")"
+PROJECT_DIR="${PROJECT_DIR%/}"
+if [[ -n "$PROJECT_DIR" ]]; then
+  case "$NORM_FILE" in
+    "$PROJECT_DIR"/*) ;; # inside the project — proceed
+    *) exit 0 ;;         # outside the project — not this hook's concern
+  esac
+fi
+
+# --- Allowlist: files that legitimately contain secret patterns ---
+# Each entry grants a narrow hole — keep it tight:
+#   - hook scripts: contain regex strings for the patterns themselves
+#   - settings.local.json / CLAUDE.local.md: gitignored, designed for real secrets
+#   - .venv / node_modules: gitignored dependency caches
+#   - .env.example/sample/template: placeholder format; the patterns require
+#     10+ chars after prefix so `sk_test_xxx`-style placeholders don't match
+#   - tests/fixtures, tests/testdata: scoped to test trees only
+#   - CC skill context/completed: research notes; code review is the backstop
+case "$ALLOW_FILE" in
+  *.claude/hooks/*) exit 0 ;;
+  *settings.local.json) exit 0 ;;
+  *CLAUDE.local.md) exit 0 ;;
+  # Dependency caches — anchored to a path-segment boundary (leading `/` or start
+  # of path) so a directory that merely CONTAINS the name (evil_node_modules/,
+  # .venv-backup/) is NOT exempted from the scan.
+  */.venv/* | .venv/*) exit 0 ;;
+  */node_modules/* | node_modules/*) exit 0 ;;
+  *.env.example | *.env.sample | *.env.template) exit 0 ;;
+  *tests/fixtures/* | *tests/testdata/* | *Tests/fixtures/* | *Tests/testdata/*) exit 0 ;;
+  *.claude/skills/*/context/*) exit 0 ;;
+  *.claude/skills/*/completed/*) exit 0 ;;
+  *) ;; # proceed to content check
+esac
+
+# --- Extract content to check ---
+case "$TOOL" in
+  Write) CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null | tr -d '\r') ;;
+  Edit) CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null | tr -d '\r') ;;
+  NotebookEdit) CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_source // empty' 2>/dev/null | tr -d '\r') ;;
+  *) exit 0 ;; # unreachable — $TOOL filtered to Write|Edit|NotebookEdit above
+esac
+[[ -n "${CONTENT:-}" ]] || exit 0
+
+# Repo-relative file for telemetry data.file (best-effort prefix strip).
+FILE_REL="$FILE"
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  _root="${CLAUDE_PROJECT_DIR//\\//}"
+  _root="${_root%/}"
+  _fwd="${FILE//\\//}"
+  FILE_REL="${_fwd#"$_root"/}"
+fi
+# Redaction: if the path could not be made repo-relative, emit the basename only
+# — never an absolute path (it would embed the developer's username) into telemetry.
+case "$FILE_REL" in
+  /* | [A-Za-z]:*) FILE_REL="${FILE_REL##*/}"; FILE_REL="${FILE_REL##*\\}" ;;
+  *) ;;
+esac
+
+# Emit one telemetry envelope: $1 status, $2 labels JSON array. Gated on the
+# high-res start stamp and the opt-in sink — the unwired path spawns nothing.
+emit_tel() {
+  [[ -n "$start" ]] || return 0
+  hook::telemetry_enabled || return 0
+  local data
+  data=$(jq -n --arg file "$FILE_REL" --argjson violations "$2" \
+    '{tool:"'"$TOOL"'",file:$file,violations:$violations}' 2>/dev/null) \
+    || data='{"tool":"","file":"","violations":[]}'
+  hook::emit_telemetry "secret-pattern-detection" "PreToolUse" "$1" "$start" "$data" "${CLAUDE_PROJECT_DIR:-}"
+}
+
+# --- High-confidence secret patterns (grep -E compatible) ---
+# Each pattern has a distinctive prefix + structured format = very low FP rate.
+# Sourced from gitleaks default rules (github.com/gitleaks/gitleaks).
+VIOLATIONS=""
+LABELS=()
+
+check_pattern() {
+  local label="$1" pattern="$2" lines
+  lines=$(grep -nE -- "$pattern" <<<"$CONTENT" 2>/dev/null | head -3 | cut -d: -f1 | tr '\n' ',' | sed 's/,$//')
+  if [[ -n "$lines" ]]; then
+    VIOLATIONS="${VIOLATIONS}${label} (line ${lines})\n"
+    LABELS+=("$label")
+  fi
+}
+
+# (label, ERE) parallel arrays — one combined grep can fast-reject the common
+# (no-secret) case in a single process. Index alignment is load-bearing: the
+# Nth label describes the Nth pattern.
+SECRET_LABELS=(
+  "AWS Access Key"
+  "GitHub PAT"
+  "GitHub OAuth Token"
+  "GitHub App Token"
+  "GitHub Fine-grained PAT"
+  "GitLab PAT"
+  "Slack Bot Token"
+  "Slack User/App Token"
+  "Stripe Key"
+  "OpenAI API Key"
+  "OpenAI API Key"
+  "Private Key (PEM)"
+)
+SECRET_PATTERNS=(
+  '(AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}'          # AWS (AKIA/ASIA/ABIA/ACCA + 16)
+  'ghp_[0-9a-zA-Z]{36}'                        # GitHub PAT
+  'gho_[0-9a-zA-Z]{36}'                        # GitHub OAuth
+  'gh[us]_[0-9a-zA-Z]{36}'                     # GitHub app (ghu_/ghs_)
+  'github_pat_[0-9a-zA-Z_]{82}'                # GitHub fine-grained PAT
+  'glpat-[0-9a-zA-Z_-]{20}'                    # GitLab PAT
+  'xoxb-[0-9]{10,13}-[0-9]{10,13}'             # Slack bot token
+  'xox[pe]-[0-9]{10,13}-'                      # Slack user/app token
+  '[sr]k_(test|live|prod)_[0-9a-zA-Z]{10,99}'  # Stripe key
+  'sk-(proj|svcacct|admin)-[A-Za-z0-9_-]{20,}' # OpenAI prefixed API key
+  'sk-[A-Za-z0-9]{20,}'                        # OpenAI legacy bare sk- key
+  '-----BEGIN [A-Z ]*PRIVATE KEY-----'         # PEM private key header
+)
+
+# Fast reject: one grep spawn matching ANY pattern. The common case (no secret)
+# exits here. Without it, the per-pattern itemization (grep|head|cut|tr|sed = 5
+# processes × 12 patterns) runs unconditionally; on a large file under Windows
+# MSYS2 + Defender that is ~60 spawns costing 10-25s. grep -qE over all patterns
+# is logically equivalent to "any pattern matched" — if it finds nothing, no
+# individual pattern can match, so skipping itemization is sound.
+grep_e_args=()
+for pattern in "${SECRET_PATTERNS[@]}"; do
+  grep_e_args+=(-e "$pattern")
+done
+if ! grep -qE "${grep_e_args[@]}" <<<"$CONTENT" 2>/dev/null; then
+  emit_tel "ok" '[]'
+  exit 0
+fi
+
+# Rare path: a secret matched — itemize per-pattern (label + line numbers) for
+# the actionable message. The expensive pipeline only runs here, on a hit.
+for i in "${!SECRET_PATTERNS[@]}"; do
+  check_pattern "${SECRET_LABELS[$i]}" "${SECRET_PATTERNS[$i]}"
+done
+
+# --- Report violations ---
+if [[ -n "$VIOLATIONS" ]]; then
+  {
+    printf 'Secret/credential pattern(s) detected in %s:\n\n' "$FILE"
+    printf '%b' "$VIOLATIONS"
+    printf 'If this is a test fixture or example, add the file to the allowlist\n'
+    printf 'in secret-pattern-detection.sh. Never commit real secrets — use\n'
+    printf 'environment variables, settings.local.json, or a secret manager.\n'
+  } >&2
+  labels_json=$(printf '%s\n' "${LABELS[@]}" | jq -R . | jq -s . 2>/dev/null) || labels_json='[]'
+  emit_tel "blocked" "$labels_json"
+  exit 2
+fi
+
+emit_tel "ok" '[]'
+exit 0
diff --git a/plugins/guardrails/hooks/secret-pattern-detection.test.sh b/plugins/guardrails/hooks/secret-pattern-detection.test.sh
new file mode 100755
index 000000000..ab00ab360
--- /dev/null
+++ b/plugins/guardrails/hooks/secret-pattern-detection.test.sh
@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# Contract test for secret-pattern-detection.sh (guardrails plugin).
+#
+# Black-box subprocess invocation. The hook reads file_path as a string only —
+# fixtures need not exist on disk.
+#
+# Token construction discipline: every real-shape token is assembled at runtime
+# from concatenated parts, so the literal joined string never appears in this
+# file's source bytes — no secret scanner (gitleaks etc.) sees a committed key.
+
+set -uo pipefail
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$HOOK_DIR/secret-pattern-detection.sh"
+TEST_TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+# shellcheck source=guardrails-test-helpers.sh
+source "$HOOK_DIR/guardrails-test-helpers.sh"
+
+# Neutralize any ambient CLAUDE_PROJECT_DIR (a CC-wrapped run sets it) so the
+# default cases exercise the fail-closed scan path deterministically.
+unset CLAUDE_PROJECT_DIR
+
+# Runtime-constructed obviously-fake tokens (never a literal joined string).
+AWS_PREFIX='AKIA'
+AWS_TOKEN="${AWS_PREFIX}IOSFODNN7EXAMPLE"
+GH_PREFIX='ghp_'
+GH_PAT="${GH_PREFIX}$(printf 'a%.0s' {1..36})"
+SLACK_PREFIX='xoxb-'
+SLACK_TOKEN="${SLACK_PREFIX}1234567890123-9876543210987"
+STRIPE_PREFIX='sk_live_'
+STRIPE_TOKEN="${STRIPE_PREFIX}abcdefghij1234567890"
+OPENAI_PREFIX='sk-'
+OPENAI_BARE_KEY="${OPENAI_PREFIX}$(printf 'A%.0s' {1..25})"
+PEM_HEADER='-----BEGIN '"PRIVATE KEY-----"
+
+# Force the Windows case-fold path even on Linux CI: OSTYPE must be set BEFORE
+# the hook is sourced (bash resets it to the build value at startup).
+run_hook_windows() {
+  bash -c 'OSTYPE=msys; source "$1"' _ "$HOOK" <<<"$1"
+}
+
+FIXTURE="$TEST_TMPDIR/fixture.txt"
+
+# ============================ DETECT (exit 2) ================================
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "config = '$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "AWS Access Key → exit 2" 2 "$RC"
+assert_contains "AWS → message" "$OUT" "AWS Access Key"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "token = '$GH_PAT'")" 2>&1); RC=$?
+assert_exit "GitHub PAT → exit 2" 2 "$RC"
+assert_contains "GH PAT → message" "$OUT" "GitHub PAT"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "SLACK='$SLACK_TOKEN'")" 2>&1); RC=$?
+assert_exit "Slack Bot Token → exit 2" 2 "$RC"
+assert_contains "Slack → message" "$OUT" "Slack Bot Token"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "STRIPE_KEY='$STRIPE_TOKEN'")" 2>&1); RC=$?
+assert_exit "Stripe Key → exit 2" 2 "$RC"
+assert_contains "Stripe → message" "$OUT" "Stripe Key"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "OPENAI_KEY='$OPENAI_BARE_KEY'")" 2>&1); RC=$?
+assert_exit "OpenAI bare sk- key → exit 2" 2 "$RC"
+assert_contains "OpenAI bare sk- → message" "$OUT" "OpenAI API Key"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" "$PEM_HEADER")" 2>&1); RC=$?
+assert_exit "PEM private key → exit 2" 2 "$RC"
+assert_contains "PEM → message" "$OUT" "Private Key (PEM)"
+
+OUT=$(bash "$HOOK" <<<"$(edit_json "$FIXTURE" "old to '$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "Edit new_string → exit 2" 2 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(notebook_json "$FIXTURE" "secret = '$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "NotebookEdit new_source → exit 2" 2 "$RC"
+
+# In-project secret still blocks when CLAUDE_PROJECT_DIR is set (file under root).
+OUT=$(CLAUDE_PROJECT_DIR="/repo" bash "$HOOK" <<<"$(write_json "/repo/src/config.env" "config = '$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "in-project secret with PROJECT_DIR set → exit 2" 2 "$RC"
+assert_contains "in-project secret → message" "$OUT" "AWS Access Key"
+
+# Trailing slash on CLAUDE_PROJECT_DIR must not skip in-project scans.
+OUT=$(CLAUDE_PROJECT_DIR="/repo/" bash "$HOOK" <<<"$(write_json "/repo/src/config.env" "config = '$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "trailing-slash PROJECT_DIR still scans in-project file → exit 2" 2 "$RC"
+
+# ============================ ALLOW (exit 0) ================================
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" 'just some normal code here')" 2>&1); RC=$?
+assert_exit "clean content → exit 0" 0 "$RC"
+assert_silent "clean content → no stderr" "$OUT"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "$FIXTURE" 'api_key=mySecretValue123')" 2>&1); RC=$?
+assert_exit "low-confidence generic pattern → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(other_tool_json "Read" "$FIXTURE")" 2>&1); RC=$?
+assert_exit "Read tool → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/.env.example" "API_KEY='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit ".env.example allowlist → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/tests/fixtures/secrets.txt" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "tests/fixtures/ allowlist → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/.claude/hooks/foo.sh" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit ".claude/hooks/ self-exemption → exit 0" 0 "$RC"
+
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/settings.local.json" "{\"k\":\"$AWS_TOKEN\"}")" 2>&1); RC=$?
+assert_exit "settings.local.json allowlist → exit 0" 0 "$RC"
+
+# CLAUDE.local.md allowlist must match case-sensitively even under the Windows
+# path fold (regression: the fold lower-cases the membership path only).
+OUT=$(run_hook_windows "$(write_json "C:/repo/CLAUDE.local.md" "token='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "CLAUDE.local.md allowlist (case-sensitive) → exit 0" 0 "$RC"
+
+# Secret in a file OUTSIDE the project root → exit 0, silent.
+OUT=$(CLAUDE_PROJECT_DIR="/repo" bash "$HOOK" <<<"$(write_json "/other-repo/fixtures/bad/leak.env" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "file outside project root → exit 0" 0 "$RC"
+assert_silent "outside project root → no stderr" "$OUT"
+
+# Kill switch — disabled path is a clean no-op even on a real-shape token.
+OUT=$(HOOK_SECRET_PATTERN_DETECTION_ENABLED=false bash "$HOOK" <<<"$(write_json "$FIXTURE" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "kill switch off → exit 0" 0 "$RC"
+assert_silent "kill switch off → no stderr" "$OUT"
+
+# --- jq fail-open visibility (finding P4) -----------------------------------
+# Runtime jq-removal is not portably simulable — an isolated bin dir without jq
+# cannot host bash + coreutils (their DLLs / PATH) across Git Bash and Linux.
+# Assert the fail-open guard (visible notice, no silent disable) is present in
+# the hook source; the runtime path itself is a trivial `command -v jq` short.
+HOOK_SRC=$(cat "$HOOK")
+assert_contains "jq guard: command -v jq check present" "$HOOK_SRC" 'command -v jq'
+assert_contains "jq guard: visible stderr notice" "$HOOK_SRC" 'jq not found on PATH'
+assert_contains "jq guard: fail-open exit 0" "$HOOK_SRC" 'guard disabled'
+
+# --- Allowlist path-segment anchoring (finding P5) --------------------------
+# A real dependency-cache SEGMENT is exempt; a directory that merely CONTAINS the
+# name as a substring is scanned (and blocked on a real token).
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/src/node_modules/pkg/creds.env" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "node_modules real segment → exit 0 (exempt)" 0 "$RC"
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/evil_node_modules/creds.env" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit "evil_node_modules substring → exit 2 (scanned)" 2 "$RC"
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/.venv/lib/creds.env" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit ".venv real segment → exit 0 (exempt)" 0 "$RC"
+OUT=$(bash "$HOOK" <<<"$(write_json "/repo/.venv-backup/creds.env" "x='$AWS_TOKEN'")" 2>&1); RC=$?
+assert_exit ".venv-backup impostor → exit 2 (scanned)" 2 "$RC"
+
+# ============================ TELEMETRY ====================================
+TEL="$(mktemp -p "$TEST_TMPDIR")"
+SINK="$(make_sink "cat >\"$TEL\"")"
+env HOOK_TELEMETRY_SINK="$SINK" CLAUDE_PROJECT_DIR="/repo" \
+  bash "$HOOK" <<<"$(write_json "/repo/src/config.env" "config = '$AWS_TOKEN'")" >/dev/null 2>&1 || true
+if wait_for_sink "$TEL"; then
+  assert_contains "telemetry: hook id" "$(jq -r '.hook' "$TEL")" "secret-pattern-detection"
+  assert_contains "telemetry: status blocked" "$(jq -r '.status' "$TEL")" "blocked"
+  assert_contains "telemetry: violation label" "$(jq -r '.data.violations[]' "$TEL")" "AWS Access Key"
+  assert_absent "telemetry: no raw token in envelope" "$(cat "$TEL")" "$AWS_TOKEN"
+else
+  bad "telemetry: no envelope written on block"
+fi
+
+# --- Telemetry path redaction (finding P4): absolute path (no project dir) →
+# --- basename only, so no username-bearing path lands in the envelope --------
+H="ho""me"
+ABS_FILE="/${H}/alice/secretproj/config.env"
+TELR="$(mktemp -p "$TEST_TMPDIR")"
+SINKR="$(make_sink "cat >\"$TELR\"")"
+env HOOK_TELEMETRY_SINK="$SINKR" bash "$HOOK" \
+  <<<"$(write_json "$ABS_FILE" "config = '$AWS_TOKEN'")" >/dev/null 2>&1 || true
+if wait_for_sink "$TELR"; then
+  df=$(jq -r '.data.file' "$TELR")
+  assert_contains "redaction: data.file is the basename" "$df" "config.env"
+  assert_absent "redaction: data.file has no path separator" "$df" "/"
+  assert_absent "redaction: envelope drops the username dir" "$(cat "$TELR")" "alice"
+else
+  bad "redaction: no envelope written"
+fi
+
+report
diff --git a/plugins/guardrails/lib/path-detection/hardcoded-path-patterns.sh b/plugins/guardrails/lib/path-detection/hardcoded-path-patterns.sh
new file mode 100644
index 000000000..cb501bae1
--- /dev/null
+++ b/plugins/guardrails/lib/path-detection/hardcoded-path-patterns.sh
@@ -0,0 +1,185 @@
+# shellcheck shell=bash
+# Shared hardcoded-path detection patterns for the hardcoded-path-check hook.
+#
+# This is a library — NOT executable. Pure-function: no env reads, no stdin
+# parsing, no exit calls. Callers handle I/O, exemptions, and exit-code
+# mapping.
+#
+# Cross-platform: detects Windows (C:\Users\, drive letters), macOS
+# (/Users/), and Linux (/home/) hardcoded paths plus machine-specific repo
+# checkout roots. Uses POSIX ERE only (grep -E) — NO grep -P. macOS BSD grep
+# lacks -P entirely. Lookbehinds/lookaheads are replaced by grep -v
+# pipe-stage exclusions.
+
+# Per-OS machine-path regex BODIES — single source of truth shared by this
+# lib's hpp::scan_text and any driver that sources it. Extracting the bodies
+# lets a pattern change land once and reach every scan driver in lockstep.
+#
+# DEFINE single-quoted, EXPAND double-quoted ("$HPP_…"): a double-quoted
+# definition would collapse the escaped-repo body's doubled backslashes and
+# silently change what grep matches. POSIX ERE only. Only the BODIES are
+# shared — each call site keeps its own wrapping (macOS/Linux pipe exclusions
+# here; a boundary prefix in a driver).
+#
+# The 3 Windows bodies match the separator as single-backslash, forward-slash,
+# OR doubled-backslash (JSON-escaped) at EVERY position — (/|\\\\?) is fwd-slash
+# OR one-or-two backslashes — and accept an 8.3 short-name segment that ends
+# ~<digit> (e.g. ALICE~1) via the optional (~[0-9]+). These are the two shapes
+# a script-written temp path evaded with. The negative class still excludes a
+# bare ~ so a tilde-shorthand segment stays clean. macOS/Linux bodies are NOT
+# widened: no 8.3 / escaped-JSON analogue exists there, so widening is pure
+# false-positive risk.
+HPP_WIN_USER_BODY='[A-Za-z]:(/|\\\\?)Users(/|\\\\?)[^/\\$<{~]+(~[0-9]+)?(/|\\\\?)'
+HPP_MACOS_USER_BODY='/Users/[^/$<{~]+/'
+HPP_LINUX_USER_BODY='/home/[^/$<{~]+/'
+HPP_WIN_REPO_BODY='[A-Za-z]:(/|\\\\?)repos(/|\\\\?)[^/\\$<{~]+(~[0-9]+)?(/|\\\\?)'
+# shellcheck disable=SC1003  # literal backslashes in the ERE body, not a quote escape
+HPP_ESCAPED_WIN_REPO_BODY='[A-Za-z]:\\\\repos\\\\[^\\$<{~]+(~[0-9]+)?\\\\'
+
+# hpp::scan_text <content> [project-root] [file-path]
+#
+# Scans <content> for hardcoded machine-specific paths. When [project-root]
+# is non-empty, also matches the absolute repo path in slash, backslash, and
+# double-escaped backslash forms.
+#
+# When [file-path] is non-empty, OS-specific detection blocks are suppressed
+# for files unambiguously scoped to that OS:
+#   Windows context — file ext .ps1/.psm1/.psd1/.cmd/.bat/.reg, OR path
+#     matches */scripts/windows/* or */tests/windows/*, OR filename matches
+#     *-windows.* or *-win32.*  → suppresses Win-user, Win-repo, escaped-
+#     Win-repo blocks
+#   macOS context — */scripts/macos/*, *-macos.*, *-osx.*, *-darwin.*
+#     → suppresses macOS-user block
+#   Linux context — */scripts/linux/*, *-linux.*
+#     → suppresses Linux-user block
+# Cross-OS detections (e.g. /Users/alice/ inside a .ps1) and project-root
+# match (machine-specific repo path) are NEVER suppressed — these are leaks
+# regardless of file context.
+#
+# Output (stdout): violation block(s). Each block:
+#   <label>:
+#   <up to 3 matched "lineno:line" entries>
+#   <blank line>
+#
+# Exit: 0 = clean, 1 = violations found.
+#
+# Callers: capture stdout, then map the return code to whatever exit code
+# their layer expects (a PreToolUse hook blocks via exit 2; a commit hook
+# fails the commit via exit 1).
+hpp::scan_text() {
+  local content="$1" project_root="${2:-}" file_path="${3:-}"
+  local violations="" match
+  local nl=$'\n'
+
+  # ---- Cheap pre-filter gate (perf; behavior-preserving) ----
+  # On clean content (~99% of calls in a large scan) this skips the ~8-10
+  # detailed `grep` pipelines below. The alternation is a strict SUPERSET
+  # of every detailed pattern's invariant literal:
+  #   Users   ⊇ Windows-user + macOS-user  (both forms contain "Users")
+  #   /home/  ⊇ Linux-user
+  #   repos   ⊇ Windows-repo + escaped-Windows-repo
+  # The project-root branch keys on the root's final path segment, which is
+  # present identically in the slash, backslash, and escaped forms. When NONE of
+  # these triggers fire, no detailed pattern below can match, so early-returning
+  # 0 cannot drop a true positive. A false NEGATIVE here = guard bypass, so the
+  # gate must never be TIGHTER than the detailed patterns (a looser gate only
+  # costs a wasted full scan). The gate stays case-sensitive for the OS-path
+  # alternation (matching the detailed patterns' literal "Users") and
+  # case-insensitive for the root segment (matching the detailed `grep -Fi`).
+  # Uses a here-string, NOT `printf | grep -q`: a pipe + `grep -q` early-exit
+  # would SIGPIPE printf, and under `pipefail` the pipeline would report printf's
+  # failure and invert the result.
+  if ! grep -qE 'Users|/home/|repos' <<<"$content" 2>/dev/null; then
+    local gate_root=""
+    if [[ -n "$project_root" ]]; then
+      gate_root="${project_root//\\//}"
+      gate_root="${gate_root%/}"
+      gate_root="${gate_root##*/}"
+    fi
+    if [[ -z "$gate_root" ]] || ! grep -qFi "$gate_root" <<<"$content" 2>/dev/null; then
+      return 0
+    fi
+  fi
+  # ---- end gate (clean content has returned; fall through to full scan) ----
+
+  # Normalize file_path for OS-context matching: backslash→slash, lowercase.
+  # Use tr for the lowercasing pass — bash-3.2-compatible (macOS stock bash
+  # before brew install). This lib may be sourced by commit-time hooks running
+  # under whatever bash a fresh macOS clone has on PATH; staying portable here
+  # avoids commit-time failures.
+  local norm_file="${file_path//\\//}"
+  norm_file=$(printf '%s' "$norm_file" | tr '[:upper:]' '[:lower:]')
+
+  # OS-context flags — non-empty when file is unambiguously OS-scoped
+  local windows_context="" macos_context="" linux_context=""
+  case "$norm_file" in
+    *.ps1 | *.psm1 | *.psd1 | *.cmd | *.bat | *.reg) windows_context=1 ;;
+    */scripts/windows/* | */tests/windows/*) windows_context=1 ;;
+    *-windows.* | *-win32.*) windows_context=1 ;;
+    *) ;;
+  esac
+  case "$norm_file" in
+    */scripts/macos/* | *-macos.* | *-osx.* | *-darwin.*) macos_context=1 ;;
+    *) ;;
+  esac
+  case "$norm_file" in
+    */scripts/linux/* | *-linux.*) linux_context=1 ;;
+    *) ;;
+  esac
+
+  # Windows user home paths: C:\Users\<name>\ or C:/Users/<name>/
+  # Suppressed in Windows context (.ps1 etc). Cross-OS leaks (macOS/Linux
+  # user paths in a .ps1) still fire from their own blocks below.
+  if [[ -z "$windows_context" ]]; then
+    match=$(printf '%s' "$content" | grep -nE "$HPP_WIN_USER_BODY" 2>/dev/null | head -3)
+    [[ -n "$match" ]] && violations="${violations}Windows user path detected:${nl}${match}${nl}${nl}"
+  fi
+
+  # macOS user home paths: /Users/<name>/
+  # Exclusions via pipe (replaces Perl lookbehind/lookahead):
+  #   grep -v '/Users/Shared/'  — legitimate shared directory
+  #   grep -vE '[A-Za-z]:[/\\]' — Windows paths (caught above)
+  if [[ -z "$macos_context" ]]; then
+    match=$(printf '%s' "$content" | grep -nE "$HPP_MACOS_USER_BODY" 2>/dev/null | grep -v '/Users/Shared/' | grep -vE '[A-Za-z]:[/\\]' | head -3)
+    [[ -n "$match" ]] && violations="${violations}macOS user path detected:${nl}${match}${nl}${nl}"
+  fi
+
+  # Linux user home paths
+  if [[ -z "$linux_context" ]]; then
+    match=$(printf '%s' "$content" | grep -nE "$HPP_LINUX_USER_BODY" 2>/dev/null | head -3)
+    [[ -n "$match" ]] && violations="${violations}Linux user path detected:${nl}${match}${nl}${nl}"
+  fi
+
+  # Generic Windows repo checkout roots — suppressed in Windows context.
+  if [[ -z "$windows_context" ]]; then
+    match=$(printf '%s' "$content" | grep -nE "$HPP_WIN_REPO_BODY" 2>/dev/null | head -3)
+    [[ -n "$match" ]] && violations="${violations}Windows repo path detected:${nl}${match}${nl}${nl}"
+
+    match=$(printf '%s' "$content" | grep -nE "$HPP_ESCAPED_WIN_REPO_BODY" 2>/dev/null | head -3)
+    [[ -n "$match" ]] && violations="${violations}Escaped Windows repo path detected:${nl}${match}${nl}${nl}"
+  fi
+
+  # Current repo absolute path in slash/backslash/escaped forms. ALWAYS
+  # runs — machine-specific marker for THIS checkout, never suppressible by
+  # OS context.
+  if [[ -n "$project_root" ]]; then
+    local root_fwd root_bslash root_escaped candidate
+    root_fwd=${project_root//\\//}
+    root_fwd=${root_fwd%/}
+    # Bash expansion — `tr '/' '\\'` mishandles backslashes on Git Bash.
+    root_bslash=${root_fwd//\//\\}
+    root_escaped=${root_bslash//\\/\\\\}
+
+    for candidate in "$root_fwd" "$root_bslash" "$root_escaped"; do
+      [[ -n "$candidate" ]] || continue
+      match=$(printf '%s' "$content" | grep -nFi "$candidate" 2>/dev/null | head -3)
+      [[ -n "$match" ]] && violations="${violations}Machine-specific repo path detected:${nl}${match}${nl}${nl}"
+    done
+  fi
+
+  if [[ -n "$violations" ]]; then
+    printf '%s' "$violations"
+    return 1
+  fi
+  return 0
+}
diff --git a/plugins/guardrails/lib/verification/verify-cli-flag.sh b/plugins/guardrails/lib/verification/verify-cli-flag.sh
new file mode 100755
index 000000000..15e7ac735
--- /dev/null
+++ b/plugins/guardrails/lib/verification/verify-cli-flag.sh
@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# Verify whether a CLI flag exists by parsing `<bin> [<subcmd>...] --help`.
+# Deterministic primitive used by:
+#   - Agents (callable inline before editing scripts that reference CLI flags)
+#   - The cli-flag-verify PostToolUse hook (file-write detection)
+#
+# Usage:
+#   verify-cli-flag.sh [OPTIONS] <bin> [<subcmd>...] --<flag>
+#
+# Options (recognized only BEFORE <bin>; a target flag named --quiet or
+# --verbose is therefore never consumed as a verifier option):
+#   -h, --help        Print usage and exit 0
+#   --quiet           Suppress non-error output
+#   --verbose         Print the matching --help line on success
+#   --                End of verifier options
+#
+# Arguments:
+#   <bin>             Binary name on PATH (e.g. claude, gh, dotnet)
+#   <subcmd>...       Optional subcommand chain (e.g. gh pr create)
+#   --<flag>          The flag to verify (must start with `--`)
+#
+# Exit codes:
+#   0  Flag exists in `<bin> [<subcmd>...] --help` output
+#   1  Flag absent — likely hallucinated
+#   2  Binary missing on PATH OR `<bin> --help` failed (cannot verify)
+#   3  Argument validation error (caller bug)
+#
+# Cross-platform: Git Bash on Windows + Linux + macOS bash 5.x.
+# Caches `--help` output per-binary in $LOCALAPPDATA/guardrails or $XDG_CACHE_HOME/guardrails.
+
+# Omit -e: we explicitly capture exit codes from `<bin> --help` and decide.
+set -uo pipefail
+
+usage() {
+  sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+QUIET=false
+VERBOSE=false
+
+# Verifier options are recognized only at the FRONT of argv; parsing stops at
+# the first positional so a TARGET flag spelled --quiet/--verbose stays a
+# positional and gets verified instead of silently steering the verifier.
+while (($# > 0)); do
+  case "$1" in
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    --quiet)
+      QUIET=true
+      shift
+      ;;
+    --verbose)
+      VERBOSE=true
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    *) break ;;
+  esac
+done
+
+ARGS=("$@")
+
+if ((${#ARGS[@]} < 2)); then
+  echo "verify-cli-flag: error: expected <bin> [<subcmd>...] --<flag>" >&2
+  echo "Run with --help for usage." >&2
+  exit 3
+fi
+
+# Last positional must be a --flag token. Everything before it is bin+subcmds.
+FLAG="${ARGS[-1]}"
+if [[ "$FLAG" != --* ]]; then
+  echo "verify-cli-flag: error: last argument must start with '--' (got '$FLAG')" >&2
+  exit 3
+fi
+
+# Strip trailing =VALUE if present (e.g. --output-format=json).
+FLAG_NAME="${FLAG%%=*}"
+
+unset 'ARGS[-1]'
+BIN="${ARGS[0]}"
+unset 'ARGS[0]'
+# Remaining ARGS are subcommands. Empty array if none.
+SUBCMDS=("${ARGS[@]}")
+
+# Verify binary on PATH.
+if ! command -v "$BIN" >/dev/null 2>&1; then
+  $QUIET || echo "verify-cli-flag: '$BIN' not found on PATH" >&2
+  exit 2
+fi
+
+# Cache directory — derived constants (fixed by env, not flags).
+if [[ -n "${LOCALAPPDATA:-}" ]]; then
+  CACHE_BASE="${LOCALAPPDATA//\\//}/guardrails"
+else
+  CACHE_BASE="${XDG_CACHE_HOME:-$HOME/.cache}/guardrails"
+fi
+CACHE_DIR="$CACHE_BASE/cli-flag-cache"
+mkdir -p "$CACHE_DIR" 2>/dev/null || true
+
+# Cache key: bin + subcmds joined by '__'. Slugify path-unsafe chars to '_'.
+CACHE_KEY="$BIN"
+for s in "${SUBCMDS[@]}"; do
+  CACHE_KEY="${CACHE_KEY}__${s}"
+done
+CACHE_KEY="${CACHE_KEY//[^a-zA-Z0-9_-]/_}"
+CACHE_FILE="$CACHE_DIR/$CACHE_KEY.help"
+
+# Cache hit if file exists, mtime within 24h, non-empty.
+USE_CACHE=false
+if [[ -s "$CACHE_FILE" ]]; then
+  if find "$CACHE_FILE" -mmin -1440 2>/dev/null | grep -q .; then
+    USE_CACHE=true
+  fi
+fi
+
+HELP_OUTPUT=""
+if $USE_CACHE; then
+  HELP_OUTPUT=$(cat "$CACHE_FILE")
+else
+  # Run `<bin> [<subcmds>...] --help` with timeout 5s. 2>&1 catches binaries
+  # that print --help to stderr (e.g. some legacy tools).
+  if command -v timeout >/dev/null 2>&1; then
+    HELP_OUTPUT=$(timeout 5 "$BIN" "${SUBCMDS[@]}" --help 2>&1)
+    HELP_RC=$?
+  else
+    HELP_OUTPUT=$("$BIN" "${SUBCMDS[@]}" --help 2>&1)
+    HELP_RC=$?
+  fi
+  # Some CLIs return non-zero on --help (e.g. busybox tools, malformed args).
+  # Tolerate non-zero IF output is non-empty AND looks like help text.
+  if [[ -z "$HELP_OUTPUT" ]] || ((HELP_RC == 124)); then
+    $QUIET || echo "verify-cli-flag: '$BIN ${SUBCMDS[*]} --help' failed (rc=$HELP_RC, empty/timeout)" >&2
+    exit 2
+  fi
+  # Persist to cache (best-effort).
+  printf '%s' "$HELP_OUTPUT" >"$CACHE_FILE" 2>/dev/null || true
+fi
+
+# Match anchored on word boundaries. The flag may appear as:
+#   `  --flag         description`            (column-aligned)
+#   `  --flag <ARG>   description`            (with metavar)
+#   `  --flag=VALUE`                          (equals form)
+#   `  -F, --flag`                            (with short form)
+#   `  --flag, -F`                            (reverse short form)
+#   `  [--flag]`                              (optional-arg notation)
+#   `  [-S|--save|--save-dev|--save-optional]` (pipe-separated synopsis, e.g. npm)
+#   `--flag` inside a usage line               (rare but valid)
+# Pattern: `--flag` followed by a flag terminator — space, =, comma, `[`, `]`,
+# `|`, `)`, or end-of-line. The trailing class lists `]` first (literal), then
+# the POSIX space class and the remaining literals. The leading
+# `(^|[^a-zA-Z0-9_-])` plus this trailing terminator prevent a prefix false
+# match (e.g. searching `--save-dev` must not match `--save-developer`).
+FLAG_PATTERN="(^|[^a-zA-Z0-9_-])${FLAG_NAME}([][:space:]=,|)[]|\$)"
+if grep -E "$FLAG_PATTERN" <<<"$HELP_OUTPUT" >/dev/null; then
+  if $VERBOSE; then
+    grep -nE "$FLAG_PATTERN" <<<"$HELP_OUTPUT" | head -1
+  fi
+  exit 0
+fi
+
+$QUIET || echo "verify-cli-flag: '$FLAG_NAME' not found in '$BIN ${SUBCMDS[*]} --help' output" >&2
+exit 1