@event4u/agent-config 15.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/review_baseline_hook.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * review-baseline — `session_start` concern
+ * (road-to-a-question-that-survives-the-turn Phase 2).
+ *
+ * WHAT IT DOES, and it is the whole of it: on session start, record how many
+ * non-doc lines were ALREADY dirty, and what HEAD was. `end-review-nudge`
+ * subtracts that at `stop` so a session is charged for its own mutation instead
+ * of for whatever the working tree happened to be carrying.
+ *
+ * THE DEFECT IT CLOSES. `end_review_nudge_hook`'s own header names it: a dirty
+ * tree that predates the session is counted as the session's, and the reason it
+ * was not fixed was "no such baseline exists anywhere a `stop` concern can read
+ * it". That was true of a phase with a one-concern scope, and stale by the time
+ * it mattered — `session_start` is bound on seven hosts carrying fourteen
+ * concerns. The measured consequence of leaving it: on a branch deliberately
+ * accumulating work, the nudge read 1,771 lines of two crashed sessions'
+ * uncommitted work and fired every turn. An advisory that always fires is noise,
+ * and noise is worse than silence because it trains the reader to skip the one
+ * that mattered.
+ *
+ * MEASURED WITH THE READER'S OWN INSTRUMENT. `totalNonDocMutatedLinesWithMeasure`
+ * is imported from the nudge rather than reimplemented, so the two sides cannot
+ * drift on what a "non-doc mutated line" is. A second counting implementation
+ * would produce a baseline in one unit and a measurement in another, and the
+ * subtraction would be silently wrong rather than visibly broken.
+ *
+ * CAPTURE ONLY. It never emits context, never warns, and always returns 0. A
+ * `session_start` concern that could refuse would turn an unreadable git
+ * directory into a session that cannot start, which is a far worse failure than
+ * the noise it is fixing.
+ *
+ * NO PATHS, NO FINGERPRINTS. The record is two numbers and a timestamp. A
+ * path-level change set was the shape the source draft proposed; it is a bigger
+ * object with a bigger privacy surface, and nothing in the nudge consumes one.
+ * The file cannot hold a path, a diff or a file body by construction, which is
+ * the same PII-exclusion-by-construction the telemetry record keeps.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    baselineStateFile,
+    currentHeadSha,
+    type ReviewBaseline,
+} from '../_lib/review_baseline.js';
+import { deriveSessionKey, totalNonDocMutatedLinesWithMeasure } from './end_review_nudge_hook.js';
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { atomic_write_json } from './state_io.js';
+
+const EXIT_OK = 0;
+
+export function buildBaseline(workspaceRoot: string, now: Date = new Date()): ReviewBaseline {
+    const measured = totalNonDocMutatedLinesWithMeasure(workspaceRoot);
+    return {
+        head_sha: currentHeadSha(workspaceRoot),
+        baseline_lines: measured.lines,
+        // Carried, not discarded. Past `UNTRACKED_FILE_CAP` the count is a
+        // synthetic `THRESHOLD + 1 + tracked` chosen to be over the bar rather
+        // than to be true, and subtracting that from a later exact count is
+        // arithmetic over two different quantities. The consumer refuses the
+        // subtraction when the two measures disagree; it can only do that if the
+        // writer says which one it took.
+        measure: measured.measure,
+        written_at: now.toISOString(),
+    };
+}
+
+export function main(): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_OK;
+    }
+
+    const event = String(envelope['event'] ?? '');
+    if (event !== '' && event !== 'session_start') return EXIT_OK;
+
+    const workspaceRoot =
+        String((envelope['workspace_root'] as JsonValue | undefined) ?? '').trim() || process.cwd();
+
+    // A baseline is written ONCE per session. A host that fires session_start
+    // twice — Cline maps both TaskStart and TaskResume onto it — must not
+    // re-baseline mid-session: the second write would fold everything the
+    // session had already changed into its own baseline and the nudge would go
+    // permanently quiet for that session. Over-writing is the silent failure
+    // direction, so it is the one guarded.
+    const sessionKey = deriveSessionKey(envelope, payload);
+    const file = baselineStateFile(workspaceRoot, sessionKey);
+    try {
+        if (fs.existsSync(file)) return EXIT_OK;
+    } catch {
+        return EXIT_OK;
+    }
+
+    try {
+        // `atomic_write_json` is already `AGENT_CONFIG_REPLAY`-aware, so a
+        // fixture-replay run leaves no baseline behind.
+        atomic_write_json(file, buildBaseline(workspaceRoot) as unknown as JsonObject);
+    } catch {
+        // An unwritable state dir degrades to today's behaviour — the nudge
+        // reads `absent` and does not subtract. Never a failed session start.
+    }
+    return EXIT_OK;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    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