@event4u/agent-config 16.0.0 → 16.1.0

package/src/scripts/hooks/obligation_settle_hook.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env tsx
+/**
+ * obligation-settle — the reader the delivered-obligation record never had.
+ *
+ * The injector has always known which rules it delivered into a session. Until
+ * this concern, nothing asked whether the turn that received them discharged
+ * any. This is that question, asked at turn-end, and — for now — asked out
+ * loud and answered with nothing.
+ *
+ * SHADOW ONLY. IT REFUSES NOTHING, AND THAT IS NOT A PLACEHOLDER.
+ * It computes the verdict a future armed detector would reach, records it, and
+ * returns allow on every path. Arming is gated on a bar pre-registered in
+ * `docs/CLAIMS.md` BEFORE any code able to refuse exists, so that the bar
+ * cannot be chosen to fit the numbers the shadow window happened to produce.
+ * The estate already has one blocking turn-end concern and the first-ranked
+ * risk against this work is that a second one refuses a clean turn and an
+ * operator disables the carrier for good.
+ *
+ * THE TOUCHED SET COMES FROM THE DIFF, NOT FROM TOOL EVENTS.
+ * A tool event carries the path the tool was given. A shell heredoc writing
+ * three files reports one Bash call and no paths at all, so a detector reading
+ * tool events is blind to exactly the turns that wrote the most. `git diff
+ * --numstat HEAD` plus `git ls-files --others` sees the tree as it actually
+ * is, which is the only description that cannot be evaded by how the write was
+ * spelled. The helpers are the end-review concern's own, imported rather than
+ * re-derived.
+ *
+ * IT REFUSES ONLY ON CLASSES THAT COULD HAVE A DISCHARGE.
+ * `hook`, `validator` and `test` name carriers that run and leave traces.
+ * `observer`, `instruction-only` and `none` do not, so demanding a discharge
+ * for one would demand evidence nobody can produce — and 69 of 97 delivered
+ * rules on the frozen corpus are class `none`.
+ *
+ * IT IS SILENT WHILE A SUBAGENT DISPATCH IS OPEN.
+ * Three of the turn-end gate's six detectors are gated this way and three are
+ * not; the difference is whether the finding could be about work a dispatch is
+ * still doing. This one could — a subagent writing UI files is the canonical
+ * case — so it takes the gated side.
+ */
+
+import path from 'node:path';
+import process from 'node:process';
+
+import { may_refuse_on } from '../_lib/obligation_frequency.js';
+import { appendShadow, readDelivered, readDischarged, stamp } from '../_lib/obligations.js';
+import { loadRouter, matchTierRules } from '../_lib/rule_injection.js';
+import { gitNumstatRows, isDocPath, untrackedNonDocFiles } from './end_review_nudge_hook.js';
+import { openRecordStats } from './subagent_ledger_hook.js';
+
+const EXIT_ALLOW = 0;
+
+/**
+ * Every non-doc path this turn wrote, tracked or not.
+ *
+ * Doc paths are excluded on the same grounds the end-review concern excludes
+ * them: a markdown edit is not the kind of change whose obligations this
+ * detector can speak to, and including them would make almost every turn a
+ * candidate.
+ */
+export function touchedPaths(cwd: string): string[] {
+    const tracked = gitNumstatRows(cwd)
+        .map((r) => r.path)
+        .filter((p) => p !== '' && !isDocPath(p));
+    const untracked = untrackedNonDocFiles(cwd);
+    return [...new Set([...tracked, ...untracked])];
+}
+
+export interface SettleVerdict {
+    /** Non-doc paths this turn wrote. */
+    readonly touched: string[];
+    /** Delivered rules whose path triggers match something touched. */
+    readonly candidates: string[];
+    /** Candidates with no recorded discharge, and a class that could have one. */
+    readonly missing: string[];
+    /** True when a subagent dispatch is open — every other field is then advisory only. */
+    readonly dispatchOpen: boolean;
+}
+
+/**
+ * What an armed detector would conclude, computed without refusing anything.
+ *
+ * Exported whole rather than as a boolean so the shadow row, the tests and any
+ * later armed path all read the SAME computation. A detector whose shadow
+ * measurement and live behaviour come from different code measures nothing.
+ */
+export function computeVerdict(root: string, session: string): SettleVerdict {
+    const dispatchOpen = (() => {
+        try {
+            return openRecordStats(root).open_count > 0;
+        } catch {
+            // An unreadable ledger is not a reason to change the verdict.
+            return false;
+        }
+    })();
+
+    const touched = touchedPaths(root);
+    if (touched.length === 0) {
+        return { touched, candidates: [], missing: [], dispatchOpen };
+    }
+
+    const delivered = readDelivered(root, session);
+    if (delivered.length === 0) {
+        return { touched, candidates: [], missing: [], dispatchOpen };
+    }
+
+    let pathMatched = new Set<string>();
+    try {
+        const router = loadRouter(root);
+        // Empty prompt, so only PATH triggers can fire. A turn's file writes
+        // are not a restatement of the user's request and must not re-fire
+        // keyword rules — the same reasoning the injector applies on its own
+        // tool slot.
+        pathMatched = new Set(matchTierRules(router, '', touched, null).map((m) => m.id));
+    } catch {
+        return { touched, candidates: [], missing: [], dispatchOpen };
+    }
+
+    const candidates = delivered
+        .filter((r) => pathMatched.has(r.rule) && may_refuse_on(r.cls))
+        .map((r) => r.rule);
+
+    const discharged = new Set(readDischarged(root, session).map((r) => r.rule));
+    const missing = candidates.filter((id) => !discharged.has(id));
+    return { touched, candidates: [...new Set(candidates)], missing: [...new Set(missing)] , dispatchOpen };
+}
+
+/**
+ * Whether this reading should force a continuation, were anything armed.
+ *
+ * An UNCHANGED missing set on a second reading means the previous nudge moved
+ * nothing, so nudging again would loop rather than progress. The obligations
+ * stay OPEN — that is the whole point, and it is the side of the source set's
+ * self-contradiction this ships. A budget running out is a fact about the
+ * budget; letting it write a policy verdict is how an unmet obligation becomes
+ * a satisfied one with nobody deciding, and an exhausted budget is exactly the
+ * moment the obligation is least likely to have been met.
+ *
+ * There is therefore no `waived` state anywhere in this file, and no code path
+ * that writes one.
+ */
+export function shouldContinue(attempt: number): boolean {
+    return attempt <= 1;
+}
+
+export function main(): number {
+    const root = process.cwd();
+    const session = (process.env['CLAUDE_CODE_SESSION_ID'] ?? '').trim();
+    if (session === '') return EXIT_ALLOW;
+
+    let verdict: SettleVerdict;
+    try {
+        verdict = computeVerdict(root, session);
+    } catch {
+        // A detector that cannot compute has nothing to say. It never has a
+        // refusal to withhold, so there is no safe-vs-unsafe choice here.
+        return EXIT_ALLOW;
+    }
+
+    // Silent while a dispatch is open: the files may be a subagent's, still
+    // being written, and a shadow row claiming otherwise would poison the very
+    // corpus the arming decision is measured against.
+    if (verdict.dispatchOpen) return EXIT_ALLOW;
+    if (verdict.missing.length === 0) return EXIT_ALLOW;
+
+    const attempt = appendShadow(root, session, verdict.missing, stamp());
+    if (attempt === 0) return EXIT_ALLOW;
+
+    // ONE line for the whole missing set, never one per obligation — the same
+    // aggregation the row itself uses, for the same reason.
+    process.stderr.write(
+        `obligation-settle (shadow, refusing nothing): ${verdict.missing.length} `
+            + `obligation(s) with no recorded discharge after writing `
+            + `${verdict.touched.length} file(s): ${verdict.missing.join(', ')}`
+            + `${shouldContinue(attempt) ? '' : ' — unchanged since the last reading; still open'}\n`,
+    );
+    return EXIT_ALLOW;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle.
+if (process.argv[1] !== undefined && path.basename(process.argv[1]).startsWith('obligation_settle')) {
+    process.exit(main());
+}

package/src/scripts/hooks/rule_inject_hook.ts

@@ -11,7 +11,14 @@
  * the 36.2 %-against-48 % run at `docs/CLAIMS.md:188-189`. Whatever that
  * instrument's flaws — and ADR-202 closed it — it points one way.
  *
- * SHIPPED ON FOR CLAUDE CODE SINCE ADR-265 — corrected 2026-09-08 (R2 finding
+ * SHIPPED ON FOR CLAUDE CODE SINCE ADR-267 — the delivery-default record, and
+ * the citation is corrected here (2026-09-13) from ADR-265, which decides
+ * something else entirely: whether the iron-law reserve is activated, answered
+ * no, with the verifier kept inside the change. Nothing in it ships a
+ * projection mode. ADR-267 `delivery-default-for-claude-code` is the record
+ * that turns this concern on for this host, and it is the one whose
+ * `review_trigger` fires if a rule stops arriving. Previously corrected
+ * 2026-09-08 (R2 finding
  * 4), because this paragraph read "DEFAULT OFF, AND OFF MEANS ZERO BYTES …
  * under every shipped default it emits nothing … there is no measured emission
  * to register yet" and all four clauses became false in the same change that
@@ -94,6 +101,8 @@ import {
     normalizeLeanProjectionMode,
     resolveLeanProjectionHosts,
 } from '../_lib/lean_projection_mode.js';
+import { enforcement_class_from_frontmatter } from '../_lib/obligation_frequency.js';
+import { appendDelivered, stamp, type DeliveredRow } from '../_lib/obligations.js';
 import {
     loadRuleBody,
     loadRouter,
@@ -237,6 +246,44 @@ export interface Injection {
     body: string;
 }
 
+/**
+ * Record what this fire delivered, so something can later ask whether the turn
+ * discharged it.
+ *
+ * The write happens HERE and not in a later slot because this is the only
+ * place that knows the answer. By the time a turn ends, the selection that
+ * produced these ids is gone — the router would have to be re-run against a
+ * prompt nobody kept, which is a different computation that could disagree.
+ *
+ * EMITTER RECORD, NEVER A COMPLIANCE ONE. A row says a body was emitted into
+ * this slot. It does not say the model read it, and the ledger's own header
+ * carries the council lock that forbids reading it that way.
+ *
+ * Best-effort by construction: every failure path inside `appendDelivered`
+ * returns rather than throws, and this wrapper adds one more guard so a
+ * ledger problem can never turn a successful injection into a failed hook.
+ * A missed reading is cheaper than a refused turn, and this concern has no
+ * refusal to offer anyway.
+ */
+export function recordDelivered(root: string, session: string, ruleIds: string[]): number {
+    try {
+        const now = stamp();
+        const rows: DeliveredRow[] = ruleIds.map((id) => {
+            const body = loadRuleBody(root, id);
+            return {
+                rule: id,
+                // A rule with no projected body declares nothing this can read,
+                // which is `none` — the same answer as a body declaring none.
+                cls: body === null ? 'none' : enforcement_class_from_frontmatter(body),
+                at: now,
+            };
+        });
+        return appendDelivered(root, session, rows);
+    } catch {
+        return 0;
+    }
+}
+
 /**
  * Build the injection for one event, or `null` for silence.
  *
@@ -371,6 +418,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
 
     for (const id of injection.rules) seen.add(id);
     writeSeen(root, session, seen);
+    recordDelivered(root, session, injection.rules);
 
     process.stdout.write(
         `${JSON.stringify({

package/src/scripts/hooks/run_continuation_hook.ts

@@ -185,6 +185,7 @@ import { premiseMoved, readContextObservation } from '../_lib/context_observatio
 import { RUN_TERMINAL_VOCABULARY_VERSION } from '../_lib/outcome_vocabularies.js';
 import {
     HALT_ACTIONS,
+    buildLedgerEvent, parseDeliveryState, type DeliveryState,
     ladder,
     MAX_ITERATIONS,
     parseHaltStamp,
@@ -322,6 +323,8 @@ export interface RunState {
      * observed one, which is never a disagreement (`premiseMoved`).
      */
     context_fingerprint?: string;
+    /** DELIVERY position (8.1), written by the run; absent is no hold. */
+    delivery?: DeliveryState;
 }
 
 /**
@@ -651,6 +654,10 @@ function readState(file: string): RunState | null {
         if (o['inert_reported'] === true) {
             rec.inert_reported = true;
         }
+        // Round-tripped for the same reason `history_source` is: without this the
+        // 8.1 hold is dead code that reads as shipped.
+        const dlv = parseDeliveryState(o['delivery']);
+        if (dlv !== undefined) rec.delivery = dlv;
         // Round-tripped for the same reason `history_source` is: dropped, the
         // premise would be re-recorded every fire from the newest observation, so
         // the two sides could never differ and the rung would be dead code.
@@ -1384,14 +1391,14 @@ export function main(): number {
     const observed = readContextObservation(workspaceRoot)?.fingerprint ?? null;
     const premiseInvalidated = premiseMoved(state.context_fingerprint, observed);
 
+    const delivery = parseDeliveryState(state.delivery) ?? null;
     const action = ladder(
-        state,
-        scan.open,
-        Date.now(),
+        state, scan.open, Date.now(),
         scan.blocked,
         undefined,
         unavailable,
         premiseInvalidated,
+        delivery,
     );
 
     if (action !== 'engage') {
@@ -1408,23 +1415,13 @@ export function main(): number {
         const alreadyBlocked =
             action === 'blocked' && eventAlreadyLogged(workspaceRoot, runId, slug, 'blocked');
         if (!alreadyStamped && !alreadyBlocked) {
-            appendEvent(workspaceRoot, {
-                event: action,
-                run_id: runId,
-                roadmap: slug,
-                turn: turnOrdinal,
-                iterations: state.iterations,
-                open: scan.open,
-                blocked: scan.blocked,
-                // A ledger line is a persisted shape carrying a `RunTerminalState`,
-                // so it names the vocabulary version it was written against: a
-                // reader meeting an unknown value can then tell a newer writer
-                // from a corrupt row.
-                terminal_state: terminalStateFor(action),
-                terminal_vocabulary_version: RUN_TERMINAL_VOCABULARY_VERSION,
-                at: new Date().toISOString(),
-                ...roots,
-            });
+            const line = buildLedgerEvent(
+                { action, runId, slug, turn: turnOrdinal, iterations: state.iterations,
+                  open: scan.open, blocked: scan.blocked, delivery },
+                RUN_TERMINAL_VOCABULARY_VERSION,
+                new Date(),
+            );
+            appendEvent(workspaceRoot, { ...line, ...roots } as JsonObject);
         }
         if (action === 'complete') {
             // Only a COMPLETION clears the state, so a later run on the same

package/src/scripts/hooks_doctor.ts

@@ -45,6 +45,7 @@ import {
   type InstallBoundary,
   type RefusalStats,
 } from "./_lib/turn_end_refusals.js";
+import { ledgerWritable, readDelivered } from "./_lib/obligations.js";
 
 // src/scripts/hooks_doctor.ts → parents[2] (../../..) is the repo root,
 // mirroring the Python `Path(__file__).resolve().parents[2]`.
@@ -191,10 +192,35 @@ export interface DoctorPayload {
    * concern's health is already read, so this is where the number belongs.
    */
   turn_end_refusals: RefusalStats;
+  /**
+   * The obligation ledger's two readiness figures.
+   *
+   * Reported here and nowhere else, because the doctor is where a concern's
+   * health is already read and the ledger's failure mode is silence: it never
+   * throws, never refuses and never fails a turn, so an unwritable ledger
+   * looks exactly like a session that triggered no rules. These two lines are
+   * the difference between those, and they are the ONLY consumer the ledger
+   * has — reporting a count is not acting on the rows.
+   */
+  obligation_ledger: ObligationLedgerStats;
   /** The machine's install stamp, for reading the version split below it. */
   install_boundary: InstallBoundary;
 }
 
+/** What the doctor can say about the ledger without interpreting a single row. */
+export interface ObligationLedgerStats {
+  /** Probed by writing and removing a sentinel, not by reading mode bits. */
+  writable: boolean;
+  /**
+   * Rows for THIS session, or `null` when no session id was resolvable.
+   *
+   * `null` and `0` are different answers and are rendered differently: `0`
+   * means this session was delivered no rule, `null` means the doctor could
+   * not tell which session it is in and so has nothing to count.
+   */
+  rows_this_session: number | null;
+}
+
 /** Build the doctor payload — JSON-serialisable. */
 export function collect(
   project_root: string,
@@ -288,10 +314,67 @@ export function collect(
     trampolines,
     dispatch_issues: issues,
     turn_end_refusals,
+    obligation_ledger: collectLedgerStats(project_root),
     install_boundary: readInstallBoundary(),
   };
 }
 
+/**
+ * The ledger's two figures, never throwing.
+ *
+ * The session id comes from the host's own environment variable, which is the
+ * same source the concerns key their state on. Absent means the doctor is
+ * being run outside a session — by a human at a shell, most often — and the
+ * honest answer is `null` rather than 0, because there is no session whose
+ * rows could be counted.
+ */
+export function collectLedgerStats(project_root: string): ObligationLedgerStats {
+  let writable = false;
+  try {
+    writable = ledgerWritable(project_root);
+  } catch {
+    writable = false;
+  }
+  const session = (process.env["CLAUDE_CODE_SESSION_ID"] ?? "").trim();
+  if (session === "") return { writable, rows_this_session: null };
+  try {
+    return { writable, rows_this_session: readDelivered(project_root, session).length };
+  } catch {
+    return { writable, rows_this_session: null };
+  }
+}
+
+/**
+ * The ledger section.
+ *
+ * Deliberately states what a row is NOT. The council lock this ledger sits
+ * under says installation proves availability and not exposure, so a reader
+ * who sees a healthy row count and concludes the rules were followed has made
+ * the one claim these records may never support. The line is cheap; the
+ * misreading it prevents is the whole reason the ledger needed a non-goal.
+ */
+export function _render_ledger(payload: DoctorPayload): string[] {
+  const s = payload.obligation_ledger;
+  const lines: string[] = [];
+  lines.push("Obligation ledger");
+  lines.push("-".repeat(60));
+  lines.push(
+    `${s.writable ? "✅ " : "❌ "}writable  ${
+      s.writable ? "agents/runtime/state/obligations/" : "cannot write agents/runtime/state/obligations/"
+    }`,
+  );
+  if (s.rows_this_session === null) {
+    lines.push("·  rows this session: no session id resolved — nothing to count");
+  } else {
+    lines.push(`·  rows this session: ${s.rows_this_session}`);
+  }
+  lines.push(
+    "   Rows record that an emitter ran. They are not evidence that a rule",
+  );
+  lines.push("   reached the model, and may not be read as compliance.");
+  return lines;
+}
+
 function _strVal(v: JsonValue | undefined): string {
   return v === undefined || v === null ? "undefined" : String(v);
 }
@@ -415,6 +498,8 @@ export function _render_table(payload: DoctorPayload): string {
   }
   lines.push("");
   lines.push(..._render_refusals(payload));
+  lines.push("");
+  lines.push(..._render_ledger(payload));
   // Dispatch-issues detail — last 20 grouped by concern.
   if (payload.dispatch_issues.length > 0) {
     lines.push("");

package/src/scripts/hooks_status.ts

@@ -73,11 +73,22 @@ export const PLATFORM_BRIDGES: Record<string, [string, string]> = {
   copilot: ["", "rule-only fallback — this package binds no hook here"],
 };
 
+/** The shape of a host's user-facing question primitive. */
+export type AskShape = "native" | "text";
+
 export interface PlatformRow {
   platform: string;
   status: string;
   bridge_path: string | null;
   fallback_only: boolean;
+  /**
+   * DECLARED in the manifest, never probed. A host with no row reads `text`:
+   * the conservative answer, and the one that is true of every host that has
+   * not said otherwise. Absent must not read as "unknown" here — an unknown
+   * that the contract then treats as native is exactly the silent degrade the
+   * row exists to prevent.
+   */
+  ask: AskShape;
   bindings: Record<string, string[]>;
   hint: string | null;
 }
@@ -122,6 +133,7 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
     const blockRaw = platforms[platform];
     const block = _isObject(blockRaw) ? blockRaw : {};
     const fallback_only = Boolean(block["fallback_only"]);
+    const ask: AskShape = block["ask"] === "native" ? "native" : "text";
     const bindings: Record<string, string[]> = {};
     if (!fallback_only) {
       for (const [ev, c] of Object.entries(block)) {
@@ -138,6 +150,7 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
       status,
       bridge_path: rel || null,
       fallback_only,
+      ask,
       bindings,
       hint: ["missing", "empty", "degraded", "n/a"].includes(status)
         ? hint
@@ -166,6 +179,12 @@ export function _render_table(matrix: StatusMatrix): string {
       head += `  (${row.bridge_path})`;
     }
     lines.push(head);
+    lines.push(
+      `    ask                    → ${row.ask}` +
+        (row.ask === "native"
+          ? "  (structured-ask tool; the recommendation is its default option)"
+          : "  (numbered text block — the fallback, and it says so)"),
+    );
     if (row.fallback_only) {
       lines.push(
         "    degraded: rule-only fallback " +