@event4u/agent-config 13.0.0 → 14.0.0

package/src/scripts/hooks/concern_registry.ts

@@ -32,6 +32,7 @@ import { main as onboardingGateMain } from '../onboarding_gate_hook.js';
 import { main as contextHygieneMain } from '../context_hygiene_hook.js';
 import { main as verifyBeforeCompleteMain } from '../before_complete_hook.js';
 import { main as minimalSafeDiffMain } from '../minimal_safe_diff_hook.js';
+import { main as shipDiffVolumeMain } from './ship_diff_volume_hook.js';
 import { main as injectionScanMain } from '../injection_scan_hook.js';
 import { main as memoryLearnMain } from '../memory_learn_hook.js';
 import { main as firstRunGateMain } from '../first_run_gate_hook.js';
@@ -66,6 +67,7 @@ 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';
 import { main as spawnGuardShadowMain } from './spawn_guard_shadow_hook.js';
+import { main as interruptionLedgerMain } from './interruption_ledger_hook.js';
 
 /** A concern `main` — argv-taking or not; both shapes exist. */
 export type ConcernMain = (argv?: string[]) => number | undefined | void;
@@ -80,6 +82,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/context_hygiene_hook.ts': contextHygieneMain as ConcernMain,
     'src/scripts/before_complete_hook.ts': verifyBeforeCompleteMain as ConcernMain,
     'src/scripts/minimal_safe_diff_hook.ts': minimalSafeDiffMain as ConcernMain,
+    'src/scripts/hooks/ship_diff_volume_hook.ts': shipDiffVolumeMain as ConcernMain,
     'src/scripts/injection_scan_hook.ts': injectionScanMain as ConcernMain,
     'src/scripts/memory_learn_hook.ts': memoryLearnMain as ConcernMain,
     'src/scripts/first_run_gate_hook.ts': firstRunGateMain as ConcernMain,
@@ -114,4 +117,5 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
     'src/scripts/hooks/tool_result_bytes_hook.ts': toolResultBytesMain as ConcernMain,
     'src/scripts/hooks/spawn_guard_shadow_hook.ts': spawnGuardShadowMain as ConcernMain,
+    'src/scripts/hooks/interruption_ledger_hook.ts': interruptionLedgerMain as ConcernMain,
 };

package/src/scripts/hooks/dispatch_hook.ts

@@ -342,16 +342,51 @@ export function _role_drop_set(
   return new Set(drop.filter((d): d is string => typeof d === "string"));
 }
 
