@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/hooks/concern_registry.ts

@@ -69,10 +69,12 @@ import { main as delegationNudgeMain } from './delegation_nudge_hook.js';
 import { main as skillRouteMain } from './skill_route_hook.js';
 import { main as ruleInjectMain } from './rule_inject_hook.js';
 import { main as endReviewNudgeMain } from './end_review_nudge_hook.js';
+import { main as reviewBaselineMain } from './review_baseline_hook.js';
 import { main as turnEndGateMain } from './turn_end_gate_hook.js';
 import { main as editShapeMain } from './edit_shape_hook.js';
 import { main as commentDisciplineMain } from './comment_discipline_hook.js';
 import { main as rereadGuardMain } from './reread_guard_hook.js';
+import { main as memoryRecallMain } from './memory_recall_hook.js';
 import { main as sessionEolMain } from './session_eol_hook.js';
 import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
 import { main as toolResultBytesMain } from './tool_result_bytes_hook.js';
@@ -81,6 +83,7 @@ import { main as sourceFirstGateMain } from './source_first_gate_hook.js';
 import { main as interruptionLedgerMain } from './interruption_ledger_hook.js';
 import { main as runContinuationMain } from './run_continuation_hook.js';
 import { main as journalRecordMain } from './journal_record_hook.js';
+import { main as obligationSettleMain } from './obligation_settle_hook.js';
 
 /** A concern `main` — argv-taking or not; both shapes exist. */
 export type ConcernMain = (argv?: string[]) => number | undefined | void;
@@ -132,10 +135,13 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/skill_route_hook.ts': skillRouteMain as ConcernMain,
     'src/scripts/hooks/rule_inject_hook.ts': ruleInjectMain as ConcernMain,
     'src/scripts/hooks/end_review_nudge_hook.ts': endReviewNudgeMain as ConcernMain,
+    'src/scripts/hooks/obligation_settle_hook.ts': obligationSettleMain as ConcernMain,
+    'src/scripts/hooks/review_baseline_hook.ts': reviewBaselineMain as ConcernMain,
     'src/scripts/hooks/turn_end_gate_hook.ts': turnEndGateMain as ConcernMain,
     'src/scripts/hooks/edit_shape_hook.ts': editShapeMain as ConcernMain,
     'src/scripts/hooks/comment_discipline_hook.ts': commentDisciplineMain as ConcernMain,
     'src/scripts/hooks/reread_guard_hook.ts': rereadGuardMain as ConcernMain,
+    'src/scripts/hooks/memory_recall_hook.ts': memoryRecallMain as ConcernMain,
     'src/scripts/hooks/session_eol_hook.ts': sessionEolMain as ConcernMain,
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
     'src/scripts/hooks/tool_result_bytes_hook.ts': toolResultBytesMain as ConcernMain,

package/src/scripts/hooks/design_pass_hook.ts

@@ -56,6 +56,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { appendDischarge, stamp } from '../_lib/obligations.js';
 import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
 import { loadDesignContext, scanFile } from '../lint_design_slop.js';
 import { readHookStdin } from './hook_stdin.js';
@@ -65,6 +66,7 @@ const EXIT_WARN = 2;
 const SETTINGS_FILE = '.agent-settings.yml';
 const STATE_REL = path.join('agents', 'runtime', 'state', 'design-pass-hook.json');
 const AUDIT_REL = path.join('agents', 'runtime', 'state', 'ui-audit.json');
