@event4u/agent-config 14.21.0 → 14.22.0

package/src/scripts/hooks/chain_nudge_hook.ts

@@ -0,0 +1,282 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse chain nudge — deterministic, warn-only.
+ *
+ * WHY A CARRIER EXISTS AT ALL. `token-efficiency` § One command per Bash call
+ * is `type: auto`, so its triggers match the PROMPT, and no prompt announces
+ * that the next tool call will be a chained Bash command. The obligation
+ * applies at tool-call time and was reachable by nothing there. This concern
+ * is that reach, and it is the only thing in the tree that reads
+ * `tool_input.command` for this purpose.
+ *
+ * WHAT IT IS FOR, MEASURED. The host splits a compound command on `&&`, `||`,
+ * `;`, `|`, `|&`, `&` and newlines and requires each segment to match the
+ * allowlist independently, so one unmatched segment sends the whole call down
+ * the permission path even when every other segment was already allowed. Over
+ * 40,268 real Bash calls on the maintainer's machine, 17.9 % had a head token
+ * matching no pattern and 5,037 of those were a leading `VAR=…` assignment —
+ * a shape that cannot be written as an allowlist pattern at all. That class
+ * shrinks only by not writing it.
+ *
+ * WHAT IT DOES NOT FLAG, DELIBERATELY. A pipe of ordinary filters
+ * (`grep foo file | head`) is one command with a filter, not two work steps.
+ * A redirect has its target checked against the file rules on its own. A
+ * heredoc is a command with input. Flagging any of those would make the
+ * nudge noise, and a nudge that fires on correct usage is worse than none.
+ *
+ * NEVER BLOCKS. The dispatcher contract is 0 allow · 2 warn, and a warn on
+ * `pre_tool_use` with `severity: advisory` is an injection, not a deny — the
+ * same channel `code-graph-nudge` and `ui-route-nudge` already use. Every
+ * failure path returns allow: unreadable stdin, malformed JSON, unwritable
+ * latch. A token optimisation must never break a tool call.
+ *
+ * ONCE PER SESSION. A latch keyed by session id, in the state directory
+ * `code-graph-nudge.json` already occupies. The rule body reaches the model
+ * once, early, on the first chained call — repeating it every call would be
+ * the nagging this codebase refuses elsewhere.
+ *
+ * ON BY DEFAULT, WITH AN OPT-OUT. Unlike `code-graph-nudge`, which gates on a
+ * project capability that may not exist, the fact this nudge carries is a
+ * property of the HOST's permission matcher and is therefore true in every
+ * consumer. `hooks.chain_nudge.enabled: false` turns it off.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { readHookStdin } from './hook_stdin.js';
+
+const SETTINGS_FILE = '.agent-settings.yml';
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * `hooks.chain_nudge.enabled: false` mini-parser. Absent means ON, which is
+ * the inverse of `code_graph_nudge.enabled` and stated in the header: the
+ * fact carried here holds on every host, so absent-means-off would ship a
+ * carrier nobody receives.
+ */
+export function enabled(root: string): boolean {
+    let text: string;
+    try {
+        const f = path.join(root, SETTINGS_FILE);
+        if (!fs.statSync(f).isFile()) return true;
+        text = fs.readFileSync(f, 'utf-8');
+    } catch {
+        return true;
+    }
+    let inHooks = false;
+    let inCn = false;
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inHooks = /^hooks\s*:\s*$/.test(line);
+            inCn = false;
+            continue;
+        }
+        if (inHooks) {
+            if (/^\s+chain_nudge\s*:\s*$/.test(line)) {
+                inCn = true;
+                continue;
+            }
+            if (inCn && /^\s{0,3}\S/.test(line)) inCn = false;
+        }
+        if (inCn && /^\s+enabled\s*:\s*false\b/.test(line)) return false;
+    }
+    return true;
+}
+
+/**
+ * Strip quoted spans and heredoc bodies so an operator inside a string
+ * literal cannot be read as chaining. `grep "a && b" f` is one command, and a
+ * scanner that misses that fires on correct usage — the failure this concern
+ * must not have.
+ */
+export function stripLiterals(cmd: string): string {
+    let out = '';
+    let i = 0;
+    let quote: string | null = null;
+    while (i < cmd.length) {
+        const c = cmd[i] as string;
+        if (quote) {
+            if (c === '\\' && quote === '"') {
+                i += 2;
+                continue;
+            }
+            if (c === quote) quote = null;
+            i += 1;
+            continue;
+        }
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            i += 1;
+            continue;
+        }
+        const heredoc = /^<<-?\s*'?"?([A-Za-z_][A-Za-z0-9_]*)'?"?/.exec(cmd.slice(i));
+        if (heredoc) {
+            const tag = heredoc[1] as string;
+            const end = cmd.indexOf(`\n${tag}`, i);
+            i = end === -1 ? cmd.length : end + tag.length + 1;
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+
+/** What the nudge saw, or null when the command is not chained work. */
+export function detectChaining(command: string): string | null {
+    const bare = stripLiterals(command);
+    if (/^\s*[A-Za-z_][A-Za-z0-9_]*=/.test(bare) && /[;\n]/.test(bare)) {
+        return 'a leading `VAR=…` assignment carrying state into a later segment';
+    }
+    if (/&&|\|\|/.test(bare)) return 'work steps chained with `&&` / `||`';
+    if (/;\s*\S/.test(bare)) return 'work steps chained with `;`';
+    return null;
+}
+
+/**
+ * Tools that carry a shell command. Mirrors `ship_diff_volume_hook` and
+ * `git_command_classifier` rather than hardcoding `Bash`: the tool name is
+ * host-specific, and the manifest's own `code-graph-nudge` block warns about
+ * exactly this spread. A named tool outside the set is declined; a payload
+ * naming no tool still reads, which is the bare-host shape.
+ */
+const COMMAND_TOOLS: ReadonlySet<string> = new Set([
+    'launch-process',
+    'launch_process',
+    'Bash',
+    'BashTool',
+    'run-process',
+    'runProcess',
+    'shell',
+    'execute_shell',
+    'RunShellCommand',
+]);
+
+/** The shell command this call carries, or '' when it carries none. */
+export function bashCommand(envelope: JsonObject): string {
+    const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const nameVal = payload['tool_name'] ?? payload['toolName'] ?? payload['tool'];
+    if (typeof nameVal === 'string' && !COMMAND_TOOLS.has(nameVal)) return '';
+    const ti = payload['tool_input'] ?? payload['toolInput'];
+    if (isObject(ti)) {
+        const c = ti['command'];
+        if (typeof c === 'string') return c;
+    }
+    const c = payload['command'];
+    return typeof c === 'string' ? c : '';
+}
+
+function sessionId(envelope: JsonObject): string {
+    const s = envelope['session_id'] ?? envelope['sessionId'];
+    return typeof s === 'string' && s ? s : 'default';
+}
+
+function latchFile(root: string): string {
+    return path.join(root, 'agents', 'runtime', 'state', 'chain-nudge.json');
+}
+
+function alreadyNudged(root: string, session: string): boolean {
+    try {
+        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
+        return state[session] === true;
+    } catch {
+        return false;
+    }
+}
+
+function latch(root: string, session: string): void {
+    try {
+        const p = latchFile(root);
+        let state: Record<string, boolean> = {};
+        try {
+            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
+        } catch {
+            /* fresh */
+        }
+        state[session] = true;
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(state));
+    } catch {
+        /* fail-open: a persistence failure must not break the tool call */
+    }
+}
+
+/** The nudge line — one line, names what was seen and what to do instead. */
+export function nudgeReason(seen: string): string {
+    return (
+        `This Bash call chains work: ${seen}. The host matches each segment against ` +
+        'the allowlist independently, so one unmatched segment sends the whole call ' +
+        'down the permission path. Send N commands as N Bash calls in ONE block — ' +
+        'that is the batch. `D=/repo; cd $D && git status` is `git -C /repo status`. ' +
+        'Pipes of filters, redirects and heredocs are fine and are not what this flags. ' +
+        'See `token-efficiency` § One command per Bash call.'
+    );
+}
+
+export function main(): number {
+    let envelope: JsonValue;
+    try {
+        const raw = readHookStdin();
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (!isObject(envelope)) return EXIT_ALLOW;
+
+    // ORDER IS LOAD-BEARING, and getting it wrong cost 26 ms at p95. Every
+    // predicate below that touches the filesystem runs AFTER the in-memory
+    // ones, so the overwhelming majority of tool calls — every non-shell
+    // call, and every unchained shell call — exit having read no file at all.
+    // The first draft called `enabled()` first, which put a settings read in
+    // front of every single pre_tool_use event on the host.
+    const command = bashCommand(envelope);
+    if (!command) return EXIT_ALLOW;
+
+    const seen = detectChaining(command);
+    if (!seen) return EXIT_ALLOW;
+
+    const cwd = envelope['cwd'];
+    const pr = envelope['workspace_root'] ?? envelope['project_root'];
+    const root = typeof cwd === 'string' && cwd ? cwd : typeof pr === 'string' && pr ? pr : '.';
+    if (!enabled(root)) return EXIT_ALLOW;
+
+    const session = sessionId(envelope);
+    if (alreadyNudged(root, session)) return EXIT_ALLOW;
+
+    latch(root, session);
+    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: nudgeReason(seen) })}\n`);
+    return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (isCliEntry()) process.exit(main());

package/src/scripts/hooks/code_graph_context_hook.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse code-graph context line (road-to-a-graph-that-is-shipped 1.2).
+ *
+ * Replaces `code_graph_nudge_hook.ts`, which shipped default-OFF behind
+ * `hooks.code_graph.enabled` — a flag the settings table itself described as
+ * "deprecated — honest null 2026-07-28", requiring a manual install of the
+ * ABI-locked parser pair. Phase 0.1 made that manual install unnecessary, so
+ * the flag's premise is gone and the flag with it.
+ *
+ * Two behavioural changes, and both are the reason the replacement exists
+ * rather than a rename:
+ *
+ * 1. It speaks ONLY when a graph actually exists — `fresh` or `behind:N`.
+ *    The nudge also fired on ABSENT, i.e. it advertised a capability the
+ *    consumer had not built and, before 0.1, could not build. A hook whose
+ *    common case is "you do not have this" is an advertisement, not context.
+ *    Absent → silent, which is what makes default-on defensible: a consumer
+ *    who never builds a graph never hears from this hook at all.
+ * 2. It carries STATE, not an instruction. `fresh` and `behind:N` are facts
+ *    the model cannot otherwise see, and `behind:N` is the one that changes a
+ *    decision — an answer from a graph N commits stale is worth less than the
+ *    same answer from a fresh one, and only the hook knows N.
+ *
+ * Delivery is the dispatcher's, not this hook's: returning `warn` + a reason
+ * makes `emitFor` lower it to the host's structured envelope — on Claude Code
+ * `hookSpecificOutput.additionalContext` at exit 0 (`claudeAdditionalContext`
+ * in host_semantics.ts). It is never a plain echo. On a host with no verified
+ * PreToolUse contract the dispatcher swallows concern stdout, so the same line
+ * is carried as a rule instead (`external-code-graph-interop`), which is what
+ * "per-host `enforced_by` resolved from the table, not from a host name" means
+ * in practice.
+ *
+ * Once per session (a latch keyed by session id), so it cannot nag.
+ * fail_closed: false — every error path returns allow; a context line must
+ * never break a tool call.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { detectSources, pickSource } from '../code_graph/detect.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+const CODE_EXT = /\.(php|ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+interface ToolIntent {
+    isSearch: boolean;
+    isCodeRead: boolean;
+}
+
+/**
+ * Best-effort read of the intercepted tool + its target from the envelope.
+ *
+ * Carried over from the nudge unchanged, and the manifest's `tools:` filter is
+ * pinned against exactly this branch surface — Grep, Glob, Read.
+ */
+export function classifyTool(envelope: JsonObject): ToolIntent {
+    const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const nameVal =
+        payload['tool_name'] ?? payload['toolName'] ?? payload['tool'] ?? envelope['tool_name'] ?? envelope['tool'];
+    const name = typeof nameVal === 'string' ? nameVal : '';
+    const ti = (isObject(payload['tool_input']) ? payload['tool_input'] : envelope['tool_input']) as
+        | JsonObject
+        | undefined;
+    const isSearch = name === 'Grep' || name === 'Glob';
+    let isCodeRead = false;
+    if (name === 'Read' && isObject(ti)) {
+        const fp = ti['file_path'] ?? ti['path'];
+        if (typeof fp === 'string') isCodeRead = CODE_EXT.test(fp);
+    }
+    return { isSearch, isCodeRead };
+}
+
+function sessionId(envelope: JsonObject): string {
+    const s = envelope['session_id'] ?? envelope['sessionId'];
+    return typeof s === 'string' && s ? s : 'default';
+}
+
+function latchFile(root: string): string {
+    return path.join(root, 'agents', 'runtime', 'state', 'code-graph-context.json');
+}
+function alreadySpoke(root: string, session: string): boolean {
+    try {
+        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
+        return state[session] === true;
+    } catch {
+        return false;
+    }
+}
+function latch(root: string, session: string): void {
+    try {
+        const p = latchFile(root);
+        let state: Record<string, boolean> = {};
+        try {
+            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
+        } catch {
+            /* fresh */
+        }
+        state[session] = true;
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(state));
+    } catch {
+        /* fail-open: a persistence failure must not break the tool call */
+    }
+}
+
+const NATIVE_CACHE = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
+
+/** The three-state staleness token this hook reports. */
+export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
+
+/**
+ * Resolve the graph's state for `root`.
+ *
+ * `absent` means no source at all — the silent case. A picked source whose
+ * staleness is UNKNOWN reads as `fresh`, mirroring `computeVerdict`'s own
+ * `picked.stale ? STALE : FRESH`: unknown is not treated as stale, because
+ * inventing a commit count would be worse than reporting none.
+ */
+export function graphState(root: string): GraphState {
+    const picked = pickSource(detectSources(root, path.join(root, NATIVE_CACHE)));
+    if (!picked) return 'absent';
+    if (picked.stale !== true) return 'fresh';
+    const behind = picked.commits_behind;
+    return `behind:${typeof behind === 'number' ? behind : 0}`;
+}
+
+/**
+ * The one line, ≤ ~45 tokens.
+ *
+ * It names the state and the verbs, and — on the stale branch — what the state
+ * costs. It does NOT claim the graph beats grep: that ordering question is
+ * `later/road-to-a-graph-that-wins.md`'s, and Kill register K5 forbids
+ * "graph-first" wording here.
+ */
+export function contextLine(state: GraphState): string {
+    if (state === 'fresh') {
+        return (
+            'code-graph: fresh. For structure questions (who calls / where used / impact) ' +
+            '`agent-config code-graph query|affected <symbol>` answers from the index; ' +
+            'grep is the other path — say which one answered.'
+        );
+    }
+    const n = state.slice('behind:'.length);
+    return (
+        `code-graph: ${n} commit(s) behind. Relationship answers may miss anything newer — ` +
+        '`agent-config code-graph refresh` rebuilds it, or use grep and say so.'
+    );
+}
+
+export function main(): number {
+    let envelope: JsonValue;
+    try {
+        const raw = readHookStdin();
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (!isObject(envelope)) return EXIT_ALLOW;
+
+    const cwd = envelope['cwd'];
+    const pr = envelope['workspace_root'] ?? envelope['project_root'];
+    const root = typeof cwd === 'string' && cwd ? cwd : typeof pr === 'string' && pr ? pr : '.';
+
+    const { isSearch, isCodeRead } = classifyTool(envelope);
+    if (!isSearch && !isCodeRead) return EXIT_ALLOW;
+
+    const session = sessionId(envelope);
+    if (alreadySpoke(root, session)) return EXIT_ALLOW; // once per session
+
+    let state: GraphState;
+    try {
+        state = graphState(root);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    // No graph is the silent case — see the header. Nothing is latched either,
+    // so a session that builds a graph mid-flight still gets the line once.
+    if (state === 'absent') return EXIT_ALLOW;
+
+    latch(root, session);
+    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: contextLine(state) })}\n`);
+    return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (isCliEntry()) process.exit(main());