+/**
+ * True when this `stop` is the RETRY of a turn a stop-hook already refused.
+ *
+ * The host sets `stop_hook_active` on exactly that Stop; `turn_end_gate_hook`
+ * reads the same field as its layer-1 re-entrancy guard, so this is the host's
+ * own answer rather than an inference of ours. Anything unparseable is `false`,
+ * which is the full chain — the safe direction, since the cost of running a
+ * concern twice is duplicate work and the cost of skipping one wrongly is a lost
+ * write.
+ */
+export function _is_refusal_retry(event: string, payload_text: string): boolean {
+  if (event !== "stop") return false;
+  try {
+    const parsed: unknown = JSON.parse(payload_text);
+    if (!_isObject(parsed)) return false;
+    const payload = parsed["payload"];
+    const source = _isObject(payload) ? payload : parsed;
+    return source["stop_hook_active"] === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Return the ordered concern definitions for (platform, event) under the
  * given session role (default `orchestrator` — byte-identical to the
  * pre-role-axis behaviour).
+ *
+ * `opts.refusal_retry` drops concerns that opted in with
+ * `skip_on_refusal_retry: true` — `road-to-stop-gate-honesty` step 3.1. Stop is
+ * the heaviest slot on claude and **every refused Stop runs the whole slot again
+ * on the retry** (§ D-3), so the concerns whose second run provably produces the
+ * identical artefact are pure duplicate cost.
+ *
+ * Opt-in per concern, default off, never a blanket skip: Risk 3 of that roadmap
+ * is that a concern skipped on the retry might have been the one that needed the
+ * second pass, and the loss would be silent. The manifest carries the per-concern
+ * argument beside each flag.
  */
 export function _resolve_concerns(
   manifest: JsonObject,
   platform: string,
   event: string,
   role: SessionRole = "orchestrator",
+  opts: { refusal_retry?: boolean } = {},
 ): ConcernDef[] {
   const platformsRaw = manifest["platforms"];
   const platforms = _isObject(platformsRaw) ? platformsRaw : {};
@@ -381,6 +416,9 @@ export function _resolve_concerns(
       );
       continue;
     }
+    if (opts.refusal_retry && spec["skip_on_refusal_retry"] === true) {
+      continue;
+    }
     out.push({ name: String(name), ...spec });
   }
   return out;
@@ -1081,13 +1119,17 @@ export function main(argv?: string[]): number {
   const payload_text = process.stdin.isTTY ? "" : _readStdin();
   _maybe_capture_payload(args, payload_text);
   const session_role = resolveSessionRole(process.env);
-  const concerns = _resolve_concerns(manifest, args.platform, args.event, session_role);
+  const refusal_retry = _is_refusal_retry(args.event, payload_text);
+  const concerns = _resolve_concerns(manifest, args.platform, args.event, session_role, {
+    refusal_retry,
+  });
 
   if (args.dry_run) {
     const plan = {
       platform: args.platform,
       event: args.event,
       role: session_role,
+      refusal_retry,
       concerns: concerns.map((c) => c["name"]),
     };
     process.stdout.write(_py_json_dumps(plan, 2) + "\n");

package/src/scripts/hooks/interruption_ledger_hook.ts

@@ -0,0 +1,256 @@
+/**
+ * interruption_ledger — road-to-user-out-of-the-loop Phase 0 Step 1.
+ *
+ * CAPTURE ONLY. Every `stop`, classifies whether the turn that just ended put a
+ * synchronous contact to the user, and appends one line to
+ * `agents/runtime/state/interruptions.jsonl`. It never emits context, never
+ * warns, and always returns 0 — the whole point of Phase 0 is a window that no
+ * mechanism reacted to, so a ledger that could change a run would corrupt the
+ * baseline it exists to measure.
+ *
+ * WHY THIS EXISTS. The roadmap's Goal names two axes — synchronous contacts per
+ * delivered roadmap, and wall-clock to open PR — and pre-registers both as
+ * claims. Neither is derivable today: nothing in the tree records that a turn
+ * ended by asking the user something. `check_enforcement_coverage` counts
+ * carriers, `gate-metrics.jsonl` counts gate verdicts, and the conformance suite
+ * scores reply SHAPE without ever asking whether the reply stopped the run.
+ *
+ * REUSE, NOT REIMPLEMENTATION. Reply-shape detection is `turn_end_gate_hook`'s,
+ * imported rather than copied: `readTranscriptTail` for the last assistant text,
+ * `finalParagraph` for the closing paragraph, and its `HANDBACK` list for the
+ * yields-without-asking shape. That file is the measured corpus's detector and
+ * has an R2 history behind each regex; a second copy here would drift from it
+ * silently and the drift would land in the baseline, not in a test.
+ *
+ * WHAT COUNTS AS A CONTACT, and why it is three classes rather than two. A
+ * question mark is the obvious one. It is not the only one: `scope-control`
+ * requires a hand-back — "das entscheidest Du", "your call" — which ends the
+ * turn and waits for the user just as hard as a question does, with no `?`
+ * anywhere. Counting only questions would report the package's own preferred
+ * hand-back shape as zero contacts, which is precisely the metric-that-flatters-
+ * the-design failure the roadmap's Risk 6 names.
+ *
+ *   ask       — the closing paragraph ends in a question mark.
+ *   handback  — no question, but the closing paragraph yields the decision.
+ *   none      — the turn ended without putting anything to the user.
+ *
+ * `class` refines an `ask` by the shape the user has to answer in:
+ * `numbered-options` when the reply carries a numbered block (the
+ * `user-interaction` shape — one decision point, cheap to answer), or
+ * `open-question` when it does not (free text, the expensive shape). The split
+ * exists because the two are not equal contacts and the report separates them.
+ *
+ * DEDUPE is on the turn ordinal, the same identity `turn_end_gate_hook` derives
+ * and for the same reason: a host may fire `stop` more than once for one turn,
+ * and a per-turn ledger that double-counts inflates exactly the number the
+ * baseline is pre-registered on.
+ *
+ * The roadmap slug comes from this session's own claim file — the one
+ * `agent-config sessions:claim` writes — so a contact is attributable to a
+ * delivered roadmap without this hook knowing anything about roadmaps. No claim
+ * means `roadmap: null`, which is a real and common state (any session that is
+ * not a roadmap run) and never a reason to skip the line.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { derive_session_tag } from '../chat_history.js';
+import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
+import { readHookStdin } from './hook_stdin.js';
+import { HANDBACK, finalParagraph, readTranscriptTail } from './turn_end_gate_hook.js';
+
+const EXIT_OK = 0;
+
+/** Same cap the turn-end gate reads its tail under. */
+const TRANSCRIPT_READ_MAX_BYTES = 2 * 1024 * 1024;
+
+export const LEDGER_RELPATH = path.join('agents', 'runtime', 'state', 'interruptions.jsonl');
+
+export type ContactKind = 'ask' | 'handback' | 'none';
+export type ContactClass = 'numbered-options' | 'open-question' | 'handback' | 'none';
+
+export interface InterruptionRecord {
+    run_id: string;
+    turn: number;
+    kind: ContactKind;
+    class: ContactClass;
+    roadmap: string | null;
+    at: string;
+}
+
+/**
+ * A numbered-options block: two or more numbered lines. One numbered line is an
+ * ordinary enumeration inside prose and is not a decision surface — requiring
+ * two is what keeps "1. read the file" from reading as an ask.
+ */
+export function hasNumberedOptions(reply: string): boolean {
+    let count = 0;
+    for (const line of reply.split('\n')) {
+        if (/^[ \t]{0,3}\d+[.)]\s+\S/.test(line)) count += 1;
+        if (count >= 2) return true;
+    }
+    return false;
+}
+
+/**
+ * Classify the reply. The question test is `turn_end_gate_hook`'s exactly — a
+ * question that ENDS the paragraph, never `includes('?')`, because a rhetorical
+ * or quoted question mid-reply is not a contact and counting it would inflate
+ * the baseline in the direction that makes the roadmap look successful later.
+ */
+export function classifyReply(reply: string): { kind: ContactKind; class: ContactClass } {
+    const tail = finalParagraph(reply);
+    if (!tail) return { kind: 'none', class: 'none' };
+
+    if (/\?["'’)\]]*\s*$/.test(tail)) {
+        return {
+            kind: 'ask',
+            class: hasNumberedOptions(reply) ? 'numbered-options' : 'open-question',
+        };
+    }
+    if (HANDBACK.some((re) => re.test(tail))) return { kind: 'handback', class: 'handback' };
+    return { kind: 'none', class: 'none' };
+}
+
+/** The roadmap this session claimed, or null. Never throws. */
+export function readClaimedRoadmap(workspaceRoot: string, sessionId: string): string | null {
+    if (!sessionId) return null;
+    try {
+        const file = path.join(
+            workspaceRoot,
+            'agents',
+            'runtime',
+            'state',
+            `roadmap-claim-${sessionId}.json`,
+        );
+        const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object') return null;
+        const slug = (parsed as Record<string, unknown>)['slug'];
+        return typeof slug === 'string' && slug.length > 0 ? slug : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * True when this run has already recorded this turn. Reads only the tail of the
+ * ledger: the duplicate a repeated `stop` produces is always the most recent
+ * line, so scanning the whole file would cost more on every turn to catch
+ * nothing extra.
+ */
+export function alreadyRecorded(ledgerPath: string, runId: string, turn: number): boolean {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(ledgerPath, 'utf8');
+    } catch {
+        return false;
+    }
+    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+    for (const line of lines.slice(-20)) {
+        try {
+            const rec: unknown = JSON.parse(line);
+            if (rec === null || typeof rec !== 'object') continue;
+            const r = rec as Record<string, unknown>;
+            if (r['run_id'] === runId && r['turn'] === turn) return true;
+        } catch {
+            // A corrupt line is not a reason to skip the write.
+        }
+    }
+    return false;
+}
+
+function str(v: JsonValue | undefined): string {
+    return typeof v === 'string' ? v : '';
+}
+
+export function main(): number {
+    let envelope: JsonObject;
+    let payload: JsonObject;
+    try {
+        [envelope, payload] = unwrap(readHookStdin(), 'claude');
+    } catch {
+        return EXIT_OK;
+    }
+
+    const workspaceRoot = str(envelope['workspace_root'] as JsonValue | undefined) || process.cwd();
+    const transcriptPath = str(
+        (payload['transcript_path'] ?? payload['transcriptPath']) as JsonValue | undefined,
+    );
+    if (!transcriptPath) return EXIT_OK;
+
+    let lastAssistant = '';
+    let turnOrdinal = 0;
+    try {
+        const tail = readTranscriptTail(transcriptPath, { maxBytes: TRANSCRIPT_READ_MAX_BYTES });
+        lastAssistant = tail.lastAssistant;
+        turnOrdinal = tail.turnOrdinal;
+    } catch {
+        return EXIT_OK;
+    }
+    if (!lastAssistant) return EXIT_OK;
+
+    const sessionId =
+        str(payload['session_id'] as JsonValue | undefined) ||
+        str(envelope['session_id'] as JsonValue | undefined);
+    // `derive_session_tag`, NOT the turn-end gate's `deriveSessionKey`. Both
+    // hash the session id, and only this one produces the tag `chat_history`
+    // already writes as `s`. The wall-clock axis is a join between this ledger
+    // and those timestamps, so a 32-char key from the other derivation would
+    // have made the roadmap's second pre-registered claim underivable — while
+    // looking correct in every test that never crossed the two files.
+    const runId = sessionId ? derive_session_tag(sessionId) : 'unknown';
+
+    const ledgerPath = path.join(workspaceRoot, LEDGER_RELPATH);
+    if (alreadyRecorded(ledgerPath, runId, turnOrdinal)) return EXIT_OK;
+
+    const verdict = classifyReply(lastAssistant);
+    const record: InterruptionRecord = {
+        run_id: runId,
+        turn: turnOrdinal,
+        kind: verdict.kind,
+        class: verdict.class,
+        roadmap: readClaimedRoadmap(workspaceRoot, sessionId),
+        at: new Date().toISOString(),
+    };
+
+    try {
+        fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+        fs.appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+    } catch {
+        // A ledger that cannot be written is a lost measurement, never a
+        // reason to affect the turn. Phase 0 is advisory by construction.
+    }
+    return EXIT_OK;
+}
+
+/**
+ * The concern runs in-process via `CONCERN_REGISTRY`, but the manifest's
+ * `script:` path is also the SPAWN FALLBACK — and without this guard that path
+ * imports the module, calls nothing, and exits 0. A silent no-op on a
+ * capture-only concern is invisible by construction: the ledger simply stays
+ * empty and the baseline reads as "no contacts". Caught by running the hook
+ * against a real envelope rather than by any unit test, which is why the probe
+ * is worth the two minutes.
+ */
+function _isCliEntry(): boolean {
+    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/ship_diff_volume_hook.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * `ship-diff-volume` — a shipping-intent gate on diff VOLUME.
+ *
+ * Complementary to `minimal-safe-diff`, not a duplicate of it, and the
+ * distinction is the reason this exists: that concern counts unique FILES
+ * TOUCHED PER TURN, which is a within-session shape signal. This one measures
+ * total changed LINES on the branch AT A SHIP VERB — the moment the change
+ * leaves for review. A twelve-turn change of four files each time trips
+ * neither; a single-turn 3,000-line change trips only this one.
+ *
+ * THE THRESHOLD IS DERIVED FROM THIS REPOSITORY'S OWN HISTORY, never copied
+ * from the reference that suggested the gate. Replay of the 40 most recently
+ * merged PRs (agents/evidence/eval-findings/metric-loop-s04.md) put the
+ * corrected p90 at 1,695 lines.
+ *
+ * THE EXCLUSION SET IS PART OF THE DEFINITION, NOT A TUNING PARAMETER. The
+ * same replay found the naive metric double-counting: four of the five largest
+ * PRs were dominated by `*.review-input/diff.patch` — a committed copy of the
+ * very diff being measured — and the fifth by a generated index. Precision at
+ * the raw p90 was 2/5, below the pre-registered 0.50 floor; excluding the
+ * repository's own bookkeeping moved it to 5/5. Removing an input that was
+ * never shipping volume is a correction. Growing this set until a firing goes
+ * away would be tuning, and the kill criterion applies to that.
+ *
+ * WARN-LEVEL FIRST. It never blocks; escalation waits for one release of
+ * recorded firings, per the phase. Exit code is always 0 on the advisory path;
+ * 2 is the warn-in-context channel this estate's dispatcher reads.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { readHookStdin } from './hook_stdin.js';
+import { atomic_write_json } from './state_io.js';
+
+export const STATE_FILE = path.join('agents', 'state', 'ship-diff-volume.json');
+
+/** Derived: corrected p90 over the last 40 merged PRs (spike s04). */
+export const DEFAULT_THRESHOLD = 1695;
+
+/**
+ * Paths excluded from the volume because they are not shipping volume.
+ *
+ * Each entry is a category of artefact the change did not author: a snapshot of
+ * the diff itself, a generated index, or a projection tree regenerated from
+ * source. None is a threshold in disguise.
+ */
+export const EXCLUDED = [
+    '.review-input/', // a committed copy of the diff being measured
+    'agents/roadmaps/archive/index.json', // generated index
+    'dist/', // projection of src/
+    '.augment/',
+    '.claude/',
+    '.cursor/',
+    '.clinerules/',
+] as const;
+
+/** Ship verbs — the moment a change leaves for review. */
+const SHIP_PATTERNS = [/\bgit\s+push\b/, /\bgh\s+pr\s+create\b/] as const;
+
+export function isShipCommand(cmd: string): boolean {
+    return SHIP_PATTERNS.some((re) => re.test(cmd));
+}
+
+export function isExcluded(p: string): boolean {
+    return EXCLUDED.some((e) => (e.endsWith('/') ? p.startsWith(e) || p.includes(e) : p === e));
+}
+
+/** `git diff --numstat` output → corrected volume plus what was excluded. */
+export function correctedVolume(numstat: string): { volume: number; excluded: number; files: number } {
+    let volume = 0;
+    let excluded = 0;
+    let files = 0;
+    for (const line of numstat.split('\n')) {
+        const m = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
+        if (m === null) continue;
+        const add = m[1] === '-' ? 0 : Number(m[1]);
+        const del = m[2] === '-' ? 0 : Number(m[2]);
+        const p = m[3]!;
+        if (isExcluded(p)) {
+            excluded += add + del;
+            continue;
+        }
+        volume += add + del;
+        files += 1;
+    }
+    return { volume, excluded, files };
+}
+
+function extractCommand(envelope: Record<string, unknown>): string {
+    const ti = envelope['tool_input'];
+    if (ti !== null && typeof ti === 'object') {
+        const c = (ti as Record<string, unknown>)['command'];
+        if (typeof c === 'string') return c;
+    }
+    const c = envelope['command'];
+    return typeof c === 'string' ? c : '';
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const idx = args.indexOf('--command');
+    let cmd = idx >= 0 && args[idx + 1] !== undefined ? args[idx + 1]! : '';
+    if (!cmd) {
+        const raw = readHookStdin();
+        let envelope: Record<string, unknown> = {};
+        if (raw.trim()) {
+            try {
+                envelope = JSON.parse(raw) as Record<string, unknown>;
+            } catch {
+                envelope = {};
+            }
+        }
+        cmd = extractCommand(envelope);
+    }
+    if (!isShipCommand(cmd)) return 0;
+
+    let numstat: string;
+    let base: string;
+    try {
+        base = execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], { encoding: 'utf-8' }).trim();
+        numstat = execFileSync('git', ['diff', '--numstat', `${base}...HEAD`], {
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    } catch {
+        // No merge base, no origin, a detached probe — nothing to say. An
+        // advisory concern that guesses on missing input is worse than silent.
+        return 0;
+    }
+
+    const { volume, excluded, files } = correctedVolume(numstat);
+    const over = volume >= DEFAULT_THRESHOLD;
+
+    try {
+        fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+        atomic_write_json(STATE_FILE, {
+            schema_version: 1,
+            base,
+            corrected_volume: volume,
+            excluded_volume: excluded,
+            files_counted: files,
+            threshold: DEFAULT_THRESHOLD,
+            warning: over,
+            checked_at: new Date().toISOString(),
+        });
+    } catch {
+        // State is observability, never the gate. A read-only tree must not
+        // turn an advisory warning into a failed ship.
+    }
+
+    if (!over) return 0;
+
+    process.stderr.write(
+        `ship-diff-volume: ${String(volume)} changed lines against ${DEFAULT_THRESHOLD} ` +
+            `(${String(files)} file(s); ${String(excluded)} line(s) excluded as bookkeeping).\n` +
+            `Every PR above this line in the last 40 named two or more concerns in its own title. ` +
+            `Splitting is a suggestion, not a requirement — this warns and never blocks.\n`,
+    );
+    return 2; // warn-in-context; advisory severity means the dispatcher does not block
+}
+
+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 (_isCliEntry()) {
+    process.exit(main());
+}