@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/hooks/table_fingerprint.ts

@@ -9,6 +9,27 @@ import { createHash } from 'node:crypto';
  * dispatcher: `dispatch_hook` → `host_semantics` → `host_lowering` is a live
  * import chain, so the reverse edge would be a cycle.
  *
+ * THE RETIRED ARGUMENT, kept because both callers point here for it rather
+ * than restating it. `dispatch_hook._manifest_fingerprint` argued AGAINST a
+ * cryptographic hash on two grounds, and by the time road-to-blocking-
+ * severities 3.1 read that header the body had already been delegating here for
+ * a release — so a reader checking whether the dispatcher resists a CRAFTED
+ * sibling met a disclaimer the code had stopped making. Both grounds were
+ * re-measured when this module was extracted, and both were stale:
+ *
+ *   - "`require('node:crypto')` costs 8 ms of process start, which is most of
+ *     what the precompiled manifest exists to save." The module is already
+ *     loaded: `dist/hooks/dispatch.js` carries 23 top-level
+ *     `import … from "node:crypto"` statements from other parts of the graph,
+ *     so the cost is paid whether this function uses it or not.
+ *   - "An FNV-1a loop runs in about 0.2 ms and is the right trade." SHA-256
+ *     measured FASTER — 0.106 ms against 0.113 ms over the 99,792-byte
+ *     manifest — because Node's digest is native and the loop was that many
+ *     interpreted `charCodeAt` calls.
+ *
+ * Both readers now point here instead of restating it, so the argument and the
+ * numbers that retired it cannot part company again.
+ *
  * DELIBERATELY CONTENT-DERIVED, NOT MTIME. The first version of the manifest
  * fast path compared mtimes and that was a measured defect, not a theoretical
  * one: on a fresh `actions/checkout` both files carry the checkout timestamp in

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -22,12 +22,31 @@
  * activates only when `enabled` is true AND the org pack supplied an
  * endpoint, an org id, and a salt. An external clone of this repository
  * carries the key names and no values, so copying the tree cannot reach the