package/src/scripts/hooks/concern_registry.ts

@@ -58,7 +58,8 @@ import { main as oneQuestionPerAskMain } from './one_question_per_ask_hook.js';
 import { main as rtkWrapMain } from './rtk_wrap_hook.js';
 import { _main as designPassMain } from './design_pass_hook.js';
 import { main as designSlopMain } from './design_slop_hook.js';
-import { main as codeGraphNudgeMain } from './code_graph_nudge_hook.js';
+import { main as codeGraphContextMain } from './code_graph_context_hook.js';
+import { main as chainNudgeMain } from './chain_nudge_hook.js';
 import { main as suggestionCaptureMain } from './suggestion_capture_hook.js';
 import { main as uiRouteNudgeMain } from './ui_route_nudge_hook.js';
 import { main as orchestrationRecordMain } from './orchestration_record_hook.js';
@@ -120,7 +121,8 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/rtk_wrap_hook.ts': rtkWrapMain as ConcernMain,
     'src/scripts/hooks/design_pass_hook.ts': designPassMain as ConcernMain,
     'src/scripts/hooks/design_slop_hook.ts': designSlopMain as ConcernMain,
-    'src/scripts/hooks/code_graph_nudge_hook.ts': codeGraphNudgeMain as ConcernMain,
+    'src/scripts/hooks/code_graph_context_hook.ts': codeGraphContextMain as ConcernMain,
+    'src/scripts/hooks/chain_nudge_hook.ts': chainNudgeMain as ConcernMain,
     'src/scripts/hooks/suggestion_capture_hook.ts': suggestionCaptureMain as ConcernMain,
     'src/scripts/hooks/ui_route_nudge_hook.ts': uiRouteNudgeMain as ConcernMain,
     'src/scripts/hooks/orchestration_record_hook.ts': orchestrationRecordMain as ConcernMain,

