@event4u/agent-config 16.5.0 → 17.0.0

package/dist/scripts/_lib/claude_settings_hooks.js

@@ -83,47 +83,115 @@ export function build_claude_hook_matrix(manifest_path) {
         const concerns = claude_events[ac_event];
         if (!concerns || (Array.isArray(concerns) && concerns.length === 0))
             continue;
-        // Bundle fast path (road-to-hook-latency-repair Phase 2): invoke the
-        // precompiled dispatcher bundle directly — no bash shim, no CLI boot
-        // (measured ~450-500 ms CLI vs ~110 ms bundle per event on a 1-vCPU
-        // container; bench_hook_latency --via-cli pins it). Candidates:
-        //   1. project npm install (node_modules/@event4u/agent-config/…)
-        //   2. a source checkout — guarded by hook_manifest.yaml existing
-        //      next to it, so an UNRELATED consumer file that happens to sit
-        //      at dist/hooks/dispatch.js can never be executed as a hook
-        //      (council 2026-08-03).
-        // `exec node` replaces the shell; stdin/exit codes flow through
-        // unchanged (a fail_closed concern still denies). Global installs
-        // have no project-relative bundle path and take the CLI fallback
-        // below, which boots the same bundle in-process via the launcher
-        // fast path (src/cli/agent-config.ts).
+        // Only package-owned dispatchers are trusted (17.0.0 finding
+        // feaebdef733b, owner decision of 2026-10-21): the staged runtime,
+        // then an `agent-config` on PATH whose resolved path is absolute and
+        // outside the opened project. Nothing inside $CLAUDE_PROJECT_DIR runs
+        // — not a project npm install, not a source checkout's dist/, not a
+        // local wrapper — because a cloned repository can commit any of them
+        // and would then run as the user's global hook, ahead of the guards.
+        // `exec` replaces the shell; stdin and exit codes flow through, so a
+        // fail_closed concern still denies. PreToolUse is the exception: it
+        // runs the dispatcher as a child so a missing verdict can be refused
+        // (see _pre_tool_use_exit_guard).
         //
-        // Hook-resilience fallback (road-to-opt-subagent-harvest P1.4):
-        // local binary → PATH fallback → SILENT exit 0 when neither exists
-        // (a hook must never error-spam the loop on an uninstalled repo).
-        // The dispatcher's own exit code PROPAGATES when it runs — a
-        // fail_closed concern (e.g. block-no-verify) still denies; only the
-        // missing-binary case degrades open, which is the honest degrade
-        // (an absent dispatcher cannot evaluate anything).
+        // With no dispatcher, PreToolUse refuses (exit 2) on the settings
+        // carrier (finding bb6ab0f5f37d): every fail_closed guard would
+        // otherwise pass silently, which an upgrade swap was measured doing
+        // 487 times in 4,190 invocations. The plugin carrier keeps the warning
+        // and exit 0 — a plugin-only install has no package to enforce with,
+        // and the session-start context line names the guards that are off
+        // (council 2026-10-21). Every other event stays exit 0.
         // NOTE: the CLI fallback carries MANAGED_SIGNATURE — keep it, or
         // previously installed managed entries orphan on refresh.
         const dispatchArgs = `--platform claude --event ${ac_event} --native-event ${native} ` +
             `--project-dir "$CLAUDE_PROJECT_DIR" --min-version ${String(hook_spec)}`;
         matrix[native] =
-            'B=""; ' +
-                '[ -f "$CLAUDE_PROJECT_DIR/node_modules/@event4u/agent-config/dist/hooks/dispatch.js" ] && ' +
-                'B="$CLAUDE_PROJECT_DIR/node_modules/@event4u/agent-config/dist/hooks/dispatch.js"; ' +
-                '[ -z "$B" ] && [ -f "$CLAUDE_PROJECT_DIR/dist/hooks/dispatch.js" ] && ' +
-                '[ -f "$CLAUDE_PROJECT_DIR/src/scripts/hook_manifest.yaml" ] && ' +
-                'B="$CLAUDE_PROJECT_DIR/dist/hooks/dispatch.js"; ' +
-                'if [ -n "$B" ] && command -v node >/dev/null 2>&1; then ' +
-                `exec node "$B" ${dispatchArgs}; fi; ` +
-                'BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config; ' +
-                'command -v "$BIN" >/dev/null 2>&1 || exit 0; ' +
-                `"$BIN" dispatch:hook ${dispatchArgs}`;
+            'R="${EVENT4U_CONFIG_HOME:-$HOME/.event4u/agent-config}/runtime"; S="$R/current"; N=""; ' +
+                '[ -f "$S/node" ] && read -r N < "$S/node"; ' +
+                'if [ -n "$N" ] && [ -x "$N" ] && [ -f "$S/dist/hooks/dispatch.js" ]; then ' +
+                `${native === 'PreToolUse' ? '' : 'exec '}"$N" "$S/dist/hooks/dispatch.js" ${dispatchArgs}; ` +
+                `${native === 'PreToolUse' ? 'else ' : 'fi; '}` +
+                'BIN=$(command -v agent-config); [ "${BIN#/}" = "$BIN" ] && BIN=""; ' +
+                '[ -n "$CLAUDE_PROJECT_DIR" ] && [ "${BIN#"$CLAUDE_PROJECT_DIR"/}" != "$BIN" ] && BIN=""; ' +
+                `[ -n "$BIN" ] || { ${_no_dispatcher_notice(native)}${_thinned_dead_carrier(native)}${_no_dispatcher_exit(native)} }; ` +
+                `"$BIN" dispatch:hook ${dispatchArgs}` +
+                (native === 'PreToolUse' ? _pre_tool_use_exit_guard() : '');
     }
     return matrix;
 }
