@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/hooks/code_graph_nudge_hook.ts

@@ -0,0 +1,191 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse code-graph nudge (ADR-124 Phase 4) — deterministic, warn-only.
+ *
+ * When a code-graph source is available and the agent is about to search or
+ * read source files, surface a one-line reminder to query the graph first.
+ * NEVER blocks (dispatcher contract: 0 allow · 2 warn) — Source G's strict
+ * block-the-first-read mode is deliberately NOT ported (blocking reads on a
+ * possibly-stale index violates the minimal-safe-diff posture). Once per
+ * session (a latch keyed by session id), so it cannot nag.
+ *
+ * Default-OFF. Fires only when `hooks.code_graph.enabled: true`. Disabled /
+ * missing / already-latched → no-op exit 0. fail_closed: false — any error
+ * returns allow; a token optimisation must never break a tool call.
+ *
+ * Branches (first eligible search/read this session):
+ *   present + fresh → "query the graph first"
+ *   present + stale → "index N commits behind — rebuild"
+ *   absent          → "no graph — build one?"
+ */
+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 SETTINGS_FILE = '.agent-settings.yml';
+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);
+}
+
+/** `hooks.code_graph.enabled: true` mini-parser (mirrors rtk_wrap_hook). */
+export function enabled(root: string): boolean {
+    const f = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(f).isFile()) return false;
+        text = fs.readFileSync(f, 'utf-8');
+    } catch {
+        return false;
+    }
+    let inHooks = false;
+    let inCg = 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);
+            inCg = false;
+            continue;
+        }
+        if (inHooks) {
+            if (/^\s+code_graph\s*:\s*$/.test(line)) {
+                inCg = true;
+                continue;
+            }
+            if (inCg && /^\s{0,3}\S/.test(line)) inCg = false;
+        }
+        if (inCg && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+    }
+    return false;
+}
+
+interface ToolIntent {
+    isSearch: boolean;
+    isCodeRead: boolean;
+}
+
+/** Best-effort read of the intercepted tool + its target from the envelope. */
+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-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 */
+    }
+}
+
+const NATIVE_CACHE = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
+
+/** The nudge line for the current source state (≤40 tokens, one line). */
+export function nudgeReason(root: string): string {
+    const verdicts = detectSources(root, path.join(root, NATIVE_CACHE));
+    const picked = pickSource(verdicts);
+    if (!picked) {
+        return 'No code-graph found. For "who calls / where used / impact" run `agent-config code-graph refresh` once, then `agent-config code-graph query <symbol>` instead of grepping blind.';
+    }
+    if (picked.stale) {
+        return `code-graph is ${picked.commits_behind ?? 'N'} commit(s) behind — rebuild with \`agent-config code-graph refresh\` before trusting relationship answers.`;
+    }
+    return 'A fresh code-graph is present — for structure questions run `agent-config code-graph query|affected <symbol>` first; grep is the fallback (say which answered).';
+}
+
+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 : '.';
+    if (!enabled(root)) return EXIT_ALLOW;
+
+    const { isSearch, isCodeRead } = classifyTool(envelope);
+    if (!isSearch && !isCodeRead) return EXIT_ALLOW;
+
+    const session = sessionId(envelope);
+    if (alreadyNudged(root, session)) return EXIT_ALLOW; // once per session
+
+    let reason: string;
+    try {
+        reason = nudgeReason(root);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    latch(root, session);
+    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason })}\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

