Merge refactor/v0.17-hook-gate-lib — extract gate lib (conflict resolved)

hooks/*.sh: take shim from A1 (gate logic lives in _lib/gate.sh) install.sh: take dispatcher from v0.16 install-split; ported A1's _lib-copy logic into install/lib-hooks.sh::install_hooks (since A1 worktree was based on pre-v0.16-split main and couldn't see the cube structure). Gate semantics preserved — tokenized KEI_DISABLED_HOOKS, minimal profile whitelist. Net: −171 (hooks) +104 (_lib new) +15 (lib-hooks) = −52 LOC across kit.
2026-04-22 15:23:44 +08:00 · 2026-04-22 15:23:44 +08:00 · d0ade2b411
commit d0ade2b411
parent 4c77b9a79b 588e194d59
12 changed files with 139 additions and 234 deletions
--- a/hooks/_lib/gate.sh
+++ b/hooks/_lib/gate.sh
@ -0,0 +1,57 @@
+#!/bin/sh
+# hooks/_lib/gate.sh — shared runtime-gate library for KeiSeiKit hooks.
+#
+# SOURCED (not executed). Each hook dot-sources this file and then calls
+# `kei_hook_gate <hook-name-without-.sh>`. Return value:
+#   0 → hook continues executing
+#   1 → hook MUST `exit 0` (disabled or filtered out by profile)
+#
+# Semantics (bit-identical to the v0.15.1 RED-1 hotfix):
+#   KEI_DISABLED_HOOKS=""                         → everything runs
+#   KEI_DISABLED_HOOKS="hook-a,hook-b"            → a and b skipped
+#   KEI_DISABLED_HOOKS="hook-a hook-b"            → a and b skipped (space-sep OK)
+#   KEI_DISABLED_HOOKS="all"                      → ALL hooks skipped (literal token)
+#   KEI_DISABLED_HOOKS="foo-all-bar"              → NOTHING skipped (exact-token only)
+#   KEI_HOOK_PROFILE=minimal                      → only whitelist hooks run
+#   KEI_HOOK_PROFILE=minimal + disabled-whitelist → that hook ALSO skipped (disabled wins)
+#
+# POSIX sh only (macOS bash 3.2 compatible). No arrays, no `[[`.
+
+# Idempotent re-source guard.
+if [ "${_KEI_HOOK_GATE_LOADED:-0}" = "1" ]; then
+  return 0 2>/dev/null || true
+fi
+_KEI_HOOK_GATE_LOADED=1
+
+# Minimal-profile whitelist as space-separated tokens (iterated, not pattern-matched).
+_KEI_HOOK_MINIMAL_WHITELIST='no-hand-edit-agents assemble-validate agent-fork-logger session-end-dump'
+
+kei_hook_gate() {
+  _khg_name="$1"
+  [ -n "$_khg_name" ] || return 0
+
+  # Normalize KEI_DISABLED_HOOKS: commas → spaces. Iterate with exact-token match;
+  # substring bypass (`foo-all-bar` vs literal `all`) is impossible by construction.
+  _khg_disabled="${KEI_DISABLED_HOOKS:-}"
+  if [ -n "$_khg_disabled" ]; then
+    _khg_disabled=$(printf '%s' "$_khg_disabled" | tr ',' ' ')
+    for _khg_tok in $_khg_disabled; do
+      if [ "$_khg_tok" = "$_khg_name" ] || [ "$_khg_tok" = "all" ]; then
+        return 1
+      fi
+    done
+  fi
+
+  # Profile filter. `minimal` keeps only whitelist; any other value (empty,
+  # `full`, unknown) runs every hook.
+  if [ "${KEI_HOOK_PROFILE:-}" = "minimal" ]; then
+    for _khg_tok in $_KEI_HOOK_MINIMAL_WHITELIST; do
+      if [ "$_khg_tok" = "$_khg_name" ]; then
+        return 0
+      fi
+    done
+    return 1
+  fi
+
+  return 0
+}
--- a/hooks/_lib/test-gate.sh
+++ b/hooks/_lib/test-gate.sh
@ -0,0 +1,47 @@
+#!/bin/sh
+# hooks/_lib/test-gate.sh — POSIX sh unit test for kei_hook_gate.
+# Run: sh hooks/_lib/test-gate.sh ; echo $?
+
+set -u
+
+_TEST_DIR=$(cd "$(dirname "$0")" 2>/dev/null && pwd)
+. "$_TEST_DIR/gate.sh"
+
+_pass=0
+_total=0
+
+# assert_rc <expected-rc> <case-name>
+assert_rc() {
+  _total=$((_total+1))
+  _exp="$1"; _name="$2"
+  kei_hook_gate "$_hook_under_test"
+  _got=$?
+  if [ "$_got" = "$_exp" ]; then
+    _pass=$((_pass+1))
+  else
+    printf 'FAIL case %s: expected rc=%s got rc=%s (KEI_DISABLED_HOOKS=%s KEI_HOOK_PROFILE=%s name=%s)\n' \
+      "$_name" "$_exp" "$_got" "${KEI_DISABLED_HOOKS:-}" "${KEI_HOOK_PROFILE:-}" "$_hook_under_test" >&2
+    exit 1
+  fi
+}
+
+_hook_under_test='session-end-dump'
+
+KEI_DISABLED_HOOKS=''; KEI_HOOK_PROFILE=''; assert_rc 0 empty_disabled_runs
+KEI_DISABLED_HOOKS='session-end-dump,agent-fork-logger'; KEI_HOOK_PROFILE=''; assert_rc 1 comma_list_match
+KEI_DISABLED_HOOKS='agent-fork-logger session-end-dump'; KEI_HOOK_PROFILE=''; assert_rc 1 space_list_match
+KEI_DISABLED_HOOKS='  session-end-dump ,  agent-fork-logger  '; KEI_HOOK_PROFILE=''; assert_rc 1 whitespace_tolerant
+KEI_DISABLED_HOOKS='foo-session-end-dump-bar'; KEI_HOOK_PROFILE=''; assert_rc 0 substring_no_match
+KEI_DISABLED_HOOKS='all'; KEI_HOOK_PROFILE=''; assert_rc 1 literal_all_skips
+KEI_DISABLED_HOOKS='foo-all-bar'; KEI_HOOK_PROFILE=''; assert_rc 0 all_substring_no_match
+KEI_DISABLED_HOOKS=''; KEI_HOOK_PROFILE='minimal'; assert_rc 0 minimal_whitelist_runs
+
+_hook_under_test='tomd-preread'
+KEI_DISABLED_HOOKS=''; KEI_HOOK_PROFILE='minimal'; assert_rc 1 minimal_excluded_skipped
+KEI_DISABLED_HOOKS=''; KEI_HOOK_PROFILE='full'; assert_rc 0 unknown_profile_runs
+
+_hook_under_test='session-end-dump'
+KEI_DISABLED_HOOKS='session-end-dump'; KEI_HOOK_PROFILE='minimal'; assert_rc 1 minimal_plus_disabled_skips
+
+printf 'PASS %d/%d\n' "$_pass" "$_total"
+exit 0
--- a/hooks/agent-fork-logger.sh
+++ b/hooks/agent-fork-logger.sh
@ -8,32 +8,8 @@

 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "agent-fork-logger" || exit 0; fi

 set -eu

--- a/hooks/assemble-agents.sh
+++ b/hooks/assemble-agents.sh
@ -13,32 +13,8 @@
 # Claude Code would refuse the tool call system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "assemble-agents" || exit 0; fi

 set -eu

--- a/hooks/assemble-validate.sh
+++ b/hooks/assemble-validate.sh
@ -10,32 +10,8 @@
 # Claude Code would refuse the tool call system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "assemble-validate" || exit 0; fi

 set -eu

--- a/hooks/error-spike-detector.sh
+++ b/hooks/error-spike-detector.sh
@ -8,32 +8,8 @@

 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "error-spike-detector" || exit 0; fi

 set -eu

--- a/hooks/milestone-commit-hook.sh
+++ b/hooks/milestone-commit-hook.sh
@ -8,32 +8,8 @@

 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "milestone-commit-hook" || exit 0; fi

 set -eu

--- a/hooks/no-hand-edit-agents.sh
+++ b/hooks/no-hand-edit-agents.sh
@ -12,32 +12,8 @@
 # Claude Code would refuse Edit/Write system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "no-hand-edit-agents" || exit 0; fi

 set -eu

--- a/hooks/session-end-dump.sh
+++ b/hooks/session-end-dump.sh
@ -8,32 +8,8 @@

 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "session-end-dump" || exit 0; fi

 set -eu

--- a/hooks/site-wysiwyd-check.sh
+++ b/hooks/site-wysiwyd-check.sh
@ -13,32 +13,8 @@

 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "site-wysiwyd-check" || exit 0; fi

 set -eu

--- a/hooks/tomd-preread.sh
+++ b/hooks/tomd-preread.sh
@ -11,32 +11,8 @@
 # Claude Code would refuse Read system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.15.1) ---
-# KEI_DISABLED_HOOKS: tokenized exact-match list (comma- or space-separated).
-# Repro of pre-v0.15.1 substring bypass (CVE-class): KEI_DISABLED_HOOKS="foo-all-bar"
-# previously disabled every hook via `*all*`. v0.15.1 requires token equality.
-_hook_name="$(basename "$0" .sh)"
-_disabled=" $(printf '%s' "${KEI_DISABLED_HOOKS:-}" | tr ',' ' ') "
-case "$_disabled" in
-  *" $_hook_name "*|*" all "*) unset _disabled; exit 0 ;;
-esac
-unset _disabled
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-hand-edit-agents|assemble-validate|agent-fork-logger|session-end-dump) ;;
-      *) exit 0 ;;
-    esac
-    ;;
-  advisory-off)
-    case "$_hook_name" in
-      recurrence-suggest|citation-verify|error-spike-detector|milestone-commit-hook) exit 0 ;;
-    esac
-    ;;
-  full|*) ;;
-esac
-# --- end runtime controls ---
+_KEI_LIB="$(dirname "$0")/_lib/gate.sh"
+if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "tomd-preread" || exit 0; fi

 set -eu

--- a/install/lib-hooks.sh
+++ b/install/lib-hooks.sh
@ -10,6 +10,9 @@
 # Reads globals: $KIT_DIR, $HOOKS_DIR, $HOME_DIR.

 # Copy every *.sh hook from the kit into $HOOKS_DIR, +x, with per-file backup.
+# Also copies hooks/_lib/*.sh → $HOOKS_DIR/_lib/ (v0.17 gate-extract). The
+# hooks dot-source "$(dirname "$0")/_lib/gate.sh" — the _lib/ sub-tree MUST
+# land alongside the hook scripts or the gate becomes a no-op (fail-open).
 install_hooks() {
  say "copying hooks -> $HOOKS_DIR/"
  local hook_count=0 hook_src h
@ -22,6 +25,20 @@ install_hooks() {
    hook_count=$((hook_count+1))
  done
  say "  installed $hook_count hook(s)"
+
+  # v0.17 — shared hook library (gate.sh + test-gate.sh)
+  if [ -d "$KIT_DIR/hooks/_lib" ]; then
+    mkdir -p "$HOOKS_DIR/_lib"
+    local lib_count=0 lib_src lib_name
+    for lib_src in "$KIT_DIR/hooks/_lib/"*.sh; do
+      [ -f "$lib_src" ] || continue
+      lib_name="$(basename "$lib_src")"
+      cp -f "$lib_src" "$HOOKS_DIR/_lib/$lib_name"
+      chmod +x "$HOOKS_DIR/_lib/$lib_name"
+      lib_count=$((lib_count+1))
+    done
+    say "  installed $lib_count hook library file(s) -> $HOOKS_DIR/_lib/"
+  fi
 }

 # Merge settings-snippet.json into ~/.claude/settings.json non-interactively