+export const NO_DISPATCHER_STDERR = 'agent-config: no hook dispatcher reachable, so no agent-config hook runs in this session. ' +
+    'Hooks need the npm package where they can reach it: npm i -g @event4u/agent-config ' +
+    '(then npx -y @event4u/agent-config init)';
+export const NO_DISPATCHER_CONTEXT = 'agent-config hooks are NOT running in this session: the plugin found no dispatcher, so no ' +
+    'concern runs, the fail_closed guards block-no-verify, block-kernel-rule-writes and ' +
+    'block-plumbing-writes included.';
+/**
+ * The no-dispatcher branch, keyed on CLAUDE_PLUGIN_ROOT — set by the host for
+ * a plugin's hooks only (road-to-a-hook-carrier-that-is-never-silent 5.1, D5).
+ * The settings carrier runs the byte-same string, which the host's dedupe
+ * needs, and stays silent there: that carrier's branch belongs to Phase 3.
+ * One stderr line per event (exit 0, never blocking); the context line goes to
+ * stdout on SessionStart only, so a tool call is never followed by context.
+ * Both texts are single-quoted shell literals: no `'`, and no `;` either,
+ * because commandHead() splits on the last `;`.
+ */
+function _no_dispatcher_notice(native) {
+    const context = native === 'SessionStart' ? ` echo '${NO_DISPATCHER_CONTEXT}';` : '';
+    return `[ -n "$CLAUDE_PLUGIN_ROOT" ] && { echo '${NO_DISPATCHER_STDERR}' >&2;${context} }; `;
+}
+export const NO_DISPATCHER_REFUSAL = 'agent-config: no hook dispatcher reachable, so this tool call is refused: the fail_closed guards ' +
+    'block-no-verify, block-kernel-rule-writes and block-plumbing-writes cannot run. Repair in a terminal: ' +
+    'npm i -g @event4u/agent-config then npx -y @event4u/agent-config init. To drop the hooks instead: ' +
+    'agent-config uninstall, or delete the agent-config entries from ~/.claude/settings.json.';
+/**
+ * How the no-dispatcher branch ends. PreToolUse on the settings carrier
+ * refuses; the plugin carrier and every other event exit 0. Single-quoted
+ * literal like the notices: no `'`, no `;`.
+ */
+function _no_dispatcher_exit(native) {
+    if (native !== 'PreToolUse')
+        return 'exit 0;';
+    return `[ -z "$CLAUDE_PLUGIN_ROOT" ] && { echo '${NO_DISPATCHER_REFUSAL}' >&2; exit 2; }; exit 0;`;
+}
+export const DISPATCHER_FAILED_REFUSAL = 'agent-config: the hook dispatcher did not return a verdict, so this tool call is refused: the fail_closed ' +
+    'guards could not decide. If an agent-config upgrade is running, retry once it has finished.';
+/**
+ * PreToolUse runs its dispatcher as a child, never via `exec`, so this tail can
+ * read the exit code: Claude Code lets a tool call through on any exit other
+ * than 2, so a dispatcher that vanished mid-upgrade (127) or crashed on a
+ * half-written tree (1) used to pass the call. Only 0 and 2 are verdicts.
+ */
+function _pre_tool_use_exit_guard() {
+    return (`; fi; RC=$?; [ "$RC" = 0 ] || [ "$RC" = 2 ] || { echo '${DISPATCHER_FAILED_REFUSAL}' >&2; exit 2; }; ` +
+        'exit $RC');
+}
+export const THINNED_DEAD_CARRIER_LINE = 'agent-config: no hook dispatcher was reached and the rule layer on disk is thinned, so routed rule ' +
+    'bodies will not arrive in this session. Open a rule body from the absolute Body path in its stub. ' +
+    'The full rule layer is restored for the next session.';
+/**
+ * The dead-carrier branch on a THINNED layer (road-to-a-hook-carrier-that-is-never-silent
+ * 3.1, 3.2), SessionStart only and without node. `$R/thinned` exists only while
+ * the install left the claude layer thinned and holds that layer's directory; on
+ * a full layer the branch is silent, which is what keeps an uninstalled
+ * repository quiet. It prints one context line, then restores the staged full
+ * layer — overwriting only files that carry the package stamp, adding missing
+ * ones, removing none, each by an atomic rename — and demotes the machine. A
+ * failed copy leaves the marker, so the line keeps printing rather than the
+ * session going quiet on a layer that is still thin. `AC_HOOK_PROBE` is the
+ * stripped-environment probe, which must observe and never restore.
+ */
+function _thinned_dead_carrier(native) {
+    if (native !== 'SessionStart')
+        return '';
+    return (`[ -z "$AC_HOOK_PROBE" ] && [ -f "$R/thinned" ] && { echo '${THINNED_DEAD_CARRIER_LINE}'; ` +
+        'L=""; read -r L < "$R/thinned"; F=1; ' +
+        'if [ -d "$L" ] && [ -d "$S/claude-rules" ]; then F=0; for f in "$S/claude-rules"/*.md; do ' +
+        '[ -f "$f" ] || continue; t="$L/${f##*/}"; ' +
+        'if [ ! -e "$t" ] || grep -qx "package: event4u/agent-config" "$t"; then ' +
+        'cp "$f" "$t.ac-restore" && mv -f "$t.ac-restore" "$t" || F=1; fi; done; fi; ' +
+        '[ "$F" = 0 ] && mv -f "$R/thinned" "$R/demoted"; }; ');
+}
 function _is_managed_group(group) {
     if (typeof group !== 'object' || group === null || Array.isArray(group))
         return false;
@@ -135,7 +203,7 @@ function _is_managed_group(group) {
         typeof h.command === 'string' &&
         h.command.includes(MANAGED_SIGNATURE));
 }
-function _read_settings(settings_path) {
+export function _read_settings(settings_path) {
     if (!fs.existsSync(settings_path))
         return {};
     const raw = fs.readFileSync(settings_path, 'utf8');
@@ -153,7 +221,7 @@ function _read_settings(settings_path) {
     }
     return parsed;
 }
-function _with_lock(settings_path, fn) {
+export function _with_lock(settings_path, fn) {
     const lockPath = settings_path + '.agent-config.lock';
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     let fd;