heyspex 0.1.0 → 0.2.0

package/spexharness/src/adapters/audit.mjs

@@ -0,0 +1,197 @@
+// spexharness/src/adapters/audit.mjs
+//
+// Restores the `.heyspex/guardrail-history.jsonl` audit-log side effect the
+// ported gates under spexharness/src/gates/ deliberately left out — each
+// one's header comment says "Not ported HERE" and points here. A gate stays
+// a pure decision function (no fs writes); THIS module is the front-side
+// observer that turns a gate's decision back into the exact row(s) its
+// pre-cutover Claude Code hook wrote for the same firing, so
+// scripts/claude-hooks/<gate>.smoke.mjs — the spec of that original
+// behavior — keeps passing now that the shells route through the ported
+// gates instead of the original scripts.
+//
+// Row shape is byte-compatible with the original writer
+// (scripts/claude-hooks/_guardrail-events.mjs's appendGuardrailEvent):
+// `{ timestamp, event_kind: "guardrail.fired", actor, spec_id, metadata }`.
+// This module calls that function directly rather than reimplementing it —
+// same "import the shared, already-pure library" precedent this porting
+// effort already set for _guardrail-loader.mjs / _transcript-text.mjs (see
+// e.g. enforce-session-sequence.mjs's own header) — so the JSONL rows the
+// console's guardrail-history reader sees are identical whichever writer
+// produced them.
+//
+// Per-gate mapping: only the three gates whose pre-cutover hooks called
+// appendGuardrailEvent AND whose smoke tests assert on the resulting log
+// (capture-workflow-gate, enforce-session-sequence, naughty-list-gate) are
+// mapped in {@link auditRowsFor} today. Each case reads its exact original
+// call shape straight from `git show HEAD:scripts/claude-hooks/<gate>.mjs`
+// (pre-cutover) and reconstructs it from the fields the ported gate's
+// decision object carries forward for exactly this purpose (see each gate's
+// own header comment for which fields and why). A gate/decision this module
+// has no case for returns no rows — this NEVER guesses a shape for a gate it
+// doesn't recognize.
+//
+// FAIL-SAFE (same contract as every hook and as _guardrail-events.mjs
+// itself): a write failure here must never break the caller. Every row
+// write is wrapped; recordGuardrailAudit() never throws.
+
+import { appendGuardrailEvent as defaultAppendGuardrailEvent } from '../../../scripts/claude-hooks/_guardrail-events.mjs';
+import { redactRecord } from '../redact.mjs';
+
+/**
+ * Build the zero-or-more guardrail-history rows implied by one gate's
+ * decision, matching what its pre-cutover Claude Code hook wrote for the
+ * same firing. Pure — no I/O. Returns `[]` for a plain `allow`, for any gate
+ * this module has no mapping for, or for a decision shape the mapping
+ * doesn't recognize (fail-safe: never guess).
+ *
+ * Each returned row is an `appendGuardrailEvent()`-shaped options object
+ * (`{ rule, surface, severity, decision, specId?, matchContext? }`) — the
+ * caller still supplies `repoRoot`.
+ *
+ * @param {{ id?: string }} gate
+ * @param {{ decision: string, reason?: string, rewrite?: Record<string, unknown>, rule?: string, blockHits?: Array<{ word: string, context?: string }> }} decision
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function auditRowsFor(gate, decision) {
+  const kind = decision?.decision ?? 'allow';
+  if (kind === 'allow' || !decision) return [];
+
+  switch (gate?.id) {
+    // Original (scripts/claude-hooks/capture-workflow-gate.mjs, pre-cutover):
+    //   appendGuardrailEvent({ rule: `capture-workflow-gate:${type}`,
+    //     surface: 'pretooluse', severity: 'warn', decision: 'warn',
+    //     specId: resolved.spec_id }, root);
+    // Fired on every match — this gate NEVER denies (see its header), so
+    // only the `rewrite.warn` shape is mapped.
+    case 'capture-workflow-gate': {
+      if (kind !== 'rewrite' || !decision.rewrite?.warn) return [];
+      const captureId = decision.rewrite?.captureId;
+      if (!captureId) return [];
+      const type = decision.rewrite?.type ?? '';
+      return [
+        {
+          rule: `capture-workflow-gate:${type}`,
+          surface: 'pretooluse',
+          severity: 'warn',
+          decision: 'warn',
+          specId: captureId,
+        },
+      ];
+    }
+
+    // Original (scripts/claude-hooks/enforce-session-sequence.mjs, pre-cutover)
+    // fireRule():
+    //   appendGuardrailEvent({ rule: ruleId, surface: 'stop',
+    //     severity: forReal ? (rule.severity ?? 'block') : 'warn',
+    //     decision: forReal ? 'block' : 'warn' }, root);
+    // Fired exactly once per Stop — either the wip rule or the progress
+    // rule, whichever the gate reported (`decision.rule`, carried on both
+    // the `deny` and `rewrite` results — see the gate's own header). The
+    // registry's `session-wip-before-stop` / `session-progress-before-review`
+    // rules are both severity "block" today, so `rule.severity ?? 'block'`
+    // and the `'block'` literal here agree; this reads the literal (matching
+    // the fallback) rather than re-loading the registry, keeping this module
+    // free of any guardrail-loader dependency of its own.
+    case 'enforce-session-sequence': {
+      const ruleId = decision.rule;
+      if (!ruleId) return []; // no rule id carried → nothing to log (fail-safe)
+      if (kind === 'deny') {
+        return [{ rule: ruleId, surface: 'stop', severity: 'block', decision: 'block' }];
+      }
+      if (kind === 'rewrite' && decision.rewrite?.warn) {
+        return [{ rule: ruleId, surface: 'stop', severity: 'warn', decision: 'warn' }];
+      }
+      return [];
+    }
+
+    // Original (scripts/claude-hooks/naughty-list-gate.mjs, pre-cutover):
+    //   for (const hit of blockHits) {
+    //     appendGuardrailEvent({ rule: `naughty-list:${hit.word}`,
+    //       surface: 'stop', severity: 'block',
+    //       decision: warnOnly ? 'warn' : 'block', matchContext: hit.context });
+    //   }
+    // One row PER block-severity hit (not deduped by word — a repeated hit
+    // logs a repeated row, same as the original's own loop), fired on both
+    // rungs; warn-severity-only hits are never logged (the original's loop
+    // only ever iterates `blockHits`). `decision.blockHits` carries exactly
+    // that array on both `deny` and `rewrite` — see the gate's own header.
+    case 'naughty-list-gate': {
+      const hits = Array.isArray(decision.blockHits) ? decision.blockHits : [];
+      if (!hits.length) return [];
+      const rowDecision = kind === 'deny' ? 'block' : 'warn';
+      return hits.map((hit) => ({
+        rule: `naughty-list:${hit?.word ?? ''}`,
+        surface: 'stop',
+        severity: 'block',
+        decision: rowDecision,
+        matchContext: hit?.context,
+      }));
+    }
+
+    // Original (scripts/claude-hooks/epic-milestone-phrasing-gate.mjs,
+    // pre-cutover):
+    //   appendGuardrailEvent({ rule: RULE_ID, surface: 'stop',
+    //     severity: 'warn', decision: warnOnly ? 'warn' : 'block',
+    //     matchContext: hits[0].excerpt });
+    // Exactly ONE row per firing (the original logs the FIRST hit's excerpt,
+    // not one row per hit — unlike naughty-list-gate above), at the literal
+    // severity 'warn' on BOTH rungs, because this gate ships warn-first by
+    // design and the registry row's own severity is 'warn' too. `decision.hits`
+    // carries the excerpts on both the `deny` and `rewrite` results — see the
+    // gate's own header.
+    case 'epic-milestone-phrasing-gate': {
+      const hits = Array.isArray(decision.hits) ? decision.hits : [];
+      if (!hits.length) return [];
+      if (kind !== 'deny' && !(kind === 'rewrite' && decision.rewrite?.warn)) return [];
+      return [
+        {
+          rule: 'epic-milestone-phrasing-gate',
+          surface: 'stop',
+          severity: 'warn',
+          decision: kind === 'deny' ? 'block' : 'warn',
+          matchContext: hits[0]?.excerpt,
+        },
+      ];
+    }
+
+    default:
+      return [];
+  }
+}
+
+/**
+ * Write every audit row {@link auditRowsFor} derives from one gate's
+ * decision. Injectable: pass `deps.append` to swap out the real
+ * `_guardrail-events.mjs` writer (e.g. so a unit test can assert the call
+ * without touching the real file, or so an in-process caller that wants no
+ * file writes passes a no-op). Never throws — a row write failure is
+ * swallowed per row, matching `appendGuardrailEvent`'s own fail-safe
+ * contract (and this module's own header).
+ *
+ * @param {{ id?: string }} gate
+ * @param {{ decision: string }} decision
+ * @param {string} repoRoot
+ * @param {{ append?: (row: Record<string, unknown>, repoRoot: string) => unknown }} [deps]
+ * @returns {number} how many rows were written (best-effort; a swallowed
+ *   per-row failure still counts as attempted, not written — callers that
+ *   need the true count should inspect their own `deps.append`'s return).
+ */
+export function recordGuardrailAudit(gate, decision, repoRoot, deps = {}) {
+  const append = deps.append ?? defaultAppendGuardrailEvent;
+  const rows = auditRowsFor(gate, decision);
+  let written = 0;
+  for (const row of rows) {
+    try {
+      // Redacted before it ever reaches `.heyspex/guardrail-history.jsonl`
+      // (HS-Y424) — `matchContext` (naughty-list-gate) is literally a
+      // snippet of whatever text tripped a rule, the field most likely to
+      // carry ingested prose or a leaked key verbatim.
+      append(redactRecord(row), repoRoot);
+      written += 1;
+    } catch {
+      // fail-safe: observability must never break the caller.
+    }
+  }
+  return written;
+}

