@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/claim_phrases.ts

@@ -0,0 +1,71 @@
+/**
+ * Claim-phrase registry for `check_voice_lexicon` (brand-checkability roadmap 5.3).
+ *
+ * Static, literal, multi-word PHRASES — never bare words. A single word such as
+ * "only" or "best" is ordinary prose far too often to mean a claim (NG-10); a
+ * phrase like "industry-leading" or "the number one platform" is a claim that
+ * needs a proof. A hit is advisory: the finding says "needs proof", never
+ * "unlawful".
+ *
+ * PRE-REGISTERED: this list was frozen before each measurement. v1 missed the
+ * bar on `tests/fixtures/voice-lexicon/negative-corpus.txt`; v2 drops the four
+ * English single-word entries NG-10 already excludes and is measured on
+ * `negative-corpus-v2.txt`, a corpus it was not revised against (bar ≤ 0.1 hits
+ * per 10k words). Changing it re-opens the measurement.
+ *
+ * German phrases run at `hint` severity until a German negative corpus is
+ * registered (E5, 5.3).
+ */
+
+export type ClaimClass = 'superlative' | 'comparative' | 'absolute' | 'certification' | 'guarantee';
+
+export interface ClaimPhrase {
+    phrase: string;
+    cls: ClaimClass;
+    language: 'en' | 'de';
+}
+
+const en = (cls: ClaimClass, ...phrases: string[]): ClaimPhrase[] =>
+    phrases.map((phrase) => ({ phrase, cls, language: 'en' as const }));
+const de = (cls: ClaimClass, ...phrases: string[]): ClaimPhrase[] =>
+    phrases.map((phrase) => ({ phrase, cls, language: 'de' as const }));
+
+export const CLAIM_PHRASES: readonly ClaimPhrase[] = [
+    ...en(
+        'superlative',
+        'number one',
+        'no. 1',
+        "world's best",
+        "world's leading",
+        'world-leading',
+        'world-class',
+        'industry-leading',
+        'industry leading',
+        'market-leading',
+        'market leader',
+        'best-in-class',
+        'best in class',
+        'best-of-breed',
+        'the leading provider',
+        'the leading platform',
+        'second to none',
+    ),
+    ...en(
+        'comparative',
+        'faster than any',
+        'better than any',
+        'cheaper than any',
+        'more secure than any',
+        'outperforms all',
+        'outperforms every',
+        'beats every',
+    ),
+    ...en('absolute', 'never fails', 'zero downtime', '100% secure', '100% uptime', '100% accurate', 'completely secure'),
+    ...en('certification', 'officially certified', 'award-winning', 'award winning', 'clinically proven', 'scientifically proven'),
+    ...en('guarantee', 'guaranteed results', 'guaranteed to work', 'we guarantee', 'money-back guarantee', 'risk-free'),
+    ...de('superlative', 'nummer eins', 'marktführer', 'weltweit führend', 'branchenführend', 'unschlagbar', 'unübertroffen'),
+    ...de('comparative', 'schneller als jede', 'besser als jede', 'günstiger als jede'),
+    ...de('absolute', '100 % sicher', '100% sicher', 'absolut sicher', 'null ausfallzeit'),
+    ...de('certification', 'preisgekrönt', 'klinisch bewiesen', 'wissenschaftlich bewiesen'),
+    ...de('guarantee', 'garantiert', 'geld-zurück-garantie', 'risikofrei'),
+];

package/src/scripts/_lib/classify_update.ts

