@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/hooks/block_config_weakening.ts

@@ -126,12 +126,13 @@ const _PATH_KEYS: readonly string[] = ['file_path', 'path', 'target_file', 'file
 export type ConfigKind = 'allowlist' | 'advisory' | 'class-c' | null;
 
 /**
- * Project settings files whose keys this guard fences. User-global files are
+ * Project settings files, and the committed git-convention carrier (ADR-283),
+ * whose keys this guard fences. User-global files are
  * never in reach — the hook only sees a path a tool call named, and the writes
  * that reach `~/.event4u/` go through `settings:set`, which applies its own
  * per-key refusal.
  */
-const CLASS_C_BASENAMES: readonly string[] = ['.agent-settings.yml', '.agent-settings.yaml', 'settings.json'];
+const CLASS_C_BASENAMES: readonly string[] = ['.agent-settings.yml', '.agent-settings.yaml', '.git-convention.yml', 'settings.json'];
 
 /** Where the class contract lives, relative to the package root. */
 export const SETTINGS_CLASSES_RELATIVE = 'docs/contracts/settings-classes.md';
@@ -382,10 +383,25 @@ export interface Decision {
  * unreadable for the length of one tool call, which is a bypass with no
  * authorisation step in it.
  *
+ * The edit forms it models: `Write` (`content`), `Edit` (`old_string` /
+ * `new_string`, with `replace_all`) and `MultiEdit` (an `edits` list of those
+ * pairs, applied in order).
+ *
  * WHAT IT CANNOT SEE: an edit applied through a shell redirect rather than an
  * edit tool — `EDIT_TOOLS` is the corpus, and the shell shapes are
  * `block_plumbing_writes`' subject, not this one.
  */
+/** The host writes `new_string` verbatim; `String.replace` would expand `$&`-style tokens. */
+function _replaceFirstLiteral(text: string, from: string, to: string): string {
+    const at = text.indexOf(from);
+    return text.slice(0, at) + to + text.slice(at + from.length);
+}
+
+/** An empty `old_string` is the host's create form, which `split('')` does not model. */
+function _applyEdit(text: string, from: string, to: string, all: unknown): string {
+    return all === true && from !== '' ? text.split(from).join(to) : _replaceFirstLiteral(text, from, to);
+}
+
 export function classCVerdict(
     ti: JsonObject,
     on_disk: string | null,
@@ -397,11 +413,22 @@ export function classCVerdict(
     const content = ti['content'];
     const oldStr = ti['old_string'];
     const newStr = ti['new_string'];
+    const forms = [content !== undefined, oldStr !== undefined || newStr !== undefined, ti['edits'] !== undefined];
+    if (forms.filter(Boolean).length > 1) {
+        return (
+            `${rel_path}: this edit carries more than one edit form (content, old_string/new_string, edits), ` +
+            'so the guard cannot tell which one the host will run and no key can be cleared. ' +
+            'Re-send it as one form, or write the change through `agent-config settings:set`.'
+        );
+    }
+    // A file that does not exist yet is created by an edit with an empty
+    // `old_string`, so it is modelled as empty text rather than left unchecked.
+    const current = on_disk ?? '';
     let afterText: string | null = null;
     if (typeof content === 'string') {
         afterText = content;
-    } else if (typeof oldStr === 'string' && typeof newStr === 'string' && on_disk !== null) {
-        if (!on_disk.includes(oldStr)) return null; // the edit will not apply
+    } else if (typeof oldStr === 'string' && typeof newStr === 'string') {
+        if (!current.includes(oldStr)) return null; // the edit will not apply
         // `replace_all` is the host's own flag and it changes WHICH text the
         // edit produces. Modelling only the first occurrence let a
         // `replace_all` edit whose SECOND occurrence is the Class C one pass
@@ -417,7 +444,23 @@ export function classCVerdict(
                 '`agent-config settings:set`.'
             );
         }
-        afterText = all === true ? on_disk.split(oldStr).join(newStr) : on_disk.replace(oldStr, newStr);
+        afterText = _applyEdit(current, oldStr, newStr, all);
+    } else if (ti['edits'] !== undefined && !Array.isArray(ti['edits'])) {
+        return `${rel_path}: this MultiEdit carries an edit the guard cannot interpret, so the text it would produce is unknown and no key can be cleared. Re-send it as plain edits, or write the change through \`agent-config settings:set\`.`;
+    } else if (Array.isArray(ti['edits'])) {
+        // MultiEdit applies its pairs in order and applies none when one misses.
+        let text = current;
+        for (const e of ti['edits']) {
+            const o = _isObject(e) ? e['old_string'] : undefined;
+            const n = _isObject(e) ? e['new_string'] : undefined;
+            const a = _isObject(e) ? e['replace_all'] : undefined;
+            if (typeof o !== 'string' || typeof n !== 'string' || (a !== undefined && typeof a !== 'boolean')) {
+                return `${rel_path}: this MultiEdit carries an edit the guard cannot interpret, so the text it would produce is unknown and no key can be cleared. Re-send it as plain edits, or write the change through \`agent-config settings:set\`.`;
+            }
+            if (!text.includes(o)) return null;
+            text = _applyEdit(text, o, n, a);
+        }
+        afterText = text;
     }
     if (afterText === null) return null;
 

package/src/scripts/hooks/block_plumbing_writes.ts

@@ -5,10 +5,14 @@
  * road-to-a-kernel-that-guards-its-plumbing 1.2 — the other half of a
  * deliberate split, and the split is the whole design:
  *
- *   · plumbing SOURCES (`hook_manifest.yaml`, `host_lowering.yaml`, the
- *     `*-dispatcher.sh` trampolines, both hook budget files) are edited
- *     legitimately all the time. They carry a RECORD — the ADR-268 § 4
- *     ratification gate, path set extended by step 1.1 — not a deny.
+ *   · plumbing SOURCES are edited legitimately all the time. They carry a
+ *     RECORD — the ADR-268 § 4 ratification gate — not a deny. Which files
+ *     count is NOT listed here: it is `check_kernel_edit_ratified`'s
+ *     `PLUMBING_SOURCE_RE` plus the verdict-deciding modules of the
+ *     dispatcher's import closure (`derivedPlumbing`), computed at run time.
+ *     A copy of that list here drifted once already — it named the pattern
+ *     and missed the policy module a refactor moved out of the dispatcher —
+ *     so this header points at the set instead of restating it.
  *   · plumbing BUILD OUTPUTS have no legitimate hand edit at all. They carry a
  *     DENY, which is this file.
  *

package/src/scripts/hooks/block_speaking_inbox_dir.ts

@@ -149,11 +149,26 @@ function isGlobOverAcceptableInboxDir(name: string): boolean {
     if (!/[*?[\]]/.test(name)) {
         return false;
     }
-    const literal = name.replace(/[*?]|\[[^\]]*\]/g, '');
+    // Only a generic class is stripped. Any other bracket payload stays in the
+    // literal and is judged: `[acme]` names a source, and so does a run of
+    // singleton ranges like `[a-a][c-c]`.
+    const literal = name.replace(/[*?]|\[(?:a-z|0-9|a-f|0-9a-f|a-z0-9)\]/gi, '');
+    if (OPAQUE_FAMILY_WILDCARD_RE.test(name)) {
+        return true;
+    }
     const trimmed = literal.replace(/-+$/, '');
     return trimmed !== '' && isAcceptableInboxDir(trimmed);
 }
 
+/**
+ * The fixed head of an opaque identifier family followed by wildcards only.
+ * `round-*` lists hex rounds; as a literal it would create `round-*`, which
+ * carries no source. Brackets are excluded because their payload survives as
+ * literal text: `round-[acme]-*` must not pass by stripping to `round`.
+ */
+const OPAQUE_FAMILY_WILDCARD_RE =
+    /^(?:(?:inbox|round|src-set|source-set)(?:-\d{4}(?:-\d{2})?)?|set)-[*?]+$/i;
+
 /**
  * The paths a redirect inside one segment would create.
  *

package/src/scripts/hooks/concern_registry.ts

@@ -65,6 +65,7 @@ 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';
 import { main as telemetryUsageMain } from './telemetry_usage_hook.js';
+import { main as mcpUsageObservationMain } from './mcp_usage_observation_hook.js';
 import { main as telemetryFlushMain } from './telemetry_flush_hook.js';
 import { main as delegationNudgeMain } from './delegation_nudge_hook.js';
 import { main as skillRouteMain } from './skill_route_hook.js';
@@ -132,6 +133,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/ui_route_nudge_hook.ts': uiRouteNudgeMain as ConcernMain,
     'src/scripts/hooks/orchestration_record_hook.ts': orchestrationRecordMain as ConcernMain,
     'src/scripts/hooks/telemetry_usage_hook.ts': telemetryUsageMain as ConcernMain,
+    'src/scripts/hooks/mcp_usage_observation_hook.ts': mcpUsageObservationMain as ConcernMain,
     'src/scripts/hooks/telemetry_flush_hook.ts': telemetryFlushMain as ConcernMain,
     'src/scripts/hooks/delegation_nudge_hook.ts': delegationNudgeMain as ConcernMain,
     'src/scripts/hooks/skill_route_hook.ts': skillRouteMain as ConcernMain,

package/src/scripts/hooks/delegation_nudge_hook.ts

@@ -320,11 +320,10 @@ export function resolveActivation(
   const emergency = (settings["emergency"] ?? {}) as Record<string, unknown>;
   const halted = emergency["orchestration_halt"] === true;
   const host_manifest = probeHostCapabilities(hostId);
-  const sub = (settings["subagents"] ?? {}) as Record<string, unknown>;
-  const downshift = sub["downshift"] !== false;
   return {
     activation: { halted, subagent_spawn: host_manifest.subagent_spawn },
-    downshift,
+    // Fixed on: the `subagents.downshift` key was retired with this default.
+    downshift: true,
     separate_quota_pool: host_manifest.separate_quota_pool,
     agentTeams: host_manifest.agent_teams,
   };

package/src/scripts/hooks/design_pass_hook.ts

@@ -48,6 +48,37 @@
  * reason instead of passing silently. `src/rules/design-review-after-ui-write.md`
  * already required that in prose with nothing to read it; this emits it.
  *
+ * SVG ROUTING, AND HOW TO REVERT IT. Step 1.3 of
+ * `road-to-svg-rules-in-the-dispatch-path`. An `.svg` write reaches
+ * `lint_svg_asset`'s rules from here, inside or outside a UI tree, through
+ * `svg_rules_loader` — a CJS chunk beside the dispatch bundle, required only
+ * for a path ending in `.svg`. The review that withdrew the first attempt
+ * named the gap plainly: a statically bundled rule set has no off switch, so
+ * the triggers and the mechanism are written down before they are needed.
+ *
+ *   REVERT WHEN any of these is read:
+ *     · the composition gate exceeds its ceiling attributable to this routing
+ *       (`check_hook_bundle_composition`; measured 2,128 B on 2026-10-11, with
+ *       16,910 B of headroom left);
+ *     · a non-`.svg` hook event is observed failing with a stack that passes
+ *       through the chunk — the containment case
+ *       `design_pass_svg.test.ts > rule-failure-does-not-reach-an-unrelated-event`
+ *       exists to make impossible, so one observation is enough;
+ *     · an operator reports SVG false positives on files they accept, at a rate
+ *       that would make them switch the carrier off — Risk 1 of the parent
+ *       roadmap, and the failure this whole concern is shaped around.
+ *
+ *   THE MECHANISM, in increasing order of blast radius:
+ *     1. Delete `dist/hooks/svg_rules.chunk.cjs`. The loader returns `null`,
+ *        the pass reports `verification: degraded` naming the missing file,
+ *        and every other finding family is unaffected. This is the per-install
+ *        off switch the static import could not have had.
+ *     2. Drop `isSvgAsset` from `isPassSurface` below. An `.svg` outside a UI
+ *        tree stops reaching the pass at all; one inside it reads as it did
+ *        before this step.
+ *     3. Turn the concern off entirely (`hooks.design_pass.enabled: false`),
+ *        which was already the default.
+ *
  * Default-OFF (`hooks.design_pass.enabled`), fail_closed: false.
  *
  * Exit codes (dispatcher contract): 0 allow · 1 block · 2 warn + JSON reason.
@@ -62,6 +93,7 @@ import { trigger_matches, type Trigger } from '../_lib/router_match.js';
 import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
 import { loadDesignContext, scanFile } from '../lint_design_slop.js';
 import { readHookStdin } from './hook_stdin.js';
+import { CHUNK_BASENAME, loadSvgScan } from './svg_rules_loader.js';
 import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 const SETTINGS_FILE = '.agent-settings.yml';
@@ -129,8 +161,42 @@ export function enabled(root: string, key = 'design_pass'): boolean {
     return false;
 }
 
+/**
+ * True for a path this pass should look at.
+ *
+ * `.svg` is admitted HERE and nowhere else — step 1.2 of
+ * `road-to-svg-rules-in-the-dispatch-path`. The obvious way to reach an `.svg`
+ * from this pass was to add `svg` to `UI_EXTENSIONS`, and that is the thing the
+ * parent roadmap's decision E10 and `design_pass_svg.test.ts` forbid: the same
+ * predicate backs `ui_route_nudge_hook`'s `isUiWrite`, so widening it would
+ * draw a UI routing nudge and its tokens on every icon dropped into `public/`.
+ * A local disjunct reaches the asset without touching the shared predicate, in
+ * either direction.
+ */
+export const isSvgAsset = (p: string): boolean => /\.svg$/i.test(p);
+
+/**
+ * UNCHANGED, and that is the point of the predicate below it.
+ *
+ * Finding 6 of this change's own completion review: widening THIS predicate to
+ * admit every `.svg` would have moved the UI-turn denominator the
+ * consultation-rate measurement is defined against — which the
+ * `HANDOVER_TRIGGERS` note further down reserves, in writing, as a different
+ * decision than any routing change. It was widened and is widened no longer.
+ */
 export const isUiSurface = (p: string): boolean => isUiPath(p) || isUiTreePath(p);
 
+/**
+ * What this PASS looks at — a UI surface, or any `.svg`.
+ *
+ * The routing step 1.2 of `road-to-svg-rules-in-the-dispatch-path` asked for,
+ * in the one place it belongs: the pass's own entry gate. Keeping it out of
+ * `isUiSurface` leaves every other reading that predicate feeds — the
+ * conformance verdict's noteworthy test, the denominator above — reading
+ * exactly what it read before.
+ */
+export const isPassSurface = (p: string): boolean => isUiSurface(p) || isSvgAsset(p);
+
 /**
  * The shadow read of `ui-conformance.json` — Phase 5 of
  * `road-to-behaviour-evidence-over-pixels`.
@@ -441,6 +507,53 @@ function renderAvailable(root: string): boolean {
     }
 }
 
+/**
+ * SVG severity → this pass's severity.
+ *
+ * `error` and `warning` become P1 and P2; `inert` is dropped. Deliberately NOT
+ * P0: the P0 set above is a closed list of objective floors and it is the only
+ * thing that computes a block at stop. Routing a new rule family into it would
+ * change the block surface, which is a different decision than making the
+ * findings visible — and the one Risk 1 of the parent roadmap warns about.
+ */
+export function svgSeverity(s: 'error' | 'warning' | 'inert'): Finding['severity'] | null {
+    if (s === 'error') return 'P1';
+    if (s === 'warning') return 'P2';
+    return null;
+}
+
+export interface SvgRuleFinding {
+    rule: string;
+    file: string;
+    line: number;
+    snippet: string;
+    severity: 'error' | 'warning' | 'inert';
+}
+
+/**
+ * Map the SVG rule set's findings onto this pass's shape.
+ *
+ * Pure, and exported, so the routing can be proven without building a bundle:
+ * the half that is expensive to exercise end-to-end is the chunk load, and that
+ * has its own test in `svg_rules_loader`.
+ */
+export function svgFindings(raw: readonly SvgRuleFinding[], rel: string): Finding[] {
+    const out: Finding[] = [];
+    for (const f of raw) {
+        const severity = svgSeverity(f.severity);
+        if (severity === null) continue;
+        out.push({
+            file: rel,
+            severity,
+            catalogId: 'SVG',
+            rule: f.rule,
+            line: f.line,
+            message: `${f.rule}${f.snippet ? ` — ${f.snippet}` : ''}`,
+        });
+    }
+    return out;
+}
+
 /** Extracts the written path from a tool payload, whichever key the host uses. */
 export function targetPath(payload: unknown): string | null {
     if (typeof payload !== 'object' || payload === null) return null;
@@ -499,7 +612,7 @@ function main(): number {
         targets = state.touched;
     } else {
         const t = targetPath(payload);
-        if (!t || !isUiSurface(t)) return EXIT_ALLOW;
+        if (!t || !isPassSurface(t)) return EXIT_ALLOW;
         targets = [t];
         if (!state.touched.includes(t)) state.touched.push(t);
     }
@@ -508,6 +621,7 @@ function main(): number {
     // Findings come from the shipped registry, via the same entrypoint CI uses.
     const findings: Finding[] = [];
     let scanFailed: string | null = null;
+    let svgRulesUnavailable = false;
     try {
         const ctx = loadDesignContext(root);
         for (const rel of targets) {
@@ -517,6 +631,17 @@ function main(): number {
             // itself rather than handing over a path, which is also what lets a
             // post-write pass see the bytes that were just written.
             const content = fs.readFileSync(abs, 'utf-8');
+            if (isSvgAsset(rel)) {
+                // The conditional chunk. Loaded only here, so a hook event that
+                // never touched an `.svg` pays none of its bytes and runs none
+                // of its code — the containment `design_pass_svg.test.ts` pins.
+                // A null load is reported through `svgRulesUnavailable`, never
+                // thrown: a consumer whose install is missing the chunk must
+                // lose the SVG findings, not the whole dispatch.
+                const scan = loadSvgScan();
+                if (scan === null) svgRulesUnavailable = true;
+                else findings.push(...svgFindings(scan(content, rel) as SvgRuleFinding[], rel));
+            }
             for (const f of scanFile(content, rel, ctx)) {
                 findings.push({
                     file: rel,
@@ -532,11 +657,40 @@ function main(): number {
         scanFailed = String(err);
     }
 
-    const auditMissing = targets.filter((t) => !auditIsFresh(root, t));
-    recordAuditDischarge(root, targets, auditMissing);
+    // The audit question is asked of UI SURFACES, never of the pass surface.
+    // Findings 1 and 2 of the third completion review, both reproduced by
+    // running the hook: round one split the entry gate from the UI predicate,
+    // and `targets` carried the `.svg` past the split anyway. So a clean
+    // conformant icon write exited WARN with "no ui-audit.json newer than
+    // public/icon.svg" — an asset has no component inventory to be audited
+    // against — and, worse, `recordAuditDischarge` returns early on a non-empty
+    // `auditMissing`, so writing ONE `.svg` in a turn silently suppressed the
+    // ui-audit discharge row for every real UI file in that same turn.
+    const auditTargets = targets.filter((t) => isUiSurface(t));
+    const auditMissing = auditTargets.filter((t) => !auditIsFresh(root, t));
+    recordAuditDischarge(root, auditTargets, auditMissing);
     let result = decide(slot, findings, auditMissing, new Set(state.surfaced), renderAvailable(root));
     if (scanFailed) {
         result = { ...result, verification: 'unverified', degradation_reason: `detector unavailable: ${scanFailed}` };
+    } else if (svgRulesUnavailable) {
+        // Degraded, not unverified: the rest of the pass ran. An absent chunk
+        // is reported rather than silently producing a clean SVG verdict —
+        // "absent is not clean" is the same rule the conformance verdict keeps.
+        // APPENDED, never overwritten. Finding 6 of the fourth completion
+        // review: `decide` may already have set a reason — the renderer being
+        // absent is the one it sets — and assigning here threw it away, so a
+        // turn where both degradations held reported only the newer one. Two
+        // degradations are two facts; the operator needs both or they fix one
+        // and are surprised by the other.
+        const svgReason = `the SVG rule set could not be loaded (expected dist/hooks/${CHUNK_BASENAME} beside the dispatch bundle) — the .svg files in this turn were not checked`;
+        result = {
+            ...result,
+            verification: 'degraded',
+            degradation_reason:
+                result.degradation_reason === undefined || result.degradation_reason === ''
+                    ? svgReason
+                    : `${result.degradation_reason}; ${svgReason}`,
+        };
     }
 
     for (const f of result.findings) state.surfaced.push(`${f.file}::${f.rule}::${f.line}`);

package/src/scripts/hooks/evidence_independence.ts

@@ -53,6 +53,7 @@ import { atomic_write_json } from "./state_io.js";
 import { readHookStdin } from "./hook_stdin.js";
 import { isCodePath, isTestPath } from "../_lib/test_delta.js";
 import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
+import { ledgerFileFor } from "../git_authorization_hook.js";
 
 // MUST equal dispatch_hook.EXIT_BLOCK. The dispatcher's internal ladder is
 // 0 allow / 1 block / 2 warn — NOT the 2-means-block shape a PreToolUse guard
@@ -198,11 +199,18 @@ interface DispatchState extends JsonObject {
   evaluations: JsonValue[];
 }
 
-/** The current user turn's stamp, or "" when no ledger exists yet. */
-function _ledgerStamp(consumer_root: string): string {
+/**
+ * The current user turn's stamp, or "" when no ledger exists yet.
+ *
+ * Reads the ledger through the writer's own `ledgerFileFor(session_id)`
+ * rather than the legacy session-less path: with a session id the writer
+ * never touches that path, so reading it unconditionally found an empty or
+ * stale file and the stamp never changed per turn.
+ */
+function _ledgerStamp(consumer_root: string, session_id: string): string {
   try {
     const raw = fs.readFileSync(
-      path.join(consumer_root, "agents", "state", "git-authorization.json"),
+      path.join(consumer_root, ledgerFileFor(session_id)),
       "utf8",
     );
     const d = JSON.parse(raw) as Record<string, unknown>;
@@ -421,7 +429,7 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
   // in a session blocked every later one. The only per-user-turn stamp that
   // actually exists is `detected_at` in the authorization ledger, which
   // `git_authorization_hook` rewrites on every `user_prompt_submit`.
-  const turnMarker = `${session_id}:${_ledgerStamp(options.consumer_root)}`;
+  const turnMarker = `${session_id}:${_ledgerStamp(options.consumer_root, session_id)}`;
   if (state.session_id !== turnMarker) {
     state.session_id = turnMarker;
     state.turn_started_at = new Date().toISOString();

package/src/scripts/hooks/mcp_usage_observation_hook.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env tsx
+/**
+ * Foreign MCP tool names, observed on `post_tool_use`
+ * (road-to-neighbours-that-pull-their-weight step 3.3, decision D12).
+ *
+ * DEFAULT-ON LOCAL OBSERVATION, AND IT BYPASSES THE TELEMETRY OPT-IN. Stated
+ * here first because it is the one property a reader must not have to infer.
+ * This concern writes on every install, whether or not the org telemetry switch
+ * was ever enabled, because the file it writes feeds `doctor neighbours` — a
+ * report the consumer runs on their own tree — and gating it on an org switch
+ * would publish `0` on every install that never enabled one. Nothing here is
+ * telemetry: no transport reads the file, it is never spooled, and it lives
+ * under gitignored `agents/runtime/` (decision D9).
+ *
+ * WHAT IS RECORDED: the tool NAME, `mcp__<server>__<tool>`, and the UTC day it
+ * was last seen. Nothing else — no arguments, no response, no session id, no
+ * host. The dispatcher serves this concern a REDUCED payload: its manifest
+ * entry declares no `needs_payload_bodies`, so `tool_input` and `tool_response`
+ * arrive as size-only stubs and cannot be recorded even by mistake.
+ *
+ * RETENTION. A map keyed by tool name, rewritten in place at most once per day
+ * per name — bounded by the neighbour's tool surface, so it needs no TTL job.
+ * The reader applies a 30-day window; older entries stop counting. Deleting
+ * `agents/runtime/neighbour-tool-use.json` erases all of it.
+ *
+ * Why a concern of its own rather than a branch of `telemetry-usage`: that
+ * concern's dispatcher filter is `tools: [Skill]` and matches exactly, so a
+ * branch there was never called for an MCP tool; and a concern named for
+ * opt-in telemetry should not also carry default-on local collection. Both
+ * were the AI council's findings (2026-10-02); the owner chose this shape.
+ *
+ * No `tools:` filter on the manifest entry, deliberately: MCP tool names are
+ * not enumerable and matching is exact. The prefix test below is the filter.
+ *
+ * Exit code is ALWAYS 0 and nothing is printed — it observes, never gates.
+ */
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+
+import { FOREIGN_TOOL_USE_REL, MCP_TOOL_PREFIX, resolveStoreRoot, usageDay } from '../_lib/neighbour_tool_use.js';
+import { update_json_under_lock } from './state_io.js';
+import { readHookStdin } from './hook_stdin.js';
+import { EXIT_ALLOW } from './exit_codes.js';
+
+type JsonObject = { [k: string]: unknown };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The MCP tool name off the envelope, or null for anything else. */
+export function mcpToolName(envelope: unknown): string | null {
+    if (!isObject(envelope)) return null;
+    const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const v = payload['tool_name'] ?? payload['toolName'] ?? payload['tool'];
+    return typeof v === 'string' && v.startsWith(MCP_TOOL_PREFIX) && v.length > MCP_TOOL_PREFIX.length ? v : null;
+}
+
+function record(envelope: unknown, consumer_root: string): number {
+    try {
+        const tool = mcpToolName(envelope);
+        if (tool === null) return EXIT_ALLOW;
+        const day = usageDay(new Date());
+        update_json_under_lock<Record<string, string>>(
+            path.join(resolveStoreRoot(consumer_root), FOREIGN_TOOL_USE_REL),
+            (seen) => (seen[tool] === day ? null : ({ ...seen, [tool]: day } as Record<string, string>)),
+            { blocking: false },
+        );
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return EXIT_ALLOW;
+}
+
+export function run(stdin_text: string, options: { consumer_root: string }): number {
+    let envelope: unknown;
+    try {
+        const raw = stdin_text.trim();
+        if (!raw) return EXIT_ALLOW;
+        envelope = JSON.parse(raw);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return record(envelope, options.consumer_root);
+}
+
+function _root(envelope: unknown): string {
+    if (isObject(envelope)) {
+        const v = envelope['cwd'] ?? envelope['workspace_root'] ?? envelope['project_root'];
+        if (typeof v === 'string' && v) return v;
+    }
+    return process.cwd();
+}
+
+export function main(): number {
+    const raw = readHookStdin();
+    let envelope: unknown = {};
+    try {
+        envelope = raw.trim() ? JSON.parse(raw) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return record(envelope, _root(envelope));
+}
+
+// Bundle-safety: guarded at the call site so esbuild drops the whole entry
+// check inside the shared hook bundle (see telemetry_usage_hook.ts, D11).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (typeof __AGENT_CONFIG_BUNDLE__ === 'undefined' || !__AGENT_CONFIG_BUNDLE__) {
+    if (_isCliEntry()) process.exit(main());
+}

package/src/scripts/hooks/push_settle_hook.ts

@@ -195,9 +195,10 @@ export function buildReminder(branch: string, pr: number | null): { reason: stri
     `  2. Red? Read only the failing part:\n` +
     `     gh run view --job <id> --log-failed | grep -E '×|FAIL|Error'\n` +
     `     then fix it and push again (fix-what-you-see: the author is irrelevant).\n` +
-    `  3. Still red after 3 attempts on the same target, or blocked on something ` +
-    `only the user can decide — stop and say so, with the three attempts named ` +
-    `(autonomous-execution N=3).\n\n` +
+    `  3. 3 attempts on the same target triggers autonomous-execution's ` +
+    `execution.fix_loop_max strategy shift — change approach, never stop. ` +
+    `Blocked on something only the user can decide is the one branch that halts: ` +
+    `say so, with what was tried named.\n\n` +
     `Handing the user a red PR with its cause named and unfixed is not a delivery ` +
     `either. If you are deliberately leaving this WIP, say that in the reply — ` +
     `silence is what this hook exists to stop.`;

package/src/scripts/hooks/rule_inject_hook.ts

@@ -147,7 +147,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { hookSectionEnabled } from '../_lib/hook_settings.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
-import { deliversBodies, resolveLeanProjection } from '../_lib/lean_projection_mode.js';
+import {
+    deliversBodies,
+    installerThinsHost,
+    resolveLeanProjection,
+} from '../_lib/lean_projection_mode.js';
 import { enforcement_class_from_frontmatter } from '../_lib/obligation_frequency.js';
 import {
     appendDelivered,
@@ -168,7 +172,8 @@ import {
 } from '../_lib/rule_injection.js';
 import { readConsequenceClass, stubLawIds } from '../_lib/rule_consequence_class.js';
 import { lawText, ruleBody } from '../_lib/rule_law_section.js';
-import { hostRuleLayerIds } from '../_lib/rule_layer_overlap.js';
+import { hostRuleLayerDirs, hostRuleLayerIds } from '../_lib/rule_layer_overlap.js';
+import { is_thin_entry } from '../_lib/thin_rules.js';
 import { readHookStdin } from './hook_stdin.js';
 import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
@@ -853,6 +858,9 @@ export function buildInjection(
     openFiles: string[] | null,
     command: string | null,
     seen: Set<string>,
+    // `false` only for an offline measurement of WHAT the concern delivers,
+    // which must not read the measuring machine's installed rule files.
+    servedOnce = true,
 ): Injection | null {
     let router;
     try {
@@ -878,14 +886,47 @@ export function buildInjection(
     // `hostRuleLayerIds`. No filter then, because scoping to an empty set would
     // re-create the silence step 1.1 repaired.
     const scope = hostRuleLayerIds(root);
-    const matches = matchTierRules(router, prompt, openFiles, command).filter(
+    let matches = matchTierRules(router, prompt, openFiles, command).filter(
         (m) => !seen.has(m.id) && (scope === null || scope.has(m.id)),
     );
     if (matches.length === 0) return null;
+    // ONE COPY (`road-to-a-default-install-served-once` 1.1). The gate opens on
+    // the template's `delivery`, but the installer thins only on an explicit
+    // user-global choice, so a default install carries every routed body in
+    // its rule files already. A rule whose installed copy is a full body gets
+    // nothing; a stub still gets its body. Asked only off the consent path, so
+    // an opted-in install's delivery is unchanged byte for byte.
+    if (servedOnce && scope !== null && !installerThinsHost(DELIVERY_HOST, { packageRoot: ruleSources(root).pkg })) {
+        const full = installedFullIds(root, matches.map((m) => m.id));
+        matches = matches.filter((m) => !full.has(m.id));
+        if (matches.length === 0) return null;
+    }
     const sel = selectForInjection(root, matches, CAP_BYTES);
     return compose(root, sel, highConsequenceIds(root));
 }
 
+/**
+ * Ids among `ids` whose copy in EITHER host rule layer is a full body rather
+ * than a stub. Either, because the host loads both: one full copy is enough
+ * for the body to be standing in context already. Reads only matched ids,
+ * never the whole layer, because this runs on the per-prompt path.
+ */
+export function installedFullIds(root: string, ids: readonly string[]): Set<string> {
+    const out = new Set<string>();
+    for (const dir of hostRuleLayerDirs(root)) {
+        for (const id of ids) {
+            let text: string;
+            try {
+                text = fs.readFileSync(path.join(dir, `${id}.md`), 'utf-8');
+            } catch {
+                continue;
+            }
+            if (!is_thin_entry(text)) out.add(id);
+        }
+    }
+    return out;
+}
+
 // ── main ─────────────────────────────────────────────────────────────────
 
 /**