@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/hooks/obligation_settle_hook.ts

@@ -41,13 +41,19 @@
 import path from 'node:path';
 import process from 'node:process';
 
+import { readHookStdin } from './hook_stdin.js';
+// The WRITER's own root resolver, imported rather than re-derived. A second
+// spelling of "which tree is this" is how a reader comes to address a ledger
+// the writer never wrote — which is the defect this whole file is repairing,
+// one field over.
+import { workspaceRoot as writerWorkspaceRoot } from './rule_inject_hook.js';
+
 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;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /**
  * Every non-doc path this turn wrote, tracked or not.
@@ -142,9 +148,144 @@ 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();
+/**
+ * The session and root this reading is about, resolved the way the WRITER does.
+ *
+ * THE DEFECT THIS EXISTS TO CLOSE. This hook used to read
+ * `CLAUDE_CODE_SESSION_ID` out of the process environment and return allow when
+ * it was empty. The dispatcher sets no such variable — it hands each concern
+ * the envelope on stdin and `AGENT_CONFIG_PACKAGE_ROOT` in the environment,
+ * nothing else — so on every dispatched stop event the reader looked for a
+ * ledger under a key the writer never used. Measured 2026-09-29 on this
+ * machine's own ledgers: 187 delivered rows, 0 shadow rows, across 8 sessions.
+ *
+ * WHY THE ORDER IS ENVELOPE-THEN-ENVIRONMENT AND NOT THE REVERSE. The envelope
+ * id is the key `rule_inject_hook.ts` wrote the delivered rows under, so it is
+ * not merely the better source — it is the ONLY one that can find them. The
+ * environment fallback survives for a raw invocation that carries no envelope
+ * at all (a maintainer piping nothing, a host shim that skips the dispatcher),
+ * which is a case where guessing wrong costs a missing reading rather than a
+ * wrong one.
+ *
+ * THE ROOT IS PART OF THE SAME JOIN, not a second change riding along. A ledger
+ * is addressed by root AND session; reading the session from the envelope while
+ * taking the root from `process.cwd()` would leave the pair half-joined, and the
+ * two disagree exactly on the hosts whose shim does not chdir. `cwd` stays the
+ * fallback because that is what the dispatcher sets it to.
+ *
+ * Both spellings of each key are accepted because the injector accepts both.
+ */
+export function resolveSettleContext(
+    envelope: Record<string, unknown>,
+    payload: Record<string, unknown>,
+    env: Record<string, string | undefined>,
+): { root: string; session: string } {
+    const str = (...values: unknown[]): string => {
+        for (const v of values) {
+            if (typeof v === 'string' && v.trim() !== '') return v.trim();
+        }
+        return '';
+    };
+    return {
+        // `workspaceRoot` is the INJECTOR's function, not a copy of it. It reads
+        // `workspace` / `cwd` / `project_dir`; this file used to read
+        // `workspace_root` / `workspace` / `cwd`, so the two key sets overlapped
+        // without matching and the pair was joined on the session only. It
+        // happened to agree on both real envelope shapes — the dispatcher sets
+        // `workspace_root` and chdirs concerns to it, a native wiring passes
+        // `cwd` — which made the asymmetry a property of today's envelopes
+        // rather than of the code. `workspace_root` is appended ahead of the
+        // shared resolver because the dispatcher is the only producer that sets
+        // it and nothing else reads it.
+        root:
+            str(envelope['workspace_root'])
+            || writerWorkspaceRoot(envelope as Parameters<typeof writerWorkspaceRoot>[0]),
+        session: str(
+            envelope['session_id'],
+            envelope['sessionId'],
+            payload['session_id'],
+            payload['sessionId'],
+            // The one pre-existing source, kept as the last resort and NOT
+            // joined by siblings: adding a name the writer never keys on
+            // would address a ledger that cannot exist.
+            env['CLAUDE_CODE_SESSION_ID'],
+        ),
+    };
+}
+
+/**
+ * The session id the WRITER would have used, for the ledger nobody reads.
+ *
+ * `rule_inject_hook.ts` defaults an unnamed session to the literal `unknown`
+ * and writes delivered rows there; this reader used to return `''` and allow, so
+ * that population was invisible to every reading of the bar. Reported rather
+ * than silently joined: a shared `unknown` bucket aggregates unrelated sessions,
+ * so reading it as one session's turn would be worse than not reading it. The
+ * constant is exported so a future census can count what is sitting there.
+ */
+export const WRITER_UNNAMED_SESSION = 'unknown';
+
+/** The envelope on stdin, or an empty object when there is none to read. */
+function readEnvelope(): { envelope: Record<string, unknown>; payload: Record<string, unknown> } {
+    let envelope: Record<string, unknown> = {};
+    try {
+        const raw = readHookStdin();
+        const parsed: unknown = raw.trim() === '' ? {} : JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            envelope = parsed as Record<string, unknown>;
+        }
+    } catch {
+        // A malformed envelope is not a reason to refuse, and this concern
+        // refuses nothing anyway. It is a reason to read nothing from it.
+    }
+    const nested = envelope['payload'];
+    const payload =
+        typeof nested === 'object' && nested !== null && !Array.isArray(nested)
+            ? (nested as Record<string, unknown>)
+            : envelope;
+    return { envelope, payload };
+}
+
+/**
+ * The resolver as it stood BEFORE the join fix, kept reachable for one test.
+ *
+ * A reproduction that cannot run the old code is not a reproduction — it is an
+ * assertion about the new function's behavior on inputs nobody sends, and
+ * `tests/hooks/obligation_settle.test.ts` carried exactly that until an
+ * independent review named it. This function is dead on every production path
+ * (nothing but the fixture calls it) and exists so the defect stays executable:
+ * environment-only resolution, allow when empty, root from the cwd.
+ */
+export function resolveSettleContextPreFix(
+    _envelope: Record<string, unknown>,
+    _payload: Record<string, unknown>,
+    env: Record<string, string | undefined>,
+): { root: string; session: string } {
+    // Same arity as the live resolver ON PURPOSE. A narrower signature would let
+    // the fixture pass the envelope in as `env`, where the lookup misses for the
+    // wrong reason and the test goes green without exercising the defect.
+    return { root: process.cwd(), session: (env['CLAUDE_CODE_SESSION_ID'] ?? '').trim() };
+}
+
+/**
+ * Which context resolver this reading uses — the seam the pre-fix fixture needs.
+ *
+ * It is NOT a parameter of `main()`, and that is a contract rather than a
+ * preference: `concern_main_signature` requires every concern's `main()` to take
+ * argv first or nothing, because the dispatcher calls `main(argv)` — so a
+ * resolver in first position would receive an argv array at runtime and resolve
+ * a session from it. Caught by that test, which is the reason this indirection
+ * exists instead of the obvious default parameter.
+ */
+export type SettleResolver = (
+    envelope: Record<string, unknown>,
+    payload: Record<string, unknown>,
+    env: Record<string, string | undefined>,
+) => { root: string; session: string };
+
+export function runSettle(resolve: SettleResolver = resolveSettleContext): number {
+    const { envelope, payload } = readEnvelope();
+    const { root, session } = resolve(envelope, payload, process.env);
     if (session === '') return EXIT_ALLOW;
 
     let verdict: SettleVerdict;
@@ -176,6 +317,11 @@ export function main(): number {
     return EXIT_ALLOW;
 }
 
+/** The dispatcher entry point. Argv-shaped, per `concern_main_signature`. */
+export function main(_argv: readonly string[] = process.argv.slice(2)): number {
+    return runSettle();
+}
+
 // 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/one_question_per_ask_hook.ts

@@ -14,12 +14,38 @@
  * names the count so the caller can split the ask instead of guessing what
  * happened.
  *
- * WHAT IT SEES, honestly. `_lib/structured_ask.ts` carries no observed
- * per-host tool, so this guard matches on a name SHAPE and is filtered by the
- * manifest's per-concern `tools:` key to the same candidate names. On every
- * host measured today it therefore fires on nothing — the concern exists so
- * that the first host to ship a picker meets the rule already in force, not
- * because a violation has been observed.
+ * WHAT IT SEES, honestly. `_lib/structured_ask.ts` carries ONE observed
+ * per-host tool — `claude`'s `AskUserQuestion`, 48 calls across versions
+ * 2.1.252 to 2.1.284 between 2026-09-01 and 2026-10-02.
+ *
+ * THIS GUARD DOES NOT USE THAT ROW, and the distinction matters enough to say
+ * rather than leave to a reader. `verdict()` calls `isStructuredAskTool(tool)`
+ * with no host id, so the shape branch is unreachable from here and the name
+ * SHAPE pattern decides on every host, `claude` included — filtered by the
+ * manifest's per-concern `tools:` key to the same candidate names. Threading a
+ * host id through would NARROW what this guard matches on the one host where a
+ * picker is known to exist (`ask_user_question` would stop matching), which is
+ * a behaviour change and not a header repair, so it is deliberately not made
+ * here.
+ *
+ * This header carried the opposite claim until 2026-10-05 — that no host's
+ * delivered surface had been observed carrying a picker — and it was wrong in
+ * a specific, instructive way rather than merely stale. Its measurement base
+ * was one `false` row taken from a SUBAGENT leg, whose surface carries no
+ * picker because a subagent has no user to ask. The step from "this leg has
+ * none" to "no host has been observed with one" is the substitution the
+ * observation protocol exists to refuse, and the registry comment now records
+ * which leg each reading came from for that reason. The old wording is
+ * described rather than quoted, because 1.1's drift check is a grep and a grep
+ * cannot tell a refuted quotation from a live assertion.
+ *
+ * The other eight hosts in `docs/enforcement-by-host.md` still have no row at
+ * all — never looked, not measured — so nothing here is a claim about them.
+ *
+ * WHAT THE OBSERVATION DOES NOT CHANGE: the deny threshold. One question per
+ * call is `ask-when-uncertain`'s Iron Law, not a host limit, and all 47
+ * parsed calls already carried exactly one. The guard has had nothing to deny
+ * and that is the expected reading, not evidence it is inert.
  *
  * ENFORCEMENT REACH, also honestly. `fail_closed: false` and the exit-1 deny
  * are only a deny where the host both binds `pre_tool_use` AND honours the
@@ -141,6 +167,17 @@ export function selfTest(): number {
             { tool_name: 'ask_user_question', tool_input: { question: 'which one?' } },
             false,
         ],
+        [
+            // PINS THE HEADER'S INVARIANT. `ask_user_question` is not the name
+            // claude's observed shape row carries, so this case denies only
+            // while `verdict()` passes no host id and the name-SHAPE pattern
+            // decides. Thread a host id through and the shape branch rejects
+            // the name, the call stops being an ask, and this flips to allow —
+            // which is the silent narrowing the header says is not being made.
+            'a snake_case picker with two questions is still denied — this guard is host-blind',
+            { tool_name: 'ask_user_question', tool_input: { questions: [{}, {}] } },
+            true,
+        ],
         [
             'an empty ask passes — malformed, but not this guard\'s failure',
             { tool_name: 'AskUserQuestion', tool_input: { questions: [] } },

package/src/scripts/hooks/orchestration_record_hook.ts

@@ -72,8 +72,7 @@ import { buildOrchestrationLine, type RecordInput } from '../_lib/orchestration_
 import { DEFAULT_DIR } from '../orchestration_record.js';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/payload_stub.ts

@@ -108,7 +108,16 @@ export const BODY_CLASSES: readonly BodyClass[] = ["input", "result"] as const;
  */
 export const BODY_KEYS: Readonly<Record<BodyClass, readonly string[]>> = {
   input: ["tool_input", "toolInput"],
-  result: ["tool_response", "toolResponse", "tool_result", "toolUseResult"],
+  // `error` is a result body and is listed as one. On claude's
+  // `PostToolUseFailure` the failing call carries NO `tool_response` at all —
+  // the command's own stdout and stderr arrive here instead, under the first
+  // line stating the exit code. Until that event was bound this key reached no
+  // concern, so its absence from this list cost nothing; binding the event
+  // without adding it would have delivered raw command output in full to every
+  // concern on the slot, including the fourteen that never declared `result`.
+  // That is exactly the content this module exists to withhold, so the key
+  // belongs to the class whose semantics it has — not to an exception.
+  result: ["tool_response", "toolResponse", "tool_result", "toolUseResult", "error"],
 };
 
 export interface PayloadStub extends JsonObject {

package/src/scripts/hooks/permission_gate.ts

@@ -20,6 +20,7 @@ import {
   type PermissionDecision,
   type PermissionEmission,
 } from "./host_semantics.js";
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -29,8 +30,6 @@ function _isObject(v: unknown): v is JsonObject {
 }
 
 /** Mirrors `dispatch_hook.EXIT_ALLOW` / `EXIT_BLOCK`; imported would be a cycle. */
-const EXIT_ALLOW = 0;
-const EXIT_BLOCK = 1;
 
 /** The host's `tool_name`, or `""` when the event carries none. */
 export function _payload_tool_name(envelope: JsonObject): string {

package/src/scripts/hooks/push_settle_hook.ts

@@ -54,9 +54,7 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readHookStdin } from "./hook_stdin.js";
-
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/replay_hook.ts

@@ -36,6 +36,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { EXIT_USAGE } from './exit_codes.js';
 
 // src/scripts/hooks/replay_hook.ts → parents[3] is the repo root.
 const REPO_ROOT = path.resolve(
@@ -175,7 +176,7 @@ function _parse_args(argv: string[]): ReplayArgs {
     process.stderr.write(
       `replay_hook: the following arguments are required: ${missing.join(", ")}\n`,
     );
-    process.exit(2);
+    process.exit(EXIT_USAGE);
   }
   return args;
 }

package/src/scripts/hooks/reread_guard_hook.ts

@@ -69,12 +69,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json } from './state_io.js';
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 // Severity is taken from the EXIT CODE, not from the `decision` field — see
 // the file header for why this never blocks on `claude`. This concern never
 // returns exit 1 on any path.
-const EXIT_WARN = 2;
 
 /**
  * Committed exemption list — deliberately duplicated from

package/src/scripts/hooks/review_baseline_hook.ts

@@ -49,8 +49,7 @@ import { deriveSessionKey, totalNonDocMutatedLinesWithMeasure } from './end_revi
 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;
+import { EXIT_ALLOW as EXIT_OK } from './exit_codes.js';
 
 export function buildBaseline(workspaceRoot: string, now: Date = new Date()): ReviewBaseline {
     const measured = totalNonDocMutatedLinesWithMeasure(workspaceRoot);

package/src/scripts/hooks/rtk_wrap_hook.ts

@@ -63,10 +63,9 @@ import {
 } from "./block_no_verify.js";
 import { readHookStdin } from "./hook_stdin.js";
 import { detectRtkCached } from "../../install/rtkDetection.js";
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 const SETTINGS_FILE = ".agent-settings.yml";
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };