diff --git a/.claude/hooks/check-affected-pre-push.test.sh b/.claude/hooks/check-affected-pre-push.test.sh
index f653de3124..19ba2a9135 100755
--- a/.claude/hooks/check-affected-pre-push.test.sh
+++ b/.claude/hooks/check-affected-pre-push.test.sh
@@ -309,6 +309,7 @@ cp "$tmp/stub" "$lh/scripts/check-affected.sh"
 cp "$hook" "$lh/.claude/hooks/"
 cp "$repo_root/lib/hook-utils.sh" "$lh/lib/"
 cp "$repo_root/lefthook.yml" "$lh/"
+cp -R "$repo_root/.githooks" "$lh/"
 git_test_config "$lh" add -A
 git_test_config "$lh" commit -q -m base
 git_test_config "$lh" update-ref refs/remotes/origin/main HEAD
diff --git a/.claude/source-control.md b/.claude/source-control.md
index ca47cad92b..13e05da70c 100644
--- a/.claude/source-control.md
+++ b/.claude/source-control.md
@@ -5,8 +5,9 @@ Commit-subject / PR-title convention for the source-control plugin, resolved by
 CLAUDE.md/rules/commit-msg hook or fall back to the bundled Conventional Commits default.
 Re-run `/source-control:setup` to change these values.
 
-Of the convention keys, only `pr_body_required_sections` is set here. Every other one falls
-through to `/source-control:setup`'s inference (this repo's commit history is already
+Of the convention keys, only `pr_body_required_sections` and `subject_pattern` are set here;
+the guardrails `commit-msg` job in `lefthook.yml` enforces `subject_pattern`. Every other key
+falls through to `/source-control:setup`'s inference (this repo's commit history is already
 Conventional-Commits-shaped) per config-resolution.md's per-key fallthrough, so this file
 deliberately does not restate them. The `babysit_loop_*` keys below are the other key family this
 file carries, and they are set explicitly.
@@ -45,3 +46,7 @@ c2-mechanical
 ## babysit_loop_grace_window_minutes
 
 30
+
+## subject_pattern
+
+^((build|chore|ci|docs|feat|fix|perf|refactor|revert|security|style|test)(\(.+\))?!?: .+|Merge .+|Revert ".+)
diff --git a/.githooks/guardrails/abort-boundary.sh b/.githooks/guardrails/abort-boundary.sh
new file mode 100644
index 0000000000..bf980737eb
--- /dev/null
+++ b/.githooks/guardrails/abort-boundary.sh
@@ -0,0 +1,255 @@
+# shellcheck shell=bash
+# Abort boundary for the guardrails hooks (#3528). Sourced by every registered
+# hook and by the dispatcher; never executed on its own.
+#
+# A hook has three outcomes, not two: allow (exit 0), block (exit 2, reason on
+# stderr), and could-not-run. Before this file the third had no signal. A hook
+# that died between its first line and its own final `exit` (an unbound
+# variable under `set -u`, a helper that no longer exists, a `source` that
+# failed) ended with whatever status the last command had, usually 1, and wrote
+# nothing of its own. That status is not a block, so the tool call went ahead;
+# bash's one-line error went to the debug log, and the transcript recorded
+# "exit 1, stderr: (none)". How Claude Code treats each exit status is the
+# hooks page's to state; our hooks.json rows set no failure-handling field, so
+# they take its default. Pointer:
+# https://code.claude.com/docs/en/hooks#exit-code-output. As of: 2026-10-11.
+# Recheck trigger: that section changes what a status other than 0 or 2 does
+# to the tool call, or is renamed. A blocking
+# guard enforced nothing and nobody was told. The boundary makes that outcome a
+# deliberate one:
+#
+#   source "$_HOOK_SELF/abort-boundary.sh"
+#   guard::abort_boundary <hook-name> <HookEventName> <open|closed> <chosen-status>...
+#
+# installs an EXIT trap that passes every CHOSEN status through untouched (the
+# hook's own `exit 0` / `exit 2`, including the ones the shared helpers make on
+# its behalf: hook::check_enabled, hook::require jq, hook::require_jq_blocking)
+# and treats any other status as "the guard did not run". For those it writes
+# one line naming the hook and the status to stderr, and then applies the
+# hook's declared posture:
+#
+#   open    exit 0, after emitting the same text as a `systemMessage` on
+#           stdout, for the user (stderr on exit 0 reaches only the debug log,
+#           see docs/conventions/hook-observability/). The tool call proceeds,
+#           as it did before, and the notice says it was not checked. The
+#           model gets nothing: it cannot fix a hook.
+#   closed  exit 2 with the notice on stderr, the channel a blocking exit feeds
+#           back to the agent. The tool call is denied.
+#
+# <HookEventName> is the event the hook is registered for (PreToolUse,
+# PostToolUse), kept in _GAB_EVENT for the dispatcher's telemetry. Pass an empty
+# string when the event is not known at install time (the dispatcher serves
+# both).
+#
+# Why a trap and not `set -e`: errexit across the hook set would change
+# behavior on every non-zero status a guard tests on purpose. The trap sees
+# only the status the process actually terminates with.
+#
+# Handler discipline. `trap - EXIT` is the handler's first action so nothing it
+# does can re-enter it. It uses builtins only, every variable it reads is set
+# at install time, and it calls nothing from hook-utils.sh, because a failed
+# `source hook-utils.sh` is one of the aborts it exists to report. A failure
+# inside the handler ends the process once, with that failure's status, after
+# the stderr line is already written.
+#
+# One EXIT trap per shell. Bash holds a single EXIT trap, so a hook that runs
+# its own `trap ... EXIT` (or `trap - EXIT`) after the install line REPLACES
+# this boundary and is back to the silent abort it exists to remove, with
+# nothing at run time to say so. abort-boundary.test.sh fails on any `trap`
+# naming EXIT in a registered hook or in a library it sources; this file is the
+# only one allowed to touch it. No hook needs exit-time work today (each is
+# builtins plus one jq read, nothing to clean up). The supported way for one
+# that does is to chain through this library, not around it: fill the chain slot
+# below (_GAB_CONTINUE) that guard::_abort_on_exit calls before it decides, the
+# chained function under the same handler discipline (builtins only, never
+# exits, never touches the trap), with a suite case beside the others, in the
+# same change. A release on purpose goes through guard::abort_boundary_release.
+#
+# run-guards.sh is the one documented exception to that discipline, and it is
+# an exception because it is not a hook's exit-time work: its
+# run_guards::guard_died is the DISPATCHER settling a dead guard and then
+# finishing the run the process still owes, so it runs the guards left in
+# another process, spawns jq to merge their documents, and ends at `builtin exit`
+# without returning. Nothing is left for the handler to decide, which is why
+# the slot may swallow control here and nowhere else. Any other consumer keeps
+# the discipline above: a chained function that RETURNS, so that
+# guard::_abort_on_exit still settles the status and exits.
+#
+# Under run-guards.sh the guards are sourced into the dispatcher's own shell,
+# and `exit` there is a function of the dispatcher's. A guard that ends through
+# it, or by falling off its end, never reaches this trap: the dispatcher applies
+# guard::_abort_settle to the status itself and merges the notice document with
+# the other guards' output. The trap fires only for a guard that dies of a hard
+# error, when the shell is exiting, and then hands the status to the chain slot
+# below (_GAB_CONTINUE), which the dispatcher fills for the span of its guards.
+
+[[ -n "${_GUARDRAILS_ABORT_BOUNDARY_LOADED:-}" ]] && return 0
+readonly _GUARDRAILS_ABORT_BOUNDARY_LOADED=1
+
+_GAB_NAME=""
+_GAB_EVENT=""
+_GAB_POSTURE="open"
+_GAB_CHOSEN=" "
+
+# guard::say_once <key> <line>: write <line> to stderr unless this process
+# already wrote <key>. Under run-guards.sh the guards share one shell, so a
+# refusal several of them make on one call reaches the deny reason once.
+_GUARD_SAID=" "
+guard::say_once() {
+  [[ "$_GUARD_SAID" == *" $1 "* ]] && return 0
+  _GUARD_SAID+="$1 "
+  printf '%s\n' "$2" >&2
+}
+
+# Refusals several guards share. The caller exits 2.
+guard::refuse_nul() {
+  guard::say_once nul "BLOCKED: the payload carries a NUL byte. Reissue the call without it."
+}
+guard::refuse_unparsable() {
+  guard::say_once unparsable "BLOCKED: the hook payload could not be parsed."
+}
+# The git guards that walk alias chains (hook::git_alias_admit).
+# shellcheck disable=SC2154  # HOOK_ALIAS_WORK_MAX is hook-utils.sh's, loaded by every caller
+guard::refuse_alias_chain() {
+  guard::say_once alias-chain "BLOCKED: checking this git alias chain needs over $HOOK_ALIAS_WORK_MAX re-expansions. Run the subcommand directly."
+}
+# guard::alias_depth_max: set HOOK_ALIAS_DEPTH_MAX, the deepest alias re-expansion
+# the git guards walk. The work budget bounds time, not stack: bash runs each
+# nested check_segment on the C stack, and a walk under 128 analyses still
+# crashed the process (SIGSEGV, exit 139, which Claude Code lets through) on a
+# 512 KB stack. A level costs up to ~9 KB measured under the dispatcher (a
+# 512 KB stack survives 50 hops and not 60), so the cap is 20 KB a level, which
+# leaves headroom for the heavier `!` shell-alias levels. The stack comes from
+# /proc with builtins, because `$(ulimit -s)` forks and these guards run on every
+# Bash call. No /proc (macOS, Git Bash) or an unlimited stack gives 25, what a
+# 512 KB stack yields, and no stack gives more than 409 (8 MiB). For tests only,
+# GUARDRAILS_PROC_LIMITS names a second limits file and GUARDRAILS_ALIAS_DEPTH_MAX
+# a number; each can only lower the cap, since the result is the minimum of every
+# value read and a missing or unparsable file reads as 25.
+guard::alias_depth_max() {
+  local file line cap
+  HOOK_ALIAS_DEPTH_MAX=
+  for file in /proc/self/limits ${GUARDRAILS_PROC_LIMITS:+"$GUARDRAILS_PROC_LIMITS"}; do
+    cap=25
+    if [[ -r "$file" ]]; then
+      while IFS= read -r line; do
+        if [[ "$line" =~ ^Max\ stack\ size[[:space:]]+([0-9]+)[[:space:]] ]]; then
+          cap=$((10#${BASH_REMATCH[1]} / 1024 / 20))
+          break
+        fi
+      done <"$file"
+    fi
+    ((cap <= 409)) || cap=409
+    [[ -n "$HOOK_ALIAS_DEPTH_MAX" ]] && ((cap >= HOOK_ALIAS_DEPTH_MAX)) || HOOK_ALIAS_DEPTH_MAX=$cap
+  done
+  if [[ "${GUARDRAILS_ALIAS_DEPTH_MAX-}" =~ ^[0-9]+$ ]] && ((10#$GUARDRAILS_ALIAS_DEPTH_MAX < HOOK_ALIAS_DEPTH_MAX)); then
+    HOOK_ALIAS_DEPTH_MAX=$((10#$GUARDRAILS_ALIAS_DEPTH_MAX))
+  fi
+}
+guard::refuse_config_env_alias() { # <alias>
+  guard::say_once "config-env-$1" "BLOCKED: git alias '$1' is defined via --config-env, so its expansion cannot be checked. Define it in git config or run the subcommand directly."
+}
+
+# guard::bad_switch_notice <option> <value> <input>: a strict kill switch that
+# is neither true nor false keeps its guard on. The user is told once per
+# session; the model cannot change a plugin option. Needs hook-utils.sh.
+# shellcheck disable=SC2154  # HOOK_NOTICE_TO_USER is set by hook::notice_once
+guard::bad_switch_notice() {
+  hook::notice_once "guardrails-bad-switch-$1" "$3" || return 0
+  [[ "$HOOK_NOTICE_TO_USER" == 1 ]] || return 0
+  hook::emit_channels PreToolUse "" "guardrails: $1=$2 is not true or false, so the guard stays on. Fix it in /plugin configure."
+}
+
+# guard::abort_boundary <hook-name> <HookEventName|""> <open|closed> <status>...
+guard::abort_boundary() {
+  _GAB_NAME="$1"
+  _GAB_EVENT="$2"
+  case "$3" in
+  open | closed) _GAB_POSTURE="$3" ;;
+  *)
+    # A posture that is neither word is a defect in the hook's own prologue.
+    # Say so and keep the status quo enforcement (fail-open) rather than
+    # inventing a block the hook never declared.
+    printf 'guardrails %s: abort boundary posture %q is not open or closed; using open\n' "$1" "$3" >&2
+    _GAB_POSTURE="open"
+    ;;
+  esac
+  shift 3
+  _GAB_CHOSEN=" $* "
+  trap guard::_abort_on_exit EXIT
+}
+
+# guard::abort_boundary_release: uninstall the trap. For a process whose final
+# status is computed rather than written as a literal (the dispatcher's
+# aggregated exit): release right before that deliberate `exit`, so a status
+# reached on purpose is never reported as an abort.
+guard::abort_boundary_release() {
+  trap - EXIT
+}
+
+# JSON-escape $2 into the variable named by $1: backslash, double quote, and the
+# three line-structure control bytes. The notice text is built from install-time
+# literals and a status number, so nothing else can occur in it; the escape is
+# here so a hook name or event containing a quote cannot break the document.
+guard::_abort_json_escape_to() {
+  local __gab_s="$2"
+  __gab_s="${__gab_s//\\/\\\\}"
+  __gab_s="${__gab_s//\"/\\\"}"
+  __gab_s="${__gab_s//$'\n'/\\n}"
+  __gab_s="${__gab_s//$'\r'/\\r}"
+  __gab_s="${__gab_s//$'\t'/\\t}"
+  printf -v "$1" '%s' "$__gab_s"
+}
+
+# The chain slot. run-guards.sh runs its guards inside its own process, so a
+# guard that dies of a hard error takes the dispatcher's shell down with it
+# and this handler is what runs. With a function name here the handler hands
+# that guard's status to it instead of deciding the process's fate itself; the
+# dispatcher settles the guard's boundary, runs the guards still owed, and
+# exits on the aggregate. run-guards.sh is the one consumer that does not
+# return from here, and the header above says why it may; a chained function
+# that DOES return hands control back and the handler settles the status as
+# documented there. Empty (every guard run alone), the handler decides as
+# documented above.
+_GAB_CONTINUE=""
+
+guard::_abort_on_exit() {
+  local rc=$?
+  trap - EXIT
+  if [[ -n "$_GAB_CONTINUE" ]]; then
+    "$_GAB_CONTINUE" "$rc"
+  fi
+  guard::_abort_settle "$rc" && return 0
+  [[ -n "$_GAB_DOC" ]] && printf '%s\n' "$_GAB_DOC"
+  exit "$_GAB_RC"
+}
+
+# guard::_abort_settle <status>: the decision, apart from the exit. Returns 0
+# when <status> is one the hook chose, and nothing else happens. Otherwise
+# writes the notice line to stderr, leaves the stdout document (empty for the
+# closed posture) in _GAB_DOC and the status the posture maps to in _GAB_RC,
+# and returns 1. The trap handler above exits on those; run-guards.sh, which
+# runs each guard in its own process, records them for that guard and carries
+# on with the next.
+_GAB_DOC=""
+_GAB_RC=0
+guard::_abort_settle() {
+  local rc="$1"
+  _GAB_DOC=""
+  _GAB_RC=0
+  [[ "$_GAB_CHOSEN" == *" $rc "* ]] && return 0
+  local msg
+  if [[ "$_GAB_POSTURE" == closed ]]; then
+    msg="guardrails ${_GAB_NAME}: guard did not run (internal error, rc=${rc}); fail-closed: this tool call is denied because the guard could not check it. The failing line is on the hook's stderr."
+    printf '%s\n' "$msg" >&2
+    _GAB_RC=2
+    return 1
+  fi
+  # User channel only: nothing was blocked, and the model cannot fix a hook.
+  msg="guardrails ${_GAB_NAME}: guard did not run (internal error, rc=${rc}); this call was not checked. Details: claude --debug."
+  printf '%s\n' "$msg" >&2
+  local esc
+  guard::_abort_json_escape_to esc "$msg"
+  _GAB_DOC='{"systemMessage":"'"$esc"'"}'
+  return 1
+}
diff --git a/.githooks/guardrails/check-lib.sh b/.githooks/guardrails/check-lib.sh
new file mode 100755
index 0000000000..1388a69d9a
--- /dev/null
+++ b/.githooks/guardrails/check-lib.sh
@@ -0,0 +1,394 @@
+#!/usr/bin/env bash
+# GENERATED from lib/git-hooks/check-lib.sh by scripts/sync-shared-copies.sh. Do not edit this copy:
+# edit the canonical source, then rerun the script.
+# Shared helpers for git-hook check scripts: the file set, the changed lines,
+# the push range, the missing-tool skip key and agent detection. A check script
+# sources this file from its own directory and runs under bash, never under sh.
+# The contract is the check-placement convention's check-script runtime table.
+#
+# Names are POSIX-safe (checks_files, not checks::files) and the syntax stays
+# within bash 3.2, which is what macOS ships: no associative arrays, no
+# mapfile, no ${var,,}. Every git call that can legitimately fail (an unset
+# config key, a missing ref) is guarded, so the helpers also hold under set -e.
+#
+#   checks_init <event> "$@"   set CHECKS_MODE (pre-commit, pre-push or, with
+#                              --worktree, worktree), CHECKS_EVENT, CHECKS_TMP,
+#                              and cd to the top level; returns 1 outside a repo
+#   checks_files               NUL-separated paths to check, repo-relative
+#   checks_changed_lines       write "<path><TAB><start><TAB><end>" ranges of
+#                              added lines to $CHECKS_TMP/ranges, none for a
+#                              file whose content is binary
+#   checks_file_text [--tip <sha>] <p> [<rev>]
+#                              <p> as the change holds it, on stdout: the
+#                              tip's blob (in pre-push with no tip, the tip of
+#                              the range <p> changed in), else the work tree in
+#                              worktree mode, else the index; returns 1,
+#                              printing nothing, when <p> is not a regular
+#                              file there (deleted, symlink, submodule)
+#   checks_regular_file [--tip <sha>] <p> [<rev>]
+#                              0 when <p> is a regular file in that place;
+#                              --tip names the tip when two pushed ranges
+#                              change the same path
+#   checks_has_nul <p> [<rev>] 0 when that content's first 8000 bytes hold a NUL
+#   checks_filter_findings     stdin "<path>:<line>: <message>" lines; prints
+#                              those inside a changed range
+#   checks_partly_staged <p>   0 when <p> has unstaged changes too
+#   checks_refuse_partly_staged
+#                              a rewriting check calls this first: prints the
+#                              contract line per partly staged path, returns 1
+#   checks_refuse_config_drift [--if <fn>] <name>... -- <path>...
+#                              pre-commit: prints the contract line per config
+#                              governing a <path> whose work tree differs from
+#                              the index, returns 1
+#   checks_require_tool <tool> <install>
+#                              returns 0 when the tool is on PATH, else exits
+#                              the script with the contract's missing-tool rule
+#   checks_is_agent            0 when an agent runs the hook
+#   checks_skip_listed <tool>  0 when checks.skipmissing names the tool
+#   checks_push_ranges         pre-push: "<base> <local>" per pushed ref
+
+CHECKS_EMPTY_TREE=4b825dc642cb6eb9a060e54bf8d69288fbee4904
+
+checks_init() {
+  CHECKS_EVENT="$1"
+  shift
+  CHECKS_MODE="$CHECKS_EVENT"
+  CHECKS_ARGS=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+    --worktree) CHECKS_MODE=worktree ;;
+    *) CHECKS_ARGS="${CHECKS_ARGS:+$CHECKS_ARGS }$1" ;;
+    esac
+    shift
+  done
+  local top
+  top="$(git rev-parse --show-toplevel 2>/dev/null)" || return 1
+  cd "$top" || return 1
+  CHECKS_TMP="$(mktemp -d "${TMPDIR:-/tmp}/checks.XXXXXX")" || return 1
+  # shellcheck disable=SC2064 # expand now: the path is fixed at init
+  trap "rm -rf '$CHECKS_TMP'" EXIT
+  if [[ "$CHECKS_MODE" == pre-push ]]; then
+    checks_push_ranges >"$CHECKS_TMP/push-ranges"
+  fi
+  return 0
+}
+
+checks_is_agent() {
+  [[ "${CLAUDECODE:-}" == 1 || -n "${AI_AGENT:-}" ]]
+}
+
+# git config --get exits 1 for an unset key; that is an empty list, not an error.
+checks_skip_listed() {
+  local list item
+  list="$(git config --get checks.skipmissing 2>/dev/null || true)"
+  [[ -n "$list" ]] || return 1
+  local IFS=,
+  for item in $list; do
+    item="${item#"${item%%[![:space:]]*}"}"
+    item="${item%"${item##*[![:space:]]}"}"
+    [[ "$item" == "$1" ]] && return 0
+  done
+  return 1
+}
+
+checks_git_verb() {
+  case "$CHECKS_EVENT" in
+  pre-push) printf 'push' ;;
+  *) printf 'commit' ;;
+  esac
+}
+
+checks_require_tool() {
+  local tool="$1" install="$2" verb
+  command -v "$tool" >/dev/null 2>&1 && return 0
+  if checks_skip_listed "$tool"; then
+    printf 'SKIPPED: %s (missing)\n' "$tool" >&2
+    exit 0
+  fi
+  verb="$(checks_git_verb)"
+  if checks_is_agent; then
+    printf 'FAIL: %s missing. Install: %s\n' "$tool" "$install" >&2
+    printf 'To skip only while %s is missing: git -c checks.skipmissing=%s %s ...\n' "$tool" "$tool" "$verb" >&2
+    exit 1
+  fi
+  printf 'NOTICE: %s missing, so this check did not run. Install: %s\n' "$tool" "$install" >&2
+  exit 0
+}
+
+# The default branch of <remote>: <remote>/HEAD when it resolves, else the
+# remote's own symref from ls-remote when that branch is fetched here. Prints
+# nothing when neither resolves.
+checks_remote_head() {
+  local remote="$1" ref line
+  ref="$(git rev-parse --verify --quiet "refs/remotes/$remote/HEAD" 2>/dev/null || true)"
+  if [[ -n "$ref" ]]; then
+    printf '%s' "$ref"
+    return 0
+  fi
+  line="$(git ls-remote --symref "$remote" HEAD 2>/dev/null | sed -n 's#^ref: refs/heads/\([^[:space:]]*\)[[:space:]]*HEAD$#\1#p' || true)"
+  [[ -n "$line" ]] || return 0
+  git rev-parse --verify --quiet "refs/remotes/$remote/$line" 2>/dev/null || true
+}
+
+# Reads git's pre-push stdin. A deletion (all-zero local sha) is skipped; a new
+# branch (all-zero remote sha) starts at its merge-base with the remote's
+# default branch, and is skipped with a notice when that cannot be found. With
+# no stdin at all (a hook manager that kept it from this script), the current
+# branch against its upstream is the range.
+checks_push_ranges() {
+  # An all-zero id of any width: 40 hex digits under SHA-1, 64 under SHA-256.
+  local remote="${CHECKS_ARGS%% *}" zero='^0+$'
+  local lref lsha rsha head base seen=0
+  [[ -n "$remote" ]] || remote=origin
+  while read -r lref lsha _ rsha; do
+    [[ -n "$lsha" ]] || continue
+    seen=1
+    [[ "$lsha" =~ $zero ]] && continue
+    if ! [[ "$rsha" =~ $zero ]]; then
+      printf '%s %s\n' "$rsha" "$lsha"
+      continue
+    fi
+    head="$(checks_remote_head "$remote")"
+    base=""
+    [[ -z "$head" ]] || base="$(git merge-base "$lsha" "$head" 2>/dev/null || true)"
+    if [[ -z "$base" ]]; then
+      printf 'NOTICE: no default branch found for %s, so %s was not checked.\n' "$remote" "$lref" >&2
+      continue
+    fi
+    printf '%s %s\n' "$base" "$lsha"
+  done
+  ((seen)) && return 0
+  base="$(git rev-parse --verify --quiet '@{upstream}' 2>/dev/null || true)"
+  [[ -n "$base" ]] && printf '%s %s\n' "$base" "$(git rev-parse HEAD)"
+  return 0
+}
+
+# checks_diff <git diff options...>: the diff for the current mode.
+# core.quotePath=false keeps non-ASCII names unquoted.
+checks_diff() {
+  case "$CHECKS_MODE" in
+  pre-commit) git -c core.quotePath=false diff --cached --no-color --no-ext-diff "$@" ;;
+  worktree)
+    local base=HEAD
+    git rev-parse --verify --quiet HEAD >/dev/null 2>&1 || base="$CHECKS_EMPTY_TREE"
+    git -c core.quotePath=false diff "$base" --no-color --no-ext-diff "$@"
+    ;;
+  pre-push)
+    local b l
+    while read -r b l; do
+      git -c core.quotePath=false diff "$b" "$l" --no-color --no-ext-diff "$@"
+    done <"$CHECKS_TMP/push-ranges"
+    ;;
+  *) return 1 ;;
+  esac
+}
+
+# checks_range_tip <path>: pre-push; prints the tip of the first pushed range
+# whose base-to-tip diff touches <path>, so a path is read from its own ref.
+checks_range_tip() {
+  local b l
+  while read -r b l; do
+    git diff --quiet "$b" "$l" -- ":(literal)$1" 2>/dev/null && continue
+    printf '%s' "$l"
+    return 0
+  done <"$CHECKS_TMP/push-ranges"
+  return 1
+}
+
+# checks_tip_arg: the shared "[--tip <sha>] <path> [<rev>]" parse; sets tip
+# and path. <rev> is the older spelling of --tip.
+checks_tip_arg() {
+  tip=""
+  if [[ "${1:-}" == --tip ]]; then
+    tip="$2"
+    shift 2
+  fi
+  path="$1"
+  [[ -n "$tip" ]] || tip="${2:-}"
+}
+
+# checks_regular_file [--tip <sha>] <path> [<rev>]: a regular file, not a
+# symlink or a submodule entry, where checks_file_text reads it: the tip's
+# tree, else the work tree in worktree mode, else the index. In pre-push with
+# no tip, the tip of the range that changed <path>, never the work tree.
+checks_regular_file() {
+  local tip path entry
+  checks_tip_arg "$@"
+  if [[ -z "$tip" ]]; then
+    case "$CHECKS_MODE" in
+    worktree)
+      [[ -f "$path" && ! -L "$path" ]]
+      return
+      ;;
+    pre-push) tip="$(checks_range_tip "$path")" || return 1 ;;
+    *)
+      entry="$(git ls-files -s -z -- ":(literal)$path" 2>/dev/null | tr -d '\0')"
+      [[ "$entry" == 100* && "${entry#*$'\t'}" == "$path" ]]
+      return
+      ;;
+    esac
+  fi
+  entry="$(git ls-tree -z "$tip" -- "$path" 2>/dev/null | tr -d '\0')"
+  [[ "$entry" == 100* && "${entry#*$'\t'}" == "$path" ]]
+}
+
+# checks_file_text [--tip <sha>] <path> [<rev>]: the content a check judges,
+# from the place checks_regular_file looks. A path that is not a regular file
+# there returns 1 with no output, so it is never judged as an empty file.
+checks_file_text() {
+  local tip path
+  checks_tip_arg "$@"
+  if [[ -z "$tip" && "$CHECKS_MODE" == pre-push ]]; then
+    tip="$(checks_range_tip "$path")" || return 1
+  fi
+  checks_regular_file --tip "$tip" "$path" || return 1
+  if [[ -n "$tip" ]]; then
+    git show "$tip:$path" 2>/dev/null
+  elif [[ "$CHECKS_MODE" == worktree ]]; then
+    cat -- "$path"
+  else
+    git show ":$path" 2>/dev/null
+  fi
+}
+
+checks_files() {
+  checks_diff --name-only --diff-filter=ACMR -z
+  if [[ "$CHECKS_MODE" == worktree ]]; then
+    git ls-files --others --exclude-standard -z
+  fi
+}
+
+# Hunk headers read "@@ -a[,b] +c[,d] @@"; d defaults to 1 and d=0 adds
+# nothing. Paths come from "+++ b/<path>", where git appends a tab to a name
+# holding a space; a name git still quotes is skipped.
+#
+# --text keeps a `-diff` attribute from hiding a text file's hunks, so a file
+# is dropped here instead when the content the change holds is binary
+# (checks_has_nul): no caller then sees ranges for it.
+checks_changed_lines() {
+  local out="$CHECKS_TMP/ranges" raw="$CHECKS_TMP/ranges.raw"
+  : >"$raw"
+  checks_diff -U0 --text --diff-filter=ACMR --src-prefix=a/ --dst-prefix=b/ 2>/dev/null |
+    awk '
+      /^\+\+\+ / { path = substr($0, 5); sub(/\t$/, "", path); if (path ~ /^b\//) path = substr(path, 3); else path = ""; next }
+      /^@@ / && path != "" {
+        split($3, n, ",")
+        start = substr(n[1], 2) + 0
+        count = (n[2] == "") ? 1 : n[2] + 0
+        if (count > 0) printf "%s\t%d\t%d\n", path, start, start + count - 1
+      }' >>"$raw"
+  if [[ "$CHECKS_MODE" == worktree ]]; then
+    local f
+    while IFS= read -r -d '' f; do
+      printf '%s\t1\t2147483647\n' "$f" >>"$raw"
+    done < <(git ls-files --others --exclude-standard -z)
+  fi
+  local p s e prev="" bin=0
+  : >"$out"
+  while IFS=$'\t' read -r p s e; do
+    if [[ "$p" != "$prev" ]]; then
+      prev="$p"
+      bin=0
+      checks_change_has_nul "$p" && bin=1
+    fi
+    ((bin)) || printf '%s\t%s\t%s\n' "$p" "$s" "$e" >>"$out"
+  done <"$raw"
+}
+
+# checks_has_nul <path> [<rev>]: 0 when the first 8000 bytes of
+# checks_file_text hold a NUL, the binary test git itself applies. The bytes
+# decide, never a `-diff` attribute. Builtins only: a check may run with a
+# PATH that holds little beyond git. read stops at the first NUL, so fewer
+# than 8000 bytes read without reaching the end means one was found.
+checks_has_nul() {
+  local LC_ALL=C chunk
+  IFS= read -r -d '' -n 8000 chunk < <(checks_file_text "$1" "${2:-}") && ((${#chunk} < 8000))
+}
+
+# checks_change_has_nul <path>: checks_has_nul against what is checked; on
+# pre-push, each pushed commit that holds <path>.
+checks_change_has_nul() {
+  [[ "$CHECKS_MODE" == pre-push ]] || {
+    checks_has_nul "$1"
+    return
+  }
+  local b l
+  while read -r b l; do
+    checks_has_nul "$1" "$l" && return 0
+  done <"$CHECKS_TMP/push-ranges"
+  return 1
+}
+
+checks_filter_findings() {
+  awk -v ranges="$CHECKS_TMP/ranges" '
+    BEGIN { while ((getline l < ranges) > 0) { split(l, r, "\t"); n++; p[n] = r[1]; s[n] = r[2] + 0; e[n] = r[3] + 0 } }
+    {
+      if (!match($0, /:[0-9]+: /)) next
+      path = substr($0, 1, RSTART - 1)
+      line = substr($0, RSTART + 1, RLENGTH - 3) + 0
+      for (i = 1; i <= n; i++) if (p[i] == path && line >= s[i] && line <= e[i]) { print; break }
+    }'
+}
+
+# checks_refuse_partly_staged: a rewriting check calls this before it rewrites.
+# Each staged path that also has unstaged changes gets the contract line on
+# stderr; returns 1 when any did, since re-staging a rewrite would stage the
+# unstaged hunks too.
+checks_refuse_partly_staged() {
+  local f refused=0
+  while IFS= read -r -d '' f; do
+    if checks_partly_staged "$f"; then
+      printf '%s: partly staged; format it or stage it fully, then commit\n' "$f" >&2
+      refused=1
+    fi
+  done < <(checks_files)
+  return "$refused"
+}
+
+checks_partly_staged() {
+  [[ "$CHECKS_MODE" == pre-commit ]] || return 1
+  if [[ ! -f "$CHECKS_TMP/unstaged" ]]; then
+    git diff --name-only --no-color -z >"$CHECKS_TMP/unstaged" 2>/dev/null || : >"$CHECKS_TMP/unstaged"
+  fi
+  local f
+  while IFS= read -r -d '' f; do
+    [[ "$f" == "$1" ]] && return 0
+  done <"$CHECKS_TMP/unstaged"
+  return 1
+}
+
+# checks_refuse_config_drift [--if <fn>] <name>... -- <path>...: pre-commit
+# only. A check reads its config from the work tree but the commit holds the
+# index, so each config file called <name> in a <path>'s directory or above it
+# that the index holds and the work tree changes or deletes gets the contract
+# line on stderr; returns 1 when any did. An untracked config is not drift: it
+# is the repository's config being set up. With --if, a drifted file counts only
+# when <fn> <file> returns 0.
+checks_refuse_config_drift() {
+  [[ "$CHECKS_MODE" == pre-commit ]] || return 0
+  local filter=""
+  if [[ "${1:-}" == --if ]]; then
+    filter="$2"
+    shift 2
+  fi
+  local -a specs=()
+  while [[ $# -gt 0 && "$1" != -- ]]; do
+    specs+=(":(glob)**/$1")
+    shift
+  done
+  shift
+  local c dir f refused=0
+  while IFS= read -r -d '' c; do
+    [[ -z "$filter" ]] || "$filter" "$c" || continue
+    dir="${c%/*}"
+    [[ "$dir" == "$c" ]] && dir=.
+    for f in "$@"; do
+      if [[ "$dir" == . || "$f" == "$dir"/* ]]; then
+        printf '%s: config differs between the index and the work tree; stage it or restore it, then commit\n' "$c" >&2
+        refused=1
+        break
+      fi
+    done
+  done < <(git diff --name-only --no-color -z -- "${specs[@]}" 2>/dev/null)
+  return "$refused"
+}
diff --git a/.githooks/guardrails/cli-flag-cache.sh b/.githooks/guardrails/cli-flag-cache.sh
new file mode 100644
index 0000000000..cb40f328d8
--- /dev/null
+++ b/.githooks/guardrails/cli-flag-cache.sh
@@ -0,0 +1,69 @@
+# shellcheck shell=bash
+# Shared by lib/verification/verify-cli-flag.sh and hooks/cli-flag-verify.sh:
+# where the `--help` cache lives, how a cache key is spelled, how long an entry
+# stays fresh, and the pattern that decides whether a flag appears in a help
+# text. Defined ONCE, because the hook answers cache hits in its own process
+# and the verifier answers misses in its own, and two hand-copied definitions
+# drifted apart on the first review of that split (a `[` fell out of one
+# terminator class, so `--flag[=VALUE]` was known cold and unknown warm).
+#
+# Sourced, never executed (no shebang, like every other sourced library here).
+# Every function assigns into a caller-named variable (`printf -v`) rather
+# than printing, so no caller pays a command substitution, which is a fork on
+# Windows Git Bash.
+
+# Freshness window for a cached `--help`, in minutes (24 h). Read by both
+# sourcing scripts, which is why shellcheck sees no use here.
+# shellcheck disable=SC2034
+CFV_CACHE_WINDOW_MIN=1440
+
+# cfv_cache_dir_to <var>: the cache directory for this host, forward slashes.
+cfv_cache_dir_to() {
+  if [[ -n "${LOCALAPPDATA:-}" ]]; then
+    printf -v "$1" '%s' "${LOCALAPPDATA//\\//}/guardrails/cli-flag-cache"
+  else
+    printf -v "$1" '%s' "${XDG_CACHE_HOME:-$HOME/.cache}/guardrails/cli-flag-cache"
+  fi
+}
+
+# cfv_cache_key_to <var> <bin> [<subcmd>...]: bin and subcommands joined by
+# `__`, every path-unsafe character slugified to `_`.
+# The locals carry a prefix no caller uses, because `printf -v` writes to the
+# NAME it is given: a local named like the caller's target would shadow it and
+# the assignment would land here instead of in the caller.
+cfv_cache_key_to() {
+  local cfv__var="$1" cfv__key="$2" cfv__s
+  shift 2
+  for cfv__s in "$@"; do
+    cfv__key="${cfv__key}__${cfv__s}"
+  done
+  printf -v "$cfv__var" '%s' "${cfv__key//[^a-zA-Z0-9_-]/_}"
+}
+
+# cfv_flag_pattern_to <var> <flag-name>: the ERE that matches <flag-name> as a
+# whole flag inside a --help text. The flag may appear as:
+#   `  --flag         description`            (column-aligned)
+#   `  --flag <ARG>   description`            (with metavar)
+#   `  --flag=VALUE`                          (equals form)
+#   `  --flag[=VALUE]` / `--flag[-suffix]`    (optional-part notation)
+#   `  -F, --flag`                            (with short form)
+#   `  --flag, -F`                            (reverse short form)
+#   `  [--flag]`                              (optional-arg notation)
+#   `  [-S|--save|--save-dev|--save-optional]` (pipe-separated synopsis)
+#   `--flag` inside a usage line               (rare but valid)
+# The leading class (or the start) and the trailing terminator class (or the
+# end) prevent a prefix match: `--save-dev` never satisfies `--save-developer`.
+# The trailing class lists `]` first (literal), then the POSIX space class and
+# the remaining literals, `[` among them. Used with bash `=~` over a whole
+# multi-line text, the leading class admits the newline before a line start,
+# so it matches exactly where a line-wise `grep -E` would.
+cfv_flag_pattern_to() {
+  printf -v "$1" '%s' "(^|[^a-zA-Z0-9_-])${2}([][:space:]=,|)[]|\$)"
+}
+
+# cfv_flag_in_help <help-text> <flag-name>: 0 when the flag appears.
+cfv_flag_in_help() {
+  local cfv__pat
+  cfv_flag_pattern_to cfv__pat "$2"
+  [[ "$1" =~ $cfv__pat ]]
+}
diff --git a/.githooks/guardrails/cli-flag-verify.sh b/.githooks/guardrails/cli-flag-verify.sh
new file mode 100755
index 0000000000..0f421ebc20
--- /dev/null
+++ b/.githooks/guardrails/cli-flag-verify.sh
@@ -0,0 +1,540 @@
+#!/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 the cli_flag_verify_skip_bins userConfig option (e.g. for
+# extension-heavy CLIs like gh where --help is non-exhaustive). Disable entirely
+# with the cli_flag_verify_enabled userConfig option set to false.
+
+set -uo pipefail
+
+# High-res start stamp for telemetry (Bash 5.0+; empty on older bash → skip).
+start=${EPOCHREALTIME:-}
+
+# Kill switch FIRST, before any library is sourced: a disabled hook must not
+# pay to parse hook-utils.sh to learn it is off. Same predicate as
+# hook::is_enabled; scripts/check-killswitch-hoist.sh pins the two together.
+[[ "${CLAUDE_PLUGIN_OPTION_CLI_FLAG_VERIFY_ENABLED:-true}" == "true" ]] || exit 0
+
+# The hook's own directory is derived with parameter expansion rather than
+# `dirname`. GNU Bash forks a subshell for every command substitution even when
+# the body is a builtin (Command Substitution, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution). On Windows Git Bash that
+# fork is a process, and this line runs on every fire — including inside the
+# dispatcher, where the include guard makes `source` cheap but `$(dirname …)`
+# still execs. `${BASH_SOURCE[0]%/*}` equals `dirname` for every shape
+# BASH_SOURCE takes; the fallback covers a bare filename, where the strip is a
+# no-op and dirname answers `.`.
+_HOOK_SELF="${BASH_SOURCE[0]%/*}"
+[[ "$_HOOK_SELF" == "${BASH_SOURCE[0]}" ]] && _HOOK_SELF=.
+# shellcheck source=abort-boundary.sh
+source "$_HOOK_SELF/abort-boundary.sh"
+# Could-not-run posture (#3528): fail-open with a dual-channel "guard did not
+# run" notice; 0 is the only status this advisory verifier chooses. Nothing is
+# enforced here, so the loss on an abort is the advisory itself; the notice
+# says it was not produced.
+guard::abort_boundary cli-flag-verify PostToolUse open 0
+# shellcheck source=hook-utils.sh
+source "$_HOOK_SELF/hook-utils.sh" || exit 70 # not a chosen status: the boundary reports it
+
+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 "$_HOOK_SELF/.." && pwd)}"
+VERIFIER="$PLUGIN_ROOT/lib/verification/verify-cli-flag.sh"
+
+# hook::buffer_stdin encapsulates the Win32-pipe-safe bounded fd0 read; empty
+# or timed-out stdin skips this advisory hook. Buffering does not require jq
+# (hook::buffer_stdin's own JSON-completeness check is jq-optional), so it
+# runs before the jq gate below — hook::require jq needs the buffered input
+# for its once per session and agent notice scoping, and hook::read_file_path_to
+# (next) falls back to jq for a payload its builtin parse cannot prove.
+hook::buffer_stdin_to INPUT || exit 0
+
+# jq is required to parse the tool payload. hook::require jq fails OPEN
+# (this hook never blocks) but makes the degraded state visible to both the
+# user (systemMessage) and the agent (additionalContext), once per session and
+# agent — see docs/conventions/hook-observability/.
+hook::require jq "PostToolUse" guardrails "$INPUT"
+
+FILE=""
+hook::read_file_path_to FILE "$INPUT" || exit 0
+IS_MD=false
+case "$FILE" in
+*.md) IS_MD=true ;;
+*.sh | *.bash | *.ps1 | *.psm1) ;;
+*) exit 0 ;;
+esac
+
+# Diff-scope: verify only the content THIS tool call wrote, never re-read the
+# whole file from disk. An Edit's pre-existing lines outside the changed hunk are
+# not this call's claims; scanning the whole file re-flags an unknown flag on
+# every later unrelated edit. Edit -> the changed hunk (new_string); Write -> the
+# full payload content (a PostToolUse Write payload cannot distinguish a new file
+# from an overwrite, so "whole-file only for new files" degrades to whole-content
+# here — still the payload, never disk). The live matcher is Write|Edit; any
+# other tool carries nothing this call wrote that we can scope a scan to.
+#
+# Tool name and both per-tool content fields in ONE jq process
+# (hook::jq_fields), not two — a jq spawn is fork() emulation on Windows Git
+# Bash. Selecting the field inside jq would still cost the same process, so both
+# are fetched and the tool-specific choice happens below in the shell. Failure
+# semantics are unchanged: a missing jq or an unparsable payload yields rc 1
+# here, which exits 0 exactly as the unmatched-TOOL case did — hook::require jq
+# above has already made the degraded state visible once per session and agent.
+hook::jq_fields "$INPUT" '.tool_name' '.tool_input.new_string' '.tool_input.content' || exit 0
+TOOL="${HOOK_JQ_FIELDS[0]}"
+case "$TOOL" in
+Edit) SCAN_CONTENT="${HOOK_JQ_FIELDS[1]}" ;;
+Write) SCAN_CONTENT="${HOOK_JQ_FIELDS[2]}" ;;
+*) exit 0 ;;
+esac
+[[ -n "$SCAN_CONTENT" ]] || exit 0
+
+# Bundled verifier missing (install corruption, not a consumer-facing
+# prerequisite) — fail open, don't block, but tell the user once per session
+# rather than skip silently (docs/conventions/hook-observability/). The model
+# cannot reinstall a plugin, so it is not told; the path goes to the debug log.
+CFV_SHARED="$PLUGIN_ROOT/lib/verification/cli-flag-cache.sh"
+if [[ ! -x "$VERIFIER" || ! -f "$CFV_SHARED" ]]; then
+  if hook::notice_once "guardrails-cli-flag-verifier" "$INPUT"; then
+    if [[ ! -x "$VERIFIER" ]]; then
+      echo "cli-flag-verify: bundled verifier missing at $VERIFIER" >&2
+    else
+      echo "cli-flag-verify: bundled verifier library missing at $CFV_SHARED" >&2
+    fi
+    hook::emit_skip_notice PostToolUse "" \
+      "guardrails: cli-flag-verify is off: its bundled verifier is missing. Reinstall guardrails."
+  fi
+  exit 0
+fi
+
+# Repo root for telemetry data.file + relative sink resolution (file-anchored).
+# Parameter expansion, not a `$(dirname …)` subshell: this hook runs on every
+# Write and Edit, and a command substitution is a fork per call on Windows Git
+# Bash. Same answers as `dirname`: no slash -> `.`, and a root-level `/x` ->
+# `/` rather than the empty string, which hook::repo_root would read as `.`.
+FILE_DIR="${FILE%/*}"
+[[ "$FILE_DIR" == "$FILE" ]] && FILE_DIR="."
+[[ -n "$FILE_DIR" ]] || FILE_DIR=/
+REPO_ROOT="" REPO_ROOT_RESOLVED=1
+hook::repo_root_to REPO_ROOT "$FILE_DIR" || REPO_ROOT_RESOLVED=0
+
+# Known binaries to check. Override via the cli_flag_verify_bins userConfig option.
+# `git`, `npx`, and `npm` are intentionally EXCLUDED — all three have unreliable
+# or non-exhaustive `--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.
+#   - `npm <subcmd> --help` lists only that subcommand's own options, but EVERY
+#     npm config key is simultaneously a command-line flag on every subcommand —
+#     `npm --help` says so itself: "Specify configs in the ini-formatted file …
+#     or on the command line via: npm <command> --key=value". So the global
+#     config flags (`--prefix`, `--registry`, `--userconfig`, …) appear in
+#     NEITHER `npm <subcmd> --help` NOR `npm --help`, and every use of one is a
+#     false positive. The authoritative list (`npm config ls -l`) prints
+#     `prefix = "…"`, not `--prefix`, so it cannot be consumed by a generic
+#     `--help` flag-list parser without an npm-specific transform.
+# Re-add any of them via the option if it ever ships a stdout-parseable,
+# exhaustive flag list.
+DEFAULT_BINS="claude gh dotnet docker kubectl terraform az aws"
+BINS_RAW="${CLAUDE_PLUGIN_OPTION_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="${CLAUDE_PLUGIN_OPTION_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 scanned payload
+# content ($SCAN_CONTENT — the changed hunk for Edit, full content for Write).
+#   - 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.
+# Fence state is derived from the hunk alone, so a fence-straddling markdown edit
+# can misclassify in EITHER direction (a hunk inside a block whose ``` markers
+# fall outside it reads as prose and is under-scanned; a hunk that opens with a
+# closing ``` can over-scan). The convention trades this whole-file context away
+# for diff-scope precision; this fence-straddling residual is accepted, not
+# reconstructed. A distinct residual — an Edit hunk that is a bare flag fragment
+# with no binary in the changed region — IS recovered downstream by
+# reconstruct_partial_edit, which pulls bounded on-disk context so a swapped-in
+# unknown flag is not missed.
+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
+    printf '%s' "$SCAN_CONTENT" | grep -oE '`[^`]+`' 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).
+    printf '%s' "$SCAN_CONTENT" | awk '
+      /^[[:space:]]*```/ { f = !f; next }
+      /^[[:space:]]*~~~/ { f = !f; next }
+      f && $0 !~ /^[[:space:]]*#/ { print }
+    ' 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.
+    printf '%s' "$SCAN_CONTENT" | grep -vE '^[[:space:]]*#' 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)
+}
+
+# CHEAP PRE-GATE, ahead of every process this hook spends on scanning. A
+# candidate is a (bin, chain, flag) triple and a flag token always carries a
+# `-`, so content with no `-` anywhere cannot yield one, and the fragment
+# pipeline (grep plus sed, or awk) would run three processes to build an empty set. The
+# same holds for the Edit reconstruction below, whose anchor IS a flag token
+# from the hunk. What is skipped is the scan, never the report: telemetry and
+# the exit path below are reached exactly as before.
+HAS_FLAG_SHAPE=0
+[[ "$SCAN_CONTENT" == *-* ]] && HAS_FLAG_SHAPE=1
+
+# SECOND PRE-GATE, same cost class. A candidate also names one of the scanned
+# bins, and ordinary prose is full of hyphens ("well-known", "re-run") that pass
+# the `-` test alone, so on a markdown Write the scan ran for nothing on nearly
+# every paragraph. Substring, not word-bounded: a superset of every real
+# candidate (extract_candidates matches the whole token), so it skips only
+# content that could not have yielded one, and it spawns nothing. The Edit
+# reconstruction below keeps its own gate: a bare-flag hunk names no bin by
+# definition, and the bin it belongs to is on disk.
+HAS_BIN=0
+for cfv_bin in $BINS; do
+  if [[ "$SCAN_CONTENT" == *"$cfv_bin"* ]]; then
+    HAS_BIN=1
+    break
+  fi
+done
+
+((HAS_FLAG_SHAPE && HAS_BIN)) && extract_candidates
+
+# Partial-replacement context reconstruction (Edit only). When an Edit's hunk is
+# a bare flag fragment — a flag token swapped in with no binary/subcommand in the
+# changed region — the diff-scoped scan finds no command candidate and would
+# silently miss a genuinely-introduced unknown flag. Recover bounded context:
+# pull from the on-disk file only the lines carrying one of the hunk's flag
+# tokens (the edit has already been applied by PostToolUse time, so the swapped-in
+# flag is on disk), scan those, and keep only candidates whose flag appears in the
+# hunk. The flag-token filter is what preserves the diff-scope contract: a
+# pre-existing unrelated flag sharing one of those lines never re-fires. The
+# anchor is the flag token, not the line — a bare-flag hunk carries no positional
+# information — so a hunk flag that also occurs on an untouched line is scanned
+# there too; only a DIFFERENT pre-existing flag is excluded.
+reconstruct_partial_edit() {
+  [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0
+  # Trigger only when the hunk produced no command candidate; a full-command hunk
+  # already scans correctly and must not re-scan from disk.
+  ((${#CANDIDATES[@]} == 0)) || return 0
+  local -a hunk_flags=()
+  mapfile -t hunk_flags < <(
+    printf '%s' "$SCAN_CONTENT" |
+      grep -oE '(^|[[:space:]])--?[A-Za-z0-9][A-Za-z0-9-]*' 2>/dev/null |
+      sed -E 's/^[[:space:]]*//' | sort -u
+  )
+  ((${#hunk_flags[@]})) || return 0
+  local tok ctx="" lines
+  for tok in "${hunk_flags[@]}"; do
+    lines=$(grep -F -- "$tok" "$FILE" 2>/dev/null)
+    [[ -n "$lines" ]] && ctx+="$lines"$'\n'
+  done
+  ctx=$(printf '%s' "$ctx" | grep -vE '^[[:space:]]*$' | head -20)
+  [[ -n "$ctx" ]] || return 0
+  SCAN_CONTENT="$ctx"
+  extract_candidates
+  local key flag t keep
+  for key in "${!CANDIDATES[@]}"; do
+    flag="${key##*|}"
+    keep=0
+    for t in "${hunk_flags[@]}"; do
+      [[ "$flag" == "$t" ]] && {
+        keep=1
+        break
+      }
+    done
+    ((keep)) || unset 'CANDIDATES[$key]'
+  done
+}
+
+((HAS_FLAG_SHAPE)) && reconstruct_partial_edit
+
+# Split a "bin|chain|flag" CANDIDATES/FAILURES key into its three parts. Globals
+# rather than an echo: this runs per candidate and per finding, and a command
+# substitution would add a fork to each one.
+KEY_BIN=""
+KEY_CHAIN=""
+KEY_FLAG=""
+split_candidate_key() {
+  local rest
+  KEY_BIN="${1%%|*}"
+  rest="${1#*|}"
+  KEY_CHAIN="${rest%|*}"
+  KEY_FLAG="${rest##*|}"
+}
+
+# CACHE HITS ARE ANSWERED IN THIS PROCESS. The verifier keeps each
+# `<bin> [<subcmd>...] --help` output under a 24 h cache, and on a hit its whole
+# job is to read that file and match one pattern. Spawning it for that cost more
+# than the work: a bash process, the `#!/usr/bin/env` PATH walk for bash (one
+# failed execve per PATH entry ahead of it), then mkdir, find, grep. Measured on
+# a warm cache: 88 failed execve per run on this host, 4 of the 5 env walks
+# being these spawns. The cache location, key, freshness window and match
+# pattern are ONE definition, sourced from lib/verification/cli-flag-cache.sh
+# by this hook and by the verifier, so the two paths cannot drift; a miss still
+# goes through the verifier, which populates the cache, and every exit code
+# keeps its meaning.
+CFV_CACHE_DIR=""
+declare -A CFV_FRESH=()
+CFV_FRESH_INDEXED=0
+# Runs once, on the first candidate whose bin is installed: sources the shared
+# definitions, resolves the cache directory, and indexes with one find every
+# cache file inside the freshness window. A write that yields no candidate, or
+# only cites bins this machine lacks, never pays any of it.
+cfv_index_fresh_cache() {
+  local f
+  ((CFV_FRESH_INDEXED)) && return 0
+  CFV_FRESH_INDEXED=1
+  # shellcheck source=../lib/verification/cli-flag-cache.sh
+  source "$CFV_SHARED"
+  cfv_cache_dir_to CFV_CACHE_DIR
+  [[ -d "$CFV_CACHE_DIR" ]] || return 0
+  while IFS= read -r f; do
+    [[ -n "$f" ]] && CFV_FRESH["$f"]=1
+  done < <(find "$CFV_CACHE_DIR" -maxdepth 1 -name '*.help' -mmin "-$CFV_CACHE_WINDOW_MIN" 2>/dev/null)
+}
+# verify_candidate <bin> <chain> <flag> -> 0 present, 1 absent, 2 unverifiable
+# (the verifier's contract, answered here on a hit and by the verifier on a miss).
+verify_candidate() {
+  local bin="$1" chainstr="$2" flag="$3" key cache_file help rc
+  local -a chainarr=()
+  read -ra chainarr <<<"$chainstr"
+  cfv_index_fresh_cache
+  cfv_cache_key_to key "$bin" "${chainarr[@]}"
+  cache_file="$CFV_CACHE_DIR/$key.help"
+  if [[ -n "${CFV_FRESH[$cache_file]:-}" && -s "$cache_file" ]]; then
+    help=$(<"$cache_file")
+    cfv_flag_in_help "$help" "$flag" && return 0
+    return 1
+  fi
+  "$VERIFIER" --quiet "$bin" "${chainarr[@]}" "$flag" 2>/dev/null
+  rc=$?
+  # A miss the verifier could answer (0 or 1) has just written the cache file,
+  # so every later candidate sharing this (bin, chain) is answered here rather
+  # than spawning the verifier again for the same --help text.
+  if ((rc == 0 || rc == 1)) && [[ -s "$cache_file" ]]; then
+    CFV_FRESH["$cache_file"]=1
+  fi
+  return "$rc"
+}
+
+# Verify each unique (bin, chain, flag). Collect failures (keys, formatted later).
+FAILURES=()
+for key in "${!CANDIDATES[@]}"; do
+  split_candidate_key "$key"
+  # Skip if binary not on PATH (verifier exit 2). Avoids spurious failures on
+  # systems missing tools the file references for documentation purposes.
+  command -v "$KEY_BIN" >/dev/null 2>&1 || continue
+  verify_candidate "$KEY_BIN" "$KEY_CHAIN" "$KEY_FLAG"
+  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
+  # The helper carries the redaction: a path it could not make repo-relative
+  # comes back as the basename, never an absolute path (which would embed the
+  # developer's username).
+  local findings_json="[]" file_rel
+  file_rel=""
+  hook::repo_relative_path_to file_rel "$FILE" "$REPO_ROOT"
+  if ((${#FAILURES[@]} > 0)); then
+    local f raw="" disp
+    for f in "${FAILURES[@]}"; do
+      split_candidate_key "$f"
+      [[ -n "$KEY_CHAIN" ]] && disp="$KEY_BIN $KEY_CHAIN $KEY_FLAG" || disp="$KEY_BIN $KEY_FLAG"
+      raw+="$disp"$'\n'
+    done
+    findings_json=$(printf '%s' "$raw" | jq -Rn '[inputs]' 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
+  # The file as the model names it: repo-relative when it sits under the root
+  # spelled the same way, else as given. Outside a repo the root is the file's
+  # own directory, and a bare name would name a different file.
+  show_file="$FILE"
+  ((REPO_ROOT_RESOLVED)) && [[ "$FILE" == "${REPO_ROOT%/}/"?* ]] && show_file="${FILE#"${REPO_ROOT%/}/"}"
+  lines=""
+  for f in "${FAILURES[@]}"; do
+    split_candidate_key "$f"
+    if [[ -n "$KEY_CHAIN" ]]; then
+      disp="$KEY_BIN $KEY_CHAIN $KEY_FLAG"
+      helpref="$KEY_BIN $KEY_CHAIN --help"
+    else
+      disp="$KEY_BIN $KEY_FLAG"
+      helpref="$KEY_BIN --help"
+    fi
+    lines+="$disp (not in '$helpref')"$'\n'
+  done
+  cfv_ctx=""
+  hook::findings_to cfv_ctx \
+    "cli-flag-verify: unknown flag(s) in $show_file, unverified, not proven wrong: the installed --help may predate the flag." \
+    "$lines" --max 10
+  hook::ctx_append "$cfv_ctx"
+  hook::ctx_flush PostToolUse
+fi
+
+emit_tel
+exit 0
diff --git a/.githooks/guardrails/commit-msg-convention.sh b/.githooks/guardrails/commit-msg-convention.sh
new file mode 100755
index 0000000000..1f25236eb5
--- /dev/null
+++ b/.githooks/guardrails/commit-msg-convention.sh
@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# guardrails commit-msg-convention sha256:2c8e3cb3fe60ec94871ad2fbc478bfc9a6e29f76e1ef484de7e8f9eb9385b7d3
+# guardrails-commit-msg-convention v2
+# guardrails commit-msg check: the commit subject matches the team convention.
+#
+#   commit-msg-convention.sh <message-file>   git runs it as commit-msg
+#
+# The tool-agnostic layer of commit-convention enforcement: the Claude Code
+# guard sees only tool calls, while this git hook checks every commit in the
+# repository, from an editor, `git commit -F <file>`, an IDE or another agent.
+# It reads the team-tracked pattern (`subject_pattern` in
+# .claude/source-control.md) through the same resolver the guard uses,
+# installed beside this script as an entry asset.
+#
+# Sentinel: the "guardrails-commit-msg-convention" marker on line 1 or 3 marks
+# this hook as derived FROM the tracked config, so convention-inference tooling
+# must not count it as an independent signal.
+#
+# No tracked pattern: no enforcement, exit 0, silent. A pattern that is not POSIX
+# ERE, an unreadable config or a resolver that cannot run also exits 0, but
+# prints a notice with the resolver's diagnostic to stderr (this hook has no
+# model channel): exit 1 with empty stderr is "no pattern", anything else a failure.
+# Fixup, squash and amend subjects pass, as rebase --autosquash consumes them.
+# A violation prints how to fix the subject and exits 1; this hook never
+# suggests skipping it.
+set -uo pipefail
+
+msg_file="${1:-}"
+[[ -n "$msg_file" && -f "$msg_file" ]] || exit 0
+
+here="${BASH_SOURCE[0]%/*}"
+[[ "$here" == "${BASH_SOURCE[0]}" ]] && here=.
+resolver="$here/resolve-convention-pattern.sh"
+[[ -f "$resolver" ]] || resolver="$here/../hooks/resolve-convention-pattern.sh"
+# Resolver gone: no enforcement, never a blind block.
+[[ -f "$resolver" ]] || exit 0
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+errf="$(mktemp 2>/dev/null)" || errf=/dev/null
+subject_ere="$(bash "$resolver" "$repo_root" subject_pattern 2>"$errf")"
+rc=$?
+if ((rc != 0)); then
+  err=""
+  IFS= read -r -d '' err <"$errf" || true
+  err="${err//[$'\r\n\t']/ }"
+  err="${err#"${err%%[![:space:]]*}"}"
+  err="${err%"${err##*[![:space:]]}"}"
+  [[ "$errf" == /dev/null ]] || rm -f "$errf"
+  # Exit 1 with empty stderr is "no convention tracked": quiet. Any other
+  # failure means this check did not run; it still lets the commit through.
+  if [[ -n "$err" || $rc -ne 1 ]]; then
+    [[ -n "$err" ]] || err="exit status $rc, no message"
+    echo "guardrails: the commit-msg convention check did not run, so this subject was not checked. The convention resolver reported \"${err:0:300}\"." >&2
+  fi
+  exit 0
+fi
+[[ "$errf" == /dev/null ]] || rm -f "$errf"
+[[ -n "$subject_ere" ]] || exit 0
+
+# The subject is the first non-empty line git keeps. Git drops comment lines
+# only under the strip cleanup: commit.cleanup=strip, or the default when an
+# editor ran. Git sets GIT_EDITOR=: for this hook when none did (-m, -F), so a
+# `-m "#123 fix"` subject is kept and checked. A --cleanup flag cannot be seen
+# here. The comment character follows core.commentChar; `auto` cannot be known
+# here.
+comment_char="$(git config --get core.commentChar 2>/dev/null || true)"
+[[ -n "$comment_char" && "$comment_char" != auto ]] || comment_char="#"
+case "$(git config --get commit.cleanup 2>/dev/null || true)" in
+strip) strip=1 ;;
+verbatim | whitespace | scissors) strip=0 ;;
+*) if [[ "${GIT_EDITOR:-}" == ":" ]]; then strip=0; else strip=1; fi ;;
+esac
+
+subject=""
+while IFS= read -r line || [[ -n "$line" ]]; do
+  line="${line%$'\r'}"
+  [[ -n "$line" ]] || continue
+  ((strip)) && [[ "${line:0:1}" == "$comment_char" ]] && continue
+  subject="$line"
+  break
+done <"$msg_file"
+
+# An empty message: git aborts the commit itself.
+[[ -n "$subject" ]] || exit 0
+
+case "$subject" in
+"fixup! "* | "squash! "* | "amend! "*) exit 0 ;;
+*) ;;
+esac
+
+grep -Eq -- "$subject_ere" <<<"$subject" && exit 0
+{
+  echo "guardrails: the commit subject does not match the team convention."
+  echo "  subject: $subject"
+  echo "  pattern: $subject_ere   (subject_pattern in .claude/source-control.md)"
+  echo "Rewrite the subject to match the pattern and commit again. If the pattern"
+  echo "itself is wrong, change it in .claude/source-control.md through a pull request."
+} >&2
+exit 1
diff --git a/.githooks/guardrails/hardcoded-path-patterns.sh b/.githooks/guardrails/hardcoded-path-patterns.sh
new file mode 100644
index 0000000000..715b866f73
--- /dev/null
+++ b/.githooks/guardrails/hardcoded-path-patterns.sh
@@ -0,0 +1,320 @@
+# 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.
+
+# The per-OS regex BODIES live in machine-path-patterns.sh — the org-shared,
+# standards-managed materialization — so a pattern change lands upstream once
+# and reaches every scan driver in lockstep. This lib keeps only its own
+# wrapping (the macOS/Linux pipe exclusions and OS-context suppression below).
+# shellcheck source=machine-path-patterns.sh
+source "${BASH_SOURCE[0]%/*}/machine-path-patterns.sh"
+
+# 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
+  #   checkout-root literals ⊇ Windows-repo + escaped-Windows-repo — the gate
+  #     lists every root token HPP_WIN_REPO_BODY / HPP_ESCAPED_WIN_REPO_BODY
+  #     accept (both spellings), so a widened body must widen this list too.
+  # 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`).
+  # Feeds the payload through PROCESS SUBSTITUTION — not `<<<`, and not
+  # `printf | grep -q`. Both alternatives are broken on whole-payload content:
+  #   `<<<"$content"` deadlocks. Bash delivers a here-string through a pipe and
+  #     appends a newline, so a content length of 65536-65663 puts the write
+  #     1-128 bytes past the 65536-byte pipe capacity and bash blocks forever
+  #     (at >=129 bytes over it spills to a temp file and works again). A
+  #     blocking guard that never answers loses its verdict outright — the
+  #     harness cancels it at the hook timeout.
+  #   `printf … | grep -q` INVERTS. `grep -q` exits at the first match and
+  #     SIGPIPEs printf; under `pipefail` the pipeline reports printf's 141, and
+  #     `if ! …` reads a non-zero status as "no match" and early-returns clean —
+  #     a fail-open on exactly the content that matched.
+  # `grep -q … < <(printf …)` keeps the early exit, keeps the writer OUT of the
+  # pipeline (so `pipefail` never sees its SIGPIPE), and never blocks. Same rule
+  # as lib/hook-utils.sh's `printf | jq`: never feed a whole payload through
+  # `<<<`; use a pipe when the reader drains its input (jq), and process
+  # substitution when the reader may exit early (`grep -q`).
+  # `printf '%s'` (no trailing newline) also matches the detailed blocks below,
+  # so the gate and the scan see byte-identical input.
+  #
+  # Builtin pre-gate, no process: it answers "clean" only where the two greps
+  # below would, and hands everything else to them. Under LC_ALL=C:
+  #   - A literal in the content means the scan runs. Byte substring presence is
+  #     never tighter than grep's line match of the same literals, and a looser
+  #     gate only costs a scan that finds nothing.
+  #   - Otherwise the root segment is compared with ASCII case folding, but only
+  #     when the content and the segment are ASCII and the segment holds no
+  #     newline (grep -F reads a newline as a second pattern). Over ASCII text
+  #     grep -i's locale folding can only match a subset of what ASCII folding
+  #     matches, so "no match" here is "no match" there. Non-ASCII text goes to
+  #     grep, whose locale folding (the Kelvin sign for k) is wider.
+  # A case pattern, not a regex: Git Bash's regex decodes UTF-8 even under C.
+  local gate_root="" hpp_gate=grep hpp_lc_set=${LC_ALL+x} hpp_lc=${LC_ALL-} hpp_nc=0
+  local hpp_non_ascii=$'[!\x01-\x7f]' hpp_non_ascii_nl=$'[!\x01-\x09\x0b-\x7f]'
+  if [[ -n "$project_root" ]]; then
+    gate_root="${project_root//\\//}"
+    gate_root="${gate_root%/}"
+    gate_root="${gate_root##*/}"
+  fi
+  # Assigning a readonly LC_ALL would abort this function, so a readonly one
+  # skips the pre-gate and the greps decide. So does bash before 4.4, which has
+  # no ${var@a}; eval keeps that expansion out of such a bash's parse. The
+  # expansion trips `set -u` on an unset LC_ALL, so nounset is lifted around it.
+  local hpp_attr=r
+  if ((BASH_VERSINFO[0] * 100 + BASH_VERSINFO[1] >= 404)); then
+    case $- in
+    *u*)
+      set +u
+      eval 'hpp_attr=${LC_ALL@a}'
+      set -u
+      ;;
+    *) eval 'hpp_attr=${LC_ALL@a}' ;;
+    esac
+  fi
+  if [[ $hpp_attr != *r* ]]; then
+    LC_ALL=C
+    case $content in
+    *Users* | */home/* | *repos* | *Repos* | *projects* | *Projects* | *dev* | *Dev*) hpp_gate=scan ;;
+    *$hpp_non_ascii*) ;;
+    *)
+      case $gate_root in
+      *$hpp_non_ascii_nl*) ;;
+      "") hpp_gate=clean ;;
+      *)
+        shopt -q nocasematch && hpp_nc=1
+        shopt -s nocasematch
+        hpp_gate=clean
+        [[ $content == *"$gate_root"* ]] && hpp_gate=scan
+        ((hpp_nc)) || shopt -u nocasematch
+        ;;
+      esac
+      ;;
+    esac
+    # Restoring an LC_ALL that names a locale this host lacks makes bash warn
+    # "setlocale: cannot change locale"; only the restore is silenced.
+    { if [[ -n "$hpp_lc_set" ]]; then LC_ALL=$hpp_lc; else unset LC_ALL; fi; } 2>/dev/null
+  fi
+  [[ $hpp_gate == clean ]] && return 0
+  # `--` on every grep whose pattern comes from the project root: a root whose
+  # last segment starts with `-` (`-e`, `--help`) is a pattern, not an option.
+  if [[ $hpp_gate == grep ]] && ! grep -qE -- 'Users|/home/|repos|Repos|projects|Projects|dev|Dev' < <(printf '%s' "$content") 2>/dev/null; then
+    # Process substitution for the same two reasons as the gate above.
+    if [[ -z "$gate_root" ]] || ! grep -qFi -- "$gate_root" < <(printf '%s' "$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
+
+  # Left boundary for the slash-rooted macOS/Linux bodies — the driver-owned
+  # prefix the pattern lib's contract calls for, so a URL or relative-path
+  # suffix (https://example.test + the home root) is not treated as a
+  # filesystem root. Line start, whitespace, quote, backtick, paren, "=", ":"
+  # (yaml/docker value position), or a file:// scheme. Mirrors the
+  # ci-workflows/medley verification drivers' boundary, plus ":".
+  local _posix_boundary
+  _posix_boundary="(^|[[:space:]\"'\`(=:]|file://)"
+
+  # macOS user home paths (the Users root with a child segment).
+  # Exclusions (replace Perl lookbehind/lookahead):
+  #   grep -vE '[A-Za-z]:[/\\]' — Windows paths (caught above)
+  #   Shared exclusion — the Users/Shared directory is legitimately shareable.
+  #     NOT a line-level grep -v: one line can hold a Shared path AND a
+  #     user-specific one, and dropping the whole line would silently pass the
+  #     real violation. Each candidate line is re-tested with its Shared tokens
+  #     defanged; only lines whose SOLE matches are Shared drop out. The defang
+  #     boundary is any character that cannot CONTINUE a real directory name
+  #     (word chars, dot, hyphen) — not an enumerated delimiter list, so shell
+  #     and prose punctuation right after the value (";", a closing quote, a
+  #     paren) counts as a boundary while a longer segment like SharedStuff
+  #     stays untouched and flagged. Basic-regex sed expressions (no in-group
+  #     anchors) keep macOS stock sed compatibility; the ORIGINAL line is
+  #     reported, never the defanged copy.
+  #     The Shared literal is assembled from pieces so this driver's own source
+  #     never carries a contiguous Users-root token for the write-scan hook
+  #     that consumes these bodies to flag.
+  #
+  # The defang runs ONCE over the whole candidate block, not once per candidate
+  # line, so the subprocess count is constant rather than proportional to the
+  # candidate count. `sed` is line-oriented in this pipeline — no `N`/`H`
+  # multiline commands, and `$` is a per-line anchor in both shapes — so
+  # hoisting cannot change any individual line's result. A per-line loop is
+  # pathologically slow on exactly the innocent input this exclusion exists to
+  # serve: the loop's only escape is the trailing `head -3`, which fires when
+  # candidates SURVIVE, so an all-Shared block never short-circuits and pays a
+  # `sed` plus a `grep` on every line. Measured through the hook on Git Bash
+  # over the same corpora, swapping only this library: the per-line shape
+  # spawned 210 `grep`/`sed` processes at 100 Shared-only lines and its wall
+  # clock grew 13x for 4x the input (22s to 288s), against 12 spawns at either
+  # size and a flat ~10s hoisted.
+  # A guard killed at its hook timeout fails OPEN, so the bound is a correctness
+  # property, not merely a speed one. `grep -E` stays the sole matcher — `awk`
+  # only selects lines by index and does no regex work, so no second regex
+  # dialect enters the pipeline and the shared HPP_* bodies stay the SSOT.
+  if [[ -z "$macos_context" ]]; then
+    local _shared _shared_defused _cands _keep
+    _shared='/Use''rs/Shared'
+    _shared_defused='/Use''rs-Shared'
+    # `|| true`: the trailing `grep -v` exits 1 when nothing survives (the
+    # common clean case). This lib is sourced by commit-time hooks whose shell
+    # options it does not control, and aborting the scan under `set -e` would
+    # fail OPEN — the very failure mode this block is shaped to avoid.
+    _cands=$(printf '%s' "$content" | grep -nE "${_posix_boundary}${HPP_MACOS_USER_BODY}" 2>/dev/null |
+      grep -vE '[A-Za-z]:[/\\]') || true
+    if [[ -n "$_cands" ]]; then
+      if [[ "$_cands" != *"$_shared"* ]]; then
+        # No Shared token anywhere in the block, so the defang is a provable
+        # no-op and every candidate survives it. This bash-builtin substring
+        # test keeps the common case free; the branch below costs four more
+        # processes, and on Git Bash spawn cost — not matching — dominates.
+        match=$(printf '%s\n' "$_cands" | head -3)
+      else
+        # Block-relative indices of the candidates that still match once
+        # defanged, then select those lines from the ORIGINAL block so the
+        # reported line is never the defanged copy.
+        #
+        # The leading `s/^[0-9]*://` drops the line-number prefix the first
+        # `grep -n` added, so this re-test sees the same bytes the first pass
+        # matched. Without it a violation at COLUMN 0 reaches the re-test as
+        # `<n>:/Users/…` and can no longer satisfy the boundary's `^`
+        # alternative — it survives today only because the class happens to
+        # also accept ":", which is there for yaml/docker value position and
+        # carries no obligation to this pipeline. Stripping keeps the two
+        # passes' conditions identical instead of coupling the second to an
+        # unrelated member of the class. It costs no extra process: the strip
+        # is another expression on the `sed` the defang already runs.
+        _keep=$(printf '%s\n' "$_cands" |
+          sed -e 's|^[0-9]*:||' -e "s|${_shared}\([^A-Za-z0-9._-]\)|${_shared_defused}\1|g" -e "s|${_shared}\$|${_shared_defused}|" |
+          grep -nE "${_posix_boundary}${HPP_MACOS_USER_BODY}" 2>/dev/null | cut -d: -f1)
+        match=$(printf '%s\n' "$_cands" | awk -v keep="$_keep" '
+          BEGIN { n = split(keep, a, "\n"); for (i = 1; i <= n; i++) k[a[i]] = 1 }
+          k[NR]' | head -3)
+      fi
+      [[ -n "$match" ]] && violations="${violations}macOS user path detected:${nl}${match}${nl}${nl}"
+    fi
+  fi
+
+  # Linux user home paths (same driver-owned left boundary).
+  if [[ -z "$linux_context" ]]; then
+    match=$(printf '%s' "$content" | grep -nE "${_posix_boundary}${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/.githooks/guardrails/hook-utils.sh b/.githooks/guardrails/hook-utils.sh
new file mode 100644
index 0000000000..def8a71d1a
--- /dev/null
+++ b/.githooks/guardrails/hook-utils.sh
@@ -0,0 +1,5046 @@
+# GENERATED from lib/hook-utils.sh by scripts/sync-shared-copies.sh. Do not edit this copy:
+# edit the canonical source, then rerun the script.
+# 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-shared-copies.sh; CI rejects drifted copies.
+#
+# CALLING CONVENTION: a helper that produces a value is spelled
+# `hook::<name>_to <var> [args…]` and writes into the caller's variable. That
+# is the one convention; call it directly rather than wrapping it in `$( )`.
+# GNU Bash forks a subshell for every command substitution even when the body
+# is only builtins (Command Substitution, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution), and on Windows Git Bash a
+# fork is a non-copy-on-write Win32 CreateProcess costing milliseconds, so a
+# capture around a `_to` helper is pure loss on hooks that run per edit.
+# Six helpers still print instead — hook::json_escape, hook::physical_path,
+# hook::repo_root, hook::buffer_stdin, hook::raw_file_path and
+# hook::read_file_path (which reads fd0; a hook holding the buffered payload
+# calls hook::read_file_path_to). Each carries, at its definition, the reason
+# its print form is kept.
+
+# Guard against double-sourcing.
+[[ -n "${_HOOK_UTILS_LOADED:-}" ]] && return 0
+readonly _HOOK_UTILS_LOADED=1
+
+# Per-hook kill switch via the plugin's <name>_enabled userConfig boolean,
+# read from the hook-process CLAUDE_PLUGIN_OPTION_<NAME>_ENABLED mirror.
+# Exits 0 (allow) if disabled. Place after source, before stdin parsing.
+#   hook::check_enabled "MARKDOWN_FORMAT"  # checks CLAUDE_PLUGIN_OPTION_MARKDOWN_FORMAT_ENABLED
+#
+# Deliberately NOT layered with a marketplace-specific fleet switch. Claude Code
+# already ships the coarse controls, and a parallel scheme here would become a
+# second source of truth for the same question:
+#   * `--safe-mode` / `CLAUDE_CODE_SAFE_MODE`
+#     (https://code.claude.com/docs/en/cli-reference#cli-flags)
+#   * `disableAllHooks`
+#     (https://code.claude.com/docs/en/settings-reference#disableallhooks)
+#   * `claude plugin disable|enable <name>`
+#     (https://code.claude.com/docs/en/plugins/cli-reference#plugin-disable)
+# Each pointer says what the control covers (as of 2026-10-11; recheck when one
+# of those sections is removed or stops covering hooks).
+# This helper stays scoped to the one thing it owns: the plugin's own
+# `<name>_enabled` userConfig boolean, surfaced to hook processes as the native
+# `$CLAUDE_PLUGIN_OPTION_<KEY>` mirror.
+
+# hook::is_enabled <NAME> — the same check as a PREDICATE. Returns 0 when the
+# plugin should run, 1 when it should not. For callers that must not terminate
+# the process on a "disabled" answer, such as a wrapper that must skip its own
+# side effect and still pass the wrapped command's output through.
+hook::is_enabled() {
+  local var_name="CLAUDE_PLUGIN_OPTION_${1}_ENABLED"
+  [[ "${!var_name:-true}" == "true" ]]
+}
+
+hook::check_enabled() {
+  hook::is_enabled "$1" || exit 0
+}
+
+# --- Prerequisite visibility --------------------------------------------------
+# Doctrine: a missing runtime prerequisite must surface to BOTH the agent
+# (additionalContext) and the user (systemMessage) — a silently skipped feature
+# is a defect. Everything in this section is jq-FREE by design: the most common
+# missing prerequisite is jq itself.
+
+# JSON-escape a string for embedding in a hand-built JSON document. Escapes
+# backslash, double quote, and the line-structure control bytes by name
+# (\n \r \t); the remaining C0 bytes JSON forbids raw are dropped — notice text
+# never carries meaningful control bytes beyond line structure. Byte-safe under
+# UTF-8: every escaped byte is ASCII, and UTF-8 continuation bytes are >= 0x80.
+#
+# hook::json_escape_to <var> <string> writes in THIS shell and is the form to
+# call. hook::json_escape is kept as a print form for the two Stop/PostCompact
+# marker builders that splice an escaped field into a single-quoted JSON
+# literal, where a capture is the shape; a `$(hook::json_escape …)` capture is
+# still a fork even when the body is only builtins (Command Execution
+# Environment, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution). The previous
+# `printf | tr -d` pipeline added two more process creations and a `tr` exec
+# per notice; Cygwin's fork is a non-copy-on-write Win32 CreateProcess
+# (Cygwin User's Guide, "Process Creation": "fork will almost certainly
+# always be inefficient under Win32"). Residual C0 deletion is the same
+# character class tr used (`\001-\010\013\014\016-\037`); NUL cannot appear
+# in a bash string, so tr's `\000` was already unrepresentable.
+hook::json_escape_to() {
+  local __hu_s="$2"
+  __hu_s="${__hu_s//\\/\\\\}"
+  __hu_s="${__hu_s//\"/\\\"}"
+  __hu_s="${__hu_s//$'\n'/\\n}"
+  __hu_s="${__hu_s//$'\r'/\\r}"
+  __hu_s="${__hu_s//$'\t'/\\t}"
+  if [[ "$__hu_s" == *[[:cntrl:]]* ]]; then
+    __hu_s="${__hu_s//[$'\001'-$'\010'$'\013'$'\014'$'\016'-$'\037']/}"
+  fi
+  printf -v "$1" '%s' "$__hu_s"
+}
+
+hook::json_escape() {
+  local __hu_e
+  hook::json_escape_to __hu_e "$1"
+  printf '%s' "$__hu_e"
+}
+
+# Emit hook JSON carrying an agent-channel context (additionalContext) and/or a
+# user-channel message (systemMessage) as ONE document, so a run that has both
+# lint findings and a pending skip notice composes them here rather than
+# printing twice; how stdout is parsed as JSON is
+# https://code.claude.com/docs/en/hooks#exit-code-0 (as of 2026-10-11; recheck
+# when that section starts reading more than one JSON object from stdout). Either
+# channel may be empty; emits nothing when both are. One entry point for both
+# channels, so a hook with only one of them passes "" for the other rather
+# than picking between two spellings of the same emit.
+#   hook::emit_channels PostToolUse "$ctx" "$sysmsg"
+#   hook::emit_channels PreToolUse "$ctx" ""      # agent channel only
+hook::emit_channels() {
+  local event="$1" ctx="$2" sysmsg="$3"
+  [[ -n "$ctx" || -n "$sysmsg" ]] || return 0
+  local __hu_ee __hu_ec __hu_es out="{"
+  if [[ -n "$ctx" ]]; then
+    hook::json_escape_to __hu_ee "$event"
+    hook::json_escape_to __hu_ec "$ctx"
+    out+='"hookSpecificOutput":{"hookEventName":"'"$__hu_ee"'","additionalContext":"'"$__hu_ec"'"}'
+    [[ -n "$sysmsg" ]] && out+=","
+  fi
+  if [[ -n "$sysmsg" ]]; then
+    hook::json_escape_to __hu_es "$sysmsg"
+    out+='"systemMessage":"'"$__hu_es"'"'
+  fi
+  out+="}"
+  hook::emit_document "$out"
+}
+
+# hook::emit_document <json>: write ONE hook JSON document to stdout. Every
+# document a hook emits goes through here, hook::emit_channels included, so a
+# dispatcher that runs several hooks in one process (guardrails run-guards.sh)
+# can override this one function to collect the documents and merge them,
+# instead of capturing each hook's stdout in a subshell. A hook that prints a
+# document with its own printf bypasses that collection: under such a
+# dispatcher its document reaches stdout unmerged, which is invalid hook
+# output when another hook emitted too.
+hook::emit_document() {
+  printf '%s\n' "$1"
+}
+
+# Skip notice, gated per channel by the last hook::notice_once. The caller exits
+# 0 right after unless it composes via hook::emit_channels itself.
+#   hook::emit_skip_notice PostToolUse "$text"                 # same text, both channels
+#   hook::emit_skip_notice PostToolUse "$model" "$user"        # one text per channel
+#   hook::emit_skip_notice PostToolUse "" "$user"              # user channel only
+#
+# The model gets <model-text> when HOOK_NOTICE_TO_MODEL is 1 and the user gets
+# <user-text> when HOOK_NOTICE_TO_USER is 1; both are 1 unless hook::notice_once
+# just cleared one. A `PATH probed:` line in either text goes to stderr, which
+# an exit-0 hook sends to the debug log, never to a channel.
+hook::emit_skip_notice() {
+  local event="$1" model="$2" user="${3-$2}" probe=$'\nPATH probed: ' path=""
+  if [[ "$model" == *"$probe"* ]]; then
+    path="${model#*"$probe"}"
+    model="${model%%"$probe"*}"
+  fi
+  if [[ "$user" == *"$probe"* ]]; then
+    path="${user#*"$probe"}"
+    user="${user%%"$probe"*}"
+  fi
+  [[ -n "$path" ]] && printf 'PATH probed: %s\n' "$path" >&2
+  [[ "${HOOK_NOTICE_TO_MODEL:-1}" == 1 ]] || model=""
+  [[ "${HOOK_NOTICE_TO_USER:-1}" == 1 ]] || user=""
+  HOOK_NOTICE_TO_MODEL=1
+  HOOK_NOTICE_TO_USER=1
+  hook::emit_channels "$event" "$model" "$user"
+}
+
+# The exit-0 notice for hook::buffer_stdin rc 3 (a JSON payload cut short by
+# the pipe CLOSING mid-document; a pipe that stalls on such a prefix is rc 2
+# and never reaches this). Not once-per-session: each occurrence is one tool
+# call that ran unevaluated. User channel only, since the user is the one who
+# can act on a starved host; the same line goes to stderr next to
+# buffer_stdin's own diagnostic. <event> is accepted for the callers that pass
+# it and is not used. The caller exits 0 right after.
+#   hook::stdin_cut_short_notice PreToolUse "guardrails block-no-verify"
+hook::stdin_cut_short_notice() {
+  local msg="$2: hook stdin was cut short, so this tool call ran unchecked. If it recurs, the host is starved; see the stdin_read_timeout option."
+  echo "$msg" >&2
+  hook::emit_channels "" "" "$msg"
+}
+
+# systemMessage-only variant for a hook with nothing for the model. Notification
+# hooks do not use it, per https://code.claude.com/docs/en/hooks#notification
+# (as of 2026-10-11; recheck when that section starts showing a Notification
+# hook's systemMessage).
+hook::emit_system_message() {
+  hook::emit_channels "" "" "$1"
+}
+
+# hook::session_agent_to <session-var> <agent-var> <input>: the latch keys from
+# the raw hook input, jq-free. Session is session_id, else no-session. Agent is
+# agent_id, else the transcript_path basename (the main agent), else no-agent.
+# Both are reduced to [A-Za-z0-9_-] so they can name a marker file.
+hook::session_agent_to() {
+  local __hu_sa_s="no-session" __hu_sa_a="no-agent"
+  if [[ "$3" =~ \"session_id\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
+    __hu_sa_s="${BASH_REMATCH[1]//[^A-Za-z0-9_-]/-}"
+  fi
+  if [[ "$3" =~ \"agent_id\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then
+    __hu_sa_a="${BASH_REMATCH[1]}"
+  elif [[ "$3" =~ \"transcript_path\"[[:space:]]*:[[:space:]]*\"(([^\"\\]|\\.)*)\" ]]; then
+    __hu_sa_a="${BASH_REMATCH[1]##*/}"
+    __hu_sa_a="${__hu_sa_a%.jsonl}"
+  fi
+  __hu_sa_a="${__hu_sa_a//[^A-Za-z0-9_-]/-}"
+  printf -v "$1" '%s' "$__hu_sa_s"
+  printf -v "$2" '%s' "${__hu_sa_a:-no-agent}"
+}
+
+# hook::_state_dir_to <var> <subdir>: $CLAUDE_PLUGIN_DATA/<subdir>, created on
+# first use, with files older than 7 days pruned once per process. Returns 1
+# when there is no data directory or it cannot be created.
+hook::_state_dir_to() {
+  [[ -n "${CLAUDE_PLUGIN_DATA:-}" ]] || return 1
+  local __hu_sd="${CLAUDE_PLUGIN_DATA%/}/$2"
+  # `-d` before `mkdir -p`: mkdir is an external command.
+  if [[ ! -d "$__hu_sd" ]]; then
+    mkdir -p "$__hu_sd" 2>/dev/null || return 1
+  fi
+  # One `find` per hook process and directory: the markers are tiny and the
+  # process short-lived, so a second walk could find nothing newly stale.
+  local __hu_sd_var="_HOOK_PRUNED_${2//[^A-Za-z0-9_]/_}"
+  if [[ -z "${!__hu_sd_var:-}" ]]; then
+    find "$__hu_sd" -maxdepth 1 -type f -mtime +7 -delete 2>/dev/null || true
+    printf -v "$__hu_sd_var" '%s' 1
+  fi
+  printf -v "$1" '%s' "$__hu_sd"
+}
+
+# hook::_file_key_to <var> <file>: a marker-name fragment for <file>. Lossy
+# (characters outside [A-Za-z0-9._-] fold to _ and a long path keeps its tail),
+# so callers store the full path in the marker and compare it.
+hook::_file_key_to() {
+  local __hu_fk="${2//[^A-Za-z0-9._-]/_}"
+  ((${#__hu_fk} > 120)) && __hu_fk="${__hu_fk: -120}"
+  printf -v "$1" '%s' "$__hu_fk"
+}
+
+# hook::_claim <path>: create <path> only if absent, atomically (noclobber), so
+# of two hooks racing on one marker exactly one wins. 0 when this call created
+# it, 1 when it already existed, 2 when it could not be written.
+hook::_claim() {
+  (set -C && : >"$1") 2>/dev/null && return 0
+  [[ -e "$1" ]] && return 1
+  return 2
+}
+
+# Skip-notice latch: one notice per channel, never renewed. Returns 0 when
+# either channel is due, 1 when neither is, and sets:
+#   HOOK_NOTICE_TO_MODEL  1 on the first call for <key> in this (session, agent)
+#   HOOK_NOTICE_TO_USER   1 on the first call for <key> in this session
+# hook::emit_skip_notice reads both. The model marker keys on the agent because
+# a subagent does not see what the main agent was told; the user marker keys on
+# the session because the user sees one transcript. prerequisites.mjs probe
+# writes the user marker at SessionStart, so its notice and this one are one
+# notice to the user.
+#
+# HOOK_NOTICE_KIND is `full` when the user channel is due, `model` when only
+# the model channel is, `silent` otherwise; it remains for callers that read
+# it, and HOOK_NOTICE_TO_USER says the same. A third argument is accepted and
+# ignored.
+#
+# Fails open toward visibility: without a data directory both channels are due
+# every time.
+#   hook::notice_once "my-plugin-jq" "$INPUT" && hook::emit_skip_notice ...
+HOOK_NOTICE_TO_MODEL=1
+HOOK_NOTICE_TO_USER=1
+HOOK_NOTICE_KIND=full
+
+# shellcheck disable=SC2034 # HOOK_NOTICE_KIND is read by callers, not here
+hook::notice_once() {
+  local key="$1" session agent dir
+  HOOK_NOTICE_TO_MODEL=1
+  HOOK_NOTICE_TO_USER=1
+  HOOK_NOTICE_KIND=full
+  hook::session_agent_to session agent "${2:-}"
+  hook::_state_dir_to dir skip-notices || return 0
+  local model="$dir/${key}.${session}.${agent}" user="$dir/${key}.${session}.user"
+  hook::_claim "$model"
+  case $? in 1) HOOK_NOTICE_TO_MODEL=0 ;; 2) return 0 ;; *) ;; esac
+  hook::_claim "$user"
+  case $? in 1) HOOK_NOTICE_TO_USER=0 ;; 2) return 0 ;; *) ;; esac
+  if [[ "$HOOK_NOTICE_TO_USER" == 1 ]]; then
+    return 0
+  elif [[ "$HOOK_NOTICE_TO_MODEL" == 1 ]]; then
+    HOOK_NOTICE_KIND=model
+    return 0
+  fi
+  HOOK_NOTICE_KIND=silent
+  HOOK_NOTICE_TO_MODEL=1
+  HOOK_NOTICE_TO_USER=1
+  return 1
+}
+
+# hook::once_per_file <key> <input> <file>: 0 the first time per (key, session,
+# agent, file), 1 after. For a hint worth giving once per file rather than on
+# every report about it. Fails open (0) without a data directory.
+#   hook::once_per_file my-plugin-hint "$INPUT" "$FILE" && ctx+=" <hint>"
+hook::once_per_file() {
+  local session agent dir fkey prev=""
+  hook::session_agent_to session agent "$2"
+  hook::_state_dir_to dir skip-notices || return 0
+  hook::_file_key_to fkey "$3"
+  local marker="$dir/${1}.${session}.${agent}.f.${fkey}"
+  if [[ -f "$marker" ]]; then
+    IFS= read -r prev <"$marker" || true
+    [[ "$prev" == "$3" ]] && return 1
+  fi
+  printf '%s\n' "$3" 2>/dev/null >"$marker" || true
+  return 0
+}
+
+# Best-effort jq-free extraction of tool_input.file_path from the raw hook
+# input, for the applicability pre-filter an extension-scoped hook runs BEFORE
+# its jq gate — a missing-jq notice must never fire for an edit the hook would
+# not process anyway (e.g. a README edit reaching a workflow-lint hook whose
+# Write|Edit matcher is broader than its file filter). The value is returned
+# JSON-escaped (backslashes doubled); that is fine for extension/segment
+# matching, which is all the pre-filter does. Returns 1 when no file_path is
+# present.
+#   hook::raw_file_path_to RAW_FILE "$INPUT" || exit 0
+# <var> is left unchanged on a return of 1.
+hook::raw_file_path_to() {
+  [[ "$2" =~ \"file_path\"[[:space:]]*:[[:space:]]*\"(([^\"\\]|\\.)*)\" ]] || return 1
+  [[ -n "${BASH_REMATCH[1]}" ]] || return 1
+  printf -v "$1" '%s' "${BASH_REMATCH[1]}"
+}
+
+# Print form, kept for the hooks that capture it once at top level
+# (instruction-placement's index-drift hook), off the per-edit prologue.
+#   RAW_FILE=$(hook::raw_file_path "$INPUT") || exit 0
+hook::raw_file_path() {
+  local __hu_raw
+  hook::raw_file_path_to __hu_raw "$1" || return 1
+  printf '%s' "$__hu_raw"
+}
+
+# ============================================================================
+# THE jq GATE — TWO POSTURES, AND WHY THERE ARE TWO (#2146)
+# ============================================================================
+#
+# A hook that cannot parse its payload has exactly two honest moves: let the
+# tool call through (fail OPEN) or deny it (fail CLOSED). This library offers
+# both, as two named functions, and the choice belongs to the CALLING hook. The
+# reasoning lives HERE, at the decision point, not only at the call sites —
+# before #2146 every call site asserted a posture in a comment and nothing where
+# the posture is actually implemented explained it.
+#
+# hook::require jq              fails OPEN  — the default, and correct for most hooks
+# hook::require_jq_blocking fails CLOSED — for a guard that blocks an
+#                                          irreversible operation
+#
+# WHY FAIL OPEN IS THE DEFAULT. Most hooks in this marketplace are advisory or
+# cosmetic: a formatter, a lint pass, a context injector, a detect-then-judge
+# oracle. Their finding is a prompt, not a verdict. Blocking a user's tool call
+# because an OPTIONAL formatting hook could not find an OPTIONAL dependency
+# inverts the cost: the guard's job is worth less than the work it would stop.
+# The once per session and agent notice is what keeps that degradation honest
+# rather than silent — the user and the agent are both told the hook is off.
+#
+# WHY A MINORITY MUST FAIL CLOSED. A guard whose job is to stop an IRREVERSIBLE
+# operation cannot be a suggestion. Its whole value is that it is there when
+# nobody is watching, and "somewhere without jq" is not an exotic state — it is
+# the default state of a machine that has not installed one dependency. A guard
+# that a missing dependency silently switches off is not a guard; it is a guard
+# on machines that happen to be configured for it. #2146 measured this: with jq
+# unreachable, `git push --force origin main` was ALLOWED by block-dangerous-git,
+# after one notice, for the rest of the session.
+#
+# WHICH HOOKS ARE IN THAT MINORITY — the criterion is mechanical, and it is
+# INTERNAL CONSISTENCY, not a taste judgment about severity. A hook belongs in
+# the fail-closed class iff it ALREADY fails closed on some other
+# "I cannot parse this input" condition. Every such hook today carries a
+# MAX_COMMAND_LEN ceiling above which an unparsable command is denied unread;
+# plugins/guardrails/hooks/require-jq-posture.test.sh derives the class from
+# that ceiling, so no list here can go stale.
+#
+# block-dangerous-git and block-no-verify, the first two members, held two
+# opposite postures toward the same question (an over-long command is hostile
+# and blocked; a missing jq is fine and skipped), which meant an author who
+# could not fit a dangerous command under 16384 characters could simply be on a
+# machine without jq. That contradiction is what #2146 reports, and resolving it
+# is all this class is for. Because the posture test derives membership from the
+# ceiling, the class cannot drift.
+#
+# DELIBERATELY NOT WIDENED. block-noncanonical-commit also exits 2. It stays
+# fail-open: it guards a message shape, trivially reversible, and it does not
+# hold the internal contradiction above. Severity is a slope; "already fails
+# closed elsewhere in the same script" is a line. If it grows a length ceiling
+# it joins the class, and the posture test will say so.
+#
+# WHY TWO FUNCTIONS RATHER THAN ONE WITH A FLAG. A parameter's OMITTED value has
+# to default to something, and the safe-looking default (fail open, matching
+# today's behavior) means a guard that should fail closed but whose flag someone
+# forgot fails open SILENTLY — which is the exact defect class #2146 reports,
+# reintroduced at the API. Two names make the posture greppable, make the
+# fail-closed path impossible to reach by accident, and make omission a visible
+# choice instead of an invisible default.
+
+# Fail-OPEN dependency gate — the default. For hooks whose work cannot proceed
+# without the tool <id> (jq, almost always) and whose finding is advisory. When
+# <id> is absent: the hook::prereq_notice_to notice (once per channel, see
+# hook::notice_once), then exit 0. Place after hook::check_enabled (and after
+# any jq-free applicability pre-filter), passing the buffered stdin for session
+# scoping. See the posture block above for when this is the WRONG choice.
+#   hook::require jq PostToolUse my-plugin "$INPUT"
+#
+# <plugin> names the notice and its latch key; it never installs.
+#
+# No PATH line: a guard chain under one dispatcher (guardrails run-guards.sh)
+# can still exit 2 after this notice. Where exit-2 stderr goes: on PreToolUse,
+# https://code.claude.com/docs/en/hooks#exit-code-2 (Claude receives it as the
+# tool's error); on other events,
+# https://code.claude.com/docs/en/hooks#exit-code-2-behavior-per-event. Where
+# exit-0 stderr goes: https://code.claude.com/docs/en/hooks#exit-code-0. As of
+# 2026-10-11; recheck when the exit-code-2 section stops saying Claude receives
+# a blocked PreToolUse hook's stderr, the exit-code-2-behavior-per-event table
+# changes which events show exit-2 stderr to Claude, or the exit-code-0 section
+# starts showing exit-0 stderr to Claude. The --no-path and stderr-deny notes
+# below rest on this record.
+hook::require() {
+  command -v "$1" >/dev/null 2>&1 && return 0
+  local model user
+  if hook::prereq_notice_to model user "$1" "${4:-}" --label "$3" --no-path; then
+    hook::emit_skip_notice "$2" "$model" "$user"
+  fi
+  exit 0
+}
+
+# hook::prereq_notice_to <model-var> <user-var> <id> <input> [--label <name>]
+#                        [--where <phrase>] [--install <text>] [--no-path]
+# Composes the notice for a missing prerequisite <id> from the plugin's
+# prerequisites.json entry (docs/conventions/prerequisites/) and latches it per
+# channel through hook::notice_once with key `<label>-<id>`. Returns 0 when a
+# notice is due (each var holds its text, or "" when that channel is already
+# told), 1 when neither channel is due. The caller emits, usually through
+# hook::emit_skip_notice <event> "$model" "$user".
+#   --label    the notice prefix and latch key (default: the plugin name)
+#   --where    where the tool was looked for (default: "not on the hook PATH",
+#              plus " or at <path>" per detect.local_bin entry)
+#   --install  replaces the install route on the user line
+#   --no-path  skips the `PATH probed:` line it otherwise writes to stderr;
+#              pass it when the process can still exit 2 (the stderr routing
+#              is in the hook::require record above)
+# The user line renders the same fields prerequisites.mjs probe renders at
+# SessionStart, so the two cannot drift.
+hook::prereq_notice_to() {
+  local __hu_prn_m="$1" __hu_prn_u="$2" __hu_prn_id="$3" __hu_prn_in="$4"
+  local __hu_prn_label="" __hu_prn_where="" __hu_prn_inst="" __hu_prn_inst_set=0 __hu_prn_path=1
+  shift 4
+  while (($#)); do
+    case "$1" in
+    --label) __hu_prn_label="$2" ;;
+    --where) __hu_prn_where="$2" ;;
+    --install)
+      __hu_prn_inst="$2"
+      __hu_prn_inst_set=1
+      ;;
+    --no-path)
+      __hu_prn_path=0
+      shift
+      continue
+      ;;
+    *) ;;
+    esac
+    shift 2 || break
+  done
+  local __hu_prn_d __hu_prn_i __hu_prn_c __hu_prn_local __hu_prn_name
+  hook::prerequisite_fields_to __hu_prn_d __hu_prn_i __hu_prn_c "$__hu_prn_id" __hu_prn_local __hu_prn_name
+  [[ -n "$__hu_prn_label" ]] || __hu_prn_label="$__hu_prn_name"
+  printf -v "$__hu_prn_m" '%s' ""
+  printf -v "$__hu_prn_u" '%s' ""
+  hook::notice_once "${__hu_prn_label}-${__hu_prn_id}" "$__hu_prn_in" || return 1
+  if [[ -z "$__hu_prn_where" ]]; then
+    __hu_prn_where="not on the hook PATH${__hu_prn_local:+ or at $__hu_prn_local}"
+  fi
+  ((__hu_prn_inst_set)) || __hu_prn_inst="${__hu_prn_i:+Install ($__hu_prn_i).}"
+  local __hu_prn_head="$__hu_prn_label: $__hu_prn_id $__hu_prn_where. $__hu_prn_d"
+  local __hu_prn_tail="No further notice this session; $__hu_prn_c diagnoses."
+  ((__hu_prn_path)) && printf 'PATH probed: %s\n' "${PATH:-<unset>}" >&2
+  [[ "$HOOK_NOTICE_TO_MODEL" == 1 ]] && printf -v "$__hu_prn_m" '%s' "$__hu_prn_head $__hu_prn_tail"
+  [[ "$HOOK_NOTICE_TO_USER" == 1 ]] &&
+    printf -v "$__hu_prn_u" '%s' "$__hu_prn_head ${__hu_prn_inst:+$__hu_prn_inst }Hooks read Claude Code's PATH, not your shell profile. $__hu_prn_tail"
+  return 0
+}
+
+# hook::prerequisite_fields_to <degrade-var> <install-var> <check-var> <id>
+#                              [<local-bin-var> [<plugin-var>]]
+# Reads the declared entry for <id> from ${CLAUDE_PLUGIN_ROOT}/prerequisites.json
+# with bash alone. An entry runs from its "id" to the next "id", so each entry
+# carries "id" as its first key, as the convention's example does. <install-var>
+# gets the install map as `key: value; key: value`, the form prerequisites.mjs
+# prints; <local-bin-var> gets detect.local_bin joined with " or ". An absent
+# file or entry gives generic text and a check command derived from the plugin
+# root, which also names the plugin.
+hook::prerequisite_fields_to() {
+  local __hu_d="The hook skips its work." __hu_i="" __hu_c="" __hu_l=""
+  local __hu_root="${CLAUDE_PLUGIN_ROOT:-}" __hu_txt="" __hu_name="" __hu_m
+  local __hu_s='[[:space:]]*:[[:space:]]*"(([^"\\]|\\.)*)"'
+  if [[ -r "$__hu_root/prerequisites.json" ]]; then
+    __hu_txt=$(<"$__hu_root/prerequisites.json")
+    if [[ "$__hu_txt" =~ \"id\"[[:space:]]*:[[:space:]]*\"$4\"(.*) ]]; then
+      __hu_txt="${BASH_REMATCH[1]}"
+      __hu_txt="${__hu_txt%%\"id\"[[:space:]]*:*}"
+      [[ "$__hu_txt" =~ \"degrade\"$__hu_s ]] && __hu_d="${BASH_REMATCH[1]}"
+      [[ "$__hu_txt" =~ \"check\"$__hu_s ]] && __hu_c="${BASH_REMATCH[1]}"
+      if [[ "$__hu_txt" =~ \"install\"[[:space:]]*:[[:space:]]*\{([^}]*)\} ]]; then
+        __hu_m="${BASH_REMATCH[1]}"
+        while [[ "$__hu_m" =~ \"([^\"]+)\"$__hu_s(.*) ]]; do
+          __hu_i+="${__hu_i:+; }${BASH_REMATCH[1]}: ${BASH_REMATCH[2]}"
+          __hu_m="${BASH_REMATCH[4]}"
+        done
+      fi
+      if [[ "$__hu_txt" =~ \"local_bin\"[[:space:]]*:[[:space:]]*\[([^]]*)\] ]]; then
+        __hu_m="${BASH_REMATCH[1]}"
+        while [[ "$__hu_m" =~ \"(([^\"\\]|\\.)*)\"(.*) ]]; do
+          __hu_l+="${__hu_l:+ or }${BASH_REMATCH[1]}"
+          __hu_m="${BASH_REMATCH[3]}"
+        done
+      fi
+      __hu_d="${__hu_d//\\\"/\"}"
+    fi
+  fi
+  # The plugin name as prerequisites.mjs takes it: plugin.json's name, else the
+  # root's directory name (its parent's for a versioned cache directory).
+  if [[ -r "$__hu_root/.claude-plugin/plugin.json" ]] &&
+    [[ "$(<"$__hu_root/.claude-plugin/plugin.json")" =~ \"name\"$__hu_s ]]; then
+    __hu_name="${BASH_REMATCH[1]}"
+  else
+    __hu_name="${__hu_root%/}"
+    __hu_name="${__hu_name##*/}"
+    if [[ "$__hu_name" =~ ^[0-9] ]]; then
+      __hu_name="${__hu_root%/*}"
+      __hu_name="${__hu_name##*/}"
+    fi
+  fi
+  __hu_name="${__hu_name:-plugin}"
+  if [[ -z "$__hu_c" ]]; then
+    __hu_c="/${__hu_name}:check"
+    [[ -d "$__hu_root/skills/check-prerequisites" ]] && __hu_c+="-prerequisites"
+  fi
+  printf -v "$1" '%s' "$__hu_d"
+  printf -v "$2" '%s' "$__hu_i"
+  printf -v "$3" '%s' "$__hu_c"
+  [[ -n "${5:-}" ]] && printf -v "$5" '%s' "$__hu_l"
+  [[ -n "${6:-}" ]] && printf -v "$6" '%s' "$__hu_name"
+  return 0
+}
+
+# Fail-CLOSED jq gate (#2146) — for a guard that blocks an irreversible
+# operation, per the membership criterion in the posture block above. When jq is
+# absent the tool call is DENIED (exit 2) with one line naming jq and its
+# install page.
+#
+# No notice_once here, and that is deliberate: this message is not a once per
+# session and agent heads-up about a degraded hook, it is THIS tool call's denial
+# reason. Suppressing the repeat would leave a later denial unexplained. It also
+# goes to stderr rather than through hook::emit_channels, as the exit-2 channel
+# (see the hook::require record on exit-2 stderr).
+#
+# The kill switch stays the only supported deliberate bypass: a consumer who
+# genuinely wants the operation unguarded on a jq-less machine sets the guard's
+# own *_enabled userConfig option to false, which hook::check_enabled honors
+# BEFORE this gate is ever reached. The deny reason does not name it: the reason
+# reaches the model, and the switch is the user's call (the plugin README names
+# it).
+# DISCLOSED COST, because it is not small: this guard runs on EVERY Bash and
+# PowerShell tool call, and without jq it cannot read the command at all — so it
+# cannot tell a dangerous one from a safe one and denies both. On a machine
+# without jq every such tool call is blocked until jq is installed or the kill
+# switch is set. That is the hard dependency #2146 accepted when it chose this
+# posture over a jq-free substring pre-check, which was rejected for
+# manufacturing a false sense of coverage.
+#
+# $1 = the hook's own id (for the message). A second argument, the guard's
+# *_enabled option name, is accepted and not used.
+#   hook::require_jq_blocking guardrails-block-dangerous-git block_dangerous_git_enabled
+hook::require_jq_blocking() {
+  command -v jq >/dev/null 2>&1 && return 0
+  echo "BLOCKED: jq is not on PATH, so $1 cannot read the command and denies every Bash and PowerShell call. Ask the user to install jq (https://jqlang.org/download/)." >&2
+  exit 2
+}
+
+# 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.
+#
+# Every path helper below is spelled `hook::<name>_to <var> <path>` and stores
+# its answer in the caller's variable: one convention, no per-call-site choice.
+# The `_to` helpers keep their locals under a `__hu_` prefix so the caller's
+# variable name cannot collide with them.
+hook::normalize_path_to() {
+  local __hu_p="${2//\\//}"
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32)
+    if [[ "$__hu_p" =~ ^/([a-zA-Z])/ || "$__hu_p" =~ ^([a-zA-Z]):/ ]]; then
+      local __hu_rest="${__hu_p:2}"
+      printf -v "$1" '%s' "${BASH_REMATCH[1]^}:${__hu_rest,,}"
+      return 0
+    fi
+    ;;
+  *) ;; # POSIX hosts: case-sensitive FS, no drive fold — pass through below
+  esac
+  printf -v "$1" '%s' "$__hu_p"
+}
+
+# Expand Windows 8.3 short-name components (KYLESE~1 → KyleSexton) on
+# Windows/MSYS hosts, where GNU realpath resolves symlinks but leaves short
+# names as-is. Without this a short-form file_path — the shape Claude Code's
+# own scratchpad paths take — fails the membership prefix comparison below and
+# an IN-project file is silently skipped. 8.3 generation is a PER-VOLUME
+# property (`fsutil 8dot3name query <vol>`): a checkout on a volume that
+# generates short names hits this constantly while one on a non-generating
+# volume can never reproduce it, so the guard must not assume either.
+#
+# `cygpath -m` (form conversion only) is compared against `cygpath -l -m`
+# (long names via Win32), and the path is replaced only when the two DIFFER —
+# a legitimate long name that merely contains '~' (foo~bar.md) converts
+# identically both ways and passes through byte-for-byte untouched. A genuine
+# expansion returns mixed form (C:/...); the membership comparison normalizes
+# both sides, so the form change is absorbed, and any such path failed the
+# comparison outright before this expansion existed. Fail-open on this host
+# class: cygpath ships with Git Bash (the documented Windows bash), so its
+# absence or failure keeps the resolver's answer unchanged — degrading to the
+# pre-expansion comparison, same doctrine as the resolver fallback below.
+hook::expand_8dot3_to() {
+  local __hu_p="$2"
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32) ;;
+  *)
+    printf -v "$1" '%s' "$__hu_p"
+    return 0
+    ;;
+  esac
+  if [[ "$__hu_p" == *~* ]] && command -v cygpath >/dev/null 2>&1; then
+    local __hu_plain __hu_long
+    if __hu_plain=$(cygpath -m -- "$__hu_p" 2>/dev/null) &&
+      __hu_long=$(cygpath -l -m -- "$__hu_p" 2>/dev/null) &&
+      [[ -n "$__hu_long" && "$__hu_long" != "$__hu_plain" ]]; then
+      printf -v "$1" '%s' "$__hu_long"
+      return 0
+    fi
+  fi
+  printf -v "$1" '%s' "$__hu_p"
+}
+
+# hook::_physical_builtin_to <var> <path>...
+# realpath's answer for every <path>, one per line, with no realpath process:
+# one subshell reads the physical form with `cd -P` (a directory, or a file's
+# directory plus its name). Linux only, and only for the shapes where the two
+# agree: every path absolute with no `//`, each an existing directory or an
+# existing non-symlink file whose name is not `.` or `..`, and every `cd -P`
+# succeeding. Anything else returns 1 and the caller runs realpath as before:
+# a symlinked file, a missing path, a relative one, a directory it cannot
+# enter. Git Bash and macOS keep realpath, whose drive and short-name forms
+# this does not reproduce. `builtin cd`, so an exported `cd` function cannot
+# answer for it.
+hook::_physical_builtin_to() {
+  [[ "${OSTYPE:-}" == linux* ]] || return 1
+  local __hu_pb_dest="$1" __hu_pb_p __hu_pb_out
+  shift
+  for __hu_pb_p in "$@"; do
+    [[ "$__hu_pb_p" == /* && "$__hu_pb_p" != *//* && "$__hu_pb_p" != *$'\n'* ]] || return 1
+  done
+  __hu_pb_out=$(
+    for __hu_pb_p in "$@"; do
+      if [[ -d "$__hu_pb_p" ]]; then
+        builtin cd -P -- "$__hu_pb_p" 2>/dev/null || exit 1
+        printf '%s\n' "$PWD"
+      else
+        [[ -e "$__hu_pb_p" && ! -L "$__hu_pb_p" ]] || exit 1
+        __hu_pb_d=${__hu_pb_p%/*} __hu_pb_b=${__hu_pb_p##*/}
+        [[ -n "$__hu_pb_b" && "$__hu_pb_b" != . && "$__hu_pb_b" != .. ]] || exit 1
+        builtin cd -P -- "${__hu_pb_d:-/}" 2>/dev/null || exit 1
+        printf '%s\n' "${PWD%/}/$__hu_pb_b"
+      fi
+    done
+  ) || return 1
+  printf -v "$__hu_pb_dest" '%s' "$__hu_pb_out"
+}
+
+# Canonicalize to a physical path — symlinks resolved, Windows 8.3 short names
+# expanded — 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) and a short-form
+# spelling of an in-project path cannot dodge it (the long-form prefix would
+# never match). 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 still receives the lexical path unchanged — 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 — but the answer is now DISTINGUISHABLE: return 1 and
+# HOOK_PHYSICAL_PATH_UNRESOLVED=1. Success (return 0) means resolved; advisory
+# callers that ignore the status keep today's behavior. Guards that must fail
+# closed branch on the return code or on HOOK_PHYSICAL_PATH_UNRESOLVED. The 8.3
+# expansion applies only on the resolver's success path: consumers that fail
+# closed on an unresolved signature must not see a form-converted path instead.
+# shellcheck disable=SC2034  # public contract: advisory callers may read HOOK_PHYSICAL_PATH_UNRESOLVED
+hook::physical_path_to() {
+  local __hu_r=""
+  HOOK_PHYSICAL_PATH_UNRESOLVED=0
+  if hook::_physical_builtin_to __hu_r "$2"; then
+    hook::expand_8dot3_to "$1" "$__hu_r"
+    return 0
+  fi
+  if __hu_r=$(realpath -- "$2" 2>/dev/null) || __hu_r=$(readlink -f -- "$2" 2>/dev/null); then
+    if [[ -n "$__hu_r" ]]; then
+      hook::expand_8dot3_to "$1" "$__hu_r"
+      return 0
+    fi
+  fi
+  # No cygpath fallback: cygpath converts spellings but does not follow
+  # symlinks, and guards that fail closed on this return would exempt a temp
+  # symlink pointing into the repository.
+  HOOK_PHYSICAL_PATH_UNRESOLVED=1
+  printf -v "$1" '%s' "$2"
+  return 1
+}
+
+# Kept as a print form because markdown-format's directory walk resolves each
+# queue entry inline inside an array append, where a capture is the shape.
+# shellcheck disable=SC2034  # public contract: advisory callers may read HOOK_PHYSICAL_PATH_UNRESOLVED
+hook::physical_path() {
+  local __hu_v __hu_rc=0
+  hook::physical_path_to __hu_v "$1" || __hu_rc=$?
+  printf '%s' "$__hu_v"
+  return "$__hu_rc"
+}
+
+# --- Per-process physical-path cache --------------------------------------
+# The membership guard resolves the same few directories on every call: the
+# project root and this host's temp roots. Their physical form does not change
+# within one hook process, so each spelling is resolved once and remembered in
+# three parallel indexed arrays (keys, values, resolver status). Plain arrays,
+# not an associative array, so the cache runs on Bash 3.2. Only directories are
+# meant to live here for a process lifetime; hook::read_file_path forgets the
+# edited file's entry as soon as it has read it, so a later call in the same
+# process sees the file as it is then.
+_HOOK_PHYS_KEYS=()
+_HOOK_PHYS_VALS=()
+_HOOK_PHYS_RCS=()
+_HOOK_PHYS_I=-1
+
+# hook::_phys_cache_index <path>: sets _HOOK_PHYS_I to the slot holding <path>,
+# returns 1 when it is not cached. A forgotten slot has an empty key, which no
+# real path can match.
+hook::_phys_cache_index() {
+  local __hu_i
+  [[ -n "$1" ]] || return 1
+  for ((__hu_i = 0; __hu_i < ${#_HOOK_PHYS_KEYS[@]}; __hu_i++)); do
+    if [[ "${_HOOK_PHYS_KEYS[__hu_i]}" == "$1" ]]; then
+      _HOOK_PHYS_I=$__hu_i
+      return 0
+    fi
+  done
+  return 1
+}
+
+hook::_phys_cache_forget() {
+  hook::_phys_cache_index "$1" && _HOOK_PHYS_KEYS[_HOOK_PHYS_I]=""
+  return 0
+}
+
+# hook::_physical_cached_to <var> <path>: hook::physical_path_to through the
+# cache. Same value, same return status, same HOOK_PHYSICAL_PATH_UNRESOLVED as
+# the uncached call; a miss resolves the one path and stores it.
+# shellcheck disable=SC2034  # public contract: advisory callers may read HOOK_PHYSICAL_PATH_UNRESOLVED
+hook::_physical_cached_to() {
+  if hook::_phys_cache_index "$2"; then
+    printf -v "$1" '%s' "${_HOOK_PHYS_VALS[_HOOK_PHYS_I]}"
+    HOOK_PHYSICAL_PATH_UNRESOLVED=${_HOOK_PHYS_RCS[_HOOK_PHYS_I]}
+    return "${_HOOK_PHYS_RCS[_HOOK_PHYS_I]}"
+  fi
+  local __hu_v __hu_rc=0
+  hook::physical_path_to __hu_v "$2" || __hu_rc=$?
+  if [[ -n "$2" ]]; then
+    _HOOK_PHYS_KEYS+=("$2")
+    _HOOK_PHYS_VALS+=("$__hu_v")
+    _HOOK_PHYS_RCS+=("$__hu_rc")
+  fi
+  printf -v "$1" '%s' "$__hu_v"
+  return "$__hu_rc"
+}
+
+# hook::_physical_prime <path>...: resolve every uncached path with ONE
+# realpath process and store the answers. realpath resolves each argument on
+# its own and prints one line per argument in argument order, so the batch
+# answer for a path is the same string the per-path call returns; the 8.3
+# expansion is applied per answer exactly as hook::physical_path_to does. Any
+# doubt (a path carrying a newline, a non-zero exit, a line count that does not
+# match) stores nothing and leaves the per-path resolver to answer lazily, so
+# the batch can only ever save work, never change an answer. readlink -f hosts
+# (no realpath) skip the batch for the same reason.
+hook::_physical_prime() {
+  local -a __hu_todo=()
+  local __hu_p __hu_out __hu_i __hu_seen="" __hu_v
+  for __hu_p in "$@"; do
+    [[ -n "$__hu_p" ]] || continue
+    [[ "$__hu_p" == *$'\n'* ]] && return 0
+    case "$__hu_seen" in
+    *"|$__hu_p|"*) continue ;;
+    *) ;; # first sighting
+    esac
+    __hu_seen="$__hu_seen|$__hu_p|"
+    hook::_phys_cache_index "$__hu_p" && continue
+    __hu_todo+=("$__hu_p")
+  done
+  ((${#__hu_todo[@]} > 1)) || return 0
+  if ! hook::_physical_builtin_to __hu_out "${__hu_todo[@]}"; then
+    command -v realpath >/dev/null 2>&1 || return 0
+    # portability-ok: realpath with several operands is GNU and BSD alike; a host whose realpath rejects it fails the exit-status check and falls back per path
+    __hu_out=$(realpath -- "${__hu_todo[@]}" 2>/dev/null) || return 0
+  fi
+  local -a __hu_lines=()
+  local __hu_glob=0
+  [[ $- == *f* ]] || __hu_glob=1
+  set -f
+  local IFS=$'\n'
+  # shellcheck disable=SC2206 # splitting realpath's one-line-per-operand output is the intent
+  __hu_lines=($__hu_out)
+  ((__hu_glob)) && set +f
+  ((${#__hu_lines[@]} == ${#__hu_todo[@]})) || return 0
+  for ((__hu_i = 0; __hu_i < ${#__hu_todo[@]}; __hu_i++)); do
+    [[ -n "${__hu_lines[__hu_i]}" ]] || return 0
+    hook::expand_8dot3_to __hu_v "${__hu_lines[__hu_i]}"
+    _HOOK_PHYS_KEYS+=("${__hu_todo[__hu_i]}")
+    _HOOK_PHYS_VALS+=("$__hu_v")
+    _HOOK_PHYS_RCS+=(0)
+  done
+  return 0
+}
+
+# The temp-root candidates hook::under_temp_root compares against: the
+# environment's own answer (TMPDIR/TMP/TEMP) plus the POSIX defaults, never a
+# hardcoded platform assumption. Existing directories only, each spelling
+# once, in _HOOK_TEMP_CANDS.
+#
+# On a Windows bash (msys, cygwin, win32) with cygpath, the drive spellings of
+# those candidates follow them: Cygwin bash reports TEMP and TMP as `/tmp`, so
+# without cygpath no candidate is spelled `C:/...` and a drive-spelled target
+# never matches. The POSIX spellings stay, because a `/tmp/...` target must
+# still match. The long form (`cygpath -l -m`) comes before the mixed form
+# (`cygpath -m`) when the two differ, so a long target matches without
+# resolving an 8.3 spelling. The drive spellings are looked up once per process
+# for a given candidate list: one cygpath process, plus a second only when a
+# mixed answer carries an 8.3 `~`. A cygpath that fails, or answers with the
+# wrong number of lines, adds nothing, which leaves the POSIX candidates as
+# they were. `--no-drive` stops after the environment and POSIX spellings, so a
+# caller's lexical pre-match spawns no process.
+_HOOK_TEMP_CANDS=()
+_HOOK_TEMP_WIN_KEY=""
+_HOOK_TEMP_WIN=()
+hook::_temp_root_candidates() {
+  local __hu_cand __hu_seen=""
+  _HOOK_TEMP_CANDS=()
+  for __hu_cand in "${TMPDIR:-}" "${TMP:-}" "${TEMP:-}" /tmp /var/tmp; do
+    [[ -n "$__hu_cand" && -d "$__hu_cand" ]] || continue
+    case "$__hu_seen" in
+    *"|$__hu_cand|"*) continue ;;
+    *) ;; # first sighting of this candidate
+    esac
+    __hu_seen="$__hu_seen|$__hu_cand|"
+    _HOOK_TEMP_CANDS+=("$__hu_cand")
+  done
+  [[ "${1:-}" == --no-drive ]] && return 0
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32) ;;
+  *) return 0 ;; # POSIX hosts: the candidates above are the whole set
+  esac
+  ((${#_HOOK_TEMP_CANDS[@]})) || return 0
+  if [[ "$_HOOK_TEMP_WIN_KEY" != "$__hu_seen" ]]; then
+    hook::_temp_win_spellings "${_HOOK_TEMP_CANDS[@]}" || return 0
+    _HOOK_TEMP_WIN_KEY=$__hu_seen
+  fi
+  for __hu_cand in ${_HOOK_TEMP_WIN[@]+"${_HOOK_TEMP_WIN[@]}"}; do
+    [[ -n "$__hu_cand" && -d "$__hu_cand" ]] || continue
+    case "$__hu_seen" in
+    *"|$__hu_cand|"*) continue ;;
+    *) ;; # first sighting of this spelling
+    esac
+    __hu_seen="$__hu_seen|$__hu_cand|"
+    _HOOK_TEMP_CANDS+=("$__hu_cand")
+  done
+}
+
+# hook::_split_lines <text> <count>: <text> split on newlines into the
+# caller's __hu_lines array. Returns 1 unless it held exactly <count> non-empty
+# lines.
+hook::_split_lines() {
+  local __hu_glob=0 IFS=$'\n'
+  [[ $- == *f* ]] || __hu_glob=1
+  set -f
+  # shellcheck disable=SC2206 # splitting one-line-per-operand output is the intent
+  __hu_lines=($1)
+  ((__hu_glob)) && set +f
+  ((${#__hu_lines[@]} == $2))
+}
+
+# hook::_temp_win_spellings <candidate>...: the drive spellings of every
+# candidate in _HOOK_TEMP_WIN, long forms first. Returns 1, storing nothing,
+# when there is no cygpath or the mixed-form answer cannot be trusted.
+hook::_temp_win_spellings() {
+  local __hu_out __hu_i
+  local -a __hu_lines=() __hu_mixed=() __hu_tilde=()
+  command -v cygpath >/dev/null 2>&1 || return 1
+  for __hu_out in "$@"; do
+    [[ "$__hu_out" == *$'\n'* ]] && return 1
+  done
+  __hu_out=$(cygpath -m -- "$@" 2>/dev/null) || return 1
+  hook::_split_lines "$__hu_out" "$#" || return 1
+  __hu_mixed=("${__hu_lines[@]}")
+  _HOOK_TEMP_WIN=()
+  for __hu_out in "${__hu_mixed[@]}"; do
+    if [[ "$__hu_out" == *~* ]]; then __hu_tilde+=("$__hu_out"); fi
+  done
+  if ((${#__hu_tilde[@]})) &&
+    __hu_out=$(cygpath -l -m -- "${__hu_tilde[@]}" 2>/dev/null) &&
+    hook::_split_lines "$__hu_out" "${#__hu_tilde[@]}"; then
+    for ((__hu_i = 0; __hu_i < ${#__hu_tilde[@]}; __hu_i++)); do
+      if [[ "${__hu_lines[__hu_i]}" != "${__hu_tilde[__hu_i]}" ]]; then
+        _HOOK_TEMP_WIN+=("${__hu_lines[__hu_i]}")
+      fi
+    done
+  fi
+  _HOOK_TEMP_WIN+=("${__hu_mixed[@]}")
+}
+
+# True when <normalized-path> sits inside one of this host's temp trees.
+# Both arguments and candidates go through the same canonicalize+normalize
+# pipeline as the membership comparison, because the same directory has several
+# spellings: on a Windows bash the temp tree is `/tmp` and also a `C:/...`
+# path, and `realpath` resolves the drive form to a drive path while leaving
+# `/tmp` as `/tmp`. The environment does not reliably carry the drive form
+# (Cygwin bash reports TEMP and TMP as `/tmp`), so the candidate list adds it
+# through cygpath (see hook::_temp_root_candidates). Neither form alone matches a
+# `file_path` that could arrive in either, so every candidate is compared and a
+# match on any one is a match. Duplicates are resolved once, and each
+# candidate's physical form is remembered for the process (see the cache
+# above), so a second call costs no resolver process.
+#
+# Raw-spelling shortcut: when the caller vouches that <normalized-path> is a
+# PHYSICAL path (_HOOK_UTR_TARGET_PHYSICAL=1, set only by hook::read_file_path
+# after the resolver succeeded), a candidate whose raw normalized spelling is
+# already a prefix of the target is a match without resolving it. A physical
+# path contains no symlink component, so a candidate that spells one of its
+# prefixes names a chain of real directories whose physical form is that same
+# prefix; the resolver would answer the same. A candidate that does not match
+# raw is still resolved, so a symlinked temp root (macOS /tmp) is found the
+# way it always was. Without the vouch the shortcut is off and every candidate
+# is resolved, exactly as before. Note that hook::read_file_path primes every
+# candidate into the cache with one batched realpath before calling here, so
+# on that path the shortcut skips a lookup, not a process; the batch is what
+# saves the processes. A direct caller without the batch saves the resolver.
+#
+# On a Windows Git Bash host (msys, cygwin, win32) the target goes through
+# hook::normalize_path_to like the candidates, so its `/c/...` and `C:/...`
+# spellings both compare. A POSIX host leaves it untouched: `\` is a filename
+# byte there, and folding it could make a root-level `tmp\x` compare as under
+# `/tmp`. Precondition: the target is already lexically normalized (as
+# a guard's own path normalizer produces) or physically resolved, with no `..`
+# segment; nothing here resolves `..`.
+#   hook::under_temp_root "$norm_path" && ...
+_HOOK_UTR_TARGET_PHYSICAL=0
+hook::under_temp_root() {
+  local target="$1" cand norm phys
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32) hook::normalize_path_to target "$target" ;;
+  *) ;; # POSIX hosts: compare the target as given
+  esac
+  hook::_temp_root_candidates
+  for cand in ${_HOOK_TEMP_CANDS[@]+"${_HOOK_TEMP_CANDS[@]}"}; do
+    if ((_HOOK_UTR_TARGET_PHYSICAL)); then
+      hook::normalize_path_to norm "$cand"
+      if [[ "$norm" != / ]]; then
+        norm="${norm%/}"
+        if [[ -n "$norm" && ("$target" == "$norm" || "$target" == "$norm"/*) ]]; then
+          return 0
+        fi
+      fi
+    fi
+    hook::_physical_cached_to phys "$cand" || :
+    hook::normalize_path_to norm "$phys"
+    # The filesystem root as a temp candidate contains every absolute path;
+    # trimming its only slash would empty the candidate and discard it.
+    [[ "$norm" == / ]] && return 0
+    norm="${norm%/}"
+    [[ -n "$norm" ]] || continue
+    # Equality counts: a project root that IS the temp root must answer true,
+    # otherwise the exemption below would not recognize it as a temp-rooted
+    # project and would reject every file in it.
+    [[ "$target" == "$norm" || "$target" == "$norm"/* ]] && return 0
+  done
+  return 1
+}
+
+# True when <dir> sits inside a git working tree. Unsets locating globals so an
+# inherited GIT_DIR cannot make an out-of-tree directory look in-tree — the same
+# discipline markdown-format adopted for #972.
+#   hook::in_git_working_tree "$(dirname "$file")" && ...
+hook::in_git_working_tree() {
+  (
+    unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_CEILING_DIRECTORIES \
+      GIT_DISCOVERY_ACROSS_FILESYSTEM
+    git -C "$1" rev-parse --show-toplevel
+  ) >/dev/null 2>&1
+}
+
+# True when the repository enclosing <file> gitignores it (hook-precision rule
+# 6, #4671). A rewrite of an ignored file has no `git checkout` to undo it.
+#
+# `git check-ignore` consults the index unless --no-index is passed, so a
+# TRACKED file matching an ignore pattern reads as not ignored: a file under
+# version control is part of the reviewable artifact whatever the patterns say.
+# Exit 0 = ignored, 1 = not ignored, 128 = error; only 0 answers true.
+# https://git-scm.com/docs/git-check-ignore (fetched 2026-09-28; recheck when
+# that page changes the exit codes or the tracked-file behavior without --no-index)
+#
+# FAILS TOWARD ACTING. Git absent, the directory gone, no repository, or a
+# check-ignore error all answer false, so the hook runs as before. A skip that
+# fired on an error would disable the hook invisibly and repo-wide.
+#
+# Git's repository-selection environment is cleared: an inherited
+# GIT_DIR/GIT_WORK_TREE from a wrapper that launched the session would make
+# another repository answer, and a linked worktree under a path its parent
+# ignores (`.claude/worktrees/**`) would read every file as ignored. The
+# check runs from the file's own directory with a `./<base>` spelling, so no
+# path translation is needed on Windows Git Bash.
+#   hook::file_is_gitignored "$FILE" && ...
+hook::file_is_gitignored() {
+  local file="$1" dir base
+  dir="${file%/*}" base="${file##*/}"
+  command -v git >/dev/null 2>&1 || return 1
+  [[ -n "$base" && "$dir" != "$file" ]] || return 1
+  (
+    unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_CEILING_DIRECTORIES \
+      GIT_DISCOVERY_ACROSS_FILESYSTEM
+    cd "${dir:-/}" 2>/dev/null || exit 1
+    git check-ignore -q -- "./$base" 2>/dev/null
+  )
+}
+
+# True when the hook should leave <file> alone because the repository ignores
+# it and the plugin's `<plugin>_lint_gitignored` opt-in, passed as <opt-in>
+# from its CLAUDE_PLUGIN_OPTION_* mirror, is not the string "true". Any other
+# value, including garbage, reads as the manifest default (false).
+#   hook::gitignored_out_of_scope "${CLAUDE_PLUGIN_OPTION_X_LINT_GITIGNORED:-false}" "$FILE" && emit_skipped
+hook::gitignored_out_of_scope() {
+  [[ "$1" == "true" ]] && return 1
+  hook::file_is_gitignored "$2"
+}
+
+# --- Builtin JSON helpers ----------------------------------------------------
+# hook::read_file_path and hook::emit_telemetry used to spend a jq process each
+# on every hook run. On Windows Git Bash one spawn costs tens of milliseconds,
+# so the helpers here handle the well-formed shapes those two functions see in
+# practice with shell builtins and hand anything they cannot PROVE to the
+# unchanged jq path. The contract is "the bytes jq would produce, or fall
+# back", never "close enough".
+#
+# What the builtin paths rely on: the text is valid JSON. Every hook payload
+# reaching hook::read_file_path has passed hook::buffer_stdin's validation
+# (jq's, or hook::_json_object_proven's for an object the skeleton below
+# accepts), and every telemetry data object is built with jq. The helpers
+# verify the structure they walk (terminated strings, well-formed tokens,
+# properly nested brackets, one root, no raw control bytes inside strings,
+# only escapes jq accepts). What they do not check is jq's parser depth limit
+# (jq 1.8.2 rejects 9999 nested levels), which no hook payload comes near.
+#
+# Why no scanning: on this repo's Windows hosts bash regex matching and the
+# `%%`/`##` pattern operators cost about a microsecond per character, so a
+# 60 KB Write payload would cost more than the jq process they replace. The
+# only string operations used on the whole payload are literal-substring
+# replacement, `[[ == *x* ]]` containment, IFS word splitting and offset
+# slicing, all of which run at C speed.
+#
+# They run in the C locale. Under a UTF-8 locale bash does those operations
+# per multibyte character, and the cost grows faster than the payload: 297 ms
+# for a 37 KB Edit payload against about 8 ms under C, on WSL. In C one
+# character is one byte, so the offsets and lengths recorded while splitting
+# are byte counts, and the bodies sliced with them are the payload's own bytes;
+# a non-ASCII byte is ordinary string data, as JSON allows. The entry points
+# (hook::_fast_file_path_to, hook::_fast_fields, hook::json_compact_to,
+# hook::_json_object_proven) re-enter through hook::_c_locale, so every
+# skeleton, and the cached one, is built under the same locale.
+
+# hook::_c_locale <command> [args...]
+# Run <command> with LC_ALL=C and put the caller's LC_ALL back afterwards,
+# exported or not, set or unset, whatever <command> returned. An explicit save
+# and restore rather than `local LC_ALL`, whose unwind is not relied on to reset
+# the shell's locale on every bash these hooks support (the eol-normalizer
+# plugin's EOL library uses the same idiom). Nothing it wraps starts a process.
+hook::_c_locale() {
+  local __hu_lc_set=${LC_ALL+x} __hu_lc=${LC_ALL-} __hu_lc_rc=0
+  LC_ALL=C
+  "$@" || __hu_lc_rc=$?
+  if [[ -n "$__hu_lc_set" ]]; then LC_ALL=$__hu_lc; else unset LC_ALL; fi
+  return "$__hu_lc_rc"
+}
+
+# hook::_json_split <text>
+# Split <text> at every unescaped double quote into the global array
+# _HOOK_JSON_PARTS: even indices hold the structural text between strings, odd
+# indices hold string bodies. Before splitting, every `\\` and `\"` pair is
+# replaced by `@@` (same length), so a quote that survives is a real string
+# delimiter and a body's ORIGINAL bytes are ${text:offset:length}. Returns 1
+# when the text is too large, its quotes do not pair up, or it holds more
+# strings than the callers' loops are meant to walk. The neutralized text is
+# kept in _HOOK_JSON_NT.
+_HOOK_JSON_PARTS=()
+_HOOK_JSON_NT=""
+hook::_json_split() {
+  local __hu_s="$1" __hu_t __hu_q __hu_n
+  ((${#__hu_s} <= 65536)) || return 1
+  __hu_t=${__hu_s//"\\\\"/@@}
+  __hu_t=${__hu_t//"\\\""/@@}
+  _HOOK_JSON_NT=$__hu_t
+  __hu_q=${__hu_t//\"/}
+  __hu_n=$((${#__hu_t} - ${#__hu_q}))
+  ((__hu_n % 2 == 0)) || return 1
+  ((__hu_n <= 2000)) || return 1
+  local __hu_glob=0
+  [[ $- == *f* ]] || __hu_glob=1
+  set -f
+  local IFS='"'
+  # shellcheck disable=SC2206 # splitting on IFS='"' is the whole point
+  _HOOK_JSON_PARTS=($__hu_t)
+  ((__hu_glob)) && set +f
+  ((${#_HOOK_JSON_PARTS[@]} % 2 == 1)) || return 1
+  return 0
+}
+
+# hook::_json_skeleton <text>
+# Split <text> (hook::_json_split), record each string body's byte offset in
+# _HOOK_JSON_OFF, and build _HOOK_JSON_SK: the structural text with every
+# string replaced by a numbered placeholder `"#<index>"` and all JSON
+# whitespace removed. The skeleton is small (no string bodies), so regex and
+# per-token work on it is cheap. Returns 1 unless the text is exactly one JSON
+# value by the JSON grammar (well-formed tokens, whitespace only between them,
+# objects as key:value lists, arrays as value lists, brackets nested and
+# closed once) whose strings carry only escapes jq accepts and no raw control
+# byte, which jq rejects.
+_HOOK_JSON_SK=""
+_HOOK_JSON_OFF=()
+# The last text and its verdict. A hook that primes several fields and then
+# reads its file path asks for the same payload's skeleton twice in one
+# process; the parts, offsets and skeleton are still those of that text, so the
+# second ask is a string comparison rather than a second walk.
+_HOOK_JSON_SK_TEXT=""
+_HOOK_JSON_SK_RC=""
+hook::_json_skeleton() {
+  local __hu_s="$1" __hu_i __hu_n __hu_part __hu_off=0 __hu_sk="" __hu_g="" __hu_prev __hu_esc __hu_c
+  # The regex checks run where the C locale's regex reads bytes (Linux,
+  # macOS). A Windows bash's regex decodes UTF-8 even under C, where
+  # [[:cntrl:]] matches a C1 character the glob check does not, so it keeps the
+  # glob checks.
+  local __hu_rx=1 __hu_partcntrl=1
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32) __hu_rx=0 ;;
+  *) ;;
+  esac
+  local __hu_cntrl='[[:cntrl:]]'
+  local __hu_badesc='\\([^/bfnrtu]|$|u(.?.?.?$|[^0-9a-fA-F]|.[^0-9a-fA-F]|..[^0-9a-fA-F]|...[^0-9a-fA-F]))'
+  if [[ -n "$_HOOK_JSON_SK_RC" && "$__hu_s" == "$_HOOK_JSON_SK_TEXT" ]]; then
+    return "$_HOOK_JSON_SK_RC"
+  fi
+  _HOOK_JSON_SK_TEXT=$__hu_s
+  _HOOK_JSON_SK_RC=1
+  hook::_json_split "$__hu_s" || return 1
+  if ((__hu_rx)); then
+    # Every escape must be one jq accepts, or jq rejects the whole text. In
+    # the neutralized text `\\` and `\"` are already `@@`, so every surviving
+    # backslash starts one of the other escapes, `\/ \b \f \n \r \t` or
+    # `\uXXXX`; one followed by anything else, or by `u` and fewer than four
+    # hex digits, is an invalid escape. One search over the whole text: a
+    # surviving backslash is never followed by a quote, so a match never spans
+    # two parts, and one in the structural text is not JSON either.
+    [[ "$_HOOK_JSON_NT" =~ $__hu_badesc ]] && return 1
+    # No control byte anywhere: no string body can hold one.
+    [[ "$__hu_s" =~ $__hu_cntrl ]] || __hu_partcntrl=0
+  fi
+  __hu_n=${#_HOOK_JSON_PARTS[@]}
+  _HOOK_JSON_OFF=()
+  for ((__hu_i = 0; __hu_i < __hu_n; __hu_i++)); do
+    __hu_part=${_HOOK_JSON_PARTS[__hu_i]}
+    if ((__hu_i % 2 == 0)); then
+      __hu_sk+=$__hu_part
+      __hu_g+=$__hu_part
+    else
+      _HOOK_JSON_OFF[__hu_i]=$__hu_off
+      if ((__hu_rx)); then
+        # A regex search: on a large body it runs about ten times faster than
+        # the equivalent `*[...]*` glob match.
+        ((__hu_partcntrl)) && [[ "$__hu_part" =~ $__hu_cntrl ]] && return 1
+      else
+        [[ "$__hu_part" == *[[:cntrl:]]* ]] && return 1
+        if [[ "$__hu_part" == *\\* ]]; then
+          # Delete every well-formed escape (literal glob substitution); a
+          # backslash that survives is an invalid escape. Six literal two-byte
+          # replacements: a quoted backslash before a bracket expression does
+          # not survive bash's pattern quoting.
+          __hu_esc=${__hu_part//'\u'[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]/}
+          for __hu_c in / b f n r t; do
+            __hu_esc=${__hu_esc//"\\$__hu_c"/}
+          done
+          [[ "$__hu_esc" == *\\* ]] && return 1
+        fi
+      fi
+      __hu_sk+="\"#$__hu_i\""
+      __hu_g+='"'
+    fi
+    __hu_off=$((__hu_off + ${#__hu_part} + 1))
+  done
+  # Run the structural text, each string a lone `"`, through the JSON grammar
+  # with a few whole-string rewrites instead of a regex per token.
+  # Whitespace is allowed only between tokens: between two characters that
+  # are neither punctuation nor whitespace it splits a token (`tr ue`) or # spellchecker:disable-line
+  # separates two scalars, neither of which is JSON. Anywhere else it goes.
+  local __hu_ws=$' \t\n\r'
+  local __hu_wsre="[^][{}:,$__hu_ws][$__hu_ws]+[^][{}:,$__hu_ws]"
+  [[ "$__hu_g" =~ $__hu_wsre ]] && return 1
+  __hu_g=${__hu_g//[$__hu_ws]/}
+  # Every token between punctuation is a string, a number, true, false or null.
+  local __hu_sc=${__hu_g//[][\{\}:,]/ }
+  local __hu_scre='^ *(("|true|false|null|-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][-+]?[0-9]+)?) +)*$'
+  [[ "$__hu_sc " =~ $__hu_scre ]] || return 1
+  # Grammar: each non-string scalar becomes `v`; a string followed by `,`, `]`
+  # or `}` is a value, so it becomes `v` too, and one followed by `:` stays `s`
+  # (a key). The root is wrapped as `<k:<root>>`, with marks no other rule
+  # makes or consumes. Then reduce until nothing changes, in this order each
+  # pass: `k:v` is `K`; `s:v` is a member `m`; `v,v` is `v`; `m,m` is `m`;
+  # `{m}`, `{}`, `[v]` and `[]` are `v`. Each rewrite undoes one grammar
+  # production, so the text is one JSON value exactly when it reduces to
+  # `<K>`. `v,v` is an array's element list only because `k:v` and `s:v` were
+  # folded just before it: a value after a key or at the root is already
+  # inside a `K` or an `m`, so the rule cannot join it with a stray value.
+  # A structure this long is no hook envelope (about 100 characters); it goes
+  # to jq, which answers the same, rather than through thousands of passes.
+  ((${#__hu_g} <= 8192)) || return 1
+  __hu_g=${__hu_g//[^\]\[\{\}:,\"]/v}
+  while [[ "$__hu_g" == *vv* ]]; do __hu_g=${__hu_g//vv/v}; done
+  __hu_g="<k:${__hu_g//\"/s}>"
+  __hu_g=${__hu_g//s,/v,}
+  __hu_g=${__hu_g//s\]/v]}
+  __hu_g=${__hu_g//s\}/v\}}
+  __hu_g=${__hu_g//s>/v>}
+  while :; do
+    __hu_prev=$__hu_g
+    __hu_g=${__hu_g//k:v/K}
+    __hu_g=${__hu_g//s:v/m}
+    while [[ "$__hu_g" == *v,v* ]]; do __hu_g=${__hu_g//v,v/v}; done
+    while [[ "$__hu_g" == *m,m* ]]; do __hu_g=${__hu_g//m,m/m}; done
+    __hu_g=${__hu_g//\{m\}/v}
+    __hu_g=${__hu_g//\{\}/v}
+    __hu_g=${__hu_g//\[v\]/v}
+    __hu_g=${__hu_g//\[\]/v}
+    [[ "$__hu_g" != "$__hu_prev" ]] || break
+  done
+  [[ "$__hu_g" == '<K>' ]] || return 1
+  _HOOK_JSON_SK=${__hu_sk//[$' \t\n\r']/}
+  _HOOK_JSON_SK_RC=0
+  return 0
+}
+
+# hook::_json_object_proven <text>
+# The builtin stand-in for hook::buffer_stdin's `jq -e .` probe: 0 when
+# hook::_json_skeleton accepts <text> and its root is an object, which jq -e
+# accepts too (an object is truthy); 1 when not proven, and the caller runs jq.
+hook::_json_object_proven() {
+  [[ "${LC_ALL-}" == C ]] || {
+    hook::_c_locale hook::_json_object_proven "$@"
+    return
+  }
+  hook::_json_skeleton "$1" && [[ "$_HOOK_JSON_SK" == \{* ]]
+}
+
+# hook::json_unescape_to <var> <raw>
+# Decode a JSON string body (the bytes between the quotes) into <var>. Handles
+# \" \\ \/ \b \f \n \r \t and \uXXXX for U+0001 to U+007F. Returns 1 on any
+# other escape (a \u outside that range, U+0000 which bash cannot hold, or an
+# invalid escape), leaving the caller to fall back to jq.
+hook::json_unescape_to() {
+  local __hu_raw="$2" __hu_out="" __hu_pre __hu_c __hu_hex __hu_oct __hu_ch
+  while [[ "$__hu_raw" == *\\* ]]; do
+    __hu_pre=${__hu_raw%%\\*}
+    __hu_out+=$__hu_pre
+    __hu_raw=${__hu_raw:${#__hu_pre}+1}
+    __hu_c=${__hu_raw:0:1}
+    __hu_raw=${__hu_raw:1}
+    case "$__hu_c" in
+    '"') __hu_out+='"' ;;
+    "\\") __hu_out+="\\" ;;
+    '/') __hu_out+='/' ;;
+    b) __hu_out+=$'\b' ;; # portability-ok: bash ANSI-C backspace byte, not a GNU grep word boundary
+    f) __hu_out+=$'\f' ;;
+    n) __hu_out+=$'\n' ;;
+    r) __hu_out+=$'\r' ;;
+    t) __hu_out+=$'\t' ;;
+    u)
+      __hu_hex=${__hu_raw:0:4}
+      [[ "$__hu_hex" =~ ^00[0-7][0-9a-fA-F]$ ]] || return 1
+      [[ "$__hu_hex" == 0000 ]] && return 1
+      __hu_raw=${__hu_raw:4}
+      printf -v __hu_oct '%03o' "$((16#$__hu_hex))"
+      printf -v __hu_ch '%b' "\\0$__hu_oct"
+      __hu_out+=$__hu_ch
+      ;;
+    *) return 1 ;;
+    esac
+  done
+  __hu_out+=$__hu_raw
+  printf -v "$1" '%s' "$__hu_out"
+}
+
+# hook::_fast_file_path_to <var> <payload>
+# The builtin answer to `jq -r '(.tool_input.file_path // empty) |
+# gsub("\r";"")'` followed by the `$(...)` capture. Returns
+#   0  proven: <var> holds exactly what jq would have printed
+#   1  proven absent: jq would have printed nothing (the guard skips)
+#   2  not proven: run jq
+# Proof, on top of hook::_json_skeleton's structural checks: the root is an
+# object; exactly one string in the whole payload decodes to `tool_input` and
+# exactly one to `file_path` (so neither a duplicate key nor a same-named key
+# in another object can change jq's answer); `tool_input` is a key of the root
+# (depth 1, key position) whose value is a flat object (no nested object or
+# array, else jq); and inside it `file_path` is a key with a plain string
+# value. A payload where `file_path` names a value or sits in another object
+# has no `.tool_input.file_path`, which jq reports as nothing. Key strings are
+# compared AFTER decoding their escapes, so a key spelled with \u escapes is
+# still recognized; a body longer than any escaped spelling of either name is
+# skipped without decoding.
+hook::_fast_file_path_to() {
+  [[ "${LC_ALL-}" == C ]] || {
+    hook::_c_locale hook::_fast_file_path_to "$@"
+    return
+  }
+  local __hu_s="$2" __hu_i __hu_n __hu_part __hu_body __hu_ti=-1 __hu_fp=-1 __hu_m __hu_raw __hu_pre __hu_re __hu_file
+  hook::_json_skeleton "$__hu_s" || return 2
+  [[ "$_HOOK_JSON_SK" == \{* ]] || return 2
+  __hu_n=${#_HOOK_JSON_PARTS[@]}
+  for ((__hu_i = 1; __hu_i < __hu_n; __hu_i += 2)); do
+    __hu_part=${_HOOK_JSON_PARTS[__hu_i]}
+    ((${#__hu_part} <= 60)) || continue
+    # A part with no `@` is its body verbatim (the split rewrote only `\\` and
+    # `\"`, each to `@@`), so it skips a slice that copies the whole payload.
+    if [[ "$__hu_part" == *@* ]]; then
+      __hu_body=${__hu_s:${_HOOK_JSON_OFF[__hu_i]}:${#__hu_part}}
+    else
+      __hu_body=$__hu_part
+    fi
+    if [[ "$__hu_body" == *\\* ]]; then
+      hook::json_unescape_to __hu_body "$__hu_body" || continue
+    fi
+    case "$__hu_body" in
+    tool_input)
+      ((__hu_ti < 0)) || return 2
+      __hu_ti=$__hu_i
+      ;;
+    file_path)
+      ((__hu_fp < 0)) || return 2
+      __hu_fp=$__hu_i
+      ;;
+    *) ;;
+    esac
+  done
+  ((__hu_fp >= 0)) || return 1
+  ((__hu_ti >= 0)) || return 1
+  __hu_re="(^|[{,])\"#$__hu_ti\":\\{([^][{}]*)\\}"
+  if [[ "$_HOOK_JSON_SK" =~ $__hu_re ]]; then
+    __hu_body=${BASH_REMATCH[2]}
+    __hu_pre=${_HOOK_JSON_SK%%\"#"$__hu_ti"\"*}
+    # Depth of the key: opening brackets minus closing ones before it must be
+    # exactly one, i.e. a direct member of the root object.
+    local __hu_o1=${__hu_pre//\{/} __hu_o2=${__hu_pre//\[/} __hu_c1=${__hu_pre//\}/} __hu_c2=${__hu_pre//\]/}
+    local __hu_depth=$(((${#__hu_pre} - ${#__hu_o1}) + (${#__hu_pre} - ${#__hu_o2}) - (${#__hu_pre} - ${#__hu_c1}) - (${#__hu_pre} - ${#__hu_c2})))
+    ((__hu_depth == 1)) || return 2
+  else
+    return 2
+  fi
+  __hu_re="(^|,)\"#$__hu_fp\":\"#([0-9]+)\"(,|$)"
+  if [[ "$__hu_body" =~ $__hu_re ]]; then
+    __hu_m=${BASH_REMATCH[2]}
+  elif [[ "$__hu_body" == *\"#$__hu_fp\"* ]]; then
+    return 2
+  else
+    return 1
+  fi
+  __hu_raw=${__hu_s:${_HOOK_JSON_OFF[__hu_m]}:${#_HOOK_JSON_PARTS[__hu_m]}}
+  if [[ "$__hu_raw" == *\\* ]]; then
+    hook::json_unescape_to __hu_file "$__hu_raw" || return 2
+  else
+    __hu_file=$__hu_raw
+  fi
+  __hu_file=${__hu_file//$'\r'/}
+  while [[ "$__hu_file" == *$'\n' ]]; do
+    __hu_file=${__hu_file%$'\n'}
+  done
+  printf -v "$1" '%s' "$__hu_file"
+  return 0
+}
+
+# The associative-array availability guard for hook::_fast_fields below, split
+# out as its own predicate so the pre-4.0 path stays reachable in tests on a
+# modern host: BASH_VERSINFO is readonly, so it cannot be shadowed, but a test
+# can override this function after sourcing. Same class as
+# hook::read_supports_nchars. macOS ships Bash 3.2 and these hooks document
+# 3.2+ support, so below the floor the answer is jq's, not a wrong one. Not a
+# consumer seam.
+hook::_fast_fields_supported() {
+  ((BASH_VERSINFO[0] >= 4))
+}
+
+# hook::_fast_fields <payload> <filter>...
+# The builtin answer to hook::jq_fields' jq program for the filters that
+# program is usually given: `.key` and `.key.sub`, identifier keys only, each
+# optionally followed by ` // false | tostring` (the guards' `replace_all`
+# read). With that suffix an absent or null value is `false`, and a boolean is
+# proven too: jq prints `true` or `false`.
+# Returns
+#   0  proven: HOOK_JQ_FIELDS holds, per filter, exactly what jq prints for
+#      `((<filter>) // "" | tostring)` with CR stripped, and HOOK_JQ_FIELDS_NUL
+#      is 0 (a NUL escape in any requested value is a proof failure)
+#   2  not proven: run jq
+# Any other filter shape is not proven. Proof, on top of hook::_json_skeleton's
+# structural checks (which include every escape jq accepts and no raw control
+# byte): the root is an object; every key named by a filter decodes from
+# exactly ONE string in the whole payload, so neither a duplicate key nor a
+# same-named key in another object nor a value spelled like the key can change
+# jq's answer; a top-level key is a direct member of the root; a nested key's
+# parent is a flat object (no container inside it, else jq); and each
+# requested value is a plain string or null, or the key is absent. A number,
+# boolean, object or array value is handed to jq for its `tostring`, a string
+# whose escapes hook::json_unescape_to does not decode (a NUL, a \u past
+# U+007F) likewise. Key strings are compared after decoding, so a key spelled
+# with \u escapes is still recognized; a body longer than any escaped spelling
+# of a requested key name is skipped without decoding. That bound is six times
+# the longest requested key name: a filter key is an ASCII identifier, and an
+# identifier character's longest escaped spelling is `\uXXXX`, six bytes.
+#
+# Bash 4.0+ only (the `local -A` index below), so the call site gates it on
+# hook::_fast_fields_supported and a 3.2 shell runs jq instead.
+hook::_fast_fields() {
+  [[ "${LC_ALL-}" == C ]] || {
+    hook::_c_locale hook::_fast_fields "$@"
+    return
+  }
+  local __hu_s="$1"
+  shift
+  local -a __hu_k1=() __hu_k2=() __hu_df=()
+  local __hu_f __hu_i __hu_n __hu_part __hu_body __hu_re __hu_raw __hu_val __hu_j __hu_nil
+  local __hu_ident='[A-Za-z_][A-Za-z0-9_]*'
+  local __hu_cap=0
+  __hu_re="^\\.($__hu_ident)(\\.($__hu_ident))?( // false \\| tostring)?\$"
+  for __hu_f in "$@"; do
+    [[ "$__hu_f" =~ $__hu_re ]] || return 2
+    __hu_k1+=("${BASH_REMATCH[1]}")
+    __hu_k2+=("${BASH_REMATCH[3]}")
+    __hu_df+=("${BASH_REMATCH[4]:+1}")
+    ((${#BASH_REMATCH[1]} > __hu_cap)) && __hu_cap=${#BASH_REMATCH[1]}
+    ((${#BASH_REMATCH[3]} > __hu_cap)) && __hu_cap=${#BASH_REMATCH[3]}
+  done
+  # The skip bound: six bytes per character of the longest requested key name,
+  # the width of `\uXXXX`. A shorter bound proves the wrong thing rather than
+  # costing time: a key whose body exceeds it is never decoded, so a key that
+  # IS present is reported absent, and a key of 11 or more characters spelled
+  # entirely in \u escapes is missed the same way.
+  __hu_cap=$((__hu_cap * 6))
+  hook::_json_skeleton "$__hu_s" || return 2
+  [[ "$_HOOK_JSON_SK" == \{* ]] || return 2
+  # Every string body that decodes to a requested key name, by name: the part
+  # index, or -1 once a second body decodes to the same name.
+  local -A __hu_idx=()
+  local -A __hu_want=()
+  for __hu_f in "${__hu_k1[@]}" "${__hu_k2[@]}"; do
+    [[ -n "$__hu_f" ]] && __hu_want[$__hu_f]=1
+  done
+  __hu_n=${#_HOOK_JSON_PARTS[@]}
+  for ((__hu_i = 1; __hu_i < __hu_n; __hu_i += 2)); do
+    __hu_part=${_HOOK_JSON_PARTS[__hu_i]}
+    ((${#__hu_part} <= __hu_cap)) || continue
+    # A part with no `@` is its body verbatim (the split rewrote only `\\` and
+    # `\"`, each to `@@`), so it skips a slice that copies the whole payload.
+    if [[ "$__hu_part" == *@* ]]; then
+      __hu_body=${__hu_s:${_HOOK_JSON_OFF[__hu_i]}:${#__hu_part}}
+    else
+      __hu_body=$__hu_part
+    fi
+    if [[ "$__hu_body" == *\\* ]]; then
+      hook::json_unescape_to __hu_body "$__hu_body" || continue
+    fi
+    [[ -n "$__hu_body" && -n "${__hu_want[$__hu_body]+x}" ]] || continue
+    if [[ -n "${__hu_idx[$__hu_body]+x}" ]]; then
+      __hu_idx[$__hu_body]=-1
+    else
+      __hu_idx[$__hu_body]=$__hu_i
+    fi
+  done
+  local -a __hu_vals=()
+  local __hu_ti __hu_fi __hu_pre __hu_o1 __hu_o2 __hu_c1 __hu_c2 __hu_depth __hu_tok
+  for ((__hu_j = 0; __hu_j < ${#__hu_k1[@]}; __hu_j++)); do
+    # What jq prints for an absent or null value: `// ""` gives the empty
+    # string, `// false | tostring` gives `false`.
+    __hu_nil=${__hu_df[__hu_j]:+false}
+    __hu_ti=${__hu_idx[${__hu_k1[__hu_j]}]--2}
+    ((__hu_ti != -1)) || return 2
+    if ((__hu_ti == -2)); then
+      __hu_vals+=("$__hu_nil") # no string in the payload spells the key: absent
+      continue
+    fi
+    # The key must be a direct member of the root: a key position at depth
+    # exactly one. Anywhere else (a value, a deeper key) the root has no such
+    # member, and the unique spelling means nothing else could be one.
+    __hu_re="(^|[{,])\"#$__hu_ti\":(\"#[0-9]+\"|\\{[^][{}]*\\}|null|true|false|[-0-9][^,}]*|\\[|\\{)"
+    if ! [[ "$_HOOK_JSON_SK" =~ $__hu_re ]]; then
+      __hu_vals+=("$__hu_nil")
+      continue
+    fi
+    __hu_tok=${BASH_REMATCH[2]}
+    __hu_pre=${_HOOK_JSON_SK%%\"#"$__hu_ti"\"*}
+    __hu_o1=${__hu_pre//\{/}
+    __hu_o2=${__hu_pre//\[/}
+    __hu_c1=${__hu_pre//\}/}
+    __hu_c2=${__hu_pre//\]/}
+    __hu_depth=$(((${#__hu_pre} - ${#__hu_o1}) + (${#__hu_pre} - ${#__hu_o2}) - (${#__hu_pre} - ${#__hu_c1}) - (${#__hu_pre} - ${#__hu_c2})))
+    if ((__hu_depth != 1)); then
+      __hu_vals+=("$__hu_nil")
+      continue
+    fi
+    if [[ -z "${__hu_k2[__hu_j]}" ]]; then
+      case "$__hu_tok" in
+      \"#*) __hu_raw=${__hu_tok:2:${#__hu_tok}-3} ;;
+      null) __hu_vals+=("$__hu_nil") && continue ;;
+      true | false)
+        [[ -n "${__hu_df[__hu_j]}" ]] || return 2
+        __hu_vals+=("$__hu_tok") && continue
+        ;;
+      *) return 2 ;;
+      esac
+    else
+      case "$__hu_tok" in
+      null) __hu_vals+=("$__hu_nil") && continue ;;
+      \{*\}) ;;      # a flat object: its members are the only place the key can be
+      *) return 2 ;; # a string, number, boolean, array, or an object with a container inside
+      esac
+      __hu_fi=${__hu_idx[${__hu_k2[__hu_j]}]--2}
+      ((__hu_fi != -1)) || return 2
+      if ((__hu_fi == -2)); then
+        __hu_vals+=("$__hu_nil")
+        continue
+      fi
+      __hu_body=${__hu_tok:1:${#__hu_tok}-2}
+      __hu_re="(^|,)\"#$__hu_fi\":(\"#[0-9]+\"|null|true|false|[-0-9][^,]*)(,|\$)"
+      if ! [[ "$__hu_body" =~ $__hu_re ]]; then
+        __hu_vals+=("$__hu_nil") # not a key of the parent; unique, so not one anywhere
+        continue
+      fi
+      __hu_tok=${BASH_REMATCH[2]}
+      case "$__hu_tok" in
+      \"#*) __hu_raw=${__hu_tok:2:${#__hu_tok}-3} ;;
+      null) __hu_vals+=("$__hu_nil") && continue ;;
+      true | false)
+        [[ -n "${__hu_df[__hu_j]}" ]] || return 2
+        __hu_vals+=("$__hu_tok") && continue
+        ;;
+      *) return 2 ;;
+      esac
+    fi
+    __hu_val=${__hu_s:${_HOOK_JSON_OFF[__hu_raw]}:${#_HOOK_JSON_PARTS[__hu_raw]}}
+    if [[ "$__hu_val" == *\\* ]]; then
+      hook::json_unescape_to __hu_val "$__hu_val" || return 2
+    fi
+    __hu_val=${__hu_val//$'\r'/}
+    __hu_vals+=("$__hu_val")
+  done
+  HOOK_JQ_FIELDS=("${__hu_vals[@]}")
+  HOOK_JQ_FIELDS_NUL=0
+  return 0
+}
+
+# hook::dirname_to <var> <path>: dirname with builtins for the resolver's
+# answer. Strips the last segment; a bare name lives in `.`, a root-level file
+# in `/`. The path comes from realpath, so the trailing-slash and doubled-slash
+# spellings dirname also collapses never occur here.
+hook::dirname_to() {
+  local __hu_d="${2%/*}"
+  [[ "$__hu_d" == "$2" ]] && __hu_d=.
+  [[ -n "$__hu_d" ]] || __hu_d=/
+  printf -v "$1" '%s' "$__hu_d"
+}
+
+# Print the arguments joined by NUL bytes, no trailing NUL: the byte stream
+# hook::read_file_path read from stdin, rebuilt for the jq fallback.
+hook::_print_nul_joined() {
+  local __hu_first=1 __hu_c
+  for __hu_c in "$@"; do
+    ((__hu_first)) || printf '\0'
+    __hu_first=0
+    printf '%s' "$__hu_c"
+  done
+}
+
+# hook::json_compact_to <var> <object-json>
+# The bytes `jq -c .` prints for <object-json>, when that can be proven with
+# builtins: JSON whitespace between tokens removed, everything else verbatim.
+# jq's own output, compact or pretty, satisfies the proof, which is what every
+# telemetry data builder in this marketplace produces (jq -c, jq -n, or a
+# compact literal). Returns 1 when the text is not a single object, or a
+# string carries something jq would re-encode (a \u or \/ escape, an escape
+# outside the JSON set, a raw control byte), or the structure fails
+# hook::_json_skeleton; the caller then runs jq.
+hook::json_compact_to() {
+  [[ "${LC_ALL-}" == C ]] || {
+    hook::_c_locale hook::json_compact_to "$@"
+    return
+  }
+  local __hu_s="$2" __hu_out="" __hu_i __hu_part __hu_n
+  hook::_json_skeleton "$__hu_s" || return 1
+  [[ "$_HOOK_JSON_SK" == \{*\} ]] || return 1
+  # Numbers: only short integer literals are passed through. A fraction, an
+  # exponent or an integer beyond 15 digits is rendered differently by
+  # different jq releases (1.6 canonicalizes, 1.7+ preserves the literal), so
+  # the bytes cannot be proven; jq decides. In the skeleton every string is a
+  # `"#N"` placeholder and letters occur only in true/false/null, so a digit
+  # followed by `.`, `e` or `E` can only be part of a number.
+  local __hu_num='[0-9][.eE]|[0-9]{16}'
+  [[ "$_HOOK_JSON_SK" =~ $__hu_num ]] && return 1
+  __hu_n=${#_HOOK_JSON_PARTS[@]}
+  for ((__hu_i = 0; __hu_i < __hu_n; __hu_i++)); do
+    __hu_part=${_HOOK_JSON_PARTS[__hu_i]}
+    if ((__hu_i % 2 == 0)); then
+      __hu_out+=${__hu_part//[$' \t\n\r']/}
+    else
+      if [[ "$__hu_part" == *\\* ]]; then
+        [[ "$__hu_part" == *'\u'* || "$__hu_part" == *'\/'* ]] && return 1
+        [[ "$__hu_part" == *\\[!bfnrt]* ]] && return 1
+      fi
+      __hu_out+="\"${__hu_s:${_HOOK_JSON_OFF[__hu_i]}:${#__hu_part}}\""
+    fi
+  done
+  printf -v "$1" '%s' "$__hu_out"
+}
+
+# hook::json_escape_jq_to <var> <string>
+# Escape <string> exactly as jq serializes a string value (without the
+# quotes): backslash and double quote, the five short forms \b \f \n \r \t,
+# every other byte from 0x01 to 0x1f and 0x7f as lowercase \u00xx, and
+# everything else, including non-ASCII, verbatim. This is the escaper the
+# telemetry envelope needs for byte parity with the jq envelope it replaced;
+# hook::json_escape above is a different tool (it DROPS the residual control
+# bytes, which is right for a notice and wrong for parity) and is unchanged.
+hook::json_escape_jq_to() {
+  local __hu_s="$2" __hu_i __hu_c __hu_oct __hu_hex
+  __hu_s="${__hu_s//\\/\\\\}"
+  __hu_s="${__hu_s//\"/\\\"}"
+  if [[ "$__hu_s" == *[[:cntrl:]]* ]]; then
+    __hu_s="${__hu_s//$'\n'/\\n}"
+    __hu_s="${__hu_s//$'\r'/\\r}"
+    __hu_s="${__hu_s//$'\t'/\\t}"
+    __hu_s="${__hu_s//$'\b'/\\b}" # portability-ok: bash ANSI-C backspace byte and the JSON \b escape, not a GNU grep word boundary
+    __hu_s="${__hu_s//$'\f'/\\f}"
+    for __hu_i in 1 2 3 4 5 6 7 11 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 127; do
+      printf -v __hu_oct '%03o' "$__hu_i"
+      printf -v __hu_c '%b' "\\0$__hu_oct"
+      [[ "$__hu_s" == *"$__hu_c"* ]] || continue
+      printf -v __hu_hex '%04x' "$__hu_i"
+      __hu_s="${__hu_s//"$__hu_c"/\\u$__hu_hex}"
+    done
+  fi
+  printf -v "$1" '%s' "$__hu_s"
+}
+
+# hook::json_str_object_to <var> [key value]...
+# Compact JSON object of string fields, byte-identical to
+# `jq -n --arg k v --arg k2 v2 '{k:$k,k2:$k2}'` after `jq -c` (what
+# hook::json_compact_to already proves for telemetry data). Keys are
+# emitted in caller order. No jq, no temp file. Guard emit_tel builders
+# that only carry string fields use this so a wired HOOK_TELEMETRY_SINK
+# no longer spends one jq per guard on `{tool,subject,form}`.
+hook::json_str_object_to() {
+  local __hu_dest="$1"
+  shift
+  local __hu_out="{" __hu_first=1 __hu_k __hu_v __hu_ek __hu_ev
+  while (($# >= 2)); do
+    __hu_k="$1"
+    __hu_v="$2"
+    shift 2
+    hook::json_escape_jq_to __hu_ek "$__hu_k"
+    hook::json_escape_jq_to __hu_ev "$__hu_v"
+    if ((__hu_first)); then
+      __hu_first=0
+    else
+      __hu_out+=","
+    fi
+    __hu_out+='"'"$__hu_ek"'":"'"$__hu_ev"'"'
+  done
+  __hu_out+="}"
+  printf -v "$__hu_dest" '%s' "$__hu_out"
+}
+
+# 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
+#
+# jq-free on the common shape. The payload is read into the shell and
+# hook::_fast_file_path_to takes `.tool_input.file_path` with builtins when it
+# can PROVE the answer jq would give (see that helper for what "prove" means);
+# every other payload goes to the unchanged jq filter. The path comparison then
+# resolves the file, the project root and the temp roots with one realpath
+# process instead of one each (hook::_physical_prime), and remembers the
+# directories for the process. Same verdict, same emitted path, fewer
+# processes: on Windows Git Bash each spawn costs tens of milliseconds and this
+# guard runs on every Write and Edit.
+#
+# Print form, kept for a caller that holds no buffered payload and reads fd0
+# itself. A hook that already buffered stdin calls hook::read_file_path_to
+# with that buffer: `FILE=$(printf '%s' "$INPUT" | hook::read_file_path)`
+# paid a capture subshell, a pipeline member and a byte-at-a-time
+# `read -d ''` of the pipe for the same answer.
+hook::read_file_path() {
+  local -a __hu_chunks=()
+  local __hu_chunk __hu_out=""
+  # Builtin read to NUL or EOF. A NUL splits the payload into several chunks;
+  # the fast path only takes a single-chunk (NUL-free) payload, and the jq
+  # fallback is fed the chunks NUL-joined, so it sees the bytes jq used to
+  # read straight from stdin.
+  while :; do
+    __hu_chunk=""
+    if IFS= read -r -d '' __hu_chunk; then
+      __hu_chunks+=("$__hu_chunk")
+      continue
+    fi
+    __hu_chunks+=("$__hu_chunk")
+    break
+  done
+  hook::read_file_path_to __hu_out "${__hu_chunks[@]}" || return 1
+  printf '%s' "$__hu_out"
+}
+
+# hook::read_file_path_to <var> <payload>
+# hook::read_file_path's answer for an already-buffered payload, written into
+# <var> in THIS shell; returns 1 to skip, leaving <var> unchanged. A buffered
+# payload holds no NUL, so it is one chunk. More than one argument is the print
+# form's NUL-split stdin, which only jq may parse.
+#
+# The in-shell call leaves hook::_physical_prime's directory cache (and the
+# temp-root candidates) in the caller's process, where the print form's
+# subshell dropped them; a later path check in the same process reuses them,
+# which is what that cache is for.
+#
+# The one entry point is split in two names, as hook::jq_fields is: a
+# dispatcher that answers several guards from one payload (guardrails
+# run-guards.sh) puts a cache in front of hook::read_file_path_to and falls
+# through to hook::read_file_path_uncached_to on a miss.
+hook::read_file_path_to() {
+  hook::read_file_path_uncached_to "$@"
+}
+
+hook::read_file_path_uncached_to() {
+  local __hu_rf_dest="$1" __hu_rf_file="" __hu_rf_mode=2
+  shift
+  if (($# == 1)); then
+    __hu_rf_mode=0
+    hook::_fast_file_path_to __hu_rf_file "$1" || __hu_rf_mode=$?
+  fi
+  case "$__hu_rf_mode" in
+  0) ;;          # proven: `__hu_rf_file` holds jq's answer
+  1) return 1 ;; # proven absent
+  *)
+    __hu_rf_file=$(hook::_print_nul_joined "$@" | jq -r '(.tool_input.file_path // empty) | gsub("\r";"")' 2>/dev/null)
+    ;;
+  esac
+  [[ -n "$__hu_rf_file" ]] || return 1
+  [[ -f "$__hu_rf_file" ]] || return 1
+  # Scope opt-out, off unless the caller sets it for the duration of ONE call
+  # (`local HOOK_READ_FILE_PATH_UNSCOPED=1` in the calling frame). Parse and
+  # existence only, no membership.
+  #
+  # For an advisory PostToolUse linter whose own location filter already bounds
+  # what it reads, the membership guard protects nothing it can act on —
+  # PostToolUse cannot block or undo the write, so every guard false negative
+  # is a silent coverage loss instead. The concrete one: GNU realpath under Git
+  # Bash does not expand Windows 8.3 short names, so a short-form file_path
+  # (<drive>:\...\SOMEDIR~1\...) fails the prefix match against a long-form
+  # project dir and the lint never runs. A hook that MUTATES a file keeps the
+  # guard: there the scope is what stops a rewrite of something outside the
+  # project.
+  if [[ "${HOOK_READ_FILE_PATH_UNSCOPED:-0}" == 1 ]]; then
+    printf -v "$__hu_rf_dest" '%s' "$__hu_rf_file"
+    return 0
+  fi
+  if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+    local __hu_rf_norm_file __hu_rf_norm_project __hu_rf_phys_file __hu_rf_phys_project
+    local __hu_rf_file_resolved=0 __hu_rf_project_resolved=0
+    hook::_temp_root_candidates
+    hook::_physical_prime "$__hu_rf_file" "${CLAUDE_PROJECT_DIR}" ${_HOOK_TEMP_CANDS[@]+"${_HOOK_TEMP_CANDS[@]}"}
+    hook::_physical_cached_to __hu_rf_phys_file "$__hu_rf_file" && __hu_rf_file_resolved=1
+    hook::_phys_cache_forget "$__hu_rf_file"
+    hook::_physical_cached_to __hu_rf_phys_project "${CLAUDE_PROJECT_DIR}" && __hu_rf_project_resolved=1
+    hook::normalize_path_to __hu_rf_norm_file "$__hu_rf_phys_file"
+    hook::normalize_path_to __hu_rf_norm_project "$__hu_rf_phys_project"
+    __hu_rf_norm_project="${__hu_rf_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 [[ "$__hu_rf_norm_file" != "$__hu_rf_norm_project" && "$__hu_rf_norm_file" != "$__hu_rf_norm_project"/* ]]; then
+      return 1
+    fi
+    # Prefix membership alone is not project membership. When the project dir is
+    # the user's home (or any ancestor of the temp tree), every scratch file the
+    # harness writes — its own per-session scratchpad lives under the OS temp
+    # root — passes the prefix test and reaches hooks that then lint, rewrite,
+    # or autocorrect a file that is not project content and has no project
+    # config to opt out with. Same shape as hook-precision rule 5: gate on what
+    # the path IS, not on a literal substring of an over-broad project dir.
+    #
+    # The exemption is deliberate and load-bearing: when the project root ITSELF
+    # lives under temp, a file under temp is the project (a fixture checkout
+    # built by `mktemp -d`, which is how this repo's own hook suites run), so
+    # the branch must not fire. Only a temp-tree file reached from a project
+    # root OUTSIDE the temp tree is scratch.
+    local __hu_rf_file_in_temp=0
+    _HOOK_UTR_TARGET_PHYSICAL=$__hu_rf_file_resolved
+    hook::under_temp_root "$__hu_rf_norm_file" && __hu_rf_file_in_temp=1
+    _HOOK_UTR_TARGET_PHYSICAL=0
+    if ((__hu_rf_file_in_temp)); then
+      local __hu_rf_project_in_temp=0
+      _HOOK_UTR_TARGET_PHYSICAL=$__hu_rf_project_resolved
+      hook::under_temp_root "$__hu_rf_norm_project" && __hu_rf_project_in_temp=1
+      _HOOK_UTR_TARGET_PHYSICAL=0
+      ((__hu_rf_project_in_temp)) || return 1
+    fi
+  elif command -v git >/dev/null 2>&1; then
+    # When CLAUDE_PROJECT_DIR is unset, scope to git-working-tree membership so
+    # scratch files outside any repository are not mutated by formatter hooks
+    # (#1091 / #972).
+    local __hu_rf_file_physical __hu_rf_file_dir
+    hook::physical_path_to __hu_rf_file_physical "$__hu_rf_file" || :
+    if [[ -L "$__hu_rf_file" && "$__hu_rf_file_physical" == "$__hu_rf_file" ]]; then
+      return 1
+    fi
+    hook::dirname_to __hu_rf_file_dir "$__hu_rf_file_physical"
+    if ! hook::in_git_working_tree "$__hu_rf_file_dir"; then
+      return 1
+    fi
+  else
+    # No project dir and no git: fail closed rather than revert to unscoped
+    # pre-#1091 behavior (#1091).
+    return 1
+  fi
+  printf -v "$__hu_rf_dest" '%s' "$__hu_rf_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; when git
+# cannot resolve, still returns the hint (with a trailing /.claude stripped) so
+# advisory callers keep today's fallback — but the answer is now
+# DISTINGUISHABLE: return 1 and HOOK_REPO_ROOT_UNRESOLVED=1. Success (return 0)
+# means git answered; advisory callers that ignore the status are unchanged.
+# Guards that must fail closed branch on the return code or on
+# HOOK_REPO_ROOT_UNRESOLVED.
+#   hook::repo_root_to ROOT "$some_path"
+# `_to` writes in THIS shell so the caller does not pay an extra subshell
+# around the necessary git process (Command Substitution, Bash Reference
+# Manual; https://mywiki.wooledge.org/CommandSubstitution).
+#
+# Split in two names like hook::read_file_path_to: guardrails run-guards.sh
+# caches in front of hook::repo_root_to and falls through to
+# hook::repo_root_uncached_to.
+hook::repo_root_to() {
+  hook::repo_root_uncached_to "$@"
+}
+
+# shellcheck disable=SC2034  # public contract: advisory callers may read HOOK_REPO_ROOT_UNRESOLVED
+hook::repo_root_uncached_to() {
+  local __hu_rr_dest="$1"
+  local __hu_rr_hint="${2:-.}"
+  local __hu_rr_val
+  HOOK_REPO_ROOT_UNRESOLVED=0
+  # CR-stripped in the shell, not `git | tr`: that pipeline paid a `tr` exec
+  # on every repo_root call (~80 ms on Windows Git Bash) to delete one byte
+  # class bash already rewrites in place. Same bytes as `tr -d '\r'` — the
+  # same substitution buffer_stdin already uses for the payload.
+  __hu_rr_val=$(git -C "$__hu_rr_hint" rev-parse --show-toplevel 2>/dev/null) || __hu_rr_val=""
+  __hu_rr_val="${__hu_rr_val//$'\r'/}"
+  if [[ -n "$__hu_rr_val" ]]; then
+    printf -v "$__hu_rr_dest" '%s' "$__hu_rr_val"
+    return 0
+  fi
+  __hu_rr_val="$__hu_rr_hint"
+  __hu_rr_val="${__hu_rr_val%/.claude}"
+  __hu_rr_val="${__hu_rr_val%\\.claude}"
+  HOOK_REPO_ROOT_UNRESOLVED=1
+  printf -v "$__hu_rr_dest" '%s' "$__hu_rr_val"
+  return 1
+}
+
+# Kept as a print form for the callers outside this repo's hook tree (a skill
+# script, a repo-local sink copy) that read the root once at top level and are
+# not on a per-edit hot path.
+hook::repo_root() {
+  local __hu_rr
+  hook::repo_root_to __hu_rr "${1:-.}"
+  local __hu_rr_st=$?
+  printf '%s' "$__hu_rr"
+  return "$__hu_rr_st"
+}
+
+# Walk from <start> toward the filesystem root, asking <predicate> about each
+# directory, and write the directory it accepted into <dest>. Returns 0 when
+# one was accepted, 1 when none was. Every consumer opt-in gate and repo-local
+# binary probe in this marketplace is this walk; only the predicate differs.
+#
+#   hook::walk_up_to <dest> <start> <ceiling> <predicate> [first|topmost]
+#
+# <predicate> is called as `<predicate> <dir>` and answers with an exit status:
+#
+#   0  accept this directory
+#   1  keep walking
+#   2  stop the walk here, without accepting this directory — for a search
+#      whose own rules end it above a hit, such as EditorConfig's `root = true`
+#
+# <mode> is `first` (default: the closest accepted directory, the answer a
+# file-anchored tool resolves) or `topmost` (keep walking past a hit and answer
+# with the highest one, the answer a CWD-anchored tool that treats the outermost
+# config as the orchestrator resolves).
+#
+# THE CEILING IS REQUIRED, AND AN UNRESOLVED CEILING FAILS CLOSED: an empty
+# <ceiling> accepts nothing and walks nowhere. These walks decide whether a
+# repository opted into having its files rewritten, and a walk that runs past
+# the repository reads configuration from directories the consuming repository
+# does not own — a home directory, a build agent's workspace root — and answers
+# "yes, format this" on their say-so. A missed opt-in is a file left alone; a
+# ceiling-less walk is somebody else's config governing an edit. To walk to the
+# filesystem root deliberately, pass `/`, which is a resolved ceiling and stops
+# the walk in the same place.
+#
+# The terminator is the whole reason this is one function: `${dir%/*}` leaves an
+# empty string for a directory directly under the filesystem root and leaves the
+# string unchanged for a bare relative name, so the `/` fallback and the
+# self-comparison are both load-bearing, and eight hand-rolled copies of them
+# were eight places for one of the two to go missing.
+hook::walk_up_to() {
+  local __hu_wu_dest="$1" __hu_wu_dir="$2" __hu_wu_ceiling="$3"
+  local __hu_wu_pred="$4" __hu_wu_mode="${5:-first}"
+  local __hu_wu_hit="" __hu_wu_parent __hu_wu_rc
+  printf -v "$__hu_wu_dest" '%s' ""
+  [[ -n "$__hu_wu_dir" && -n "$__hu_wu_ceiling" ]] || return 1
+  while :; do
+    "$__hu_wu_pred" "$__hu_wu_dir"
+    __hu_wu_rc=$?
+    if ((__hu_wu_rc == 0)); then
+      __hu_wu_hit="$__hu_wu_dir"
+      [[ "$__hu_wu_mode" == topmost ]] || break
+    elif ((__hu_wu_rc != 1)); then
+      break
+    fi
+    [[ "$__hu_wu_dir" == "$__hu_wu_ceiling" ]] && break
+    __hu_wu_parent="${__hu_wu_dir%/*}"
+    [[ -n "$__hu_wu_parent" ]] || __hu_wu_parent=/
+    [[ "$__hu_wu_parent" == "$__hu_wu_dir" ]] && break
+    __hu_wu_dir="$__hu_wu_parent"
+  done
+  printf -v "$__hu_wu_dest" '%s' "$__hu_wu_hit"
+  [[ -n "$__hu_wu_hit" ]]
+}
+
+# Repo-relative form of <file> under <repo-root> — the shape the telemetry
+# schema requires of `data.file` ("relative to the consuming repo root").
+#
+# On a Windows bash host (OSTYPE msys, cygwin or win32) both sides go through
+# `cygpath -l -m` (long name, forward-slash mixed form) when it is available, so
+# the prefix strip compares ONE representation: on Windows Git Bash
+# `git rev-parse --show-toplevel` answers with a drive-letter path while
+# file_path may arrive in POSIX mount form, and the raw strip never matches.
+# A trailing separator is trimmed first, and the Windows compare is
+# case-insensitive, so `C:/repo/` and `c:/repo/src/run.sh` still yield
+# `src/run.sh`. When cygpath sends the two sides to different trees, the
+# caller's own spelling is tried before the basename degrade. On Linux/macOS
+# both paths are already POSIX, so the strip runs directly without calling
+# cygpath.
+#
+# What survives the strip is not trusted to BE relative. A mount/symlink
+# mismatch, or a cygpath that answers for one side and not the other, leaves
+# the whole absolute path, which embeds the developer's username and breaks the
+# schema contract. Such a path degrades to its basename rather than leaking
+# (#1133), and the answer is DISTINGUISHABLE: return 1 and
+# HOOK_REPO_RELATIVE_DEGRADED=1. Success (return 0) means the path is genuinely
+# repo-relative. Telemetry callers that ignore the status still get the safe
+# value; a caller that feeds the result to a TOOL must branch on it, because a
+# bare basename resolved against the repo root names a different file.
+#   hook::repo_relative_path_to FILE_REL "$FILE" "$REPO_ROOT"
+#
+# Callers under `set -e` must not take the status from a bare call: a degraded
+# answer returns 1 and would abort the shell. Append `|| <flag>=1` (what every
+# tool-feeding caller here does) or `|| :` to keep the failure handled. The
+# helper writes in THIS shell so a Linux caller (no cygpath) pays no capture
+# subshell around builtins-only work (Command Substitution, Bash Reference
+# Manual; https://mywiki.wooledge.org/CommandSubstitution).
+# shellcheck disable=SC2034  # public contract: callers may read HOOK_REPO_RELATIVE_DEGRADED
+hook::repo_relative_path_to() {
+  local __hu_rp_dest="$1"
+  local __hu_rp_file="$2" __hu_rp_root="$3" __hu_rp_rel=""
+  local __hu_rp_file_n __hu_rp_root_n __hu_rp_file_c __hu_rp_root_c __hu_rp_pre
+  local __hu_rp_fold=0 __hu_rp_file_lm="" __hu_rp_root_lm=""
+  HOOK_REPO_RELATIVE_DEGRADED=0
+  # One separator spelling, then drop a trailing separator. A root that already
+  # ends in / or \ makes the prefix "/repo//" and matches nothing, so every
+  # in-project file collapses to its basename (#4527). The filesystem root
+  # itself is kept: trimming its only slash would empty the anchor.
+  # Backslash is a separator only on Windows; on POSIX it is a filename
+  # character, and folding it could make an outside path look like a member.
+  __hu_rp_file_n=$__hu_rp_file
+  __hu_rp_root_n=$__hu_rp_root
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32)
+    __hu_rp_file_n="${__hu_rp_file_n//\\//}"
+    __hu_rp_root_n="${__hu_rp_root_n//\\//}"
+    ;;
+  *) ;; # POSIX: keep the caller's spelling
+  esac
+  while [[ "$__hu_rp_root_n" == */ && "$__hu_rp_root_n" != / ]]; do
+    __hu_rp_root_n="${__hu_rp_root_n%/}"
+  done
+  while [[ "$__hu_rp_file_n" == */ && ${#__hu_rp_file_n} -gt 1 ]]; do
+    __hu_rp_file_n="${__hu_rp_file_n%/}"
+  done
+  __hu_rp_file_c=$__hu_rp_file_n
+  __hu_rp_root_c=$__hu_rp_root_n
+  # An empty root anchors nothing, and the strip must not run against one:
+  # `${file#""/}` merely shaves the leading slash, handing back a path that is
+  # still the caller's absolute path but no longer LOOKS absolute to the
+  # redaction below, so it would leak with a success status. Skipping the strip
+  # leaves rel as the input, which the redaction then degrades correctly.
+  #
+  # cygpath exists only on the Windows bash hosts (the OSTYPE set
+  # hook::normalize_path_to uses). Elsewhere `command -v` misses, and a miss
+  # probes every PATH directory: on WSL that includes the /mnt/c entries, one
+  # 9P round trip each, 13-20 ms per call. The call is therefore the lookup.
+  if [[ -n "$__hu_rp_root_n" ]]; then
+    case "${OSTYPE:-}" in
+    msys* | cygwin* | win32)
+      __hu_rp_fold=1
+      __hu_rp_file_lm=$(cygpath -l -m -- "$__hu_rp_file_n" 2>/dev/null) || __hu_rp_file_lm=""
+      __hu_rp_root_lm=$(cygpath -l -m -- "$__hu_rp_root_n" 2>/dev/null) || __hu_rp_root_lm=""
+      if [[ -n "$__hu_rp_file_lm" && -n "$__hu_rp_root_lm" ]]; then
+        __hu_rp_file_c="${__hu_rp_file_lm//\\//}"
+        __hu_rp_root_c="${__hu_rp_root_lm//\\//}"
+        while [[ "$__hu_rp_root_c" == */ && "$__hu_rp_root_c" != / ]]; do
+          __hu_rp_root_c="${__hu_rp_root_c%/}"
+        done
+        while [[ "$__hu_rp_file_c" == */ && ${#__hu_rp_file_c} -gt 1 ]]; do
+          __hu_rp_file_c="${__hu_rp_file_c%/}"
+        done
+      fi
+      ;;
+    *) ;; # POSIX hosts: case-sensitive FS, strip the caller's spelling
+    esac
+    __hu_rp_pre="${__hu_rp_root_c}/"
+    if [[ "$__hu_rp_file_c" == "$__hu_rp_pre"* ]]; then
+      __hu_rp_rel="${__hu_rp_file_c#"$__hu_rp_pre"}"
+    elif ((__hu_rp_fold)) && [[ "${__hu_rp_file_c,,}" == "${__hu_rp_pre,,}"* ]]; then
+      __hu_rp_rel="${__hu_rp_file_c:${#__hu_rp_pre}}"
+    elif [[ "$__hu_rp_file_c" != "$__hu_rp_file_n" || "$__hu_rp_root_c" != "$__hu_rp_root_n" ]]; then
+      # cygpath sent the two sides to different trees (a /tmp that is usertemp
+      # on one side and a drive-root translation on the other). The caller's
+      # own spelling still shares a prefix; use that rather than the basename.
+      __hu_rp_pre="${__hu_rp_root_n}/"
+      if [[ "$__hu_rp_file_n" == "$__hu_rp_pre"* ]]; then
+        __hu_rp_rel="${__hu_rp_file_n#"$__hu_rp_pre"}"
+      elif ((__hu_rp_fold)) && [[ "${__hu_rp_file_n,,}" == "${__hu_rp_pre,,}"* ]]; then
+        __hu_rp_rel="${__hu_rp_file_n:${#__hu_rp_pre}}"
+      else
+        __hu_rp_rel=$__hu_rp_file_c
+      fi
+    else
+      __hu_rp_rel=$__hu_rp_file_c
+    fi
+  else
+    __hu_rp_rel=$__hu_rp_file_n
+  fi
+  # POSIX-absolute, drive-letter, and UNC are the three spellings an unstripped
+  # path arrives in. Separators were folded to / above, so the slash arm covers
+  # a UNC that arrived with backslashes. Trim on either separator anyway: a
+  # mixed-form path can still carry a backslash when folding was skipped.
+  case "$__hu_rp_rel" in
+  /* | [A-Za-z]:* | \\\\*)
+    __hu_rp_rel="${__hu_rp_rel##*/}"
+    __hu_rp_rel="${__hu_rp_rel##*\\}"
+    HOOK_REPO_RELATIVE_DEGRADED=1
+    ;;
+  *) ;; # already repo-relative, nothing to redact
+  esac
+  printf -v "$__hu_rp_dest" '%s' "$__hu_rp_rel"
+  ((HOOK_REPO_RELATIVE_DEGRADED == 0))
+}
+
+# Buffer a complete JSON payload from stdin, tolerating Windows Win32-pipe
+# late-EOF stalls via a bounded read on the inherited fd0. Returns the payload
+# on success; returns 1 on empty/incomplete stdin (caller skips), 2 when the
+# read stalled before a complete JSON payload arrived or the buffer is not
+# JSON (caller may block), or 3 when a well-formed JSON prefix arrived and
+# the pipe then CLOSED mid-document (a transport fault; caller loud-allows).
+#
+# The bound (stdin_read_timeout userConfig option, in seconds, read via
+# CLAUDE_PLUGIN_OPTION_STDIN_READ_TIMEOUT, default 2) is an IDLE bound, not a
+# total one: only a window in which NOTHING arrives ends the read. A single
+# `read -d ''` bounded by -t was a total bound, and because bash consumes
+# `read -d ''` on a pipe one byte at a time (~32 KB/s on Git Bash) that made it
+# a ~64 KB THROUGHPUT ceiling — every larger payload tripped the timeout branch,
+# so fail-closed callers blocked a legitimate write and fail-open callers
+# skipped silently. Two things together make the bound mean what it says:
+#
+#   * The read is chunked. `read -N` lets bash satisfy it in blocks instead of
+#     byte-at-a-time: 50 KB drops from ~2100 ms to ~20 ms, 200 KB from ~6800 ms
+#     to ~85 ms.
+#   * The timer measures inactivity, not the read. `read -t` is a deadline for
+#     the WHOLE requested read, so a producer that keeps delivering but slower
+#     than one chunk per window would still trip it. `read` assigns whatever it
+#     did receive even when it times out, so any byte counts as progress: the
+#     loop keeps that partial chunk and reads on. Only the absence of bytes for a
+#     whole stdin_read_timeout is a stall.
+#   * The bound is read in HOOK_STDIN_READ_SLICES slices. `read -t` reports only
+#     that its window expired, never WHEN inside it the last byte arrived, so a
+#     bound armed as one window would declare a stall anywhere between one and
+#     TWO bounds after the pipe actually went quiet. Slicing bounds that
+#     overshoot: with four slices a stall lands within a quarter-bound of the
+#     configured interval. That residual quarter is the honest limit of the
+#     approximation, and it errs toward waiting — never toward declaring a live
+#     producer dead. On a shell whose `read -t` rejects the fractional slice the
+#     count degrades to 1, i.e. the unsliced one-to-two-bound behavior.
+#
+# Reading on is skipped once the buffer already parses as whole JSON, so the
+# late-EOF case costs ONE slice past the payload rather than the rest of the
+# bound — a producer holding the pipe open cannot be distinguished from a slow
+# one until a window expires, so some wait there is the floor.
+#
+# The trade this makes: a producer trickling bytes indefinitely is never cut off
+# here. That is deliberate: the harness already caps a `command` hook at its
+# timeout (https://code.claude.com/docs/en/hooks#common-fields, as of
+# 2026-10-11; recheck when that section drops the default timeout for command
+# hooks), and blocking a live
+# producer is exactly the failure this function had.
+#
+# `read` reports which stop condition it hit — EOF returns 1, an exceeded -t
+# returns >128 — so the loop takes the verdict off $? rather than inferring it
+# from elapsed-time arithmetic. jq (when present) is still the completeness
+# backstop: a stall that nevertheless delivered a complete payload is the Win32
+# late-EOF case this function exists for and must succeed, not block. A
+# missing/broken jq (exit 127) fails open like absent jq.
+#
+# `read -N` is Bash 4.1+; macOS ships Bash 3.2 and these hooks document 3.2+
+# support, so the pre-4.1 branch falls back to the delimiter read, which already
+# reads to EOF and is fast enough on native POSIX pipes. The re-arming
+# loop wraps both forms, so 3.2 gets the progress semantics too — just in
+# byte-at-a-time-sized steps.
+#   hook::buffer_stdin_to INPUT || exit 0
+#   INPUT=$(hook::buffer_stdin) || exit 0   # print form; the $() is a subshell
+
+# The `read -N` availability guard, split out as its own predicate so the
+# pre-4.1 path stays reachable in tests on a modern host: BASH_VERSINFO is
+# readonly, so it cannot be shadowed, but a test can override this function
+# after sourcing. Not a consumer seam — nothing reads it from the environment.
+hook::read_supports_nchars() {
+  ((BASH_VERSINFO[0] > 4 || (BASH_VERSINFO[0] == 4 && BASH_VERSINFO[1] >= 1)))
+}
+
+# Is the buffered text already a complete JSON document? Lets the read stop the
+# moment the payload is whole instead of spending another idle window waiting
+# for an EOF a Win32 pipe may never deliver. Returns non-zero when jq is
+# unavailable or broken (exit 127) as well as when the text is incomplete — the
+# caller must keep reading rather than guess, and the caller's own fail-open
+# handling for absent jq is unaffected.
+hook::json_complete() {
+  # Structural pre-filter before paying for a jq process: a hook payload is a
+  # JSON object, so a complete one ends in `}` (possibly with trailing newline
+  # or CR). Testing the last few characters is O(1) and skips the spawn for
+  # every mid-payload buffer, which is what keeps this off the hot path of a
+  # large or slow read. A false negative here costs only the early break — the
+  # read continues and the caller's final completeness check still decides — so
+  # the pre-filter can never turn a whole payload into a wrong verdict.
+  [[ "${1: -4}" == *"}"* ]] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  # `printf | jq`, never `jq <<< "$1"`. A here-string is delivered through a pipe
+  # that bash fills itself, so a payload at or above the pipe capacity (65536
+  # bytes on this platform — exactly one read chunk) blocks the shell forever
+  # before jq is ever exec'd. Reproduced: a 65536-byte buffer hung here
+  # indefinitely while 65000 returned immediately. A separate writer process
+  # cannot deadlock that way.
+  printf '%s' "$1" | jq -e . >/dev/null 2>&1
+}
+
+# Resolve the read timeout to a value THIS shell's `read -t` will actually
+# accept, falling back to the documented default of 2 otherwise.
+#
+# The configured value reaches `read -t` directly, and an unusable one is not a
+# tuning mistake — it is a silent disable. `read` rejects a bad spec with rc 1
+# plus a usage error on stderr for EVERY hook invocation; the buffer loop reads
+# rc 1 as EOF, produces an empty payload, and every caller skips. `0` is worse
+# still: it makes `read` return immediately having consumed nothing, which would
+# spin the loop.
+#
+# Fractional `read -t` landed in bash-4.0-alpha (CHANGES: "The `-t` option to
+# the `read` builtin now supports fractional timeout values"). Integer
+# timeouts are valid on every Bash these hooks support, including 3.2. A
+# live probe that redirected stderr into TMPDIR leaked a file on every
+# `buffer_stdin` (suites that isolate TMPDIR and assert it is empty after
+# the hook exits fail closed on that leftover). The version predicate is
+# the same class as hook::read_supports_nchars: overridable in tests because
+# BASH_VERSINFO is readonly. No file, no `read -t` against /dev/null.
+# Minimum 0.00001 s (10 µs): smaller positive values are a silent disable — the
+# read returns before payload bytes arrive, same class as exact zero (#1883).
+readonly HOOK_STDIN_READ_TIMEOUT_MIN_MICROS=10
+
+# Fractional `read -t` is Bash 4.0+. Split out so a test can force the 3.2
+# fallback the way hook::read_supports_nchars forces the pre-4.1 delimiter
+# read. Not a consumer seam.
+hook::read_supports_fractional_timeout() {
+  ((BASH_VERSINFO[0] >= 4))
+}
+
+# hook::resolve_read_timeout_to <var>
+# Write the resolved timeout into <var> in THIS shell. GNU Bash runs command
+# substitution in a subshell even when the body is only builtins (Command
+# Execution Environment), so a capture here is a startup fork on every hook;
+# this is the only spelling, and the suite pins that buffer_stdin uses it.
+hook::resolve_read_timeout_to() {
+  local __hu_dest="$1"
+  local __hu_t="${CLAUDE_PLUGIN_OPTION_STDIN_READ_TIMEOUT:-2}"
+  if [[ "$__hu_t" != "2" ]]; then
+    if ! [[ "$__hu_t" =~ ^[0-9]+(\.[0-9]+)?$ ]] || [[ "$__hu_t" =~ ^0+(\.0+)?$ ]] ||
+      { [[ "$__hu_t" == *.* ]] && ! hook::read_supports_fractional_timeout; }; then
+      __hu_t=2
+    elif [[ "$__hu_t" =~ ^([0-9]+)(\.([0-9]+))?$ ]]; then
+      local whole="${BASH_REMATCH[1]}" frac="${BASH_REMATCH[3]:-}"
+      frac="${frac}000000"
+      frac="${frac:0:6}"
+      local micros=$((10#$whole * 1000000 + 10#$frac))
+      if ((micros < HOOK_STDIN_READ_TIMEOUT_MIN_MICROS)); then
+        __hu_t=2
+      fi
+    fi
+  fi
+  printf -v "$__hu_dest" '%s' "$__hu_t"
+}
+
+# How many slices the idle bound is divided into. `read -t` reports only that a
+# window expired, never WHEN inside it the last byte arrived, so a bound armed as
+# one window declares a stall anywhere between one and two bounds after the pipe
+# actually went quiet. Asking more often shrinks that: with N slices, a stall is
+# declared within one slice of the configured interval. Four is the compromise —
+# it cuts worst-case overshoot from 100% of the bound to 25% while keeping the
+# idle path to four cheap builtin reads.
+HOOK_STDIN_READ_SLICES=4
+
+# Resolve the per-read slice for an already-resolved timeout into two caller
+# variables (slice, count), falling back to "<timeout> 1" — exactly the
+# unsliced behavior — when this shell cannot accept a fractional `read -t`
+# (Bash 3.2; CHANGES bash-4.0-alpha introduced fractional timeouts).
+# Version-tested via hook::read_supports_fractional_timeout, not probed: a
+# TMPDIR stderr file leaked on every buffer_stdin. Two variables, never a
+# printed "<slice> <count>" pair the caller re-splits, so the resolution pays
+# no substitution fork (GNU Bash: commands grouped for substitution run in a
+# subshell).
+hook::resolve_read_slice_to() {
+  local __hu_t="$1" __hu_slice=""
+  local __hu_slice_dest="$2" __hu_count_dest="$3"
+  # The division is fixed-point shell arithmetic, not `awk t/n`. A hook pays for
+  # every external process it spawns — ~140 ms each on Windows Git Bash, where
+  # process creation is fork() emulation — and this one spawned awk on EVERY
+  # invocation to divide two numbers. Bash has no float arithmetic, so the value
+  # is carried in micro-units (1e-6 s; `read -t` never resolves finer than
+  # milliseconds anyway) and rounded back half-up to the same three decimals
+  # awk's "%.3f" produced. Identical output for every timeout in practice; the
+  # one seam is a quotient landing on an exact half-millisecond (t=2.006 → 0.502
+  # here, 0.501 under awk, whose C printf rounds the binary approximation), a
+  # 1 ms difference in an idle bound that is itself an approximation — see the
+  # residual-quarter note above. printf -v, not $( ), because a command
+  # substitution forks the shell even for a builtin — the fork IS the cost here.
+  # A value the pattern rejects, or one large enough to overflow the arithmetic
+  # into a negative, leaves `slice` unusable and falls through to the unsliced
+  # "<t> 1" form below, exactly as an awk failure did.
+  if [[ "$__hu_t" =~ ^([0-9]+)(\.([0-9]+))?$ ]] && ((HOOK_STDIN_READ_SLICES > 0)); then
+    local whole="${BASH_REMATCH[1]}" frac="${BASH_REMATCH[3]:-}"
+    frac="${frac}000000"
+    frac="${frac:0:6}"
+    local micros=$((10#$whole * 1000000 + 10#$frac))
+    local milli=$(((micros / HOOK_STDIN_READ_SLICES + 500) / 1000))
+    printf -v __hu_slice '%d.%03d' "$((milli / 1000))" "$((milli % 1000))"
+  fi
+  if [[ -n "$__hu_slice" && "$__hu_slice" =~ ^[0-9]+\.[0-9]+$ ]] && ! [[ "$__hu_slice" =~ ^0+\.0+$ ]] &&
+    hook::read_supports_fractional_timeout; then
+    printf -v "$__hu_slice_dest" '%s' "$__hu_slice"
+    printf -v "$__hu_count_dest" '%s' "$HOOK_STDIN_READ_SLICES"
+    return 0
+  fi
+  printf -v "$__hu_slice_dest" '%s' "$__hu_t"
+  printf -v "$__hu_count_dest" '%s' "1"
+}
+
+# hook::buffer_stdin_to <var> [jq-filter...]
+# Write the buffered payload into <var> in THIS shell. GNU Bash forks a
+# subshell for every command substitution even when the body is only
+# builtins (Command Substitution, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution). On Windows Git Bash that
+# fork is a process, paid on every hook that captures via
+# INPUT=$(hook::buffer_stdin) before the payload is parsed. The _to form is
+# the in-process capture, matching hook::resolve_read_timeout_to.
+#
+# Optional jq filters fuse the completeness check with hook::jq_fields so a
+# caller that was about to extract fields anyway spends one jq process, not
+# two (`jq -e .` plus a second jq for fields). On success HOOK_JQ_FIELDS is
+# populated, index-parallel to the filters, with the same NUL-flag contract
+# as a direct hook::jq_fields call. jq absent still fails open (return 0,
+# empty fields), matching the print form's completeness check.
+#
+# Return codes match hook::buffer_stdin: 0 payload, 1 empty, 2 stalled or
+# not JSON, 3 cut short at EOF. The print form below is the compatibility
+# wrapper.
+hook::buffer_stdin_to() {
+  local __hu_dest="$1"
+  shift
+  # Every local is `__hu_`-prefixed so a caller dest named `input`,
+  # `read_timeout`, `fields_rc`, or any other ordinary name cannot collide
+  # with this function's own variables (the `_to` helper convention at the
+  # path helpers above). An unprefixed local would make `printf -v` write
+  # the payload into THIS frame and return 0 while the caller kept stale data.
+  local __hu_input="" __hu_chunk="" __hu_read_rc=0 __hu_stalled=0
+  local __hu_idle_slices=0 __hu_validated=0
+  local __hu_read_timeout __hu_read_slice __hu_slice_count
+  # _to, not $( ) / process substitution: GNU Bash forks a subshell for both,
+  # even when the body is builtins only. Those two forks were the documented
+  # buffer_stdin startup cost (lib/hook-utils.test.sh). Slice acceptance is
+  # hook::read_supports_fractional_timeout (Bash 4+), so it creates no TMPDIR
+  # file and pays no substitution fork.
+  hook::resolve_read_timeout_to __hu_read_timeout
+  hook::resolve_read_slice_to "$__hu_read_timeout" __hu_read_slice __hu_slice_count
+  local -a __hu_read_opts=(-r -t "$__hu_read_slice")
+  if hook::read_supports_nchars; then
+    __hu_read_opts+=(-N 65536)
+  else
+    __hu_read_opts+=(-d '')
+  fi
+  while :; do
+    __hu_chunk=""
+    __hu_read_rc=0
+    # shellcheck disable=SC2162 # -r is in __hu_read_opts; shellcheck cannot see through the array
+    IFS= read "${__hu_read_opts[@]}" __hu_chunk || __hu_read_rc=$?
+    __hu_input+="$__hu_chunk"
+    # Any byte at all resets the idle count — that, not the read's exit status,
+    # is what makes this an idle timer rather than a per-read deadline.
+    [[ -n "$__hu_chunk" ]] && __hu_idle_slices=0
+    if ((__hu_read_rc == 0)); then
+      # A full chunk (or a delimiter) — more may still be coming. A SUCCESSFUL
+      # read that consumed nothing, however, cannot make progress, so continuing
+      # would spin: break instead. hook::resolve_read_timeout_to already excludes
+      # the only known way to reach that (`read -t 0`, which returns success
+      # without consuming); this keeps loop termination a structural property
+      # rather than a consequence of validation staying correct.
+      [[ -n "$__hu_chunk" ]] || break
+      continue
+    fi
+    if ((__hu_read_rc > 128)); then
+      # A slice expired. Bytes in it mean the producer is alive: keep them and
+      # read on. Only slice_count CONSECUTIVE empty slices — one whole
+      # stdin_read_timeout with nothing arriving — is the stall this guard
+      # exists to catch, which is why the count is not reset here.
+      if [[ -n "$__hu_chunk" ]]; then
+        # ... but stop immediately if what we already hold is a whole JSON
+        # document. That is the Win32 late-EOF case — the payload arrived, the
+        # pipe just never closed — and reading on there would spend the rest of
+        # the bound waiting for an EOF that is not coming.
+        if hook::json_complete "${__hu_input//$'\r'/}"; then
+          __hu_validated=1
+          break
+        fi
+        continue
+      fi
+      # An EMPTY slice can also be the late-EOF case: the payload may have been
+      # completed by the PREVIOUS read, which returned rc 0 and so never reached
+      # the completeness check above. That happens whenever the payload ends on a
+      # 65536-character boundary, and without this the helper would wait out the
+      # whole bound instead of a single slice. Checking here rather than on the
+      # rc-0 path keeps jq off the hot path — a large payload costs one check
+      # when the producer first pauses, not one per 64 KB chunk.
+      #
+      # Only on the FIRST empty slice of a quiet period: the buffer cannot grow
+      # while nothing is arriving, so re-checking an unchanged buffer would spend
+      # a jq process per slice to re-derive the same answer — enough overhead on
+      # a slow-spawning host to cost more than slicing saves. idle_slices resets
+      # the moment a byte lands, so the next quiet period checks again.
+      if ((__hu_idle_slices == 0)) && hook::json_complete "${__hu_input//$'\r'/}"; then
+        __hu_validated=1
+        break
+      fi
+      ((__hu_idle_slices++))
+      ((__hu_idle_slices >= __hu_slice_count)) || continue
+      __hu_stalled=1
+    fi
+    break # EOF (rc 1), a full idle bound with no bytes, or a read error
+  done
+  # CR-stripped in the shell, not through `printf | tr`: that pipeline cost a
+  # fork AND an exec (~280 ms together on Windows Git Bash) to delete one byte
+  # class from a string bash can already rewrite in place. Same bytes either way
+  # — which is what lets the completeness verdict below be reused.
+  __hu_input="${__hu_input//$'\r'/}"
+  [[ -n "$__hu_input" ]] || return 1
+  local __hu_jq_rc=0
+  # The loop above breaks on hook::json_complete only when jq PARSED this exact
+  # CR-stripped buffer as a whole document, so re-probing it here would spend a
+  # second jq process to re-derive an answer already in hand. jq's absence or
+  # failure never sets that flag (json_complete returns non-zero for both), so
+  # the fail-open path below is unchanged: an unvalidated buffer still gets the
+  # probe, and a host without jq still reaches the 127 branch.
+  #
+  # Filters fuse that remaining probe with hook::jq_fields: a valid payload
+  # that the caller was going to parse anyway is extracted in the same jq
+  # process that would have been `jq -e .`. jq_fields rc 2 is the malformed
+  # path (parse failure or cardinality mismatch); rc 1 is jq absent, which
+  # fails open like jq -e's 127.
+  if (($#)); then
+    local __hu_fields_rc=0
+    hook::jq_fields "$__hu_input" "$@" || __hu_fields_rc=$?
+    if ((__hu_fields_rc == 2)); then
+      __hu_jq_rc=2
+    fi
+  elif ((__hu_validated == 0)) && command -v jq >/dev/null 2>&1 &&
+    ! hook::_json_object_proven "$__hu_input"; then
+    # hook::_json_object_proven answers first, with builtins: a text
+    # hook::_json_skeleton accepts whose root is an object is one `jq -e .`
+    # accepts (an object is truthy), so the common payload spawns nothing. The
+    # skeleton it builds is cached for the file-path and field parses that
+    # follow on the same text. Anything it cannot prove still goes to jq.
+    # `printf | jq`, not a here-string — see hook::json_complete: a here-string
+    # at or above the pipe capacity deadlocks the shell before jq is exec'd, and
+    # a hook payload routinely exceeds it. A direct probe, not a command
+    # substitution: this is the hot path (every closed-pipe payload on POSIX
+    # lands here), and `$(...)` would add a subshell fork to it on every hook
+    # invocation. jq's diagnostic is fetched by a second run below, only once
+    # this probe has failed and the stall and whitespace arms have been
+    # decided, so a valid payload pays for exactly one jq.
+    printf '%s' "$__hu_input" | jq -e . >/dev/null 2>&1 || __hu_jq_rc=$?
+  fi
+  if ((__hu_jq_rc != 0 && __hu_jq_rc != 127)); then
+    # STALLED stays fail-closed, and is decided FIRST — before the
+    # whitespace-only check and before the content split below. A pipe still
+    # open after a whole idle bound without a complete document is rc 2
+    # whatever arrived, whitespace included. A stall is reachable from the
+    # agent's side (a payload past 64 KiB splits the harness write; host load
+    # from earlier tool calls widens the gap) and the dispatcher takes rc 3
+    # before any guard is sourced, so an allow here would let one induced
+    # stall skip every guard on the lane. Some genuine stalls on a starved
+    # host are therefore still denied; that is the accepted trade. Only the
+    # early-EOF arm below is allowed.
+    if ((__hu_stalled)); then
+      echo "BLOCKED: hook stdin timed out before a complete JSON payload arrived." >&2
+      return 2
+    fi
+    # Whitespace-only stdin (e.g. `<<<""` sends a lone newline) is an empty
+    # payload, not a malformed one — keep the silent rc=1 path advisory hooks
+    # treat as a no-op. Reached only at EOF, since a stall returned above.
+    [[ -n "${__hu_input//[[:space:]]/}" ]] || return 1
+    # CUT SHORT AT EOF versus NOT JSON. jq names a document that ended before
+    # it closed "Unfinished JSON term at EOF" / "Unfinished string at EOF"
+    # (wording stable across jq 1.5 through 1.7; the suite pins it), while
+    # text that is not JSON fails on the offending token. The read reached
+    # here on end-of-file, not on the idle bound, so a well-formed prefix
+    # means every byte that arrived was the harness's payload and the
+    # harness's pipe then closed before the rest came: a transport fault.
+    # The harness serializes that payload and owns the close, so the agent
+    # cannot stage it; the fault says nothing about the command. A blocking
+    # caller therefore must not deny on it: rc 3. Text that never parsed
+    # keeps rc 2. Should jq's wording change, an unrecognized diagnostic
+    # falls through to rc 2 — never a wider allow. The diagnostic is read
+    # here, by a second jq over the same buffer (stdout dropped, stderr
+    # captured), and nowhere earlier: this arm is only reached once the
+    # probe above has failed on a non-stalled, non-blank payload, so the
+    # re-run is a cold-path cost and the stall and whitespace verdicts
+    # above never depend on it.
+    local __hu_jq_err=""
+    __hu_jq_err=$(printf '%s' "$__hu_input" | jq -e . 2>&1 >/dev/null) || true
+    if [[ "$__hu_jq_err" == *Unfinished* ]]; then
+      echo "hook stdin was cut short: ${#__hu_input} characters of a JSON payload arrived, then the pipe closed before the document was complete (a transport fault, not a property of the tool call)." >&2
+      return 3
+    fi
+    echo "BLOCKED: hook stdin is not valid JSON." >&2
+    return 2
+  fi
+  printf -v "$__hu_dest" '%s' "$__hu_input"
+}
+
+# Kept as a print form because the guardrails dispatcher overrides both
+# spellings to answer every sourced guard from one already-read payload, and a
+# guard that captures must still reach the override.
+hook::buffer_stdin() {
+  local __hu_buf
+  hook::buffer_stdin_to __hu_buf || return $?
+  printf '%s' "$__hu_buf"
+}
+
+# Extract a single jq field from a buffered input string. CR-stripped. Returns 1
+# when the field is empty or jq fails, so the caller can skip.
+#
+# Fed through `printf | jq`, never a here-string: bash fills a here-string's pipe
+# itself, so a payload at or above the pipe capacity (65536 bytes here) blocks
+# before jq is exec'd. Callers pass the WHOLE buffered hook payload, which
+# routinely exceeds that.
+#   FIELD=$(hook::jq_field "$INPUT" '.tool_input.file_path') || exit 0
+hook::jq_field() {
+  local field
+  field=$(printf '%s' "$1" | jq -r "(${2} // empty)"' | gsub("\r";"")' 2>/dev/null)
+  [[ -n "$field" ]] || return 1
+  printf '%s' "$field"
+}
+
+# Extract SEVERAL fields from one buffered input in ONE jq process. A hook that
+# reads three fields with hook::jq_field pays three forks and three execs over
+# the SAME stdin envelope — ~840 ms on Windows Git Bash, per invocation, for
+# work jq does once. Results land in the HOOK_JQ_FIELDS array, index-parallel to
+# the filters.
+#
+# An absent, null, or empty field becomes the EMPTY STRING and keeps its slot:
+# `// empty` (what hook::jq_field uses, where "empty means the caller skips" is
+# the whole contract) would DROP the field here and silently shift every later
+# index onto the wrong filter. Emptiness stays the caller's decision.
+#
+# Returns 1 — with HOOK_JQ_FIELDS empty — when jq is absent or zero filters were
+# requested. Returns 2 when jq is present but cannot parse the payload, or when
+# the record count does not match what was asked for in EITHER direction (an
+# over-count rejects too: two concatenated well-formed JSON documents parse fine
+# and yield twice the records). Advisory callers allow on both codes; a blocking
+# guard branches on the codes and exits 2 on rc 2 (#2157). An advisory caller
+# spells that `|| exit 0`, a PreToolUse ALLOW, so what can reach it matters. NUL
+# CONTENT cannot (#2122). A payload jq itself rejects — malformed JSON, a
+# wrongly typed field, an empty buffer — still can, and process substitution
+# means jq's own exit status is not observed either. Values are CR-stripped, as
+# in hook::jq_field.
+#
+# HOOK_JQ_FIELDS_NUL is set on EVERY call — "1" when any REQUESTED field carried
+# a NUL byte, "0" otherwise, and "0" on every failure path — so a caller can
+# never inherit a stale "1" from an earlier invocation by forgetting to reset it.
+# A caller that owns a block/allow verdict MUST consult it and fail CLOSED.
+#
+# Fields are NUL-separated on the wire, and every value has its own NUL bytes
+# REMOVED jq-side first, so the delimiter provably cannot occur inside a value
+# and the record count does not depend on what a PARSEABLE payload holds.
+# Without the jq-side strip, a raw NUL would split the value in two, fail the
+# cardinality check below, and the callers' `|| exit 0` would turn a PreToolUse
+# BLOCK into a silent ALLOW (#2122).
+#
+# The FLAG is computed from the values as the payload carried them, BEFORE the
+# strip — the ordering is load-bearing and is the one thing a textual merge of
+# this function will get wrong. Strip first and `index(0)` looks at a value that
+# no longer holds a NUL, so the flag reads "0" on every payload and the guards
+# that consult it never fire: a fail-open with no diagnostic, which is the exact
+# defect #2122 filed. Anyone editing the jq program must keep the flag ahead of
+# the strip.
+#
+# Removing the NUL is NOT a claim about how a NUL executes, and must not be read
+# as one. Two behaviors were measured and they disagree: bash DISCARDS a NUL
+# while parsing a command it reads (stdin or a script file), so `echo ha<NUL>rd`
+# prints `hard`; Node's child_process REFUSES a NUL-bearing string outright, on
+# argv, on `shell: true`, and on exec alike. Which of those — if either — a hook
+# payload would ever reach is UNTRACED. No value semantics chosen here can claim
+# fidelity to the executor, in either direction, and none is claimed.
+#
+# That is exactly why the verdict is fail-CLOSED on the flag rather than a match
+# against the value: blocking is correct under deletion, under truncation, and
+# under refusal alike, so it does not depend on anyone having traced the path —
+# and it cannot be invalidated by tracing it later. The flag is the load-bearing
+# part; the value semantics are not.
+#
+# Deletion over truncation is chosen on grounds that appeal to no shell at all,
+# and it is the disposition #2120 already shipped: a truncating helper hides
+# everything after the first NUL from the ten scanning callers #2120 converted,
+# none of which consults the flag, so truncation would make a credential past a
+# NUL invisible to secret-pattern-detection and hardcoded-path-check. Deletion
+# keeps those callers seeing the whole value. The trade runs the other way for a
+# COMMAND caller that forgets the flag — `--no-verify<NUL>x` joins to
+# `--no-verifyx` and matches nothing — which is precisely why the two guards
+# refuse on the flag before reading a value at all, rather than relying on the
+# disposition to keep them safe.
+#
+# split/join (1-arity, a plain string split — NOT gsub, which would put a NUL
+# inside an Oniguruma pattern) for the strip, and explode/index for the flag, so
+# that no regex pattern and no string literal in the jq PROGRAM text carries a
+# NUL byte: a construct whose behavior varied across jq builds would fail EVERY
+# payload, which is strictly worse than the payload-dependent bug being fixed.
+#
+# The library cannot impose the verdict itself — the plugins sourcing it include
+# formatters, for which exiting 2 would be wrong — so policy stays with the
+# caller and the library only reports the fact.
+#
+# Read through a process substitution rather than $( ): command substitution
+# strips NUL bytes, which would eat the separators themselves.
+#
+#   hook::jq_fields "$INPUT" '.tool_input.command' '.tool_name' || exit 0
+#   if ((HOOK_JQ_FIELDS_NUL)); then echo "BLOCKED: …" >&2; exit 2; fi
+#   COMMAND="${HOOK_JQ_FIELDS[0]}" TOOL_NAME="${HOOK_JQ_FIELDS[1]}"
+#
+# The jq process is the last resort, not the first. hook::_fast_fields answers
+# the common shape (a well-formed payload whose requested fields are plain
+# strings under unique keys) with builtins and hands anything it cannot prove
+# to jq, so a hook that reads `.tool_input.command` and `.tool_name` from an
+# ordinary Bash payload spawns nothing. The two entry points are one function:
+# hook::jq_fields is the name every hook calls, and hook::jq_fields_uncached is
+# the same body under the name a dispatcher that puts a per-event cache in
+# front of it (guardrails run-guards.sh) falls through to on a miss. Overriding
+# hook::jq_fields alone therefore never loses the library's own path.
+# shellcheck disable=SC2034  # result globals are consumed by the sourcing hook, not this file
+hook::jq_fields() {
+  hook::jq_fields_uncached "$@"
+}
+
+# shellcheck disable=SC2034  # result globals are consumed by the sourcing hook, not this file
+hook::jq_fields_uncached() {
+  local input="$1"
+  shift
+  HOOK_JQ_FIELDS=()
+  HOOK_JQ_FIELDS_NUL=0
+  (($#)) || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  # The floor first: hook::_fast_fields indexes with an associative array, which
+  # is Bash 4.0+. Below it the whole fast path is skipped and jq answers, rather
+  # than `local -A` failing per call on a shell these hooks support.
+  if hook::_fast_fields_supported && hook::_fast_fields "$input" "$@"; then
+    return 0
+  fi
+  HOOK_JQ_FIELDS=()
+  HOOK_JQ_FIELDS_NUL=0
+  local prog="" filter
+  for filter in "$@"; do
+    [[ -n "$prog" ]] && prog+=","
+    # Raw here: the NUL must still be in the value when the flag is computed
+    # below. The strip happens after, on the whole array.
+    prog+="((${filter}) // \"\" | tostring)"
+  done
+  # The NUL flag rides in front of the values as one more record, so reporting
+  # it costs no second jq process — the whole point of this helper. It is
+  # computed FIRST, from the values exactly as the payload carried them; only
+  # then is each value stripped. `-j` concatenates outputs verbatim, so emitting
+  # the separator as its own output yields exactly value NUL value NUL … with
+  # nothing added. `A | (X, Y)` feeds the SAME array to both branches, so the
+  # flag and the values come from one input with no jq variable in the program
+  # text. Moving the split/join up into the loop above — which is what a textual
+  # merge of this function produces — would silently zero the flag on every
+  # payload.
+  prog="[$prog]"
+  prog+=' | ((if (map(explode | index(0) != null) | any) then "1" else "0" end),'
+  prog+=' (.[] | split("\u0000") | join("")))'
+  prog+=" | (., \"\\u0000\")"
+  local -a values=()
+  local v clean
+  # `read -d ''` (not `mapfile -d ''`, which is Bash 4.4+; this lib supports
+  # 3.2+). The trailing NUL means every value arrives on a successful read.
+  while IFS= read -r -d '' v; do
+    # CR-stripped HERE, not with a jq-side gsub: the Windows jq build writes
+    # stdout in TEXT mode and expands every LF it emits to CRLF, so a value
+    # cleaned inside jq arrives dirty anyway. Stripping after the read removes
+    # both that translation artifact and any CR the payload itself carried —
+    # the same all-CRs-removed contract hook::jq_field has always had.
+    #
+    # Stripped into a scalar FIRST, then appended. Written inline as
+    # `values+=("${v//$'\r'/}")` the substitution silently does nothing (bash
+    # 5.3 leaves the CR in place inside an array-append compound assignment),
+    # which is a failure with no error and no exit status — the value simply
+    # arrives dirty. Observed here, not theorized.
+    clean="${v//$'\r'/}"
+    values+=("$clean")
+  done < <(printf '%s' "$input" | jq -j "$prog" 2>/dev/null)
+  # One record for the flag plus one per filter. Short of that, jq produced no
+  # usable output — it is absent, it failed, or it rejected the payload. What
+  # cannot shorten it is NUL CONTENT: the values carry no separator byte.
+  ((${#values[@]} == $# + 1)) || return 2
+  HOOK_JQ_FIELDS_NUL="${values[0]}"
+  HOOK_JQ_FIELDS=("${values[@]:1}")
+}
+
+# Best-effort jq-free extraction of tool_input.notebook_path, the key a
+# NotebookEdit payload carries INSTEAD of file_path (verified against the
+# tool's own input schema). Same escaped-string match and same contract as
+# hook::raw_file_path, so a notebook payload reaches the jq gate like any
+# other. Returns 1 when no notebook_path is present.
+hook::raw_notebook_path() {
+  [[ "$1" =~ \"notebook_path\"[[:space:]]*:[[:space:]]*\"(([^\"\\]|\\.)*)\" ]] || return 1
+  [[ -n "${BASH_REMATCH[1]}" ]] || return 1
+  printf '%s' "${BASH_REMATCH[1]}"
+}
+
+# Does <path> match any of the <glob>s? Matched with `case`, so the globs are
+# ordinary shell patterns and `*` spans separators.
+#
+# Each glob is tried against the path as it arrived AND against its
+# hook::normalize_path_to form (backslashes folded to slashes; on Windows also
+# a drive fold), so one `*.sh` or `*/.github/workflows/*.yml` list covers a
+# JSON-escaped raw path, a POSIX path and a Win32 path alike. Normalizing is
+# builtins-only, so the second try costs no process.
+#   hook::path_matches "$FILE" '*.sh' '*.bash' || exit 0
+hook::path_matches() {
+  local __hu_pm_path="$1" __hu_pm_norm __hu_pm_glob
+  shift
+  hook::normalize_path_to __hu_pm_norm "$__hu_pm_path"
+  for __hu_pm_glob in "$@"; do
+    # shellcheck disable=SC2254  # the glob is the pattern; quoting would match it literally
+    case "$__hu_pm_path" in
+    $__hu_pm_glob) return 0 ;;
+    *) ;; # try the normalized spelling below, then the next glob
+    esac
+    # shellcheck disable=SC2254  # same, on the normalized spelling
+    case "$__hu_pm_norm" in
+    $__hu_pm_glob) return 0 ;;
+    *) ;; # no match for this glob; try the next
+    esac
+  done
+  return 1
+}
+
+# Build the telemetry `data` object a file-edit hook emits.
+#
+#   hook::data_json_to <dest> <tool> <file> <changed> [<key> array|str <value>]...
+#
+# {tool,file} first, then each declared key in the order given, then `changed`:
+# a boolean when <changed> is "true" or "false", and the key omitted entirely
+# when <changed> is empty, which is the honest shape for a skip arm that never
+# decided whether the file was rewritten. Each <key> is a bare jq identifier
+# (`findings`, `applied`, `action`); `array` values are JSON, `str` values are
+# plain strings.
+#
+# jq is authoritative, and every `array` value arrives on STDIN rather than as
+# an --argjson. Those arrays are uncapped by design and Windows caps a process
+# command line at 32767 characters, so a file with a few hundred findings
+# fails `jq` outright there and the fallback would emit an envelope claiming
+# ZERO findings for the noisiest files in the repository. A payload that lies
+# is worse than no payload. <tool> and <file> stay arguments: both are bounded
+# by a path length.
+#
+# The fallback is a fixed empty-shape object — never an interpolation of
+# <tool>/<file>, which could inject a quote or a backslash from a path and
+# corrupt the envelope. It is essentially unreachable (when jq is absent
+# hook::emit_telemetry drops the envelope anyway), so losing the values there
+# is harmless and strictly safer than emitting malformed JSON.
+hook::data_json_to() {
+  local __hu_dj_dest="$1" __hu_dj_tool="$2" __hu_dj_file="$3" __hu_dj_changed="$4"
+  shift 4
+  local __hu_dj_stdin="{" __hu_dj_sep=""
+  # shellcheck disable=SC2016  # jq program text: $tool and $file are jq's own variables
+  local __hu_dj_prog='{tool:$tool,file:$file}'
+  local __hu_dj_fallback='{"tool":"","file":""'
+  local -a __hu_dj_args=(--arg tool "$__hu_dj_tool" --arg file "$__hu_dj_file"
+    --arg changed "$__hu_dj_changed")
+  local __hu_dj_key __hu_dj_kind __hu_dj_val
+  while (($# >= 3)); do
+    __hu_dj_key="$1"
+    __hu_dj_kind="$2"
+    __hu_dj_val="$3"
+    shift 3
+    case "$__hu_dj_kind" in
+    array)
+      __hu_dj_stdin+="${__hu_dj_sep}\"${__hu_dj_key}\":${__hu_dj_val:-[]}"
+      __hu_dj_sep=","
+      __hu_dj_prog+=" + {${__hu_dj_key}: .${__hu_dj_key}}"
+      __hu_dj_fallback+=",\"${__hu_dj_key}\":[]"
+      ;;
+    *)
+      __hu_dj_args+=(--arg "$__hu_dj_key" "$__hu_dj_val")
+      __hu_dj_prog+=" + {${__hu_dj_key}: \$${__hu_dj_key}}"
+      __hu_dj_fallback+=",\"${__hu_dj_key}\":\"\""
+      ;;
+    esac
+  done
+  __hu_dj_stdin+="}"
+  __hu_dj_fallback+="}"
+  # shellcheck disable=SC2016  # jq program text: $changed is jq's own variable
+  __hu_dj_prog+=' + (if $changed == "" then {} else {changed: ($changed == "true")} end)'
+  local __hu_dj_out=""
+  __hu_dj_out=$(printf '%s' "$__hu_dj_stdin" |
+    jq -c "${__hu_dj_args[@]}" "$__hu_dj_prog" 2>/dev/null) || __hu_dj_out=""
+  # The Windows jq build writes stdout in TEXT mode and expands every LF to
+  # CRLF; the envelope is one line, so a trailing CR would ride into it.
+  __hu_dj_out="${__hu_dj_out//$'\r'/}"
+  [[ -n "$__hu_dj_out" ]] || __hu_dj_out="$__hu_dj_fallback"
+  printf -v "$__hu_dj_dest" '%s' "$__hu_dj_out"
+}
+
+# ============================================================================
+# hook::begin — the file-edit hook prologue as ONE call
+# ============================================================================
+#
+# A PostToolUse hook acting on the file just written needs the same context
+# every time, and the ORDER is the load-bearing part: the jq-free
+# applicability pre-filter runs before the jq gate (a missing-jq notice must
+# never fire for an edit the hook would not have processed anyway), the gate
+# before the parsed read, the repo root before the repo-relative path, and the
+# telemetry-only values behind the sink opt-in so the unwired default path
+# spawns nothing to build them.
+#
+#   hook::begin [<flag>...] <plugin> <event> [<glob>...]
+#
+# <plugin> is the label the skip notices carry. Sets, in the CALLER's shell:
+#
+#   start              $EPOCHREALTIME at entry, or empty on bash before 5.0 —
+#                      the caller's signal to skip telemetry rather than abort
+#   INPUT              the buffered payload
+#   RAW_FILE           the JSON-escaped path the pre-filter matched
+#   FILE               the parsed, existence- and scope-checked path
+#   FILE_BASE          FILE's last component, trimmed on either separator so a
+#                      mixed-form Windows path still yields it
+#   FILE_DIR           FILE's directory, split on either separator on Windows
+#                      and on `/` alone on POSIX (`.` for a bare name, `/` under
+#                      the filesystem root, where the strip leaves an empty
+#                      string that hook::repo_root_to would read as the process
+#                      CWD, and `C:\` or `C:/` under a drive root)
+#   REPO_ROOT          the consuming repo root, anchored at FILE_DIR
+#   TOOL               tool_name, ONLY when a telemetry sink is wired
+#   FILE_REL           the repo-relative path the telemetry schema requires,
+#                      degrading to the basename so an absolute path never
+#                      reaches telemetry; resolved when a sink is wired, or
+#                      always under --relative
+#   FILE_REL_DEGRADED  1 when that degrade happened
+#   HOOK_PLUGIN        <plugin>, the default telemetry hook id at hook::finish
+#   HOOK_EVENT         <event>, the event hook::finish emits under
+#
+# and EXITS 0 itself on every path where the hook has nothing to do: stdin
+# empty, malformed, or cut short mid-document (hook::buffer_stdin_to rc 1, 2
+# and 3 alike — an advisory PostToolUse hook allows all three, since the tool
+# already ran); no path in the payload, or one no <glob> matches; jq absent,
+# after hook::require's once per session and agent skip notice; a path
+# hook::read_file_path rejects.
+#
+# No <glob> means "any payload carrying a path", for a hook whose matcher is
+# already its whole filter. The globs are checked twice, once on the jq-free
+# raw path and once on the parsed one, because the raw extraction is a
+# best-effort regex and the parsed path is the authoritative answer.
+#
+# Flags:
+#   --relative       resolve FILE_REL even with no sink wired, for a hook that
+#                    hands its tool a repository-relative argument. Two cygpath
+#                    processes on Windows, which is why it is opt-in.
+#   --no-membership  parse and existence-check the path without the
+#                    CLAUDE_PROJECT_DIR scope (see HOOK_READ_FILE_PATH_UNSCOPED
+#                    at hook::read_file_path).
+#   --notebook       also accept a NotebookEdit payload, whose target is
+#                    tool_input.notebook_path; the path is copied onto
+#                    file_path so the shared reader — and its scoping, which is
+#                    the load-bearing part — stays the single place a path is
+#                    admitted. An explicit file_path always wins.
+#   --repo-root <fn> resolve REPO_ROOT with <fn> (called as `<fn> REPO_ROOT
+#                    <dir>`) instead of hook::repo_root_to, for a hook whose
+#                    ceiling contract is not git's answer.
+#   --pre-jq <fn>    call `<fn> "$RAW_FILE"` immediately before the jq gate,
+#                    for a hook that must settle its own consumer opt-in before
+#                    the gate can nag about a prerequisite that opt-in does not
+#                    need. <fn> may exit 0 itself.
+# shellcheck disable=SC2034  # the caller's contract: every name above is read by the hook, not here
+hook::begin() {
+  local __hu_bg_relative=0 __hu_bg_unscoped=0 __hu_bg_notebook=0
+  local __hu_bg_root_fn="" __hu_bg_prejq_fn=""
+  while (($#)); do
+    case "$1" in
+    --relative) __hu_bg_relative=1 ;;
+    --no-membership) __hu_bg_unscoped=1 ;;
+    --notebook) __hu_bg_notebook=1 ;;
+    --repo-root)
+      __hu_bg_root_fn="$2"
+      shift
+      ;;
+    --pre-jq)
+      __hu_bg_prejq_fn="$2"
+      shift
+      ;;
+    *) break ;;
+    esac
+    shift
+  done
+  local __hu_bg_plugin="$1" __hu_bg_event="$2"
+  shift 2
+  # The label and the event, kept for hook::finish so the exit arm restates
+  # neither. HOOK_PLUGIN doubles as the default telemetry hook id.
+  HOOK_PLUGIN="$__hu_bg_plugin"
+  HOOK_EVENT="$__hu_bg_event"
+
+  # EPOCHREALTIME is Bash 5.0+; on older bash it is unset, so default to empty
+  # — referencing it bare under `set -u` would abort before the advisory
+  # exit 0 and fail every edit. Captured first so duration_ms covers the whole
+  # run; the exits below are pre-work and emit no telemetry.
+  start=${EPOCHREALTIME:-}
+
+  # Read inherited fd0 ONCE, here. Every path-reading step below is fed the
+  # buffered payload, because reading fd0 twice would drain the pipe on the
+  # second read — and on Windows Git Bash that pipe is a Win32 pipe that
+  # `/dev/stdin` cannot resolve at all.
+  hook::buffer_stdin_to INPUT || exit 0
+
+  RAW_FILE=""
+  hook::raw_file_path_to RAW_FILE "$INPUT" || :
+  if [[ -z "$RAW_FILE" ]] && ((__hu_bg_notebook)); then
+    RAW_FILE=$(hook::raw_notebook_path "$INPUT") || RAW_FILE=""
+  fi
+  [[ -n "$RAW_FILE" ]] || exit 0
+  if (($#)); then
+    # Matched on the UNESCAPED spelling. RAW_FILE is the JSON string literal's
+    # contents, still escaped, so a Windows payload carries `C:\\repo\\x.yml`;
+    # normalizing that turns each of the two backslashes into a slash and the
+    # caller's glob then has to be written loose on separators
+    # (`*/.github/*workflows/*.yml`) to survive the doubling. Collapsing the
+    # escape here lets every caller write the separator its path actually has,
+    # and the same glob list serves this pre-filter and the authoritative
+    # re-check on the parsed path below. Only ever widens what the pre-filter
+    # admits, and that re-check is what decides.
+    hook::path_matches "${RAW_FILE//\\\\/\\}" "$@" || exit 0
+  fi
+
+  [[ -n "$__hu_bg_prejq_fn" ]] && "$__hu_bg_prejq_fn" "$RAW_FILE"
+
+  # jq is load-bearing for input parsing; absent → visible once per session and agent
+  # skip notice instead of a silent no-op (dim-9 doctrine).
+  hook::require jq "$__hu_bg_event" "$__hu_bg_plugin" "$INPUT"
+
+  # The jq runs only for a payload whose raw text carries a notebook_path,
+  # because without one the filter's own condition is false and it hands the
+  # payload back unchanged. The textual pre-check is deliberately BROADER than
+  # the filter's `.tool_input.notebook_path`: it can admit a payload the filter
+  # no-ops on, never reject one the filter would have acted on. Every ordinary
+  # Write and Edit reaches this line and none of them is a notebook, so on the
+  # hot path this is one fewer jq. A jq failure leaves INPUT exactly as it
+  # arrived rather than emptying it.
+  if ((__hu_bg_notebook)) && hook::raw_notebook_path "$INPUT" >/dev/null; then
+    local __hu_bg_normalized
+    __hu_bg_normalized=$(printf '%s' "$INPUT" | jq -c '
+      if ((.tool_input.file_path // "") == "") and ((.tool_input.notebook_path // "") != "")
+      then .tool_input.file_path = .tool_input.notebook_path
+      else . end' 2>/dev/null) &&
+      [[ -n "$__hu_bg_normalized" ]] && INPUT="$__hu_bg_normalized"
+  fi
+
+  local HOOK_READ_FILE_PATH_UNSCOPED="$__hu_bg_unscoped"
+  FILE=""
+  hook::read_file_path_to FILE "$INPUT" || exit 0
+  if (($#)); then
+    hook::path_matches "$FILE" "$@" || exit 0
+  fi
+
+  # Basename and directory by parameter expansion, never `basename`/`dirname`:
+  # GNU Bash forks a subshell for every command substitution even when the body
+  # is a single exec (Command Substitution, Bash Reference Manual;
+  # https://mywiki.wooledge.org/CommandSubstitution), and this runs on every
+  # Write and Edit. The two fallbacks cover the shapes where the strip and
+  # dirname disagree: a bare relative filename, where dirname answers `.`, and
+  # a file directly under the filesystem root, where the strip leaves an empty
+  # string and dirname answers `/`. On Windows the directory strip splits on
+  # either separator, so a backslash-only path yields its own directory, not `.`
+  # (which would resolve the CWD's repository). On POSIX a backslash is a
+  # filename character, so `/a/b\c.md` stays in `/a`. A bare drive keeps its
+  # separator: `C:` alone is drive-relative, the drive's current directory.
+  FILE_BASE="${FILE##*/}"
+  FILE_BASE="${FILE_BASE##*\\}"
+  FILE_DIR="${FILE%/*}"
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32) FILE_DIR="${FILE%[/\\]*}" ;;
+  *) ;; # POSIX: keep the slash-only split
+  esac
+  [[ "$FILE_DIR" == "$FILE" ]] && FILE_DIR=.
+  [[ -n "$FILE_DIR" ]] || FILE_DIR=/
+  [[ "$FILE_DIR" == [A-Za-z]: ]] && FILE_DIR+="${FILE:2:1}"
+
+  # File-anchored, not CWD-anchored: the hook process CWD is not guaranteed to
+  # be the repo root, and the root bounds every opt-in walk and names data.file.
+  REPO_ROOT=""
+  if [[ -n "$__hu_bg_root_fn" ]]; then
+    "$__hu_bg_root_fn" REPO_ROOT "$FILE_DIR"
+  else
+    hook::repo_root_to REPO_ROOT "$FILE_DIR"
+  fi
+
+  # TOOL feeds the telemetry data object and nothing else, so it is parsed only
+  # when a sink is wired: the unwired default path spawns zero telemetry-only
+  # subprocesses (the tool_name parse, and 2x cygpath on Windows inside
+  # hook::repo_relative_path_to).
+  TOOL=""
+  FILE_REL="$FILE"
+  FILE_REL_DEGRADED=0
+  if ((__hu_bg_relative)); then
+    FILE_REL=""
+    hook::repo_relative_path_to FILE_REL "$FILE" "$REPO_ROOT" || FILE_REL_DEGRADED=1
+  fi
+  if hook::telemetry_enabled; then
+    hook::jq_fields "$INPUT" '.tool_name' && TOOL="${HOOK_JQ_FIELDS[0]}"
+    if ((__hu_bg_relative == 0)); then
+      FILE_REL=""
+      hook::repo_relative_path_to FILE_REL "$FILE" "$REPO_ROOT" || FILE_REL_DEGRADED=1
+    fi
+  fi
+  return 0
+}
+
+# ============================================================================
+# hook::finish — the exit arm as ONE call
+# ============================================================================
+#
+# The bookend to hook::begin. Every arm a file-edit hook can exit on owes the
+# same three steps, and the ORDER is the load-bearing part:
+#
+#   1. take the rewrite disclosure — that is also what settles the byte
+#      verdict data.changed reports and what releases the guard's snapshot;
+#   2. emit telemetry, so the envelope carries the verdict step 1 just settled;
+#   3. emit the ONE stdout document — Claude Code parses a hook's whole stdout
+#      as a single JSON document, so an arm that both rewrote the file and has
+#      findings composes both channels here instead of printing twice.
+#
+#   hook::finish [<flag>...] <status> [<key> <kind> <value>]...
+#
+# <status> is the telemetry status the arm reports ("ok" when the tool ran to
+# judgment, "skipped" when it never did, "error"). The trailing triples are the
+# telemetry data keys, passed through to hook::data_json_to unchanged.
+#
+# EXITS 0. There is no arm after the arm that finishes, and an exiting finish
+# is what makes "exactly one document" structural rather than a rule each hook
+# has to keep.
+#
+# Flags:
+#   --context <text>  the agent channel (additionalContext): findings, a tool
+#                     break diagnostic, whatever the model is owed
+#   --message <text>  the user channel (systemMessage) the caller composed. The
+#                     rewrite disclosure, when there is one, goes FIRST and
+#                     this follows on its own line
+#   --disclose <text> the disclosure to take: emitted on the user channel when
+#                     the file differs from the snapshot hook::rewrite_guard_begin
+#                     took, dropped silently when it does not. Omit it on an arm
+#                     that cannot have rewritten anything — the take still runs,
+#                     because settling data.changed and releasing the snapshot
+#                     are owed on every arm
+#   --changed <v>     the data.changed verdict for a hook that decides it from
+#                     its tool's own report rather than from a byte comparison
+#                     ("true"/"false", or empty to omit the key). Overrides the
+#                     guard's verdict
+#   --id <hook-id>    the telemetry hook id, when it is not the label
+#                     hook::begin was given
+#
+# TOOL, FILE_REL, REPO_ROOT, start, HOOK_PLUGIN and HOOK_EVENT are hook::begin's
+# outputs, read here rather than restated by every caller.
+hook::finish() {
+  local __hu_fi_ctx="" __hu_fi_msg="" __hu_fi_disclose="" __hu_fi_changed=""
+  local __hu_fi_changed_set=0 __hu_fi_id="${HOOK_PLUGIN:-}"
+  while (($#)); do
+    case "$1" in
+    --context)
+      __hu_fi_ctx="$2"
+      shift
+      ;;
+    --message)
+      __hu_fi_msg="$2"
+      shift
+      ;;
+    --disclose)
+      __hu_fi_disclose="$2"
+      shift
+      ;;
+    --changed)
+      __hu_fi_changed="$2"
+      __hu_fi_changed_set=1
+      shift
+      ;;
+    --id)
+      __hu_fi_id="$2"
+      shift
+      ;;
+    *) break ;;
+    esac
+    shift
+  done
+  local __hu_fi_status="$1"
+  shift
+
+  # Only a hook that can rewrite the edited file sources rewrite-guard.sh, so
+  # the take is conditional on the companion lib being loaded. `declare -F` is
+  # a builtin: the probe costs no process on the hooks that never rewrite.
+  local __hu_fi_sysmsg=""
+  if declare -F hook::rewrite_take_disclosure >/dev/null 2>&1; then
+    hook::rewrite_take_disclosure "" "$__hu_fi_disclose"
+    # shellcheck disable=SC2154  # the take's two outputs, assigned in rewrite-guard.sh
+    __hu_fi_sysmsg="$HOOK_REWRITE_MESSAGE"
+    ((__hu_fi_changed_set)) || __hu_fi_changed="${HOOK_REWRITE_CHANGED:-}"
+  fi
+  if [[ -n "$__hu_fi_msg" ]]; then
+    [[ -n "$__hu_fi_sysmsg" ]] && __hu_fi_sysmsg+=$'\n'
+    __hu_fi_sysmsg+="$__hu_fi_msg"
+  fi
+
+  # Two guards, the same two every hand-rolled emit_tel carried: the high-res
+  # start stamp (empty on bash before 5.0, where telemetry is skipped so the
+  # hook still formats rather than aborting) and the sink opt-in. The data
+  # payload costs a jq process, so it is built behind both — never on the
+  # unwired path.
+  if [[ -n "${start:-}" ]] && hook::telemetry_enabled; then
+    local __hu_fi_data=""
+    hook::data_json_to __hu_fi_data "${TOOL:-}" "${FILE_REL:-}" "$__hu_fi_changed" "$@"
+    hook::emit_telemetry "$__hu_fi_id" "${HOOK_EVENT:-}" "$__hu_fi_status" \
+      "$start" "$__hu_fi_data" "${REPO_ROOT:-}"
+  fi
+
+  hook::emit_channels "${HOOK_EVENT:-}" "$__hu_fi_ctx" "$__hu_fi_sysmsg"
+  exit 0
+}
+
+# Reduce a tool + optional Bash command to a privacy-safe subject label. For
+# Bash, returns "Bash:<first-token>" (leading sudo / VAR=val prefixes stripped,
+# basename applied) — never the full command. For any other tool, returns the
+# tool name unchanged. Carries no argument body, path, or command tail.
+#
+# Whitespace-splitting is only safe when no quoted value spans the whitespace.
+# A quoted assignment value (e.g. `TOKEN="a b" curl …`) would otherwise leak a
+# fragment of the value into the token, so any token carrying a quote aborts to a
+# bare "Bash" subject rather than risk exposing part of the value.
+#
+# A bare or trailing unquoted assignment that no following command consumed
+# (e.g. the whole command is `TOKEN=ghp_…`) is likewise a value the subject must
+# not carry, so a resolved token still shaped like a NAME=value assignment aborts
+# to the bare "Bash" subject too.
+#   hook::extract_bash_subject_to SUBJECT "$TOOL" "$CMD"   # in this shell
+#   SUBJECT=$(hook::extract_bash_subject "$TOOL" "$CMD")   # print form: a fork
+hook::extract_bash_subject() {
+  local __hu_subject
+  hook::extract_bash_subject_to __hu_subject "$1" "${2:-}"
+  printf '%s' "$__hu_subject"
+}
+
+hook::extract_bash_subject_to() {
+  local __hu_dest="$1" tool="$2" cmd="${3:-}"
+  if [[ "$tool" != "Bash" ]]; then
+    printf -v "$__hu_dest" '%s' "$tool"
+    return 0
+  fi
+  # Trim leading whitespace so the first token is real.
+  cmd="${cmd#"${cmd%%[![:space:]]*}"}"
+  local first_token="${cmd%%[[:space:]]*}"
+  while [[ "$first_token" == "sudo" || "$first_token" == *=* ]] &&
+    [[ -n "$cmd" && "$cmd" == *[[:space:]]* ]]; do
+    # A quote in the prefix token means a quoted value spans the next whitespace;
+    # we cannot tokenize it safely — bail rather than leak a value fragment.
+    if [[ "$first_token" == *[\"\']* ]]; then
+      printf -v "$__hu_dest" '%s' "$tool"
+      return 0
+    fi
+    cmd="${cmd#*[[:space:]]}"
+    cmd="${cmd#"${cmd%%[![:space:]]*}"}"
+    first_token="${cmd%%[[:space:]]*}"
+  done
+  # The resolved command token itself must not carry a quote (e.g. a value that
+  # ended here), which would likewise be a value fragment.
+  if [[ "$first_token" == *[\"\']* ]]; then
+    printf -v "$__hu_dest" '%s' "$tool"
+    return 0
+  fi
+  # A resolved token still shaped like a bare/trailing assignment (no following
+  # command word consumed it in the strip loop) would emit the assignment's
+  # value — a possible credential — as the subject; bail to the bare "Bash"
+  # subject as with a quoted value. All valid Bash assignment forms count:
+  # NAME=value, append NAME+=value, and subscripted NAME[idx]=value /
+  # NAME[idx]+=value — the subscript matched greedily (`.*`) because Bash
+  # accepts nested subscripts like NAME[1+IDX[0]]=value, which a
+  # no-close-bracket class would miss. This runs BEFORE the basename strip so
+  # a path-valued assignment (TOKEN=/a/b/secret) cannot lose its "=" first.
+  if [[ "$first_token" =~ ^[a-zA-Z_][a-zA-Z0-9_]*(\[.*\])?\+?= ]]; then
+    printf -v "$__hu_dest" '%s' "$tool"
+    return 0
+  fi
+  first_token="${first_token##*/}"
+  if [[ -n "$first_token" ]]; then
+    printf -v "$__hu_dest" 'Bash:%s' "$first_token"
+  else
+    printf -v "$__hu_dest" '%s' "$tool"
+  fi
+}
+
+# Append one line to a JSONL file, serialized under an flock advisory lock when
+# flock is present (bounded 2s wait; a lost race drops the line rather than
+# blocking) and a best-effort bare append otherwise. Fire-and-forget: never
+# fails the caller. Used by audit hooks that maintain a bespoke second store.
+#   hook::append_jsonl <file> <line>
+hook::append_jsonl() {
+  local file="$1" line="$2"
+  if command -v flock >/dev/null 2>&1; then
+    (
+      flock -w 2 9 || exit 0
+      printf '%s\n' "$line" >>"$file"
+    ) 9>"${file}.lock" 2>/dev/null
+  else
+    printf '%s\n' "$line" >>"$file" 2>/dev/null
+  fi
+}
+
+# Per-hook stdout context accumulator. ctx_reset at entry, ctx_append per line,
+# then either ctx_take_to (handing the agent channel to hook::finish, which
+# owns the emit) or 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'
+}
+
+# Write the accumulated context, whitespace-trimmed, into <dest> and clear the
+# buffer — for a hook whose exit arm hands the agent channel to hook::finish,
+# which owns the emit and must not have a second document printed under it.
+hook::ctx_take_to() {
+  local __hu_ct_trimmed="${_HOOK_CTX_BUFFER%"${_HOOK_CTX_BUFFER##*[![:space:]]}"}"
+  __hu_ct_trimmed="${__hu_ct_trimmed#"${__hu_ct_trimmed%%[![:space:]]*}"}"
+  hook::ctx_reset
+  printf -v "$1" '%s' "$__hu_ct_trimmed"
+}
+
+# Emit the accumulated context as hookSpecificOutput JSON, then clear the buffer.
+# Composes through hook::emit_channels: one builder for the document, and the
+# agent channel of an always-on hook costs no process to write.
+hook::ctx_flush() {
+  local __hu_cf_trimmed=""
+  hook::ctx_take_to __hu_cf_trimmed
+  hook::emit_channels "$1" "$__hu_cf_trimmed" ""
+}
+
+# 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.
+#
+# The envelope is assembled with shell builtins (hook::json_escape_jq_to for
+# the string fields, hook::json_compact_to for the caller's data object) as
+# ONE compact line, `jq -c` style: the same document, field order and
+# escapes the jq filter below produces, with the data object compacted
+# exactly as jq compacts its own output. That path needs no jq, no temp file
+# and no subprocess. When the data object cannot be proven jq-idempotent (see
+# hook::json_compact_to), the jq path runs, now with -c so both paths write
+# the same bytes, and there jq's absence is still fail-open: return 0, no
+# envelope. Before this the envelope was jq's default pretty-printed form
+# (several lines, and CRLF line endings with a Windows jq); the sink contract
+# was always "one JSON document on stdin", and a compact line is also valid
+# JSONL for a sink that appends raw envelopes.
+#
+# 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() {
+  [[ -n "${HOOK_TELEMETRY_SINK:-}" ]] || 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).
+  # EPOCHREALTIME is Bash 5.0+; on an older host it (and the caller's start
+  # snapshot) is empty. Skip telemetry fail-open rather than abort under set -u —
+  # the same silent-skip the caller's `START=${EPOCHREALTIME:-}` guard intends.
+  local now=${EPOCHREALTIME:-}
+  [[ -n "$start_epoch" && -n "$now" ]] || return 0
+  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). The %()T printf format is Bash 4.2+, and printf -v keeps it in the
+  # shell (a `$(...)` capture is a fork); an older bash, or a printf that
+  # binds nothing, falls back to date -u.
+  local timestamp=""
+  TZ=UTC printf -v timestamp '%(%Y-%m-%dT%H:%M:%SZ)T' -1 2>/dev/null || timestamp=""
+  [[ -n "$timestamp" ]] || timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null) || timestamp=""
+
+  # Correlation keys (contract 1.1): session_id, prompt_id, tool_use_id and
+  # agent_id, read from the hook payload and placed on the envelope spine so a
+  # sink can file the row per session without every producer repeating the
+  # extraction. The payload is whatever the caller buffered: HOOK_TELEMETRY_PAYLOAD
+  # when set, else INPUT, the variable every fleet hook assigns from
+  # hook::buffer_stdin (that call runs in a command substitution, so the
+  # library cannot cache the buffer itself). A caller that buffered under
+  # another name sets HOOK_TELEMETRY_PAYLOAD before emitting. Each key is the
+  # first `"<key>":"<value>"` pair AT THE PAYLOAD ROOT whose value is a plain
+  # id ([A-Za-z0-9._-]); absent or malformed keys are omitted, never guessed,
+  # and the values need no JSON escaping by construction. No jq, no subprocess.
+  #
+  # ROOT ONLY, AND EVERY ROOT KEY. Searching the raw payload takes the leftmost
+  # match anywhere in it, which reads `tool_input.options.prompt_id` as the
+  # envelope's prompt_id and lets a nested `session_id` ahead of the real one
+  # file the row under the WRONG session. Truncating at the first nested
+  # container fixes that but loses `tool_use_id`, which the documented payload
+  # places AFTER `tool_input` (session-event-log.sh says so in its own early-stop
+  # note: "tool_input closed, tool_use_id still to come"), so the keys are
+  # instead selected by depth.
+  #
+  # The payload is rendered down to its root level first, then searched. Escaped
+  # backslashes and quotes are neutralized so that splitting on `"` cannot land
+  # inside an escape, and the split alternates: even fields are structure
+  # (braces, commas, colons, numbers), odd fields are string bodies. Walking
+  # them costs one step per string, not one per byte, and the bulk of a payload
+  # is a handful of huge string bodies that are skipped whole. A string body is
+  # kept only at depth 1; deeper ones are dropped, which leaves nested objects
+  # as brace-and-colon rubble carrying no quotes, so no nested key can match.
+  # What remains is small, so the four searches run over a short string however
+  # large the payload was — the reason this stays inside the latency budget that
+  # keeps jq off this path.
+  local corr="" corr_key corr_payload="${HOOK_TELEMETRY_PAYLOAD-${INPUT-}}"
+  if [[ -n "$corr_payload" ]]; then
+    # `[[{]` is a bracket expression holding `[` and `{`; the brace is safe
+    # there only because it is a regex bracket expression, not a `${...}`
+    # pattern, where a literal `}` would end the expansion. Used by the size
+    # gate fallback below.
+    local corr_cut=':[[:space:]]*[[{]'
+    # Only a payload within the size gate is walked; see the fallback below for
+    # what the gate costs and why. The two neutralizing passes are what make
+    # splitting on `"` safe, and each copies the payload, so a payload with no
+    # backslash in it skips both; that test short-circuits at the first one.
+    local corr_t=""
+    if ((${#corr_payload} <= 65536)); then
+      corr_t=$corr_payload
+      if [[ $corr_t == *\\* ]]; then
+        corr_t=${corr_t//"\\\\"/@@}
+        corr_t=${corr_t//"\\\""/@@}
+      fi
+    fi
+    local corr_parts corr_i corr_n corr_depth=0 corr_root="" corr_seg corr_x
+    local corr_o corr_c
+    # Brace characters come from variables: a literal `}` inside a `${...}`
+    # pattern ends the expansion before the pattern is read. Each one is
+    # counted by deleting it and taking the length difference — a negated
+    # bracket class is not usable here, because `[!]}]` does not parse as the
+    # "neither ] nor }" class it looks like (it counted `{` as a closer).
+    local corr_ob='{' corr_cb='}' corr_osb='[' corr_csb=']'
+    local corr_glob=0
+    [[ $- == *f* ]] || corr_glob=1
+    set -f
+    local IFS='"'
+    # shellcheck disable=SC2206 # splitting on IFS='"' is the whole point
+    corr_parts=($corr_t)
+    ((corr_glob)) && set +f
+    IFS=$' \t\n'
+    corr_n=${#corr_parts[@]}
+    # An even field count means an unbalanced quote: the payload is malformed,
+    # so no key is guessed from it. A payload past the size gate never got
+    # split (corr_n is 1 there), so it falls through to the head cut below.
+    if ((corr_n % 2 == 1 && corr_n > 1)); then
+      for ((corr_i = 0; corr_i < corr_n; corr_i++)); do
+        if ((corr_i % 2 == 0)); then
+          corr_seg=${corr_parts[corr_i]}
+          corr_root+=$corr_seg
+          corr_x=${corr_seg//"$corr_ob"/}
+          corr_o=$((${#corr_seg} - ${#corr_x}))
+          corr_x=${corr_seg//"$corr_osb"/}
+          corr_o=$((corr_o + ${#corr_seg} - ${#corr_x}))
+          corr_x=${corr_seg//"$corr_cb"/}
+          corr_c=$((${#corr_seg} - ${#corr_x}))
+          corr_x=${corr_seg//"$corr_csb"/}
+          corr_c=$((corr_c + ${#corr_seg} - ${#corr_x}))
+          corr_depth=$((corr_depth + corr_o - corr_c))
+        elif ((corr_depth == 1)); then
+          corr_root+='"'${corr_parts[corr_i]}'"'
+        fi
+      done
+    else
+      # SIZE GATE FALLBACK. Above the gate the walk is not affordable: the
+      # neutralizing passes are superlinear in the number of escapes, measured
+      # here at 4 / 13 / 38 / 486 ms per emit for a 16 KiB / 64 KiB / 128 KiB /
+      # 512 KiB escape-bearing payload, and this runs on every telemetry-
+      # emitting hook. So a large payload is cut at its first nested container
+      # instead. That is still safe — nothing inside tool_input or
+      # tool_response is reachable — but it is not complete: a root key placed
+      # after the first container, which is where tool_use_id sits, is omitted
+      # rather than guessed. session_id and prompt_id lead the payload, so
+      # routing is unaffected. #3784 tracks a cheaper exact tail scan that
+      # would close the gap without paying the neutralizing passes.
+      corr_root=$corr_payload
+      if [[ "$corr_root" =~ $corr_cut ]]; then
+        corr_root=${corr_root%%"${BASH_REMATCH[0]}"*}
+      fi
+    fi
+    for corr_key in session_id prompt_id tool_use_id agent_id; do
+      if [[ "$corr_root" =~ \"$corr_key\"[[:space:]]*:[[:space:]]*\"([A-Za-z0-9._-]+)\" ]]; then
+        corr+='"'"$corr_key"'":"'"${BASH_REMATCH[1]}"'",'
+      fi
+    done
+  fi
+
+  # Trailing whitespace after the object (a newline a caller left on the
+  # value) does not change what jq parses, so it does not block the builtin
+  # path either.
+  local envelope="" data="" data_trim="$data_json"
+  while [[ "$data_trim" == *[$' \t\r\n'] ]]; do
+    data_trim="${data_trim%?}"
+  done
+  if [[ "$data_trim" == \{*\} ]] && hook::json_compact_to data "$data_trim"; then
+    # Builtin envelope: the same document the jq filter below produces, field
+    # for field, with jq's string escaping and jq's compact data.
+    local e_timestamp e_hook e_event e_status
+    hook::json_escape_jq_to e_timestamp "$timestamp"
+    hook::json_escape_jq_to e_hook "$hook_id"
+    hook::json_escape_jq_to e_event "$hook_event"
+    hook::json_escape_jq_to e_status "$status"
+    envelope='{"schema_version":"1.1","timestamp":"'"$e_timestamp"'","hook":"'"$e_hook"'","hook_event":"'"$e_event"'","status":"'"$e_status"'","duration_ms":'"$duration_ms"','"$corr"'"data":'"$data"'}'
+  else
+    # jq path, for a data object the builtin compactor cannot prove. Fail-open:
+    # jq absent → return 0. The `data` object is written to a temp file, not
+    # passed as --argjson, so payloads larger than the Windows 32767-character
+    # command-line cap are not dropped before jq runs (#1595). /dev/stdin is
+    # not used: jq's --slurpfile there is not portable on Windows. Redirect jq
+    # stderr to /dev/null; output goes to a local variable — never to fd1.
+    command -v jq >/dev/null 2>&1 || return 0
+    local data_file
+    data_file=$(mktemp) || return 0
+    printf '%s' "$data_json" >"$data_file" || {
+      rm -f "$data_file"
+      return 0
+    }
+    envelope=$(jq -nc \
+      --arg schema_version "1.1" \
+      --arg timestamp "$timestamp" \
+      --arg hook "$hook_id" \
+      --arg hook_event "$hook_event" \
+      --arg status "$status" \
+      --argjson duration_ms "$duration_ms" \
+      --argjson corr "{${corr%,}}" \
+      --slurpfile data "$data_file" \
+      '{schema_version:$schema_version,timestamp:$timestamp,hook:$hook,hook_event:$hook_event,status:$status,duration_ms:$duration_ms} + $corr + {data:($data[0] // {})}' \
+      2>/dev/null) || {
+      rm -f "$data_file"
+      return 0
+    }
+    rm -f "$data_file"
+  fi
+
+  # 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) &
+}
+
+# ---------------------------------------------------------------------------
+# Argv-grammar-faithful Bash command parsing for git guards. 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 is resolved at
+# the segment's command position past env-var assignments and known wrappers,
+# and its subcommand resolved past git global options.
+#
+# Static matching over the literal command string only: shell variable and
+# command substitution ($VAR, $(…)) are NOT evaluated. Guards built on this
+# are friction against accidental/casual bypass, not a sandbox.
+
+# 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).
+#
+# hook::ansi_c_decode_to <var> <body> writes in THIS shell and is the only
+# spelling. A capture around it would be a fork even though the body is only
+# `printf` (Command Substitution, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution), and Cygwin's fork is a
+# non-copy-on-write Win32 CreateProcess (Cygwin User's Guide, Process
+# Creation).
+hook::ansi_c_decode_to() {
+  local __hu_acd_b="${2//%/%%}"
+  # shellcheck disable=SC2059  # the body IS the format — that is how ANSI-C escapes decode; %-escaped above so it cannot inject a specifier
+  printf -v "$1" -- "$__hu_acd_b" 2>/dev/null || printf -v "$1" '%s' ""
+}
+
+# Split a GNU `env -S` operand the way env does: whitespace-separated words
+# honoring "…" and '…' quotes and backslash escapes — so a flag quoted inside
+# the operand (`env -S 'git push "--force"'`) still surfaces as its unquoted
+# argv word. env's $VAR expansion inside the operand is NOT evaluated (static
+# analysis over the literal string — same residual as the segment tokenizer).
+# Result in the global HOOK_ENV_S_WORDS array.
+# shellcheck disable=SC2034  # result global is consumed by hook::git_resolve_index
+# shellcheck disable=SC1003  # '\' compares a literal backslash char, not a quote escape
+hook::env_s_split() {
+  local s="$1" i c n=${#1} word="" have=0
+  HOOK_ENV_S_WORDS=()
+  for ((i = 0; i < n; i++)); do
+    c="${s:i:1}"
+    case "$c" in
+    "'")
+      ((i++))
+      while ((i < n)) && [[ "${s:i:1}" != "'" ]]; do
+        word+="${s:i:1}"
+        ((i++))
+      done
+      have=1
+      ;;
+    '"')
+      ((i++))
+      while ((i < n)) && [[ "${s:i:1}" != '"' ]]; do
+        if [[ "${s:i:1}" == '\' ]] && ((i + 1 < n)); then
+          word+="${s:i+1:1}"
+          ((i += 2))
+          continue
+        fi
+        word+="${s:i:1}"
+        ((i++))
+      done
+      have=1
+      ;;
+    '\')
+      if ((i + 1 < n)); then
+        word+="${s:i+1:1}"
+        ((i++))
+      fi
+      have=1
+      ;;
+    ' ' | $'\t')
+      if ((have)); then
+        HOOK_ENV_S_WORDS+=("$word")
+        word=""
+        have=0
+      fi
+      ;;
+    *)
+      word+="$c"
+      have=1
+      ;;
+    esac
+  done
+  ((have)) && HOOK_ENV_S_WORDS+=("$word")
+}
+
+# Detect a `sh -c` style shell wrapper in a segment's argv: a shell at the
+# command position (after leading env-var assignments) carrying a `-c` flag.
+# On match, the command-string operand lands in HOOK_SHELL_C_OPERAND for the
+# caller to re-parse with hook::bash_parse_segments — the operand is a full
+# shell command (operators, quoting, everything), so re-parsing with the same
+# tokenizer is the faithful treatment. Wrappers stacked in front of the shell
+# (`sudo bash -c …`) are NOT resolved here — a documented residual of the
+# static-matcher posture. A shell invoked on a script file (no -c) never
+# matches: file contents cannot be inspected statically.
+#
+# `wsl` / `wsl.exe` at the command position is read the same way: it runs its
+# command line inside a Linux distribution, so that command line is the operand
+# (hook::wsl_operand).
+# shellcheck disable=SC2034  # result global is consumed by the sourcing guard
+hook::shell_c_operand() {
+  local -a w=("$@")
+  local n=${#w[@]} i=0 b t has_c=0
+  # Skip leading VAR=val assignments, mirroring the git resolver.
+  while ((i < n)) && [[ "${w[i]}" == *=* && "${w[i]}" != -* ]]; do ((i++)); done
+  ((i < n)) || return 1
+  b="${w[i]##*/}"
+  b="${b##*\\}"
+  # wsl.exe is reachable by that name from Git Bash and from inside a distro
+  # (interop, through a case-insensitive /mnt/c), so it is folded on every OS.
+  t="${b,,}"
+  if [[ "${t%.exe}" == wsl ]]; then
+    hook::wsl_operand "${w[@]:i+1}"
+    return
+  fi
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32)
+    b="${b,,}"
+    b="${b%.exe}"
+    ;;
+  *) ;;
+  esac
+  case "$b" in
+  bash | sh | zsh | dash | ksh | mksh) ;;
+  *) return 1 ;;
+  esac
+  ((i++))
+  while ((i < n)); do
+    t="${w[i]}"
+    case "$t" in
+    --)
+      ((i++))
+      break
+      ;;
+    # -o/-O (and +o/+O) consume a set/shopt operand; --rcfile/--init-file
+    # consume a startup-file operand (bash) — none of these ends the option
+    # scan, so `bash --rcfile /dev/null -c '…'` still reaches its -c.
+    -o | +o | -O | +O | --rcfile | --init-file) ((i += 2)) ;;
+    -*)
+      [[ "$t" =~ ^-[A-Za-z]+$ && "$t" == *c* ]] && has_c=1
+      ((i++))
+      ;;
+    *) break ;;
+    esac
+  done
+  ((has_c)) || return 1
+  ((i < n)) || return 1
+  HOOK_SHELL_C_OPERAND="${w[i]}"
+  return 0
+}
+
+# The command line a `wsl` / `wsl.exe` invocation runs, as one shell string in
+# HOOK_SHELL_C_OPERAND, from the words after the wsl word; returns 1 when wsl
+# runs no command line. Read the way microsoft/WSL src/windows/common/
+# WslClient.cpp reads its own Windows command line (option names from
+# src/windows/inc/wsl.h, usage text MessageWslUsage):
+#   - A leading distribution GUID, then a leading `~`, are stripped first.
+#   - `-d`/`--distribution`, `--distribution-id`, `-u`/`--user`, `--cd`,
+#     `--shell-type` and `--parent-console` take an operand; `--system` takes
+#     none. `--` ends the options. `-e`/`--exec` ends them too and runs the
+#     rest as argv, as does `--shell-type none`.
+#   - Any other word starting with `-` is a management verb (`--list`,
+#     `--install`, `--shutdown`, ...) or an option this build does not know.
+#     It is stepped over, not trusted to end the command, so a run option a
+#     later wsl adds cannot hide one; the words a management verb leaves are
+#     re-parsed as a command line, which can only over-read.
+#   - Otherwise the rest of the raw Windows command line goes to the distro
+#     shell as `$SHELL -c <line>`. Git Bash builds that line from argv with the
+#     MSVCRT quoting rules, so a word carrying whitespace or `"` (or an empty
+#     word) is rebuilt in double quotes and every other word is passed bare:
+#     `wsl echo x '>' f` redirects, `wsl 'git status && x'` is one command word.
+# In exec mode each word stays one argv word, so a word carrying a shell
+# metacharacter is single-quoted for the re-parse.
+# shellcheck disable=SC1003  # '\' compares a literal backslash char, not a quote escape
+# shellcheck disable=SC2034  # result global is consumed by the sourcing guard
+hook::wsl_operand() {
+  local -a w=("$@")
+  local n=${#w[@]} i=0 exec_mode=0 out="" wd enc bs nb k ch
+  local guid='^\{?[0-9A-Fa-f]{8}(-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}\}?$'
+  ((i < n)) && [[ "${w[i]}" =~ $guid ]] && ((++i))
+  ((i < n)) && [[ "${w[i]}" == "~" ]] && ((++i))
+  while ((i < n)); do
+    case "${w[i]}" in
+    --)
+      ((++i))
+      break
+      ;;
+    -e | --exec)
+      exec_mode=1
+      ((++i))
+      break
+      ;;
+    --shell-type)
+      [[ "${w[i + 1]-}" == none ]] && exec_mode=1
+      ((i += 2))
+      ;;
+    -d | --distribution | --distribution-id | -u | --user | --cd | --parent-console) ((i += 2)) ;;
+    -*) ((++i)) ;;
+    *) break ;;
+    esac
+  done
+  ((i < n)) || return 1
+  if ((exec_mode)); then
+    local safe='^[][A-Za-z0-9_./:=+,@%~*?^-]+$'
+    for wd in "${w[@]:i}"; do
+      if [[ "$wd" =~ $safe ]]; then
+        out+="$wd "
+      else
+        out+="'${wd//\'/\'\\\'\'}' "
+      fi
+    done
+  else
+    for wd in "${w[@]:i}"; do
+      if [[ -n "$wd" && "$wd" != *[[:space:]\"]* ]]; then
+        out+="$wd "
+        continue
+      fi
+      # MSVCRT: backslashes are literal unless they precede a `"`, where they
+      # are doubled and the quote escaped; a run before the closing quote is
+      # doubled too.
+      enc='"'
+      nb=0
+      for ((k = 0; k < ${#wd}; k++)); do
+        ch="${wd:k:1}"
+        if [[ "$ch" == '\' ]]; then
+          ((++nb))
+          continue
+        fi
+        if [[ "$ch" == '"' ]]; then
+          printf -v bs '%*s' "$((2 * nb + 1))" ''
+        else
+          printf -v bs '%*s' "$nb" ''
+        fi
+        enc+="${bs// /\\}$ch"
+        nb=0
+      done
+      printf -v bs '%*s' "$((2 * nb))" ''
+      out+="$enc${bs// /\\}\" "
+    done
+  fi
+  HOOK_SHELL_C_OPERAND="${out% }"
+  return 0
+}
+
+# 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::normalize_path_to) so `GIT` / `git.exe` are caught there but a
+# case-variant stays distinct on a case-sensitive POSIX filesystem.
+hook::git_is_bin() {
+  local b="${1##*/}"
+  b="${b##*\\}"
+  case "${OSTYPE:-}" in
+  msys* | cygwin* | win32)
+    local lc="${b,,}"
+    lc="${lc%.exe}"
+    [[ "$lc" == "git" ]]
+    ;;
+  *) [[ "$b" == "git" ]] ;;
+  esac
+}
+
+# Record the directory a WRAPPER changes to, into the slot belonging to the
+# wrapper occurrence currently being walked. A repeat within ONE wrapper is
+# last-wins rather than cumulative — GNU env keeps its --chdir operand in a
+# single slot, so `env -C a -C b` lands in `b` resolved against the cwd env was
+# invoked from, not in `a/b`. Nested wrappers each take their own slot, in
+# execution order, so the caller composes them left to right.
+# Call as: hook::wrapper_chdir_record <slot-index-var-name> <dir>
+hook::wrapper_chdir_record() {
+  # shellcheck disable=SC2178  # nameref to the caller's integer slot, not a string
+  local -n slot="$1"
+  local dir="$2"
+  [[ -n "$dir" ]] || return 0
+  if ((slot < 0)); then
+    HOOK_GIT_RESOLVED_WRAPPER_DIRS+=("$dir")
+    slot=$((${#HOOK_GIT_RESOLVED_WRAPPER_DIRS[@]} - 1))
+  else
+    HOOK_GIT_RESOLVED_WRAPPER_DIRS[slot]="$dir"
+  fi
+}
+
+# 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.
+#   HOOK_GIT_RESOLVED_GI    — index of git in HOOK_GIT_RESOLVED_WORDS
+#   HOOK_GIT_RESOLVED_WORDS — the (possibly rewritten) segment argv
+#   HOOK_GIT_RESOLVED_WRAPPER_DIRS — directories the wrappers chdir into before
+#                            git runs, in execution order (empty when none)
+# Leading `NAME=value` env-assignment prefixes and `env NAME=value` operands are walked
+# PAST to reach the git token, but their values are not collected: a `--config-env` alias
+# for the invoked subcommand is refused by SHAPE (hook::git_alias_expansion), so the
+# resolver never needs to know what an environment variable holds.
+#
+# A wrapper's chdir IS collected, because a caller that scopes its git-global
+# parsing to `[gi, sub_idx)` — as it must, since this parser is the only place
+# that knows which wrapper options take a value — would otherwise lose the
+# relocation entirely and inspect the wrong repository. This resolver is the
+# single place that can answer it: `env -C <dir>` really does move git, while the
+# `-C` in `env -u -C git` is the operand of `-u` and moves nothing.
+# shellcheck disable=SC1003  # '\' compares a literal backslash char, not a quote escape
+# shellcheck disable=SC2034  # result globals are consumed by the sourcing guard, not this file
+hook::git_resolve_index() {
+  HOOK_GIT_RESOLVED_WORDS=("$@")
+  HOOK_GIT_RESOLVED_GI=-1
+  HOOK_GIT_RESOLVED_WRAPPER_DIRS=()
+  # shellcheck disable=SC2178  # nameref to the array result global, not a string assignment
+  local -n w=HOOK_GIT_RESOLVED_WORDS
+  local n=${#w[@]} i=0 tok
+
+  while ((i < n)); do
+    tok="${w[i]}"
+    if [[ "$tok" == *=* ]]; then
+      # A leading NAME=value token is a command-line env-assignment prefix; skip it to
+      # reach the git token (the shell treats only a valid-name assignment as such, but
+      # skipping any `*=*` word here is harmless — a non-assignment command word never
+      # contains an unquoted `=` at argv position 0 in a real invocation).
+      ((i++))
+      continue
+    fi
+
+    case "${tok##*/}" in
+    env)
+      # env [OPTION]... [--] [NAME=VALUE]... [COMMAND ...]: options first, then
+      # operand assignments, then the command. `--` ends option parsing (so a
+      # following leading-dash operand like `-AV=…` is an assignment, not an
+      # option). Unlike a shell prefix, env sets any name — collect every operand
+      # assignment regardless of name shape so a hyphenated/leading-dash name git
+      # reads via --config-env is captured, not dropped.
+      ((i++))
+      local env_past_optmark=0 env_ci=-1 etok
+      while ((i < n)); do
+        if ((env_past_optmark == 0)) && [[ "${w[i]}" == -* ]]; then
+          # GNU env clusters short options, so `-vC dir` carries a chdir that no
+          # exact `-C` match sees. Peel the valueless shorts (-i/-0/-v, per
+          # `env --help`) off a single-dash token so the value-taking tail
+          # (-u/-C/-S) reaches its own branch; peel into a scratch copy, leaving
+          # HOOK_GIT_RESOLVED_WORDS as the caller matches on it.
+          etok="${w[i]}"
+          if [[ "$etok" == -[!-]* ]]; then
+            while [[ "$etok" =~ ^-[i0v](.+)$ ]]; do etok="-${BASH_REMATCH[1]}"; done
+          fi
+          case "$etok" in
+          --)
+            ((i++))
+            env_past_optmark=1
+            ;;
+          # -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 resume. The splice drops every word before `i`, this `env`
+          # included, so a chdir already recorded for it is not re-walked and
+          # stays recorded — which is right, because env performs that chdir
+          # whether or not -S rewrites the command.
+          #
+          # Resume INSIDE env's own option loop (`continue`, not `continue 2`),
+          # because the split words are env's OWN arguments: `-S` exists so a
+          # shebang line can carry env options, and GNU documents exactly that
+          # (`#!/usr/bin/env -S -i some-program`). Restarting at the command
+          # dispatcher instead would read a leading option in the split string
+          # as the COMMAND NAME and abandon the whole segment — `env -S '-C
+          # <dir> git push --force'` would resolve to no git at all, so every
+          # guard would skip a real force-push, and `env -S '-C <sha256-repo>
+          # git push --force-with-lease=main:<40-hex>'` would skip a lease
+          # against a movable ref name. Staying in this loop also keeps
+          # `env_ci` in scope, so
+          # `env -C a -S '-C b git …'` is last-wins in the one slot GNU env
+          # keeps, exactly as an unspliced `env -C a -C b` already is.
+          #
+          # Termination: each splice consumes the `-S` word and its operand and
+          # substitutes only the operand's own words, so the argv's byte count
+          # strictly decreases — a self-referential `env -S '-S -S'` runs out
+          # rather than looping.
+          -S | --split-string)
+            local sval=""
+            ((i + 1 < n)) && sval="${w[i + 1]}"
+            hook::env_s_split "$sval"
+            w=(${HOOK_ENV_S_WORDS[@]+"${HOOK_ENV_S_WORDS[@]}"} "${w[@]:i+2}")
+            n=${#w[@]}
+            i=0
+            continue
+            ;;
+          -S* | --split-string=*)
+            local sval="${etok#-S}"
+            sval="${sval#--split-string=}"
+            hook::env_s_split "$sval"
+            w=(${HOOK_ENV_S_WORDS[@]+"${HOOK_ENV_S_WORDS[@]}"} "${w[@]:i+1}")
+            n=${#w[@]}
+            i=0
+            continue
+            ;;
+          -C | --chdir)
+            ((i + 1 < n)) && hook::wrapper_chdir_record env_ci "${w[i + 1]}"
+            ((i += 2))
+            ;;
+          --chdir=*)
+            hook::wrapper_chdir_record env_ci "${etok#--chdir=}"
+            ((i++))
+            ;;
+          -C*)
+            hook::wrapper_chdir_record env_ci "${etok#-C}"
+            ((i++))
+            ;;
+          -u | --unset) ((i += 2)) ;;
+          -*) ((i++)) ;;
+          *) ((i++)) ;;
+          esac
+        elif [[ "${w[i]}" == *=* ]]; then
+          # An `env NAME=value` operand — skip it to reach the command (git). Its value
+          # is never read: a --config-env alias is refused by shape, not resolved.
+          # The operand also ENDS option parsing, as env's own grammar does
+          # (`env FOO=1 -C dir git …` makes env look for a command named `-C`, not
+          # chdir), so a later dash word is the command or its argument. Reading one
+          # as an option recorded a chdir env never performs.
+          env_past_optmark=1
+          ((i++))
+        else
+          break
+        fi
+      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)
+      # sudo's own chdir is -D/--chdir (its -C is close-from, -R is --chroot).
+      # GNU sudo clusters short options, so `-bD dir` carries a chdir that no
+      # exact `-D` match sees. Peel the documented valueless shorts (-A/-B/-b/-e/-E
+      # -H/-K/-k/-l/-n/-P/-s/-S/-v/-V, per `sudo --help`) off a single-dash token
+      # so the value-taking tail (-D/--chdir, -u/-g/-h/-p/-C/-R/-T) reaches its own
+      # branch. `-h` is value-taking (`-h host` / `--host=`) and must not be peeled.
+      # `-i` relocates to the target user's home without naming a directory at all.
+      ((i++))
+      local sudo_ci=-1 stok
+      while ((i < n)) && [[ "${w[i]}" == -* ]]; do
+        stok="${w[i]}"
+        if [[ "$stok" == -[!-]* ]]; then
+          while [[ "$stok" =~ ^-[ABbeEHKklnPsSvV](.+)$ ]]; do stok="-${BASH_REMATCH[1]}"; done
+        fi
+        case "$stok" in
+        -D | --chdir)
+          ((i + 1 < n)) && hook::wrapper_chdir_record sudo_ci "${w[i + 1]}"
+          ((i += 2))
+          ;;
+        --chdir=*)
+          hook::wrapper_chdir_record sudo_ci "${stok#--chdir=}"
+          ((i++))
+          ;;
+        -D*)
+          hook::wrapper_chdir_record sudo_ci "${stok#-D}"
+          ((i++))
+          ;;
+        -u | -g | -h | -p | -C | -R | -T | --user | --group) ((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 carry their own options before the real command
+    # (`command [-pVv]`, `exec [-cl] [-a name]`) and an optional `--`
+    # end-of-options marker (`command -- git …`) — skip them so the git
+    # command behind the wrapper is still resolved. But `command -v`/`-V`
+    # only PRINT the command's path/description — nothing runs — so a git
+    # word behind them is a probe, not an invocation: bail out.
+    command | exec | builtin | eval | !)
+      local is_command=0
+      [[ "${tok##*/}" == "command" ]] && is_command=1
+      ((i++))
+      while ((i < n)) && [[ "${w[i]}" == -* && "${w[i]}" != "--" ]]; do
+        if ((is_command)) && [[ "${w[i]}" == -*[vV]* ]]; then
+          return 1
+        fi
+        [[ "${w[i]}" == "-a" ]] && ((i++))
+        ((i++))
+      done
+      ((i < n)) && [[ "${w[i]}" == "--" ]] && ((i++))
+      continue
+      ;;
+    time)
+      ((i++))
+      if ((i < n)) && [[ "${w[i]}" == "-p" ]]; then
+        ((i++))
+      fi
+      continue
+      ;;
+    # Compound-command reserved words at the execution position: a command
+    # can directly follow any of these within one segment (`if git …`,
+    # `then git …`, `do git …`), so skip them and keep resolving.
+    if | then | elif | else | while | until | for | do | case | select | coproc | '{' | '}')
+      ((i++))
+      continue
+      ;;
+    *)
+      if hook::git_is_bin "$tok"; then
+        HOOK_GIT_RESOLVED_GI=$i
+        return 0
+      fi
+      return 1
+      ;;
+    esac
+  done
+  return 1
+}
+
+# Resolve the git subcommand in an already-resolved segment: 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. Results in
+# globals:
+#   HOOK_GIT_SUB           — the subcommand word ("" when none found)
+#   HOOK_GIT_SUB_IDX       — its index in the argv (-1 when none)
+#   HOOK_GIT_CONFIG_VALUES — values of -c/--config/--config-env options, in
+#                            order, so a guard can inspect config assignments
+#                            without re-walking (commit messages and pathspecs
+#                            are never collected here)
+#   HOOK_GIT_CONFIG_VALUE_KINDS — parallel to HOOK_GIT_CONFIG_VALUES (1:1 by
+#                            index): "inline" for a -c/--config value (the literal
+#                            assignment) or "env" for a --config-env value (whose
+#                            operand is `<key>=<envvar>`, an environment-variable
+#                            NAME, not the value). An env-kind alias for the invoked
+#                            subcommand is REFUSED by shape (hook::git_alias_expansion),
+#                            never resolved — the value is deliberately never read.
+# Call as: hook::git_resolve_subcommand <git-index> <argv words...>
+# shellcheck disable=SC2034  # result globals are consumed by the sourcing guard, not this file
+hook::git_resolve_subcommand() {
+  local gi="$1"
+  shift
+  local -a w=("$@")
+  local nseg=${#w[@]} j gw
+  HOOK_GIT_SUB=""
+  HOOK_GIT_SUB_IDX=-1
+  HOOK_GIT_CONFIG_VALUES=()
+  HOOK_GIT_CONFIG_VALUE_KINDS=()
+
+  j=$((gi + 1))
+  while ((j < nseg)); do
+    gw="${w[j]}"
+    case "$gw" in
+    -c | --config)
+      ((j + 1 < nseg)) && {
+        HOOK_GIT_CONFIG_VALUES+=("${w[j + 1]}")
+        HOOK_GIT_CONFIG_VALUE_KINDS+=("inline")
+      }
+      ((j += 2))
+      ;;
+    --config-env)
+      ((j + 1 < nseg)) && {
+        HOOK_GIT_CONFIG_VALUES+=("${w[j + 1]}")
+        HOOK_GIT_CONFIG_VALUE_KINDS+=("env")
+      }
+      ((j += 2))
+      ;;
+    --config=*)
+      HOOK_GIT_CONFIG_VALUES+=("${gw#*=}")
+      HOOK_GIT_CONFIG_VALUE_KINDS+=("inline")
+      ((j++))
+      ;;
+    --config-env=*)
+      HOOK_GIT_CONFIG_VALUES+=("${gw#*=}")
+      HOOK_GIT_CONFIG_VALUE_KINDS+=("env")
+      ((j++))
+      ;;
+    -C | --git-dir | --work-tree | --namespace | --super-prefix | --attr-source | --exec-path)
+      ((j += 2))
+      ;;
+    -*)
+      ((j++))
+      ;;
+    *)
+      HOOK_GIT_SUB="$gw"
+      HOOK_GIT_SUB_IDX=$j
+      return 0
+      ;;
+    esac
+  done
+  return 1
+}
+
+# Classify how a guard should treat the alias for the invoked subcommand, from the
+# config values collected by hook::git_resolve_subcommand. git reads TWO spellings as the
+# alias for a subcommand — `alias.<sub>` and its `alias.<sub>.command` subkey (the only
+# alias subkey git reads) — and which spelling wins when both are set is git-version-
+# dependent. Rather than model that precedence (and risk a benign value in one spelling
+# masking a dangerous value in the other on a git that resolves it the opposite way), this
+# classifier fails closed on the MAX-DANGER UNION of the two spellings: the LAST value
+# WITHIN each spelling decides that spelling (git applies the last value for a given key),
+# then the spellings combine so the guard blocks if EITHER could carry a guarded op.
+#
+#   - "env" (--config-env=<key>=<envvar>) in EITHER spelling: the expansion lives in an
+#     environment variable whose VALUE is deliberately never read — that value is the
+#     recurring attack surface (an ambient var, an inline/`env` prefix, an `export`,
+#     `set -a`, or a nested `bash -c`, in this or any enclosing wrapper), and each attempt
+#     to resolve it has reopened a fail-open. Nobody legitimately defines an alias for a
+#     guarded subcommand via --config-env on the invoking command line (the canonical form
+#     is a gitconfig alias or the plain subcommand), so the SHAPE alone is sufficient.
+#     Returns 2 — the guard blocks without reading anything.
+#   - "inline" (-c/--config), no env spelling: each present spelling's expansion is
+#     literally present and bounded. Returns 0 with HOOK_GIT_ALIAS_EXPS holding one entry
+#     per present spelling (1 or 2), so the guard re-checks every expansion and blocks if
+#     any is dangerous — a benign expansion never suppresses a dangerous sibling.
+#   - neither spelling present: returns 1, the subcommand is not an inline/env alias here.
+#
+# A --config-env that sets a NON-alias key, or an alias for a subcommand OTHER than the
+# invoked one, never matches — those stay resolvable/allowed. Call after
+# hook::git_resolve_subcommand; read HOOK_GIT_ALIAS_EXPS only on return 0.
+# shellcheck disable=SC2034  # HOOK_GIT_ALIAS_EXPS is consumed by the sourcing guard
+hook::git_alias_expansion() {
+  local sub="$1" i cv key kind
+  local plain_exp="" plain_kind="" cmd_exp="" cmd_kind=""
+  HOOK_GIT_ALIAS_EXPS=()
+  # git config names are case-insensitive: fold both sides of the exact key match. Keep
+  # the LAST value WITHIN each spelling separately, never collapsed across the two, so one
+  # spelling's value cannot mask the other's.
+  for i in "${!HOOK_GIT_CONFIG_VALUES[@]}"; do
+    cv="${HOOK_GIT_CONFIG_VALUES[i]}"
+    key="${cv%%=*}"
+    kind="${HOOK_GIT_CONFIG_VALUE_KINDS[i]:-inline}"
+    if [[ "${key,,}" == "alias.${sub,,}" ]]; then
+      plain_exp="${cv#*=}"
+      plain_kind="$kind"
+    elif [[ "${key,,}" == "alias.${sub,,}.command" ]]; then
+      cmd_exp="${cv#*=}"
+      cmd_kind="$kind"
+    fi
+  done
+  # Max-danger union: an env spelling in either place is unreadable — value-blind refusal.
+  [[ "$plain_kind" == "env" || "$cmd_kind" == "env" ]] && return 2
+  [[ -n "$plain_kind" ]] && HOOK_GIT_ALIAS_EXPS+=("$plain_exp")
+  [[ -n "$cmd_kind" ]] && HOOK_GIT_ALIAS_EXPS+=("$cmd_exp")
+  ((${#HOOK_GIT_ALIAS_EXPS[@]})) && return 0
+  return 1
+}
+
+# THE parsed git invocation for one segment. The three functions above are the
+# steps; this is the seam a guard calls. Every git guard needs the same answers
+# about a segment — where git is, what the argv looks like after `env -S`
+# splicing, where the wrappers moved it, which subcommand runs, which config
+# assignments ride along, and whether the subcommand is an inline alias — so
+# they are answered once, in one shape, rather than reassembled per guard.
+#
+# Call as: hook::git_invocation <argv words...> — one segment's argv, as
+# hook::bash_parse_segments hands it to a callback. A `sh -c` wrapper is
+# deliberately NOT unwrapped here: its operand is a whole shell command
+# (operators, quoting, everything), so the caller detects it with
+# hook::shell_c_operand and re-parses the operand through its OWN segment
+# callback, which is the only faithful treatment.
+#
+# Returns 0 with the result below, 1 when no git executable sits at the
+# segment's command position, and 2 when git resolves but names no subcommand
+# (`git --version`, globals only). Every result variable is reset on entry, so a
+# non-zero return can never leave a previous segment's answer standing.
+#
+#   HOOK_GITINV_GI            — index of the git word in HOOK_GITINV_WORDS
+#   HOOK_GITINV_WORDS         — the segment argv AFTER `env -S` splicing; match
+#                               on these, never on the words passed in
+#   HOOK_GITINV_WRAPPER_DIRS  — directories the wrappers chdir into before git
+#                               runs, in execution order (empty when none).
+#                               A caller scoping its git-global parsing to
+#                               [gi, sub_idx) cannot see these and must replay
+#                               them ahead of git's own globals
+#   HOOK_GITINV_SUB           — the subcommand word
+#   HOOK_GITINV_SUB_IDX       — its index in HOOK_GITINV_WORDS
+#   HOOK_GITINV_CONFIG_VALUES — -c/--config/--config-env values, in order
+#   HOOK_GITINV_CONFIG_KINDS  — 1:1 with the values: "inline" (the literal
+#                               assignment) or "env" (a `<key>=<envvar>` operand
+#                               naming a variable whose value is never read)
+#   HOOK_GITINV_ALIAS_EXPS    — the invoked subcommand's inline alias
+#                               expansions, one per present spelling
+#                               (`alias.<sub>` then `alias.<sub>.command`)
+#   HOOK_GITINV_ALIAS_TERM    — why the alias chain stops at this hop:
+#                               "none"       — the subcommand is no inline alias
+#                               "inline"     — HOOK_GITINV_ALIAS_EXPS holds every
+#                                              present spelling's expansion, and
+#                                              a guard must re-check each one so
+#                                              a benign spelling cannot suppress
+#                                              a dangerous sibling
+#                               "config-env" — the alias is defined via
+#                                              --config-env, so its expansion is
+#                                              an environment variable's value
+#                                              this parser deliberately never
+#                                              reads; guards refuse by shape
+#
+# The chain BEYOND this hop stays with the caller: git re-expands an expansion
+# whose first word is another alias, and each guard runs its own predicate at
+# every hop, resolves persisted aliases (or does not) on its own terms, and
+# bounds its own recursion. So a guard splices the expansion and re-enters its
+# segment callback, which calls back into this function for the next hop.
+# shellcheck disable=SC2034  # result globals are consumed by the sourcing guard, not this file
+hook::git_invocation() {
+  HOOK_GITINV_GI=-1
+  HOOK_GITINV_WORDS=()
+  HOOK_GITINV_WRAPPER_DIRS=()
+  HOOK_GITINV_SUB=""
+  HOOK_GITINV_SUB_IDX=-1
+  HOOK_GITINV_CONFIG_VALUES=()
+  HOOK_GITINV_CONFIG_KINDS=()
+  HOOK_GITINV_ALIAS_EXPS=()
+  HOOK_GITINV_ALIAS_TERM="none"
+
+  hook::git_resolve_index "$@" || return 1
+  HOOK_GITINV_GI=$HOOK_GIT_RESOLVED_GI
+  HOOK_GITINV_WORDS=(${HOOK_GIT_RESOLVED_WORDS[@]+"${HOOK_GIT_RESOLVED_WORDS[@]}"})
+  HOOK_GITINV_WRAPPER_DIRS=(${HOOK_GIT_RESOLVED_WRAPPER_DIRS[@]+"${HOOK_GIT_RESOLVED_WRAPPER_DIRS[@]}"})
+
+  hook::git_resolve_subcommand "$HOOK_GITINV_GI" "${HOOK_GITINV_WORDS[@]}" || return 2
+  HOOK_GITINV_SUB="$HOOK_GIT_SUB"
+  HOOK_GITINV_SUB_IDX=$HOOK_GIT_SUB_IDX
+  HOOK_GITINV_CONFIG_VALUES=(${HOOK_GIT_CONFIG_VALUES[@]+"${HOOK_GIT_CONFIG_VALUES[@]}"})
+  HOOK_GITINV_CONFIG_KINDS=(${HOOK_GIT_CONFIG_VALUE_KINDS[@]+"${HOOK_GIT_CONFIG_VALUE_KINDS[@]}"})
+
+  hook::git_alias_expansion "$HOOK_GITINV_SUB"
+  case $? in
+  0)
+    HOOK_GITINV_ALIAS_TERM="inline"
+    HOOK_GITINV_ALIAS_EXPS=(${HOOK_GIT_ALIAS_EXPS[@]+"${HOOK_GIT_ALIAS_EXPS[@]}"})
+    ;;
+  2) HOOK_GITINV_ALIAS_TERM="config-env" ;;
+  *) ;;
+  esac
+  return 0
+}
+
+# Would git IGNORE a config alias named for this subcommand? git-config
+# (https://git-scm.com/docs/git-config, fetched 2026-09-06): "aliases that hide
+# existing Git commands are ignored except for deprecated commands." A current
+# non-deprecated builtin therefore cannot expand to anything, so a guard that
+# probes `alias.<builtin>` spends a fork per call and can false-block on a
+# leftover ignored alias. Asking the installed git for its builtin list would
+# put that spawn right back on every `git status`.
+#
+# This is a static subset of names that were already builtins in git 2.25, minus
+# the names git marks DEPRECATED (`git --list-cmds=deprecated`; git.c
+# `DEPRECATED` bit, master fetched 2026-09-06: `whatchanged` and
+# `pack-redundant`). Names added later (`bugreport` 2.27, `maintenance` 2.31,
+# `diagnose` 2.38) stay probed, so an older git that still honors
+# `alias.bugreport = commit` cannot slip through. git 2.51+ honors
+# `alias.whatchanged = commit` (t/t0014-alias.sh). A name not listed here is
+# still probed: skipping a non-builtin would miss a real alias.
+# Recheck when the git-config page stops saying aliases that hide builtins are
+# ignored, or git.c marks another command DEPRECATED.
+hook::git_subcommand_ignores_alias() {
+  case "$1" in
+  add | am | annotate | apply | archive | bisect | blame | branch | bundle | \
+    cat-file | check-attr | check-ignore | check-mailmap | check-ref-format | checkout | \
+    checkout-index | cherry | cherry-pick | clean | clone | column | commit | commit-graph | \
+    commit-tree | config | describe | diff | diff-files | diff-index | diff-tree | \
+    difftool | fetch | for-each-ref | format-patch | fsck | gc | grep | hash-object | help | \
+    init | interpret-trailers | log | ls-files | ls-remote | ls-tree | merge | \
+    merge-base | mv | notes | pull | push | range-diff | rebase | reflog | remote | repack | \
+    replace | reset | restore | rev-list | rev-parse | revert | rm | shortlog | show | \
+    show-ref | sparse-checkout | stash | status | switch | symbolic-ref | tag | \
+    update-ref | version | worktree)
+    return 0
+    ;;
+  *) return 1 ;;
+  esac
+}
+
+# The directory a segment's git actually runs in: the base with every `-C` in an
+# already-collected option set composed onto it, left to right — an absolute
+# value replaces, a relative one joins. git applies several `-C` values
+# cumulatively, and a wrapper's chdir happens before git starts, so a caller
+# spells the wrapper dirs (HOOK_GITINV_WRAPPER_DIRS) as LEADING `-C` words and
+# this one composition rule covers both.
+#
+# CALLERS MUST PASS GIT'S OWN GLOBALS ONLY — the slice from the resolved git
+# token (`gi`) up to the subcommand, never from index 0, and never the whole
+# argv:
+#   * Anything before `gi` belongs to a wrapper, and this composition cannot
+#     know which wrapper options take a value. In `env -u -C git …`, GNU env's
+#     `-u NAME` consumes `-C` as the variable to unset and `git` as the command,
+#     so git never moves — while a 0-based slice reads the bare tokens `-C git`
+#     and resolves into `./git`. The hook then reads one repository while git
+#     runs in another, which is a bypass, not a cosmetic mismatch.
+#   * Words after the subcommand are that subcommand's own arguments — or, for
+#     an alias, text git APPENDS to the expansion. Reading a trailing `-C` as a
+#     repository global sent `git -c alias.a='!git b #' a -C <other>` to
+#     <other> while git ran the body in the current repository, and would read
+#     `git commit -C HEAD` (--reuse-message) as a directory named HEAD.
+# The slice is always non-empty: hook::git_resolve_subcommand starts its scan at
+# `gi + 1`, so `sub_idx > gi` holds for every argv that reaches a call site.
+#
+# The composed value is a LITERAL path, never `realpath`/`cd -P`: resolving
+# symlinks is a bypass in both directions (lexical `x/..` is wrong under a POSIX
+# symlink; physical resolution is wrong on Win32, where git itself is lexical).
+# Handing the composed spelling to `git -C` lets git apply its own path
+# semantics. It is a DIRECTORY, not a repository identity — a caller that needs
+# an identity (a cycle key) must canonicalize it itself.
+#
+# hook::git_effective_dir_to <var> <locating-option...> assigns into the variable
+# named by $1 rather than printing. The body is builtins only, so capturing a
+# print form in `$( )` would spend a fork on nothing but carrying a string out of
+# a subshell, and this path runs on every blocked commit. The default base is
+# read into a local before the nameref is written, so a caller may name
+# HOOK_EFFECTIVE_BASE itself as the destination.
+hook::git_effective_dir_to() {
+  # shellcheck disable=SC2178  # nameref to the caller's string variable
+  local -n _ed_out="$1"
+  shift
+  local base="${HOOK_EFFECTIVE_BASE:-${HOOK_CWD:-${CLAUDE_PROJECT_DIR:-.}}}" i n=$# arg
+  local -a a=("$@")
+  for ((i = 0; i < n; i++)); do
+    arg="${a[i]}"
+    if [[ "$arg" == "-C" ]] && ((i + 1 < n)); then
+      if [[ "${a[i + 1]}" == /* || "${a[i + 1]}" =~ ^[A-Za-z]:[\/] ]]; then
+        base="${a[i + 1]}"
+      else
+        base="$base/${a[i + 1]}"
+      fi
+      ((i++))
+    fi
+  done
+  _ed_out="$base"
+}
+
+# The command string a `!` shell alias runs: git executes the body as a shell
+# command with the invocation's trailing arguments appended positionally, so
+# strip the leading `!` and append each trailing argument shell-quoted — the
+# reparse then tokenizes them back into the same words.
+#
+# Call as: hook::git_alias_reparse_to <var> <expansion> <trailing arg...>.
+# `printf -v`, never `$(printf '%q' …)`: the substitution form is a fork per
+# trailing argument (Command Substitution, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution) on every `!` alias hop.
+hook::git_alias_reparse_to() {
+  # shellcheck disable=SC2178  # nameref to the caller's string variable
+  local -n _gar_out="$1"
+  local body="${2#!}" a q
+  shift 2
+  for a in "$@"; do
+    printf -v q '%q' "$a"
+    body+=" $q"
+  done
+  _gar_out="$body"
+}
+
+# Admit one alias re-expansion, or report that it is already decided or over
+# budget. Alias re-expansion BRANCHES: every hop re-checks both alias spellings
+# independently, so a chain where each hop defines both walks 2^depth analysis
+# paths, and a guard that stalls stops guarding.
+#
+# MEMO — a verdict is a pure function of (analysis state, effective base, argv);
+# every other input is invocation-constant. A block is a process-wide `exit 2`,
+# so a state reached a SECOND time while the process still runs provably did not
+# block the first time and cannot decide differently now. Skipping the repeat is
+# exact rather than a coverage trade, and it collapses the common blowup — both
+# spellings of a hop expanding to the same thing — to one path per hop.
+#
+# The key carries, and needs, each of these:
+#   * <kind> — a `!` reparse STRING must never key the same as a one-word argv.
+#   * the effective base — one reparse string reached in two repositories is TWO
+#     analyses (they can disagree on hash width, so collapsing them lets a
+#     movable ref name through the second).
+#   * both seen-sets, each length-prefixed ahead of its own words — they ARE the
+#     analysis state: HOOK_ALIAS_SEEN models git's in-process alias-loop guard,
+#     HOOK_SHELL_ALIAS_SEEN bounds persisted `!` alias hops. A guard that keeps
+#     only one leaves the other empty, which contributes a constant to the key;
+#     keying both here keeps the key shape uniform across guards.
+#   * `%q` on every word, so a word containing a newline cannot merge into its
+#     neighbor and no boundary in the key can shift.
+# `printf -v` keeps the whole key build fork-free — a `$(printf …)` per word
+# would cost more than the walk it bounds.
+#
+# BUDGET — memoization alone cannot bound a chain whose two spellings DIFFER:
+# the splice carries each path's own trailing text forward, so every argv is
+# distinct and the 2^depth walk survives. HOOK_ALIAS_WORK_MAX caps total
+# analyses for the invocation; the caller decides what exhausting it means, and
+# every caller today fails CLOSED (it could not finish deciding, so it must not
+# allow). The ceiling counts ANALYSES rather than seconds because a wall clock
+# is host- and command-length-dependent; a caller sets its own by assigning
+# HOOK_ALIAS_WORK_MAX before the first call.
+#
+# Call as: hook::git_alias_admit <kind> <state-word>... — returns 0 to analyze,
+# 1 when this exact state was already analyzed, 2 when the budget is exhausted.
+# shellcheck disable=SC2154  # HOOK_ALIAS_SEEN / HOOK_SHELL_ALIAS_SEEN are the caller's analysis state, read unset-safely below
+hook::git_alias_admit() {
+  local kind="$1" key q w
+  shift
+  # First call in this process arms the memo and the counter. `declare -gA` is
+  # what makes the string key a hash lookup instead of arithmetic on an indexed
+  # array, so it must happen before any write.
+  if [[ -z "${HOOK_ALIAS_ADMIT_ARMED:-}" ]]; then
+    declare -gA HOOK_ALIAS_MEMO=()
+    HOOK_ALIAS_WORK=0
+    HOOK_ALIAS_ADMIT_ARMED=1
+  fi
+  # Copied through the unset-safe idiom rather than read in place: a guard that
+  # keeps only one of the two seen-sets never declares the other, and `set -u`
+  # would abort on its length.
+  local -a _gaa_seen=(${HOOK_ALIAS_SEEN[@]+"${HOOK_ALIAS_SEEN[@]}"})
+  local -a _gaa_shell_seen=(${HOOK_SHELL_ALIAS_SEEN[@]+"${HOOK_SHELL_ALIAS_SEEN[@]}"})
+  printf -v q '%q' "${HOOK_EFFECTIVE_BASE-}"
+  key="$kind"$'\n'"$q"$'\n'"${#_gaa_seen[@]}"$'\n'"${#_gaa_shell_seen[@]}"$'\n'
+  for w in ${_gaa_seen[@]+"${_gaa_seen[@]}"} ${_gaa_shell_seen[@]+"${_gaa_shell_seen[@]}"} "$@"; do
+    printf -v q '%q' "$w"
+    key+="$q"$'\n'
+  done
+  [[ -n "${HOOK_ALIAS_MEMO[$key]+x}" ]] && return 1
+  HOOK_ALIAS_MEMO["$key"]=1
+  ((++HOOK_ALIAS_WORK <= ${HOOK_ALIAS_WORK_MAX:-128})) && return 0
+  return 2
+}
+
+# hook::reset_analysis_state: forget the per-invocation analysis state, so the
+# next hook to run in this process starts as a fresh hook process would. That
+# state is the alias memo and budget above (armed on first use, and a memo hit
+# means "already analyzed: skip"), the two seen-sets, and the effective base
+# the alias walk carries. A hook run alone never needs this; a dispatcher that
+# sources several hooks into one shell (guardrails run-guards.sh) calls it
+# before each, because otherwise the second hook to walk the same alias chain
+# is answered by the first hook's memo and skips the analysis it owes. The
+# keyed caches (physical paths, the JSON skeleton) are not analysis state:
+# they answer the same question the same way for every hook, and stay.
+hook::reset_analysis_state() {
+  unset HOOK_ALIAS_ADMIT_ARMED HOOK_ALIAS_MEMO HOOK_ALIAS_WORK
+  unset HOOK_ALIAS_SEEN HOOK_SHELL_ALIAS_SEEN HOOK_EFFECTIVE_BASE
+}
+
+# Mark the redirection still waiting for an operand as OPAQUE: the operator is
+# real, the path it names never arrived. The four places that discover an
+# orphaned operand (a second operator, a here-doc opener, a process
+# substitution, the end of a segment) share this one spelling. Reads and writes
+# hook::bash_parse_segments_uncached's own locals through dynamic scope, so it
+# is not callable on its own.
+# shellcheck disable=SC2154  # `pend` is a local of hook::bash_parse_segments_uncached
+hook::_bps_orphan_pending() {
+  ((pend)) || return 0
+  HOOK_SEG_REDIR_OPAQUE[${#HOOK_SEG_REDIR_OP[@]} - 1]=1
+  pend=0
+}
+
+# Close the word being assembled into the segment: as an argv word, or as the
+# target of the redirection still waiting for its operand. Called from the four
+# places a word can end (blank, redirection operator, control operator, end of
+# input); single-sourced so those four cannot drift apart on the quoting
+# provenance they record. Reads and writes hook::bash_parse_segments_uncached's
+# own locals through dynamic scope, so it is not callable on its own.
+# shellcheck disable=SC2154  # every unassigned name here is a local of hook::bash_parse_segments_uncached
+hook::_bps_close_word() {
+  local _bps_q=0 _bps_last
+  if ((wq_quoted || wq_esc)); then
+    if ((wq_quoted && !wq_plain && !wq_esc)); then _bps_q=2; else _bps_q=1; fi
+  fi
+  if ((pend)); then
+    _bps_last=$((${#HOOK_SEG_REDIR_OP[@]} - 1))
+    HOOK_SEG_REDIR_TARGET[_bps_last]="$word"
+    ((_bps_q)) && HOOK_SEG_REDIR_QUOTED[_bps_last]=1
+    ((wq_open)) && HOOK_SEG_REDIR_OPAQUE[_bps_last]=1
+    pend=0
+  else
+    seg+=("$word")
+    HOOK_SEG_WORD_QUOTED+=("$_bps_q")
+  fi
+  word=""
+  have=0
+  wq_quoted=0
+  wq_plain=0
+  wq_esc=0
+  wq_open=0
+}
+
+# Hand the finished segment to the callback and start the next one. A pending
+# operand that never arrived leaves its redirection OPAQUE: the operator is
+# real, the path it names is not recoverable from this command string.
+# Dynamic scope, like hook::_bps_close_word.
+# shellcheck disable=SC2154  # every unassigned name here is a local of hook::bash_parse_segments_uncached
+hook::_bps_flush_segment() {
+  hook::_bps_orphan_pending
+  if ((${#seg[@]})); then
+    "$cb" "${seg[@]}"
+    seg=()
+    HOOK_SEG_WORD_QUOTED=()
+  fi
+  HOOK_SEG_REDIR_OP=()
+  HOOK_SEG_REDIR_FD=()
+  HOOK_SEG_REDIR_TARGET=()
+  HOOK_SEG_REDIR_QUOTED=()
+  HOOK_SEG_REDIR_OPAQUE=()
+}
+
+# hook::_bps_chars <cmd>: fill hook::bash_parse_segments_uncached's `chars`
+# with the bytes of <cmd>, one per element, in time linear in its length.
+#
+# `${s:i:1}` is not O(1): bash measures the whole of `s` on every expansion
+# (a multibyte scan under a UTF-8 locale, a byte scan under C), so one call per
+# character is quadratic. Measured (#4528): 1.2 s for a 10,000-character
+# command under en_US.UTF-8 and 4.9 s for 20,000, which put a ~70 KB command
+# past the Bash row's 60-second hook timeout. Each slice here is taken from a
+# string of at most 4096, then 64, bytes, so no expansion measures more than
+# that. Bytes rather than characters, under C: every character the tokenizer
+# compares against is ASCII, and no byte of a UTF-8 multibyte sequence is, so
+# a word reassembled from bytes is the word the characters spelled.
+# Dynamic scope, like hook::_bps_close_word.
+hook::_bps_chars() {
+  [[ "${LC_ALL-}" == C ]] || {
+    hook::_c_locale hook::_bps_chars "$@"
+    return
+  }
+  local __hu_s="$1" __hu_n=${#1} __hu_o1 __hu_o2 __hu_j __hu_big __hu_bn __hu_blk __hu_bl
+  chars=()
+  for ((__hu_o1 = 0; __hu_o1 < __hu_n; __hu_o1 += 4096)); do
+    __hu_big=${__hu_s:__hu_o1:4096}
+    __hu_bn=${#__hu_big}
+    for ((__hu_o2 = 0; __hu_o2 < __hu_bn; __hu_o2 += 64)); do
+      __hu_blk=${__hu_big:__hu_o2:64}
+      __hu_bl=${#__hu_blk}
+      for ((__hu_j = 0; __hu_j < __hu_bl; __hu_j++)); do
+        chars+=("${__hu_blk:__hu_j:1}")
+      done
+    done
+  done
+}
+
+# hook::bash_parse_segments is the name every hook calls, and
+# hook::bash_parse_segments_uncached the same parse under the name a dispatcher
+# that shares one parse across the hooks of an event (guardrails
+# run-guards.sh) falls through to on a miss. Same split as hook::jq_fields.
+hook::bash_parse_segments() {
+  hook::bash_parse_segments_uncached "$@"
+}
+
+# Single linear pass: read the command into a byte array once (O(n)), then walk
+# it splitting top-level segments on UNQUOTED control operators and tokenizing
+# each segment into argv words honoring '…', "…", $'…', backslash escapes
+# (including backslash-newline continuation), and unquoted `#` comments to EOL
+# (quoted `#` preserved). Each completed segment is passed to the callback as it
+# closes, so no full segment list is retained.
+#
+# Call as: hook::bash_parse_segments <command-string> <callback>; the callback
+# receives one segment's argv words as "$@" and reads the segment's OTHER half —
+# the redirections bash strips out of argv — from these arrays, all rebuilt
+# before every call, so a consumer whose subject is the redirect target does not
+# need a second tokenizer over the same string:
+#
+#   HOOK_SEG_WORD_QUOTED[i]   quoting provenance of argv word i: 0 the word is
+#                             literally the text that was written, 1 quoting or
+#                             a backslash escape produced part of it, 2 every
+#                             character of it came from quoted spans (`""`,
+#                             `"a"`, `'a''b'`).
+#   HOOK_SEG_REDIR_OP[j]      operator in source order — `>` `>>` `<` `<>` `>&`
+#                             `<&` `<<` `<<-` `<<<`. `<<`/`<<-` is a here-doc
+#                             OPENER, whose target is the delimiter (the body is
+#                             stdin and is skipped, not tokenized); `<<<` is a
+#                             here-string, whose target is the string.
+#   HOOK_SEG_REDIR_FD[j]      the fd prefix word (`2` of `2>err`), else "".
+#   HOOK_SEG_REDIR_TARGET[j]  the target word as bash would expand quoting away;
+#                             for a dup or close (`>&1`, `>&-`) the fd or `-`.
+#   HOOK_SEG_REDIR_QUOTED[j]  1 when quoting or a backslash escape produced that
+#                             text, so the text written is not the text used.
+#   HOOK_SEG_REDIR_OPAQUE[j]  1 when the operand is not resolvable here at all:
+#                             a quote that never closed, an operand cut short by
+#                             a control operator or end of input, or one a
+#                             process substitution supplied.
+#
+# A segment with redirections but no argv word (`> f` alone) invokes no
+# callback, so its redirections are not reported.
+# shellcheck disable=SC1003  # '\' compares a literal backslash char, not a quote escape
+hook::bash_parse_segments_uncached() {
+  local cmd="$1" cb="$2"
+  local -a chars=()
+  local c nx n i __hu_acd
+  # In-process, not `read -N1` from a process substitution, which forked a
+  # subshell (and a printf) per parse even though both are builtins (Command
+  # Substitution, Bash Reference Manual;
+  # https://mywiki.wooledge.org/CommandSubstitution); Cygwin's fork is a
+  # non-copy-on-write Win32 CreateProcess (Cygwin User's Guide, Process
+  # Creation). Not a here-string either: one at or above the pipe capacity
+  # can block the shell (hook::json_complete).
+  hook::_bps_chars "$cmd"
+  n=${#chars[@]}
+  # `pend` is set while a redirection is waiting for its operand word: the next
+  # word to close becomes that target instead of an argv word.
+  local word="" have=0 pend=0 rop_txt="" rfd_next="" rdup=""
+  # Quoting provenance of the word being assembled — whether a quoted span fed
+  # it, whether any character reached it unquoted, whether a backslash escape
+  # did, and whether a span was still open at end of input. Reset with the word.
+  local wq_quoted=0 wq_plain=0 wq_esc=0 wq_open=0
+  local -a seg=()
+  HOOK_SEG_WORD_QUOTED=()
+  HOOK_SEG_REDIR_OP=()
+  HOOK_SEG_REDIR_FD=()
+  HOOK_SEG_REDIR_TARGET=()
+  HOOK_SEG_REDIR_QUOTED=()
+  HOOK_SEG_REDIR_OPAQUE=()
+  # Pending heredoc delimiters (FIFO) and their `<<-` tab-strip flags. A
+  # heredoc body is the command's stdin, not commands — recorded when `<<`
+  # is seen and skipped wholesale at the command-line newline.
+  local -a hd_delims=() hd_strip=()
+
+  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
+      ((i >= n)) && wq_open=1
+      wq_quoted=1
+      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
+      ((i >= n)) && wq_open=1
+      wq_quoted=1
+      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
+        ((i >= n)) && wq_open=1
+        hook::ansi_c_decode_to __hu_acd "$body"
+        word+="$__hu_acd"
+        wq_quoted=1
+        have=1
+      else
+        word+="$c"
+        wq_plain=1
+        have=1
+      fi
+      ;;
+    '\')
+      if ((i + 1 < n)); then
+        nx="${chars[i + 1]}"
+        if [[ "$nx" == $'\n' ]]; then
+          # bash removes a backslash-newline outright. It joins a word only when
+          # one is already open, so the escape is provenance for THAT word and
+          # for nothing after it.
+          ((have)) && wq_esc=1
+          ((i++))
+        else
+          word+="$nx"
+          ((i++))
+          wq_esc=1
+          have=1
+        fi
+      else
+        wq_esc=1
+        have=1
+      fi
+      ;;
+    ' ' | $'\t')
+      ((have)) && hook::_bps_close_word
+      ;;
+    '#')
+      # Unquoted `#` starts a shell comment to EOL only at a word boundary (no
+      # word currently being assembled). Mid-word `#` (`x#y`) stays literal.
+      if ((have)); then
+        word+="#"
+        wq_plain=1
+      else
+        while ((i + 1 < n)) && [[ "${chars[i + 1]}" != $'\n' ]]; do
+          ((i++))
+        done
+      fi
+      ;;
+    '>' | '<')
+      # Redirection: bash removes the operator and its target word from
+      # argv (redirections may appear anywhere in a simple command), so
+      # `git reset --hard>/tmp/out` still runs reset --hard. Both halves are
+      # kept — argv for the callback's "$@", the operator, fd, target and its
+      # quoting provenance in HOOK_SEG_REDIR_*. A pure-digit
+      # word immediately before the operator is its fd prefix, not argv;
+      # an fd-dup/close form (`2>&1`, `>&-`) names an fd, so its target is that
+      # fd (or `-`) and no operand word follows.
+      rfd_next=""
+      if ((have)); then
+        if [[ "$word" =~ ^[0-9]+$ ]]; then
+          rfd_next="$word"
+          word=""
+          have=0
+          wq_quoted=0
+          wq_plain=0
+          wq_esc=0
+          wq_open=0
+        else
+          hook::_bps_close_word
+        fi
+      fi
+      # Heredoc `<<` / `<<-` (but NOT here-string `<<<`): the body on the
+      # following lines is the command's stdin, so record the delimiter and
+      # let the newline handler skip the body. A quoted/backslashed delimiter
+      # (`<<'EOF'`, `<<\EOF`) still terminates on a line reading `EOF`.
+      if [[ "$c" == '<' ]] && ((i + 1 < n)) && [[ "${chars[i + 1]}" == '<' ]] &&
+        { ((i + 2 >= n)) || [[ "${chars[i + 2]}" != '<' ]]; }; then
+        ((i++))
+        local hstrip=0 hquoted=0
+        if ((i + 1 < n)) && [[ "${chars[i + 1]}" == '-' ]]; then
+          hstrip=1
+          ((i++))
+        fi
+        while ((i + 1 < n)) && [[ "${chars[i + 1]}" == ' ' || "${chars[i + 1]}" == $'\t' ]]; do ((i++)); done
+        local delim=""
+        while ((i + 1 < n)); do
+          nx="${chars[i + 1]}"
+          case "$nx" in
+          ' ' | $'\t' | $'\n' | ';' | '&' | '|' | '<' | '>') break ;;
+          "'")
+            hquoted=1
+            ((i++))
+            while ((i + 1 < n)) && [[ "${chars[i + 1]}" != "'" ]]; do
+              delim+="${chars[i + 1]}"
+              ((i++))
+            done
+            ((i + 1 < n)) && ((i++))
+            ;;
+          '"')
+            hquoted=1
+            ((i++))
+            while ((i + 1 < n)) && [[ "${chars[i + 1]}" != '"' ]]; do
+              delim+="${chars[i + 1]}"
+              ((i++))
+            done
+            ((i + 1 < n)) && ((i++))
+            ;;
+          '\')
+            hquoted=1
+            ((i++))
+            ((i + 1 < n)) && {
+              delim+="${chars[i + 1]}"
+              ((i++))
+            }
+            ;;
+          *)
+            delim+="$nx"
+            ((i++))
+            ;;
+          esac
+        done
+        hd_delims+=("$delim")
+        hd_strip+=("$hstrip")
+        # The opener is a redirection whose target is the delimiter. A pending
+        # operand ahead of it never arrived.
+        hook::_bps_orphan_pending
+        if ((hstrip)); then HOOK_SEG_REDIR_OP+=('<<-'); else HOOK_SEG_REDIR_OP+=('<<'); fi
+        HOOK_SEG_REDIR_FD+=("$rfd_next")
+        HOOK_SEG_REDIR_TARGET+=("$delim")
+        HOOK_SEG_REDIR_QUOTED+=("$hquoted")
+        HOOK_SEG_REDIR_OPAQUE+=(0)
+        continue
+      fi
+      if ((i + 1 < n)) && [[ "${chars[i + 1]}" == '(' ]]; then
+        # Process substitution <(list)/>(list): the list is a real command
+        # substituted as a filename — it satisfies any pending target, which no
+        # parse can resolve to a path, and the '(' separator splits it into a
+        # segment that gets scanned.
+        hook::_bps_orphan_pending
+      else
+        rop_txt="$c"
+        while ((i + 1 < n)) && [[ "${chars[i + 1]}" == [\<\>] ]]; do # portability-ok: bash glob bracket class matching a literal < or > character, not a GNU grep \< \> word boundary
+          rop_txt+="${chars[i + 1]}"
+          ((i++))
+        done
+        # A second operator arriving while one still waits means the first
+        # never got an operand.
+        hook::_bps_orphan_pending
+        rdup=""
+        if ((i + 1 < n)) && [[ "${chars[i + 1]}" == '&' ]]; then
+          ((i++))
+          rop_txt+='&'
+          while ((i + 1 < n)) && [[ "${chars[i + 1]}" == [0-9-] ]]; do
+            rdup+="${chars[i + 1]}"
+            ((i++))
+          done
+        fi
+        HOOK_SEG_REDIR_OP+=("$rop_txt")
+        HOOK_SEG_REDIR_FD+=("$rfd_next")
+        HOOK_SEG_REDIR_TARGET+=("$rdup")
+        HOOK_SEG_REDIR_QUOTED+=(0)
+        HOOK_SEG_REDIR_OPAQUE+=(0)
+        # A dup or close already names its target; every other form takes the
+        # next word.
+        [[ -n "$rdup" ]] || pend=1
+      fi
+      ;;
+    ';' | '&' | '|' | '(' | ')' | '`' | $'\n')
+      ((have)) && hook::_bps_close_word
+      hook::_bps_flush_segment
+      # A command-line newline ends the line that introduced any pending
+      # heredocs; their bodies (up to and including each delimiter line) are
+      # stdin, so consume them without tokenizing. Delimiters match in FIFO
+      # order; `<<-` strips leading tabs from body lines before comparing.
+      if [[ "$c" == $'\n' ]] && ((${#hd_delims[@]})); then
+        local hidx line lc d strip
+        for ((hidx = 0; hidx < ${#hd_delims[@]}; hidx++)); do
+          d="${hd_delims[hidx]}"
+          strip="${hd_strip[hidx]}"
+          while ((i + 1 < n)); do
+            line=""
+            while ((i + 1 < n)) && [[ "${chars[i + 1]}" != $'\n' ]]; do
+              line+="${chars[i + 1]}"
+              ((i++))
+            done
+            ((i + 1 < n)) && ((i++))
+            lc="$line"
+            if ((strip)); then
+              while [[ "$lc" == $'\t'* ]]; do lc="${lc#?}"; done
+            fi
+            [[ "$lc" == "$d" ]] && break
+          done
+        done
+        hd_delims=()
+        hd_strip=()
+      fi
+      ;;
+    *)
+      word+="$c"
+      wq_plain=1
+      have=1
+      ;;
+    esac
+  done
+  ((have)) && hook::_bps_close_word
+  hook::_bps_flush_segment
+}
+
+# ============================================================================
+# Reporting one tool's judgment on one file
+# ============================================================================
+#
+# A hook that drives a formatter or linter over the edited file turns that
+# tool's output into the same two things, for two different readers:
+#
+#   the agent channel   a heading with one indented line per diagnostic
+#   data.findings       those same lines as a JSON array, for a telemetry sink
+#
+# Both are built here, so such a hook states only what differs — how to invoke
+# its tool, how to read its exit code, and what its headings say.
+
+# Encode raw tool output as a data.findings array: one JSON string per line.
+#
+#   hook::findings_encode_to <dest> <raw>
+#
+# The encode sits behind the sink opt-in because data.findings has exactly one
+# reader — hook::emit_telemetry, which returns immediately when no sink is
+# wired. Keeping the check INSIDE is what makes it hold: no caller can obtain
+# the array without paying it, so the unwired default path spends no process on
+# a value nothing reads. Empty output, no sink, or a jq that is missing or
+# fails all answer `[]`.
+#
+# The two-process `jq -R . | jq -s .` shape is load-bearing. A single
+# `jq -R -s 'split("\n")'` decodes the whole stream as ONE string first, so a
+# truncated UTF-8 lead byte sitting immediately before a newline absorbs that
+# newline into a single U+FFFD and merges two diagnostics into one array
+# element. Line mode splits on the raw byte before decoding and keeps them
+# apart.
+hook::findings_encode_to() {
+  local __hu_fe_json='[]'
+  if [[ -n "$2" ]] && hook::telemetry_enabled; then
+    __hu_fe_json=$(printf '%s' "$2" | jq -R . | jq -s . 2>/dev/null) ||
+      __hu_fe_json='[]'
+  fi
+  printf -v "$1" '%s' "$__hu_fe_json"
+}
+
+# Build the agent-channel report from a tool's output, and optionally the
+# matching data.findings array.
+#
+#   hook::findings_to <ctx-dest> <heading> <output> [<findings-dest>]
+#                     [--max <n> [--more <hint>]] [--delta <input> <file>]
+#
+# <ctx-dest> receives <heading> followed by one `  `-indented line per NON-EMPTY
+# line of <output>; a tool that printed nothing leaves the heading standing
+# alone. Blank lines are dropped on both channels because they carry no
+# diagnostic and cost the model context.
+#
+# <findings-dest>, when given, receives every one of those lines through
+# hook::findings_encode_to, whatever --max and --delta do to <ctx-dest>. Omit it
+# on an arm reporting a TOOL BREAK rather than a judgment: the break diagnostic
+# belongs on the agent channel, while data.findings stays empty because the
+# tool produced no findings. An arm that needs the unfiltered stream in
+# data.findings — blank lines and all — calls hook::findings_encode_to directly
+# instead.
+#
+# --max <n> keeps the first <n> lines (0 keeps all) and ends the report with
+# `  ... and K more` plus ` (<hint>)` when --more gives one.
+#
+# --delta <input> <file> sends a finding set once: when this (session, agent,
+# file) last reported the same lines under the same --max, <ctx-dest> is "".
+# An empty <output> clears the record and leaves <ctx-dest> "", so call it on a
+# clean run too: findings that come back after a fix are reported again.
+# hook::findings_digest_reset clears every record of a session after compaction.
+hook::findings_to() {
+  local __hu_ft_dest="$1" __hu_ft_ctx="$2" __hu_ft_out="$3" __hu_ft_fd=""
+  local __hu_ft_max=0 __hu_ft_more="" __hu_ft_delta=0 __hu_ft_in="" __hu_ft_file=""
+  shift 3
+  if (($#)) && [[ "$1" != --* ]]; then
+    __hu_ft_fd="$1"
+    shift
+  fi
+  while (($#)); do
+    case "$1" in
+    --max)
+      __hu_ft_max="$2"
+      shift 2
+      ;;
+    --more)
+      __hu_ft_more="$2"
+      shift 2
+      ;;
+    --delta)
+      __hu_ft_delta=1
+      __hu_ft_in="$2"
+      __hu_ft_file="$3"
+      shift 3
+      ;;
+    *) shift ;;
+    esac
+  done
+  [[ "$__hu_ft_max" =~ ^[0-9]+$ ]] || __hu_ft_max=0
+  local __hu_ft_raw="" __hu_ft_line __hu_ft_n=0
+  while IFS= read -r __hu_ft_line; do
+    [[ -n "$__hu_ft_line" ]] || continue
+    __hu_ft_n=$((__hu_ft_n + 1))
+    __hu_ft_raw+="$__hu_ft_line"$'\n'
+    ((__hu_ft_max == 0 || __hu_ft_n <= __hu_ft_max)) && __hu_ft_ctx+=$'\n'"  $__hu_ft_line"
+  done <<<"$__hu_ft_out"
+  if ((__hu_ft_max > 0 && __hu_ft_n > __hu_ft_max)); then
+    __hu_ft_ctx+=$'\n'"  ... and $((__hu_ft_n - __hu_ft_max)) more${__hu_ft_more:+ ($__hu_ft_more)}"
+  fi
+  [[ -n "$__hu_ft_fd" ]] && hook::findings_encode_to "$__hu_ft_fd" "$__hu_ft_raw"
+  if ((__hu_ft_delta)); then
+    local __hu_ft_s __hu_ft_a __hu_ft_dir __hu_ft_key __hu_ft_prev=""
+    if ((__hu_ft_n == 0)); then
+      __hu_ft_ctx=""
+    fi
+    hook::session_agent_to __hu_ft_s __hu_ft_a "$__hu_ft_in"
+    if hook::_state_dir_to __hu_ft_dir finding-digests; then
+      hook::_file_key_to __hu_ft_key "$__hu_ft_file"
+      local __hu_ft_rec="$__hu_ft_dir/${__hu_ft_s}.${__hu_ft_a}.${__hu_ft_key}"
+      if ((__hu_ft_n == 0)); then
+        [[ -f "$__hu_ft_rec" ]] && { rm -f "$__hu_ft_rec" 2>/dev/null || true; }
+      else
+        # The record holds what was sent, so it also proves which file it is for.
+        local __hu_ft_now="max=$__hu_ft_max"$'\n'"$__hu_ft_file"$'\n'"$__hu_ft_raw"
+        [[ -f "$__hu_ft_rec" ]] && { IFS= read -r -d '' __hu_ft_prev <"$__hu_ft_rec" || true; }
+        if [[ "$__hu_ft_prev" == "$__hu_ft_now" ]]; then
+          __hu_ft_ctx=""
+        else
+          printf '%s' "$__hu_ft_now" 2>/dev/null >"$__hu_ft_rec" || true
+        fi
+      fi
+    fi
+  fi
+  printf -v "$__hu_ft_dest" '%s' "$__hu_ft_ctx"
+  return 0
+}
+
+# hook::findings_digest_reset <input>: on a SessionStart whose source is
+# `compact` or `clear`, delete every hook::findings_to --delta record of that
+# session, so the model, which lost the reports with its context, is told again.
+# Any other input does nothing. For a SessionStart hook row with matcher
+# `compact|clear`.
+hook::findings_digest_reset() {
+  [[ "$1" =~ \"source\"[[:space:]]*:[[:space:]]*\"(compact|clear)\" ]] || return 0
+  local __hu_fr_s __hu_fr_a
+  hook::session_agent_to __hu_fr_s __hu_fr_a "$1"
+  [[ -n "${CLAUDE_PLUGIN_DATA:-}" ]] || return 0
+  local __hu_fr_recs=("${CLAUDE_PLUGIN_DATA%/}/finding-digests/${__hu_fr_s}".*)
+  [[ -e "${__hu_fr_recs[0]}" ]] && { rm -f "${__hu_fr_recs[@]}" 2>/dev/null || true; }
+  return 0
+}
+
+# Compose the skip notice a hook emits when the tool it drives is not on this
+# hook's PATH. hook::prereq_notice_to composes the same notice from the
+# plugin's prerequisites.json and splits it per channel; prefer it.
+#
+#   hook::tool_missing_notice_to <dest> <lead> <scope> [<tail>]
+#
+#   <lead>   the first sentence, through "skipped for this edit": which plugin,
+#            which tool was not found and where it was looked for, and what was
+#            skipped as a result
+#   <scope>  the edit class the probe re-runs on ("matching", "shell")
+#   <tail>   the install route and any tool-specific advice
+#
+# The PATH that was probed goes to stderr, which an exit-0 hook sends to the
+# debug log.
+hook::tool_missing_notice_to() {
+  printf 'PATH probed: %s\n' "${PATH:-<unset>}" >&2
+  printf -v "$1" '%s' "$2 (the probe re-runs on every $3 edit; this notice does not repeat this session). Hooks read Claude Code's PATH, not your shell profile${4:-}"
+}
diff --git a/.githooks/guardrails/machine-path-patterns.sh b/.githooks/guardrails/machine-path-patterns.sh
new file mode 100644
index 0000000000..162d7b8d88
--- /dev/null
+++ b/.githooks/guardrails/machine-path-patterns.sh
@@ -0,0 +1,66 @@
+# shellcheck shell=bash
+# The bodies are consumed by the sourcing drivers, never in this file itself —
+# SC2034 "appears unused" is a false positive for a define-only library.
+# shellcheck disable=SC2034
+# Machine-specific path detection — shared per-OS regex BODIES, define-only.
+#
+# No functions, no env reads, no I/O, no exit calls. A scan driver sources
+# this file and adds its own wrapping: boundary prefixes, exclusion pipe
+# stages, exemptions, and exit-code mapping stay driver-owned.
+#
+# POSIX ERE only (grep -E) — NO grep -P: macOS BSD grep lacks it entirely,
+# and bash =~ delegates to the platform regex library, so non-POSIX
+# extensions would not behave identically on Linux CI and Git Bash.
+#
+# 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.
+#
+# 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.
+#
+# The Windows bodies are self-anchored by [A-Za-z]:. The slash-rooted
+# macOS/Linux bodies need a driver-side boundary prefix so a substring like
+# "doc/Users/guide" inside a longer word does not false-match.
+#
+# Right boundary: the child-segment class itself. Each body requires at least
+# one child segment past its root — a bare root (the home or checkout-parent
+# directory with no child) never matches — but the child needs NO trailing
+# separator: the class excludes whitespace and the double quote, so a match
+# ends at the segment's natural value boundary (EOL, whitespace, quote, or
+# the next separator). A % is admitted mid-segment ONLY when a digit follows —
+# `build%2026` is a real directory name, `%VAR%` and `build-%VAR%` are env
+# interpolations, and a Windows env var cannot start with a digit. Excluding %
+# throughout instead still MATCHED a literal-% path but truncated the span at
+# the % (`C:\Users\build` for `C:\Users\build%2026`), handing drivers a path
+# that does not exist. Admitting % unconditionally after the first character
+# swaps that for the opposite error: it would match `build-%USERNAME%` in full
+# and confidently report a portable path as machine-specific. The digit gate is
+# the only form that gets both right. A mandatory trailing separator was the original design
+# and inverted detection both ways: a real bare value at end of line
+# ("root = <drive>:/Dev/GitHub") has no trailing separator and was MISSED,
+# while prose satisfied the requirement anyway — the old space-permitting
+# segment class greedily consumed words until a later slash appeared on the
+# same line, flagging comments instead of values. Excluding whitespace from
+# the class is what makes dropping the separator prose-safe: a phrase like
+# "/Users/ for details" cannot match because at least one non-space child
+# character must follow the root.
+HPP_WIN_USER_BODY='[A-Za-z]:(/|\\\\?)Users(/|\\\\?)[^\\$%<{~"[:space:]/]([^\\$%<{~"[:space:]/]|%[0-9])*(~[0-9]+)?'
+HPP_MACOS_USER_BODY='/Users/[^\\$%<{~"[:space:]/]([^\\$%<{~"[:space:]/]|%[0-9])*'
+HPP_LINUX_USER_BODY='/home/[^\\$%<{~"[:space:]/]([^\\$%<{~"[:space:]/]|%[0-9])*'
+# The checkout-parent segment is drive-letter-anchored, so broadening it beyond
+# `repos` to the other common checkout-root names stays false-positive-safe —
+# only a genuine `X:\<root>\<child>\` absolute path matches, never prose. Both
+# lowercase and Capitalized spellings are listed (a regex character class such
+# as `[Rr]` would leave a partial token the docs typos-gate flags). A consumer's
+# OWN checkout root is already caught by the driver's project-root literal scan;
+# this generic body catches references to OTHER machines' checkout paths in
+# written content.
+HPP_WIN_REPO_BODY='[A-Za-z]:(/|\\\\?)(repos|Repos|projects|Projects|dev|Dev)(/|\\\\?)[^\\$%<{~"[:space:]/]([^\\$%<{~"[:space:]/]|%[0-9])*(~[0-9]+)?'
+HPP_ESCAPED_WIN_REPO_BODY='[A-Za-z]:\\\\(repos|Repos|projects|Projects|dev|Dev)\\\\[^\\$%<{~"[:space:]/]([^\\$%<{~"[:space:]/]|%[0-9])*(~[0-9]+)?'
diff --git a/.githooks/guardrails/pre-commit-content.sh b/.githooks/guardrails/pre-commit-content.sh
new file mode 100755
index 0000000000..186547f65b
--- /dev/null
+++ b/.githooks/guardrails/pre-commit-content.sh
@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# guardrails pre-commit-content sha256:619d1826b86672be22ccaa584b1b2503fafcb799e8547149406d6118dc4b6100
+# guardrails-pre-commit-content v2
+# guardrails pre-commit check: secrets and machine-specific paths in the lines
+# this commit adds.
+#
+#   pre-commit-content.sh               the staged changes (git runs it as pre-commit)
+#   pre-commit-content.sh --worktree    the uncommitted changes against HEAD,
+#                                       untracked files included
+#
+# The write-path-independent layer for what the secret-pattern-detection and
+# hardcoded-path-check guards stop on Write and Edit: a shell command, a script
+# or another tool can write a file no Claude Code guard sees, and this check
+# reads what reaches a commit. It uses the same pattern libraries, installed
+# beside this script as entry assets.
+#
+# Each file is judged the way a Write or Edit of it would be: a new file on its
+# whole content, a changed file on the lines the commit adds, read from the
+# index (the work tree with --worktree). Every staged path is judged, a
+# force-added gitignored one included; --worktree leaves out untracked
+# gitignored files. Skipped: symbolic links, submodules and files over 1 MiB.
+# A file holding a NUL byte (whatever a `-diff` attribute says) is judged
+# whole for secrets only. The two
+# guards' path exemptions apply (tests/fixtures for secrets only).
+#
+# Findings print as "<path>:<line>: <message>" on stderr and exit 1. The
+# message says how to fix the content; this hook never suggests skipping it.
+set -uo pipefail
+
+here="${BASH_SOURCE[0]%/*}"
+[[ "$here" == "${BASH_SOURCE[0]}" ]] && here=.
+lib="$here/check-lib.sh"
+[[ -f "$lib" ]] || lib="$here/../lib/git-hooks/check-lib.sh"
+# shellcheck source=../lib/git-hooks/check-lib.sh
+. "$lib" || exit 1
+
+# The pattern libraries: beside an installed copy (entry assets), or in the
+# plugin's lib/ when run from the plugin itself.
+secret_lib="$here/secret-patterns.sh"
+[[ -f "$secret_lib" ]] || secret_lib="$here/../lib/secret-detection/secret-patterns.sh"
+path_lib="$here/hardcoded-path-patterns.sh"
+[[ -f "$path_lib" ]] || path_lib="$here/../lib/path-detection/hardcoded-path-patterns.sh"
+# shellcheck source=../lib/secret-detection/secret-patterns.sh
+. "$secret_lib" || exit 1
+# shellcheck source=../lib/path-detection/hardcoded-path-patterns.sh
+. "$path_lib" || exit 1
+
+checks_init pre-commit "$@" || exit 0
+MAX_BYTES=1048576
+
+# Hardcoded-path exemptions, as hardcoded-path-check.sh has them.
+path_exempt() {
+  case "$1" in
+  *.claude/hooks/* | *.lefthook/*) return 0 ;;
+  *settings.local.json | *CLAUDE.local.md) return 0 ;;
+  */.venv/* | .venv/* | */node_modules/* | node_modules/*) return 0 ;;
+  *.env.example | *.env.sample | *.env.template) return 0 ;;
+  *.claude/skills/*/context/* | *.claude/skills/*/completed/*) return 0 ;;
+  */lib/secret-detection/* | */lib/path-detection/*) return 0 ;;
+  # The same libraries as this entry's shared-scope assets.
+  .githooks/guardrails/secret-patterns.sh | .githooks/guardrails/hardcoded-path-patterns.sh | \
+    .githooks/guardrails/machine-path-patterns.sh) return 0 ;;
+  *) return 1 ;;
+  esac
+}
+
+# Secret exemptions, as secret-pattern-detection.sh has them: the path set
+# plus test fixtures.
+secret_exempt() {
+  case "$1" in
+  *tests/fixtures/* | *tests/testdata/* | *Tests/fixtures/* | *Tests/testdata/*) return 0 ;;
+  *) path_exempt "$1" ;;
+  esac
+}
+
+# The repository path itself is a finding, unless the checkout sits at, above
+# or below the home directory, where every home path would match it.
+scan_root="$PWD"
+home="${HOME:-${USERPROFILE:-}}"
+home="${home%/}"
+if [[ -n "$home" ]]; then
+  case "$PWD/" in
+  "$home/" | "$home"/*) scan_root="" ;;
+  *) ;;
+  esac
+  case "$home/" in
+  "$PWD"/*) scan_root="" ;;
+  *) ;;
+  esac
+fi
+
+# index_mode <path>: the staged mode, empty when the path is not staged.
+index_mode() {
+  local entry
+  entry="$(git ls-files -s -- ":(literal)$1" 2>/dev/null)"
+  printf '%s' "${entry%% *}"
+}
+
+file_size() {
+  if [[ "$CHECKS_MODE" == worktree ]]; then
+    wc -c <"$1" | tr -d ' '
+  else
+    git cat-file -s ":$1" 2>/dev/null || echo 0
+  fi
+}
+
+checks_changed_lines
+
+# added_only <path>: the file with every line the commit does not add blanked,
+# so line numbers hold and only added text is scanned.
+added_only() {
+  awk -v want="$1" -v ranges="$CHECKS_TMP/ranges" '
+    BEGIN { while ((getline l < ranges) > 0) { split(l, r, "\t"); if (r[1] == want) { n++; s[n] = r[2] + 0; e[n] = r[3] + 0 } } }
+    { keep = 0; for (i = 1; i <= n; i++) if (NR >= s[i] && NR <= e[i]) { keep = 1; break } print (keep ? $0 : "") }'
+}
+
+# secret_findings <path>: secrets::scan_text output on stdin, as findings.
+secret_findings() {
+  sed -n 's/^\(.*\) (line \([0-9,]*\))$/\2 \1/p' |
+    while read -r nums label; do
+      for n in ${nums//,/ }; do
+        printf '%s:%s: secret or credential pattern: %s\n' "$1" "$n" "$label"
+      done
+    done
+}
+
+out="$CHECKS_TMP/findings"
+whole="$CHECKS_TMP/findings-whole"
+: >"$out"
+: >"$whole"
+while IFS= read -r -d '' f; do
+  if [[ "$CHECKS_MODE" == worktree ]]; then
+    [[ -f "$f" && ! -L "$f" ]] || continue
+  else
+    case "$(index_mode "$f")" in
+    100644 | 100755) ;;
+    *) continue ;;
+    esac
+  fi
+  (($(file_size "$f") <= MAX_BYTES)) || continue
+  if checks_has_nul "$f"; then
+    # A NUL byte must not hide a secret: scan the whole raw content for the
+    # secret patterns twice, each NUL read as a space, then each NUL deleted
+    # (UTF-16LE text puts one after every ASCII byte). Both keep newlines, so
+    # line numbers hold; the second pass reports only labels the first missed.
+    # Path patterns are not judged here, so an ordinary binary still commits.
+    secret_exempt "$f" && continue
+    text="$(checks_file_text "$f" | tr '\0' ' '; printf x)"
+    packed="$(checks_file_text "$f" | tr -d '\0'; printf x)"
+    {
+      secrets::scan_text "${text%x}"
+      echo --
+      secrets::scan_text "${packed%x}"
+    } | awk '$0 == "--" { p2 = 1; next }
+      { l = $0; sub(/ \(line [0-9,]*\)$/, "", l) }
+      p2 && (l in seen) { next }
+      !p2 { seen[l] } { print }' | secret_findings "$f" >>"$whole"
+    continue
+  fi
+  sink="$out"
+  if [[ "$f" == *[\"\\[:cntrl:]]* ]]; then
+    # Git quotes such a name whatever core.quotePath says, so the range table
+    # holds no entry for it: the file is judged whole, past the range filter.
+    text="$(checks_file_text "$f"; printf x)"
+    sink="$whole"
+  else
+    text="$(checks_file_text "$f" | added_only "$f"; printf x)"
+  fi
+  text="${text%x}"
+  [[ -n "${text//[[:space:]]/}" ]] || continue
+
+  if ! secret_exempt "$f"; then
+    secrets::scan_text "$text" | secret_findings "$f" >>"$sink"
+  fi
+  if ! path_exempt "$f"; then
+    hpp::scan_text "$text" "$scan_root" "$PWD/$f" |
+      awk -v f="$f" '
+        /^[^ \t].*:$/ && !/^[0-9]+:/ { label = substr($0, 1, length($0) - 1); next }
+        match($0, /^[0-9]+:/) { printf "%s:%s: machine-specific path (%s)\n", f, substr($0, 1, RLENGTH - 1), label }' >>"$sink"
+  fi
+done < <(checks_files)
+
+{
+  checks_filter_findings <"$out"
+  cat "$whole"
+} | sort -u -t: -k1,1 -k2,2n >"$CHECKS_TMP/blocking"
+[[ -s "$CHECKS_TMP/blocking" ]] || exit 0
+cat "$CHECKS_TMP/blocking" >&2
+printf 'guardrails: remove the secrets or machine-specific paths above from the change (use a placeholder, an environment variable or a portable path), then commit again.\n' >&2
+exit 1
diff --git a/.githooks/guardrails/reference-verify.sh b/.githooks/guardrails/reference-verify.sh
new file mode 100755
index 0000000000..1f9e53809d
--- /dev/null
+++ b/.githooks/guardrails/reference-verify.sh
@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# guardrails reference-verify sha256:071d805fd1ce47521d3f6fbb3bf0f266507762648b9690bea62d9c1f691f91da
+# guardrails pre-push check: CLI flags, /plugin:skill references and cited
+# repository paths in the lines the pushed commits add.
+#
+#   reference-verify.sh <remote> <url>   the pushed ranges, refs on stdin (git
+#                                        runs it as pre-push)
+#   reference-verify.sh --worktree       the uncommitted changes against HEAD,
+#                                        untracked files included
+#
+# Runs the three verifiers that used to report after every Claude Code edit
+# (cli-flag-verify, skill-reference-verify, stale-path-verify) once per changed
+# .md, .sh, .bash, .ps1 or .psm1 file, through the plugin's run-guards.sh
+# dispatcher, all installed beside this script as entry assets. Each file is
+# handed over the way the edit row handed it: a file new to the range as a
+# Write of its whole content, a changed file as an Edit whose new text is the
+# lines the range adds, so a finding is always about an added line. The
+# verifiers' own scope gates hold (skill references are judged only in a
+# marketplace repository). It runs at pre-push, not pre-commit, because its
+# cost is over the commit budget (check-placement convention, measured rows).
+#
+# The ranges come from the check lib: one per pushed ref, a new branch from its
+# merge-base with the remote's default branch, a deletion skipped. A hook
+# manager that keeps stdin from this script (lefthook passes it to only one
+# use_stdin job) leaves the lib's fallback: the current branch against its
+# upstream. Each range is checked on its own, in that range's tip: the
+# checkout when HEAD is the tip and the tree is clean, else a temporary
+# detached worktree of the tip, removed afterwards.
+#
+# A finding prints as "<path>:<line>: <message>" on stderr, the line being the
+# file's first added line, and exits 1. Missing jq follows the check-placement
+# contract: checks.skipmissing, else fail for an agent and a notice for a person.
+set -uo pipefail
+
+here="${BASH_SOURCE[0]%/*}"
+[[ "$here" == "${BASH_SOURCE[0]}" ]] && here=.
+here="$(cd "$here" && pwd)"
+lib="$here/check-lib.sh"
+[[ -f "$lib" ]] || lib="$here/../lib/git-hooks/check-lib.sh"
+# shellcheck source=../lib/git-hooks/check-lib.sh
+. "$lib" || exit 1
+
+checks_init pre-push "$@" || exit 0
+checks_require_tool jq "https://jqlang.org/download/"
+
+# The dispatcher and the verifiers: beside an installed copy, else the
+# plugin's own hooks/. cli-flag-verify finds its verifier under
+# $CLAUDE_PLUGIN_ROOT/lib/verification/, so an installed copy gets a scratch
+# root holding the two verifier assets.
+if [[ -f "$here/run-guards.sh" ]]; then
+  run_guards="$here/run-guards.sh"
+  root="$CHECKS_TMP/root"
+  mkdir -p "$root/lib/verification"
+  for f in verify-cli-flag.sh cli-flag-cache.sh; do
+    [[ -f "$here/$f" ]] && cp "$here/$f" "$root/lib/verification/$f"
+  done
+  chmod +x "$root/lib/verification/verify-cli-flag.sh" 2>/dev/null
+else
+  run_guards="$here/../hooks/run-guards.sh"
+  root="$(cd "$here/.." && pwd)"
+fi
+[[ -f "$run_guards" ]] || exit 0
+
+# The tip and base of the range being checked; both empty for --worktree.
+TIP=""
+BASE=""
+
+# is_new <path>: the range adds the file rather than changing it.
+is_new() {
+  if [[ "$CHECKS_MODE" == worktree ]]; then
+    ! git ls-files --error-unmatch -- ":(literal)$1" >/dev/null 2>&1 ||
+      ! git cat-file -e "HEAD:$1" 2>/dev/null
+    return
+  fi
+  ! git cat-file -e "$BASE:$1" 2>/dev/null
+}
+
+# added_lines <path>: the lines the range adds, in order.
+added_lines() {
+  awk -v want="$1" -v ranges="$CHECKS_TMP/ranges" '
+    BEGIN { while ((getline l < ranges) > 0) { split(l, r, "\t"); if (r[1] == want) { n++; s[n] = r[2] + 0; e[n] = r[3] + 0 } } }
+    { for (i = 1; i <= n; i++) if (NR >= s[i] && NR <= e[i]) { print; break } }'
+}
+
+first_line() {
+  awk -v want="$1" -F '\t' '$1 == want { if (min == "" || $2 + 0 < min) min = $2 + 0 } END { print (min == "" ? 1 : min) }' \
+    "$CHECKS_TMP/ranges"
+}
+
+# verified_type <path>: an extension the verifiers read.
+verified_type() {
+  local f="$1"
+  case "$f" in
+    *.md | *.sh | *.bash | *.ps1 | *.psm1) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+out="$CHECKS_TMP/findings"
+: >"$out"
+
+# check_range: every file the current range (or the worktree) changes.
+check_range() {
+  local f text payload ctx line msg _
+  local renamed=$'\n'
+  checks_changed_lines
+  # A rename's destination is missing from the base but is no new text: only
+  # the lines the range adds to it are judged.
+  while IFS= read -r -d '' _ && IFS= read -r -d '' _ && IFS= read -r -d '' f; do
+    renamed+="$f"$'\n'
+  done < <(checks_diff --name-status -M --diff-filter=R -z 2>/dev/null)
+  while IFS= read -r -d '' f; do
+    verified_type "$f" || continue
+    checks_regular_file --tip "$TIP" "$f" || continue
+    # Git quotes a name holding a quote, a backslash or a control byte whatever
+    # core.quotePath says, so the range table has no entry for it: such a file
+    # is judged whole, as a new one is.
+    if [[ "$f" == *[\"\\[:cntrl:]]* ]] || { [[ "$renamed" != *$'\n'"$f"$'\n'* ]] && is_new "$f"; }; then
+      text="$(
+        checks_file_text --tip "$TIP" "$f"
+        printf x
+      )"
+      text="${text%x}"
+      payload="$(jq -n --arg p "$PWD/$f" --arg c "$text" \
+        '{hook_event_name: "PostToolUse", tool_name: "Write", tool_input: {file_path: $p, content: $c}}')"
+    else
+      text="$(
+        checks_file_text --tip "$TIP" "$f" | added_lines "$f"
+        printf x
+      )"
+      text="${text%x}"
+      [[ -n "${text//[[:space:]]/}" ]] || continue
+      payload="$(jq -n --arg p "$PWD/$f" --arg c "$text" \
+        '{hook_event_name: "PostToolUse", tool_name: "Edit", tool_input: {file_path: $p, old_string: "", new_string: $c}}')"
+    fi
+    ctx="$(printf '%s' "$payload" |
+      CLAUDE_PLUGIN_ROOT="$root" bash "$run_guards" cli-flag-verify.sh skill-reference-verify.sh stale-path-verify.sh 2>/dev/null |
+      jq -r '.hookSpecificOutput.additionalContext // empty' 2>/dev/null)"
+    [[ -n "$ctx" ]] || continue
+    line="$(first_line "$f")"
+    while IFS= read -r msg; do
+      [[ -n "${msg//[[:space:]]/}" ]] && printf '%s:%s: %s\n' "$f" "$line" "$msg"
+    done <<<"$ctx" >>"$out"
+  done < <(checks_files)
+}
+
+# tip_is_checkout: the checkout is the tip's tree (HEAD is $TIP, nothing changed
+# or untracked), so the verifiers can read it directly.
+tip_is_checkout() {
+  [[ "$TIP" == "$(git rev-parse --verify --quiet HEAD 2>/dev/null)" && -z "$(git status --porcelain 2>/dev/null)" ]]
+}
+
+if [[ "$CHECKS_MODE" == worktree ]]; then
+  check_range
+else
+  # The lib's diff helpers read $CHECKS_TMP/push-ranges; narrow it to one range
+  # at a time so each file's text and added lines come from that range's tip.
+  top="$PWD"
+  tip_tree="$CHECKS_TMP/tip"
+  mkdir -p "$CHECKS_TMP/no-hooks"
+  # shellcheck disable=SC2064 # expand now: both paths are fixed here
+  trap "rm -rf '$CHECKS_TMP'; git -C '$top' worktree prune 2>/dev/null" EXIT
+  mv "$CHECKS_TMP/push-ranges" "$CHECKS_TMP/all-ranges"
+  while read -r BASE TIP <&3; do
+    printf '%s %s\n' "$BASE" "$TIP" >"$CHECKS_TMP/push-ranges"
+    if tip_is_checkout; then
+      check_range
+      continue
+    fi
+    # The verifiers read the tree around a file (cited paths, the plugins
+    # tree, an edited file's other lines), so they run in a detached checkout
+    # of the tip. An empty hooks path keeps post-checkout hooks from firing.
+    if ! git -c core.hooksPath="$CHECKS_TMP/no-hooks" worktree add -q --detach "$tip_tree" "$TIP" >/dev/null 2>&1; then
+      printf 'NOTICE: could not check out %s, so it was not checked.\n' "$TIP" >&2
+      continue
+    fi
+    cd "$tip_tree" && check_range
+    cd "$top" || exit 1
+    git worktree remove --force "$tip_tree" >/dev/null 2>&1
+    git worktree prune 2>/dev/null
+  done 3<"$CHECKS_TMP/all-ranges"
+fi
+
+[[ -s "$out" ]] || exit 0
+cat "$out" >&2
+printf 'guardrails: correct each flag, skill reference or path above, commit the fix, then push again.\n' >&2
+if grep -q ': cli-flag-verify: ' "$out"; then
+  printf '%s\n' \
+    'guardrails: a cli-flag finding is unverified, not proven wrong. When the flag is right, run /guardrails:setup to stop this' \
+    'entry in this clone: it declines it (install.mjs decline --entry reference-verify) and removes its registration.' >&2
+fi
+printf '%s\n' 'guardrails: git -c checks.skipmissing=jq skips this check only while jq is missing; it never skips a finding.' >&2
+exit 1
diff --git a/.githooks/guardrails/resolve-convention-pattern.sh b/.githooks/guardrails/resolve-convention-pattern.sh
new file mode 100755
index 0000000000..377047da0c
--- /dev/null
+++ b/.githooks/guardrails/resolve-convention-pattern.sh
@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+# GENERATED from lib/resolve-convention-pattern.sh by scripts/sync-shared-copies.sh. Do not edit this copy:
+# edit the canonical source, then rerun the script.
+# Resolve the ENFORCEMENT pattern for a source-control convention key
+# (`subject_pattern` / `pr_title_pattern`) to a POSIX-ERE regex a hook can hand
+# straight to `[[ =~ ]]` or `grep -E`, cross-platform.
+#
+# WHY THIS EXISTS: the convention surface (`.claude/source-control.md`, one
+# `## <key>` H2 per key) is authored for a MODEL to read — its `subject_pattern`
+# value may be the keyword `Conventional Commits` or a regex in PCRE dialect
+# (`(?:…)`, `\d`). A blocking hook cannot evaluate that: `grep -E` chokes on
+# `(?:`, and neither ERE engine knows `\d`. This centralizes the read + the
+# dialect normalization once, so `block-noncanonical-commit`, the CC-layer
+# content gate, and the opt-in `commit-msg` hook all enforce the SAME pattern
+# the SAME way — no per-hook re-fork, no drift.
+#
+# ENFORCEMENT ≠ DRAFTING — the policy-floor contract:
+#   Enforcement reads the TEAM-TRACKED layer ONLY:
+#   `${REPO_ROOT}/.claude/source-control.md`. The user-global
+#   (`~/.claude/source-control.md`) and gitignored local
+#   (`.claude/source-control.local.md`) overlays are DRAFTING inputs the model
+#   merges per `reference/config-resolution.md`; a blocking gate never reads
+#   them. That is the floor by construction: a personal/gitignored file cannot
+#   weaken what the gate enforces because the gate never looks at it, and
+#   "is regex A stricter than B" is undecidable so no merge could honor "tighten
+#   only" anyway. A team with no tracked pattern gets NO enforcement (never the
+#   bundled Conventional Commits default — that default is not lane-1-eligible,
+#   so gating an un-opted-in repo against it violates the two-lane posture).
+#
+# SINGLE SOURCE OF TRUTH: lib/resolve-convention-pattern.sh at the marketplace
+# repo root. Copies materialized into consuming plugins exist only because
+# installed plugins are cache-isolated and must be self-contained — never edit a
+# copy. Edit the source and run scripts/sync-shared-copies.sh; CI rejects
+# drifted copies. Owner contract: docs/conventions/commit-convention/.
+#
+# Usage:
+#   resolve-convention-pattern.sh <repo_root> <subject_pattern|pr_title_pattern>
+#
+# Output: the resolved ERE regex on stdout (no trailing newline sensitivity), or
+#   NOTHING when the key is unresolved OR resolves to a pattern that cannot be
+#   expressed in ERE. A non-enforceable pattern additionally writes a one-line
+#   diagnostic to stderr. Exit status:
+#     0  a pattern was emitted (enforce it)
+#     1  no enforcement (unresolved, or non-ERE-expressible — stdout empty)
+#     2  usage error
+set -uo pipefail
+
+# The bundled Conventional Commits pattern — the ONE place the `Conventional
+# Commits` keyword expands, so the model's interpretation and every hook's regex
+# cannot drift. Mirrors /source-control:commit's documented expansion and is
+# already pure ERE (capturing groups, no `\d`).
+readonly CC_ERE='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+'
+# shellcheck disable=SC2016  # backticks are a literal part of the deferral marker, not a substitution
+readonly PR_DEFERRAL='Same as `subject_pattern`.'
+
+# Well-known default path for the neutral convention SSOT — the marketplace's
+# own dogfooded docs/conventions/<concern>/ layout. When the team file declares
+# no explicit convention_source pointer, the resolver probes this path so the
+# common case reads ONE tool-agnostic file with no markdown pointer-parse. An
+# explicit pointer always overrides it; see the pointer-resolution block below.
+readonly WELL_KNOWN_NEUTRAL="docs/conventions/source-control/commit-convention.yml"
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  # Stop at the first non-comment line rather than a fixed line number: the
+  # header outgrew the hardcoded 40 and the banner silently lost its whole exit
+  # status list. A blank-line terminator will not work here, because the header
+  # runs straight into `set -uo pipefail` with no blank line between them.
+  awk 'NR > 1 { if ($0 !~ /^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"
+  exit 0
+fi
+
+repo_root="${1:-}"
+key="${2:-}"
+
+if [[ -z "$repo_root" || -z "$key" ]]; then
+  echo "resolve-convention-pattern: usage: resolve-convention-pattern.sh <repo_root> <subject_pattern|pr_title_pattern>" >&2
+  exit 2
+fi
+case "$key" in
+subject_pattern | pr_title_pattern) ;;
+*)
+  echo "resolve-convention-pattern: key must be subject_pattern or pr_title_pattern, got '$key'" >&2
+  exit 2
+  ;;
+esac
+
+# Team-tracked layer only — the enforcement authority (see header).
+readonly TEAM_FILE="$repo_root/.claude/source-control.md"
+
+# --- Neutral convention SSOT (docs/conventions/commit-convention/, #1141) ---
+# The team file MAY declare `## convention_source` naming a repo-relative
+# flat-scalar YAML file (the tool-agnostic SSOT other consumers — commit-msg
+# hooks, CI — read with one sed). When declared, that file is authoritative for
+# the machine keys it carries; a key it omits falls back to the team markdown
+# H2. The pointer is honored from the TEAM file only (same policy floor — a
+# gitignored overlay must not redirect the gate), and a declared-but-broken
+# pointer FAILS CLOSED to no-enforcement with a diagnostic rather than silently
+# re-reading markdown values migration may have retired.
+
+# First non-empty body line under `## <key>`, CR-stripped. Empty when the
+# section is absent or bodyless. Awk over sed: needs section-state, not a line
+# match.
+h2_value() {
+  local file="$1" k="$2"
+  [[ -f "$file" ]] || return 0
+  awk -v key="$k" '
+    BEGIN { in_section = 0 }
+    /^##[[:space:]]/ {
+      # A new H2 ends the target section.
+      hdr = $0; sub(/^##[[:space:]]+/, "", hdr); sub(/[[:space:]]+$/, "", hdr)
+      in_section = (hdr == key) ? 1 : 0
+      next
+    }
+    in_section {
+      line = $0; gsub(/\r/, "", line)
+      if (line ~ /^[[:space:]]*$/) next          # skip blank lines before the value
+      sub(/^[[:space:]]+/, "", line); sub(/[[:space:]]+$/, "", line)
+      print line; exit                            # first non-empty body line wins
+    }
+  ' "$file"
+}
+
+# First matching flat-scalar value for a key from the neutral YAML file:
+# `^<key>:` at column 0, CR-stripped, surrounding whitespace trimmed, ONE pair
+# of matching surrounding quotes ('…' or "…") removed. No YAML quote-escape
+# processing — the one-sed extraction contract other consumers rely on can't
+# either, so the seam doc tells authors to write patterns that need no escaping.
+# Full-line `#` comments never match the key anchor; trailing `#` text is NOT
+# stripped (a regex may legitimately contain `#`).
+yaml_value() {
+  local file="$1" k="$2" line v
+  [[ -f "$file" ]] || return 0
+  line="$(grep -m1 -E "^${k}:" "$file" | tr -d '\r')"
+  [[ -n "$line" ]] || return 0
+  v="${line#"${k}":}"
+  v="${v#"${v%%[![:space:]]*}"}"
+  v="${v%"${v##*[![:space:]]}"}"
+  if [[ ${#v} -ge 2 && ("$v" == \'*\' || "$v" == \"*\") ]]; then
+    v="${v:1:${#v}-2}"
+  fi
+  printf '%s' "$v"
+}
+
+# Resolve the optional neutral-file pointer. Sets NEUTRAL_FILE (empty when no
+# pointer is declared). A declared pointer that cannot be honored — absolute or
+# traversal path, missing file, or a dialect other than posix-ere — disables
+# enforcement (exit 1) with a diagnostic: fail closed, never fall back.
+NEUTRAL_FILE=""
+ptr="$(h2_value "$TEAM_FILE" "convention_source")"
+# Precedence: an explicit convention_source (rung 1) always wins. Absent one,
+# probe the well-known default path (rung 2) so the common case needs no pointer
+# at all; absent that too, resolution falls through to the markdown H2 (rung 3)
+# with full back-compat. The default is a plain repo-relative path and passes the
+# same safety checks below as any pointer.
+#
+# POLICY FLOOR: the well-known rung activates ONLY when the file is git-TRACKED.
+# Unlike an explicit convention_source — whose opt-in is a tracked edit to the
+# team file — this rung has no other tracked signal, so honoring an untracked or
+# gitignored file at this path would let a generated/local artifact silently
+# override team policy (or, if malformed, disable enforcement) on one checkout.
+# git unavailable, or the file untracked -> skip this rung and fall through to
+# the markdown H2 (fail toward the prior behavior, never toward the hole).
+if [[ -z "$ptr" && -f "$repo_root/$WELL_KNOWN_NEUTRAL" ]] &&
+  git -C "$repo_root" ls-files --error-unmatch -- "$WELL_KNOWN_NEUTRAL" >/dev/null 2>&1; then
+  ptr="$WELL_KNOWN_NEUTRAL"
+fi
+if [[ -n "$ptr" ]]; then
+  case "$ptr" in
+  /* | [A-Za-z]:* | *\\* | *..*)
+    # Repo-relative forward-slash paths only: no absolute paths (POSIX or
+    # drive-lettered), no backslash separators, no `..` traversal — a tracked
+    # pointer must not read outside the repository the gate governs.
+    printf '%s\n' "resolve-convention-pattern: convention_source '$ptr' is not a plain repo-relative path (absolute, backslash, or '..' segment); enforcement disabled." >&2
+    exit 1
+    ;;
+  *) ;; # plain repo-relative path — proceed
+  esac
+  NEUTRAL_FILE="$repo_root/$ptr"
+  if [[ ! -f "$NEUTRAL_FILE" ]]; then
+    printf '%s\n' "resolve-convention-pattern: convention_source declares '$ptr' but no such file exists under the repo root; enforcement disabled (fix the pointer or restore the file)." >&2
+    exit 1
+  fi
+  # The lexical checks above don't stop a symlink escape: a repo-relative
+  # pointer can name a symlink (or sit under a symlinked directory) whose
+  # physical target is outside the repository, letting untracked external
+  # content steer the gate. Require a REGULAR file whose physical directory
+  # (pwd -P canonicalizes every symlinked path segment) stays under the
+  # physical repo root. Pure-bash on purpose — the vendored hook copy cannot
+  # assume realpath exists on every consumer machine.
+  if [[ -L "$NEUTRAL_FILE" ]]; then
+    printf '%s\n' "resolve-convention-pattern: convention_source '$ptr' is a symlink; the neutral file must be a regular tracked file — enforcement disabled." >&2
+    exit 1
+  fi
+  canon_root="$(cd "$repo_root" 2>/dev/null && pwd -P)"
+  canon_dir="$(cd "$(dirname "$NEUTRAL_FILE")" 2>/dev/null && pwd -P)"
+  # Pure string-prefix test, not a glob: a `!= "$canon_root/"*` match would let a
+  # glob metacharacter in the physical repo path (`[`, `*`, `?`) be interpreted
+  # rather than compared literally. Compare the leading bytes of "$canon_dir/"
+  # against "$canon_root/" directly.
+  canon_prefix="$canon_root/"
+  canon_dir_slash="$canon_dir/"
+  if [[ -z "$canon_root" || -z "$canon_dir" || "${canon_dir_slash:0:${#canon_prefix}}" != "$canon_prefix" ]]; then
+    printf '%s\n' "resolve-convention-pattern: convention_source '$ptr' resolves outside the repository root (symlinked path segment); enforcement disabled." >&2
+    exit 1
+  fi
+  dialect="$(yaml_value "$NEUTRAL_FILE" dialect)"
+  if [[ -n "$dialect" && "$dialect" != "posix-ere" ]]; then
+    printf '%s\n' "resolve-convention-pattern: convention_source file declares dialect '$dialect'; enforcement consumes posix-ere only — enforcement disabled." >&2
+    exit 1
+  fi
+fi
+
+# A key the neutral file CARRIES must hold a value. Present-but-empty
+# (`subject_pattern:` or `subject_pattern: ''`) is a configuration error, not
+# an omission — silently falling back to the markdown H2 would enforce a stale
+# pattern the migration meant to retire. Runs at top level (not inside a
+# command substitution) so the exit reaches the caller.
+check_neutral_key() {
+  local k="$1"
+  [[ -n "$NEUTRAL_FILE" ]] || return 0
+  grep -q -E "^${k}:" "$NEUTRAL_FILE" || return 0
+  [[ -n "$(yaml_value "$NEUTRAL_FILE" "$k")" ]] && return 0
+  printf '%s\n' "resolve-convention-pattern: convention_source file carries '$k' with an empty value; a carried key must hold a value (delete the line to fall back to the markdown H2) — enforcement disabled." >&2
+  exit 1
+}
+
+# Team-layer value for a machine key: the neutral file when the pointer is
+# declared AND that file carries the key; the team markdown H2 otherwise.
+team_value() {
+  local k="$1" v
+  if [[ -n "$NEUTRAL_FILE" ]]; then
+    v="$(yaml_value "$NEUTRAL_FILE" "$k")"
+    if [[ -n "$v" ]]; then
+      printf '%s' "$v"
+      return 0
+    fi
+  fi
+  h2_value "$TEAM_FILE" "$k"
+}
+
+# Enforcement patterns are POSIX ERE, NOT PCRE. The resolver does not translate
+# a pattern (translating PCRE->ERE by string rewriting is unsound — bracket
+# expressions, POSIX classes, and escaped backslashes all break naive
+# substitution); it accepts a value that is already ERE and rejects one that
+# uses a PCRE-only construct, so a pattern the ERE engines would misread takes
+# the documented no-enforcement path instead of silently enforcing the wrong
+# thing. A team wanting a digit class writes `[0-9]`, not `\d`.
+is_non_ere() {
+  local p="$1"
+  # Any `(?...)` group — non-capturing `(?:`, lookaround `(?=`/`(?!`, named
+  # `(?<`/`(?P<`. POSIX ERE has none of these.
+  [[ "$p" == *'(?'* ]] && return 0
+  # Any backslash followed by a letter or digit: the shorthand classes
+  # \d \w \s \D \S \W, the anchors \A \Z \z \b \B, control escapes \t \n \r …,
+  # and backreferences \1..\9. POSIX ERE reads each as the literal character.
+  # A backslash before a metacharacter (`\.`, `\(`, `\+`) is valid ERE and stays
+  # allowed.
+  [[ "$p" =~ \\[a-zA-Z0-9] ]] && return 0
+  return 1
+}
+
+# Resolve one key's raw value from the team layer (neutral file first when the
+# pointer is declared — team_value), expanding the CC keyword. The keyword and
+# the deferral marker work identically on both surfaces: one literal each, no
+# per-surface variants to drift.
+raw_value() {
+  local k="$1" v
+  v="$(team_value "$k")"
+  [[ -n "$v" ]] || return 0
+  if [[ "$v" == "Conventional Commits" ]]; then
+    printf '%s' "$CC_ERE"
+  else
+    printf '%s' "$v"
+  fi
+}
+
+# Present-but-empty neutral keys fail closed BEFORE resolution (top-level so
+# the exit propagates; both keys checked for pr_title_pattern since its
+# deferral marker re-reads subject_pattern).
+check_neutral_key "$key"
+[[ "$key" == "pr_title_pattern" ]] && check_neutral_key "subject_pattern"
+
+value="$(raw_value "$key")"
+
+# pr_title_pattern deferral: `Same as `subject_pattern`.` enforces the effective
+# subject pattern. Resolve against the raw (pre-expansion) pr_title value.
+if [[ "$key" == "pr_title_pattern" ]]; then
+  raw_pr="$(team_value "pr_title_pattern")"
+  if [[ "$raw_pr" == "$PR_DEFERRAL" ]]; then
+    value="$(raw_value "subject_pattern")"
+  fi
+fi
+
+# Unresolved -> no enforcement (exit 1, stdout empty). Never fall back to CC_ERE.
+[[ -n "$value" ]] || exit 1
+
+if is_non_ere "$value"; then
+  printf '%s\n' "resolve-convention-pattern: $key is not POSIX ERE (a PCRE-only construct: a (?...) group, or a backslash-letter/backslash-digit escape such as \\d \\A \\t \\1); enforcement disabled -- author the pattern in POSIX ERE (e.g. [0-9] not \\d) to enable the gate." >&2
+  exit 1
+fi
+
+# Safety net: reject anything that still does not compile as POSIX ERE (e.g. an
+# unbalanced `^[$`) so a bad config takes the no-enforcement path, never a hook
+# that would then error or wrongly block on it. grep -E exits >=2 on an invalid
+# expression, 0/1 on a valid one.
+grep -E -- "$value" </dev/null >/dev/null 2>&1
+if (($? >= 2)); then
+  printf '%s\n' "resolve-convention-pattern: $key does not compile as POSIX ERE; enforcement disabled." >&2
+  exit 1
+fi
+
+printf '%s\n' "$value"
+exit 0
diff --git a/.githooks/guardrails/run-guards.sh b/.githooks/guardrails/run-guards.sh
new file mode 100755
index 0000000000..eae88eb4a3
--- /dev/null
+++ b/.githooks/guardrails/run-guards.sh
@@ -0,0 +1,1126 @@
+#!/usr/bin/env bash
+# Dispatcher: run several guardrails guards for ONE hook event inside ONE hook
+# process, instead of registering each guard as its own always-on hook.
+#
+#   run-guards.sh [--lib <path-under-plugin-root>]... [--max-substitutions <n>]
+#                 [--max-command-len <n>]
+#                 <guard-script>...
+#
+# Every guard named on the command line still ships as its own script with its
+# own contract test, kill switch, and telemetry envelope; nothing about a guard's
+# decision logic lives here. What this file owns is the per-event spawn shape
+# (#1403, hook-budget convention): on this fleet the per-call cost that shows
+# up as typing lag is process creation, not any one slow classifier. Eight
+# always-on Bash guards meant eight bash processes, eight parses of the shared
+# hook library, and eight jq spawns per Bash tool call. This runs them as one
+# process, and on the common payload that process spawns nothing at all.
+#
+# HOW A GUARD RUNS UNCHANGED INSIDE ONE PROCESS
+#
+#   * stdin is read and validated ONCE (hook::buffer_stdin), then every guard's
+#     own `hook::buffer_stdin` call is answered from that buffer with the same
+#     return code the guard would have seen on its own (0 payload, 1 empty,
+#     2 stalled/malformed), so each guard's fail-open / fail-closed posture on
+#     bad stdin is exercised exactly as when it runs alone.
+#   * The payload fields the guards read (`.tool_input.command`, `.tool_name`,
+#     `.cwd`, the Write/Edit content fields, ...) are extracted ONCE, by the
+#     library's builtin parser when it can prove the answer and by one jq
+#     process otherwise; `hook::jq_fields` answers from that cache when every
+#     requested filter is in it and the payload carried no NUL, and falls
+#     through to the library's own hook::jq_fields_uncached otherwise. A
+#     NUL-bearing payload therefore still reaches each guard's own NUL handling
+#     through the real jq call.
+#   * The event's command is tokenized ONCE. Six guards of the Bash row hand
+#     the same string to hook::bash_parse_segments; the first parse records
+#     every segment it reports (argv words and the HOOK_SEG_* arrays), and each
+#     later call with that string replays the record to its own callback
+#     instead of walking the string again. A parse that a callback cut short
+#     with `exit` is never recorded, so a later guard parses afresh. Any other
+#     string, including one a callback re-parses, goes to the library's own
+#     hook::bash_parse_segments_uncached.
+#   * Each guard is `source`d in THIS shell, not in a subshell: on Windows Git
+#     Bash every fork is a Win32 process creation, so eight command-substitution
+#     subshells were eight processes per tool call. A sourced guard ends by
+#     calling `exit`, which here is a shell function: it records the guard's
+#     status and unwinds the guard, so the chain never returns into a guard
+#     that has exited. A guard that falls off its end
+#     returns from `source` and is recorded the same way. Inside a real subshell
+#     (`$(...)`, `( )`, a pipeline, `&`) the function sees a different BASHPID
+#     and exits that subshell as the builtin would. Its `source hook-utils.sh`
+#     returns at once on the library's double-source guard, so the overrides
+#     stay in force; `BASH_SOURCE[0]` is the guard's own path, so sibling
+#     libraries resolve as before. stderr passes straight through, unbuffered.
+#   * A guard's stdout is a hook JSON document, and every document a guard
+#     emits goes through hook::emit_document (hook::emit_channels included).
+#     That one function is overridden here to collect the documents; nothing
+#     is captured from the process's stdout. A guard that printed a document
+#     with its own printf would bypass the collection: keep to the helper.
+#   * A guard's abort boundary (abort-boundary.sh) still decides what a status
+#     the guard did not choose means. When the guard ends through `exit` or by
+#     falling off its end, guard::_abort_settle is applied to its status here,
+#     and the notice document it builds joins the collected output. When the
+#     guard dies of a hard error (an unbound variable under `set -u`, a failed
+#     `source`), the shell itself is exiting and bash runs the guard's EXIT
+#     trap, which is this file's handler: the same settle, and the guards that
+#     have not run yet run in ONE subshell from inside that handler, because a
+#     second hard error in a dying shell would end the process with no result.
+#     That subshell reports its documents and status back on its stdout; a
+#     further hard error there costs one more subshell, never the result.
+#   * `exit` does not run the next guard from inside its own call: that would
+#     keep the exiting guard's frames on the stack under every later guard, and
+#     a guard that exits deep (the alias walk's budget deny is about 140 frames
+#     down) leaves too little stack for the rest of the chain on a small one,
+#     where the crash loses the guard's exit 2 (Git Bash reads it as exit 0).
+#     `exit` records the status and unwinds the guard back to the dispatcher's
+#     loop instead. A guard that exited past RUN_GUARDS_MAX_DEPTH frames, and a
+#     guard that dies of a hard error (the rest runs from its EXIT trap), hand
+#     the rest of the chain to a forked process, which reports back the same
+#     way, so a later guard that runs out of stack cannot take the verdict so
+#     far with it. A rest that reports no status denies the call.
+#   * Guards share one process, so a guard's functions and globals remain
+#     defined while the later guards run. Every guard
+#     assigns what it reads before it reads it; a guard must not read a global
+#     it did not set expecting it unset.
+#
+# AGGREGATION (the one deliberate delta from N separate hooks)
+#
+#   * Exit: 2 if any guard exited 2 (block); else the highest non-zero code any
+#     guard returned; else 0. Every guard runs even after one has blocked, so a
+#     command that trips two guards still shows both reasons, as it did when
+#     the guards were separate hooks.
+#   * Substitution count: with `--max-substitutions <n>`, a command holding
+#     more than <n> command or process substitutions exits 2 before the first
+#     guard is sourced, and no guard runs. The count is lexical: each `$(`
+#     (arithmetic `$((` included), `<(` and `>(` is one, and backticks count
+#     in pairs. The cost of reading a command is spread across the guards and
+#     grows with this count while every per-command cap still holds: 2,339
+#     sibling `$(: rm)` in 16,378 characters measured 65 s through the chain
+#     on Windows, and a row that runs past its hooks.json `timeout` cannot
+#     be counted on to block. Relay: the pointer record is under Over-length
+#     below. As of: 2026-10-11. Recheck trigger: that record leaves the
+#     Over-length entry, or its own recheck trigger fires. No
+#     guard sees the whole chain's time, which is why the cap
+#     lives here. An unprimed payload is counted whole, which no command
+#     inside it can exceed.
+#     For the Bash tool, a spelling inside a single-quoted span does not
+#     count: bash substitutes nothing there, and the guards read the span as
+#     one quoted word, so it costs close to the same text without the
+#     spelling and far below the unquoted cost. Nor does one in the body of a
+#     heredoc whose delimiter is quoted (`<<'EOF'`, `<<"EOF"`, `<<\EOF`,
+#     `<<-'EOF'`): bash expands nothing there and the library skips it.
+#     block-root-delete-target's substitution scan still reads such a body as
+#     commands unless the whole command is one `cat` or `gh` line feeding it
+#     (#6625). A body
+#     that gives it no work to judge (`$(: rm)`) never starts
+#     its RDT_DEADLINE, so --max-command-len is what bounds the cost: about
+#     1.1 ms per spelling, 2.6 to 3.7 s measured at 16,384 characters. A
+#     change to that length or to the guard set changes this bound. Everything
+#     else counts as before, including double-quoted text, ANSI-C `$'...'` and
+#     unquoted heredoc bodies. The discount is taken only where it is proved.
+#     The scan runs only on a command already past the cap, and from the
+#     first place bash, hook::bash_parse_segments and that scan could read the
+#     rest differently, the rest counts whole: a backtick outside a span;
+#     `$(`, `${` or `$[` inside double quotes; an unquoted heredoc, or a
+#     quoted one the scan does not model (counted_text below lists them);
+#     a single-quoted span after a heredoc body, whose quotes the root-delete
+#     scan reads; `$'` or `$$'`; a comment holding a quote; a quote that never
+#     closes; a span after `\$`, or after `((`, `[` or `{` (arithmetic, where
+#     bash expands `$(` in quotes); past 1024 scan steps. The whole command counts when it names a command a
+#     guard re-parses an argument of (`eval`, a shell, `su`, `runuser`, `sg`,
+#     `env`, `flock`, `wsl`), runs a file as shell (`source`, `. file`) or
+#     holds `alias`. A command past
+#     --max-command-len is not scanned; the guards refuse it unread.
+#     PowerShell commands are counted as text, quotes and here-strings
+#     included.
+#   * Over-length: with `--max-command-len <n>`, a command longer than <n>
+#     characters ends the chain at the first guard that blocks, and the
+#     remaining guards do not run. <n> is the MAX_COMMAND_LEN ceiling the row's
+#     guards share (run-guards.test.sh holds the two equal), above which they
+#     refuse a command unread. A guard with no ceiling that tokenizes would
+#     parse the whole command only to add a reason to a block already
+#     decided, and a row that runs past its hooks.json `timeout` loses its
+#     block, so a stalled guard is no gate. What Claude Code does with a
+#     timed-out PreToolUse command hook is the hooks page's to state; our
+#     hooks.json rows set no failure-handling field, so they take the page's
+#     default. Pointer: https://code.claude.com/docs/en/hooks#timeouts. As of:
+#     2026-10-11. Recheck trigger: that section changes what a timed-out
+#     PreToolUse command hook does to its tool call or its default failure
+#     handling, or is renamed.
+#     #4528 measured a ~70 KB command still running at 120 s.
+#     Each guard keeps its own kill switch: a disabled guard exits before its
+#     ceiling, so the next enabled ceiling guard is the one that blocks. An
+#     unprimed payload is measured by its own length, which no command inside
+#     it can exceed.
+#   * stdout: one emitter passes through verbatim. Several are merged into one
+#     document (contexts joined by a blank line; a `permissionDecision` kept,
+#     deny over ask, with the reasons of the guards that chose it joined; an
+#     exit 2 from any guard still denies the call) because a hook process gets
+#     one JSON document on stdout; as separate hooks each document was
+#     delivered on its own. Pointer:
+#     https://code.claude.com/docs/en/hooks#json-output. As of: 2026-10-11.
+#     Recheck trigger: that section starts accepting more than one JSON object
+#     on a hook's stdout, or is renamed. When jq is absent, or the merge fails,
+#     the documents are never concatenated (two documents on stdout is invalid
+#     hook output): the one carrying a blocking decision (`"decision":"block"`,
+#     `"permissionDecision":"deny"`, then `"ask"`) is emitted, else the first,
+#     and every dropped document is echoed to stderr with a `run-guards:`
+#     prefix so it stays visible in debug output. On a block it is not:
+#     exit-2 stderr is the model's deny reason.
+#   * Shared refusals: the jq-missing denial, the NUL and unparsable-payload
+#     refusals and the PowerShell sink message are printed once per call, by
+#     the first guard that makes them (guard::say_once, abort-boundary.sh).
+#
+# The overrides are scoped to this process: a guard run directly (its tests,
+# `bash hooks/<guard>.sh`) uses the library functions untouched.
+
+set -uo pipefail
+
+# Do NOT define a function named `dirname`. A function of that name would be
+# inherited by every guard sourced below and shadow the real command, with an
+# answer that diverges from GNU for `/foo` (empty, not `/`) and for `/a/b//`
+# (`/a/b`, not `/a`). Each guard's own `dirname` therefore stays the real one.
+#
+# The dispatcher's own directory is derived with parameter expansion rather than
+# `dirname` or `$(helper)`. GNU Bash forks a subshell for every command
+# substitution even when the body is only builtins (Command Substitution, Bash
+# Reference Manual; https://mywiki.wooledge.org/CommandSubstitution). On Windows
+# Git Bash that fork is a process. `${BASH_SOURCE[0]%/*}` equals `dirname`
+# for every shape BASH_SOURCE takes; the fallback covers a bare filename, where
+# the strip is a no-op and dirname answers `.`. Claude Code (and this suite)
+# invoke with an absolute path, so the strip is already absolute; `cd && pwd`
+# is kept only for a relative spelling.
+_RG_DIR="${BASH_SOURCE[0]%/*}"
+[[ "$_RG_DIR" == "${BASH_SOURCE[0]}" ]] && _RG_DIR=.
+# shellcheck source=abort-boundary.sh
+source "$_RG_DIR/abort-boundary.sh"
+# Could-not-run posture (#3528): fail-open with a visible notice. This covers
+# the dispatcher's own code, before and after the guards: stdin, the field
+# priming, the classifier load, the merge. An abort here would otherwise skip
+# EVERY guard of the event with a bare status and no line of its own. The
+# event is filled in once the payload is read (it names the additionalContext
+# block; until then the notice is systemMessage only), and the trap is
+# released right before the deliberate aggregated exit, so a non-block status
+# a guard returned still surfaces exactly as it did.
+guard::abort_boundary run-guards "" open 0 2
+# shellcheck source=hook-utils.sh
+source "$_RG_DIR/hook-utils.sh" || exit 70 # not a chosen status: the boundary reports it
+
+case "$_RG_DIR" in
+/* | ?:[/\\]*) HOOK_DIR="$_RG_DIR" ;;
+*) HOOK_DIR="$(cd "$_RG_DIR" && pwd)" ;;
+esac
+
+RUN_GUARDS_START=${EPOCHREALTIME:-}
+GUARDS=()
+LIBS=()
+# The options as given, for a fresh process that runs the rest of the chain
+# (run_guards::run_rest).
+RUN_GUARDS_OPTS=()
+RUN_GUARDS_MAX_SUBST=0
+RUN_GUARDS_MAX_CMD=0
+RUN_GUARDS_REPORT=0
+while (($#)); do
+  case "$1" in
+  --max-substitutions)
+    [[ "${2-}" =~ ^[1-9][0-9]*$ ]] || exit 70 # not a chosen status: the boundary reports it
+    RUN_GUARDS_MAX_SUBST=$2
+    RUN_GUARDS_OPTS+=("$1" "$2")
+    shift 2
+    ;;
+  --max-command-len)
+    [[ "${2-}" =~ ^[1-9][0-9]*$ ]] || exit 70 # not a chosen status: the boundary reports it
+    RUN_GUARDS_MAX_CMD=$2
+    RUN_GUARDS_OPTS+=("$1" "$2")
+    shift 2
+    ;;
+  --report)
+    # Internal: this process runs the rest of a parent's chain. Report the
+    # documents and status on stdout (run_guards::finish) and say nothing the
+    # parent already said (guard::say_once).
+    RUN_GUARDS_REPORT=1
+    _GUARD_SAID="${2-}"
+    shift 2
+    ;;
+  --lib)
+    # A library several guards source (the PowerShell classifier). Collect
+    # the path now; the parse itself waits until tool_name is known. On a
+    # Bash payload the classifier's first real statement is
+    # `[[ "$tool" == "PowerShell" ]] || return 0`, so loading ~41 KB here
+    # was a pure tax on the common path. The include guard still makes every
+    # later `source` a no-op, so the parse is paid once per PowerShell fire.
+    LIBS+=("$2")
+    RUN_GUARDS_OPTS+=("$1" "$2")
+    shift 2
+    ;;
+  *)
+    GUARDS+=("$1")
+    shift
+    ;;
+  esac
+done
+((${#GUARDS[@]})) || exit 0
+
+# --- stdin once, fields once --------------------------------------------------
+RUN_GUARDS_PRIMED=0
+declare -A RUN_GUARDS_FIELD=()
+# The union of every field the guards of this plugin declared in
+# hooks/guard-requires.sh, which is where a guard states what it consumes.
+# This array is that declaration's PROJECTION, not a second opinion about it:
+# run-guards.test.sh derives the union from the declaration and fails when the
+# two disagree, in either direction.
+#
+# Both directions cost. The cached hook::jq_fields below is all-or-nothing per
+# call, so ONE declared field missing here sends every call of that lane to an
+# uncached extraction — `.tool_input.path` (the GitHub MCP write lane's file
+# path) was measured doing exactly that, two extra spawns per Write/Edit,
+# 50 ms to 60 ms on the reference host. A field here that no guard declares is
+# the opposite: parse work on every payload of every lane that nothing reads.
+PRIME_FILTERS=(
+  '.tool_input.command' '.tool_name' '.cwd'
+  '.tool_input.file_path' '.tool_input.notebook_path' '.tool_input.path'
+  '.tool_input.content' '.tool_input.new_string' '.tool_input.new_source'
+  '.hook_event_name'
+)
+
+# Fused capture: GNU Bash forks a subshell for INPUT=$(hook::buffer_stdin)
+# even when the body is builtins (Command Substitution;
+# https://mywiki.wooledge.org/CommandSubstitution). Passing PRIME_FILTERS
+# makes the completeness check and the field extract one step: the library's
+# builtin parser on the common payload, one jq process on one it cannot prove.
+#
+# Dest is initialized here so ShellCheck SC2154 sees the assignment.
+# printf -v through a nameref inside hook::buffer_stdin_to is a dynamic
+# assignment the checker does not track
+# (https://www.shellcheck.net/wiki/SC2154, Exceptions: "explicitly
+# initialize/declare it with var="" or declare var").
+RUN_GUARDS_INPUT=""
+RUN_GUARDS_STDIN_RC=0
+hook::buffer_stdin_to RUN_GUARDS_INPUT "${PRIME_FILTERS[@]}" || RUN_GUARDS_STDIN_RC=$?
+# Nothing arrived: every guard would take its empty-stdin skip. Take it once.
+((RUN_GUARDS_STDIN_RC == 1)) && exit 0
+# The payload was cut short at EOF (rc 3): a transport fault, so every guard
+# would skip with the same notice. Say it once and stop. The event name is
+# not known here (this dispatcher is wired under PreToolUse and PostToolUse
+# alike), so the notice goes out on systemMessage and stderr only; a guard
+# run alone adds the agent channel itself. This exit precedes every guard,
+# which is why the lib keeps rc 3 to the early-EOF arm only: a stall on the
+# same prefix is rc 2, falls through here, and every blocking guard denies
+# on it.
+if ((RUN_GUARDS_STDIN_RC == 3)); then
+  hook::stdin_cut_short_notice "" "guardrails"
+  exit 0
+fi
+
+# shellcheck disable=SC2329  # invoked by every guard sourced below
+hook::buffer_stdin() {
+  ((RUN_GUARDS_STDIN_RC == 0)) || return "$RUN_GUARDS_STDIN_RC"
+  printf '%s' "$RUN_GUARDS_INPUT"
+}
+
+# shellcheck disable=SC2329  # invoked by every guard sourced below
+hook::buffer_stdin_to() {
+  # `__rg_dest`, not `dest`: an unprefixed local would collide with a guard
+  # that called `hook::buffer_stdin_to dest` and `printf -v` would write
+  # this frame's local, return 0, and leave the guard's dest unset
+  # (the `_to` helper convention at lib/hook-utils.sh).
+  local __rg_dest="$1"
+  ((RUN_GUARDS_STDIN_RC == 0)) || return "$RUN_GUARDS_STDIN_RC"
+  printf -v "$__rg_dest" '%s' "$RUN_GUARDS_INPUT"
+}
+
+if ((RUN_GUARDS_STDIN_RC == 0)) &&
+  ((${#HOOK_JQ_FIELDS[@]} == ${#PRIME_FILTERS[@]})) &&
+  ((HOOK_JQ_FIELDS_NUL == 0)); then
+  RUN_GUARDS_PRIMED=1
+  # The primed values are keyed by the FILTER that produced them, so every
+  # later read is by name. A position is not a name: a filter added ahead of
+  # another silently hands its neighbor's value to whatever read the index,
+  # and nothing at run time says so. The dispatcher itself reads two of these
+  # (`.tool_name` below, `.hook_event_name` here); abort-boundary.test.sh
+  # inserts a filter ahead of them on a copy and checks both still resolve.
+  for _rg_i in "${!PRIME_FILTERS[@]}"; do
+    RUN_GUARDS_FIELD["${PRIME_FILTERS[_rg_i]}"]="${HOOK_JQ_FIELDS[_rg_i]}"
+  done
+  unset _rg_i
+  # The event name rides in the same extraction and lets the dispatcher's own
+  # abort notice name the event.
+  [[ "${RUN_GUARDS_FIELD['.hook_event_name']-}" =~ ^[A-Za-z]+$ ]] &&
+    _GAB_EVENT="${RUN_GUARDS_FIELD['.hook_event_name']}"
+fi
+
+# Substitution count (AGGREGATION above). Parameter expansion, not a loop over
+# characters: one pass per spelling, and nothing forks.
+run_guards::count_subst() { # <text> -> _rg_subst
+  local t="$1" rest pat
+  _rg_subst=0
+  # shellcheck disable=SC2016  # literal spellings, matched as text
+  for pat in '$(' '<(' '>('; do
+    rest=${t//"$pat"/}
+    _rg_subst=$((_rg_subst + (${#t} - ${#rest}) / 2))
+  done
+  rest=${t//'`'/}
+  _rg_subst=$((_rg_subst + (${#t} - ${#rest} + 1) / 2))
+}
+
+# The text of a Bash command whose spellings count: the command with each
+# single-quoted span replaced by its last path component when that could be a
+# command name, else by one space, and the body of each heredoc whose
+# delimiter is quoted dropped. Each [[ =~ ]] jumps to the next character
+# that can change how the rest reads, so the passes grow with the quotes,
+# escapes and `$`, not the length, and nothing forks. A single-quoted span is
+# discounted only where bash, hook::bash_parse_segments and
+# block-root-delete-target's own substitution scan all read it as quoted, a
+# heredoc body only where bash and the library end it on the same line, and
+# neither where a guard re-reads it as a command; elsewhere the rest of the
+# command, or all of it, counts (AGGREGATION above lists where).
+# shellcheck disable=SC2016,SC1003  # regexes and literal spellings, not expansions
+run_guards::counted_text() { # <command> -> _rg_counted
+  local LC_ALL=C rest="$1" out="" m d t re_end ws=1 dq=0 br=0 hd=0 n=0
+  local nl=$'\n' tab=$'\t'
+  local re_plain='^[^'\''"\`$<#]*' re_dq='^[^"\$`]*' re_sq="^'([^']*)'"
+  local re_cmt="^#[^$nl]*" re_base='[/\]([^/\]*)$' re_name='^[a-zA-Z0-9_.+-]*$'
+  # `<<` or `<<-`, a delimiter word of letters, digits and `_`, each part bare,
+  # single- or double-quoted or backslashed, and the rest of its line.
+  local w='[a-zA-Z0-9_]'
+  local re_hd="^<<(-?)[ $tab]*(($w|'$w*'|\"$w*\"|\\\\$w)+)([ $tab;&|>][^'\"\`\\\$#<()$nl]*)?$nl"
+  # The words hook::shell_c_operand, eval and the root-delete guard's
+  # launcher arms (su, runuser, sg, env -S, flock -c) re-parse an argument of.
+  local re_reparse='(^|[^a-z0-9_.-])(eval|source|bash|sh|zsh|dash|ksh|mksh|wsl|su|runuser|sg|env|flock)([^a-z0-9_-]|$)'
+  # `. file` runs `file` (`. /dev/stdin <<'EOF'`) as `source` does. A `.` the
+  # shell may split from its operand (`.$IFS/dev/stdin`, `.${IFS}x`, `` .`cmd` ``)
+  # counts too.
+  local re_dot="(^|[^a-z0-9_.-])\\.([ $tab{\`\$]|\$)"
+  _rg_counted=$1
+  # A git alias definition (`-c alias.x='!…'`) is re-parsed by the git guards.
+  m=${1,,}
+  [[ $m == *alias* ]] && return 0
+  while [[ -n $rest ]] && ((++n <= 1024)); do
+    # Inside "...": counted, scanned only to find where it closes.
+    if ((dq)); then
+      [[ $rest =~ $re_dq ]]
+      out+=${BASH_REMATCH[0]}
+      rest=${rest:${#BASH_REMATCH[0]}}
+      case $rest in
+      '"'*)
+        out+='"'
+        rest=${rest:1}
+        dq=0
+        ;;
+      '\'?*)
+        out+=${rest:0:2}
+        rest=${rest:2}
+        ;;
+      # A substitution inside "..." opens a context the library does not
+      # model: it ends the string at the first `"`, bash at the matching one.
+      '$('* | '${'* | '$['*) break ;;
+      '$'?*)
+        out+='$'
+        rest=${rest:1}
+        ;;
+      *) break ;;
+      esac
+      continue
+    fi
+    [[ $rest =~ $re_plain ]]
+    m=${BASH_REMATCH[0]}
+    if [[ -n $m ]]; then
+      out+=$m
+      rest=${rest:${#m}}
+      # `((`, `[` (`$((`, `$[` and a subscript) and `{` (`${x:offset}`) may
+      # open arithmetic, where bash expands `$(` inside single quotes.
+      [[ $m == *[\[\{]* || $m == *'(('* ]] && br=1
+      [[ -n $rest ]] || break
+      case ${m: -1} in
+      [$' \t\n;&|()>']) ws=1 ;;
+      *) ws=0 ;;
+      esac
+    fi
+    case $rest in
+    "'"*)
+      # After `\$` the root-delete scan reads an ANSI-C span, whose `\'` does
+      # not close it.
+      ((br == 0 && hd == 0)) && [[ $out != *'$' && $rest =~ $re_sq ]] || break
+      m=${BASH_REMATCH[1]}
+      rest=${rest:$((${#m} + 2))}
+      # Its last path component stays when it could name a command, so a
+      # shell spelled in quotes (`'/bin/bash'`, `b'ash'`) is still caught below.
+      [[ $m =~ $re_base ]] && m=${BASH_REMATCH[1]}
+      if [[ $m =~ $re_name ]]; then out+=$m; else out+=' '; fi
+      ws=0
+      ;;
+    '"'*)
+      out+='"'
+      rest=${rest:1}
+      dq=1
+      ws=0
+      ;;
+    '\'?*)
+      # A backslash-newline is removed, so it leaves a word start standing.
+      [[ ${rest:1:1} == "$nl" ]] || ws=0
+      out+=${rest:0:2}
+      rest=${rest:2}
+      ;;
+    '\')
+      out+=$rest
+      rest=""
+      ;;
+    # An ANSI-C span: `$$'` is `$$` then a single-quoted span to bash and an
+    # ANSI-C span to the library.
+    "\$'"* | "\$\$'"*) break ;;
+    '$$'*)
+      out+='$$'
+      rest=${rest:2}
+      ws=0
+      ;;
+    '$'*)
+      out+='$'
+      rest=${rest:1}
+      ws=0
+      ;;
+    '<<<'*)
+      out+='<<<'
+      rest=${rest:3}
+      ws=1
+      ;;
+    # A heredoc whose delimiter is quoted: its body is stdin bash does not
+    # expand, so it is dropped, and the operator, the word and the rest of its
+    # line stay. The body starts after that line and ends at the first line
+    # equal to the delimiter (leading tabs stripped for `<<-`). The rest counts
+    # whole from here when the delimiter is unquoted, empty or more than
+    # letters, digits and `_` under quoting; when the rest of the line holds a
+    # quote, `\`, `$`, `#`, `<`, `(` or `)` (a second heredoc, a substitution,
+    # a continued line); when arithmetic or a substitution may enclose it; or
+    # when no terminator line follows.
+    '<<'*)
+      ((br == 0)) && [[ $out != *['$<>']'('* && $rest =~ $re_hd ]] || break
+      m=${BASH_REMATCH[0]}
+      d=${BASH_REMATCH[2]//[\'\"\\]/}
+      [[ -n $d && $d != "${BASH_REMATCH[2]}" ]] || break
+      re_end=$nl
+      [[ -n ${BASH_REMATCH[1]} ]] && re_end+="$tab*"
+      re_end+=$d$nl
+      # A newline is added so the terminator line always ends in one.
+      t=$nl${rest:${#m}}$nl
+      [[ $t =~ $re_end ]] || break
+      out+=$m
+      m=${t%%"${BASH_REMATCH[0]}"*}
+      rest=${t:$((${#m} + ${#BASH_REMATCH[0]}))}
+      rest=${rest%"$nl"}
+      ws=1
+      # The root-delete scan reads the body's quotes as quotes, so a later
+      # single-quoted span may be open code to it.
+      hd=1
+      ;;
+    '<'*)
+      out+='<'
+      rest=${rest:1}
+      ws=1
+      ;;
+    '#'*)
+      if ((ws)); then
+        # bash and the library skip a comment; the root-delete scan reads a
+        # quote in it as one.
+        [[ $rest =~ $re_cmt && ${BASH_REMATCH[0]} != *[\'\"\`]* ]] || break
+        out+=${BASH_REMATCH[0]}
+        rest=${rest:${#BASH_REMATCH[0]}}
+      else
+        out+='#'
+        rest=${rest:1}
+      fi
+      ;;
+    # A backtick: bash re-reads its body under its own backslash rules.
+    *) break ;;
+    esac
+  done
+  # With each `\` kept (a boundary, as in `C:\…\bash.exe`) and removed
+  # (`ev\al`).
+  m=$out$rest
+  m=${m//\"/}
+  m=${m,,}
+  [[ $m =~ $re_reparse || ${m//\\/} =~ $re_reparse || $m =~ $re_dot ]] || _rg_counted=$out$rest
+}
+
+if ((RUN_GUARDS_MAX_SUBST && RUN_GUARDS_STDIN_RC == 0)); then
+  if ((RUN_GUARDS_PRIMED)); then
+    _rg_text="${RUN_GUARDS_FIELD['.tool_input.command']-}"
+  else
+    _rg_text=$RUN_GUARDS_INPUT
+  fi
+  _rg_data=""
+  run_guards::count_subst "$_rg_text"
+  # The quote-aware recount runs only for a Bash command already past the cap
+  # that holds a single quote or a heredoc, and not for one past
+  # --max-command-len, which the guards refuse unread.
+  if ((_rg_subst > RUN_GUARDS_MAX_SUBST && RUN_GUARDS_PRIMED)) &&
+    [[ "${RUN_GUARDS_FIELD['.tool_name']-}" == Bash && ($_rg_text == *"'"* || $_rg_text == *'<<'*) ]] &&
+    ! ((RUN_GUARDS_MAX_CMD && ${#_rg_text} > RUN_GUARDS_MAX_CMD)); then
+    run_guards::counted_text "$_rg_text"
+    run_guards::count_subst "$_rg_counted"
+    unset _rg_counted
+  fi
+  unset _rg_text
+  unset -f run_guards::count_subst run_guards::counted_text
+  if ((_rg_subst > RUN_GUARDS_MAX_SUBST)); then
+    echo "BLOCKED: $_rg_subst command or process substitutions, over the $RUN_GUARDS_MAX_SUBST the guards can check in time. Split the command, or run the work from a script file." >&2
+    if hook::telemetry_enabled; then
+      hook::json_str_object_to _rg_data tool "${RUN_GUARDS_FIELD['.tool_name']-}" form "too-many-substitutions" count "$_rg_subst"
+      hook::emit_telemetry run-guards "${_GAB_EVENT:-PreToolUse}" blocked "$RUN_GUARDS_START" "$_rg_data" "${CLAUDE_PROJECT_DIR:-}"
+    fi
+    exit 2
+  fi
+  unset _rg_subst _rg_data
+fi
+
+# Over-length (AGGREGATION above). Measured in this shell's locale, as each
+# guard measures its own ${#COMMAND}.
+RUN_GUARDS_OVERLONG=0
+if ((RUN_GUARDS_MAX_CMD && RUN_GUARDS_STDIN_RC == 0)); then
+  if ((RUN_GUARDS_PRIMED)); then
+    _rg_cmd="${RUN_GUARDS_FIELD['.tool_input.command']-}"
+    ((${#_rg_cmd} > RUN_GUARDS_MAX_CMD)) && RUN_GUARDS_OVERLONG=1
+    unset _rg_cmd
+  elif ((${#RUN_GUARDS_INPUT} > RUN_GUARDS_MAX_CMD)); then
+    RUN_GUARDS_OVERLONG=1
+  fi
+fi
+
+# The cache in front of the library's extractor. The miss path is the
+# library's own function under its second name, so nothing is copied here.
+# shellcheck disable=SC2329  # invoked by every guard sourced below
+hook::jq_fields() {
+  local input="$1"
+  shift
+  (($#)) || return 1
+  if ((RUN_GUARDS_PRIMED)) && [[ "$input" == "$RUN_GUARDS_INPUT" ]]; then
+    local -a out=()
+    local filter
+    for filter in "$@"; do
+      # `+x`, not a non-empty test: a primed field whose value is the empty
+      # string is served, not treated as a miss.
+      [[ -n "${RUN_GUARDS_FIELD[$filter]+x}" ]] || break
+      out+=("${RUN_GUARDS_FIELD[$filter]}")
+    done
+    if ((${#out[@]} == $#)); then
+      HOOK_JQ_FIELDS=("${out[@]}")
+      HOOK_JQ_FIELDS_NUL=0
+      return 0
+    fi
+  fi
+  hook::jq_fields_uncached "$input" "$@" || return
+  # A miss on the event's own payload joins the cache, so a later guard asking
+  # for the same unprimed filter (stale-path-verify's `replace_all` after
+  # skill-reference-verify's) is answered without a second jq. Only a clean
+  # answer is kept: status 0 and no NUL in the values.
+  if ((RUN_GUARDS_PRIMED && HOOK_JQ_FIELDS_NUL == 0)) && [[ "$input" == "$RUN_GUARDS_INPUT" ]]; then
+    local __rg_i=0 __rg_f
+    for __rg_f in "$@"; do
+      RUN_GUARDS_FIELD["$__rg_f"]="${HOOK_JQ_FIELDS[__rg_i]}"
+      __rg_i=$((__rg_i + 1))
+    done
+  fi
+  return 0
+}
+
+# The file path and the repository root, each resolved once per event. The
+# PostToolUse verifiers all read `.tool_input.file_path` through
+# hook::read_file_path_to and then ask hook::repo_root_to about its directory:
+# three payload parses, three realpath processes and up to three git processes
+# for one answer each. The first call resolves through the library's uncached
+# twin and the rest are served from here, with the same status and the same
+# HOOK_REPO_ROOT_UNRESOLVED. Nothing a guard does between those calls moves
+# the file, the project dir or the repository (the verifiers read, never
+# write). A payload other than the event's own, or a changed scope setting,
+# misses and takes the uncached path.
+RUN_GUARDS_RFP_KEY=""
+RUN_GUARDS_RFP_RC=""
+RUN_GUARDS_RFP_VAL=""
+# shellcheck disable=SC2329  # invoked by every guard sourced below
+hook::read_file_path_to() {
+  local __rg_key="${CLAUDE_PROJECT_DIR-}|${HOOK_READ_FILE_PATH_UNSCOPED:-0}" __rg_val="" __rg_rc=0
+  if (($# != 2)) || [[ "$2" != "$RUN_GUARDS_INPUT" ]]; then
+    hook::read_file_path_uncached_to "$@"
+    return
+  fi
+  if [[ -z "$RUN_GUARDS_RFP_RC" || "$__rg_key" != "$RUN_GUARDS_RFP_KEY" ]]; then
+    hook::read_file_path_uncached_to __rg_val "$2" || __rg_rc=$?
+    RUN_GUARDS_RFP_KEY=$__rg_key
+    RUN_GUARDS_RFP_RC=$__rg_rc
+    RUN_GUARDS_RFP_VAL=$__rg_val
+  fi
+  ((RUN_GUARDS_RFP_RC == 0)) || return "$RUN_GUARDS_RFP_RC"
+  printf -v "$1" '%s' "$RUN_GUARDS_RFP_VAL"
+}
+
+RUN_GUARDS_RR_KEY=""
+RUN_GUARDS_RR_RC=""
+RUN_GUARDS_RR_VAL=""
+RUN_GUARDS_RR_UNRESOLVED=""
+# shellcheck disable=SC2329,SC2034  # invoked by the guards; HOOK_REPO_ROOT_UNRESOLVED is their contract
+hook::repo_root_to() {
+  # The working directory is part of the key: a relative hint resolves against it.
+  local __rg_hint="${2:-.}" __rg_key="$PWD|${2:-.}" __rg_val="" __rg_rc=0
+  if [[ -z "$RUN_GUARDS_RR_RC" || "$__rg_key" != "$RUN_GUARDS_RR_KEY" ]]; then
+    hook::repo_root_uncached_to __rg_val "$__rg_hint" || __rg_rc=$?
+    RUN_GUARDS_RR_KEY=$__rg_key
+    RUN_GUARDS_RR_RC=$__rg_rc
+    RUN_GUARDS_RR_VAL=$__rg_val
+    RUN_GUARDS_RR_UNRESOLVED=$HOOK_REPO_ROOT_UNRESOLVED
+  fi
+  HOOK_REPO_ROOT_UNRESOLVED=$RUN_GUARDS_RR_UNRESOLVED
+  printf -v "$1" '%s' "$RUN_GUARDS_RR_VAL"
+  return "$RUN_GUARDS_RR_RC"
+}
+
+# One tokenization per event (HOW above). The record is one string's parse,
+# as flat arrays: per segment its argv count and redirection count, then the
+# words, their HOOK_SEG_WORD_QUOTED flags and the five HOOK_SEG_REDIR_* arrays
+# end to end. Only an outermost call records or stores, so a callback's
+# re-parse of a substring cannot evict the event's command; the depth is reset
+# before each guard, because a guard's `exit` inside a callback never unwinds
+# it.
+RUN_GUARDS_BPS_HAVE=0
+RUN_GUARDS_BPS_KEY=""
+RUN_GUARDS_BPS_DEPTH=0
+RUN_GUARDS_BPS_ARGC=()
+RUN_GUARDS_BPS_REDC=()
+RUN_GUARDS_BPS_WORDS=()
+RUN_GUARDS_BPS_WQ=()
+RUN_GUARDS_BPS_ROP=()
+RUN_GUARDS_BPS_RFD=()
+RUN_GUARDS_BPS_RTGT=()
+RUN_GUARDS_BPS_RQ=()
+RUN_GUARDS_BPS_ROPQ=()
+
+# shellcheck disable=SC2329  # invoked by every guard sourced below
+hook::bash_parse_segments() {
+  if ((RUN_GUARDS_BPS_HAVE)) && [[ "$1" == "$RUN_GUARDS_BPS_KEY" ]]; then
+    run_guards::bps_replay "$2"
+    return 0
+  fi
+  if ((RUN_GUARDS_BPS_DEPTH)); then
+    hook::bash_parse_segments_uncached "$@"
+    return
+  fi
+  local __rg_bps_cb="$2"
+  local -a __rg_bps_argc=() __rg_bps_redc=() __rg_bps_words=() __rg_bps_wq=()
+  local -a __rg_bps_rop=() __rg_bps_rfd=() __rg_bps_rtgt=() __rg_bps_rq=() __rg_bps_ropq=()
+  RUN_GUARDS_BPS_DEPTH=1
+  hook::bash_parse_segments_uncached "$1" run_guards::bps_record
+  RUN_GUARDS_BPS_DEPTH=0
+  RUN_GUARDS_BPS_KEY=$1
+  RUN_GUARDS_BPS_ARGC=(${__rg_bps_argc[@]+"${__rg_bps_argc[@]}"})
+  RUN_GUARDS_BPS_REDC=(${__rg_bps_redc[@]+"${__rg_bps_redc[@]}"})
+  RUN_GUARDS_BPS_WORDS=(${__rg_bps_words[@]+"${__rg_bps_words[@]}"})
+  RUN_GUARDS_BPS_WQ=(${__rg_bps_wq[@]+"${__rg_bps_wq[@]}"})
+  RUN_GUARDS_BPS_ROP=(${__rg_bps_rop[@]+"${__rg_bps_rop[@]}"})
+  RUN_GUARDS_BPS_RFD=(${__rg_bps_rfd[@]+"${__rg_bps_rfd[@]}"})
+  RUN_GUARDS_BPS_RTGT=(${__rg_bps_rtgt[@]+"${__rg_bps_rtgt[@]}"})
+  RUN_GUARDS_BPS_RQ=(${__rg_bps_rq[@]+"${__rg_bps_rq[@]}"})
+  RUN_GUARDS_BPS_ROPQ=(${__rg_bps_ropq[@]+"${__rg_bps_ropq[@]}"})
+  RUN_GUARDS_BPS_HAVE=1
+}
+
+# The recording callback: copy the segment before the guard's own callback
+# sees it, since that callback may re-parse and overwrite HOOK_SEG_*. Reads
+# the recording hook::bash_parse_segments frame's locals through dynamic scope.
+# shellcheck disable=SC2329  # invoked as the parse callback above
+run_guards::bps_record() {
+  __rg_bps_argc+=("$#")
+  __rg_bps_redc+=("${#HOOK_SEG_REDIR_OP[@]}")
+  __rg_bps_words+=("$@")
+  __rg_bps_wq+=(${HOOK_SEG_WORD_QUOTED[@]+"${HOOK_SEG_WORD_QUOTED[@]}"})
+  __rg_bps_rop+=(${HOOK_SEG_REDIR_OP[@]+"${HOOK_SEG_REDIR_OP[@]}"})
+  __rg_bps_rfd+=(${HOOK_SEG_REDIR_FD[@]+"${HOOK_SEG_REDIR_FD[@]}"})
+  __rg_bps_rtgt+=(${HOOK_SEG_REDIR_TARGET[@]+"${HOOK_SEG_REDIR_TARGET[@]}"})
+  __rg_bps_rq+=(${HOOK_SEG_REDIR_QUOTED[@]+"${HOOK_SEG_REDIR_QUOTED[@]}"})
+  __rg_bps_ropq+=(${HOOK_SEG_REDIR_OPAQUE[@]+"${HOOK_SEG_REDIR_OPAQUE[@]}"})
+  "$__rg_bps_cb" "$@"
+}
+
+# run_guards::bps_replay <callback>: hand the recorded segments to <callback>
+# exactly as the parse did, each with its HOOK_SEG_* arrays rebuilt first, and
+# leave those arrays empty afterwards, as the parse does. Elements are read one
+# index at a time rather than sliced: a slice walks the array from its head.
+run_guards::bps_replay() {
+  local __rg_cb="$1" __rg_k __rg_j __rg_a __rg_c __rg_w=0 __rg_r=0
+  local __rg_depth=$RUN_GUARDS_BPS_DEPTH
+  local -a __rg_argv=()
+  RUN_GUARDS_BPS_DEPTH=1
+  for ((__rg_k = 0; __rg_k < ${#RUN_GUARDS_BPS_ARGC[@]}; __rg_k++)); do
+    __rg_a=${RUN_GUARDS_BPS_ARGC[__rg_k]}
+    __rg_c=${RUN_GUARDS_BPS_REDC[__rg_k]}
+    __rg_argv=()
+    HOOK_SEG_WORD_QUOTED=()
+    for ((__rg_j = 0; __rg_j < __rg_a; __rg_j++)); do
+      __rg_argv+=("${RUN_GUARDS_BPS_WORDS[__rg_w + __rg_j]}")
+      HOOK_SEG_WORD_QUOTED+=("${RUN_GUARDS_BPS_WQ[__rg_w + __rg_j]}")
+    done
+    HOOK_SEG_REDIR_OP=()
+    HOOK_SEG_REDIR_FD=()
+    HOOK_SEG_REDIR_TARGET=()
+    HOOK_SEG_REDIR_QUOTED=()
+    HOOK_SEG_REDIR_OPAQUE=()
+    for ((__rg_j = 0; __rg_j < __rg_c; __rg_j++)); do
+      HOOK_SEG_REDIR_OP+=("${RUN_GUARDS_BPS_ROP[__rg_r + __rg_j]}")
+      HOOK_SEG_REDIR_FD+=("${RUN_GUARDS_BPS_RFD[__rg_r + __rg_j]}")
+      HOOK_SEG_REDIR_TARGET+=("${RUN_GUARDS_BPS_RTGT[__rg_r + __rg_j]}")
+      HOOK_SEG_REDIR_QUOTED+=("${RUN_GUARDS_BPS_RQ[__rg_r + __rg_j]}")
+      HOOK_SEG_REDIR_OPAQUE+=("${RUN_GUARDS_BPS_ROPQ[__rg_r + __rg_j]}")
+    done
+    __rg_w=$((__rg_w + __rg_a))
+    __rg_r=$((__rg_r + __rg_c))
+    "$__rg_cb" "${__rg_argv[@]}"
+  done
+  HOOK_SEG_WORD_QUOTED=()
+  HOOK_SEG_REDIR_OP=()
+  HOOK_SEG_REDIR_FD=()
+  HOOK_SEG_REDIR_TARGET=()
+  HOOK_SEG_REDIR_QUOTED=()
+  HOOK_SEG_REDIR_OPAQUE=()
+  RUN_GUARDS_BPS_DEPTH=$__rg_depth
+}
+
+# --- PowerShell classifier, once, and only on that tool -----------------------
+# A Bash payload must not parse ps-command.sh at all; an unprimed payload still
+# loads it so a PowerShell command whose field cache missed cannot reach a guard
+# with `ps::` unbound.
+#
+# `--lib` in hooks.json is the wiring's cue that this event's guards declare a
+# library at all, which keeps the Bash hot path at one array test and reads
+# nothing. WHAT to load comes from each guard's own declaration in
+# guard-requires.sh, satisfied here ONCE for the event; a guard run alone
+# satisfies the same declaration itself through guard::require_libs, so a row
+# that omits the cue costs a repeated load and never a verdict. A `--lib` path
+# is loaded as well, so an explicit argument still preloads a library no guard
+# declared.
+_rg_tool="${RUN_GUARDS_FIELD['.tool_name']-}"
+if ((${#LIBS[@]})) && [[ "$_rg_tool" != "Bash" ]]; then
+  # shellcheck source=guard-requires.sh
+  source "$_RG_DIR/guard-requires.sh"
+  for _rg_guard in "${GUARDS[@]}"; do
+    guard::require_libs "${_rg_guard##*/}"
+  done
+  unset _rg_guard
+  for _rg_lib in "${LIBS[@]}"; do
+    guard::require_lib "$_rg_lib"
+  done
+  unset _rg_lib
+fi
+unset _rg_tool
+
+# --- run ----------------------------------------------------------------------
+RC=0
+OUTS=()
+# The guard being run: an index into GUARDS, or -1 while the dispatcher's own
+# code runs (before the first guard, and again from the merge onward). The
+# EXIT-trap handler below reads it to tell a guard's hard error from the
+# dispatcher's own abort.
+RUN_GUARDS_CUR=-1
+# The process the chain runs in. `exit` below compares BASHPID against it: a
+# guard's `exit` inside a real subshell must end that subshell, not unwind to
+# the dispatcher's loop there.
+RUN_GUARDS_PID=$BASHPID
+RUN_GUARDS_T0=""
+
+# Every document a guard emits is collected, not printed (hook-utils.sh,
+# hook::emit_document).
+# shellcheck disable=SC2329  # invoked by every guard sourced below
+hook::emit_document() {
+  OUTS+=("$1")
+}
+
+# Without jq every fail-closed guard denies the call through this helper. The
+# deny reason says so once for the call, not once per guard.
+# shellcheck disable=SC2329  # invoked by every fail-closed guard sourced below
+hook::require_jq_blocking() {
+  command -v jq >/dev/null 2>&1 && return 0
+  guard::say_once jq "BLOCKED: jq is not on PATH, so guardrails denies every Bash and PowerShell call, and every file write on Windows. Ask the user to install jq (https://jqlang.org/download/)."
+  exit 2
+}
+
+# `exit` for the sourced guards. The status a guard exits with is recorded and
+# the guard is unwound, so control never returns to the code after the call:
+# every frame of the guard returns at once, `source` returns to
+# run_guards::run_from, and the next guard starts on that frame's stack, not on
+# top of the exiting guard's. No argument means the status of the guard's last
+# command, as the builtin does.
+#
+# The unwind is a DEBUG trap under extdebug: a trap that returns 2 makes bash
+# simulate a `return` from the function or sourced script the next command
+# belongs to, and the trap fires again for the command after that return, until
+# run_from itself holds the next command; the trap then removes itself.
+# shellcheck disable=SC2329  # invoked by every guard sourced below
+exit() {
+  local __rg_rc="${1:-$?}"
+  [[ "$BASHPID" == "$RUN_GUARDS_PID" ]] || builtin exit "$__rg_rc"
+  ((RUN_GUARDS_CUR >= 0)) || builtin exit "$__rg_rc"
+  RUN_GUARDS_EXIT_RC=$__rg_rc
+  RUN_GUARDS_EXIT_DEPTH=${#FUNCNAME[@]}
+  set -T
+  shopt -s extdebug
+  # Inline, not a function: the first firing is at the guard's deepest frame,
+  # and a call there costs stack the guard may not have left.
+  trap '[[ ${FUNCNAME[0]-} == run_guards::run_from ]] && { trap - DEBUG; shopt -u extdebug; set +T; RUN_GUARDS_UNWOUND=1; } || return 2' DEBUG
+  return 0
+}
+
+RUN_GUARDS_EXIT_RC=0
+RUN_GUARDS_EXIT_DEPTH=0
+RUN_GUARDS_UNWOUND=0
+
+# A guard died of a hard error: the shell is exiting, and the EXIT trap the
+# guard installed through guard::abort_boundary handed the status here (the
+# library's chain slot, _GAB_CONTINUE, set right before the first guard runs
+# and cleared before the merge). A deliberate `exit` in a guard never comes
+# this way; that is the function above. Never returns.
+# shellcheck disable=SC2329  # invoked through _GAB_CONTINUE by the trap handler
+run_guards::guard_died() {
+  run_guards::guard_done "$1"
+}
+
+# run_guards::record <rc>: the guard at RUN_GUARDS_CUR ended with <rc>. Applies
+# its abort boundary (when it installed one: a stub that never called
+# guard::abort_boundary keeps its raw status, as it did in its own subshell,
+# which had no trap), collects the notice document, prints the profile line,
+# and folds the status into RC.
+run_guards::record() {
+  local __rg_rc="$1" __rg_path="${GUARDS[RUN_GUARDS_CUR]}"
+  if [[ -n "$_GAB_NAME" ]] && ! guard::_abort_settle "$__rg_rc"; then
+    [[ -n "$_GAB_DOC" ]] && OUTS+=("$_GAB_DOC")
+    __rg_rc=$_GAB_RC
+  fi
+  # RUN_GUARDS_PROFILE=1 prints one line per guard to stderr (ms, rc, name);
+  # this is how the README's budget accounting is measured.
+  if [[ -n "${RUN_GUARDS_PROFILE:-}" && -n "${EPOCHREALTIME:-}" && -n "$RUN_GUARDS_T0" ]]; then
+    local __rg_t1=$EPOCHREALTIME
+    printf 'run-guards: %5d ms rc=%d %s\n' "$(((${__rg_t1/./} - ${RUN_GUARDS_T0/./}) / 1000))" "$__rg_rc" "${__rg_path##*/}" >&2
+  fi
+  if ((__rg_rc == 2)); then
+    RC=2
+  elif ((__rg_rc != 0 && RC != 2 && __rg_rc > RC)); then
+    RC=$__rg_rc
+  fi
+}
+
+# The call depth past which the rest of the chain does not run on this stack.
+# `exit` unwinds its guard, so only a guard that dies of a hard error (its EXIT
+# trap runs the rest) leaves its frames under whatever runs next. Git Bash's
+# main thread has a 2 MB stack, and a second alias walk on top of the first
+# overflowed it: bash died of an access violation that its parent read as exit
+# 0 with no output, an allow. A guard that exited past this depth, and a hard
+# error past it, hand the rest to another process: a fork after the deep
+# `exit`, a fresh dispatcher from the dying shell's trap.
+RUN_GUARDS_MAX_DEPTH=64
+
+# run_guards::guard_done <rc>: record the guard that died of a hard error and
+# run the rest. Never returns.
+# shellcheck disable=SC2329  # invoked by run_guards::guard_died, itself invoked through _GAB_CONTINUE
+run_guards::guard_done() {
+  run_guards::record "$1"
+  ((RUN_GUARDS_OVERLONG && RC == 2)) && run_guards::finish
+  local __rg_next=$((RUN_GUARDS_CUR + 1))
+  ((__rg_next < ${#GUARDS[@]})) || run_guards::finish
+  run_guards::run_rest "$__rg_next"
+  run_guards::finish
+}
+
+# run_guards::run_from <index>: run the guards from <index> on, then finish.
+# Never returns. A guard that ends through `exit` has been unwound back to the
+# `source` below (see `exit`), so every guard starts on this frame's stack.
+run_guards::run_from() {
+  local __rg_i __rg_rc
+  for ((__rg_i = $1; __rg_i < ${#GUARDS[@]}; __rg_i++)); do
+    RUN_GUARDS_CUR=$__rg_i
+    local __rg_path
+    case "${GUARDS[__rg_i]}" in
+    */*) __rg_path="${GUARDS[__rg_i]}" ;;
+    *) __rg_path="$HOOK_DIR/${GUARDS[__rg_i]}" ;;
+    esac
+    if [[ ! -f "$__rg_path" ]]; then
+      echo "run-guards: guard not found: $__rg_path" >&2
+      # Under exec-bash --fail-closed this 1 denies the call.
+      ((RC < 1)) && RC=1
+      continue
+    fi
+    # The guard's own boundary sets this; a guard that never installs one is
+    # recorded on its raw status.
+    _GAB_NAME=""
+    # A fresh hook process has no alias memo; the guard before this one may
+    # have armed it on the same command, and a memo hit is "already analyzed".
+    hook::reset_analysis_state
+    RUN_GUARDS_BPS_DEPTH=0
+    RUN_GUARDS_T0=${EPOCHREALTIME:-}
+    # shellcheck disable=SC1090
+    source "$__rg_path" </dev/null
+    __rg_rc=$?
+    if ((RUN_GUARDS_UNWOUND)); then
+      RUN_GUARDS_UNWOUND=0
+      __rg_rc=$RUN_GUARDS_EXIT_RC
+    fi
+    run_guards::record "$__rg_rc"
+    ((RUN_GUARDS_OVERLONG && RC == 2)) && break
+    # A guard that exited this deep may have come close to the stack limit,
+    # and the next guard's own walk can run out of it where the first did not.
+    # In a forked child that crash cannot take this process, and the verdict
+    # already recorded, with it: a rest that reports nothing denies the call.
+    if ((RUN_GUARDS_EXIT_DEPTH > RUN_GUARDS_MAX_DEPTH && __rg_i + 1 < ${#GUARDS[@]})); then
+      RUN_GUARDS_EXIT_DEPTH=0
+      run_guards::run_rest $((__rg_i + 1))
+      break
+    fi
+    RUN_GUARDS_EXIT_DEPTH=0
+  done
+  run_guards::finish
+}
+
+# run_guards::run_rest <index>: the guards from <index> on, run in another
+# process, after a guard exited past RUN_GUARDS_MAX_DEPTH or from inside a dying
+# shell's EXIT trap. Its collected documents and status come back on its stdout as
+# <doc>RS ... RS<doc>RS RC=<n>. RS (0x1e) cannot occur inside a document (JSON
+# escapes every control byte).
+#
+# A dying shell past the depth bound gets a fresh dispatcher fed the same payload, so the
+# guards run on an empty stack. That needs a payload the fresh process reads
+# back the same: read whole (stdin rc 0), and primed, so it carried no NUL that
+# the shell variable dropped. Any other payload past the bound is denied:
+# carrying on here is how the stack ran out. A dying shell within the bound
+# forks a subshell of the same chain, as before; RUN_GUARDS_PID moves with it,
+# and a further hard error there costs one more subshell from its own trap.
+#
+# No status reported back means the rest of the chain died unseen, and on Git
+# Bash a crash reads as exit 0, so its verdict is unknown: the call is denied.
+run_guards::run_rest() {
+  local __rg_rest="" __rg_doc
+  if ((${#FUNCNAME[@]} > RUN_GUARDS_MAX_DEPTH)); then
+    if ((RUN_GUARDS_STDIN_RC == 0 && RUN_GUARDS_PRIMED)); then
+      __rg_rest=$("$BASH" "$HOOK_DIR/run-guards.sh" --report "$_GUARD_SAID" \
+        ${RUN_GUARDS_OPTS[@]+"${RUN_GUARDS_OPTS[@]}"} "${GUARDS[@]:$1}" <<<"$RUN_GUARDS_INPUT")
+    fi
+  else
+    # shellcheck disable=SC2030  # the subshell's own OUTS and RC come back on its stdout
+    __rg_rest=$(
+      RUN_GUARDS_PID=$BASHPID
+      RUN_GUARDS_REPORT=1
+      OUTS=()
+      RC=0
+      run_guards::run_from "$1"
+    )
+  fi
+  while [[ "$__rg_rest" == *$'\x1e'* ]]; do
+    __rg_doc=${__rg_rest%%$'\x1e'*}
+    __rg_rest=${__rg_rest#*$'\x1e'}
+    # shellcheck disable=SC2031  # this is the parent's OUTS, fed from the report
+    OUTS+=("$__rg_doc")
+  done
+  if [[ "$__rg_rest" =~ ^RC=([0-9]+)$ ]]; then
+    __rg_doc=${BASH_REMATCH[1]}
+    if ((__rg_doc == 2)); then
+      RC=2
+    elif ((__rg_doc != 0 && RC != 2 && __rg_doc > RC)); then
+      RC=$__rg_doc
+    fi
+  else
+    echo "BLOCKED: guardrails could not finish checking this call: the guards after ${GUARDS[$1 - 1]##*/} reported no verdict. Split the command into simpler steps." >&2
+    RC=2
+  fi
+}
+
+# Several documents and no way to merge them: a hook process may emit exactly
+# ONE JSON document, so pick one. A blocking decision must not be lost, so a
+# document carrying `"decision":"block"` or `"permissionDecision":"deny"` wins,
+# then one carrying `"permissionDecision":"ask"`, else the first document. The
+# rest go to stderr, prefixed, so the drop is visible in debug output.
+run_guards::emit_one() {
+  local why="$1" pick=-1 i doc
+  local re_block='"decision"[[:space:]]*:[[:space:]]*"block"'
+  local re_deny='"permissionDecision"[[:space:]]*:[[:space:]]*"deny"'
+  local re_ask='"permissionDecision"[[:space:]]*:[[:space:]]*"ask"'
+  for i in "${!OUTS[@]}"; do
+    doc="${OUTS[i]}"
+    if [[ "$doc" =~ $re_block || "$doc" =~ $re_deny ]]; then
+      pick=$i
+      break
+    fi
+    ((pick < 0)) && [[ "$doc" =~ $re_ask ]] && pick=$i
+  done
+  ((pick < 0)) && pick=0
+  printf '%s\n' "${OUTS[pick]}"
+  # On a block, stderr is the model's deny reason, not the debug log.
+  ((RC == 2)) && return 0
+  for i in "${!OUTS[@]}"; do
+    ((i == pick)) && continue
+    printf 'run-guards: dropped %s: %s\n' "$why" "${OUTS[i]}" >&2
+  done
+}
+
+# run_guards::finish: emit the aggregated result and exit. Never returns.
+run_guards::finish() {
+  RUN_GUARDS_CUR=-1
+  _GAB_CONTINUE=""
+  # shellcheck disable=SC2031  # each process reads its own: the fork in run_guards::run_rest sets the subshell's
+  if ((RUN_GUARDS_REPORT)); then
+    local __rg_doc
+    for __rg_doc in ${OUTS[@]+"${OUTS[@]}"}; do
+      printf '%s\x1e' "$__rg_doc"
+    done
+    printf 'RC=%d' "$RC"
+    builtin exit 0
+  fi
+  # The dispatcher's own boundary again, for the merge below: the last guard's
+  # boundary is what the trap holds at this point. Once a guard has blocked,
+  # an abort in the merge must not turn the block into an allow.
+  local __rg_posture=open
+  ((RC == 2)) && __rg_posture=closed
+  guard::abort_boundary run-guards "$_GAB_EVENT" "$__rg_posture" 0 2
+  # A guard that exited 2 denies the call, so an ask another guard emitted is
+  # dropped rather than shown beside the deny.
+  if ((RC == 2 && ${#OUTS[@]})); then
+    local __rg_keep=() __rg_d __rg_re_ask='"permissionDecision"[[:space:]]*:[[:space:]]*"ask"'
+    for __rg_d in "${OUTS[@]}"; do
+      [[ "$__rg_d" =~ $__rg_re_ask ]] || __rg_keep+=("$__rg_d")
+    done
+    OUTS=(${__rg_keep[@]+"${__rg_keep[@]}"})
+  fi
+  if ((${#OUTS[@]} == 1)); then
+    printf '%s\n' "${OUTS[0]}"
+  elif ((${#OUTS[@]} > 1)); then
+    if ! command -v jq >/dev/null 2>&1; then
+      run_guards::emit_one "without jq"
+    else
+      local merged
+      # A permission decision survives the merge: deny over ask, and the
+      # reasons of every guard that chose the winning decision are joined.
+      merged=$(printf '%s\n' "${OUTS[@]}" | jq -cs '
+        (map(.hookSpecificOutput.permissionDecision // empty)) as $d
+        | (if any($d[]; . == "deny") then "deny" elif any($d[]; . == "ask") then "ask" else "" end) as $dec
+        | { hookSpecificOutput: ({
+              hookEventName: (map(.hookSpecificOutput.hookEventName // empty) | .[0] // ""),
+              additionalContext: (map(.hookSpecificOutput.additionalContext // empty) | join("\n\n")) }
+            + (if $dec == "" then {} else {
+                permissionDecision: $dec,
+                permissionDecisionReason: (map(select(.hookSpecificOutput.permissionDecision == $dec)
+                  | .hookSpecificOutput.permissionDecisionReason // empty) | join("\n\n")) } end)),
+            systemMessage: (map(.systemMessage // empty) | join("\n\n")) }
+        | if .systemMessage == "" then del(.systemMessage) else . end
+        | if .hookSpecificOutput.additionalContext == "" then del(.hookSpecificOutput.additionalContext) else . end
+        | if (.hookSpecificOutput | keys) == ["hookEventName"] then del(.hookSpecificOutput) else . end
+        | if . == {} then empty else . end' 2>/dev/null)
+      # The Windows jq build writes CRLF; a raw CR never belongs in a JSON document.
+      merged="${merged//$'\r'/}"
+      if [[ -n "$merged" ]]; then
+        printf '%s\n' "$merged"
+      else
+        run_guards::emit_one "(merge failed)"
+      fi
+    fi
+  fi
+  # The aggregated status is the dispatcher's answer. Under exec-bash's
+  # --fail-closed, which every run-guards.sh row passes, any non-zero status
+  # other than 2 (a guard-not-found 1, a stub's 3) denies the call. Release
+  # the boundary so it is not reported as an abort.
+  guard::abort_boundary_release
+  builtin exit "$RC"
+}
+
+_GAB_CONTINUE=run_guards::guard_died
+run_guards::run_from 0
diff --git a/.githooks/guardrails/secret-patterns.sh b/.githooks/guardrails/secret-patterns.sh
new file mode 100644
index 0000000000..8c929436d6
--- /dev/null
+++ b/.githooks/guardrails/secret-patterns.sh
@@ -0,0 +1,89 @@
+# shellcheck shell=bash
+# Shared high-confidence secret/credential patterns for secret-pattern-detection
+# and the write-path-independent pre-commit content-invariants hook.
+#
+# This is a library — NOT executable. Pure-function: no env reads, no stdin
+# parsing, no exit calls beyond the scan helper's documented return codes.
+# Callers handle I/O, exemptions, and exit-code mapping.
+#
+# Pattern selection: only HIGH-confidence patterns with distinctive prefixes
+# and fixed lengths or a fixed structure. The ghs_ installation token varies in
+# length and may carry a JWT with or without an app id, so it takes the regex
+# GitHub recommends for current and stateless installation tokens from
+# https://github.blog/changelog/2026-05-15-github-app-installation-tokens-per-request-override-header/
+# (as of 2026-10-21; recheck when GitHub changes a token format or its
+# recommended regex). 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. grep -E (POSIX ERE) only,
+# run under LC_ALL=C: in a UTF-8 locale GNU grep takes quadratic time on a long
+# line against the combined set.
+
+# (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 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_)
+  '(^|[^A-Za-z0-9_])ghs_[A-Za-z0-9._-]{36,}|ghs_([0-9]+_)?eyJ[A-Za-z0-9._-]{20,}' # GitHub installation token, current and stateless; a JWT-shaped one needs no left boundary
+  '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
+)
+
+# secrets::scan_text <content>
+#
+# Scans <content> for high-confidence secret patterns.
+#
+# Output (stdout): one line per hit — `<label> (line <n[,n…]>)` — empty when
+# clean. Stdout is the ONLY channel: both callers read it through a command
+# substitution, so a global set here would be discarded with the subshell.
+# Telemetry labels are parsed back off these lines by the caller.
+#
+# Exit: 0 = clean, 1 = violations found.
+#
+# Feeds content through PROCESS SUBSTITUTION, never `<<<"$content"` (deadlocks
+# at 65536-65663 bytes) and never `printf | grep -q` under pipefail (SIGPIPE
+# inverts a hit into a clean miss). See hardcoded-path-patterns.sh for the
+# two-shapes rule.
+secrets::scan_text() {
+  local content="$1" lines label pattern i
+  local grep_e_args=()
+  for pattern in "${SECRET_PATTERNS[@]}"; do
+    grep_e_args+=(-e "$pattern")
+  done
+  if ! LC_ALL=C grep -qE "${grep_e_args[@]}" < <(printf '%s' "$content") 2>/dev/null; then
+    return 0
+  fi
+  for i in "${!SECRET_PATTERNS[@]}"; do
+    label="${SECRET_LABELS[$i]}"
+    pattern="${SECRET_PATTERNS[$i]}"
+    lines=$(LC_ALL=C grep -nE -- "$pattern" < <(printf '%s' "$content") 2>/dev/null |
+      head -3 | cut -d: -f1 | tr '\n' ',' | sed 's/,$//')
+    if [[ -n "$lines" ]]; then
+      printf '%s (line %s)\n' "$label" "$lines"
+    fi
+  done
+  return 1
+}
diff --git a/.githooks/guardrails/skill-reference-verify.sh b/.githooks/guardrails/skill-reference-verify.sh
new file mode 100755
index 0000000000..0580d2d200
--- /dev/null
+++ b/.githooks/guardrails/skill-reference-verify.sh
@@ -0,0 +1,927 @@
+#!/usr/bin/env bash
+# PostToolUse hook: verify `/<plugin>:<skill>` references written to markdown
+# resolve to a skill that exists in the working tree.
+# Triggered on Write|Edit of *.md files.
+#
+# Catches subagent / training-recall hallucinations — a slash-command reference
+# written AS a capability that does not exist, or one left behind by a rename.
+# Sibling of cli-flag-verify and stale-path-verify: same defect class, third
+# oracle.
+#
+# ENFORCEABILITY TIER: Detect-then-judge — ADVISORY PLUS A HUMAN VERDICT, never
+# an auto-fix. Globbing a plugins tree is exact only inside a marketplace repo
+# that owns the referenced plugin. In a consuming repo the reference may name a
+# plugin from another marketplace, or one the operator has simply not installed,
+# and this hook cannot distinguish that from a hallucination. Per the org
+# convention on enforceability tiers, that means the finding is a prompt for a
+# human decision, not a determination. The plugins-root gate below is what keeps
+# the noise inside the one context where the oracle is meaningful.
+#
+# PLUGINS-ROOT GATE: the hook does nothing unless the file being written lives in
+# a repo with a `plugins/` directory containing at least one `.claude-plugin/`
+# manifest — i.e. a marketplace repo. Outside one there is no local authority to
+# resolve a reference against, so the guard stays silent rather than guessing.
+#
+# PLUGIN-SCOPE GATE: within a marketplace repo, a reference is only adjudicated
+# when its PLUGIN half resolves locally. `/some-other-marketplace:thing` is left
+# alone; `/guardrails:nonexistent` is reported, because this repo owns
+# `guardrails` and can therefore say the skill is not there.
+#
+# NON-BLOCKING (advisory): exits 0 with hookSpecificOutput additionalContext.
+#
+# Disable with the skill_reference_verify_enabled userConfig option set to false.
+
+set -uo pipefail
+
+# High-res start stamp for telemetry (Bash 5.0+; empty on older bash → skip).
+start=${EPOCHREALTIME:-}
+
+# Kill switch FIRST, before any library is sourced: a disabled hook must not
+# pay to parse hook-utils.sh to learn it is off. Same predicate as
+# hook::is_enabled; scripts/check-killswitch-hoist.sh pins the two together.
+[[ "${CLAUDE_PLUGIN_OPTION_SKILL_REFERENCE_VERIFY_ENABLED:-true}" == "true" ]] || exit 0
+
+# The hook's own directory is derived with parameter expansion rather than
+# `dirname`. GNU Bash forks a subshell for every command substitution even when
+# the body is a builtin (Command Substitution, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution). On Windows Git Bash that
+# fork is a process, and this line runs on every fire — including inside the
+# dispatcher, where the include guard makes `source` cheap but `$(dirname …)`
+# still execs. `${BASH_SOURCE[0]%/*}` equals `dirname` for every shape
+# BASH_SOURCE takes; the fallback covers a bare filename, where the strip is a
+# no-op and dirname answers `.`.
+_HOOK_SELF="${BASH_SOURCE[0]%/*}"
+[[ "$_HOOK_SELF" == "${BASH_SOURCE[0]}" ]] && _HOOK_SELF=.
+# shellcheck source=abort-boundary.sh
+source "$_HOOK_SELF/abort-boundary.sh"
+# Could-not-run posture (#3528): fail-open with a dual-channel "guard did not
+# run" notice; 0 is the only status this advisory verifier chooses. Nothing is
+# enforced here, so the loss on an abort is the advisory itself.
+guard::abort_boundary skill-reference-verify PostToolUse open 0
+# shellcheck source=hook-utils.sh
+source "$_HOOK_SELF/hook-utils.sh" || exit 70 # not a chosen status: the boundary reports it
+
+hook::ctx_reset
+
+hook::buffer_stdin_to INPUT || exit 0
+
+hook::require jq "PostToolUse" guardrails "$INPUT"
+
+FILE=""
+hook::read_file_path_to FILE "$INPUT" || exit 0
+case "$FILE" in
+# A CHANGELOG is an append-only historical record: an entry saying a skill was
+# renamed MUST keep naming the old command, so every rename permanently adds an
+# unresolvable reference to one. Measured on this repo: 56 of 63 findings (89%)
+# were CHANGELOG rename entries, all correct as written, and excluding them moves
+# the guard from 3.4% of files firing at 6% precision to 0.5% firing at 57%.
+#
+# Deliberately narrow: a broader "historical by contract" rule would cost real signal.
+*/CHANGELOG.md | CHANGELOG.md) exit 0 ;;
+*.md) ;;
+*) exit 0 ;;
+esac
+
+# Parameter expansion, not a `$(dirname …)` subshell, with the same answers:
+# no slash -> `.`, and a root-level `/x` -> `/` rather than the empty string,
+# which hook::repo_root would read as `.`.
+FILE_DIR="${FILE%/*}"
+[[ "$FILE_DIR" == "$FILE" ]] && FILE_DIR="."
+[[ -n "$FILE_DIR" ]] || FILE_DIR=/
+REPO_ROOT="" REPO_ROOT_RESOLVED=1
+hook::repo_root_to REPO_ROOT "$FILE_DIR" || REPO_ROOT_RESOLVED=0
+PLUGINS_DIR="$REPO_ROOT/plugins"
+
+# PLUGINS-ROOT GATE. Outside a marketplace repo there is no local authority.
+# It runs before the payload read below: the structuredPatch filter is one the
+# builtin parser cannot answer, so reading first spent a jq process on every
+# .md edit in a repo this guard then leaves alone.
+[[ -d "$PLUGINS_DIR" ]] || exit 0
+shopt -s nullglob
+manifests=("$PLUGINS_DIR"/*/.claude-plugin/plugin.json)
+shopt -u nullglob
+((${#manifests[@]} > 0)) || exit 0
+
+# Diff-scope: verify only the content THIS tool call wrote, never re-read the
+# whole file from disk.
+#
+# Every payload field this hook can need, in ONE jq process (hook::jq_fields),
+# not three — a jq spawn is fork() emulation on Windows Git Bash. Both per-tool
+# content fields and replace_all are fetched together because selecting between
+# them would cost another process; jq reads the same envelope either way, and the
+# tool-specific choice happens below in the shell. `replace_all` keeps its
+# `// false | tostring` INSIDE the filter: hook::jq_fields wraps each filter in
+# `// ""`, and jq's `//` treats the boolean false as empty, so a bare
+# `.tool_input.replace_all` would come back "" instead of "false". That is kept
+# for parity with the pre-conversion output, not because a branch depends on it
+# — every consumer below tests `== "true"`, which "" and "false" fail alike.
+# Failure semantics are unchanged: a missing jq or an unparsable payload yields
+# rc 1 here, which exits 0 exactly as the unmatched-TOOL case did —
+# hook::require jq above has already made the degraded state visible once per
+# session and agent.
+hook::jq_fields "$INPUT" '.tool_name' '.tool_input.new_string' \
+  '.tool_input.content' '.tool_input.replace_all // false | tostring' \
+  '[(.tool_response | objects | .structuredPatch)[]?.lines[]?
+    | select(type == "string" and startswith("+")) | .[1:]] | join("\n")' || exit 0
+TOOL="${HOOK_JQ_FIELDS[0]}"
+# Edit's `replace_all`. Reconstruction needs it: with `replace_all` the same
+# `new_string` lands in several places on purpose, so several matches are the
+# edit's own footprint rather than an ambiguity. Absent or false on every
+# ordinary Edit. This record also serves stale-path-verify.sh. Pointer: when
+# the uniqueness gate's premise is in doubt, read
+# https://code.claude.com/docs/en/tools-reference#edit-tool-behavior live. As
+# of: 2026-10-11. Recheck trigger: that section changes how often `old_string`
+# may match or what `replace_all` does, or is renamed.
+#
+# `replace_all` alone cannot say WHICH occurrences this call wrote, and that is
+# the whole of the residual reported in #2129: after `ghost` replaces `setup`
+# everywhere, the `ghost` inside a pre-existing `ghost-old` reads exactly like one
+# the edit produced. Nothing in `tool_input` separates them — but the premise
+# "nothing in the PAYLOAD does" is false. `tool_response` carries the Edit tool's
+# structured output, whose `structuredPatch` marks the lines the call actually
+# wrote with a leading `+`.
+#
+# Both halves rest on upstream pages, read live rather than restated here.
+# Pointers: what a PostToolUse payload carries,
+# https://code.claude.com/docs/en/hooks#posttooluse-input; the Edit tool's
+# structured output and its `structuredPatch` shape, the Edit entry under
+# https://code.claude.com/docs/en/agent-sdk/typescript#tool-output-types. As of:
+# 2026-10-11. Recheck trigger: the hooks section changes what `tool_response`
+# carries for PostToolUse, or the SDK section changes `FileEditOutput`'s
+# `structuredPatch`, or either section is renamed.
+#
+# OBSERVED, not merely documented: an independent reviewer captured a live
+# PostToolUse payload (a temp settings.json dumping stdin, driven by a headless
+# claude 2.1.225 session) and `tool_response` arrived as an OBJECT carrying
+# `filePath newString oldString originalFile replaceAll structuredPatch
+# userModified`. An object, not the serialized string `PostToolBatch` passes — the
+# distinction the hooks reference draws, and the one shape that would have broken
+# the filter below. `structuredPatch` was complete rather than truncated at 42
+# replacement sites in a 300-line file.
+#
+# The read is SHAPE-TOLERANT anyway (`objects` in the jq filter): a non-object
+# `tool_response` yields an empty witness and leaves the filter inert, instead of
+# erroring hook::jq_fields into its `|| exit 0` and silencing the whole guard —
+# a risk the pre-gate code did not carry, because it never touched the field.
+#
+# Kept as the LINE TEXTS rather than line numbers on purpose. Numbers would be
+# wrong the moment another PostToolUse hook reformats the file between the write
+# and this read — the case the reconstruction fallback below already exists for —
+# and mapping a character offset back to a line number costs a whole-prefix scan
+# per occurrence, which is the quadratic term this hook spent a release removing.
+# Matching the physical line by text is a hash lookup and survives renumbering.
+# Its one imprecision is conservative: an untouched line whose text is identical
+# to an edited one still passes, which keeps a finding rather than dropping one.
+EDIT_WROTE_LINES=""
+REPLACE_ALL=false
+case "$TOOL" in
+Edit)
+  SCAN_CONTENT="${HOOK_JQ_FIELDS[1]}"
+  REPLACE_ALL="${HOOK_JQ_FIELDS[3]}"
+  case "$REPLACE_ALL" in
+  true | false) ;;
+  *)
+    # Advisory guard: a malformed replace_all extraction must not wear the permissive
+    # "false" branch. Well-formed payloads always stringify to true/false; anything
+    # else is an unreadable field — skip verification rather than guess.
+    exit 0
+    ;;
+  esac
+  EDIT_WROTE_LINES="${HOOK_JQ_FIELDS[4]}"
+  ;;
+Write) SCAN_CONTENT="${HOOK_JQ_FIELDS[2]}" ;;
+*) exit 0 ;;
+esac
+[[ -n "$SCAN_CONTENT" ]] || exit 0
+
+# A plugin's command namespace is its manifest `name`, which need not equal its
+# directory name. Build the name → directory map from the manifests themselves so
+# a renamed directory or a name override resolves correctly.
+#
+# The manifest also decides WHERE that plugin's skills live. We treat the paths
+# its `skills` key declares as extra skill directories beside the conventional
+# `skills/`, and collect them per plugin so a skill loaded from a declared
+# location resolves like any other. Pointer:
+# https://code.claude.com/docs/en/plugins/manifest-reference#how-each-key-combines-with-its-default-location.
+# As of: 2026-10-11. Recheck trigger: that section stops saying declared
+# `skills` paths add to the default `skills/` directory, or is renamed.
+#
+# One documented exception is NOT modeled: for a marketplace entry whose `source`
+# resolves to the marketplace root, declared subdirectories REPLACE the default
+# `skills/` scan. Modeling it would mean reading marketplace.json to learn how
+# each entry resolves, and the cost of not modeling it is bounded — the default
+# stays in the search set, so at worst a reference resolves that Claude Code would
+# not offer and this advisory stays quiet. Staying quiet is the failure this guard
+# is allowed to have; a false alarm is not.
+# BUILT ON DEMAND, IN ONE PROCESS. Nothing below the reference scan reads the
+# index, and the scan needs no plugin knowledge to find its candidates, so the
+# index is built once, only when a candidate exists. The gates above stay where
+# they are: their `exit 0` paths deliberately skip telemetry, and moving them
+# would change that.
+#
+# When it is built, one jq reads every manifest. The previous shape spawned two
+# jq and two tr per manifest, and this marketplace carries 74 of them: 296
+# processes, 468 ms on a Linux host and 11.4 s on Windows Git Bash, for work one
+# process finishes in 6 ms. Each output line is
+# `<manifest>\x1e<name>\x1e<paths>`, the declared skill paths joined by \x1f.
+# Raw strings, not @tsv: @tsv backslash-escapes its fields, and the values are
+# used as paths, so they must arrive byte-identical. The two separators are
+# non-whitespace so `read` keeps an EMPTY field in place (tab is IFS
+# whitespace and would collapse a nameless manifest's fields together); neither
+# byte can appear in a manifest name or path.
+# srv_git_dir_to <var>
+# Checkout git dir, so the manifest index can be cached beside it.
+srv_git_dir_to() {
+  local g="$REPO_ROOT/.git" line
+  if [[ -d "$g" ]]; then
+    printf -v "$1" '%s' "$g"
+    return 0
+  fi
+  if [[ -f "$g" ]]; then
+    IFS= read -r line <"$g" || return 1
+    line=${line%$'\r'}
+    [[ "$line" == 'gitdir:'* ]] || return 1
+    line=${line#gitdir:}
+    line=${line#"${line%%[![:space:]]*}"}
+    if [[ "$line" != /* && "$line" != [A-Za-z]:[/\\]* ]]; then
+      line="$REPO_ROOT/$line"
+    fi
+    printf -v "$1" '%s' "$line"
+    return 0
+  fi
+  return 1
+}
+
+declare -A PLUGIN_DIR=() PLUGIN_SKILL_PATHS=()
+PLUGIN_INDEX_BUILT=0
+build_plugin_index() {
+  ((PLUGIN_INDEX_BUILT)) && return 0
+  PLUGIN_INDEX_BUILT=1
+  local m pdir pname paths line body git_dir="" cache_file="" use_cache=0 i start last
+  local -a rows=() hdr=()
+  local -A seen=()
+  # A repeat reference at an unchanged manifest set skips jq. The cache is
+  # used only when it is strictly newer than every manifest.
+  if srv_git_dir_to git_dir; then
+    cache_file="$git_dir/guardrails-skill-index"
+  fi
+  if [[ -n "$cache_file" && -f "$cache_file" ]]; then
+    mapfile -t hdr <"$cache_file"
+    start=$((${#manifests[@]} + 2))
+    last=$((${#hdr[@]} - 1))
+    if [[ "${hdr[0]-}" == "${#manifests[@]}" ]]; then
+      use_cache=1
+      for ((i = 0; i < ${#manifests[@]}; i++)); do
+        [[ "${hdr[i + 1]-}" == "${manifests[i]}" ]] || use_cache=0
+        [[ "$cache_file" -nt "${manifests[i]}" ]] || use_cache=0
+      done
+      [[ "${hdr[${#manifests[@]} + 1]-}" == '---' ]] || use_cache=0
+      # The rows end with `end <count>`. A parallel fire can be rewriting this
+      # file, and two writers that both truncate leave a mix of their bytes, so
+      # the count must equal the rows read and no row may look like a sentinel.
+      # Anything else is a miss and jq rebuilds it.
+      ((last >= start)) && [[ "${hdr[last]}" == "end $((last - start))" ]] || use_cache=0
+      if ((use_cache && last > start)); then
+        rows=("${hdr[@]:start:last-start}")
+        for line in "${rows[@]}"; do
+          [[ "$line" == "end "[0-9]* ]] && use_cache=0
+        done
+      fi
+    fi
+  fi
+  if ((!use_cache)); then
+    rows=()
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      rows+=("$line")
+    done < <(
+      jq -r '[input_filename, (.name // "" | tostring),
+              ((.skills // null) | if . == null then ""
+                elif type == "array" then map(tostring) | join("\u001f")
+                else tostring end)] | join("\u001e")' "${manifests[@]}" 2>/dev/null
+    )
+    if [[ -n "$cache_file" ]]; then
+      # Built in memory and written by one printf, sentinel last: a temp file
+      # plus mv would add a process to every cold write.
+      printf -v body '%s\n' "${#manifests[@]}" "${manifests[@]}" '---' ${rows[@]+"${rows[@]}"}
+      printf '%send %d\n' "$body" "${#rows[@]}" 2>/dev/null >"$cache_file" || :
+    fi
+  fi
+  for line in ${rows[@]+"${rows[@]}"}; do
+    [[ -n "$line" ]] || continue
+    IFS=$'\x1e' read -r m pname paths <<<"$line"
+    m="${m//$'\r'/}"
+    [[ -n "$m" ]] || continue
+    # `input_filename` echoes the argument as jq received it, and on Windows
+    # Git Bash a native jq receives the MSYS-converted form (`C:/…` or
+    # `C:\…`), not the string in manifests[]. Only the plugin directory NAME
+    # is taken from the echo; the directory itself is rebuilt from
+    # PLUGINS_DIR, so neither the index nor the seen[] check below depends on
+    # the echoed form (a mismatch there would re-read every manifest through
+    # the fallback, four processes each, on every reference-bearing write).
+    m="${m%/.claude-plugin/plugin.json}"
+    m="${m%\\.claude-plugin\\plugin.json}"
+    m="${m##*/}"
+    m="${m##*\\}"
+    pdir="$PLUGINS_DIR/$m"
+    pname="${pname//$'\r'/}"
+    [[ -n "$pname" ]] || pname="${pdir##*/}"
+    PLUGIN_DIR["$pname"]="$pdir"
+    paths="${paths//$'\r'/}"
+    PLUGIN_SKILL_PATHS["$pname"]="${paths//$'\x1f'/$'\n'}"
+    seen["$pdir"]=1
+  done
+  # jq stops the batch at the first manifest it cannot parse, so every manifest
+  # behind a malformed one comes back unread. Those, and the malformed one, take
+  # the per-manifest read the batch replaced: exact for the readable ones, and
+  # the directory name for the broken one. On a tree where every manifest
+  # parses (this one, gated by CI) the residue is empty and this spawns nothing.
+  for m in "${manifests[@]}"; do
+    pdir="${m%/.claude-plugin/plugin.json}"
+    [[ -n "${seen[$pdir]:-}" ]] && continue
+    pname=$(jq -r '.name // empty' "$m" 2>/dev/null | tr -d '\r')
+    [[ -n "$pname" ]] || pname="${pdir##*/}"
+    PLUGIN_DIR["$pname"]="$pdir"
+    PLUGIN_SKILL_PATHS["$pname"]=$(
+      jq -r '.skills // empty | if type == "array" then .[] else . end' "$m" 2>/dev/null | tr -d '\r'
+    )
+  done
+}
+
+# Extract a plugin skill's frontmatter `name`, or nothing when it declares none.
+# Tolerates quoting and a trailing YAML comment (`name: renamed # public
+# command`); comments are stripped first so the value pattern stays anchored to
+# end-of-line.
+skill_frontmatter_name() {
+  sed -n '1,40p' "$1" 2>/dev/null |
+    sed -nE 's/[[:space:]]+#.*$//; s/^name:[[:space:]]*"?'"'"'?([A-Za-z0-9_-]+)"?'"'"'?[[:space:]]*$/\1/p' |
+    head -1
+}
+
+# The directories a plugin's skills are loaded from: the conventional `skills/`,
+# plus every path its manifest declares, plus the plugin root when the manifest
+# declares nothing and the root itself is the skill.
+#
+# All three shapes follow the plugin manifest reference rather than recall: we
+# resolve declared paths against the plugin root, read `.` and `./` as the root
+# itself, add them to the default `skills/` scan, and take the root as the
+# skill only under the single-skill condition. That condition is honored as
+# written rather than widened, because widening it would suppress the advisory
+# for a command Claude Code does not actually offer. Pointers:
+# https://code.claude.com/docs/en/plugins/manifest-reference#path-rules,
+# https://code.claude.com/docs/en/plugins/manifest-reference#how-each-key-combines-with-its-default-location,
+# https://code.claude.com/docs/en/plugins/manifest-reference#standard-layout.
+# As of: 2026-10-11. Recheck trigger: any of those sections changes the path
+# forms, how declared paths combine with the default location, or the
+# single-skill auto-load condition, or is renamed.
+#
+# Call as: skill_roots <plugin-dir> <declared-paths> -> $roots
+# shellcheck disable=SC2154  # roots is the caller's frame, per the call contract
+skill_roots() {
+  local pdir="$1" declared="$2" rel
+  roots=("$pdir/skills")
+  while IFS= read -r rel; do
+    [[ -n "$rel" ]] || continue
+    rel="${rel#./}"
+    rel="${rel%/}"
+    if [[ -z "$rel" || "$rel" == "." ]]; then roots+=("$pdir"); else roots+=("$pdir/$rel"); fi
+  done <<<"$declared"
+  [[ -z "$declared" && ! -d "$pdir/skills" && -f "$pdir/SKILL.md" ]] && roots+=("$pdir")
+  return 0
+}
+
+# A plugin skill's command segment comes from its frontmatter `name` when set,
+# and from the directory name ONLY when it does not.
+#
+# The directory name is not an alias. A `skills/legacy-dir/SKILL.md` declaring
+# `name: renamed` answers to `/plugin:renamed` and NOT to `/plugin:legacy-dir` —
+# treating the directory as a second valid spelling would suppress the advisory
+# for exactly the stale pre-rename references this guard exists to catch.
+#
+# A directory alone is also not a skill: it must carry a SKILL.md, or a leftover
+# empty `skills/<name>/` would suppress the advisory for a command that never
+# existed.
+#
+# A root may BE a skill directory rather than a directory of them — a declared
+# path can point straight at a directory holding SKILL.md — so each root is tried
+# both ways.
+skill_resolves() {
+  local pdir="$1" skill="$2" declared="$3" root sd sdir fname
+  local -a roots=()
+  skill_roots "$pdir" "$declared"
+  for root in "${roots[@]}"; do
+    if [[ -f "$root/$skill/SKILL.md" ]]; then
+      fname=$(skill_frontmatter_name "$root/$skill/SKILL.md")
+      # No declared name → the directory name IS the command segment.
+      [[ -z "$fname" || "$fname" == "$skill" ]] && return 0
+    fi
+    if [[ -f "$root/SKILL.md" ]]; then
+      fname=$(skill_frontmatter_name "$root/SKILL.md")
+      sdir="${root%/}"
+      if [[ -n "$fname" ]]; then
+        [[ "$fname" == "$skill" ]] && return 0
+      else
+        [[ "${sdir##*/}" == "$skill" ]] && return 0
+      fi
+    fi
+    for sd in "$root"/*/SKILL.md; do
+      [[ -f "$sd" ]] || continue
+      fname=$(skill_frontmatter_name "$sd")
+      [[ -n "$fname" && "$fname" == "$skill" ]] && return 0
+    done
+  done
+  return 1
+}
+
+# Candidate references: `/<plugin>:<skill>` inside inline-code spans only. Prose
+# is not scanned — an unbackticked `/a:b` is as likely to be a URL fragment, a
+# Windows drive path, or a time range as a command.
+#
+# The reference need not be the whole span: an invocation commonly carries
+# arguments (`/plugin:skill --apply`, `/plugin:skill <target>`). Take the leading
+# command token from each span rather than requiring the span to match exactly,
+# or argument-bearing invocations — the common form in this repo — go unchecked.
+emit_refs() {
+  # shellcheck disable=SC2016  # backticks are literal ERE data, not expansions
+  printf '%s' "$SCAN_CONTENT" | grep -oE '`[^`]+`' 2>/dev/null |
+    sed -E 's/^`+//; s/`+$//' |
+    sed -nE 's|^(/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*)([[:space:]].*)?$|\1|p'
+}
+
+# Reconstruction is bounded on four axes, because this hook has a 30s timeout
+# (hooks.json) and a guard that loses its advisory to a timeout has stopped
+# guarding. Two of the four are set from a measured cost curve rather than a
+# round number, because the cost they bound is QUADRATIC and a linear estimate
+# of it is wrong by orders of magnitude at the sizes that matter.
+#
+# One anchor_offsets scan, measured on the slowest host available (Windows/Git
+# Bash, quiescent, best of three) IN THE C LOCALE: 0.07 s at 32 KiB, 0.24 s at
+# 64 KiB, 0.53 s at 96 KiB, 1.07 s at 128 KiB, 2.18 s at 192 KiB, 3.94 s at
+# 256 KiB. That is ~0.065 s x (KiB/32)^2 — bash's `%%` pattern strip walks the
+# string it searches rather than indexing it, so the scan is quadratic in FILE
+# size no matter how short the anchor is. Extrapolated: ~67 s at 1 MiB, ~18
+# minutes at 4 MiB.
+#
+# The locale label is not a footnote: under a UTF-8 locale the same scans cost
+# ~6.5x more. reconstruct_partial_edit pins LC_ALL=C for its own scanning, so C
+# IS the locale these figures describe.
+# Re-checked rather than re-measured, on a second host of the same shape
+# (lightly loaded, not quiescent — ~18% CPU across 32 cores): 0.054 s at 32 KiB,
+# 0.221 s at 64 KiB, 0.880 s at 128 KiB, 3.410 s at 256 KiB — the same curve
+# within host-to-host spread.
+#
+# Those figures are the FLOOR, not the cost: they time an anchor that matches near
+# the end, so one strip walks the file and the second is free. A no-match strip
+# walks it twice (2.31 s at 200 KiB, measured the same way), and the whole-hunk
+# probe pays a scan of its own before the fallback runs at all. Both bounds below
+# are therefore calibrated end to end against the hook, not from that table.
+#
+#   * RECONSTRUCT_MAX_CHARS — above this, reconstruction does not run at all,
+#     because scanning a larger file already spends the hook's budget. Complete
+#     references in the hunk are still reported by the direct scan; only
+#     partial-edit recovery is skipped, which is this guard's permitted failure
+#     direction. 128 KiB is far above any real markdown file this guard reads
+#     (CHANGELOGs, the one shape that grows without bound, are excluded upstream).
+#   * RECONSTRUCT_FALLBACK_SCAN_BUDGET — the per-line fallback scans once per
+#     anchor, so its cap must fall as the file grows, on the same curve: the
+#     anchor cap is this budget divided by (KiB)^2. 60000 holds the whole
+#     invocation near 7 s at every file size on that host — 58 anchors at 32 KiB,
+#     14 at 64 KiB, 3 at 128 KiB. A flat anchor count cannot do this, and neither
+#     can a total-characters budget, which assumes the linear cost this scan does
+#     not have. The end-to-end scale case in the test suite is what holds these
+#     two numbers honest; an earlier pair passed the same case at 21 s of a 30 s
+#     budget, which is a bound in name only.
+#
+# The other two are ordinary counts: a hunk stops contributing once it has
+# yielded this many code spans, far above any real edit given that only spans the
+# anchor reaches are kept; and an anchor stops being counted one occurrence past
+# the cap, which is all the uniqueness gate needs to know.
+#
+# Deferred alternative, with its trigger: replacing the bash search with a
+# linear-time locate would retire the file cap instead of living under it. It is
+# not done here because every portable option is a subprocess whose offsets are
+# BYTES where these are characters, or a line-oriented tool that cannot match a
+# multi-line hunk at all. Revisit if a real markdown file ever exceeds the cap.
+RECONSTRUCT_MAX_CHARS=131072
+RECONSTRUCT_MAX_SPANS=40
+RECONSTRUCT_MAX_OCCURRENCES=40
+RECONSTRUCT_FALLBACK_SCAN_BUDGET=60000
+
+# Append to the caller's $ctx every inline-code span in <region> whose extent
+# OVERLAPS [<hunk-start>, <hunk-end>), and count them in the caller's $nspan.
+#
+# Span boundaries are exactly the ones emit_refs' own `\`[^\`]+\`` finds, so what
+# is kept here and what is parsed there cannot disagree: leftmost match, at least
+# one character between the backticks (an adjacent pair opens nothing), and never
+# across a newline, since grep matches within a line.
+#
+# Call as: collect_overlapping_spans <region> <hunk-start> <hunk-end>
+# shellcheck disable=SC2154  # ctx and nspan are the caller's frame, per the docblock
+collect_overlapping_spans() {
+  local region="$1" hs="$2" he="$3"
+  local i=0 a b rest pre after inner
+  while :; do
+    rest="${region:i}"
+    pre="${rest%%\`*}"
+    # No backtick left in the region — nothing further can open a span.
+    [[ "$pre" == "$rest" ]] && return 0
+    a=$((i + ${#pre}))
+    after="${region:a+1}"
+    inner="${after%%\`*}"
+    # No closing backtick anywhere after this one: no span can open here or later.
+    [[ "$inner" == "$after" ]] && return 0
+    # An empty inner (an adjacent pair) or one spanning a newline is not a match
+    # for grep either; it retries from the next character, so this walk does too.
+    if [[ -z "$inner" || "$inner" == *$'\n'* ]]; then
+      i=$((a + 1))
+      continue
+    fi
+    b=$((a + 1 + ${#inner}))
+    # The span occupies [a, b] inclusive of both backticks; the hunk [hs, he).
+    if ((a < he && b >= hs)); then
+      ctx+="\`$inner\`"$'\n'
+      ((++nspan >= RECONSTRUCT_MAX_SPANS)) && return 0
+    fi
+    i=$((b + 1))
+  done
+}
+
+# Locate every occurrence of <anchor> in the caller's $content, into the caller's
+# $offs. Stops one past the occurrence cap: the uniqueness gate only needs to know
+# whether there is more than one, and `replace_all` stops contributing context at
+# the cap anyway.
+#
+# Occurrences, not matching lines. Counting lines is not enough: two occurrences
+# on one physical line are a single line, and that is a real shape — inserting
+# `legacy` into a line that already carries an untouched `` `/alpha:ghost-legacy` ``
+# leaves the anchor twice on that line, and reporting the reference would be an
+# advisory about text this call never wrote.
+#
+# ONE pattern operation per iteration. `${rest%%"$anchor"*}` both tests and locates:
+# it returns $rest unchanged when there is no match, and a literal `==` on that
+# result is a memcmp, not a second search. Asking `[[ $rest == *"$anchor"* ]]` first
+# and then stripping searched the same text twice, which doubled the cost of the
+# whole-hunk locate — where the anchor is the size of the edit and the search is the
+# dominant term.
+#
+# Call as: anchor_offsets <anchor> -> $offs
+# shellcheck disable=SC2154  # content and offs are the caller's frame, per the call contract
+anchor_offsets() {
+  local anchor="$1" alen=${#1}
+  local rest="$content" base=0 pre
+  offs=()
+  while :; do
+    pre="${rest%%"$anchor"*}"
+    [[ "$pre" == "$rest" ]] && return 0
+    offs+=($((base + ${#pre})))
+    ((${#offs[@]} > RECONSTRUCT_MAX_OCCURRENCES)) && return 0
+    base=$((base + ${#pre} + alen))
+    rest="${content:base}"
+  done
+}
+
+# Partial-replacement context reconstruction (Edit only). The same shape lives in
+# stale-path-verify and cli-flag-verify, which still take the whole located line
+# and filter it by word token; this one keeps only the part of the line the hunk
+# reaches, so the three are not identical.
+#
+# An Edit may replace an arbitrary substring: swapping `setup` for `ghost` inside
+# an existing `/alpha:setup` leaves `/alpha:ghost` on disk, but the hunk is the
+# bare word `ghost` and carries no command for emit_refs to find, so a
+# newly-broken reference would be silently missed.
+#
+# Recover bounded context POSITIONALLY. The edit is already applied by PostToolUse
+# time, so every line of new_string is on disk verbatim and its own text locates
+# the exact span of the file this call wrote. Diff-scope is then an overlap test
+# rather than a word-token heuristic. Two gates:
+#
+#   1. LOCATE by the hunk's own text, never by its tokens, and only where that text
+#      OCCURS exactly once in the file. A unique occurrence IS where the edit
+#      landed. Anything repeated cannot say which copy that was, so it is dropped
+#      rather than unioned. Exception: under `replace_all` every occurrence is a
+#      place this call edited, so all are kept. The hunk is located WHOLE, falling
+#      back to line by line only when the whole no longer matches.
+#   2. KEEP only the inline-code spans whose extent OVERLAPS the located anchor.
+#
+# Gate 2 is what a word-token filter could never be: exact. Sharing a physical line
+# with the hunk is not evidence the edit wrote a reference, so a span the anchor
+# does not reach is dropped no matter how many words it happens to share with the
+# hunk. And overlap has no minimum length to clear, so an Edit replacing two
+# characters inside a command segment is scoped as precisely as one replacing
+# twenty — where the token filter, needing a token long enough to filter on, simply
+# produced none and gave up.
+#
+#   3. Under `replace_all` ONLY, keep an occurrence just when its physical line is
+#      one `structuredPatch` reports the call as having WRITTEN. Gate 1's
+#      uniqueness rule is what separates an edited occurrence from a coincidental
+#      one everywhere else, and `replace_all` is exactly where that rule is
+#      suspended — so it is the one branch that needs an external witness.
+#
+# Gate 3 may only ever REMOVE an occurrence when it can positively identify at
+# least one the call wrote. Comparison is whitespace-normalized, and if the
+# witness recognizes no occurrence at all it abstains and the unfiltered set
+# stands. Both exist for the same reason: an earlier-ordered PostToolUse hook can
+# reformat the file between the write and this read — the case the per-line
+# fallback above was built for — and a witness compared to rewritten text would
+# otherwise turn this gate from a filter into a silent mute, dropping a genuinely
+# written reference. Normalization covers the whitespace reflow formatters
+# actually do; the abstain covers everything else.
+#
+# What this does NOT claim, still. The witness is per LINE, so two references on
+# one physical line stand or fall together, and an untouched line whose text
+# duplicates an edited one verbatim is kept — nothing separates two identical
+# lines. A multi-line `new_string` is not filtered at all: its anchor extent spans
+# several lines and matches no single patch line. Where `structuredPatch` is absent
+# (an older harness, or any payload without `tool_response`) the filter is inert by
+# construction. Every one of those degrades to the pre-gate behavior, which is
+# over-reporting — the direction this guard already accepts — never under-reporting.
+# Reconstruction remains a best effort under an advisory guard, not a proof that
+# every reported line was written by this call; it simply no longer reports a line
+# the payload itself says was untouched.
+#
+# Cost is ONE read of the file and, normally, ONE scan of it — no subprocess per
+# hunk line and no rescan per hunk line either. The `grep` this replaced spawned two
+# processes per line of the hunk; scanning in-memory removed the processes but left
+# the per-line rescan, which is anchors TIMES file size and still spent the timeout
+# on a thousand-line hunk. Locating the hunk whole is what removes the factor; the
+# scanning budget bounds the fallback that cannot.
+# The physical line an anchor occurrence sits in: back to the newline before it,
+# forward to the newline after. A reference the edit landed inside is only whole
+# when read from the line, not from the anchor alone — which is why the line is
+# read at all, and why only the part of it the anchor reaches may be kept.
+#
+# Reads the caller's $content, $alen; sets the caller's $line, $hs, $he. Written
+# as a function because Gate 3 needs the line one pass before the span walk does,
+# and computing it twice from two copies of this arithmetic is how the two drift.
+# Call as: anchor_line <offset> -> $line $hs $he
+# shellcheck disable=SC2154  # content/alen/line/hs/he are the caller's frame, per the call contract
+anchor_line() {
+  local off="$1" head tail
+  head="${content:0:off}"
+  head="${head##*$'\n'}"
+  hs=${#head}
+  tail="${content:off+alen}"
+  tail="${tail%%$'\n'*}"
+  he=$((hs + alen))
+  line="${content:off-hs:he+${#tail}}"
+}
+
+# Whitespace-normalized form of <text>, for comparing a line on disk against the
+# line `structuredPatch` recorded at edit time. Tabs become spaces, runs collapse,
+# ends are trimmed.
+#
+# Comparing raw text made Gate 3 undo the reformatting tolerance the fallback
+# above exists to provide: a downstream PostToolUse hook that reflows whitespace
+# leaves the anchor locatable (a literal substring search does not care what
+# surrounds it) while changing the physical line, so a genuinely written reference
+# was dropped. Whitespace is what formatters move; normalizing it keeps the
+# witness usable without weakening what it discriminates, since a DIFFERENT
+# reference's line differs by far more than spacing.
+#
+# No subshell: this runs once per occurrence, and `$(…)` here would fork per line.
+# Call as: norm_ws <text> -> $NORM_WS
+norm_ws() {
+  local s="${1//$'\t'/ }"
+  while [[ "$s" == *"  "* ]]; do s="${s//  / }"; done
+  s="${s#"${s%%[![:space:]]*}"}"
+  NORM_WS="${s%"${s##*[![:space:]]}"}"
+}
+
+reconstruct_partial_edit() {
+  [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0
+  # Pin the locale this function's own scanning runs in, so its matcher semantics
+  # and its cost are the consumer's ambient locale's business no longer. Every
+  # search below is LITERAL, so a multibyte locale buys this function nothing and
+  # charges it ~6.5x: one no-match scan, measured on a lightly-loaded Windows/Git
+  # Bash host (bash 5.3, 32 logical cores at ~18%), costs 0.054 s at 32 KiB / 0.221 s
+  # at 64 KiB / 0.880 s at 128 KiB under C, against 0.395 s / 1.447 s / 5.786 s
+  # under en_US.UTF-8. That ratio is the reason for the pin; no wall-clock BOUND
+  # is claimed from it, and the caps above are calibrated end to end against the
+  # hook rather than off that table, so this is not a correction to them.
+  #
+  # `+x` is load-bearing, not decoration. The whole ~6.5x is bash's OWN `%%`
+  # walk; the child processes are locale-insensitive here (`grep -oE` on the same
+  # 64 KiB measured 0.139 s under BOTH locales), so exporting the pin would buy
+  # nothing and cost real behavior: `[[:space:]]` is ASCII-only under C but admits
+  # some non-ASCII spaces under a UTF-8 locale, so an exported pin would make
+  # emit_refs below drop a reference whose argument separator is one of them, and
+  # would make the blank-line filter keep an anchor line it used to discard.
+  # Un-exported, children run in the caller's locale exactly as before, and nothing
+  # they emit changes. Nothing needs them pinned either: no offset ever crosses a
+  # process boundary — the fallback's grep yields anchor STRINGS and emit_refs
+  # consumes a context STRING.
+  #
+  # WHICH separators those are is the host C library's table, not this hook's, and
+  # it is not portable: glibc dropped U+00A0 and U+202F from `space` in 2.26, while
+  # Cygwin/MSYS still classifies them; U+3000 and U+2028 are admitted by both.
+  # Measured. The regression case DISCOVERS a separator this host actually
+  # classifies differently rather than hardcoding one: a hardcoded byte (U+00A0,
+  # say) passes on one platform and fails on another, asserting a libc's table
+  # rather than this hook's behavior.
+  #
+  # Scope and lifetime were verified rather than assumed: assigning LC_ALL re-runs
+  # setlocale even for a `local` (and even with `+x`), and bash restores the
+  # previous value AND its export attribute on return, including when the consumer
+  # exported LC_ALL itself.
+  #
+  # Safe because every offset this function computes is also consumed by it: the
+  # unit is bytes here and characters outside, and the two never meet. Slices are
+  # taken only at a literal match or at a newline, and no UTF-8 multibyte sequence
+  # contains an ASCII byte, so a byte slice never splits a character.
+  # RECONSTRUCT_MAX_CHARS is therefore read as bytes, the stricter of the two
+  # readings, so it cannot raise the ceiling it exists to set, and the fallback's
+  # KiB estimate stops understating a multibyte file and over-granting its anchor
+  # cap. Both shifts are toward less work, never more.
+  local +x LC_ALL=C
+  local content
+  content=$(<"$FILE") || return 0
+  # Gate on the size BEFORE touching the string: every step past this point is a
+  # whole-string operation, so a gate that runs after one of them has left that one
+  # unbounded. Measuring the raw text rather than the normalized text also errs
+  # toward not reconstructing, which is the safe direction here.
+  ((${#content} <= RECONSTRUCT_MAX_CHARS)) || return 0
+  # new_string arrived with CR stripped, so a CRLF file must be searched the same
+  # way or no anchor would ever locate. Offsets are read back off this normalized
+  # text only, never off the bytes on disk.
+  content=${content//$'\r'/}
+
+  local ctx="" nspan=0 anchor alen off hs he line cap kib located_whole=0
+  local -a offs=() anchors=() keep=()
+
+  # Gate 3's witness set: the physical lines `structuredPatch` reports this call as
+  # having written, as a hash. Built only where it is consulted — under
+  # `replace_all`, whose suspended uniqueness rule is the reason an external
+  # witness is needed at all. Empty (no `tool_response`, or a patch with no added
+  # lines) leaves the filter inert, which is the pre-existing behavior.
+  local -A wrote=()
+  local filter_wrote=0 wl NORM_WS
+  if [[ "$REPLACE_ALL" == "true" && -n "$EDIT_WROTE_LINES" ]]; then
+    while IFS= read -r wl; do
+      # Keys are whitespace-normalized, matching how the on-disk line is compared,
+      # and carry a literal prefix so a patch line reading `@` or `*` cannot alias
+      # bash's own array subscripts on lookup.
+      norm_ws "$wl"
+      wrote["L$NORM_WS"]=1
+    done <<<"$EDIT_WROTE_LINES"
+    ((${#wrote[@]})) && filter_wrote=1
+  fi
+
+  # The hunk is written to disk CONTIGUOUSLY, so locate it WHOLE first — one scan
+  # for the entire edit instead of one per line. The loop below is then driven by a
+  # single anchor, and the span set it produces is the same one the per-line walk
+  # produced: an anchor's extent is the text the edit wrote on its own line, and the
+  # whole hunk's extent is the union of exactly those. Multi-line is no obstacle —
+  # the extent is bounded by offset, and a code span never crosses a newline.
+  anchor_offsets "$SCAN_CONTENT"
+  if ((${#offs[@]})) && { [[ "$REPLACE_ALL" == "true" ]] || ((${#offs[@]} == 1)); }; then
+    anchors=("$SCAN_CONTENT")
+    # $offs already holds this anchor's offsets; the loop must not pay for them twice.
+    located_whole=1
+  else
+    # FALLBACK, for a hunk that is no longer on disk verbatim — another PostToolUse
+    # hook may have reformatted the file between the write and this read — or one
+    # whose whole text repeats. Individual lines can still locate, so walk them; the
+    # budget is what keeps that walk from costing anchors TIMES file size.
+    mapfile -t anchors < <(printf '%s' "$SCAN_CONTENT" | grep -vE '^[[:space:]]*$' 2>/dev/null)
+    ((${#anchors[@]})) || return 0
+    kib=$(((${#content} + 1023) / 1024))
+    ((kib < 1)) && kib=1
+    cap=$((RECONSTRUCT_FALLBACK_SCAN_BUDGET / (kib * kib)))
+    ((cap < 1)) && cap=1
+    ((${#anchors[@]} > cap)) && anchors=("${anchors[@]:0:cap}")
+  fi
+
+  # A repeated anchor line resolves identically every time, so scan each once.
+  declare -A seen=()
+  for anchor in "${anchors[@]}"; do
+    alen=${#anchor}
+    ((alen)) || continue
+    [[ -n "${seen[$anchor]:-}" ]] && continue
+    seen["$anchor"]=1
+    if ((located_whole)); then located_whole=0; else anchor_offsets "$anchor"; fi
+    ((${#offs[@]})) || continue
+    # A non-unique anchor cannot say WHICH occurrence the edit landed on, so it is
+    # dropped rather than unioned. Cost: a missed advisory when an edit lands in
+    # text that repeats verbatim elsewhere in the file. For a detect-then-judge
+    # guard that is the right side of the trade — it is degraded far worse by being
+    # wrong when it speaks than by staying quiet.
+    [[ "$REPLACE_ALL" == "true" ]] || ((${#offs[@]} == 1)) || continue
+
+    # Gate 3, applied BEFORE the span walk so it can abstain as a whole.
+    #
+    # A MULTI-LINE anchor's extent is not a single physical line and can match no
+    # patch line, so that shape is never filtered.
+    keep=("${offs[@]}")
+    if ((filter_wrote)) && [[ "$anchor" != *$'\n'* ]]; then
+      keep=()
+      for off in "${offs[@]}"; do
+        anchor_line "$off"
+        norm_ws "$line"
+        [[ -n "${wrote[L$NORM_WS]:-}" ]] && keep+=("$off")
+      done
+      # ABSTAIN. If the witness recognized NOTHING, it is stale rather than
+      # discriminating — a downstream PostToolUse hook rewrote the lines between
+      # the write and this read, which is the very case the fallback above exists
+      # for. Letting a stale witness exclude every occurrence would turn this gate
+      # into a silent mute. Falling back to the unfiltered set is exactly the
+      # behavior that shipped before this gate, so the gate can only ever remove
+      # occurrences when it can positively identify at least one the call wrote.
+      ((${#keep[@]})) || keep=("${offs[@]}")
+    fi
+
+    for off in "${keep[@]}"; do
+      anchor_line "$off"
+      collect_overlapping_spans "$line" "$hs" "$he"
+      ((nspan >= RECONSTRUCT_MAX_SPANS)) && break 2
+    done
+  done
+  [[ -n "$ctx" ]] || return 0
+
+  local saved="$SCAN_CONTENT"
+  SCAN_CONTENT="$ctx"
+  emit_refs
+  SCAN_CONTENT="$saved"
+}
+
+declare -A CHECKED=()
+UNRESOLVED=()
+REFS=()
+mapfile -t REFS < <(emit_refs)
+# Reconstruction runs on EVERY Edit, not only when the hunk yielded nothing. One
+# hunk can both carry a complete reference and change a substring inside another
+# (`setup and placeholder` -> `ghost` plus a literal `/alpha:setup`), so gating on
+# an empty REFS would miss the partial half. Duplicates are harmless — CHECKED
+# dedupes below.
+if [[ "$TOOL" == "Edit" ]]; then
+  mapfile -t -O "${#REFS[@]}" REFS < <(reconstruct_partial_edit)
+fi
+
+((${#REFS[@]})) && build_plugin_index
+
+for ref in "${REFS[@]}"; do
+  [[ -n "$ref" ]] || continue
+  [[ -n "${CHECKED[$ref]:-}" ]] && continue
+  CHECKED["$ref"]=1
+  plugin="${ref#/}"
+  plugin="${plugin%%:*}"
+  skill="${ref##*:}"
+  # PLUGIN-SCOPE GATE: only adjudicate a plugin this repo owns.
+  pdir="${PLUGIN_DIR[$plugin]:-}"
+  [[ -n "$pdir" ]] || continue
+  skill_resolves "$pdir" "$skill" "${PLUGIN_SKILL_PATHS[$plugin]:-}" && continue
+  UNRESOLVED+=("$ref")
+done
+
+emit_tel() {
+  [[ -n "$start" ]] || return 0
+  hook::telemetry_enabled || return 0
+  # The helper carries the redaction: a path it could not make repo-relative
+  # comes back as the basename, never an absolute path, which would embed the
+  # developer's username.
+  local findings_json="[]" file_rel
+  file_rel=""
+  hook::repo_relative_path_to file_rel "$FILE" "$REPO_ROOT"
+  if ((${#UNRESOLVED[@]} > 0)); then
+    findings_json=$(printf '%s\n' "${UNRESOLVED[@]}" | jq -Rn '[inputs]' 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 "skill-reference-verify" "PostToolUse" "ok" "$start" "$data" "$REPO_ROOT"
+}
+
+if ((${#UNRESOLVED[@]} > 0)); then
+  # The file as the model names it: repo-relative when it sits under the root
+  # spelled the same way, else as given. Outside a repo the root is the file's
+  # own directory, and a bare name would name a different file.
+  show_file="$FILE"
+  ((REPO_ROOT_RESOLVED)) && [[ "$FILE" == "${REPO_ROOT%/}/"?* ]] && show_file="${FILE#"${REPO_ROOT%/}/"}"
+  lines=""
+  # Name the directories the search ACTUALLY covered, from the same skill_roots
+  # the resolution used. Naming only `skills/` understates the search for a plugin
+  # whose manifest declares paths, and the advisory ends by telling the reader to
+  # confirm against the tree — pointing them at the wrong part of it is the one
+  # thing that instruction cannot survive. For the conventional layout this still
+  # renders exactly `plugins/<plugin>/skills/`.
+  declare -a roots=()
+  for r in "${UNRESOLVED[@]}"; do
+    plugin="${r#/}"
+    plugin="${plugin%%:*}"
+    skill_roots "${PLUGIN_DIR[$plugin]}" "${PLUGIN_SKILL_PATHS[$plugin]:-}"
+    searched=""
+    for root in "${roots[@]}"; do
+      searched+="${searched:+, }plugins/${root#"$PLUGINS_DIR/"}/"
+    done
+    lines+="$r (no such skill under $searched)"$'\n'
+  done
+  srv_ctx=""
+  hook::findings_to srv_ctx \
+    "skill-reference-verify: skill reference(s) in $show_file do not resolve; this repo owns the plugin:" \
+    "$lines" --max 10
+  hook::ctx_append "$srv_ctx"
+  hook::ctx_append "A reference kept on purpose (a rename record, another marketplace's skill) is correct as written."
+  hook::ctx_flush PostToolUse
+fi
+
+emit_tel
+exit 0
diff --git a/.githooks/guardrails/stale-path-verify.sh b/.githooks/guardrails/stale-path-verify.sh
new file mode 100755
index 0000000000..65278ae661
--- /dev/null
+++ b/.githooks/guardrails/stale-path-verify.sh
@@ -0,0 +1,908 @@
+#!/usr/bin/env bash
+# PostToolUse hook: verify that a repo-relative path cited in newly-written
+# markdown is not one this repository has since removed.
+# Triggered on Write|Edit of *.md files.
+#
+# ORACLE: disappearance, not absence. A finding requires the repository to prove
+# it once owned the path — the exact repo-relative path must appear in the set
+# of paths deleted across HEAD's history AND be gone from the working tree now.
+# Absence on its own is evidence of nothing: `docs/`, `scripts/`, `lib/`,
+# `.claude/` are conventional names shared by every repo that uses them, so a
+# path's SHAPE can never establish that it was a claim about THIS tree. Only
+# history can.
+#
+# ENFORCEABILITY TIER: Detect-then-judge — ADVISORY PLUS A HUMAN VERDICT, never
+# an auto-fix. The oracle is mechanical, but the conclusion is not: a doc may
+# cite a removed path deliberately, as a deletion or completion record, and such
+# a citation is correct exactly as written. Per the org convention on
+# enforceability tiers that makes the finding a prompt for a decision, not a
+# determination.
+#
+# WHAT THIS STRUCTURALLY CANNOT CATCH: a hallucinated path. An invented path was
+# never in this repository, so it never enters the deleted-path set and this
+# guard stays silent by construction. That class needs a signal this oracle does
+# not have — something separating "asserted about THIS tree" from "documented
+# about a consumer's tree", such as an explicit marker convention for
+# consumer-tree examples. Absent that signal it stays out of scope, because a
+# hallucinated path and a correctly-documented consumer path are the same
+# observation: absent locally, conventionally shaped.
+#
+# SCOPE: inline code spans only. Markdown link destinations are out — on-disk
+# link integrity belongs to the repo's offline link checker, and under this
+# oracle no link-kind candidate contributes a finding anyway.
+#
+# NON-BLOCKING (advisory): exits 0 with hookSpecificOutput additionalContext.
+#
+# Disable with the stale_path_verify_enabled userConfig option set to false.
+
+set -uo pipefail
+
+# High-res start stamp for telemetry (Bash 5.0+; empty on older bash → skip).
+start=${EPOCHREALTIME:-}
+
+# Kill switch FIRST, before any library is sourced: a disabled hook must not
+# pay to parse hook-utils.sh to learn it is off. Same predicate as
+# hook::is_enabled; scripts/check-killswitch-hoist.sh pins the two together.
+[[ "${CLAUDE_PLUGIN_OPTION_STALE_PATH_VERIFY_ENABLED:-true}" == "true" ]] || exit 0
+
+# The hook's own directory is derived with parameter expansion rather than
+# `dirname`. GNU Bash forks a subshell for every command substitution even when
+# the body is a builtin (Command Substitution, Bash Reference Manual;
+# https://mywiki.wooledge.org/CommandSubstitution). On Windows Git Bash that
+# fork is a process, and this line runs on every fire — including inside the
+# dispatcher, where the include guard makes `source` cheap but `$(dirname …)`
+# still execs. `${BASH_SOURCE[0]%/*}` equals `dirname` for every shape
+# BASH_SOURCE takes; the fallback covers a bare filename, where the strip is a
+# no-op and dirname answers `.`.
+_HOOK_SELF="${BASH_SOURCE[0]%/*}"
+[[ "$_HOOK_SELF" == "${BASH_SOURCE[0]}" ]] && _HOOK_SELF=.
+# shellcheck source=abort-boundary.sh
+source "$_HOOK_SELF/abort-boundary.sh"
+# Could-not-run posture (#3528): fail-open with a dual-channel "guard did not
+# run" notice; 0 is the only status this advisory verifier chooses. Nothing is
+# enforced here, so the loss on an abort is the advisory itself.
+guard::abort_boundary stale-path-verify PostToolUse open 0
+# shellcheck source=hook-utils.sh
+source "$_HOOK_SELF/hook-utils.sh" || exit 70 # not a chosen status: the boundary reports it
+
+hook::ctx_reset
+
+hook::buffer_stdin_to INPUT || exit 0
+
+hook::require jq "PostToolUse" guardrails "$INPUT"
+
+FILE=""
+hook::read_file_path_to FILE "$INPUT" || exit 0
+case "$FILE" in
+# A CHANGELOG is an append-only historical record, and this oracle selects
+# precisely for removed paths — precisely what such a record documents. Mirrors
+# skill-reference-verify's exclusion for the same reason.
+*/CHANGELOG.md | CHANGELOG.md) exit 0 ;;
+*.md) ;;
+# Code files are out of scope: a path literal in a script resolves against the
+# runtime CWD, not the repo root, so a repo-root existence test is the wrong
+# oracle there.
+*) exit 0 ;;
+esac
+
+# Diff-scope: verify only the content THIS tool call wrote, never re-read the
+# whole file from disk. An Edit's pre-existing lines outside the changed hunk are
+# not this call's claims.
+#
+# Every payload field this hook can need, in ONE jq process (hook::jq_fields),
+# not three — a jq spawn is fork() emulation on Windows Git Bash. Both per-tool
+# content fields and replace_all are fetched together because selecting between
+# them would cost another process; jq reads the same envelope either way, and the
+# tool-specific choice happens below in the shell. `replace_all` keeps its
+# `// false | tostring` INSIDE the filter: hook::jq_fields wraps each filter in
+# `// ""`, and jq's `//` treats the boolean false as empty, so a bare
+# `.tool_input.replace_all` would come back "" instead of "false". That is kept
+# for parity with the pre-conversion output, not because a branch depends on it
+# — every consumer below tests `== "true"`, which "" and "false" fail alike.
+# Failure semantics are unchanged: a missing jq or an unparsable payload yields
+# rc 1 here, which exits 0 exactly as the unmatched-TOOL case did —
+# hook::require jq above has already made the degraded state visible once per
+# session and agent.
+hook::jq_fields "$INPUT" '.tool_name' '.tool_input.new_string' \
+  '.tool_input.content' '.tool_input.replace_all // false | tostring' || exit 0
+TOOL="${HOOK_JQ_FIELDS[0]}"
+# replace_all feeds reconstruction's uniqueness gate below: under replace_all
+# the same new_string landing in several places is the edit's own footprint
+# rather than an ambiguity. Relay: the pointer record for the Edit tool's
+# uniqueness rule sits beside the `replace_all` field in
+# skill-reference-verify.sh. As of: 2026-10-11. Recheck trigger: that record
+# leaves skill-reference-verify.sh or stops naming this file as one it serves,
+# or its own recheck trigger fires.
+REPLACE_ALL=false
+case "$TOOL" in
+Edit)
+  SCAN_CONTENT="${HOOK_JQ_FIELDS[1]}"
+  REPLACE_ALL="${HOOK_JQ_FIELDS[3]}"
+  case "$REPLACE_ALL" in
+  true | false) ;;
+  *)
+    # Advisory guard: a malformed replace_all extraction must not wear the permissive
+    # "false" branch. Well-formed payloads always stringify to true/false; anything
+    # else is an unreadable field — skip verification rather than guess.
+    exit 0
+    ;;
+  esac
+  ;;
+Write) SCAN_CONTENT="${HOOK_JQ_FIELDS[2]}" ;;
+*) exit 0 ;;
+esac
+[[ -n "$SCAN_CONTENT" ]] || exit 0
+
+# Parameter expansion, not a `$(dirname …)` subshell: this hook runs on every
+# Write and Edit, and a command substitution is a fork per call on Windows Git
+# Bash. The anchor is still the FILE's own directory, with `dirname`'s answers:
+# no slash -> `.`, and a root-level `/x` -> `/` rather than the empty string,
+# which hook::repo_root would read as `.`.
+FILE_DIR="${FILE%/*}"
+[[ "$FILE_DIR" == "$FILE" ]] && FILE_DIR="."
+[[ -n "$FILE_DIR" ]] || FILE_DIR=/
+REPO_ROOT=""
+hook::repo_root_to REPO_ROOT "$FILE_DIR"
+[[ -d "$REPO_ROOT" ]] || exit 0
+
+# Inline-code spans, backticks stripped. Prose is deliberately NOT scanned: an
+# unquoted `a/b` in a sentence is as likely to be a ratio, a date, or an
+# either/or as a path.
+emit_tokens() {
+  # shellcheck disable=SC2016  # backticks are literal ERE data, not expansions
+  printf '%s' "$SCAN_CONTENT" | grep -oE '`[^`]+`' 2>/dev/null |
+    sed -E 's/^`+//; s/`+$//'
+}
+
+# Builtin twins of this file's grep/sed/sort pipelines, which cost up to nine
+# processes on a .md Edit. They answer only for text made of printable ASCII
+# and whitespace: there a character is a byte, a line ends at \n, and grep, sed
+# and bash read every bracket class the same way in any locale, so each twin
+# gives the pipeline's answer. Any other byte (non-ASCII, a control character)
+# keeps the pipeline. The twins run under LC_ALL=C (hook::_c_locale), so their
+# ranges are ASCII ranges on every bash. Each fills the SPV_OUT array.
+# shellcheck disable=SC2329 # reached through hook::_c_locale
+spv__plain() { [[ "$1" != *[![:print:][:space:]]* ]]; }
+spv_plain() { hook::_c_locale spv__plain "$1"; }
+# The occurrence counter's word-anchor test (no space, ASCII word start, then
+# ASCII word characters, dots and dashes).
+# shellcheck disable=SC2329 # reached through hook::_c_locale
+spv__word_anchor() { [[ "$1" != *' '* && "$1" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; }
+# spv_word_occurrences <word-anchor> <file>: how many maximal [A-Za-z0-9_] runs
+# in <file> equal the anchor, bytes under C.
+spv_word_occurrences() {
+  HOOK_ANCHOR="$1" LC_ALL=C awk '
+    BEGIN { a = ENVIRON["HOOK_ANCHOR"]; n = 0 }
+    {
+      k = split($0, w, /[^A-Za-z0-9_]+/)
+      for (j = 1; j <= k; j++) if (w[j] == a) n++
+    }
+    END { print n + 0 }
+  ' "$2"
+}
+
+# spv_anchor_occurrences <anchor> <file>: how many times <anchor> starts in
+# <file>, overlapping starts included. The advance is one byte past each start,
+# awk's `p = p + i` when `i` is the 1-based index() of an ASCII anchor. No
+# process: the previous counter was an awk over the whole file on every
+# non-word anchor, including a path that contains `/`.
+spv_anchor_occurrences() {
+  local anchor="$1" file="$2" line rest prefix n=0
+  [[ -n "$anchor" && -f "$file" ]] || {
+    printf '0'
+    return 0
+  }
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    rest=$line
+    while [[ -n "$rest" ]]; do
+      prefix=${rest%%"$anchor"*}
+      [[ "$prefix" == "$rest" ]] && break
+      n=$((n + 1))
+      rest=${rest:$((${#prefix} + 1))}
+    done
+  done <"$file"
+  printf '%s' "$n"
+}
+
+# spv__lines <text>: SPV_LINES = <text>'s non-empty lines.
+# shellcheck disable=SC2329 # reached through hook::_c_locale
+spv__lines() {
+  local IFS=$'\n' noglob=0
+  [[ $- == *f* ]] && noglob=1
+  set -f
+  # shellcheck disable=SC2206 # splitting on newlines is the intent
+  SPV_LINES=($1)
+  ((noglob)) || set +f
+}
+
+# `grep -oE '`[^`]+`' | sed -E 's/^`+//; s/`+$//'`: per line, the leftmost
+# backtick opens a span when a non-empty run of non-backticks and a closing
+# backtick follow it, and the scan resumes after the closing one; otherwise the
+# next backtick is tried as the opener.
+# shellcheck disable=SC2329 # reached through hook::_c_locale
+spv__spans() {
+  SPV_OUT=()
+  local line rest tok
+  [[ "$1" == *'`'*'`'* ]] || return 0
+  spv__lines "$1"
+  for line in ${SPV_LINES[@]+"${SPV_LINES[@]}"}; do
+    rest=$line
+    while [[ "$rest" == *'`'*'`'* ]]; do
+      rest=${rest#*'`'}
+      tok=${rest%%'`'*}
+      [[ -n "$tok" ]] || continue
+      SPV_OUT+=("$tok")
+      rest=${rest#*'`'}
+    done
+  done
+}
+
+# `sed -E 's/`[^`]*`//g' | grep -oE '[A-Za-z0-9][A-Za-z0-9._-]{1,}' | sort -u`,
+# as a set: per line, backtick pairs are removed left to right; in what is left,
+# every maximal run of [A-Za-z0-9._-] yields its text from the first
+# alphanumeric on, when that is at least two characters. Order is not kept; the
+# one caller only tests membership.
+# shellcheck disable=SC2329 # reached through hook::_c_locale
+spv__residue_tokens() {
+  SPV_OUT=()
+  local line rest out w
+  local -A seen=()
+  local -a words=()
+  spv__lines "$1"
+  for line in ${SPV_LINES[@]+"${SPV_LINES[@]}"}; do
+    out="" rest=$line
+    while [[ "$rest" == *'`'*'`'* ]]; do
+      out+=${rest%%'`'*}
+      rest=${rest#*'`'}
+      rest=${rest#*'`'}
+    done
+    out+=$rest
+    out=${out//[^A-Za-z0-9._-]/ }
+    IFS=' ' read -r -a words <<<"$out"
+    for w in ${words[@]+"${words[@]}"}; do
+      w=${w#"${w%%[A-Za-z0-9]*}"}
+      ((${#w} >= 2)) || continue
+      [[ -n "${seen[$w]:-}" ]] && continue
+      seen[$w]=1
+      SPV_OUT+=("$w")
+    done
+  done
+}
+
+# `grep -vE '^[[:space:]]*$' | head -<max>`: the non-blank lines, at most <max>.
+# shellcheck disable=SC2329 # reached through hook::_c_locale
+spv__nonblank() {
+  SPV_OUT=()
+  local line
+  spv__lines "$1"
+  for line in ${SPV_LINES[@]+"${SPV_LINES[@]}"}; do
+    [[ "$line" == *[![:space:]]* ]] || continue
+    SPV_OUT+=("$line")
+    ((${#SPV_OUT[@]} < ${2:-2147483647})) || break
+  done
+}
+
+# emit_tokens' lines into SPV_OUT.
+spv_tokens() {
+  if spv_plain "$SCAN_CONTENT"; then
+    hook::_c_locale spv__spans "$SCAN_CONTENT"
+  else
+    mapfile -t SPV_OUT < <(emit_tokens)
+  fi
+}
+
+# Tracked-file list, read at most once per run and reused by root-basename
+# ambiguity and moved-file hint enrichment.
+TRACKED_FILES=""
+TRACKED_BUILT=0
+ensure_tracked_files() {
+  if ((TRACKED_BUILT == 0)); then
+    local out git_dir="" index="" cache="" n
+    local -a cached_lines=()
+    # Reuse the list only while the cache is strictly newer than the index, so
+    # a same-tick index rewrite is not trusted.
+    if spv_git_dir_to git_dir; then
+      index="$git_dir/index"
+      cache="$git_dir/guardrails-ls-files"
+    fi
+    if [[ -n "$cache" && -f "$cache" && -f "$index" && "$cache" -nt "$index" ]]; then
+      # One path per line, then `end <count>`. A parallel fire can be rewriting
+      # this file, and two writers that both truncate leave a mix of their bytes,
+      # so a file that is not exactly that shape is a miss. The count must equal
+      # the lines read, and a second sentinel-shaped line marks a mix.
+      mapfile -t cached_lines <"$cache"
+      n=$((${#cached_lines[@]} - 1))
+      if ((n >= 0)) && [[ "${cached_lines[n]}" == "end $n" ]]; then
+        local IFS=$'\n'
+        out="${cached_lines[*]:0:n}"
+        if [[ $'\n'"$out" != *$'\n'"end "[0-9]* ]]; then
+          TRACKED_FILES=$out
+          TRACKED_BUILT=1
+          return 0
+        fi
+      fi
+    fi
+    if out=$(git -C "$REPO_ROOT" ls-files 2>/dev/null); then
+      TRACKED_FILES=${out//$'\r'/}
+      TRACKED_BUILT=1
+      if [[ -n "$cache" ]]; then
+        # The whole file goes out in one printf, sentinel included, built in
+        # memory: a temp file plus mv would add a process to every cold write.
+        # mapfile counts the lines; `${x//[!$'\n']/}` is quadratic in bash.
+        n=0
+        out=""
+        if [[ -n "$TRACKED_FILES" ]]; then
+          mapfile -t cached_lines <<<"$TRACKED_FILES"
+          n=${#cached_lines[@]}
+          out=$TRACKED_FILES$'\n'
+        fi
+        printf '%send %d\n' "$out" "$n" 2>/dev/null >"$cache" || :
+      fi
+    fi
+  fi
+}
+
+# The tracked files whose basename equals <base>, into the caller's $matches.
+# Returns 1 when no tracked-file list could be read, leaving $matches empty; both
+# callers admit the citation in that case rather than judge it on a list they do
+# not have.
+#
+# Call as: tracked_basename_matches <base> -> $matches
+# shellcheck disable=SC2154  # matches is the caller's frame, per the call contract
+tracked_basename_matches() {
+  matches=()
+  ensure_tracked_files
+  [[ -n "$TRACKED_FILES" ]] || return 1
+  mapfile -t matches < <(printf '%s\n' "$TRACKED_FILES" | awk -F/ -v b="$1" '$NF == b')
+}
+
+# Root-level inline-code tokens (no '/') are admitted only when the basename is
+# referentially unambiguous — not when it names a class of file every repo has.
+# The discriminator is two-part, not a length or extension heuristic:
+#   (1) an enumerated set of semantically-generic root filenames that prose cites
+#       by kind rather than by location (`README.md`, `package.json`, …), and
+#   (2) more than one tracked file in this repo carrying the same basename, which
+#       makes a bare `` `name` `` referentially opaque even inside a code span.
+# Returns 0 (ambiguous → reject) or 1 (unambiguous → admit).
+root_basename_is_ambiguous() {
+  local base="$1"
+  local -a matches=()
+  case "$base" in
+  README.md | README | package.json | package-lock.json | LICENSE | LICENCE | CHANGELOG.md | Makefile | GNUmakefile | .gitignore | .gitattributes | .editorconfig) return 0 ;; # both license-file spellings are matched on purpose # spellchecker:disable-line
+  *) ;;
+  esac
+  tracked_basename_matches "$base" || return 1
+  ((${#matches[@]} > 1))
+}
+
+# Reduce a raw token to a repo-relative path candidate, or nothing.
+# Sets NORM_CAND in this shell. Empty when the token is not a candidate.
+# In-process on purpose: a command substitution would discard the tracked-file
+# cache this function fills, and the next candidate would list the repo again.
+normalize_candidate() {
+  local t="$1"
+  NORM_CAND=""
+
+  # A code span can hold a whole command; take only single-token spans. NOT
+  # because a path cannot contain whitespace — git permits spaces in pathnames —
+  # but because a whitespace-bearing span is far likelier to be a command than a
+  # path, and reading one as a path adjudicates its arguments: the suite pins
+  # `cp docs/gone.md docs/real.md` staying quiet even though it names a genuinely
+  # deleted path. The cost is that a spaced deleted path is never adjudicated;
+  # admitting one needs a discriminator against command spans, tracked in #1452.
+  [[ "$t" =~ [[:space:]] ]] && return 0
+
+  # Strip a trailing line/range citation suffix — this repo cites
+  # `docs/migration-playbook.md:576-580` and `SKILL.md:24` pervasively.
+  t="${t%%:[0-9]*}"
+
+  # Strip a trailing markdown-anchor fragment.
+  t="${t%%#*}"
+
+  # Strip surrounding and trailing prose punctuation.
+  t="${t#[\'\"\(]}"
+  t="${t%[\'\"\),;.]}"
+
+  # Leading ./ is the same path.
+  t="${t#./}"
+
+  local is_root=0
+  [[ "$t" == */* ]] || is_root=1
+
+  # Reject anything that is not a literal repo-relative path.
+  case "$t" in
+  # URLs, protocol-relative, mail, and anchors.
+  *://* | //* | mailto:* | \#*) return 0 ;;
+  # Absolute POSIX and Windows paths — hardcoded-path-check owns those.
+  /* | [A-Za-z]:[/\\]*) return 0 ;;
+  # Home-relative.
+  '~'*) return 0 ;;
+  # A repo-root-relative citation has nothing to ascend from.
+  ../* | */../*) return 0 ;;
+  # Glob, brace, or placeholder metacharacters — a pattern, not an assertion.
+  *'*'* | *'?'* | *'['* | *']'* | *'{'* | *'}'* | *'<'* | *'>'* | *'$'* | *'('* | *')'* | *'|'* | *'!'*) return 0 ;;
+  # Ellipsis stand-ins.
+  *...*) return 0 ;;
+  # Vendor and build trees are not tracked; their absence proves nothing.
+  node_modules/* | */node_modules/* | .git/* | */.git/*) return 0 ;;
+  *) ;;
+  esac
+
+  local last="${t##*/}"
+  if ((is_root)); then
+    # Deleted root-level paths such as `CONTRIBUTING.md` are valid repo-relative
+    # citations; admit them only when root_basename_is_ambiguous says the token is
+    # referentially unambiguous. Generic root names and multiply-occurring basenames
+    # stay out — see #1446.
+    root_basename_is_ambiguous "$t" && return 0
+    [[ "$last" == *.* ]] || return 0
+  else
+    # A bare directory reference with no extension and no trailing slash is
+    # ambiguous with a namespace, a module path, or a URL path fragment.
+    #
+    # A TRAILING SLASH clears that ambiguity but buys no finding: git records file
+    # deletions, never directory ones, so no DELETED key can ever carry a slash and
+    # the exact provenance lookup below can never match `docs/old/`. An absent
+    # directory citation therefore only ever reaches ABSENT — enough to trip the
+    # shallow-clone and failed-walk notices, never enough to emit a STALE_PATH.
+    # Directory citations are OUT OF SCOPE for adjudication; making them work means
+    # deriving deleted ancestors from the file entries, tracked in #1452.
+    if [[ "$t" != */ && "$last" != *.* ]]; then
+      return 0
+    fi
+  fi
+
+  NORM_CAND=$t
+}
+
+# grep -F -- "$1" "$2": matching lines, no extra process. A quoted needle is
+# literal inside [[ == ]].
+spv_fixed_hits() {
+  SPV_HITS=()
+  local line needle=$1 file=$2
+  [[ -f "$file" && -n "$needle" ]] || return 0
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ "$line" == *"$needle"* ]] && SPV_HITS+=("$line")
+  done <"$file"
+}
+
+# Partial-replacement context reconstruction (Edit only), mirroring
+# skill-reference-verify's reconstruct_partial_edit.
+#
+# An Edit may replace an arbitrary substring: swapping `gone` for `real` inside an
+# existing `docs/gone.md` span leaves `docs/real.md` on disk, but the hunk is the
+# bare word `real` with no backtick pair around it, so emit_tokens finds no span
+# and a newly-stale citation would be silently missed. Write needs none of this —
+# its content is the whole file, already fully scanned.
+#
+# Recover bounded context: the edit is already applied by PostToolUse time, so pull
+# from disk only the lines the hunk's OWN TEXT appears in, scan those, and keep only
+# candidates containing one of the hunk's word tokens.
+#
+# The anchor match is a SUBSTRING match, so line-anchoring ALONE does not bound
+# what is recovered: when the hunk is a single bare fragment the anchor IS that
+# fragment and the line filter degenerates to the token filter. What bounds it is
+# the occurrence-uniqueness gate below — the same gate the sibling guard this
+# function mirrors already carries.
+reconstruct_partial_edit() {
+  RECON_OUT=()
+  [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0
+  # The token filter reads the hunk with any COMPLETE code span removed first. A
+  # complete span is already handled by the direct scan, and leaving it in would
+  # contribute its own path segments as tokens — `docs` then passes every citation
+  # under that directory. What remains is the genuinely bare edited text.
+  local residue plain=0
+  spv_plain "$SCAN_CONTENT" && plain=1
+  # Minimum token length is two characters. A single-character token carries no
+  # filtering power; below two characters the token floor short-circuits (#1455).
+  # Path separators are deliberately NOT in the token charset: a prose fragment
+  # like `and/or` would then match far more candidates than a bare word does.
+  local -a toks=()
+  if ((plain)); then
+    hook::_c_locale spv__residue_tokens "$SCAN_CONTENT"
+    toks=(${SPV_OUT[@]+"${SPV_OUT[@]}"})
+  else
+    # shellcheck disable=SC2016  # backticks are literal ERE data, not expansions
+    residue=$(printf '%s' "$SCAN_CONTENT" | sed -E 's/`[^`]*`//g')
+    mapfile -t toks < <(printf '%s' "$residue" | grep -oE '[A-Za-z0-9][A-Za-z0-9._-]{1,}' 2>/dev/null | sort -u)
+  fi
+  ((${#toks[@]})) || return 0
+  # Lines are located by the hunk's own lines, never by its tokens. Every line of
+  # new_string is on disk verbatim, so it matches the line the edit landed in; a
+  # token, being shorter, also matches lines the edit never touched — a bare `docs`
+  # in unrelated prose pulls in every citation under docs/.
+  local -a anchors=()
+  if ((plain)); then
+    hook::_c_locale spv__nonblank "$SCAN_CONTENT"
+    anchors=(${SPV_OUT[@]+"${SPV_OUT[@]}"})
+  else
+    mapfile -t anchors < <(printf '%s' "$SCAN_CONTENT" | grep -vE '^[[:space:]]*$' 2>/dev/null)
+  fi
+  ((${#anchors[@]})) || return 0
+  # An anchor is used ONLY when it OCCURS exactly once in the file — occurrences,
+  # not matching lines. Counting lines is not enough: two occurrences on one
+  # physical line are one grep hit, and that is a real shape — editing `docs` into
+  # a line that already carries an untouched `` `docs/gone.md` `` leaves the anchor
+  # twice on that line, and adjudicating that citation would be an advisory about
+  # text this call never wrote. Occurrence uniqueness subsumes line uniqueness (one
+  # occurrence can only be on one line), so it is the only gate.
+  #
+  # This is what makes the recovered set diff-scoped rather than merely narrower.
+  # The edited line provably contains the anchor, so a single occurrence pins the
+  # edit to that line; a non-unique anchor cannot say WHICH occurrence the edit
+  # landed on, and is dropped rather than unioned. Cost: a missed advisory when an
+  # edit lands in text repeating verbatim elsewhere in the file. For a
+  # detect-then-judge guard that is the right side of the trade — it is degraded
+  # far worse by being wrong when it speaks than by staying quiet.
+  local anchor occ ctx=""
+  local -a hits=()
+  for anchor in "${anchors[@]}"; do
+    # Single-word anchors use word-boundary matching so a bare fragment like
+    # `docs` does not substring-match inside `docs/gone.md` on an untouched line (#1455).
+    if [[ "$anchor" != *' '* && "$anchor" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+      mapfile -t hits < <(grep -w -F -- "$anchor" "$FILE" 2>/dev/null)
+    else
+      spv_fixed_hits "$anchor" "$FILE"
+      hits=()
+      if ((${#SPV_HITS[@]})); then
+        hits=("${SPV_HITS[@]}")
+      fi
+    fi
+    ((${#hits[@]})) || continue
+    # replace_all is the one case where repetition is expected rather than
+    # ambiguous: every occurrence is a place THIS call edited, so all of them are
+    # in scope and uniqueness must not be required. Accepted narrowing — a line
+    # that independently contained new_string and was never touched is kept too,
+    # since nothing in the payload distinguishes it from an edited one.
+    if [[ "$REPLACE_ALL" == "true" ]]; then
+      for occ in "${hits[@]}"; do ctx+="$occ"$'\n'; done
+      continue
+    fi
+    # Count anchor STARTS, including overlapping ones. `grep -o` emits only
+    # non-overlapping matches, so a self-overlapping anchor undercounts: with
+    # anchor `docs/docs` against `docs/docs/docs`, starts exist at offsets 0 and
+    # 5, but the two spans overlap and `grep -o` reports 1 — the anchor passes a
+    # uniqueness gate it should fail, and reconstruction then scans a line it
+    # cannot attribute, recreating the false STALE_PATH this gate exists to
+    # prevent. The counter walks every start, overlapping or not, and advances
+    # one byte past each start.
+    #
+    # A word anchor is counted by splitting each line on non-word bytes: the
+    # same maximal [A-Za-z0-9_] runs a character walk finds. Under C a
+    # non-ASCII byte is a separator. A `.` or `-` can never sit inside such a
+    # run, so an anchor carrying one counts 0 and needs no counter at all.
+    if hook::_c_locale spv__word_anchor "$anchor"; then
+      [[ "$anchor" != *[.-]* ]] || continue
+      occ=$(spv_word_occurrences "$anchor" "$FILE" 2>/dev/null)
+      ((occ == 1)) || continue
+      ctx+="${hits[0]}"$'\n'
+      continue
+    fi
+    occ=$(spv_anchor_occurrences "$anchor" "$FILE")
+    ((occ == 1)) || continue
+    ctx+="${hits[0]}"$'\n'
+  done
+  [[ -n "$ctx" ]] || return 0
+  local saved="$SCAN_CONTENT" raw cand seg
+  if spv_plain "$ctx"; then
+    hook::_c_locale spv__nonblank "$ctx" 40
+    SCAN_CONTENT=""
+    for raw in ${SPV_OUT[@]+"${SPV_OUT[@]}"}; do SCAN_CONTENT+=${SCAN_CONTENT:+$'\n'}$raw; done
+  else
+    SCAN_CONTENT=$(printf '%s' "$ctx" | grep -vE '^[[:space:]]*$' | head -40)
+  fi
+  spv_tokens
+  for raw in ${SPV_OUT[@]+"${SPV_OUT[@]}"}; do
+    [[ -n "$raw" ]] || continue
+    normalize_candidate "$raw"
+    cand=$NORM_CAND
+    [[ -n "$cand" ]] || continue
+    # SUBSTRING match against the CANDIDATE, not the raw span: an Edit can replace
+    # part of a segment (`gone` -> `real` turns `docs/gone.md` into `docs/real.md`),
+    # so the hunk token is a substring of the path rather than the whole of it, and
+    # the anchor must appear in the thing actually reported.
+    for seg in "${toks[@]}"; do
+      if [[ "$cand" == *"$seg"* ]]; then
+        RECON_OUT+=("$cand")
+        break
+      fi
+    done
+  done
+  SCAN_CONTENT="$saved"
+}
+
+# spv_git_dir_to <var>
+# A normal checkout's .git is a directory. A linked worktree's is a file
+# (`gitdir: …`). Builtin reads only.
+spv_git_dir_to() {
+  local g="$REPO_ROOT/.git" line
+  if [[ -d "$g" ]]; then
+    printf -v "$1" '%s' "$g"
+    return 0
+  fi
+  if [[ -f "$g" ]]; then
+    IFS= read -r line <"$g" || return 1
+    line=${line%$'\r'}
+    [[ "$line" == 'gitdir:'* ]] || return 1
+    line=${line#gitdir:}
+    line=${line#"${line%%[![:space:]]*}"}
+    if [[ "$line" != /* && "$line" != [A-Za-z]:[/\\]* ]]; then
+      line="$REPO_ROOT/$line"
+    fi
+    printf -v "$1" '%s' "$line"
+    return 0
+  fi
+  return 1
+}
+
+# spv_git_common_to <var> <git-dir>
+# `shallow` lives in the common git dir. A linked worktree records that path
+# in `commondir`; a normal checkout's git dir is the common dir.
+spv_git_common_to() {
+  local line="$2"
+  if [[ -f "$2/commondir" ]]; then
+    IFS= read -r line <"$2/commondir" || return 1
+    line=${line%$'\r'}
+    line=${line%"${line##*[![:space:]]}"}
+    line=${line#"${line%%[![:space:]]*}"}
+    if [[ "$line" != /* && "$line" != [A-Za-z]:[/\\]* ]]; then
+      line="$2/$line"
+    fi
+  fi
+  printf -v "$1" '%s' "$line"
+}
+
+declare -A DELETED=()
+DELETED_BUILT=0
+SHALLOW=0
+WALK_FAILED=0
+
+# The deleted-path set, built at most once and only after some candidate has
+# already failed the working-tree existence test — the overwhelmingly common
+# quiet path never pays for the history walk.
+build_deleted_set() {
+  ((DELETED_BUILT)) && return 0
+  DELETED_BUILT=1
+
+  # An unborn HEAD has no history to walk. The sha keys the on-disk set so a
+  # later edit at the same commit does not walk again. The redirect sits on the
+  # group: inside the substitution it would bill a second process for one git.
+  local head_sha="" git_dir="" common="" cache="" p n torn
+  local -a cached_lines=()
+  { head_sha=$(git -C "$REPO_ROOT" rev-parse --verify -q HEAD); } 2>/dev/null || return 0
+  head_sha=${head_sha//$'\r'/}
+  [[ -n "$head_sha" ]] || return 0
+
+  # Over truncated history the set is empty and the guard would do nothing while
+  # appearing healthy, so the degradation is announced rather than absorbed.
+  # `.git/shallow` is the file `--is-shallow-repository` reads. A linked
+  # worktree keeps it in the common dir. When the git dir cannot be read, fall
+  # back to the git query.
+  if spv_git_dir_to git_dir && spv_git_common_to common "$git_dir"; then
+    cache="$common/guardrails-deleted-paths"
+    if [[ -e "$common/shallow" ]]; then
+      SHALLOW=1
+      return 0
+    fi
+    # `<sha>\nok\n`, one deleted path per line, then `end <count>`. A failed walk
+    # is not cached, so the next fire retries it. A parallel fire can be
+    # rewriting this file, and two writers that both truncate leave a mix of
+    # their bytes: a header and a partial list would pass as a whole cache and
+    # every finding in the missing part would go silent. So the count must equal
+    # the lines read, and a second sentinel-shaped line marks a mix. Anything
+    # else is a miss and the walk below rebuilds it.
+    if [[ -f "$cache" ]]; then
+      mapfile -t cached_lines <"$cache"
+      n=$((${#cached_lines[@]} - 3))
+      if [[ "${cached_lines[0]-}" == "$head_sha" && "${cached_lines[1]-}" == ok ]] &&
+        ((n >= 0)) && [[ "${cached_lines[n + 2]}" == "end $n" ]]; then
+        torn=0
+        if ((n > 0)); then
+          for p in "${cached_lines[@]:2:n}"; do
+            if [[ "$p" == "end "[0-9]* ]]; then
+              torn=1
+              break
+            fi
+            [[ -n "$p" ]] || continue
+            DELETED["$p"]=1
+          done
+        fi
+        ((torn)) || return 0
+        DELETED=()
+      fi
+    fi
+  elif [[ "$(git -C "$REPO_ROOT" rev-parse --is-shallow-repository 2>/dev/null | tr -d '\r')" == "true" ]]; then
+    SHALLOW=1
+    return 0
+  fi
+
+  # --no-renames is MANDATORY. Under git's default rename detection a moved file
+  # is recorded as R and --name-only prints the NEW path, so the stale path never
+  # enters the set and the guard silently drops to zero findings. HEAD, not
+  # --all: a path that only ever existed on an abandoned branch is not a stale
+  # mainline citation.
+  #
+  # The walk is captured and its status checked BEFORE anything is populated. A
+  # non-shallow clone can still fail mid-walk — a partial/lazy clone offline, a
+  # damaged object store — emitting some deleted paths and then exiting nonzero.
+  # Read through a pipe or process substitution that status is invisible, and a
+  # truncated set is indistinguishable from a complete one: the guard would look
+  # healthy while adjudicating against a fraction of history. Same failure mode
+  # as a shallow clone, so it takes the same announced degradation.
+  local walk walk_status=0
+  walk=$(git -C "$REPO_ROOT" -c core.quotePath=false log HEAD -m --no-renames --diff-filter=D --name-only --pretty=format: 2>/dev/null) ||
+    walk_status=$?
+  if ((walk_status != 0)); then
+    WALK_FAILED=1
+    return 0
+  fi
+
+  local rest
+  walk=${walk//$'\r'/}
+  rest=$walk
+  while [[ -n "$rest" ]]; do
+    p=${rest%%$'\n'*}
+    [[ -n "$p" ]] && DELETED["$p"]=1
+    [[ "$rest" == *$'\n'* ]] || break
+    rest=${rest#*$'\n'}
+  done
+
+  if [[ -n "$cache" ]]; then
+    # Built in memory and written by one printf, sentinel last: a temp file plus
+    # mv would add a process to every cold write.
+    local body=$head_sha$'\n'ok$'\n'
+    if ((${#DELETED[@]} > 0)); then
+      for p in "${!DELETED[@]}"; do
+        body+=$p$'\n'
+      done
+    fi
+    printf '%send %d\n' "$body" "${#DELETED[@]}" 2>/dev/null >"$cache" || :
+  fi
+}
+
+# "Did you mean" enrichment, only once a finding exists. A basename match is far
+# too weak to trigger on — `README.md` and `SKILL.md` match hundreds of paths —
+# but once history has established the path was removed, a UNIQUE surviving
+# basename is very likely where it went.
+moved_hint() {
+  local -a matches=()
+  tracked_basename_matches "${1##*/}" || return 1
+  ((${#matches[@]} == 1)) && printf '%s' "${matches[0]}"
+}
+
+declare -A CHECKED=()
+MISSING=()
+ABSENT=0
+
+spv_tokens
+RAW_TOKENS=(${SPV_OUT[@]+"${SPV_OUT[@]}"})
+# Reconstruction runs on EVERY Edit, not only when the hunk yielded nothing. One
+# hunk can both carry a complete code span and change a substring inside another,
+# so gating on an empty scan would miss the partial half. Duplicates are harmless
+# — CHECKED dedupes below.
+if [[ "$TOOL" == "Edit" ]]; then
+  reconstruct_partial_edit
+  if ((${#RECON_OUT[@]})); then
+    RAW_TOKENS+=("${RECON_OUT[@]}")
+  fi
+fi
+# Warm before the candidate loop, and only when there is something to adjudicate.
+# `git ls-files` lists the whole index; a write that cites no token must not pay it.
+((${#RAW_TOKENS[@]})) && ensure_tracked_files
+
+for raw in "${RAW_TOKENS[@]}"; do
+  [[ -n "$raw" ]] || continue
+  normalize_candidate "$raw"
+  cand=$NORM_CAND
+  [[ -n "$cand" ]] || continue
+
+  [[ -n "${CHECKED[$cand]:-}" ]] && continue
+  CHECKED["$cand"]=1
+
+  # Present, not merely reachable: -L keeps a dangling symlink — the link itself is
+  # there, only its target is not — from reading as a removal.
+  [[ -e "$REPO_ROOT/${cand%/}" || -L "$REPO_ROOT/${cand%/}" ]] && continue
+  ABSENT=1
+
+  # PROVENANCE GATE: adjudicate only a path this repository demonstrably once
+  # had. Anything else is somebody else's tree, an example, or a plan.
+  build_deleted_set
+  [[ -n "${DELETED[$cand]:-}" ]] || continue
+
+  # Deleted once, tracked again now. Under a sparse checkout such a path is absent
+  # from the working tree BY DESIGN, so the filesystem alone cannot separate it from
+  # a real removal and the index has to be consulted. Placed after the provenance
+  # gate, not before it: only a path already headed for a finding pays for the call,
+  # which keeps the quiet path free of any per-candidate git invocation.
+  #
+  # The test is the SKIP-WORKTREE BIT, not mere presence in the index. An index
+  # entry exists in two different situations and `--error-unmatch` cannot tell them
+  # apart — it reports the entry either way:
+  #
+  #   sparse checkout      `ls-files -v` tags the entry `S` — or lowercase `s`
+  #                        when the assume-unchanged bit is ALSO set, since `-v`
+  #                        marks assume-unchanged by lowercasing the letter;
+  #                        either case carries the skip-worktree bit, so the
+  #                        path is absent BY DESIGN.
+  #   unstaged deletion    tag stays `H` and `git status` shows ` D`; the path is
+  #                        genuinely gone from the working tree, which is exactly
+  #                        the disappearance this guard adjudicates.
+  #
+  # Exempting on presence alone therefore suppressed the finding for a real removal
+  # a user had not committed yet. Only the skip-worktree letter, in either case,
+  # earns the exemption.
+  ls_line=$(git -C "$REPO_ROOT" ls-files -v -- ":(literal)${cand%/}" 2>/dev/null) || ls_line=""
+  ls_line=${ls_line//$'\r'/}
+  ls_tag=${ls_line:0:1}
+  [[ "$ls_tag" == [Ss] ]] && continue
+
+  MISSING+=("$cand")
+done
+
+emit_tel() {
+  [[ -n "$start" ]] || return 0
+  hook::telemetry_enabled || return 0
+  # The helper carries the redaction: a path it could not make repo-relative
+  # comes back as the basename, never an absolute path, which would embed the
+  # developer's username.
+  local findings_json="[]" file_rel
+  file_rel=""
+  hook::repo_relative_path_to file_rel "$FILE" "$REPO_ROOT"
+  if ((${#MISSING[@]} > 0)); then
+    findings_json=$(printf '%s\n' "${MISSING[@]}" | jq -Rn '[inputs]' 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":[]}'
+  # $1 is the envelope status, defaulting to a completed check. The degradation
+  # branches pass `skipped`: they run when the deleted-path oracle was unavailable,
+  # and reporting `ok` there would make a sink read an un-run check as a healthy
+  # one — the truncated-history failure looking exactly like a clean scan is the
+  # thing this guard already refuses to do on the user-visible path.
+  hook::emit_telemetry "stale-path-verify" "PostToolUse" "${1:-ok}" "$start" "$data" "$REPO_ROOT"
+}
+
+if ((SHALLOW)) && ((ABSENT)); then
+  if hook::notice_once "guardrails-stale-path-verify-shallow" "$INPUT"; then
+    hook::emit_skip_notice PostToolUse "" \
+      "stale-path-verify is off: this clone is shallow. \`git fetch --unshallow\` turns it on."
+  fi
+  emit_tel skipped
+  exit 0
+fi
+
+if ((WALK_FAILED)) && ((ABSENT)); then
+  if hook::notice_once "guardrails-stale-path-verify-walk-failed" "$INPUT"; then
+    hook::emit_skip_notice PostToolUse "" \
+      "stale-path-verify is off: \`git log --diff-filter=D\` failed here (a partial clone offline or a damaged object store are the usual causes)."
+  fi
+  emit_tel skipped
+  exit 0
+fi
+
+if ((${#MISSING[@]} > 0)); then
+  # The file as the model names it: repo-relative when it sits under the root
+  # spelled the same way, else as given.
+  show_file="$FILE"
+  [[ "$FILE" == "${REPO_ROOT%/}/"?* ]] && show_file="${FILE#"${REPO_ROOT%/}/"}"
+  lines=""
+  for m in "${MISSING[@]}"; do
+    hint=$(moved_hint "$m")
+    if [[ -n "$hint" ]]; then
+      lines+="$m (now at: $hint)"$'\n'
+    else
+      lines+="$m"$'\n'
+    fi
+  done
+  spv_ctx=""
+  hook::findings_to spv_ctx \
+    "stale-path-verify: cited path(s) in $show_file were deleted from this repo:" \
+    "$lines" --max 10
+  hook::ctx_append "$spv_ctx"
+  hook::ctx_append "A path cited as a deletion record is correct as written."
+  hook::ctx_flush PostToolUse
+fi
+
+emit_tel
+exit 0
diff --git a/.githooks/guardrails/verify-cli-flag.sh b/.githooks/guardrails/verify-cli-flag.sh
new file mode 100755
index 0000000000..e4b7d48e94
--- /dev/null
+++ b/.githooks/guardrails/verify-cli-flag.sh
@@ -0,0 +1,177 @@
+#!/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
+
+# Cache location, key, window and flag pattern are shared with the
+# cli-flag-verify hook, which answers cache hits without spawning this script.
+CFV_LIB_DIR="${BASH_SOURCE[0]%/*}"
+[[ "$CFV_LIB_DIR" == "${BASH_SOURCE[0]}" ]] && CFV_LIB_DIR=.
+# shellcheck source=cli-flag-cache.sh
+source "$CFV_LIB_DIR/cli-flag-cache.sh"
+
+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 and key come from the shared definitions (cli-flag-cache.sh).
+CACHE_DIR=""
+cfv_cache_dir_to CACHE_DIR
+# The directory exists on every run but the first; a test costs nothing and a
+# spawn costs a process (a fork emulation on Windows Git Bash).
+[[ -d "$CACHE_DIR" ]] || mkdir -p "$CACHE_DIR" 2>/dev/null || true
+
+CACHE_KEY=""
+cfv_cache_key_to CACHE_KEY "$BIN" "${SUBCMDS[@]}"
+CACHE_FILE="$CACHE_DIR/$CACHE_KEY.help"
+
+# Cache hit if file exists, mtime within 24h, non-empty. The 24 h mark is a
+# reference file touched to that timestamp and compared with bash's own `-nt`:
+# one `touch` (POSIX `-t`) in place of `find | grep`, which cost two processes
+# plus the pipe. Bash without EPOCHSECONDS (before 5.0) keeps the find shape.
+USE_CACHE=false
+if [[ -s "$CACHE_FILE" ]]; then
+  FRESH_REF="$CACHE_DIR/.fresh-24h"
+  if [[ -n "${EPOCHSECONDS:-}" ]] &&
+    printf -v FRESH_STAMP '%(%Y%m%d%H%M.%S)T' "$((EPOCHSECONDS - CFV_CACHE_WINDOW_MIN * 60))" 2>/dev/null &&
+    touch -t "$FRESH_STAMP" "$FRESH_REF" 2>/dev/null; then
+    [[ "$CACHE_FILE" -nt "$FRESH_REF" ]] && USE_CACHE=true
+  elif find "$CACHE_FILE" -mmin "-$CFV_CACHE_WINDOW_MIN" 2>/dev/null | grep -q .; then
+    USE_CACHE=true
+  fi
+fi
+
+HELP_OUTPUT=""
+if $USE_CACHE; then
+  HELP_OUTPUT=$(<"$CACHE_FILE")
+else
+  # Run `<bin> [<subcmds>...] --help` with timeout 5s where `timeout` exists;
+  # an empty prefix array runs the binary directly. 2>&1 catches binaries that
+  # print --help to stderr (e.g. some legacy tools).
+  TIMEOUT_PREFIX=()
+  command -v timeout >/dev/null 2>&1 && TIMEOUT_PREFIX=(timeout 5)
+  HELP_OUTPUT=$("${TIMEOUT_PREFIX[@]}" "$BIN" "${SUBCMDS[@]}" --help 2>&1)
+  HELP_RC=$?
+  # Some CLIs return non-zero on --help (e.g. busybox tools, malformed args).
+  # Tolerate non-zero as long as output is non-empty and it did not time out.
+  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), published by rename. Concurrent hooks race
+  # to refresh one key, and bash's printf to a file is many write(2) calls, not
+  # one, so a reader that passes the -s and mtime gates mid-rewrite would read
+  # a prefix and report a documented flag as unknown. `mv` is atomic within a
+  # filesystem: the reader sees the previous whole text or the new whole text.
+  CACHE_TMP="$CACHE_FILE.$$.tmp"
+  if printf '%s' "$HELP_OUTPUT" >"$CACHE_TMP" 2>/dev/null; then
+    mv -f "$CACHE_TMP" "$CACHE_FILE" 2>/dev/null || rm -f "$CACHE_TMP" 2>/dev/null || true
+  else
+    rm -f "$CACHE_TMP" 2>/dev/null || true
+  fi
+fi
+
+# The match pattern is the shared definition (cli-flag-cache.sh documents the
+# help-text shapes it accepts); the hook applies the same one on a cache hit.
+FLAG_PATTERN=""
+cfv_flag_pattern_to FLAG_PATTERN "$FLAG_NAME"
+# Matched in-process: bash's `=~` is the same ERE dialect grep -E reads, and
+# over the whole multi-line string the leading class admits the newline that
+# precedes a line start, so a flag at the start of any --help line matches
+# exactly as it did under grep. No pipe, no process, no pipe-capacity window.
+# The --verbose path below still greps, because it wants the line number.
+if [[ "$HELP_OUTPUT" =~ $FLAG_PATTERN ]]; then
+  if $VERBOSE; then
+    printf '%s\n' "$HELP_OUTPUT" | grep -nE "$FLAG_PATTERN" | head -1
+  fi
+  exit 0
+fi
+
+$QUIET || echo "verify-cli-flag: '$FLAG_NAME' not found in '$BIN ${SUBCMDS[*]} --help' output" >&2
+exit 1
diff --git a/.github/workflows/pr-require-checks.yml b/.github/workflows/pr-require-checks.yml
index e2083c3ad2..02c3849248 100644
--- a/.github/workflows/pr-require-checks.yml
+++ b/.github/workflows/pr-require-checks.yml
@@ -1016,8 +1016,10 @@ jobs:
           # the parser has to survive. The paths are invented (`alice`, `x`),
           # not any operator's. source-control's same-drive unit tests need
           # literal `C:/` / `D:/` drive fixtures to exercise the gate (#2764).
+          # .githooks/guardrails/ holds the installer's copies of that pattern lib.
           exclude: >-
             :(exclude)plugins/guardrails/lib/path-detection/**
+            :(exclude).githooks/guardrails/*-path-patterns.sh
             :(exclude)plugins/autonomy/skills/setup/evals/fixtures/security-binding/**
             :(exclude)plugins/autonomy/skills/setup/scripts/check-security-binding.fixtures.test.manifest.json
             :(exclude)plugins/harness-config/skills/audit-permission-state/reference/criteria.md
@@ -1504,6 +1506,8 @@ jobs:
         with:
           files: ${{ steps.changed_shell.outputs.files }}
           rcfile: .shellcheckrc
+          # Plugin-owned guardrails copies; linted at their plugins/guardrails sources.
+          exclude: .githooks/guardrails/
 
       - name: Aggregate hygiene results
         if: always()
diff --git a/lefthook.yml b/lefthook.yml
index 9a21134e85..db40759e6d 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -24,3 +24,16 @@ pre-push:
         git archive "$mb" -- .claude/hooks/check-affected-pre-push.sh lib/hook-utils.sh 2>/dev/null | tar -x -C "$tmp" 2>/dev/null
         [ -f "$tmp/.claude/hooks/check-affected-pre-push.sh" ] || exit 0
         bash "$tmp/.claude/hooks/check-affected-pre-push.sh" --git-hook </dev/null
+    - name: guardrails-reference-verify
+      run: bash .githooks/guardrails/reference-verify.sh {0}
+      use_stdin: true
+
+pre-commit:
+  jobs:
+    - name: guardrails-pre-commit-content
+      run: bash .githooks/guardrails/pre-commit-content.sh
+
+commit-msg:
+  jobs:
+    - name: guardrails-commit-msg-convention
+      run: bash .githooks/guardrails/commit-msg-convention.sh {0}