+const CONFORMANCE_REL = path.join('agents', 'runtime', 'state', 'ui-conformance.json');
 
 /**
  * The P0 set — objective floors only, and the list is closed on purpose.
@@ -128,6 +130,77 @@ export function enabled(root: string, key = 'design_pass'): boolean {
 
 export const isUiSurface = (p: string): boolean => isUiPath(p) || isUiTreePath(p);
 
+/**
+ * The shadow read of `ui-conformance.json` — Phase 5 of
+ * `road-to-behaviour-evidence-over-pixels`.
+ *
+ * SHADOW MEANS SHADOW. This produces a line in the reported verdict and
+ * touches nothing else: it is not consulted by `decide`, never reaches
+ * `blocked`, and cannot change an exit code. The roadmap adds evidence, not
+ * enforcement, and the block path is deliberately untouched by this change.
+ *
+ * An ABSENT artefact is reported as absent, never as clean — the same rule the
+ * probe applies to its own dimensions. A malformed one is reported as
+ * unreadable for the same reason.
+ */
+export interface ConformanceVerdict {
+    /**
+     * Whether this verdict is worth surfacing on its own. An ABSENT artefact is
+     * not: most repositories never run the probe, and a line on every clean UI
+     * write is the noise that gets a carrier switched off — Risk 1 of the parent
+     * roadmap. Absent is still reported honestly whenever the pass speaks for
+     * another reason.
+     */
+    noteworthy: boolean;
+    line: string;
+}
+
+export function conformanceVerdict(root: string): ConformanceVerdict {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(path.join(root, CONFORMANCE_REL), 'utf-8');
+    } catch {
+        return {
+            noteworthy: false,
+            line: 'ui-conformance: absent — no probe artefact for this change (run `ui_conformance_probe --target <file> --reference <file>`). Absent is not clean.',
+        };
+    }
+    try {
+        const a = JSON.parse(raw) as {
+            structure_gate?: string;
+            dimensions?: { dimension: string; status: string; findings: number | null; reason?: string }[];
+            findings?: unknown[];
+        };
+        const rows = a.dimensions ?? [];
+        const exercised = rows.filter((r) => r.status === 'exercised');
+        const notApplicable = rows.filter((r) => r.status !== 'exercised');
+        const counts = exercised.map((r) => `${r.dimension}=${r.findings}`).join(' ');
+        const parts = [
+            `ui-conformance: ${(a.findings ?? []).length} behavioural finding(s) — ${counts || 'no dimension exercised'}`,
+        ];
+        if (notApplicable.length) {
+            parts.push(
+                `  · not applicable: ${notApplicable
+                    .map((r) => `${r.dimension} (${r.reason ?? 'no reason given'})`)
+                    .join('; ')}`,
+            );
+        }
+        if (a.structure_gate === 'stopped') {
+            parts.push('  · structure gate stopped on at least one node — style comparison was skipped for it');
+        }
+        parts.push('  (shadow verdict: reported, never enforced — this pass does not block on it)');
+        return {
+            noteworthy: (a.findings ?? []).length > 0 || a.structure_gate === 'stopped' || notApplicable.length > 0,
+            line: parts.join('\n'),
+        };
+    } catch {
+        return {
+            noteworthy: true,
+            line: 'ui-conformance: unreadable — the artefact exists but did not parse. Reported rather than ignored.',
+        };
+    }
+}
+
 /**
  * E2.2 — is the audit artefact newer than the target?
  *
@@ -135,6 +208,43 @@ export const isUiSurface = (p: string): boolean => isUiPath(p) || isUiTreePath(p
  * because it looks like evidence. An artefact older than the file it is
  * supposed to describe has not seen the change.
  */