@@ -0,0 +1,171 @@
+/**
+ * `classifyUpdate` — what an update from `installed` to `candidate` should do on
+ * this machine: install it (`auto`), ask first (`ask`), tell the user (`notify`),
+ * nothing (`none`), or `action` — this machine cannot run the candidate until the
+ * user changes it (its `engines.node`), so it is never installed, not even on an
+ * approval. Every verdict carries the reasons that produced it.
+ *
+ * Pure by contract: no filesystem, no network, no process state. The caller
+ * gathers the inputs — the cached registry document, the running Node version, the
+ * install origin `classify_install_origin` already detects — and this only
+ * decides. `doctor --json` reports the verdict read-only (`update_verdict`), the surface it is
+ * meant to be reported on.
+ *
+ * The one invariant everything else serves: uncertainty of any kind never
+ * resolves to `auto`.
+ */
+import { CONSUMER_IMPACT_VALUES, type ConsumerImpact } from './consumer_impact';
+import type { InstallOrigin as RunningOrigin } from './update_check';
+import { compare_versions, node_engine_satisfied, parse_version } from './version_order';
+
+export type UpdateAction = 'auto' | 'ask' | 'notify' | 'none' | 'action';
+/** The running install as `classify_install_origin` reports it, plus a source checkout. */
+export type InstallOrigin = RunningOrigin | 'source-checkout';
+export type UpdateMode = 'off' | 'notify' | 'ask' | 'auto';
+
+export interface ClassifyUpdateInput {
+    readonly installed: string;
+    readonly candidate: string;
+    readonly origin: InstallOrigin;
+    readonly env: {
+        readonly ci: boolean;
+        readonly interactive: boolean;
+        readonly noUpdateCheck: boolean;
+        /** The Node version of the machine the update would run on, `v`-prefixed. */
+        readonly nodeVersion: string;
+        /** ISO-8601 instant the decision is made at. */
+        readonly now: string;
+    };
+    /** The `agentConfig.impact` block of the candidate's registry document — untrusted. */
+    readonly impactMap: unknown;
+    /** The candidate's `engines` block — untrusted. */
+    readonly engines: unknown;
+    readonly publishedAt: string | null;
+    readonly deprecated: unknown;
+    /** True only when the registry document carried a provenance attestation. */
+    readonly provenance: boolean | null;
+    readonly settings: {
+        readonly mode?: UpdateMode | undefined;
+        readonly projectPin?: string | null;
+        readonly minReleaseAgeHours?: number;
+    };
+}
+
+export interface UpdateVerdict {
+    readonly action: UpdateAction;
+    readonly reasons: readonly string[];
+}
+
+interface RangeImpact {
+    readonly forged: string | null;
+    readonly worst: ConsumerImpact | null;
+    readonly security: boolean;
+}
+
+function read_impact_range(map: unknown, installed: string, candidate: string): RangeImpact | null {
+    if (map === null || map === undefined) return null;
+    if (typeof map !== 'object' || Array.isArray(map)) {
+        return { forged: 'impact map is not an object', worst: null, security: false };
+    }
+    const rank = (i: ConsumerImpact): number => CONSUMER_IMPACT_VALUES.indexOf(i);
+    let worst: ConsumerImpact | null = null;
+    let security = false;
+    for (const [version, entry] of Object.entries(map as Record<string, unknown>)) {
+        if (parse_version(version) === null) return { forged: `impact map key '${version}' is not a version`, worst, security };
+        if (entry === null || typeof entry !== 'object') {
+            return { forged: `impact map entry ${version} is not an object`, worst, security };
+        }
+        const impact = (entry as Record<string, unknown>)['impact'];
+        if (!(CONSUMER_IMPACT_VALUES as readonly unknown[]).includes(impact)) {
+            return { forged: `impact map entry ${version} has impact '${String(impact)}'`, worst, security };
+        }
+        if (compare_versions(version, installed) !== 1 || compare_versions(version, candidate) === 1) continue;
+        if (worst === null || rank(impact as ConsumerImpact) > rank(worst)) worst = impact as ConsumerImpact;
+        security = security || (entry as Record<string, unknown>)['security'] === true;
+    }
+    return { forged: null, worst, security };
+}
+
+/**
+ * The local machine overrides the published map: a candidate whose
+ * `engines.node` this runtime does not satisfy — or that cannot be checked —
+ * is `action` here whatever the map says. No `engines.node` at all, or a
+ * prerelease runtime, is an unknown, not an override.
+ */
+export function machine_override(
+    engines: unknown,
+    nodeVersion: string,
+): { impact: 'action'; reason: string } | { impact: null; reason: string | null } {
+    const range = engines !== null && typeof engines === 'object' ? (engines as Record<string, unknown>)['node'] : undefined;
+    if (range === undefined) return { impact: null, reason: 'candidate declares no engines.node' };
+    if ((parse_version(nodeVersion)?.pre.length ?? 0) > 0) return { impact: null, reason: `running Node ${nodeVersion} is a prerelease` };
+    const ok = node_engine_satisfied(range, nodeVersion);
+    if (ok === true) return { impact: null, reason: null };
+    const why = ok === false ? 'is not satisfied by' : 'cannot be checked against';
+    return { impact: 'action', reason: `engines.node '${String(range)}' ${why} ${nodeVersion}` };
+}
+
+function suppression(input: ClassifyUpdateInput): string | null {
+    if (input.env.ci) return 'suppressed: CI';
+    if (!input.env.interactive) return 'suppressed: non-interactive';
+    if (input.origin === 'source-checkout') return 'suppressed: source checkout';
+    if (input.origin === 'ephemeral') return 'suppressed: ephemeral npx run has nothing to update';
+    if (input.env.noUpdateCheck) return 'suppressed: AGENT_CONFIG_NO_UPDATE_CHECK=1';
+    if (input.settings.mode === 'off') return 'suppressed: mode off';
+    return null;
+}
+
+export function classifyUpdate(input: ClassifyUpdateInput): UpdateVerdict {
+    const suppressed = suppression(input);
+    if (suppressed !== null) return { action: 'none', reasons: [suppressed] };
+
+    const order = compare_versions(input.candidate, input.installed);
+    if (order === null) return { action: 'none', reasons: ['unparseable version: no action'] };
+    if (order !== 1) return { action: 'none', reasons: [`candidate ${input.candidate} is not newer than ${input.installed}`] };
+
+    const ask: string[] = [];
+    const uncertain: string[] = [];
+
+    const local = machine_override(input.engines, input.env.nodeVersion);
+    if (local.impact === 'action') return { action: 'action', reasons: [local.reason] };
+    if (local.reason !== null) uncertain.push(local.reason);
+
+    const range = read_impact_range(input.impactMap, input.installed, input.candidate);
+    const security = range?.security === true;
+    const waits: string[] = [];
+    if (input.deprecated === true || (typeof input.deprecated === 'string' && input.deprecated !== '')) {
+        waits.push('wait: candidate is deprecated');
+    }
+    const gateHours = input.settings.minReleaseAgeHours ?? 0;
+    // `NaN > 0` is false, so an unreadable gate would otherwise read as no gate.
+    if (!Number.isFinite(gateHours)) uncertain.push('release-age gate is not a number');
+    else if (gateHours > 0) {
+        const published = input.publishedAt === null ? NaN : Date.parse(input.publishedAt);
+        const now = Date.parse(input.env.now);
+        if (Number.isNaN(published) || Number.isNaN(now)) uncertain.push('publish time unknown under a release-age gate');
+        else if (now - published < gateHours * 3_600_000) waits.push(`wait: published less than ${gateHours} h ago`);
+    }
+    if (waits.length > 0) {
+        return security ? { action: 'notify', reasons: [...waits, 'security fix in range'] } : { action: 'none', reasons: waits };
+    }
+
+    if (range === null) uncertain.push('impact map unavailable');
+    else if (range.forged !== null) ask.push(`untrusted impact map: ${range.forged}`);
+    else if (range.worst === 'action') ask.push('a release in range needs consumer action');
+    if (ask.length > 0) return { action: 'ask', reasons: ask };
+
+    const notify: string[] = [];
+    if (range?.worst === 'notice') notify.push('a release in range carries a notice');
+    if (security) notify.push('security fix in range');
+    if (input.provenance !== true) uncertain.push('provenance attestation missing');
+    if (input.settings.projectPin) uncertain.push(`project pins ${input.settings.projectPin}`);
+    else if (input.origin === 'project-pin') uncertain.push('install is pinned by the project');
+    if (input.origin === 'unknown') uncertain.push('install origin unknown');
+    if (parse_version(input.candidate)!.pre.length > 0) uncertain.push('candidate is a prerelease');
+    if (input.settings.mode === undefined) uncertain.push('update mode not set');
+
+    const blocking = [...uncertain, ...(range?.worst === 'notice' ? notify : [])];
+    if (blocking.length > 0) return { action: 'notify', reasons: [...uncertain, ...notify] };
+    if (input.settings.mode !== 'auto') return { action: 'notify', reasons: [`mode ${input.settings.mode} does not install`, ...notify] };
+    return { action: 'auto', reasons: ['every input known and no release in range needs a hand', ...notify] };
+}