package/spexharness/src/adapters/claude-code.mjs

@@ -0,0 +1,441 @@
+// spexharness/src/adapters/claude-code.mjs
+//
+// The Claude Code front's translation layer (HS-IQBF, wave-5 of
+// [[HS-AZ61-NYPR]]). Every one of the twelve ported gates under
+// spexharness/src/gates/ is now driven through THIS module by a generated
+// shell (scripts/generate-hook-shells.mjs) rather than by its own
+// stdin-reading, stdout-writing main() — this file is the only place that
+// speaks the Claude Code hook stdin/stdout contract.
+//
+// Two directions, both pure except the tiny stdin/stdout glue at the bottom:
+//   1. toEngineEvent(payload)      — Claude Code hook stdin JSON → an
+//                                     spexharness/src/events.mjs event.
+//   2. toHookResponse(point, id, decision) — a gate's decide.mjs-shaped
+//                                     decision → { exitCode, stdout, stderr }
+//                                     in the exact shape Claude Code expects
+//                                     back, one of four answer forms:
+//                                       a. bare exit code (0 allow / 2 deny)
+//                                          plus a stderr banner — the
+//                                          LEGACY style two of the twelve
+//                                          originals used (env-vault-guard,
+//                                          enforce-vault-naming).
+//                                       b. hookSpecificOutput.permissionDecision
+//                                          allow|deny|ask (+ reason) on
+//                                          stdout, exit 0 — the MODERN style
+//                                          the other before_tool gates use.
+//                                       c. hookSpecificOutput.additionalContext
+//                                          on stdout, exit 0 — an `inject`
+//                                          decision (no built-in gate uses
+//                                          this yet; it's here so the
+//                                          adapter's own contract is complete
+//                                          per this task's AC1).
+//                                       d. { decision: "block", reason } on
+//                                          stdout, exit 0 — the Stop hook
+//                                          contract (enforce-session-sequence,
+//                                          naughty-list-gate,
+//                                          id-display-format-gate).
+//
+// `runGateAsHook(gate)` at the bottom is the one impure entry point: it reads
+// stdin, calls the two pure functions above, restores the guardrail-history
+// audit-log write each ported gate deliberately left out of its own pure
+// decide() (see ./audit.mjs and each gate's "Not ported HERE" header), writes
+// stdout/stderr, and sets process.exitCode. This is what every generated
+// shell calls — see scripts/generate-hook-shells.mjs and PORTING.md.
+//
+// FAIL-SAFE (house rule every original hook already followed): any internal
+// error here — bad JSON on stdin, an unknown hook_event_name, a gate that
+// throws — must never deny. It falls through to allow (exit 0, no output),
+// same as every original script's own top-level `.catch(() => process.exit(0))`.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createEvent } from '../events.mjs';
+import { recordGuardrailAudit } from './audit.mjs';
+
+/** Claude Code `hook_event_name` → spexharness/src/events.mjs event point.
+ * Deliberately does NOT map `SubagentStop` to `stop` — SubagentStop is a
+ * distinct Claude Code hook event none of the twelve gates in this task are
+ * registered for (see claim-liveness-shared.mjs for where it IS used); an
+ * explicit `hook_event_name: "SubagentStop"` on stdin must read as "not this
+ * gate's event" (→ allow), never silently fold into `stop`. */
+const HOOK_EVENT_TO_POINT = {
+  SessionStart: 'session_start',
+  UserPromptSubmit: 'prompt_submit',
+  PreToolUse: 'before_tool',
+  PostToolUse: 'after_tool',
+  Stop: 'stop',
+  SessionEnd: 'session_end',
+};
+
+/** The inverse of {@link HOOK_EVENT_TO_POINT}, for building output JSON's
+ * `hookEventName` field from an engine event's `point`. */
+const POINT_TO_HOOK_EVENT = {
+  session_start: 'SessionStart',
+  prompt_submit: 'UserPromptSubmit',
+  before_tool: 'PreToolUse',
+  after_tool: 'PostToolUse',
+  stop: 'Stop',
+  session_end: 'SessionEnd',
+};
+
+/**
+ * @param {string} hookEventName - Claude Code's `hook_event_name` stdin field.
+ * @returns {string | null} the matching spexharness event point, or null for
+ *   an event this adapter has no mapping for (a front-end concern, not a
+ *   gate concern — the caller should fail open, never guess).
+ */
+export function hookEventNameToPoint(hookEventName) {
+  return HOOK_EVENT_TO_POINT[hookEventName] ?? null;
+}
+
+/**
+ * Field mapping (Claude Code stdin → engine event fields), shared by
+ * {@link toEngineEvent} and the lenient per-gate resolution
+ * {@link runGateAsHook} uses:
+ *   session_id            → sessionId (every point)
+ *   tool_name              → toolName (before_tool / after_tool)
+ *   tool_input             → toolInput (before_tool / after_tool)
+ *   tool_response           → toolResult (after_tool)
+ *   prompt                 → prompt (prompt_submit)
+ *   cwd                    → cwd (session_start)
+ *   source                 → agent (session_start — Claude Code's own field
+ *                             name for "how the session started")
+ *   transcript_path         → transcriptPath (stop)
+ *   stop_hook_active         → stopHookActive (stop)
+ *   reason                  → reason (session_end)
+ *
+ * @param {string} point
+ * @param {Record<string, unknown>} payload
+ * @returns {Record<string, unknown>}
+ */
+function fieldsForPoint(point, payload) {
+  const fields = { sessionId: payload?.session_id };
+  switch (point) {
+    case 'before_tool':
+      fields.toolName = payload?.tool_name;
+      fields.toolInput = payload?.tool_input ?? {};
+      break;
+    case 'after_tool':
+      fields.toolName = payload?.tool_name;
+      fields.toolInput = payload?.tool_input ?? {};
+      fields.toolResult = payload?.tool_response;
+      break;
+    case 'prompt_submit':
+      fields.prompt = payload?.prompt;
+      break;
+    case 'session_start':
+      fields.cwd = payload?.cwd;
+      fields.agent = payload?.source;
+      break;
+    case 'stop':
+      fields.transcriptPath = payload?.transcript_path;
+      fields.stopHookActive = payload?.stop_hook_active;
+      break;
+    case 'session_end':
+      fields.reason = payload?.reason;
+      break;
+    default:
+      break;
+  }
+  return fields;
+}
+
+/**
+ * Map a Claude Code hook stdin payload (already JSON.parse'd) to a
+ * spexharness engine event. Returns null when `hook_event_name` is missing
+ * or unrecognized — the caller's job to fail open on that, not this
+ * function's (this module has no I/O of its own).
+ *
+ * @param {Record<string, unknown>} payload
+ * @returns {ReturnType<typeof createEvent> | null}
+ */
+export function toEngineEvent(payload) {
+  const point = hookEventNameToPoint(payload?.hook_event_name);
+  if (!point) return null;
+  return createEvent(point, fieldsForPoint(point, payload));
+}
+
+// Two of the twelve original hooks used the LEGACY "bare exit code + stderr
+// banner" style (exit 2, empty stdout, a `\n[<banner>]\n<reason>\n` stderr
+// message) instead of the modern permissionDecision JSON every other
+// before_tool gate here uses. Keyed by gate id so a future gate defaults to
+// the modern style without needing to opt out of anything.
+const LEGACY_EXIT2_BANNER = {
+  'env-vault-guard': 'HeySpex env-vault guard',
+  'enforce-vault-naming': 'HeySpex vault-naming hook',
+};
+
+function jsonStdout(obj) {
+  return JSON.stringify(obj);
+}
+
+/**
+ * Map one gate's decide.mjs-shaped result — `{ decision: 'allow'|'deny'|
+ * 'rewrite'|'inject', reason?, rewrite?, inject? }` — onto the Claude Code
+ * hook contract for the event it ran against.
+ *
+ * @param {{ id: string, event: string }} gate - the gate's own `id`/`event`
+ *   (used for the legacy-banner lookup and as a fallback hookEventName).
+ * @param {{ point: string }} engineEvent - the event the gate ran against
+ *   (its `point` decides which of the four answer shapes applies).
+ * @param {{ decision: string, reason?: string, rewrite?: object, inject?: object|string }} decision
+ * @returns {{ exitCode: number, stdout: string, stderr: string }}
+ */
+export function toHookResponse(gate, engineEvent, decision) {
+  const point = engineEvent?.point ?? gate?.event;
+  const hookEventName = POINT_TO_HOOK_EVENT[point] ?? 'PreToolUse';
+  const kind = decision?.decision ?? 'allow';
+
+  // ── Stop hook contract: { decision: "block", reason } or nothing. ────────
+  if (point === 'stop') {
+    if (kind === 'deny') {
+      return { exitCode: 0, stdout: jsonStdout({ decision: 'block', reason: decision.reason }), stderr: '' };
+    }
+    if (kind === 'rewrite' && decision.rewrite?.warn) {
+      const text = decision.rewrite.stderrText ?? warnStderrText(decision.reason ?? decision.rewrite.reason);
+      return { exitCode: 0, stdout: '', stderr: text };
+    }
+    return { exitCode: 0, stdout: '', stderr: '' };
+  }
+
+  // ── before_tool / after_tool: permissionDecision, or the legacy exit-2 style. ──
+  if (kind === 'deny') {
+    const banner = LEGACY_EXIT2_BANNER[gate?.id];
+    if (banner) {
+      return { exitCode: 2, stdout: '', stderr: `\n[${banner}]\n${decision.reason}\n` };
+    }
+    return {
+      exitCode: 0,
+      stdout: jsonStdout({
+        hookSpecificOutput: { hookEventName, permissionDecision: 'deny', permissionDecisionReason: decision.reason },
+      }),
+      stderr: '',
+    };
+  }
+
+  if (kind === 'rewrite') {
+    if (decision.rewrite?.ask) {
+      return {
+        exitCode: 0,
+        stdout: jsonStdout({
+          hookSpecificOutput: { hookEventName, permissionDecision: 'ask', permissionDecisionReason: decision.reason },
+        }),
+        stderr: '',
+      };
+    }
+    if (decision.rewrite?.warn) {
+      const text = decision.rewrite.stderrText ?? warnStderrText(decision.reason ?? decision.rewrite.reason);
+      return { exitCode: 0, stdout: '', stderr: text };
+    }
+    // A rewrite with neither ask nor warn (not produced by any of the twelve
+    // gates today) — fail open rather than guess at a shape.
+    return { exitCode: 0, stdout: '', stderr: '' };
+  }
+
+  if (kind === 'inject') {
+    const additionalContext =
+      typeof decision.inject === 'string' ? decision.inject : decision.inject?.additionalContext;
+    if (!additionalContext) return { exitCode: 0, stdout: '', stderr: '' };
+    return {
+      exitCode: 0,
+      stdout: jsonStdout({ hookSpecificOutput: { hookEventName, additionalContext } }),
+      stderr: '',
+    };
+  }
+
+  // 'allow' (and any unrecognized decision — fail open, never guess a deny).
+  return { exitCode: 0, stdout: '', stderr: '' };
+}
+
+/** Default stderr formatter for a `rewrite.warn` decision that carries no
+ * explicit `rewrite.stderrText` override: append exactly one trailing
+ * newline, unless `reason` already ends with one (several gates' own warn
+ * text already carries its own trailing newline — see naughty-list-gate.mjs
+ * / id-display-format-gate.mjs's `warnReason()`). */
+function warnStderrText(reason) {
+  const text = String(reason ?? '');
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+// ── stdin / process glue — the only impure code in this module ─────────────
+
+/** Read and JSON.parse Claude Code's hook stdin payload. Mirrors every
+ * original hook's own `readStdinJson()`: a TTY (no piped stdin) or
+ * unparseable input both resolve to null, never throw. */
+async function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) buf += chunk;
+  if (!buf.trim()) return null;
+  try {
+    return JSON.parse(buf);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the engine event a gate should run against, for one gate's shell
+ * specifically — LENIENT where {@link toEngineEvent} is strict: when
+ * `hook_event_name` is present, it must map to this gate's OWN `event`
+ * (anything else, including a recognized-but-different event like
+ * `SubagentStop` or `PostToolUse`, is "not this gate's turn" → null, allow).
+ * When `hook_event_name` is absent altogether (no key on the payload at
+ * all — every real Claude Code hook call always includes it; only a
+ * hand-built test payload omits it, e.g. `{ tool_name, tool_input }` with no
+ * envelope), this assumes the payload is already shaped for THIS gate's own
+ * registered event and maps its fields accordingly — a shell is always
+ * wired to exactly one event, so there is nothing to guess here.
+ *
+ * @param {Record<string, unknown>} payload
+ * @param {{ event: string }} gate
+ * @returns {ReturnType<typeof createEvent> | null}
+ */
+function resolveEventForGate(payload, gate) {
+  const hasHookEventName = payload?.hook_event_name !== undefined;
+  // A hook script registered on SEVERAL Claude Code events (coo-guard-check is
+  // registered on both SessionStart and PreToolUse in .claude/settings.json)
+  // hands this function a gate whose `event` is the ARRAY of points it answers
+  // for — see spexharness/src/gates/coo-guard-gate.mjs's `hookGate`. Only this
+  // adapter understands that form; registry.mjs stays one-event-per-gate by
+  // construction, so such a hook registers its rungs there as separate gates.
+  const multi = Array.isArray(gate?.event);
+  // With no `hook_event_name` at all (a hand-built test payload), a single-event
+  // gate's own event is the only sensible reading; a multi-event gate has
+  // nothing to guess from, so it declines rather than picking one.
+  const point = hasHookEventName ? hookEventNameToPoint(payload.hook_event_name) : multi ? null : gate.event;
+  if (!point) return null;
+  if (multi ? !gate.event.includes(point) : point !== gate.event) return null;
+  return createEvent(point, fieldsForPoint(point, payload));
+}
+
+/** This adapter's own repo root (spexharness/src/adapters/claude-code.mjs is
+ * three levels below it) — the same depth every ported gate's own REPO_ROOT
+ * constant resolves from, so {@link auditRepoRoot}'s env-first fallback
+ * agrees with whatever root a gate itself used to resolve its decision. */
+const ADAPTER_REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/** Same env-first resolution every pre-cutover hook's own `repoRoot()`
+ * helper used (CLAUDE_PROJECT_DIR, trailing slash stripped, else the
+ * repo-relative fallback) — kept here rather than imported so this module
+ * has no dependency on any one gate's own copy of the same three lines. */
+function auditRepoRoot() {
+  const fromEnv = process.env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return ADAPTER_REPO_ROOT;
+}
+
+/**
+ * Run ONE gate as a Claude Code hook process: read stdin, map it to an
+ * engine event, run the gate, restore the guardrail-history audit-log side
+ * effect the gate itself deliberately left out (see audit.mjs and each
+ * ported gate's own "Not ported HERE" header), map the decision back to the
+ * hook contract, write stdout/stderr, and set `process.exitCode`. This is
+ * the whole body of every generated shell under scripts/claude-hooks/ — see
+ * scripts/generate-hook-shells.mjs.
+ *
+ * Fail-safe throughout: any error anywhere in this pipeline is swallowed and
+ * treated as allow (exit 0, no output) — matching every original hook's own
+ * `.catch(() => process.exit(0))`. The audit write is additionally never
+ * allowed to affect the hook response either way — see
+ * `recordGuardrailAudit`'s own fail-safe contract.
+ *
+ * @param {{ id: string, event: string, run: (event: object, ctx: object) => unknown }} gate
+ * @param {{ audit?: false | ((gate: object, decision: object, repoRoot: string) => unknown),
+ *            append?: (row: Record<string, unknown>, repoRoot: string) => unknown,
+ *            payload?: Record<string, unknown> }} [deps]
+ *   `deps.payload` — an ALREADY-READ stdin payload. Only {@link runGatesAsHook}
+ *   passes it: stdin can be consumed exactly once, so a shell wired to several
+ *   gates reads it, picks the gate whose event matches, and hands the payload
+ *   on rather than letting this function read an empty stream.
+ *   `deps.audit` — full override of the audit step; pass `false` to disable
+ *   it entirely (an in-process caller that wants no `.heyspex/guardrail-
+ *   history.jsonl` writes at all). `deps.append` — override just the
+ *   low-level row writer (recordGuardrailAudit's own `deps.append`), while
+ *   keeping this module's row-shape mapping — what the adapter's own unit
+ *   test uses to assert the call without touching the real file. Neither
+ *   set → the real audit trail is written, restoring the pre-cutover
+ *   behavior unconditionally (every generated shell calls `runGateAsHook(gate)`
+ *   with no `deps`, so this is what a live Claude Code session gets).
+ * @returns {Promise<void>}
+ */
+/**
+ * Run the ONE gate out of `gates` that is registered for the incoming hook
+ * event, for a Claude Code hook script wired to MORE THAN ONE event.
+ *
+ * Why it exists (wave 6 of [[HS-AZ61-NYPR]]): `.claude/settings.json` registers
+ * `git-reflog-audit` on BOTH SessionStart and Stop, and the original script
+ * branched on `hook_event_name` inside its own `main()`. The engine registry
+ * keys a gate on exactly one event point (registry.mjs's `assertValidGate`), so
+ * that rule ships as a PAIR of gates and its shell needs to pick between them.
+ * `runGateAsHook` cannot simply be called twice: stdin can be consumed once, so
+ * the second call would read an empty stream. This reads it once and hands it
+ * on via `deps.payload`.
+ *
+ * Fail-safe throughout, exactly like {@link runGateAsHook}: a payload that maps
+ * to none of these gates' events writes nothing and exits 0.
+ *
+ * @param {Array<{ id: string, event: string, run: Function }>|{ id: string, event: string, run: Function }} gates
+ * @param {object} [deps] - forwarded to {@link runGateAsHook}.
+ * @returns {Promise<void>}
+ */
+export async function runGatesAsHook(gates, deps = {}) {
+  let payload = null;
+  try {
+    payload = await readStdinJson();
+  } catch {
+    return; // fail-open, same as runGateAsHook's own catch
+  }
+  if (!payload) return;
+
+  const list = Array.isArray(gates) ? gates : [gates];
+  const match = list.find((gate) => {
+    try {
+      return resolveEventForGate(payload, gate) !== null;
+    } catch {
+      return false;
+    }
+  });
+  if (!match) return; // none of these gates runs on this event — allow
+
+  await runGateAsHook(match, { ...deps, payload });
+}
+
+export async function runGateAsHook(gate, deps = {}) {
+  try {
+    const payload = deps.payload ?? (await readStdinJson());
+    if (!payload) return;
+
+    const engineEvent = resolveEventForGate(payload, gate);
+    if (!engineEvent) return; // not this gate's event — allow
+
+    const raw = await gate.run(engineEvent, {});
+    const decision = typeof raw === 'string' ? { decision: raw } : raw ?? { decision: 'allow' };
+
+    if (deps.audit === false) {
+      // in-process caller opt-out — no audit write at all.
+    } else if (typeof deps.audit === 'function') {
+      try {
+        await deps.audit(gate, decision, auditRepoRoot());
+      } catch {
+        /* fail-safe: the audit step must never affect the hook response */
+      }
+    } else {
+      try {
+        recordGuardrailAudit(gate, decision, auditRepoRoot(), deps.append ? { append: deps.append } : {});
+      } catch {
+        /* fail-safe: the audit step must never affect the hook response */
+      }
+    }
+
+    const { exitCode, stdout, stderr } = toHookResponse(gate, engineEvent, decision);
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(stderr);
+    process.exitCode = exitCode;
+  } catch {
+    // Fail-open: never strand the agent on an adapter/gate crash.
+    process.exitCode = 0;
+  }
+}