@@ -0,0 +1,75 @@
+/**
+ * concern_registry — in-process concern table for the single-process
+ * hook dispatcher (road-to-credible-install Phase 1).
+ *
+ * Maps every `hook_manifest.yaml` concern script path to its statically
+ * imported module so the dispatcher can run concerns IN-PROCESS instead of
+ * re-spawning tsx per concern (the verified ~1.6 s p50 hot path). Static
+ * imports are deliberate: esbuild folds the whole table into
+ * `dist/hooks/dispatch.js`, so one `node` start covers dispatcher + every
+ * concern.
+ *
+ * Parity is CI-enforced (tests/hooks/concern_registry_parity.test.ts):
+ * every concern in the manifest MUST have a registry entry — a new concern
+ * that forgets the registry line falls back to the spawn path and silently
+ * reintroduces the latency class this table removed.
+ *
+ * Invocation contract (mirrors the historical child process exactly):
+ *   - stdin  → hook_stdin override (concerns read via readHookStdin())
+ *   - argv   → process.argv swapped to [node, <script>, ...args] for the call
+ *   - cwd    → process.chdir(workspace) for the call, restored after
+ *   - stdout/stderr → captured via write-swap, returned to the dispatcher
+ *   - rc     → the concern's `main()` return value (undefined → 0)
+ *   - crash  → caught by the dispatcher and mapped to rc 3 (fail-open /
+ *              fail-closed reduction unchanged)
+ */
+
+import { main as chatHistoryMain } from '../chat_history.js';
+import { main as hotContextMain } from '../hot_context_hook.js';
+import { main as roadmapProgressMain } from '../roadmap_progress_hook.js';
+import { main as onboardingGateMain } from '../onboarding_gate_hook.js';
+import { main as contextHygieneMain } from '../context_hygiene_hook.js';
+import { main as verifyBeforeCompleteMain } from '../verify_before_complete_hook.js';
+import { main as minimalSafeDiffMain } from '../minimal_safe_diff_hook.js';
+import { main as injectionScanMain } from '../injection_scan_hook.js';
+import { main as memoryLearnMain } from '../memory_learn_hook.js';
+import { main as firstRunGateMain } from '../first_run_gate_hook.js';
+import { main as profileStalenessMain } from '../profile_staleness_hook.js';
+import { main as wrapperFreshnessMain } from '../wrapper_freshness_hook.js';
+import { main as surfaceProbeMain } from '../surface_probe_hook.js';
+import { main as teamReviewGateMain } from '../team_review_gate_hook.js';
+import { main as prUrlReminderMain } from '../pr_url_reminder_hook.js';
+import { main as sessionCanaryMain } from '../session_canary_hook.js';
+import { main as blockNoVerifyMain } from './block_no_verify.js';
+import { main as blockKernelRuleWritesMain } from './block_kernel_rule_writes.js';
+import { main as rtkWrapMain } from './rtk_wrap_hook.js';
+import { main as designSlopMain } from './design_slop_hook.js';
+import { main as codeGraphNudgeMain } from './code_graph_nudge_hook.js';
+
+/** A concern `main` — argv-taking or not; both shapes exist. */
+export type ConcernMain = (argv?: string[]) => number | undefined | void;
+
+/** Keyed by the manifest's `script:` value (repo-relative path). */
+export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
+    'src/scripts/chat_history.ts': chatHistoryMain as ConcernMain,
+    'src/scripts/hot_context_hook.ts': hotContextMain as ConcernMain,
+    'src/scripts/roadmap_progress_hook.ts': roadmapProgressMain as ConcernMain,
+    'src/scripts/onboarding_gate_hook.ts': onboardingGateMain as ConcernMain,
+    'src/scripts/context_hygiene_hook.ts': contextHygieneMain as ConcernMain,
+    'src/scripts/verify_before_complete_hook.ts': verifyBeforeCompleteMain as ConcernMain,
+    'src/scripts/minimal_safe_diff_hook.ts': minimalSafeDiffMain as ConcernMain,
+    'src/scripts/injection_scan_hook.ts': injectionScanMain as ConcernMain,
+    'src/scripts/memory_learn_hook.ts': memoryLearnMain as ConcernMain,
+    'src/scripts/first_run_gate_hook.ts': firstRunGateMain as ConcernMain,
+    'src/scripts/profile_staleness_hook.ts': profileStalenessMain as ConcernMain,
+    'src/scripts/wrapper_freshness_hook.ts': wrapperFreshnessMain as ConcernMain,
+    'src/scripts/surface_probe_hook.ts': surfaceProbeMain as ConcernMain,
+    'src/scripts/team_review_gate_hook.ts': teamReviewGateMain as ConcernMain,
+    'src/scripts/pr_url_reminder_hook.ts': prUrlReminderMain as ConcernMain,
+    'src/scripts/session_canary_hook.ts': sessionCanaryMain as ConcernMain,
+    'src/scripts/hooks/block_no_verify.ts': blockNoVerifyMain as ConcernMain,
+    'src/scripts/hooks/block_kernel_rule_writes.ts': blockKernelRuleWritesMain as ConcernMain,
+    'src/scripts/hooks/rtk_wrap_hook.ts': rtkWrapMain as ConcernMain,
+    'src/scripts/hooks/design_slop_hook.ts': designSlopMain as ConcernMain,
+    'src/scripts/hooks/code_graph_nudge_hook.ts': codeGraphNudgeMain as ConcernMain,
+};

package/src/scripts/hooks/design_slop_hook.ts

@@ -24,6 +24,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { type DesignContext } from "../design_slop_rules.js";
 import { loadDesignContext, scanFile } from "../lint_design_slop.js";