package/src/scripts/_lib/claude_builtin_names.ts

@@ -19,10 +19,12 @@
 //      registration with `user-invocable: false` (Claude may still load it
 //      automatically; the built-in keeps the `/name`).
 //
-// Source: https://code.claude.com/docs/en/commands (fetched 2026-07-10),
-// plus a small legacy set still present in older Claude Code versions.
-// Refresh trigger: a package artefact stops appearing in Claude Code, or a
-// release-notes entry adds a new built-in command.
+// Source: https://code.claude.com/docs/en/commands (fetched 2026-07-10), the
+// design family read offline from host 2.1.301 (2026-10-16), plus a small
+// legacy set still present in older Claude Code versions.
+// Refresh trigger: a package artefact stops appearing in Claude Code, a
+// release-notes entry adds a new built-in command, or the pinned host fixture
+// `tests/fixtures/host-builtins/<version>.json` is re-read at a newer host.
 
 const _CURRENT = [
     'add-dir',
@@ -47,7 +49,10 @@ const _CURRENT = [
     'dataviz',
     'debug',
     'deep-research',
+    'design',
+    'design-consent',
     'design-login',
+    'design-revoke',
     'design-sync',
     'desktop',
     'diff',

package/src/scripts/_lib/claude_hook_scope.ts

@@ -0,0 +1,195 @@
+/**
+ * Where agent-config's Claude hooks are registered, which runtime they would
+ * reach right now, and which of four states that adds up to.
+ *
+ * `hooks:status` used to answer from one file: `<project>/.claude/settings.json`.
+ * Claude Code merges that file with `~/.claude/settings.json`, and a global
+ * install registers its hooks in the second, so a working global install read
+ * "missing" from any project without its own settings file — every fresh
+ * worktree. The same check also read "installed" for a project settings file
+ * that merely existed, whatever hooks it carried, foreign ones included.
+ *
+ * Read-only and never throws: the post-install smoke probe runs this, and a
+ * malformed settings file must degrade the report, not abort it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { MANAGED_SIGNATURE } from './claude_settings_hooks.js';
+
+export type ClaudeHookState = 'not-installed' | 'installed-not-executable' | 'executable' | 'observed-at-runtime';
+
+/** The dispatcher a hook command would reach, in the order the command tries them. */
+export type ClaudeHookRuntime = 'staged' | 'path-cli' | 'none';
+
+export interface ClaudeHookScope {
+    registered_in: Array<'global' | 'project'>;
+    /** Commands carrying the managed signature; foreign commands are never counted here. */
+    managed_commands: { global: number; project: number };
+    foreign_commands: { global: number; project: number };
+    runtime: ClaudeHookRuntime;
+    runtime_version: string | null;
+    /** Set when the runtime that wins is OLDER than the source checkout it serves. */
+    version_skew: string | null;
+    state: ClaudeHookState;
+}
+
+export interface ClaudeHookScopeInput {
+    projectRoot: string;
+    home: string;
+    /** `<event4u root>/runtime` — where the staged runtime and carrier.json live. */
+    runtimeRoot: string;
+    /** The PATH to search for a global `agent-config`. */
+    pathEnv: string;
+}
+
+function readJson(file: string): unknown {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Managed and foreign command counts in one settings file. */
+function countCommands(file: string): { managed: number; foreign: number } {
+    const out = { managed: 0, foreign: 0 };
+    const doc = readJson(file);
+    const hooks = isObject(doc) ? doc['hooks'] : null;
+    if (!isObject(hooks)) return out;
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+            const entries = isObject(group) ? group['hooks'] : null;
+            if (!Array.isArray(entries)) continue;
+            for (const h of entries) {
+                const cmd = isObject(h) ? h['command'] : null;
+                if (typeof cmd !== 'string') continue;
+                if (cmd.includes(MANAGED_SIGNATURE)) out.managed += 1;
+                else out.foreign += 1;
+            }
+        }
+    }
+    return out;
+}
+
+function exists(p: string): boolean {
+    try {
+        fs.accessSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function executable(p: string): boolean {
+    try {
+        fs.accessSync(p, fs.constants.X_OK);
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function versionAt(pkgDir: string): string | null {
+    const doc = readJson(path.join(pkgDir, 'package.json'));
+    const v = isObject(doc) ? doc['version'] : null;
+    return typeof v === 'string' ? v : null;
+}
+
+/** Numeric dotted-version compare; a non-numeric part compares as 0. */
+function olderThan(a: string, b: string): boolean {
+    const pa = a.split(/[.-]/).map((x) => Number.parseInt(x, 10) || 0);
+    const pb = b.split(/[.-]/).map((x) => Number.parseInt(x, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0) return d < 0;
+    }
+    return false;
+}
+
+/**
+ * The runtime the installed hook command reaches, tried in the SAME order as
+ * `build_claude_hook_matrix` — a status that resolved in a different order
+ * would report a runtime the hooks never use. That command trusts only two:
+ * the staged runtime, then an `agent-config` on PATH whose path is absolute and
+ * outside the project. Nothing inside the project counts, however runnable.
+ */
+function resolveRuntime(input: ClaudeHookScopeInput): { runtime: ClaudeHookRuntime; version: string | null } {
+    const { projectRoot, runtimeRoot, pathEnv } = input;
+    const current = path.join(runtimeRoot, 'current');
+    let nodePath = '';
+    try {
+        nodePath = fs.readFileSync(path.join(current, 'node'), 'utf8').trim();
+    } catch {
+        nodePath = '';
+    }
+    if (nodePath !== '' && executable(nodePath) && exists(path.join(current, 'dist', 'hooks', 'dispatch.js'))) {
+        return { runtime: 'staged', version: versionAt(current) };
+    }
+    const cli = firstOnPath('agent-config', pathEnv);
+    if (cli !== null && path.isAbsolute(cli) && !insideDir(cli, projectRoot)) return { runtime: 'path-cli', version: null };
+    return { runtime: 'none', version: null };
+}
+
+/** `command -v` reads the first PATH hit, so only that one decides. */
+function firstOnPath(name: string, pathEnv: string): string | null {
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (dir === '') continue;
+        const p = path.join(dir, name);
+        if (executable(p)) return p;
+    }
+    return null;
+}
+
+function insideDir(p: string, dir: string): boolean {
+    const rel = path.relative(path.resolve(dir), path.resolve(p));
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function observedReached(runtimeRoot: string): boolean {
+    const doc = readJson(path.join(runtimeRoot, 'carrier.json'));
+    const hosts = isObject(doc) ? doc['hosts'] : null;
+    const claude = isObject(hosts) ? hosts['claude'] : null;
+    return isObject(claude) && claude['outcome'] === 'reached';
+}
+
+export function claudeHookScope(input: ClaudeHookScopeInput): ClaudeHookScope {
+    const global = countCommands(path.join(input.home, '.claude', 'settings.json'));
+    const project = countCommands(path.join(input.projectRoot, '.claude', 'settings.json'));
+    const registered_in: Array<'global' | 'project'> = [];
+    if (global.managed > 0) registered_in.push('global');
+    if (project.managed > 0) registered_in.push('project');
+
+    const { runtime, version } = resolveRuntime(input);
+
+    // A source checkout served by an OLDER staged or global runtime runs the old
+    // guards while the maintainer edits the new ones. Surfaced, never enforced
+    // here: a status report that refused would hide the very thing it reports.
+    let version_skew: string | null = null;
+    const isSource = exists(path.join(input.projectRoot, 'src', 'scripts', 'hook_manifest.yaml'));
+    const checkoutVersion = isSource ? versionAt(input.projectRoot) : null;
+    if (runtime === 'staged' && version !== null && checkoutVersion !== null && olderThan(version, checkoutVersion)) {
+        version_skew = `staged runtime ${version} is older than this checkout ${checkoutVersion} — its hooks run the older guards until the checkout's bundle is built (npm run build:hooks) or the runtime is restaged`;
+    }
+
+    let state: ClaudeHookState;
+    if (registered_in.length === 0) state = 'not-installed';
+    else if (runtime === 'none') state = 'installed-not-executable';
+    else if (observedReached(input.runtimeRoot)) state = 'observed-at-runtime';
+    else state = 'executable';
+
+    return {
+        registered_in,
+        managed_commands: { global: global.managed, project: project.managed },
+        foreign_commands: { global: global.foreign, project: project.foreign },
+        runtime,
+        runtime_version: version,
+        version_skew,
+        state,
+    };
+}

package/src/scripts/_lib/claude_settings_hooks.ts

@@ -110,49 +110,133 @@ export function build_claude_hook_matrix(manifest_path: string): ClaudeHookMatri
         const ac_event = String(ac_raw);
         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: string): string {
+    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: string): string {
+    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(): string {
+    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: string): string {
+    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: unknown): boolean {
     if (typeof group !== 'object' || group === null || Array.isArray(group)) return false;
     const hooks = (group as HookGroup).hooks;
@@ -166,7 +250,7 @@ function _is_managed_group(group: unknown): boolean {
     );
 }
 
-function _read_settings(settings_path: string): Record<string, unknown> {
+export function _read_settings(settings_path: string): Record<string, unknown> {
     if (!fs.existsSync(settings_path)) return {};
     const raw = fs.readFileSync(settings_path, 'utf8');
     if (raw.trim() === '') return {};
@@ -182,7 +266,7 @@ function _read_settings(settings_path: string): Record<string, unknown> {
     return parsed as Record<string, unknown>;
 }
 
-function _with_lock<T>(settings_path: string, fn: () => T): T {
+export function _with_lock<T>(settings_path: string, fn: () => T): T {
     const lockPath = settings_path + '.agent-config.lock';
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     let fd: number;