@event4u/agent-config 9.14.0 → 9.16.0

package/src/scripts/generate_router_coverage_from_matrix.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env tsx
+/**
+ * Derive the routing-matrix router-coverage corpus (road-to-tested-routing
+ * Phase 2, PREREG P2 corpus expansion).
+ *
+ * Reads every per-rule routing matrix under `tests/eval/routing-matrix/`
+ * and emits ONE generated corpus file,
+ * `internal/bench/corpora/router-coverage/routing-matrix-derived.yaml`,
+ * with one `router-coverage` prompt per matrix POSITIVE, labelled
+ * `intended_triggers: [<rule>]`. Near-misses are deliberately NOT emitted —
+ * the corpus measures intended activation; the matrices' negative half is
+ * enforced by `tests/scripts/routing_matrix.test.ts`.
+ *
+ * Ownership (two-gate pattern): this generator is the only writer;
+ * `--check` re-derives in memory and exits 1 on drift, so the derived file
+ * can never be hand-edited into disagreement with its source matrices.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parse as parseYaml } from "yaml";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+const MATRIX_DIR = path.join(REPO_ROOT, "tests", "eval", "routing-matrix");
+export const OUT_FILE = path.join(
+  REPO_ROOT,
+  "internal",
+  "bench",
+  "corpora",
+  "router-coverage",
+  "routing-matrix-derived.yaml",
+);
+
+interface MatrixCase {
+  prompt: string;
+  open_files?: string[];
+  command?: string;
+}
+interface MatrixFile {
+  rule: string;
+  positives: MatrixCase[];
+  near_misses: MatrixCase[];
+}
+
+/** Cheap language tag for the corpus `language:` field. */
+export function detect_language(prompt: string): "de" | "en" {
+  if (/[äöüßÄÖÜ]/.test(prompt)) {
+    return "de";
+  }
+  return /(^|\s)(der|die|das|und|nicht|bitte|keine?|mach|prüfe|erstelle|für)(\s|$)/i.test(prompt)
+    ? "de"
+    : "en";
+}
+
+function yamlQuote(s: string): string {
+  return JSON.stringify(s);
+}
+
+export function derive(): string {
+  const files = fs
+    .readdirSync(MATRIX_DIR)
+    .filter((f) => f.endsWith(".yaml"))
+    .sort();
+  const lines: string[] = [];
+  lines.push("# Router-coverage corpus — DERIVED FROM the per-rule routing matrices.");
+  lines.push("#");
+  lines.push("# GENERATED FILE — do not hand-edit. Source of truth:");
+  lines.push("#   tests/eval/routing-matrix/*.yaml");
+  lines.push("# Regenerate: npx tsx src/scripts/generate_router_coverage_from_matrix.ts");
+  lines.push("# Drift gate:  npx tsx src/scripts/generate_router_coverage_from_matrix.ts --check");
+  lines.push("");
+  lines.push("version: 1");
+  lines.push("corpus_id: router-coverage-routing-matrix-derived");
+  lines.push("selection_accuracy_target: 0.0");
+  lines.push("");
+  lines.push("prompts:");
+  for (const f of files) {
+    const parsed = parseYaml(fs.readFileSync(path.join(MATRIX_DIR, f), "utf-8")) as MatrixFile;
+    parsed.positives.forEach((c, i) => {
+      const id = `rm-${parsed.rule}-${String(i + 1).padStart(2, "0")}`;
+      lines.push(`  - id: ${id}`);
+      lines.push("    category: router-coverage");
+      lines.push(`    language: ${detect_language(c.prompt)}`);
+      lines.push(`    prompt: ${yamlQuote(c.prompt)}`);
+      lines.push("    expected_skills: []");
+      lines.push(`    intended_triggers: [${parsed.rule}]`);
+      if (c.open_files && c.open_files.length > 0) {
+        lines.push(`    open_files: [${c.open_files.map(yamlQuote).join(", ")}]`);
+      }
+      lines.push("");
+    });
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export function main(argv?: string[]): number {
+  const args = argv ?? process.argv.slice(2);
+  const check = args.includes("--check");
+  const derived = derive();
+  if (check) {
+    let current = "";
+    try {
+      current = fs.readFileSync(OUT_FILE, "utf-8");
+    } catch {
+      process.stderr.write(`missing derived corpus: ${OUT_FILE} — run the generator\n`);
+      return 1;
+    }
+    if (current !== derived) {
+      process.stderr.write(
+        "routing-matrix-derived.yaml is stale — regenerate via generate_router_coverage_from_matrix\n",
+      );
+      return 1;
+    }
+    process.stdout.write("routing-matrix-derived corpus: fresh\n");
+    return 0;
+  }
+  fs.writeFileSync(OUT_FILE, derived, "utf-8");
+  const promptCount = (derived.match(/^ {2}- id: /gm) ?? []).length;
+  const ruleCount = new Set(
+    [...derived.matchAll(/intended_triggers: \[([^\]]+)\]/g)].map((m) => m[1]),
+  ).size;
+  process.stdout.write(
+    `wrote ${path.relative(REPO_ROOT, OUT_FILE)} — ${promptCount} prompts, ${ruleCount} distinct rule ids\n`,
+  );
+  return 0;
+}
+
+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 {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv1;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}

package/src/scripts/hook_manifest.yaml

@@ -91,6 +91,20 @@ concerns:
     script: src/scripts/hooks/block_kernel_rule_writes.ts
     args: []
     fail_closed: true
+  # road-to-renewal-leverage Phase 2 — "fix the code, not the config".
+  # PreToolUse guard over the recorded allowlist-growth antipattern
+  # (autonomous-execution § Antipattern): warns as an allowlist grows within a
+  # session and BLOCKS past the cap that rule already states in words (>20
+  # entries in one session = the linter is wrong). Baselines and budget
+  # thresholds warn only — whether a rising count is weakening or a legitimate
+  # ratchet reset is not decidable from the edit alone. Council 2026-08-02
+  # rejected inventing a "fix-loop is active" predicate; the SESSION is the
+  # window the recorded rule already names. fail_closed: false — a malformed
+  # envelope must never block an unrelated edit.
+  block-config-weakening:
+    script: src/scripts/hooks/block_config_weakening.ts
+    args: []
+    fail_closed: false
   # token-saving Phase 3 — PreToolUse RTK-wrap nudge. DETERMINISTIC: keys off a
   # live `which rtk` probe (not the self-reported flag). When rtk is installed
   # and the agent is about to run a single verbose CLI command that is NOT
@@ -211,7 +225,7 @@ platforms:
     session_start:    [chat-history, hot-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history, memory-learn]
     stop:             [chat-history, hot-context, verify-before-complete]
-    pre_tool_use:     [block-no-verify, block-kernel-rule-writes, rtk-wrap, design-slop, code-graph-nudge]
+    pre_tool_use:     [block-no-verify, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, code-graph-nudge]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   claude:
@@ -219,7 +233,7 @@ platforms:
     session_end:      [chat-history, memory-learn]
     stop:             [chat-history, hot-context, verify-before-complete, team-review-gate]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
-    pre_tool_use:     [block-no-verify, block-kernel-rule-writes, rtk-wrap, design-slop, code-graph-nudge]
+    pre_tool_use:     [block-no-verify, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, code-graph-nudge]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   # Cowork — the Claude desktop app's local-agent-mode runtime, built
@@ -241,7 +255,7 @@ platforms:
     session_end:      [chat-history, memory-learn]
     stop:             [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
-    pre_tool_use:     [block-no-verify, block-kernel-rule-writes, rtk-wrap, design-slop, code-graph-nudge]
+    pre_tool_use:     [block-no-verify, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, code-graph-nudge]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
 
   # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the

package/src/scripts/hooks/block_config_weakening.ts

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+// MIGRATE: precompiled-hook-layer — carry this hook when road-to-credible-install
+// Phase 1 precompiles the hook path (touch-once preserved at migration).
+/**
+ * PreToolUse guard: "fix the code, not the config."
+ *
+ * The recorded antipattern (`autonomous-execution` § Antipattern —
+ * allowlist-growth as silent budget bypass): during a fix loop the agent
+ * weakens the gate instead of the code, growing a lint allowlist entry by
+ * entry until the linter no longer objects. The rule already states the
+ * threshold in words —
+ *
+ *     ALLOWLIST > 20 ENTRIES IN ONE SESSION = THE LINTER IS WRONG.
+ *     STOP. PROPOSE LINTER REDESIGN OR REMOVAL.
+ *
+ * — and two linters cite it in their own failure messages. Nothing enforced
+ * it: by the time CI sees the diff the session has already spent its budget
+ * on the wrong fix. This hook moves that stated threshold to tool-call time.
+ *
+ * Deliberately NOT built (council 2026-08-02, anthropic/claude-sonnet-4-5 +
+ * openai/gpt-4o):
+ *
+ * - **No invented "fix-loop is active" predicate.** Both members rejected it
+ *   as speculative — no such state exists in the repo and defining entry/exit
+ *   invites false positives in both directions. The SESSION is the window the
+ *   recorded rule already names, so the session id off the hook envelope is
+ *   the predicate, and it is not an invention.
+ * - **No blocking on baselines or budgets.** Whether a violation-baseline
+ *   count rising is weakening or a legitimate ratchet reset after a refactor
+ *   is not mechanically decidable from the edit alone. Those surfaces warn
+ *   (exit 2) and stay a review decision; only allowlist growth — mechanical,
+ *   countable, and already carrying a stated numeric threshold — blocks.
+ *
+ * Cumulative within a session, per allowlist file. Small additions warn from
+ * the first one so the count is visible while it is still cheap to change
+ * course; crossing the recorded cap blocks.
+ *
+ * Exit codes (docs/contracts/hook-architecture-v1.md):
+ *   0 — allow
+ *   1 — block
+ *   2 — warn
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { EDIT_TOOLS } from '../minimal_safe_diff_hook.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const EXIT_ALLOW = 0;
+const EXIT_BLOCK = 1;
+const EXIT_WARN = 2;
+
+/**
+ * The stated cap from `autonomous-execution` § Antipattern. Crossing it in one
+ * session is defined there as the third validation-target failure — the point
+ * at which the linter, not the content, is wrong.
+ */
+export const SESSION_ENTRY_CAP = 20;
+
+/** Warn from this many cumulative added entries so the count stays visible. */
+export const SESSION_WARN_AT = 5;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: JsonValue | undefined): v is JsonObject {
+    return v !== null && v !== undefined && typeof v === 'object' && !Array.isArray(v);
+}
+
+const _PATH_KEYS: readonly string[] = ['file_path', 'path', 'target_file', 'filePath', 'notebook_path'];
+
+/**
+ * Config surfaces this guard recognises.
+ *
+ * `allowlist` is the blocking class — an entry count is a plain number and the
+ * recorded rule already fixes its threshold. `advisory` covers the surfaces
+ * where "weakening" needs context a tool call does not carry (a baseline count
+ * may legitimately reset after a refactor); those warn and never block.
+ */
+export type ConfigKind = 'allowlist' | 'advisory' | null;
+
+/** Classify a target path into a config surface, or null for everything else. */
+export function classify_target(p: string): ConfigKind {
+    const posix = p.split(path.sep).join('/');
+    const base = posix.split('/').pop() ?? '';
+    if (/_allowlist\.(json|txt)$/.test(base) || /^allowlist[-_.]/.test(base)) {
+        return 'allowlist';
+    }
+    if (/(^|-)baselines?\.json$/.test(base)) {
+        return 'advisory';
+    }
+    if (/-budget(s)?\.(json|ya?ml)$/.test(base) || base === 'budgets.yml') {
+        return 'advisory';
+    }
+    return null;
+}
+
+/**
+ * Count allowlist entries in a blob.
+ *
+ * JSON: every string leaf in the structure (arrays of paths, and
+ * `{"rule": ["path", …]}` maps alike) — parsing beats a line count because a
+ * reformat would otherwise read as growth. Falls back to non-blank,
+ * non-comment lines for `.txt` allowlists and for JSON fragments that do not
+ * parse on their own (an `Edit` payload is rarely a whole document).
+ */
+export function count_entries(text: string): number {
+    const trimmed = text.trim();
+    if (trimmed) {
+        try {
+            let n = 0;
+            const walk = (v: unknown): void => {
+                if (typeof v === 'string') {
+                    n += 1;
+                } else if (Array.isArray(v)) {
+                    v.forEach(walk);
+                } else if (v !== null && typeof v === 'object') {
+                    Object.values(v as Record<string, unknown>).forEach(walk);
+                }
+            };
+            walk(JSON.parse(trimmed));
+            return n;
+        } catch {
+            /* not a standalone JSON document — fall through */
+        }
+    }
+    return text
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith('#') && !l.startsWith('//')).length;
+}
+
+/**
+ * Entries this single tool call adds to an allowlist.
+ *
+ * `Write` carries the whole new document, so the delta is measured against
+ * what is on disk. `Edit` carries a replacement pair, so the delta is the pair
+ * itself. Negative results (a shrinking allowlist — the direction this guard
+ * wants) collapse to 0: removals must never bank credit against a later
+ * addition.
+ */
+export function added_entries(
+    tool_input: JsonObject,
+    on_disk: string | null,
+): number {
+    const content = tool_input['content'];
+    if (typeof content === 'string') {
+        const before = on_disk === null ? 0 : count_entries(on_disk);
+        return Math.max(0, count_entries(content) - before);
+    }
+    const oldS = tool_input['old_string'] ?? tool_input['oldStr'] ?? tool_input['old_str'];
+    const newS = tool_input['new_string'] ?? tool_input['newStr'] ?? tool_input['new_str'];
+    if (typeof newS === 'string') {
+        const before = typeof oldS === 'string' ? count_entries(oldS) : 0;
+        return Math.max(0, count_entries(newS) - before);
+    }
+    return 0;
+}
+
+export interface Decision {
+    action: 'allow' | 'warn' | 'block';
+    reason: string;
+}
+
+/** Decide from the cumulative session total for one allowlist file. */
+export function decide(kind: ConfigKind, rel_path: string, session_total: number, added: number): Decision {
+    if (kind === null || added <= 0) {
+        return { action: 'allow', reason: '' };
+    }
+    if (kind === 'advisory') {
+        return {
+            action: 'warn',
+            reason:
+                `${rel_path}: this edit loosens a gate threshold. Whether that is a ` +
+                'legitimate ratchet reset or the config being bent around a failing ' +
+                'check is a review decision — state which in the diff.',
+        };
+    }
+    if (session_total > SESSION_ENTRY_CAP) {
+        return {
+            action: 'block',
+            reason:
+                `${rel_path}: ${session_total} allowlist entries added this session ` +
+                `(cap ${SESSION_ENTRY_CAP}). Per autonomous-execution § Antipattern — ` +
+                'allowlist-growth as silent budget bypass, crossing this cap means the ' +
+                'LINTER is wrong, not the content. Fix the code or redesign the check; ' +
+                'do not expand the allowlist further.\n' +
+                '  Legitimate override is a human action outside this session: land the ' +
+                'linter redesign, or remove the `block-config-weakening` entry in ' +
+                'src/scripts/hook_manifest.yaml.',
+        };
+    }
+    if (session_total >= SESSION_WARN_AT) {
+        return {
+            action: 'warn',
+            reason:
+                `${rel_path}: ${session_total} allowlist entries added this session ` +
+                `(cap ${SESSION_ENTRY_CAP}). Fix the code, not the config.`,
+        };
+    }
+    return { action: 'allow', reason: '' };
+}
+
+// --- session state -------------------------------------------------------
+
+function _state_file(root: string): string {
+    return path.join(root, 'agents', 'runtime', 'state', 'config-weakening.json');
+}
+
+/** Read the cumulative count, add `added`, persist, and return the new total. */
+export function bump_session(root: string, session: string, key: string, added: number): number {
+    const f = _state_file(root);
+    let data: Record<string, Record<string, number>> = {};
+    try {
+        data = JSON.parse(fs.readFileSync(f, 'utf-8')) as Record<string, Record<string, number>>;
+    } catch {
+        data = {};
+    }
+    const bucket = data[session] ?? {};
+    const total = (bucket[key] ?? 0) + added;
+    bucket[key] = total;
+    data[session] = bucket;
+    try {
+        fs.mkdirSync(path.dirname(f), { recursive: true });
+        fs.writeFileSync(f, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+    } catch {
+        /* state is an optimisation, never a gate — a read-only tree still decides */
+    }
+    return total;
+}
+
+// --- entry ---------------------------------------------------------------
+
+function _extract(envelope: JsonObject): { tool: string; paths: string[]; ti: JsonObject | null } {
+    const payload = _isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const nameVal =
+        payload['tool_name'] ?? payload['toolName'] ?? payload['tool'] ?? envelope['tool_name'] ?? envelope['tool'];
+    const tool = typeof nameVal === 'string' ? nameVal : '';
+    const ti = _isObject(payload['tool_input'])
+        ? payload['tool_input']
+        : _isObject(envelope['tool_input'])
+          ? envelope['tool_input']
+          : null;
+    const paths: string[] = [];
+    if (ti !== null) {
+        for (const key of _PATH_KEYS) {
+            const v = ti[key];
+            if (typeof v === 'string' && v) {
+                paths.push(v);
+            }
+        }
+    }
+    return { tool, paths, ti };
+}
+
+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 { tool, paths, ti } = _extract(envelope);
+    if (!tool || !EDIT_TOOLS.has(tool) || ti === null) {
+        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 sidRaw = envelope['session_id'] ?? envelope['sessionId'];
+    const session = typeof sidRaw === 'string' && sidRaw ? sidRaw : 'default';
+
+    for (const p of paths) {
+        const kind = classify_target(p);
+        if (kind === null) {
+            continue;
+        }
+        const abs = path.isAbsolute(p) ? p : path.join(root, p);
+        let on_disk: string | null = null;
+        try {
+            on_disk = fs.readFileSync(abs, 'utf-8');
+        } catch {
+            on_disk = null;
+        }
+        const added = added_entries(ti, on_disk);
+        if (added <= 0) {
+            continue;
+        }
+        const rel = path.relative(root, abs) || p;
+        const total = kind === 'allowlist' ? bump_session(root, session, rel, added) : added;
+        const d = decide(kind, rel, total, added);
+        if (d.action === 'block') {
+            process.stderr.write(`block-config-weakening: BLOCKED — ${d.reason}\n`);
+            return EXIT_BLOCK;
+        }
+        if (d.action === 'warn') {
+            process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: d.reason })}\n`);
+            return EXIT_WARN;
+        }
+    }
+    return EXIT_ALLOW;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+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.argv[1] === _HERE) {
+    process.exit(main());
+}

package/src/scripts/hooks/concern_registry.ts

@@ -42,6 +42,7 @@ 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 blockConfigWeakeningMain } from './block_config_weakening.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';
@@ -69,6 +70,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, 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/block_config_weakening.ts': blockConfigWeakeningMain 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/probe_throttle.ts

@@ -0,0 +1,75 @@
+/**
+ * probe_throttle — daily throttle for session_start probe concerns
+ * (road-to-hook-latency-repair Phase 2, SessionStart fan-out lever).
+ *
+ * `profile-staleness`, `wrapper-freshness`, and `surface-probe` are
+ * defense-in-depth probes whose findings do not change within a day; running
+ * them on EVERY session_start pays their cost per session for no new
+ * information. Each probe checks a per-concern stamp file under
+ * `agents/runtime/state/probe-throttle/` and skips when the stamp's mtime is
+ * from the same LOCAL calendar day (a skipped probe re-runs tomorrow).
+ *
+ * Deliberate simplicity (roadmap lock — "an mtime file, not a daemon"):
+ *   - The stamp carries NO semantics beyond its mtime. Deleting the file or
+ *     the directory only changes WHEN a probe re-runs, never what it answers.
+ *   - Same-day equality is skew-safe: a stamp dated in the future or the past
+ *     is simply "not today", so the probe runs and re-stamps — there is no
+ *     lockout state (council 2026-08-03).
+ *   - Fail-open both ways: an unreadable stamp means "run the probe"; an
+ *     unwritable state dir means the probe simply runs again next session.
+ *   - Replay runs (AGENT_CONFIG_REPLAY=1) bypass the throttle and never
+ *     write stamps — fixture re-execution and the latency bench must be
+ *     deterministic, not dependent on yesterday's stamps (state_io replay
+ *     contract).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { is_replay_mode } from './state_io.js';
+
+const STATE_SUBDIR = ['agents', 'runtime', 'state', 'probe-throttle'] as const;
+
+function _stampPath(projectRoot: string, concern: string): string {
+    return path.join(projectRoot, ...STATE_SUBDIR, `${concern}.stamp`);
+}
+
+/** Local-calendar-day key (YYYY-MM-DD in local time, not UTC). */
+function _localDay(d: Date): string {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+
+/**
+ * True when the probe already ran today (same LOCAL calendar day as the
+ * stamp's mtime) and may be skipped. Replay mode and any read problem
+ * return false — the probe runs.
+ */
+export function probeRanToday(projectRoot: string, concern: string): boolean {
+    if (is_replay_mode()) return false;
+    try {
+        const st = fs.statSync(_stampPath(projectRoot, concern));
+        return _localDay(st.mtime) === _localDay(new Date());
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Record that the probe ran now. Fail-silent — an unwritable state dir just
+ * means the probe runs again next session. No-op in replay mode.
+ */
+export function stampProbeRun(projectRoot: string, concern: string): void {
+    if (is_replay_mode()) return;
+    try {
+        const p = _stampPath(projectRoot, concern);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        // Content is a human-readable timestamp for debugging only — the
+        // mtime is the sole semantic carrier.
+        fs.writeFileSync(p, `${new Date().toISOString()}\n`);
+    } catch {
+        /* fail-silent */
+    }
+}

package/src/scripts/install-hooks.sh

@@ -266,10 +266,20 @@ write_chat_history_hook "post-rewrite"  "git:post-rewrite"
 # `.augment/`, etc. projections until they remember to run `task sync`.
 # These hooks bridge that gap: fast idempotent re-projection.
 #
+# The same staleness bites the compiled CLI: the Claude/agent hooks run
+# `./agent-config` → `dist/cli/` (gitignored tsc output). A pull that adds
+# or moves a TS module leaves `dist/` stale and EVERY subsequent tool-use
+# hook fails with ERR_MODULE_NOT_FOUND until someone rebuilds. So when the
+# range touches TS sources, rebuild via `npm run build:cli` — tsc only,
+# deliberately NOT the full `npm run build`: the install-bundle step
+# rewrites the committed `dist/install/install.mjs` and has produced
+# spurious tracked diffs from worktrees before.
+#
 # Bypass: `git pull --no-verify` does not exist, but devs can disable the
 # hooks per-command via `git -c core.hooksPath=/dev/null ...` or by
 # editing the file. Runtime ~200 ms when nothing relevant changed
-# (path-diff check exits early); ~2 s on full re-projection.
+# (path-diff check exits early); ~2 s on full re-projection; ~2 s extra
+# for the tsc rebuild when TS sources changed.
 
 append_auto_sync_block() {
     local name="$1"
@@ -294,13 +304,25 @@ elif [ "$name" = "post-checkout" ]; then
 fi
 
 if [ -n "\$prev" ] && [ -n "\$new" ] && [ "\$prev" != "\$new" ]; then
-    if git diff --name-only "\$prev" "\$new" 2>/dev/null | \\
+    changed="\$(git diff --name-only "\$prev" "\$new" 2>/dev/null)"
+    if printf '%s\n' "\$changed" | \\
         grep -qE '^(dist/agent-src/|\\.agent-src\\.uncondensed/|src/scripts/condense\\.ts|\\.agent-tools\\.yml|Taskfile\\.yml)'; then
         if command -v task >/dev/null 2>&1; then
             task sync >/dev/null 2>&1 || true
             task generate-tools >/dev/null 2>&1 || true
         fi
     fi
+    # TS sources changed → the gitignored tsc output (dist/cli, dist/scripts,
+    # …) is stale and the ./agent-config hook chain breaks with
+    # ERR_MODULE_NOT_FOUND. Rebuild tsc output only (build:cli), never the
+    # full build (install-bundle rewrites committed dist/install/install.mjs).
+    # Skip silently without node_modules (fresh clone / bare worktree).
+    if printf '%s\n' "\$changed" | \\
+        grep -qE '^(src/(cli|server|shared|install|scripts)/|tsconfig\\.json|package\\.json)'; then
+        if command -v npm >/dev/null 2>&1 && [ -d node_modules ]; then
+            npm run build:cli >/dev/null 2>&1 || true
+        fi
+    fi
 fi
 EOF
 }