+import { readHookStdin } from "./hook_stdin.js";
 
 const SETTINGS_FILE = ".agent-settings.yml";
 const EXIT_ALLOW = 0;
@@ -109,11 +110,7 @@ function writeState(root: string, state: Record<string, number>): void {
 }
 
 function readStdin(): string {
-  try {
-    return fs.readFileSync(0, "utf-8");
-  } catch {
-    return "";
-  }
+  return readHookStdin();
 }
 
 export function main(): number {
@@ -175,7 +172,13 @@ export function main(): number {
   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;
     }

package/src/scripts/hooks/dispatch_entry.ts

@@ -0,0 +1,37 @@
+/**
+ * dispatch_entry — bundle entry point for the precompiled hook dispatcher.
+ *
+ * road-to-credible-install Phase 1: `npm run build:hooks` bundles this file
+ * (dispatcher + concern registry + every concern module) into
+ * `dist/hooks/dispatch.js` so a hook event costs ONE node start — no tsx,
+ * no per-concern re-spawn. Invoked either
+ *   - directly: `node dist/hooks/dispatch.js --platform … --event …`, or
+ *   - in-process from the CLI's native `dispatch:hook` route (dynamic
+ *     import; the CLI process itself then runs the whole dispatch).
+ */
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { main } from './dispatch_hook.js';
+
+/**
+ * Direct-invocation detection. Under the esbuild bundle, EVERY inlined
+ * module's `import.meta.url` is the bundle file — so a plain
+ * argv[1]-vs-self comparison would make the CLI-entry guards of ALL
+ * inlined modules (lint scripts, sidecars, …) false-fire at import time
+ * and hijack the dispatch argv. The build banner therefore detects
+ * `node dist/hooks/dispatch.js` BEFORE any module code runs, sets the
+ * global marker, and rewrites argv[1] to a sentinel so no inlined guard
+ * can match. Only this entry consults the marker. The plain comparison
+ * below covers the unbundled path (`tsx src/scripts/hooks/dispatch_entry.ts`).
+ */
+const _selfPath = fileURLToPath(import.meta.url);
+const _invokedDirectly =
+    (globalThis as { __AC_HOOKS_BUNDLE_DIRECT?: boolean }).__AC_HOOKS_BUNDLE_DIRECT === true ||
+    (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath));
+
+if (_invokedDirectly) {
+    process.exitCode = main(process.argv.slice(2));
+}
+
+export { main };

package/src/scripts/hooks/dispatch_hook.ts

@@ -42,6 +42,11 @@ import {
   is_replay_mode,
 } from "./state_io.js";
 import { log_dispatch_issue, fix_hint } from "./dispatch_issues.js";
+import { CONCERN_REGISTRY, type ConcernMain } from "./concern_registry.js";
+import {
+  setHookStdinOverride,
+  clearHookStdinOverride,
+} from "./hook_stdin.js";
 
 // Free-form JSON values flow through every helper here; a documented
 // alias keeps the surface honest without `any` (ADR-200 § strict TS).
@@ -55,11 +60,14 @@ export type JsonValue =
 export type JsonObject = { [key: string]: JsonValue };
 
 // src/scripts/hooks/dispatch_hook.ts → parents[3] is the repo root.
+// Bundled (dist/hooks/dispatch.js) the module sits two levels below the repo
+// root; under tsx (src/scripts/hooks/) it sits three. The `__AGENT_CONFIG_BUNDLE__`
+// sentinel (esbuild --define) picks the right depth (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _IN_BUNDLE = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
 const REPO_ROOT = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "..",
-  "..",
+  ...(_IN_BUNDLE ? ["..", ".."] : ["..", "..", ".."]),
 );
 const MANIFEST_PATH = path.join(REPO_ROOT, "src", "scripts", "hook_manifest.yaml");
 