+/**
+ * Record that the UI-audit obligation was discharged, when it was.
+ *
+ * This concern is the only thing in the tree that knows. It already decides
+ * audit freshness for its own advisory line; until now that decision was spent
+ * on one message and thrown away, so a turn-end reader asking "was the audit
+ * done?" had to re-derive a verdict it does not own. The decision existed —
+ * only the write was missing.
+ *
+ * Discharged means: at least one target was touched AND every one of them has
+ * a fresh audit. A partial pass records nothing, because `ui-audit-gate`'s
+ * obligation is about the surfaces this turn wrote, not about a quorum of them.
+ *
+ * NO PER-WRITE VALIDATOR IS ADDED. The write is one small append behind the
+ * same lock the ledger already uses, on a path that has an mtime comparison in
+ * front of it — deliberately, because this concern sits on `post_tool_use`,
+ * the hottest slot it binds, and a validation pass per write is exactly the
+ * cost the phase forbids.
+ */
+export function recordAuditDischarge(
+    root: string,
+    targets: readonly string[],
+    auditMissing: readonly string[],
+): void {
+    if (targets.length === 0 || auditMissing.length > 0) return;
+    const session = (process.env["CLAUDE_CODE_SESSION_ID"] ?? "").trim();
+    if (session === "") return;
+    try {
+        appendDischarge(root, session, [
+            { rule: "ui-audit-gate", by: "design-pass", at: stamp() },
+        ]);
+    } catch {
+        // A discharge that cannot be recorded is a missing reading, never a
+        // reason to fail the write that prompted it.
+    }
+}
+
 export function auditIsFresh(root: string, target: string): boolean {
     try {
         const a = fs.statSync(path.join(root, AUDIT_REL)).mtimeMs;
@@ -252,7 +362,7 @@ export function targetPath(payload: unknown): string | null {
     return null;
 }
 
-export function render(result: PassResult): string {
+export function render(result: PassResult, conformance?: string): string {
     const lines: string[] = [];
     if (result.blocked.length) {
         lines.push(
@@ -272,6 +382,9 @@ export function render(result: PassResult): string {
         lines.push(`  · no ui-audit.json newer than ${m} — run \`agent-config ui:audit <path>\``);
     lines.push(`verification: ${result.verification}`);
     if (result.degradation_reason) lines.push(`degradation_reason: ${result.degradation_reason}`);
+    // Appended last and never consulted above: the conformance verdict is a
+    // report, not an input to any decision this pass makes.
+    if (conformance) lines.push(conformance);
     return lines.join('\n');
 }
 
@@ -329,6 +442,7 @@ function main(): number {
     }
 
     const auditMissing = targets.filter((t) => !auditIsFresh(root, t));
+    recordAuditDischarge(root, targets, auditMissing);
     let result = decide(slot, findings, auditMissing, new Set(state.surfaced), renderAvailable(root));
     if (scanFailed) {
         result = { ...result, verification: 'unverified', degradation_reason: `detector unavailable: ${scanFailed}` };
@@ -338,11 +452,22 @@ function main(): number {
     if (slot === 'stop') state.touched = [];
     writeState(root, state);
 
-    if (!result.findings.length && !result.audit_missing.length && result.verification === 'verified') {
+    // Shadow mount. The verdict can make the pass SPEAK when it would otherwise
+    // be silent — a behavioural finding is exactly the thing no static scan can
+    // see — but it cannot make it refuse. `result.blocked` above is computed
+    // without it and the exit code below is unchanged.
+    const conformance = conformanceVerdict(root);
+
+    if (
+        !result.findings.length &&
+        !result.audit_missing.length &&
+        result.verification === 'verified' &&
+        !conformance.noteworthy
+    ) {
         return EXIT_ALLOW;
     }
 
-    process.stdout.write(`${JSON.stringify({ reason: render(result) })}\n`);
+    process.stdout.write(`${JSON.stringify({ reason: render(result, conformance.line) })}\n`);
     // Deliberately EXIT_WARN even with a P0 verdict. EXIT_BLOCK is unreachable
     // for an advisory concern (the dispatcher downgrades it), so returning it
     // would claim a refusal the transport discards.

package/src/scripts/hooks/end_review_nudge_hook.ts

@@ -28,17 +28,26 @@
  * (`git ls-files --others --exclude-standard`, each one READ from the
  * filesystem rather than diffed in a subprocess — see "Untracked files" below;
  * fixes a review finding, F6, that a brand-new file was previously invisible
- * to this count entirely). Chosen over a session-start SHA/timestamp
- * baseline because no such baseline exists anywhere a `stop` concern can
- * read it (recording one would be new session-wide state, out of this
- * roadmap phase's one-concern scope). Two consequences, stated rather than
- * hidden:
- *   - Uncommitted changes that PREDATE this session (a dirty working tree
- *     the user already had) are counted as if they were this session's
- *     mutation. Per `commit-policy`, an agent almost never commits without
- *     explicit permission, so "uncommitted since HEAD" is usually a good
- *     proxy for "mutated this session" in practice — but it is a proxy, not
- *     an exact measure.
+ * to this count entirely).
+ *
+ * SINCE 2026-09-11 THIS READING IS BASELINE-CORRECTED ON `claude`, and this
+ * block used to say the opposite — that a session-start baseline was rejected
+ * "because no such baseline exists anywhere a `stop` concern can read it". That
+ * was true of a one-concern roadmap phase and stale by the time it mattered:
+ * `session_start` is bound on seven hosts, and `review-baseline` now records
+ * HEAD plus the already-dirty non-doc line count there. `_lib/review_baseline.ts`
+ * cites this paragraph as the defect it closes, so leaving the paragraph
+ * standing would have made the two files contradict each other.
+ *
+ * What the correction does and does not cover:
+ *   - Uncommitted changes that PREDATE the session are SUBTRACTED where a
+ *     baseline is readable and its HEAD and measure still match. Absent,
+ *     unreadable, head-moved or mixed-measure → the unsubtracted count, with
+ *     the reason carried in the `review_skipped` row.
+ *   - The baseline is written once per session and never refreshed, so from a
+ *     session's first commit onward `head-moved` holds and the pre-existing
+ *     tree is charged again. Over-reporting is the safe direction; the limit is
+ *     real and is stated in `review_baseline.ts` rather than implied away.
  *   - A session that DID commit mid-turn (one of `commit-policy`'s four
  *     exceptions) moves HEAD, so mutations already committed are invisible
  *     to this diff. Declared, not silently assumed away.
@@ -207,11 +216,20 @@
  * exit-2 warn onto an unverified propagation path is exactly the
  * speculative mapping `host_semantics.ts` exists to avoid.
  *
- * CONTRACT: never blocks THE ACTUAL TURN. The DISPATCHER-INTERNAL exit is 2
- * on a fire (never 1/BLOCK, never >=3), `fail_closed: false`; the HOST-FACING
- * exit on `claude` is 0 either way, per the proof above. Doc-only
- * diffs, a reviewer having run, or any unreadable/malformed input all
- * resolve to silence (dispatcher-internal exit 0), not a crash.
+ * CONTRACT: never REFUSES a turn. The DISPATCHER-INTERNAL exit is 2 on a fire
+ * (never 1/BLOCK, never >=3), `fail_closed: false`; the HOST-FACING exit on
+ * `claude` is 0 either way, per the proof above. Doc-only diffs, a reviewer
+ * having run, or any unreadable/malformed input all resolve to silence
+ * (dispatcher-internal exit 0), not a crash.
+ *
+ * WHAT THE PROOF ABOVE DOES NOT COVER. Every term of it is an exit code, so it
+ * settles refusal and nothing else. Whether the `additionalContext` payload
+ * this concern emits at `stop` causes the host to run the agent AGAIN is a
+ * separate question, and this tree does not answer it — see
+ * `docs/contracts/hook-architecture-v1.md` under the exit-code table, which
+ * names the measurement that would. So do not read the proof above as
+ * establishing that this concern leaves the turn alone; it establishes only
+ * that the concern never refuses it.
  */
 import { spawnSync } from 'node:child_process';
 import * as crypto from 'node:crypto';
@@ -220,7 +238,18 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { buildReviewSkippedLine, type MutationMeasure } from '../_lib/review_skipped_record.js';
+import {
+    applyBaseline,
+    currentHeadSha,
+    readBaseline,
+    type BaselineFallback,
+    type BaselineOutcome,
+} from '../_lib/review_baseline.js';
+import {
+    buildReviewSkippedLine,
+    type BaselineApplication,
+    type MutationMeasure,
+} from '../_lib/review_skipped_record.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
@@ -606,6 +635,7 @@ export function appendReviewSkippedTelemetry(
     workspaceRoot: string,
     diffLines: number,
     mutationMeasure: MutationMeasure,
+    baseline?: BaselineApplication,
 ): void {
     if (is_replay_mode()) return;
     const ts = new Date().toISOString();
@@ -614,6 +644,7 @@ export function appendReviewSkippedTelemetry(
         mutation_measure: mutationMeasure,
         ts,
         id: crypto.randomUUID(),
+        baseline,
     });
     if (errors.length || line === null) return; // refused input — never write a broken line
     try {
@@ -694,6 +725,23 @@ function _read_stdin(): string {
     return readHookStdin();
 }
 
+/**
+ * The one place the two spellings meet.
+ *
+ * `BaselineFallback` is kebab-cased because it is a TypeScript union read only
+ * in this process; `BaselineApplication` is snake_cased because it is written
+ * into an audit line and every other enum in that stream is. A hand-written
+ * ternary translated them until a review pointed out that `head-moved` and
+ * `head_moved` differ by one character in a conditional nobody would re-read —
+ * an exhaustive record makes a new fallback a compile error instead.
+ */
+const FALLBACK_TO_TELEMETRY: Readonly<Record<BaselineFallback, BaselineApplication>> = {
+    absent: 'absent',
+    unreadable: 'unreadable',
+    'head-moved': 'head_moved',
+    'mixed-measure': 'mixed_measure',
+};
+
 export function main(): number {
     const [envelope, payload] = unwrap(_read_stdin(), 'claude');
 
@@ -705,15 +753,43 @@ export function main(): number {
     const workspace_root =
         String(envelope['workspace_root'] ?? '').trim() || process.cwd();
 
-    let diffLines: number;
+    let measuredLines: number;
     let mutationMeasure: MutationMeasure;
     try {
         const measured = totalNonDocMutatedLinesWithMeasure(workspace_root);
-        diffLines = measured.lines;
+        measuredLines = measured.lines;
         mutationMeasure = measured.measure;
     } catch {
         return 0; // fail-open — never block the agent loop
     }
+
+    // The session key is derived HERE rather than after the threshold test,
+    // because the threshold is now taken on the SUBTRACTED count and the
+    // baseline is keyed on the session. That is a real reordering: one extra
+    // `sha256` of a string and one `readFileSync` of a ~100-byte JSON file now
+    // run on every stop, including the majority that end below threshold. The
+    // alternative — testing the unsubtracted count first as a cheap
+    // pre-filter — is wrong in the one direction that matters: on an
+    // accumulator branch EVERY turn clears the unsubtracted threshold, so the
+    // pre-filter would pass exactly when the subtraction is needed and save
+    // nothing.
+    const sessionKey = deriveSessionKey(envelope, payload);
+    const baselineOutcome: BaselineOutcome = applyBaseline(
+        measuredLines,
+        readBaseline(workspace_root, sessionKey),
+        // A THUNK, not a value: on the `absent` and `unreadable` branches the
+        // result is discarded, and those two are the steady state on every host
+        // without this nudge and on every session before its first baseline
+        // write. Passing the value eagerly spent an 11-14 ms `git rev-parse` on
+        // each of those stops for nothing.
+        () => currentHeadSha(workspace_root),
+        mutationMeasure,
+    );
+    const diffLines = baselineOutcome.lines;
+    const baselineApplication: BaselineApplication = baselineOutcome.applied
+        ? 'applied'
+        : FALLBACK_TO_TELEMETRY[baselineOutcome.fallback];
+
     if (diffLines <= MUTATION_LINE_THRESHOLD) {
         return 0; // below threshold, or a doc-only diff — nothing to nudge
     }
@@ -723,7 +799,6 @@ export function main(): number {
     // JSON parse below. A session that already fired stops here, at a
     // single `fs.existsSync` call, without re-reading a (potentially
     // large) transcript file it already knows the answer for.
-    const sessionKey = deriveSessionKey(envelope, payload);
     if (hasFiredThisSession(workspace_root, sessionKey)) {
         return 0;
     }
@@ -756,7 +831,12 @@ export function main(): number {
     markFiredThisSession(workspace_root, sessionKey, new Date().toISOString());
 
     try {
-        appendReviewSkippedTelemetry(workspace_root, diffLines, mutationMeasure);
+        appendReviewSkippedTelemetry(
+            workspace_root,
+            diffLines,
+            mutationMeasure,
+            baselineApplication,
+        );
     } catch {
         // never let a telemetry failure block or fail the turn
     }

package/src/scripts/hooks/evidence_independence.ts

@@ -43,6 +43,7 @@
  *
  * Exit codes: 0 allow · 2 block (stderr carries the reason).
  */
+import { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -50,6 +51,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { atomic_write_json } from "./state_io.js";
 import { readHookStdin } from "./hook_stdin.js";
+import { isCodePath, isTestPath } from "../_lib/test_delta.js";
 
 const EXIT_ALLOW = 0;
 // MUST equal dispatch_hook.EXIT_BLOCK. The dispatcher's internal ladder is
@@ -324,6 +326,79 @@ export function decide(
   };
 }
 
+/**
+ * The one-commit test-authorship flag —
+ * `road-to-adversarial-verification-and-long-runs` 2.4, third clause.
+ *
+ * A commit staging BOTH a test and code it could cover is the shape of L0 on the
+ * independence scale — the implementer wrote the evaluator — and it is the one
+ * case nobody sees, because the diff looks exactly like a well-tested change.
+ *
+ * **It reads the STAGED SET and the command, and nothing else.** It does NOT
+ * read a session id, an author or a timestamp, so it cannot distinguish an
+ * implementer who wrote both from one committing a test another session authored
+ * — an independent review of this function caught an earlier docstring here
+ * claiming a session boundary the code never reads, which is exactly the
+ * over-claim `evaluator-independence` exists over. The honest reading is: this
+ * is the shape L0 takes in a diff, surfaced so the level is stated rather than
+ * inferred.
+ *
+ * **WARN, never block.** L0 is explicitly permitted as a fallback, so refusing it
+ * would forbid a legal state; and a signal this coarse may surface, never refuse.
+ *
+ * Returns `null` when nothing is worth saying — i.e. this is not a commit.
+ */
+export function sameSessionTestFlag(command: string | null): string | null {
+  if (command === null || !/\bgit\b[^|;&]*\bcommit\b/.test(command)) return null;
+  return SAME_SESSION_TEXT;
+}
+
+const SAME_SESSION_TEXT =
+  "This commit stages both a test and code it could cover — the shape L0 takes " +
+  "in a diff, where the implementer authored the evaluator. This check reads the " +
+  "staged set only: it cannot tell who wrote the test, so it is a prompt to STATE " +
+  "the level, not a finding that you are at L0. L0 is a permitted FALLBACK, not " +
+  "the default: where a second session, a second model or a second provider was " +
+  "available, the test should have come from one of them. Say which in the commit " +
+  "or the PR body — a diff looks identical either way. See evaluator-independence " +
+  "§ Tests are evaluators.";
+
+/** Both a test path and a production path in one changed set. */
+export function touchesTestAndCode(paths: readonly string[]): boolean {
+  return paths.some(isTestPath) && paths.some(isCodePath);
+}
+
+/** The shell command this envelope is about, across the key names hosts use. */
+function _commandOf(envelope: JsonObject): string | null {
+  const payload = _isObject(envelope["payload"]) ? envelope["payload"] : envelope;
+  const input = _isObject(payload["tool_input"]) ? payload["tool_input"] : payload;
+  for (const key of ["command", "cmd", "shell_command"]) {
+    const v = input[key];
+    if (typeof v === "string" && v !== "") return v;
+  }
+  return null;
+}
+
+/**
+ * Staged paths, or `null` when git cannot answer.
+ *
+ * `null` is not "nothing staged" — it is "no reading", and the caller must not
+ * turn an unreadable index into a silent clean bill. A hook that cannot measure
+ * says nothing rather than implying a measurement.
+ */
+function _stagedPaths(consumer_root: string): string[] | null {
+  const r = spawnSync("git", ["diff", "--cached", "--name-only"], {
+    cwd: consumer_root,
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return null;
+  const out = r.stdout
+    .split("\n")
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+  return out.length === 0 ? null : out;
+}
+
 export function run(stdin_text: string, options: { consumer_root: string }): number {
   let envelope: JsonObject = {};
   if (stdin_text.trim()) {
@@ -355,6 +430,27 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
   }
 
   const [tool, prompt] = extractDispatch(envelope);
+
+  // 2.4 — the one-commit test-authorship flag, checked BEFORE the dispatch
+  // branch and returning early. A commit envelope carries no evaluation prompt,
+  // so `decide` would classify it as not-an-evaluation and allow it silently;
+  // running both would mean the commit path fell through to a counter that is
+  // about evaluation dispatches and would be wrong to advance here.
+  //
+  // CHEAP TEST FIRST, and that ordering is the finding rather than a style
+  // preference: `_stagedPaths` spawns `git diff --cached`, and this concern is
+  // bound on `pre_tool_use`, so reading the index before the regex made every
+  // Read, Edit, Grep and Task dispatch in every session pay a subprocess. The
+  // regex answers "is this even a commit" for free.
+  const flag = sameSessionTestFlag(_commandOf(envelope));
+  if (flag !== null) {
+    const staged = _stagedPaths(options.consumer_root);
+    if (staged !== null && touchesTestAndCode(staged)) {
+      process.stdout.write(`${JSON.stringify({ decision: "warn", reason: flag })}\n`);
+      return EXIT_ALLOW;
+    }
+  }
+
   const decision = decide(tool, prompt, state.evaluations.length);
 
   if (decision.evaluations > state.evaluations.length) {