- * write path. When inactive this concern performs zero telemetry file
- * operations — no log write, no directory creation — and zero network calls.
+ * write path. When inactive this concern performs zero TELEMETRY file
+ * operations — no log write, no spool, no directory under the configured
+ * output path — and zero network calls.
  * (It does read `.agent-settings.yml`, once per process and memoised: the
  * 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.
+ *
  * 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
  * `dpo-signoff`. This concern appends to a local JSONL file and stops.
@@ -55,7 +74,12 @@ import {
     FLUSH_SESSION_END,
     spool_path_for,
 } from '../../agent-src/templates/scripts/telemetry/transport.js';
-import { is_replay_mode } from './state_io.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 { readHookStdin } from './hook_stdin.js';
 import { EXIT_ALLOW } from './exit_codes.js';
 
@@ -247,7 +271,30 @@ function processEnvelope(envelope: JsonValue, consumer_root: string): number {
         if (!isObject(envelope)) return EXIT_ALLOW;
 
         const payload = unwrapPayload(envelope);
-        if (extractToolName(payload) !== SKILL_TOOL_NAME) return EXIT_ALLOW;
+        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;
+        }
 
         const { settings, text, root } = readSettingsFor(consumer_root);
         if (!settings.active) return EXIT_ALLOW;
@@ -339,11 +386,18 @@ export function main(): number {
 
 // Bundle-safety: never auto-run when inlined into an esbuild bundle, where
 // every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+//
+// The bundle test is at the CALL SITE rather than at the top of
+// `_isCliEntry`, and that placement is the whole point. Inside the function
+// esbuild folds the condition to `if (true) return false` and then emits the
+// nine unreachable lines below it anyway — measured at 475 bytes of dead code
+// in a bundle `check_hook_bundle_composition` caps. Guarding the call instead
+// makes the whole statement `if (false)`, which esbuild drops, taking the now
+// unreferenced function with it. Behavior outside the bundle is unchanged:
+// `__AGENT_CONFIG_BUNDLE__` is undeclared there, the first operand is true,
+// and `!__AGENT_CONFIG_BUNDLE__` is never evaluated — so no ReferenceError.
 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;
@@ -353,4 +407,6 @@ function _isCliEntry(): boolean {
         return false;
     }
 }
-if (_isCliEntry()) process.exit(main());
+if (typeof __AGENT_CONFIG_BUNDLE__ === 'undefined' || !__AGENT_CONFIG_BUNDLE__) {
+    if (_isCliEntry()) process.exit(main());
+}

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -186,6 +186,17 @@ export { readTurnRunState };
 // Detector E, extracted to `_lib` where its prose costs no ratchet debt.
 // Re-exported so every existing importer of this module is unchanged.
 import { detectDroppedDecision } from '../_lib/dropped_decision.js';
+// Step 3.2 of `road-to-a-graph-that-feeds-the-gate` — the shadow feeder. It
+// lives in `_lib` for the reason every other extraction here does: this file
+// sits against a 1,500-line shrink-only source budget, and the module it would
+// otherwise grow into is one a recall reading has to be able to open on its own.
+import {
+    appendFeederRow,
+    buildFeederRow,
+    type FeederLayer,
+    graphUntestedVerdict,
+} from '../_lib/graph_feeder_record.js';
+import { type GraphState, graphState } from '../code_graph/detect.js';
 import { isVerificationCommand } from '../_lib/verification_command.js';
 // Round 8 — the record path detector C prefers over its own regex. The regex
 // reads a command's TEXT and `echo test` matches it; these read what the run
@@ -215,6 +226,7 @@ import {
     readInstallBoundary,
     sessionRefusalFile,
     sessionShadowFile,
+    shadowSetBy,
     type RefusalRecord,
     type ShadowLayer,
     type ShadowRecord,
@@ -1276,6 +1288,65 @@ function runDetectors(inputs: DetectorInputs): Finding[] {
     return findings;
 }
 
+/**
+ * Write the graph feeder row for ONE stop (step 3.2).
+ *
+ * Called from both stop paths with the findings that path already computed, so
+ * the F verdict in the row is the SAME verdict the gate acted on — never a
+ * second evaluation written beside it, which is the shape
+ * `obligation_settle_hook.ts` names as measuring nothing.
+ *
+ * It changes no exit code, and the whole body is wrapped: a stop that crashed on
+ * its own instrument would be a new failure mode on a path that is supposed to
+ * cost nothing. The graph half is skipped outright unless the state is `fresh`
+ * or `edited` — an answer from an index that predates the change is not evidence
+ * about the change.
+ */
+function recordGraphFeeder(
+    inputs: DetectorInputs,
+    findings: readonly Finding[],
+    layer: FeederLayer,
+): void {
+    if (is_replay_mode()) return;
+    try {
+        let state: GraphState;
+        try {
+            state = graphState(inputs.workspaceRoot);
+        } catch {
+            return;
+        }
+        // No graph at all is the silent case, exactly as it is for the context
+        // hook: a consumer who never builds one never grows this file.
+        if (state === 'absent') return;
+        // The SAME path set detector F reads, filtered by the SAME predicate.
+        // A completion review found the two arms running over different inputs:
+        // the feeder passed every edit path while F filters to production
+        // source, so the graph arm would have fired on precisely the turns F is
+        // silent for — a recall comparison between two detectors answering
+        // different questions, which is worse than no comparison.
+        const paths = inputs.toolCalls
+            .filter((c) => _EDIT_TOOLS.has(c.name) && c.path !== undefined)
+            .map((c) => c.path as string)
+            .filter(_isProductionSource);
+        const f = findings.find((x) => x.detector === 'untested');
+        appendFeederRow(
+            inputs.workspaceRoot,
+            inputs.sessionKey,
+            buildFeederRow({
+                turn: inputs.turnOrdinal,
+                layer,
+                state,
+                fFired: f !== undefined,
+                fMode: f?.mode ?? null,
+                paths,
+                graph: graphUntestedVerdict(inputs.workspaceRoot, state, paths),
+            }),
+        );
+    } catch {
+        // An instrument is never a reason to change what the gate does.
+    }
+}
+
 /**
  * Record what this retry WOULD have been refused for, then let it end.
  *
@@ -1289,6 +1360,14 @@ function recordShadow(inputs: DetectorInputs, layer: ShadowLayer): void {
     if (is_replay_mode()) return;
     try {
         const findings = runDetectors(inputs);
+        // On `refused_turn` the answer is `ours` by construction — that marker
+        // is this gate's own and nothing else writes it. On `stop_hook_active`
+        // the host sets the flag for ANY stop hook's block, so it has to be
+        // read from our own refusal record rather than assumed.
+        const setBy = layer === 'refused_turn'
+            ? 'ours'
+            : shadowSetBy(inputs.workspaceRoot, inputs.sessionKey);
+        recordGraphFeeder(inputs, findings, layer);
         const file = sessionShadowFile(inputs.workspaceRoot, inputs.sessionKey);
         let prev: ShadowRecord | null = null;
         try {
@@ -1303,6 +1382,7 @@ function recordShadow(inputs: DetectorInputs, layer: ShadowLayer): void {
                 turnOrdinal: inputs.turnOrdinal,
                 at: new Date().toISOString(),
                 layer,
+                setBy,
             }) as unknown as Record<string, unknown>,
         );
     } catch {
@@ -1361,6 +1441,10 @@ export function main(): number {
     // warranted"; there is no second, configurable notion of warranted layered
     // on top of it.
     const findings = runDetectors(inputs);
+    // The live verdict's own row. It is written BEFORE the branch below, so a
+    // turn the gate allows and a turn it refuses are both in the record — a
+    // recall reading needs the allowed turns as its negative arm.
+    recordGraphFeeder(inputs, findings, 'live');
     if (findings.length === 0) return EXIT_ALLOW;
 
     markRefusedTurn(

package/src/scripts/hooks_status.ts

@@ -23,11 +23,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { enforcementFor } from "./check_enforcement_matrix.js";
 import {
   type JsonObject,
   type JsonValue,
   _load_yaml,
 } from "./hooks/dispatch_hook.js";
+import { loadHostLowering } from "./hooks/host_lowering.js";
+import { type SlotReading, readSlots } from "./report_enforcement_drift.js";
 
 // src/scripts/hooks_status.ts → parents[1] is the repo root (.../parents[2]
 // in the Python which lives one level deeper relative computation).
@@ -90,6 +93,18 @@ export interface PlatformRow {
    */
   ask: AskShape;
   bindings: Record<string, string[]>;
+  /**
+   * For each slot that binds at least one `blocking` concern, what that host's
+   * slot can actually carry — `refusal`, `warning-only`, `unverified` or
+   * `proof-expired` (road-to-blocking-severities 1.2).
+   *
+   * Slots with no blocking concern are ABSENT rather than present with a
+   * value, so a reader cannot mistake "nothing here claims to refuse" for a
+   * capability reading. Derived from `host_lowering.yaml`, never from the
+   * manifest: the manifest declares intent and only the lowering table records
+   * whether a refusal can land.
+   */
+  blocking_enforcement: Record<string, string>;
   hint: string | null;
 }
 
@@ -123,10 +138,79 @@ function _bridge_status(project_root: string, rel_path: string): string {
   return stat && stat.isFile() ? "installed" : "missing";
 }
 
+/**
+ * `severity` per concern, read off the manifest this report already loaded.
+ *
+ * `(undeclared)` is folded into "not blocking": this report publishes the
+ * enforcement of concerns that CLAIM to refuse, and a concern that claims
+ * nothing has nothing to reconcile. `lint_hook_manifest` is what refuses an
+ * undeclared severity; duplicating that judgement here would put two answers
+ * in the tree.
+ */
+function _severities(manifest: JsonObject): Map<string, string> {
+  const out = new Map<string, string>();
+  const concerns = manifest["concerns"];
+  if (!_isObject(concerns)) {
+    return out;
+  }
+  for (const [name, spec] of Object.entries(concerns)) {
+    const sev = _isObject(spec) ? spec["severity"] : undefined;
+    if (typeof sev === "string") {
+      out.set(name, sev);
+    }
+  }
+  return out;
+}
+
+/**
+ * What each slot carrying a `blocking` concern can actually do on this host.
+ *
+ * road-to-blocking-severities 1.2, the third surface. The decision and the
+ * vocabulary live in `check_enforcement_matrix`; this reads them rather than
+ * restating them, so the published document and this report cannot drift into
+ * two different answers to one question.
+ *
+ * Failure is SILENT and the field is simply absent. This is a read-only status
+ * report that the post-install smoke probe runs, and a malformed or missing
+ * lowering table must degrade it, never abort it — the gate is where a broken
+ * lowering table is supposed to fail.
+ */
+function _blocking_enforcement(
+  platform: string,
+  bindings: Record<string, string[]>,
+  severities: Map<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  let slots: SlotReading[];
+  try {
+    slots = readSlots(loadHostLowering(), platform).slots;
+  } catch {
+    return out;
+  }
+  const bySlot = new Map(slots.map((s) => [s.slot, s]));
+  for (const [event, concerns] of Object.entries(bindings)) {
+    if (!concerns.some((c) => severities.get(c) === "blocking")) {
+      continue;
+    }
+    const row = bySlot.get(event);
+    out[event] = enforcementFor(
+      row === undefined
+        ? "unlowerable"
+        : row.literal === null
+          ? "null-block"
+          : row.effective === null
+            ? "stale-proof"
+            : null,
+    );
+  }
+  return out;
+}
+
 /** Build the runtime matrix as a plain object — JSON-serialisable. */
 export function collect(project_root: string, manifest: JsonObject): StatusMatrix {
   const platformsRaw = manifest["platforms"];
   const platforms = _isObject(platformsRaw) ? platformsRaw : {};
+  const severities = _severities(manifest);
   const rows: PlatformRow[] = [];
   for (const platform of Object.keys(PLATFORM_BRIDGES)) {
     const [rel, hint] = PLATFORM_BRIDGES[platform] as [string, string];
@@ -148,6 +232,7 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
     rows.push({
       platform,
       status,
+      blocking_enforcement: _blocking_enforcement(platform, bindings, severities),
       bridge_path: rel || null,
       fallback_only,
       ask,
@@ -160,6 +245,23 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
   return { schema_version: 1, platforms: rows };
 }
 
+/**
+ * One short line per enforcement value, for the table.
+ *
+ * `unverified` says what is MISSING, never what the host cannot do — the same
+ * wording discipline `docs/enforcement-by-host.md` carries, and the reason this
+ * report distinguishes the two values at all.
+ */
+const _ENFORCEMENT_NOTE: Record<string, string> = {
+  refusal: "the slot denies, so a blocking verdict stops the call",
+  "proof-expired":
+    "the slot can deny; this package's `verified` citation has lapsed",
+  "warning-only":
+    "`block_exit` is null here — they run and warn, they cannot refuse",
+  unverified:
+    "no lowering row for this slot — nothing bound natively, nothing established",
+};
+
 const _STATUS_MARKER: Record<string, string> = {
   installed: "✅ ",
   missing: "❌ ",
@@ -199,6 +301,16 @@ export function _render_table(matrix: StatusMatrix): string {
     for (const event of Object.keys(row.bindings).sort()) {
       const concerns = row.bindings[event]?.join(", ") || "—";
       lines.push(`    ${event.padEnd(22)} → ${concerns}`);
+      // road-to-blocking-severities 1.2 — printed only where a concern on this
+      // slot DECLARES `blocking`, and worded so `unverified` never reads as a
+      // claim about the host.
+      const enforcement = row.blocking_enforcement[event];
+      if (enforcement !== undefined) {
+        lines.push(
+          `    ${" ".repeat(22)}   blocking concerns here: ${enforcement} — ` +
+            `${_ENFORCEMENT_NOTE[enforcement] ?? "see docs/enforcement-by-host.md"}`,
+        );
+      }
     }
     if (row.hint) {
       lines.push(`    hint: ${row.hint}`);

package/src/scripts/injection_scan_hook.ts

@@ -214,6 +214,13 @@ export const OUTPUT_KEYS: readonly string[] = [
   "toolResponse",
   "tool_result",
   "toolUseResult",
+  // The failure event's result body. A FAILING command on claude carries its
+  // stdout and stderr here and carries no `tool_response` at all, so without
+  // this line a failed `curl` of a hostile page would reach the model with
+  // nothing scanned — the one direction where the output is most likely to be
+  // attacker-shaped. Caught by this concern's own coverage test, which pins
+  // OUTPUT_KEYS as a superset of what the dispatcher serves.
+  "error",
   // Generic spellings accepted since this concern shipped.
   "output",
   "result",