@@ -471,7 +479,115 @@ function _resolve_tsx_invocation(
  * through `tsx` (resolved from the package's `node_modules/.bin`, falling
  * back to `npx tsx`), mirroring how `run.ts` runs its `.ts` twins.
  */
+/**
+ * Single-process dispatch (road-to-credible-install Phase 1): run a concern
+ * IN-PROCESS via the static registry instead of re-spawning a per-concern
+ * interpreter. Mirrors the child-process contract exactly — stdin via the
+ * hook_stdin override, argv swap, cwd = workspace, hardened env, captured
+ * stdout/stderr, crash → rc 3 (the caller applies the fail-open /
+ * fail-closed reduction unchanged).
+ *
+ * Escape hatch: AGENT_CONFIG_HOOKS_ISOLATED=1 forces the historical
+ * spawn-per-concern path (also used by the bench harness for A/B numbers).
+ *
+ * Known trade-off vs the spawn path: the 30 s kill-timeout cannot preempt
+ * in-process synchronous code. Concerns are repo-owned, budget-capped and
+ * fail-open; the latency budget gate (hook-latency-budget.json) is the
+ * standing regression net.
+ */
+function _run_concern_inproc(
+  main_fn: ConcernMain,
+  concern: ConcernDef,
+  envelope: JsonObject,
+): RunResult {
+  const scriptAbs = path.join(REPO_ROOT, String(concern["script"]));
+  const argsList = Array.isArray(concern["args"])
+    ? concern["args"].map((a) => String(a))
+    : [];
+  argsList.push("--platform", String(envelope["platform"] || "generic"));
+  const workspace = String(envelope["workspace_root"] || process.cwd());
+
+  let out = "";
+  let err = "";
+  type WriteFn = typeof process.stdout.write;
+  const makeCapture =
+    (sink: (s: string) => void): WriteFn =>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ((chunk: any, enc?: any, cb?: any): boolean => {
+      sink(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8"));
+      const callback = typeof enc === "function" ? enc : cb;
+      if (typeof callback === "function") callback();
+      return true;
+    }) as WriteFn;
+
+  const prevStdoutWrite = process.stdout.write;
+  const prevStderrWrite = process.stderr.write;
+  const prevArgv = process.argv;
+  const prevCwd = process.cwd();
+  const prevEnv = { ...process.env };
+
+  const started = performance.now();
+  let rc = 0;
+  setHookStdinOverride(_compactJsonDumps(envelope));
+  process.stdout.write = makeCapture((s) => {
+    out += s;
+  });
+  process.stderr.write = makeCapture((s) => {
+    err += s;
+  });
+  try {
+    process.argv = [prevArgv[0] as string, scriptAbs, ...argsList];
+    // Same env-hardening the spawn path applied — concerns may spawn their
+    // own children (dashboard regen, git), which inherit process.env.
+    const hardened = hardenedSpawnEnv({ AGENT_CONFIG_PACKAGE_ROOT: REPO_ROOT });
+    for (const k of Object.keys(process.env)) {
+      if (!(k in hardened)) delete process.env[k];
+    }
+    Object.assign(process.env, hardened);
+    if (workspace !== prevCwd && _isDir(workspace)) {
+      process.chdir(workspace);
+    }
+    const result = main_fn(argsList);
+    rc = typeof result === "number" ? result : 0;
+  } catch (exc) {
+    rc = 3;
+    const msg = exc instanceof Error ? (exc.stack ?? exc.message) : String(exc);
+    err += `${String(concern["name"])}: ${msg}\n`;
+    log_dispatch_issue(
+      workspace,
+      String(concern["name"] || "unknown"),
+      "execution_failed",
+      `in-process concern crashed: ${exc instanceof Error ? exc.message : String(exc)}`,
+      fix_hint(),
+    );
+  } finally {
+    process.stdout.write = prevStdoutWrite;
+    process.stderr.write = prevStderrWrite;
+    process.argv = prevArgv;
+    for (const k of Object.keys(process.env)) {
+      if (!(k in prevEnv)) delete process.env[k];
+    }
+    Object.assign(process.env, prevEnv);
+    try {
+      if (process.cwd() !== prevCwd) process.chdir(prevCwd);
+    } catch {
+      /* original cwd vanished — keep going, fail-open */
+    }
+    clearHookStdinOverride();
+  }
+  const elapsed = Math.floor(performance.now() - started);
+  return { rc, stderr: err, stdout: out, duration_ms: elapsed };
+}
+
 function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
+  // In-process fast path — the default whenever the concern is in the
+  // static registry (all manifest concerns; parity is CI-enforced).
+  if (process.env["AGENT_CONFIG_HOOKS_ISOLATED"] !== "1") {
+    const inproc = CONCERN_REGISTRY[String(concern["script"])];
+    if (inproc !== undefined) {
+      return _run_concern_inproc(inproc, concern, envelope);
+    }
+  }
   const script = path.join(REPO_ROOT, String(concern["script"]));
   const argsList = Array.isArray(concern["args"])
     ? concern["args"].map((a) => String(a))
@@ -654,6 +770,57 @@ function _write_feedback(
   }
 }
 
+/**
+ * Checkable-rule trip counting (road-to-credible-install Phase 6, scoped P3
+ * cut): every concern that returns BLOCK (1) or WARN (2) — a violation the
+ * gate actually caught — increments a per-concern counter in
+ * `agents/runtime/state/rule-trips.json`. Extends the existing dispatcher
+ * feedback machinery only; the evaluator/umbrella surfaces read this file.
+ *
+ * PII-exclusion-by-construction: the schema carries ONLY concern ids,
+ * integer counters, and ISO dates — no field capable of holding free-form
+ * content, prompt text, or file bodies. Never widen it.
+ *
+ * Fail-open (a broken counter must never affect dispatch), skipped in
+ * replay mode like the feedback dir.
+ */
+function _record_rule_trips(envelope: JsonObject, entries: FeedbackEntry[]): void {
+  if (is_replay_mode()) return;
+  const tripped = entries.filter(
+    (e) => e["exit_code"] === EXIT_BLOCK || e["exit_code"] === EXIT_WARN,
+  );
+  if (tripped.length === 0) return;
+  try {
+    const workspace = String(envelope["workspace_root"] || process.cwd());
+    const state_dir = path.join(workspace, "agents", "runtime", "state");
+    const target = path.join(state_dir, "rule-trips.json");
+    fs.mkdirSync(state_dir, { recursive: true });
+    let doc: JsonObject = { schema_version: 1, concerns: {} };
+    try {
+      const parsed = JSON.parse(fs.readFileSync(target, "utf-8")) as JsonObject;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) doc = parsed;
+    } catch {
+      /* absent or corrupt → fresh counter file */
+    }
+    const concerns = (doc["concerns"] ?? {}) as Record<string, JsonObject>;
+    const today = _now_iso().slice(0, 10);
+    for (const e of tripped) {
+      const name = String(e["concern"]);
+      const prev = (concerns[name] ?? { block: 0, warn: 0 }) as JsonObject;
+      concerns[name] = {
+        block: (Number(prev["block"]) || 0) + (e["exit_code"] === EXIT_BLOCK ? 1 : 0),
+        warn: (Number(prev["warn"]) || 0) + (e["exit_code"] === EXIT_WARN ? 1 : 0),
+        last_trip: today,
+      };
+    }
+    doc["schema_version"] = 1;
+    doc["concerns"] = concerns;
+    atomic_write_json(target, doc);
+  } catch {
+    /* fail-open — counters are observability, never dispatch-critical */
+  }
+}
+
 function _parse_args(argv: string[]): Args {
   const args: Args = {
     platform: "",
@@ -850,6 +1017,7 @@ export function main(argv?: string[]): number {
   }
   const final_rc = _reduce(rcs);
   _write_feedback(envelope, session_id, feedback_entries, final_rc, started_at);
+  _record_rule_trips(envelope, feedback_entries);
   if (context_blocks.length > 0 && final_rc === EXIT_ALLOW) {
     process.stdout.write(context_blocks.join("\n\n") + "\n");
   }
@@ -877,7 +1045,12 @@ function _readStdin(): string {
   }
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (declare at top of file).
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }

package/src/scripts/hooks/hook_stdin.ts

@@ -0,0 +1,42 @@
+/**
+ * hook_stdin — the single stdin seam for hook concern scripts.
+ *
+ * road-to-credible-install Phase 1 (single-process dispatch): concern
+ * scripts historically read their JSON envelope with `fs.readFileSync(0)`.
+ * That only works when each concern is its own child process. Under the
+ * in-process dispatcher (dist/hooks bundle) all concerns run inside ONE
+ * node process whose fd 0 carries the PLATFORM payload, already consumed
+ * by the dispatcher — so the dispatcher injects the per-concern envelope
+ * here instead.
+ *
+ * Contract:
+ *   - Standalone invocation (a concern run directly as its own process —
+ *     the historical path, still supported): no override is set, and
+ *     `readHookStdin()` falls through to `fs.readFileSync(0, 'utf-8')`.
+ *   - In-process invocation: the dispatcher calls
+ *     `setHookStdinOverride(raw)` before the concern's `main()` and
+ *     `clearHookStdinOverride()` after. Nesting is not supported (concerns
+ *     never dispatch concerns).
+ */
+import * as fs from 'node:fs';
+
+let _override: string | null = null;
+
+export function setHookStdinOverride(raw: string): void {
+    _override = raw;
+}
+
+export function clearHookStdinOverride(): void {
+    _override = null;
+}
+
+/** TTY-safe stdin read: injected override first, else fd 0, else "". */
+export function readHookStdin(): string {
+    if (_override !== null) return _override;
+    try {
+        if (process.stdin.isTTY) return '';
+        return fs.readFileSync(0, 'utf-8');
+    } catch {
+        return '';
+    }
+}