@bookedsolid/rea 0.31.0 → 0.32.0

package/.husky/prepare-commit-msg

@@ -36,28 +36,65 @@ set -u
 COMMIT_MSG_FILE="${1:-}"
 COMMIT_SOURCE="${2:-}"
 
+REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+# Forward declaration — the extension-chain runner is defined further
+# down (after $REA_ROOT is set so the dir lookup is anchored). We call
+# it from every "augmenter skipped" exit point so consumer fragments
+# under .husky/prepare-commit-msg.d/* run regardless of whether rea's
+# own augmenter ran. The function fires fragments in lex order,
+# logs-and-continues on non-zero exits, and is a no-op if the dir is
+# absent or empty.
+#
+# 0.32.0 Phase 3: the pre-0.32.0 layout exited early at every
+# precondition gate, which made the extension surface unreachable
+# when (a) attribution was disabled, (b) HALT was active, or (c)
+# REA_SKIP_ATTRIBUTION was set. The new layout runs the chain at the
+# end of every exit path EXCEPT when the message file itself is
+# missing/unparseable (no point running fragments against a path that
+# doesn't exist).
+run_extension_chain() {
+  ext_dir="${REA_ROOT}/.husky/prepare-commit-msg.d"
+  if [ -d "$ext_dir" ]; then
+    for frag in "$ext_dir"/*; do
+      [ -e "$frag" ] || continue
+      [ -f "$frag" ] || continue
+      [ -x "$frag" ] || continue
+      if ! "$frag" "$COMMIT_MSG_FILE" "$COMMIT_SOURCE"; then
+        printf 'rea: prepare-commit-msg.d fragment exited non-zero: %s (continuing)\n' \
+          "$(basename "$frag")" >&2
+      fi
+    done
+  fi
+}
+
 # Skip conditions: any missing precondition exits 0 silently. The hook
 # is purely additive; refusing here would break commits with no upside.
 
-# Missing message file → nothing to augment.
+# Missing message file → nothing to augment AND nothing for fragments
+# to act on either. Exit immediately without running the chain.
 if [ -z "$COMMIT_MSG_FILE" ] || [ ! -f "$COMMIT_MSG_FILE" ]; then
   exit 0
 fi
 
-# Per-invocation override.
+# Per-invocation override — skip the augmenter, but still run consumer
+# fragments. The flag is named REA_SKIP_ATTRIBUTION, not REA_SKIP_HOOK,
+# precisely so the rest of the chain runs.
 if [ -n "${REA_SKIP_ATTRIBUTION:-}" ]; then
+  run_extension_chain
   exit 0
 fi
 
-REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
-
-# HALT kill switch — refuse to mutate anything while frozen.
+# HALT kill switch — refuse to mutate anything while frozen. The
+# extension chain is also skipped under HALT: a frozen system means
+# "no agent-side actions" and consumer fragments are agent-side too.
 if [ -f "${REA_ROOT}/.rea/HALT" ]; then
   exit 0
 fi
 
 POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
 if [ ! -f "$POLICY_FILE" ]; then
+  run_extension_chain
   exit 0
 fi
 
@@ -172,6 +209,7 @@ print(enabled); print(name); print(email); print(skip_merge)
 PY
 )
   if [ -z "$CO_AUTHOR_PARSE" ]; then
+    run_extension_chain
     exit 0
   fi
   ENABLED=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '1p')
@@ -179,11 +217,15 @@ PY
   CO_EMAIL=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '3p')
   SKIP_MERGE=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '4p')
 else
-  # Neither rea CLI nor python3 reachable — silent no-op.
+  # Neither rea CLI nor python3 reachable — silent no-op for the
+  # augmenter, but still run consumer fragments. The chain doesn't
+  # need policy values; it just runs `.husky/prepare-commit-msg.d/*`.
+  run_extension_chain
   exit 0
 fi
 
 if [ "$ENABLED" != "true" ]; then
+  run_extension_chain
   exit 0
 fi
 
@@ -204,11 +246,13 @@ if [ -z "$CO_NAME" ] || [ -z "$CO_EMAIL" ]; then
     "$([ -z "$CO_NAME" ] && [ -z "$CO_EMAIL" ] && printf '+')" \
     "$([ -z "$CO_EMAIL" ] && printf email)" >&2
   printf 'rea: edit .rea/policy.yaml — set name + email, OR set enabled: false.\n' >&2
+  run_extension_chain
   exit 0
 fi
 
 # skip_merge: true → skip when commit source is 'merge'.
 if [ "$SKIP_MERGE" = "true" ] && [ "$COMMIT_SOURCE" = "merge" ]; then
+  run_extension_chain
   exit 0
 fi
 
@@ -226,6 +270,7 @@ LOWER_EMAIL=$(printf '%s' "$CO_EMAIL" | tr '[:upper:]' '[:lower:]')
 ESCAPED_EMAIL=$(printf '%s' "$LOWER_EMAIL" | sed 's/[.[\*^$(){}+?|]/\\&/g')
 if grep -iE "^co-authored-by:[[:space:]]*[^<]*<${ESCAPED_EMAIL}>[[:space:]]*$" \
   "$COMMIT_MSG_FILE" >/dev/null 2>&1; then
+  run_extension_chain
   exit 0
 fi
 
@@ -311,4 +356,33 @@ awk '
 } > "${COMMIT_MSG_FILE}.rea-tmp" && mv "${COMMIT_MSG_FILE}.rea-tmp" "$COMMIT_MSG_FILE"
 
 rm -f "$TMP_BODY_TRIMMED"
+
+# ── Extension-hook chaining ───────────────────────────────────────────────────
+# 0.32.0 — `.husky/prepare-commit-msg.d/*` extension surface mirrors
+# the `.husky/commit-msg.d/*` and `.husky/pre-push.d/*` patterns from
+# 0.13.0. Source every executable file under
+# `.husky/prepare-commit-msg.d/` in lexical order. Missing directory
+# is a no-op (backward compatible). Each fragment receives the same
+# `$1` (commit message file path) and `$2` (commit source) that git
+# delivered to this hook so consumers can layer on their own
+# augmenters (lint-staged --on-prepare, branch-name-injection,
+# ticket-reference-prepend, …) without losing rea coverage.
+#
+# Fragments run AFTER rea's attribution augmenter so the
+# `Co-Authored-By` trailer is already in the file before any consumer
+# fragment reads it; that lets a fragment reorder trailers, dedupe,
+# or run its own template substitution against the augmented body.
+#
+# A non-zero exit from a fragment does NOT fail the commit — this
+# hook is purely additive (its bash counterpart `commit-msg` is the
+# blocking gate). We log the failure to stderr and continue so a
+# broken consumer fragment can't take down `git commit`.
+#
+# The actual chain body lives in `run_extension_chain` (defined near
+# the top of the file). The reason for the early definition: several
+# augmenter-skip exit paths (enabled: false, missing identity, idempo-
+# tency hit, skip_merge match) need to run the chain too, so consumer
+# fragments fire regardless of whether rea's own augmenter activated.
+run_extension_chain
+
 exit 0

package/MIGRATING.md

@@ -78,13 +78,16 @@ are on the vanilla-git path — install husky first.
 The only files rea touches are explicitly enumerated above. Everything
 else is the consumer's surface.
 
-## Extension surface (added in 0.13.0)
+## Extension surface (added in 0.13.0; expanded in 0.32.0)
 
-`.husky/pre-push.d/*` and `.husky/commit-msg.d/*` are the
-**upgrade-safe** place to layer your own gates. Files in those
-directories must be executable; rea sources them in lex order AFTER
-its own governance work succeeds. A non-zero exit from any fragment
-fails the hook (matches husky's normal chaining).
+`.husky/pre-push.d/*`, `.husky/commit-msg.d/*`, and (as of 0.32.0)
+`.husky/prepare-commit-msg.d/*` are the **upgrade-safe** place to
+layer your own gates. Files in those directories must be executable;
+rea sources them in lex order AFTER its own governance work succeeds.
+A non-zero exit from any fragment fails the hook (matches husky's
+normal chaining) — EXCEPT for the `prepare-commit-msg.d/*` lane,
+which logs and continues so a broken fragment can't take down `git
+commit`.
 
 - Fragment receives positional args from git (`<remote-name> <remote-url>`
   for pre-push, `<commit-msg-file>` for commit-msg).
@@ -158,26 +161,32 @@ Two paths, depending on whether you intend to use the rea augmenter.
 
 **Path A — you want the augmenter (Co-Authored-By trailer)**
 
-Move your branch-prefix logic into rea's chained body. As of 0.30.0
-rea's prepare-commit-msg body does NOT support `.husky/prepare-commit-msg.d/*`
-fragments yet (it's on the 0.31.0 roadmap). For now, port the logic
-into a wrapper invoked by `commit-msg.d` instead:
+Move your branch-prefix logic into a `.husky/prepare-commit-msg.d/*`
+fragment. As of **0.32.0** rea's prepare-commit-msg body sources every
+executable file in `.husky/prepare-commit-msg.d/` in lexical order
+AFTER its own attribution augmenter runs (mirrors the
+`commit-msg.d/*` and `pre-push.d/*` extension surfaces from 0.13.0).
+Each fragment receives the same `$1` (commit-message file path) and
+`$2` (commit source) git delivered to the hook:
 
 ```bash
-mkdir -p .husky/commit-msg.d
-cat > .husky/commit-msg.d/00-branch-prefix <<'EOF'
+mkdir -p .husky/prepare-commit-msg.d
+cat > .husky/prepare-commit-msg.d/00-branch-prefix <<'EOF'
 #!/bin/sh
-# Branch-prefix logic moved from prepare-commit-msg to commit-msg.d
-# (runs AFTER rea's augmenter, before the commit is finalized).
+# Runs AFTER rea's Co-Authored-By augmenter. $1 = commit-msg file.
 BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)
 case $(head -1 "$1") in
   "[$BRANCH]"*) ;;  # already prefixed
   *) printf '[%s] %s' "$BRANCH" "$(cat "$1")" > "$1" ;;
 esac
 EOF
-chmod +x .husky/commit-msg.d/00-branch-prefix
+chmod +x .husky/prepare-commit-msg.d/00-branch-prefix
 ```
 
+A non-zero exit from a fragment does NOT fail the commit (the augmenter
+hook is purely additive; the blocking gate is `commit-msg`). Broken
+fragments log to stderr and the hook continues.
+
 Then remove the old `.husky/prepare-commit-msg`:
 
 ```bash

package/dist/cli/hook.js

@@ -35,6 +35,10 @@ import crypto from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
 import { parsePrePushStdin, runPushGate } from '../hooks/push-gate/index.js';
 import { runBlockedScan, runProtectedScan } from '../hooks/bash-scanner/index.js';
+import { checkHalt, formatHaltBanner } from '../hooks/_lib/halt-check.js';
+import { runHookPrIssueLinkGate } from '../hooks/pr-issue-link-gate/index.js';
+import { runHookSecurityDisclosureGate } from '../hooks/security-disclosure-gate/index.js';
+import { runHookAttributionAdvisory } from '../hooks/attribution-advisory/index.js';
 import { loadPolicy } from '../policy/loader.js';
 import { appendAuditRecord, InvocationStatus, Tier } from '../audit/append.js';
 import { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, } from '../audit/codex-event.js';
@@ -129,17 +133,12 @@ export async function runHookScanBash(options) {
     // HALT check — uniform with the bash hooks. We exit 2 (block) so
     // the shim refuses the command in the same way settings-protection
     // and the bash gates do.
-    const haltPath = path.join(reaRoot, '.rea', 'HALT');
-    if (fs.existsSync(haltPath)) {
-        let reason = 'Reason unknown';
-        try {
-            const content = fs.readFileSync(haltPath, 'utf8');
-            reason = content.slice(0, 1024).trim() || reason;
-        }
-        catch {
-            /* leave default */
-        }
-        process.stderr.write(`REA HALT: ${reason}\nAll agent operations suspended. Run: rea unfreeze\n`);
+    // 0.32.0: shared via `src/hooks/_lib/halt-check.ts` so the Phase 1
+    // pilots and the codex-review hook below all emit the same banner
+    // byte-for-byte and apply the same fail-closed read posture.
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        process.stderr.write(formatHaltBanner(halt.reason));
         const haltVerdict = {
             verdict: 'block',
             reason: 'rea HALT active',
@@ -332,17 +331,10 @@ export async function runHookPolicyGet(options) {
 export async function runHookCodexReview(options) {
     const baseDir = options.reaRoot ?? process.cwd();
     // HALT check — uniform with the rest of the hook tree.
-    const haltPath = path.join(baseDir, '.rea', 'HALT');
-    if (fs.existsSync(haltPath)) {
-        let reason = 'Reason unknown';
-        try {
-            const content = fs.readFileSync(haltPath, 'utf8');
-            reason = content.slice(0, 1024).trim() || reason;
-        }
-        catch {
-            /* leave default */
-        }
-        process.stderr.write(`REA HALT: ${reason}\nAll agent operations suspended. Run: rea unfreeze\n`);
+    // 0.32.0: shared via `src/hooks/_lib/halt-check.ts`.
+    const halt = checkHalt(baseDir);
+    if (halt.halted) {
+        process.stderr.write(formatHaltBanner(halt.reason));
         process.exit(2);
     }
     // Resolve git context + base ref using the same primitives the push-
@@ -963,6 +955,24 @@ export function registerHookCommand(program) {
         .action(async () => {
         await runHookDelegationAdvisory();
     });
+    hook
+        .command('pr-issue-link-gate')
+        .description('Node-binary port of `hooks/pr-issue-link-gate.sh` (0.32.0). Reads a Claude Code PreToolUse Bash payload from stdin; when the command is `gh pr create` without a `closes/fixes/resolves #N` reference, prints an advisory banner to stderr. ALWAYS exits 0 except HALT (exit 2) or malformed payload (exit 2, fail-closed). The bash shim at `hooks/pr-issue-link-gate.sh` invokes this.')
+        .action(async () => {
+        await runHookPrIssueLinkGate();
+    });
+    hook
+        .command('security-disclosure-gate')
+        .description('Node-binary port of `hooks/security-disclosure-gate.sh` (0.32.0). Reads a Claude Code PreToolUse Bash payload from stdin; when the command is `gh issue create` AND title/body/body-file contents match a SECURITY_PATTERNS keyword, emits a deny JSON on stdout and exits 2. Routing depends on REA_DISCLOSURE_MODE: advisory (default, redirect to GHSA), issues (private repo, redirect to labeled issue), disabled (pass through).')
+        .action(async () => {
+        await runHookSecurityDisclosureGate();
+    });
+    hook
+        .command('attribution-advisory')
+        .description('Node-binary port of `hooks/attribution-advisory.sh` (0.32.0). Opt-in via policy.yaml `block_ai_attribution: true`. Reads a Claude Code PreToolUse Bash payload from stdin; when the command is `git commit` or `gh pr create|edit` AND contains structural AI attribution markers (Co-Authored-By with vendor noreply, AI tool names, "Generated with [X]", markdown-linked tools, 🤖 Generated), exits 2 with banner. Otherwise exits 0.')
+        .action(async () => {
+        await runHookAttributionAdvisory();
+    });
     hook
         .command('policy-get')
         .description('Read a value from `.rea/policy.yaml` via the canonical YAML parser. Used by bash-tier hooks (`hooks/_lib/policy-read.sh::policy_nested_scalar`) so inline AND block YAML forms agree at a single source of truth. Default scalar mode: prints raw value or empty. With `--json`: emits JSON (scalar or object/array; missing path → `null`). Unparseable YAML → empty / null, exit 1.')

package/dist/hooks/_lib/halt-check.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared HALT kill-switch reader for the Node-binary hook tier.
+ *
+ * 0.32.0 — extracted from `src/cli/hook.ts`. Pre-extraction the same
+ * `.rea/HALT` reader inlined twice (`runHookScanBash` lines 204-222 and
+ * `runHookCodexReview` lines 518-531) and `src/hooks/push-gate/halt.ts`
+ * carried a third copy with slightly different error semantics (the
+ * push-gate variant returns `{ halted: true, reason: 'unknown (HALT
+ * file unreadable)' }` on filesystem errors instead of falling through
+ * to allow). The Node-binary hook ports landing in 0.32.0 need the
+ * same primitive, so consolidate here before more copies accumulate.
+ *
+ * Contract:
+ *
+ *   - Returns `{ halted: false }` when `<reaRoot>/.rea/HALT` is absent.
+ *   - Returns `{ halted: true, reason }` when the file exists. `reason`
+ *     is the first non-empty line trimmed and capped at 1024 bytes;
+ *     missing/blank content collapses to `"Reason unknown"`.
+ *   - Filesystem errors during the read collapse to a halted sentinel
+ *     `"unknown (HALT file unreadable)"` — fail-CLOSED. The historical
+ *     `runHookScanBash` inline copy fell through to allow on read
+ *     failure; that is the wrong posture for a kill switch (an
+ *     attacker who can prevent the read should not get a free allow).
+ *     The push-gate's halt.ts already takes this stance; we converge.
+ *   - NEVER throws.
+ *
+ * Used by:
+ *   - `runHookScanBash`, `runHookCodexReview` (existing — migrated to
+ *     this primitive in 0.32.0)
+ *   - `runHookPrIssueLinkGate`, `runHookSecurityDisclosureGate`,
+ *     `runHookAttributionAdvisory` (Phase 1 pilots, 0.32.0)
+ *
+ * Distinct from `src/hooks/push-gate/halt.ts`:
+ *   - The push-gate's `readHalt` is part of the dependency-injected
+ *     test seam (`PushGateDeps.readHalt`) and cannot be replaced
+ *     wholesale without breaking the gate's existing contract.
+ *   - Future-work item: thread `checkHalt` THROUGH the push-gate's
+ *     `readHalt` default so a single primitive backs every consumer.
+ *     Out of scope for 0.32.0 — the push-gate ships green and rotating
+ *     it now would expand the diff without carrying its own bug fix.
+ */
+/**
+ * Result of a HALT probe.
+ *
+ * Discriminated union so callers cannot accidentally read `reason` from
+ * the not-halted case. The `halted: true` arm always carries a non-
+ * empty `reason` — the reader manufactures a placeholder rather than
+ * leaving the field undefined (the operator-facing stderr message
+ * `REA HALT: <reason>` would render `undefined` otherwise).
+ */
+export type HaltState = {
+    halted: true;
+    reason: string;
+} | {
+    halted: false;
+};
+/**
+ * Probe `<reaRoot>/.rea/HALT`. Pure function — does not write, log, or
+ * mutate process state. Caller is responsible for the operator-facing
+ * stderr emission and the exit code.
+ *
+ * @param reaRoot Absolute path to the project root that owns `.rea/`.
+ *                Hooks resolve this from `$CLAUDE_PROJECT_DIR` or
+ *                `process.cwd()` — callers should pre-resolve before
+ *                invoking this primitive.
+ * @returns `{ halted: false }` when the kill switch is clear, or
+ *          `{ halted: true, reason }` with a non-empty reason string.
+ */
+export declare function checkHalt(reaRoot: string): HaltState;
+/**
+ * Render the canonical operator-facing HALT banner. Pulled into a
+ * helper so the 5 hook callers (`runHookScanBash`,
+ * `runHookCodexReview`, and the 3 Phase 1 pilots) emit the same
+ * stderr text byte-for-byte. Matches the historical inline string
+ * exactly so existing consumer-side log parsers (if any) continue to
+ * work.
+ */
+export declare function formatHaltBanner(reason: string): string;

package/dist/hooks/_lib/halt-check.js

@@ -0,0 +1,106 @@
+/**
+ * Shared HALT kill-switch reader for the Node-binary hook tier.
+ *
+ * 0.32.0 — extracted from `src/cli/hook.ts`. Pre-extraction the same
+ * `.rea/HALT` reader inlined twice (`runHookScanBash` lines 204-222 and
+ * `runHookCodexReview` lines 518-531) and `src/hooks/push-gate/halt.ts`
+ * carried a third copy with slightly different error semantics (the
+ * push-gate variant returns `{ halted: true, reason: 'unknown (HALT
+ * file unreadable)' }` on filesystem errors instead of falling through
+ * to allow). The Node-binary hook ports landing in 0.32.0 need the
+ * same primitive, so consolidate here before more copies accumulate.
+ *
+ * Contract:
+ *
+ *   - Returns `{ halted: false }` when `<reaRoot>/.rea/HALT` is absent.
+ *   - Returns `{ halted: true, reason }` when the file exists. `reason`
+ *     is the first non-empty line trimmed and capped at 1024 bytes;
+ *     missing/blank content collapses to `"Reason unknown"`.
+ *   - Filesystem errors during the read collapse to a halted sentinel
+ *     `"unknown (HALT file unreadable)"` — fail-CLOSED. The historical
+ *     `runHookScanBash` inline copy fell through to allow on read
+ *     failure; that is the wrong posture for a kill switch (an
+ *     attacker who can prevent the read should not get a free allow).
+ *     The push-gate's halt.ts already takes this stance; we converge.
+ *   - NEVER throws.
+ *
+ * Used by:
+ *   - `runHookScanBash`, `runHookCodexReview` (existing — migrated to
+ *     this primitive in 0.32.0)
+ *   - `runHookPrIssueLinkGate`, `runHookSecurityDisclosureGate`,
+ *     `runHookAttributionAdvisory` (Phase 1 pilots, 0.32.0)
+ *
+ * Distinct from `src/hooks/push-gate/halt.ts`:
+ *   - The push-gate's `readHalt` is part of the dependency-injected
+ *     test seam (`PushGateDeps.readHalt`) and cannot be replaced
+ *     wholesale without breaking the gate's existing contract.
+ *   - Future-work item: thread `checkHalt` THROUGH the push-gate's
+ *     `readHalt` default so a single primitive backs every consumer.
+ *     Out of scope for 0.32.0 — the push-gate ships green and rotating
+ *     it now would expand the diff without carrying its own bug fix.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Maximum bytes of the HALT file we consider when assembling the
+ * `reason` line. Defends against a runaway-write scenario where
+ * `.rea/HALT` is megabytes large — we always emit the reason on
+ * stderr, and a multi-MB stderr blob can overwhelm a TTY before the
+ * user sees the actual exit. 1 KiB is more than enough for a human-
+ * authored kill-switch reason.
+ */
+const HALT_REASON_MAX_BYTES = 1024;
+/**
+ * Probe `<reaRoot>/.rea/HALT`. Pure function — does not write, log, or
+ * mutate process state. Caller is responsible for the operator-facing
+ * stderr emission and the exit code.
+ *
+ * @param reaRoot Absolute path to the project root that owns `.rea/`.
+ *                Hooks resolve this from `$CLAUDE_PROJECT_DIR` or
+ *                `process.cwd()` — callers should pre-resolve before
+ *                invoking this primitive.
+ * @returns `{ halted: false }` when the kill switch is clear, or
+ *          `{ halted: true, reason }` with a non-empty reason string.
+ */
+export function checkHalt(reaRoot) {
+    const haltPath = path.join(reaRoot, '.rea', 'HALT');
+    if (!fs.existsSync(haltPath)) {
+        return { halted: false };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(haltPath, 'utf8');
+    }
+    catch {
+        // Fail-closed: the file exists (existsSync passed) but we cannot
+        // read it. The operator intended to halt; a permissions glitch or
+        // race that prevents the read should NOT translate into a free
+        // allow. Surface a generic reason so the operator knows the file
+        // was present even when its content was unreadable.
+        return { halted: true, reason: 'unknown (HALT file unreadable)' };
+    }
+    // Cap at HALT_REASON_MAX_BYTES BEFORE splitting to bound the work.
+    // The pre-0.32.0 inline copies sliced the entire file content first
+    // and then trimmed; that is identical behavior for any reasonable
+    // file size but differs unboundedly for pathological inputs.
+    const slice = raw.length > HALT_REASON_MAX_BYTES ? raw.slice(0, HALT_REASON_MAX_BYTES) : raw;
+    const firstNonEmpty = slice
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return {
+        halted: true,
+        reason: firstNonEmpty !== undefined && firstNonEmpty.length > 0 ? firstNonEmpty : 'Reason unknown',
+    };
+}
+/**
+ * Render the canonical operator-facing HALT banner. Pulled into a
+ * helper so the 5 hook callers (`runHookScanBash`,
+ * `runHookCodexReview`, and the 3 Phase 1 pilots) emit the same
+ * stderr text byte-for-byte. Matches the historical inline string
+ * exactly so existing consumer-side log parsers (if any) continue to
+ * work.
+ */
+export function formatHaltBanner(reason) {
+    return `REA HALT: ${reason}\nAll agent operations suspended. Run: rea unfreeze\n`;
+}

package/dist/hooks/_lib/payload.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared stdin payload primitive for the Node-binary hook tier.
+ *
+ * 0.32.0 — extracts the `INPUT=$(cat) ; jq -r '.tool_input.command'`
+ * pattern that every bash hook in `hooks/` repeats. The Node-binary
+ * scan-bash already does this work in `runHookScanBash` (lines 225-258
+ * of `src/cli/hook.ts`); the Phase 1 pilots landing in 0.32.0 need
+ * the same primitive without copy-pasting the parsing + type-guard +
+ * fail-closed-on-malformed-JSON dance into each new hook.
+ *
+ * The shape mirrors the bash hooks' contract verbatim:
+ *
+ *   - `tool_input.command` is the only field we read; bash hooks only
+ *     ever ran `jq -r '.tool_input.command // ""'` against this payload.
+ *   - `tool_name` is also surfaced because two bash hooks
+ *     (`pr-issue-link-gate.sh` and `security-disclosure-gate.sh`)
+ *     short-circuit when the tool isn't `Bash`.
+ *
+ * Failure modes:
+ *
+ *   - Empty stdin → `{ command: '', toolName: '' }`. The bash hooks
+ *     allow on empty command (`[[ -z "$CMD" ]] && exit 0`); the Node
+ *     port preserves this by returning empty strings rather than
+ *     throwing.
+ *   - Malformed JSON → throws `MalformedPayloadError`. The caller
+ *     decides whether to fail-closed (block) or fail-open (allow);
+ *     `runHookScanBash` chose fail-closed (block) and the Phase 1
+ *     pilots match that posture for consistency.
+ *   - `tool_input.command` is non-string → throws `TypePayloadError`.
+ *     A crafted payload like `{"tool_input":{"command":["rm","-rf"]}}`
+ *     would silently coerce to `''` if we used `String(c)`; that
+ *     would translate into a free allow. Refuse instead.
+ */
+import { Buffer } from 'node:buffer';
+/**
+ * Result of parsing a Claude Code hook PreToolUse stdin payload.
+ */
+export interface HookPayload {
+    /** `tool_name` from the payload, or `''` when absent. */
+    toolName: string;
+    /** `tool_input.command` from the payload, or `''` when absent. */
+    command: string;
+}
+/**
+ * Thrown when stdin contains content that is not valid JSON.
+ *
+ * Distinct error class so callers can `instanceof` discriminate without
+ * leaning on string matching of the message.
+ */
+export declare class MalformedPayloadError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the JSON parses but `tool_input.command` is present and
+ * has the wrong type (anything other than `string` / `undefined`).
+ */
+export declare class TypePayloadError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a Claude Code PreToolUse stdin payload. Pure function — no I/O.
+ *
+ * @param raw Bytes / string read from the hook's stdin (the `INPUT=$(cat)`
+ *            equivalent).
+ * @returns A normalized `HookPayload` with both fields always defined.
+ * @throws MalformedPayloadError if the input is not parseable JSON.
+ * @throws TypePayloadError if `tool_input.command` is present with a
+ *         non-string type.
+ */
+export declare function parseHookPayload(raw: string | Buffer): HookPayload;
+/**
+ * Read all of stdin into a string with a soft byte cap and a hard
+ * timeout. Mirrors the `readStdinWithTimeout` helper in
+ * `src/cli/hook.ts` (which scans a fixed timeout but no byte cap).
+ *
+ * The cap (default 1 MiB) defends against a misbehaving caller piping
+ * an unbounded payload — we'd otherwise sit in the read loop forever
+ * even if the caller eventually closed stdin.
+ *
+ * @param timeoutMs How long to wait for stdin to close before resolving
+ *                  with whatever we have. Default 5_000 ms.
+ * @param maxBytes Soft cap on total bytes accepted. Default 1 MiB.
+ *                 Once reached, additional chunks are dropped silently
+ *                 (the caller still gets a parseable string back).
+ */
+export declare function readStdinWithTimeout(timeoutMs?: number, maxBytes?: number): Promise<string>;