package/src/scripts/hooks/host_semantics.ts

@@ -95,7 +95,7 @@ function _joinReasons(reasons: readonly string[]): string {
  *
  * Exit 0 + this JSON is the documented way to surface advisory feedback
  * WITHOUT blocking — the mapping the four advisory PreToolUse concerns
- * (design-slop, code-graph-nudge, rtk-wrap, block-config-weakening's
+ * (design-slop, code-graph-context, rtk-wrap, block-config-weakening's
  * advisory path) always intended.
  */
 export function claudeAdditionalContext(event: string, text: string): string {

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -16,7 +16,7 @@
  * Fires only on an `Agent` / `Task` tool-use completion (the two names this
  * repo has observed for the subagent-dispatch tool across hosts/versions).
  * Every other tool call is a silent no-op — same tool-filter discipline as
- * `code-graph-nudge` (`tools: [Agent, Task]` in the manifest entry keeps the
+ * `code-graph-context` (`tools: [Agent, Task]` in the manifest entry keeps the
  * dispatcher from paying this concern's cost on unrelated calls).
  *
  * Sync vs async (road-to-orchestrator-first-execution measured: 326 of 370
@@ -89,7 +89,7 @@ export const DISPATCH_TOOL_NAMES: ReadonlySet<string> = new Set(['Agent', 'Task'
  * Unwrap the dispatcher envelope (`{schema_version, platform, event,
  * payload}`) down to the platform-native payload. Falls back to the
  * top-level object for direct/legacy invocation (same shape both
- * `pr_url_reminder_hook.ts` and `code_graph_nudge_hook.ts` handle).
+ * `pr_url_reminder_hook.ts` and `code_graph_context_hook.ts` handle).
  */
 export function unwrapPayload(envelope: JsonObject): JsonObject {
     const inner = envelope['payload'];

package/src/scripts/hooks/rule_inject_hook.ts

@@ -34,7 +34,7 @@
  * NEVER BLOCKS. Every failure path returns 0: unreadable stdin, malformed JSON,
  * missing router, unreadable body, unwritable state. The one non-zero exit is
  * the host's advisory context channel (exit 2 + `decision: "warn"`), the same
- * channel `ui-route-nudge` and `code-graph-nudge` already use on `pre_tool_use`
+ * channel `ui-route-nudge` and `code-graph-context` already use on `pre_tool_use`
  * with `severity: advisory` — a warn there is an injection, not a deny.
  *
  * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `user_prompt_submit` and

package/src/scripts/hooks/skill_route_hook.ts

@@ -140,7 +140,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { readHookStdin } from "./hook_stdin.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
-import { OBSERVATION_LOG, readObservationLog, resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { OBSERVATION_LOG, readObservationLog, resolveSkillCatalogueRoots } from "../_lib/skill_catalogue.js";
 import { knownBareNames } from "../_lib/skill_catalogue_series.js";
 import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
 
@@ -252,13 +252,20 @@ export interface RouteDecision {
  */
 export function routeDecision(
   prompt: string,
-  skillsDir: string | null,
+  // One root, or every readable root. `null` and `[]` are the same answer — no
+  // catalogue was read — and both must stay silent rather than rank nothing and
+  // call that a result.
+  skillsDir: string | readonly string[] | null,
   bareProvider?: () => Set<string> | null,
 ): RouteDecision {
   const silent: RouteDecision = { rows: [], suppressed: 0 };
   if (skillsDir === null) return silent;
+  if (Array.isArray(skillsDir) && skillsDir.length === 0) return silent;
   // Denominator floor BEFORE the catalogue read: a prompt too short to score
-  // meaningfully cannot produce a pointer worth 337 file reads either.
+  // meaningfully cannot produce a pointer worth the read either. The count is
+  // deliberately not stated — it used to say "337 file reads", which was one
+  // root; the union reads every readable root and the figure depends on the
+  // machine's install.
   try {
     if (_tokenize(prompt).size < MIN_TASK_TERMS) return silent;
   } catch {
@@ -346,7 +353,7 @@ export function main(): number {
   const root = _workspaceRoot(env);
   const platform = env["platform"];
   const host = typeof platform === "string" && platform ? platform : null;
-  const { rows, suppressed } = routeDecision(prompt, resolveSkillsRoot(root), () =>
+  const { rows, suppressed } = routeDecision(prompt, resolveSkillCatalogueRoots(root), () =>
     knownBareForHost(root, host),
   );
   if (rows.length === 0) return EXIT_ALLOW; // silence is the default