@event4u/agent-config 16.3.0 → 16.4.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/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/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 ─────────────────────────────────────────────────────────────────
 
 /**

package/src/scripts/hooks/state_io.ts

@@ -6,10 +6,14 @@
  * Python module exactly (snake_case kept deliberately — fidelity over
  * TS idiom).
  *
- * Per `docs/contracts/hook-architecture-v1.md` § Concurrency, every concern
- * that writes under `agents/runtime/state/` MUST:
- *
- * 1. Acquire an exclusive lock on `agents/runtime/state/.dispatcher.lock`.
+ * Per `docs/contracts/hook-architecture-v1.md`, Concurrency, every concern
+ * that writes a state file under `agents/` MUST:
+ *
+ * 1. Acquire an exclusive lock on `<state_dir>/.dispatcher.lock` — the SAME
+ *    directory the target file lives in, derived from the target's own
+ *    path (`path.dirname`), never a single fixed location: one concern's
+ *    target under `agents/runtime/state/` locks there, another's target
+ *    under `agents/state/` locks there instead.
  * 2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
  * 3. Rename(2) (atomic on the same filesystem) tmp → dest.
  * 4. Release the lock.

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -29,23 +29,11 @@
  * settings file is how it learns it is off, the same as the artefact-
  * engagement surface it mirrors.)
  *
- * THAT SENTENCE USED TO READ "no directory creation", UNQUALIFIED, AND IS
- * NARROWED RATHER THAN QUIETLY LEFT STANDING. The foreign-MCP recorder below
- * writes `agents/runtime/neighbour-tool-use.json` on an install that never
- * enabled telemetry, and creates that directory and a lock sentinel beside it.
- * That is deliberate — the store is a local census input, not telemetry, and
- * gating it on the org switch would print `0` everywhere (roadmap decision D9)
- * — but it IS a file operation, so the guarantee now says which operations it
- * covers. An unqualified claim this file's own code contradicts is worse than
- * the narrower one it is replaced by.
- *
- * NOT REACHED YET, AND SAYING SO HERE BECAUSE THIS IS WHERE A READER LOOKS.
- * The manifest entry for this concern carries `tools: [Skill]`, which the
- * dispatcher matches exactly, so it is not invoked for an MCP call at all and
- * the branch below is dead in production. Held as the
- * `mcp-recorder-unreachable-behind-the-tools-filter` blocker on
- * road-to-neighbours-that-pull-their-weight: the manifest is a gated
- * governance surface and the council split on the edit rather than converging.
+ * The foreign-MCP tool-name recorder that once branched here lives in its own
+ * concern, `mcp-usage-observation` (road-to-neighbours-that-pull-their-weight
+ * D12): this concern's `tools: [Skill]` filter meant the dispatcher never
+ * called that branch, and default-on local collection does not belong under an
+ * opt-in telemetry name.
  *
  * NO OUTBOUND CALL EXISTS HERE, DELIBERATELY. Transport is Phase 2 and is
  * blocked on `sink-choice`; org-wide enablement is Phase 3 and is blocked on
@@ -74,12 +62,7 @@ import {
     FLUSH_SESSION_END,
     spool_path_for,
 } from '../../agent-src/templates/scripts/telemetry/transport.js';
-import {
-    FOREIGN_TOOL_USE_REL,
-    MCP_TOOL_PREFIX,
-    usageDay,
-} from '../_lib/neighbour_tool_use.js';
-import { is_replay_mode, update_json_under_lock } from './state_io.js';
+import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { EXIT_ALLOW } from './exit_codes.js';
 
@@ -272,29 +255,7 @@ function processEnvelope(envelope: JsonValue, consumer_root: string): number {
 
         const payload = unwrapPayload(envelope);
         const tool = extractToolName(payload);
-        if (tool !== SKILL_TOOL_NAME) {
-            // The other half of this slot's observation, and the only half a
-            // `post_tool_use` envelope can supply: the tool's NAME. The MCP
-            // fingerprint store wants a tool DEFINITION, which this envelope
-            // never carries (roadmap decision D2), so what is recorded here is
-            // what was actually seen. Rooted at the settings directory, not at
-            // the session cwd, for the same reason the Class-A log below is.
-            if (tool !== null && tool.startsWith(MCP_TOOL_PREFIX)) {
-                // The mutator's cast is safe at the only place that matters:
-                // the reader in `neighbour_tool_use` drops any value that is
-                // not a string, so a hand-edited store cannot widen this.
-                // Kept OUT of the argument list below — esbuild preserves a
-                // comment in that position and it would cost the shared
-                // bundle ~190 bytes of prose nothing executes.
-                const day = usageDay(new Date());
-                update_json_under_lock<Record<string, string>>(
-                    path.join(readSettingsFor(consumer_root).root, FOREIGN_TOOL_USE_REL),
-                    (seen) => (seen[tool] === day ? null : ({ ...seen, [tool]: day } as Record<string, string>)),
-                    { blocking: false },
-                );
-            }
-            return EXIT_ALLOW;
-        }
+        if (tool !== SKILL_TOOL_NAME) return EXIT_ALLOW;
 
         const { settings, text, root } = readSettingsFor(consumer_root);
         if (!settings.active) return EXIT_ALLOW;

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -1333,6 +1333,7 @@ function recordGraphFeeder(
             inputs.workspaceRoot,
             inputs.sessionKey,
             buildFeederRow({
+                root: inputs.workspaceRoot,
                 turn: inputs.turnOrdinal,
                 layer,
                 state,

package/src/scripts/install-hooks.sh

@@ -70,9 +70,13 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # belongs here; resolution belongs to a step run with the result in front of
 # you. When this hook refuses for staleness, the thing that fixes it is
 #
-#     task push-ready          # fetch -> integrate the base SET -> regenerate
-#                              # -> verify -> re-check freshness -> push
-#     task push-ready DRY=1    # the same six steps, read-only
+#     task push-ready BASE=<base>          # fetch -> integrate the base SET -> regenerate
+#                                          # -> verify -> re-check freshness -> push
+#     task push-ready DRY=1 BASE=<base>    # the same six steps, read-only
+#
+# `<base>` is the base the refusal names. Without BASE the base comes from the
+# open pull request (gh pr view), and is the default branch only when there is
+# no open pull request or no gh.
 #
 # The base is a SET: a branch targeting a release line or a stacked parent may
 # also have to integrate the default branch, per the branch-convergence policy
@@ -141,23 +145,47 @@ fail=0
 # no useful second finding to collect from a tree that is about to move.
 #
 # It never merges. `check_branch_freshness` asks the REMOTE (one `ls-remote`,
-# measured 4.5s) and returns 1 only on a VERIFIED behind state; offline, in CI,
-# on a detached HEAD, or standing on the base itself it returns 0 and says so.
-# So an unreachable network cannot block a push, and a stale local tracking ref
-# cannot fake a green.
+# measured 4.5s) and returns 1 on a VERIFIED behind state, or when the remote
+# answered without the base at all (a misspelled or deleted base); offline, in
+# CI, on a detached HEAD, or standing on the base itself it returns 0 and says
+# so. So an unreachable network cannot block a push, and a stale local tracking
+# ref cannot fake a green. The refusal below names which of the two it was, read
+# from the gate's own lines, so a typo is never reported as staleness.
 echo "🔍 Base freshness — is this branch behind the base it will merge into?"
 if [ "${AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS:-}" = "1" ]; then
     echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1"
 elif [ ! -x ./scripts-run ]; then
     echo "⚠️  ./scripts-run not found — skipping the freshness check for this push."
-elif ! ./scripts-run src/scripts/check_branch_freshness --quiet; then
-    echo ""
-    echo "   Push blocked — the branch is behind its base, and the gates you just"
-    echo "   passed were answered against a base that no longer exists."
+else
+    fresh_rc=0
+    fresh_out=$(./scripts-run src/scripts/check_branch_freshness --quiet 2>&1) || fresh_rc=$?
+    [ -z "$fresh_out" ] || printf '%s\n' "$fresh_out"
+fi
+if [ "${fresh_rc:-0}" -ne 0 ]; then
+    # The gate prints the base in the spelling `task push-ready` accepts.
+    base=$(printf '%s\n' "$fresh_out" | sed -n 's/^ *task push-ready BASE=\([^ ]*\).*/\1/p' | head -n 1)
+    absent=$(printf '%s\n' "$fresh_out" | sed -n 's/.*base `\([^`]*\)` does not exist on \([^ ]*\) .*/\2\/\1/p' | head -n 1)
     echo ""
