refactor(v0.17): extract hook gate into shared lib

Removes 9×20 LOC duplication of KEI_DISABLED_HOOKS gate logic from each hook into hooks/_lib/gate.sh. Next CVE in gate path fixes in ONE file, not 9. hooks/_lib/gate.sh (new, 57 LOC) — POSIX sh library, single kei_hook_gate() function. Exact-token tokenize on comma OR space (RED-1 fix preserved). Minimal-profile whitelist baked in: no-hand-edit-agents, assemble-validate, agent-fork-logger, session-end-dump. Idempotent re-source guard. hooks/_lib/test-gate.sh (new, 47 LOC) — 11 test cases covering empty/comma/space/whitespace/substring-NOT-match/literal 'all'/ minimal-profile included+excluded/minimal+disabled combo. Per-hook shim (exactly 2 LOC, same in all 9): _KEI_LIB="$(dirname "$0")/_lib/gate.sh" if [ -r "$_KEI_LIB" ]; then . "$_KEI_LIB"; kei_hook_gate "<name>" || exit 0; fi Net LOC delta: −171 (hooks) +104 (lib new) +15 (installer) = −52. Gate semantics bit-identical to v0.15.1 hotfix on the 6 enumerated behaviors; off/advisory-off profile values dropped per spec (only 'minimal' recognized, any other = full). Fail-open on missing lib — if _lib/gate.sh absent (old install pre-v0.17), hook falls through to normal operation. install.sh — +15 LOC copies hooks/_lib/*.sh to $HOOKS_DIR/_lib/, preserving relative path the shim expects. Note: v0.16 split this file; A1 worktree was based on pre-split main — merge into current main required resolving conflict so _lib-copy logic moved to install/lib-hooks.sh. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 15:14:19 +08:00 · 2026-04-22 15:14:19 +08:00 · 588e194d59
commit 588e194d59
parent b62b219500
12 changed files with 138 additions and 189 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,27 +8,8 @@

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

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +13,8 @@
 # Claude Code would refuse the tool call system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +10,8 @@
 # Claude Code would refuse the tool call system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +8,8 @@

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

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +8,8 @@

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

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +12,8 @@
 # Claude Code would refuse Edit/Write system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +8,8 @@

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

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +13,8 @@

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

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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,27 +11,8 @@
 # Claude Code would refuse Read system-wide.
 command -v jq >/dev/null 2>&1 || exit 0

-# --- RUNTIME CONTROLS (v0.14.2) ---
-_hook_name="$(basename "$0" .sh)"
-case "${KEI_DISABLED_HOOKS:-}" in
-  *"$_hook_name"*|*all*) exit 0 ;;
-esac
-case "${KEI_HOOK_PROFILE:-full}" in
-  off) exit 0 ;;
-  minimal)
-    case "$_hook_name" in
-      no-github-push|genesis-leak-guard|no-hand-edit-agents|secrets-guard|assemble-validate|git-pre-commit-genesis) ;;
-      *) 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.sh
+++ b/install.sh
@ -1110,6 +1110,22 @@ for hook_src in "$KIT_DIR/hooks/"*.sh; do
 done
 say "  installed $hook_count hook(s)"

+# --- copy shared hook library (v0.17 gate-extract) -----------------------
+# 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).
+if [[ -d "$KIT_DIR/hooks/_lib" ]]; then
+  mkdir -p "$HOOKS_DIR/_lib"
+  lib_count=0
+  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
+
 # --- copy skills ----------------------------------------------------------
 if [[ -d "$KIT_DIR/skills" ]]; then
  say "copying skills"