-    echo "     task push-ready         # fetch → integrate the base SET → regenerate"
-    echo "                             # → verify → re-check freshness, then push"
-    echo "     task push-ready DRY=1   # the same steps, read-only"
+    if [ -n "$base" ]; then
+        echo "   Push blocked — the branch is behind its base, and the gates you just"
+        echo "   passed were answered against a base that no longer exists."
+        echo ""
+        echo "     task push-ready BASE=$base         # fetch → integrate the base SET"
+        echo "                                         # → regenerate → verify → re-check"
+        echo "     task push-ready DRY=1 BASE=$base   # the same steps, read-only"
+    elif printf '%s\n' "$fresh_out" | grep -q 'branch is BEHIND'; then
+        # A strategy that does not merge gets no push-ready line; its remedy
+        # is printed by the gate itself.
+        echo "   Push blocked — the branch is behind its base. The remedy for this"
+        echo "   project's update strategy is printed above."
+    elif [ -n "$absent" ]; then
+        echo "   Push blocked — the base $absent does not exist on the remote: a"
+        echo "   misspelled or deleted base, not a stale branch. Name a branch the"
+        echo "   remote has (--base main and --base origin/main are the same branch)."
+    else
+        echo "   Push blocked — the freshness gate refused without a verdict line;"
+        echo "   its output is above."
+    fi
     echo ""
     echo "   This hook refuses; it never merges. Bypass a genuine WIP push with"
     echo "   AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1."