@bookedsolid/rea 0.31.0 → 0.32.0

package/dist/hooks/attribution-advisory/index.js

@@ -0,0 +1,233 @@
+/**
+ * Node-binary port of `hooks/attribution-advisory.sh`.
+ *
+ * 0.32.0 Phase 1 Pilot #3 — opt-in policy-gated AI-attribution
+ * detector for `git commit` / `gh pr create|edit` commands.
+ *
+ * Why pilot #3 (and not #1): pilot #1 was the smallest port surface
+ * (no segments, no body-file resolution). Pilot #3 introduces the
+ * FULL `splitSegments` + `anySegmentStartsWith` + `anySegmentMatches`
+ * API surface. Pilot #2 (`security-disclosure-gate`) layers the
+ * file-IO body-file resolver on top of this same segment primitive.
+ *
+ * Behavioral contract — preserves bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner. (Same as pilot 1.)
+ *   2. Read stdin payload. When `tool_input.command` is missing /
+ *      empty, exit 0 silently.
+ *   3. Read `<reaRoot>/.rea/policy.yaml` and check for the line
+ *      `block_ai_attribution: true`. The bash original used `grep -qE
+ *      '^block_ai_attribution:[[:space:]]*true'` against the file
+ *      directly; the Node port preserves the EXACT same regex against
+ *      the file contents. NOT a YAML parse — the bash hook ran before
+ *      we had a CLI-mediated `policy-get` read, and consumers may
+ *      authored the line in either block or inline form. Matching the
+ *      regex behavior preserves all the edge cases the bash hook
+ *      shipped with.
+ *   4. Identify whether the command is RELEVANT — a `git commit` or
+ *      `gh pr create|edit` invocation at the head of any segment.
+ *      Uses `anySegmentStartsWith` (head-anchored, post-prefix-strip)
+ *      so a quoted-body mention like `gh pr edit --body "ref: git
+ *      commit earlier"` does NOT count as relevant.
+ *   5. Scan for FIVE attribution-marker classes, each via
+ *      `anySegmentMatches` so the match has to live in the same
+ *      segment as the relevant command head:
+ *        a. `Co-Authored-By:` with an AI vendor noreply@ domain
+ *        b. `Co-Authored-By:` with a known AI tool name
+ *        c. `Generated|Created|Built|… with|by <AI Tool>`
+ *        d. Markdown-linked tool name (`[Claude Code](`)
+ *        e. Robot-emoji + Generated marker
+ *   6. Any match → exit 2 with the banner. No match → exit 0.
+ *
+ * Wider-net pattern choice: the bash hook used `[[:space:]]+` for
+ * `\s+` equivalents. JS regex uses `\s+` which is broader (includes
+ * vertical tab / form feed). For the ASCII payloads `gh` and `git`
+ * actually accept, the behavior is identical.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+import { anySegmentStartsWith, anySegmentMatches } from '../_lib/segments.js';
+const RELEVANT_GH = 'gh\\s+pr\\s+(create|edit)';
+const RELEVANT_GIT_COMMIT = 'git\\s+commit';
+/**
+ * `Co-Authored-By:` paired with a vendor `noreply@` domain that we
+ * recognize as AI tooling. GitHub's per-user `users.noreply.github.com`
+ * form is EXCLUDED — that's a legitimate human-collaborator credit.
+ *
+ * Mirrors the 0.18.0 helix-020 G4.B fix exactly: the catalog of
+ * recognized AI vendor noreply domains is enumerated here verbatim
+ * from the bash hook so adding/removing a vendor is a one-place edit.
+ */
+const NOREPLY_AI_DOMAINS = [
+    'anthropic\\.com',
+    'openai\\.com',
+    'github-copilot',
+    'github\\.com',
+    'claude\\.ai',
+    'chatgpt\\.com',
+    'googlemail\\.com',
+    'google\\.com',
+    'cursor\\.com',
+    'codeium\\.com',
+    'tabnine\\.com',
+    'amazon\\.com',
+    'amazonaws\\.com',
+    'amazon-q\\.amazonaws\\.com',
+    'cody\\.dev',
+    'sourcegraph\\.com',
+    'mistral\\.ai',
+    'xai-org',
+    'x\\.ai',
+    'inflection\\.ai',
+    'perplexity\\.ai',
+    'replit\\.com',
+    'jetbrains\\.com',
+    'bito\\.ai',
+    'pieces\\.app',
+    'phind\\.com',
+    'you\\.com',
+];
+const PATTERN_NOREPLY_AI = `Co-Authored-By:.*noreply@(${NOREPLY_AI_DOMAINS.join('|')})`;
+const PATTERN_COAUTH_AI_NAME = 'Co-Authored-By:.*\\b(Claude|Sonnet|Opus|Haiku|Copilot|GPT|ChatGPT|Gemini|' +
+    'Cursor|Codeium|Tabnine|Amazon Q|CodeWhisperer|Devin|Windsurf|Cline|' +
+    'Aider|Anthropic|OpenAI|GitHub Copilot)\\b';
+const PATTERN_GENERATED_WITH = '(Generated|Created|Built|Powered|Authored|Written|Produced)\\s+' +
+    '(with|by)\\s+' +
+    '(Claude|Copilot|GPT|ChatGPT|Gemini|Cursor|Codeium|Tabnine|CodeWhisperer|' +
+    'Devin|Windsurf|Cline|Aider|AI|an? AI)\\b';
+const PATTERN_MD_LINK = '\\[Claude Code\\]\\(|\\[GitHub Copilot\\]\\(|\\[ChatGPT\\]\\(|' +
+    '\\[Gemini\\]\\(|\\[Cursor\\]\\(';
+const PATTERN_EMOJI = '🤖.*[Gg]enerated';
+const BLOCK_BANNER = [
+    '\n',
+    '═══════════════════════════════════════════════════════════════════\n',
+    '  BLOCKED: AI attribution detected in command\n',
+    '═══════════════════════════════════════════════════════════════════\n',
+    '\n',
+    '  Your command contains structural AI attribution markers.\n',
+    '\n',
+    '  What gets BLOCKED (structural attribution):\n',
+    '    - Co-Authored-By with AI names or noreply@ emails\n',
+    '    - "Generated with/by [AI Tool]" footer lines\n',
+    '    - Markdown-linked tool names: [Claude Code](...)\n',
+    '    - Emoji attribution: 🤖 Generated...\n',
+    '\n',
+    '  What is ALLOWED (legitimate references):\n',
+    '    - "Fix Claude API integration"\n',
+    '    - "Update OpenAI SDK version"\n',
+    '    - "Add Copilot config"\n',
+    '\n',
+    '  Remove the attribution markers and rewrite the command.\n',
+    '  To disable: set block_ai_attribution: false in .rea/policy.yaml\n',
+    '═══════════════════════════════════════════════════════════════════\n',
+    '\n',
+].join('');
+/**
+ * Check whether the policy file enables `block_ai_attribution`. Same
+ * grep posture as the bash hook (`grep -qE
+ * '^block_ai_attribution:[[:space:]]*true' "$POLICY_FILE"`).
+ *
+ * Missing file → not enabled. Read errors → not enabled (the policy
+ * itself becomes the gate's input; an unreadable policy can't say
+ * "block", so the safe posture is to no-op like the bash hook does).
+ */
+function isAttributionBlockingEnabled(reaRoot) {
+    const policyFile = path.join(reaRoot, '.rea', 'policy.yaml');
+    if (!fs.existsSync(policyFile))
+        return false;
+    let content;
+    try {
+        content = fs.readFileSync(policyFile, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    // ERE: `^block_ai_attribution:[[:space:]]*true`. JS regex equiv:
+    // `^block_ai_attribution:\s*true` with multiline anchor.
+    return /^block_ai_attribution:\s*true/m.test(content);
+}
+/**
+ * Pure executor — returns `{ exitCode, stderr }`.
+ */
+export async function runAttributionAdvisory(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    // 1. HALT check.
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr };
+    }
+    // 2. Read stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let cmd = '';
+    try {
+        const payload = parseHookPayload(stdinRaw);
+        cmd = payload.command;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            writeStderr(`attribution-advisory: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr };
+        }
+        throw err;
+    }
+    if (cmd.length === 0) {
+        return { exitCode: 0, stderr };
+    }
+    // 3. Policy gate.
+    if (!isAttributionBlockingEnabled(reaRoot)) {
+        return { exitCode: 0, stderr };
+    }
+    // 4. Relevance gate — only act on `git commit` / `gh pr create|edit`.
+    const isRelevant = anySegmentStartsWith(cmd, RELEVANT_GH) ||
+        anySegmentStartsWith(cmd, RELEVANT_GIT_COMMIT);
+    if (!isRelevant) {
+        return { exitCode: 0, stderr };
+    }
+    // 5. Attribution scan.
+    let found = false;
+    if (anySegmentMatches(cmd, PATTERN_NOREPLY_AI))
+        found = true;
+    if (!found && anySegmentMatches(cmd, PATTERN_COAUTH_AI_NAME))
+        found = true;
+    if (!found && anySegmentMatches(cmd, PATTERN_GENERATED_WITH))
+        found = true;
+    if (!found && anySegmentMatches(cmd, PATTERN_MD_LINK))
+        found = true;
+    if (!found && anySegmentMatches(cmd, PATTERN_EMOJI))
+        found = true;
+    if (found) {
+        writeStderr(BLOCK_BANNER);
+        return { exitCode: 2, stderr };
+    }
+    return { exitCode: 0, stderr };
+}
+/**
+ * CLI entry — `rea hook attribution-advisory`.
+ */
+export async function runHookAttributionAdvisory(options = {}) {
+    const result = await runAttributionAdvisory({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}
+// Internal exports for tests.
+export const __INTERNAL_BLOCK_BANNER_FOR_TESTS = BLOCK_BANNER;
+export const __INTERNAL_PATTERNS_FOR_TESTS = {
+    PATTERN_NOREPLY_AI,
+    PATTERN_COAUTH_AI_NAME,
+    PATTERN_GENERATED_WITH,
+    PATTERN_MD_LINK,
+    PATTERN_EMOJI,
+};

package/dist/hooks/bash-scanner/protected-scan.js

@@ -136,13 +136,25 @@ function isKillSwitchInvariant(p) {
 /**
  * Test whether a normalized lowercase project-relative path falls
  * inside the documented husky extension surface
- * (`.husky/{commit-msg,pre-push,pre-commit}.d/<fragment>`).
+ * (`.husky/{commit-msg,pre-push,pre-commit,prepare-commit-msg}.d/<fragment>`).
  *
  * The bare directory itself (`.husky/pre-push.d/`) and the dir node
  * (`.husky/pre-push.d`) do NOT match — only fragments inside.
+ *
+ * 0.32.0 codex round 2 P1: `.husky/prepare-commit-msg.d/` joined the
+ * carve-out to match settings-protection.sh §5b and the bash-tier
+ * `rea_path_is_extension_surface` helper. Without this, the new
+ * prepare-commit-msg migration path documented in MIGRATING.md was
+ * still refused by the Node-binary protected-scan even though the
+ * Write/Edit allow-list permitted it.
  */
 function isExtensionSurface(pathLc) {
-    const surfaces = ['.husky/commit-msg.d/', '.husky/pre-push.d/', '.husky/pre-commit.d/'];
+    const surfaces = [
+        '.husky/commit-msg.d/',
+        '.husky/pre-push.d/',
+        '.husky/pre-commit.d/',
+        '.husky/prepare-commit-msg.d/',
+    ];
     for (const s of surfaces) {
         if (pathLc.startsWith(s) && pathLc.length > s.length) {
             return true;

package/dist/hooks/pr-issue-link-gate/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Node-binary port of `hooks/pr-issue-link-gate.sh`.
+ *
+ * 0.32.0 Phase 1 Pilot #1 — selected first because the bash original
+ * has the smallest dependency surface in the hook tree:
+ *
+ *   - No segment splitter (just substring match on `gh pr create`)
+ *   - No `--body-file` resolution
+ *   - No multi-pattern catalog
+ *   - Advisory only (always exits 0)
+ *
+ * That makes it the safest place to validate the playbook end-to-end:
+ * archive bash → write TS module → wire `rea hook pr-issue-link-gate`
+ * subcommand → replace .sh with a 15-line shim → mirror to
+ * `.claude/hooks/pr-issue-link-gate.sh` (PROTECTED — staged for git
+ * apply) → byte-fidelity test → consumer migration via `rea upgrade`
+ * picks up the new shim on next install.
+ *
+ * Behavioral contract — preserves bash hook byte-for-byte:
+ *
+ *   1. HALT check — exits 2 with banner when `.rea/HALT` is present.
+ *      Bash original called `check_halt` from `_lib/halt-check.sh`;
+ *      Node port calls the shared `checkHalt` primitive in
+ *      `src/hooks/_lib/halt-check.ts`. Same fail-closed posture.
+ *   2. Reads stdin payload, extracts `tool_input.command`. When the
+ *      tool isn't `Bash`, exits 0 silently (matches bash original
+ *      `[[ "$TOOL_NAME" != "Bash" ]] && exit 0`).
+ *   3. When command does NOT contain `gh\s+pr\s+create`, exits 0.
+ *   4. When command DOES contain a closing keyword paired with `#N`
+ *      (case-insensitive `closes`/`fixes`/`resolves` + whitespace +
+ *      `#` + digits), exits 0 — the agent has already linked an issue.
+ *   5. Otherwise, prints the same advisory banner to stderr and exits
+ *      0 (advisory only — never blocks).
+ *
+ * Wider-net pattern choice: the bash original used `grep -qiE
+ * 'gh\s+pr\s+create'` (free `\s` shorthand). The Node port uses the
+ * equivalent JavaScript regex `/gh\s+pr\s+create/i` — same byte
+ * outcomes for ASCII inputs, which is the only shape `gh` accepts.
+ */
+import type { Buffer } from 'node:buffer';
+export interface PrIssueLinkGateOptions {
+    /**
+     * Override REA_ROOT. Production caller relies on
+     * `$CLAUDE_PROJECT_DIR` → `process.cwd()`. Tests set this.
+     */
+    reaRoot?: string;
+    /**
+     * Pre-supplied stdin bytes. When set, skip the stdin read and feed
+     * this string into `parseHookPayload`. Tests use this to avoid
+     * touching `process.stdin`.
+     */
+    stdinOverride?: string | Buffer;
+    /**
+     * Test seam — receives every stderr write the gate produces. Default
+     * is `(s) => process.stderr.write(s)`.
+     */
+    stderrWrite?: (s: string) => void;
+}
+/**
+ * Result tuple — `{ exitCode, stderr }`. The CLI wrapper translates
+ * `exitCode` into `process.exit`; tests inspect `stderr` for the
+ * advisory banner shape.
+ *
+ * `exitCode` follows the bash hook's contract:
+ *   0 — allow / advisory only
+ *   2 — HALT active OR malformed payload (fail-closed)
+ *
+ * The bash hook itself never exits non-zero except via `check_halt`;
+ * the Node port adds the malformed-JSON fail-closed exit mirroring
+ * `runHookScanBash`'s posture (an attacker who can craft a payload
+ * shouldn't get a free allow).
+ */
+export interface PrIssueLinkGateResult {
+    exitCode: number;
+    /** Full stderr concatenated for test inspection. */
+    stderr: string;
+}
+/**
+ * Pure executor — no `process.exit`, no stdin read (when
+ * `stdinOverride` is set), no HALT-check side effects beyond reading
+ * the file. Returns the exit code + full stderr; the CLI wrapper
+ * applies them to the actual process.
+ */
+export declare function runPrIssueLinkGate(options?: PrIssueLinkGateOptions): Promise<PrIssueLinkGateResult>;
+/**
+ * CLI entry — `rea hook pr-issue-link-gate`. Wires the pure executor
+ * to `process.stderr.write` + `process.exit`. Mirrors the wiring
+ * pattern in `runHookScanBash` / `runHookCodexReview`.
+ */
+export declare function runHookPrIssueLinkGate(options?: PrIssueLinkGateOptions): Promise<void>;
+export declare const __INTERNAL_ADVISORY_BANNER_FOR_TESTS: string;

package/dist/hooks/pr-issue-link-gate/index.js

@@ -0,0 +1,127 @@
+/**
+ * Node-binary port of `hooks/pr-issue-link-gate.sh`.
+ *
+ * 0.32.0 Phase 1 Pilot #1 — selected first because the bash original
+ * has the smallest dependency surface in the hook tree:
+ *
+ *   - No segment splitter (just substring match on `gh pr create`)
+ *   - No `--body-file` resolution
+ *   - No multi-pattern catalog
+ *   - Advisory only (always exits 0)
+ *
+ * That makes it the safest place to validate the playbook end-to-end:
+ * archive bash → write TS module → wire `rea hook pr-issue-link-gate`
+ * subcommand → replace .sh with a 15-line shim → mirror to
+ * `.claude/hooks/pr-issue-link-gate.sh` (PROTECTED — staged for git
+ * apply) → byte-fidelity test → consumer migration via `rea upgrade`
+ * picks up the new shim on next install.
+ *
+ * Behavioral contract — preserves bash hook byte-for-byte:
+ *
+ *   1. HALT check — exits 2 with banner when `.rea/HALT` is present.
+ *      Bash original called `check_halt` from `_lib/halt-check.sh`;
+ *      Node port calls the shared `checkHalt` primitive in
+ *      `src/hooks/_lib/halt-check.ts`. Same fail-closed posture.
+ *   2. Reads stdin payload, extracts `tool_input.command`. When the
+ *      tool isn't `Bash`, exits 0 silently (matches bash original
+ *      `[[ "$TOOL_NAME" != "Bash" ]] && exit 0`).
+ *   3. When command does NOT contain `gh\s+pr\s+create`, exits 0.
+ *   4. When command DOES contain a closing keyword paired with `#N`
+ *      (case-insensitive `closes`/`fixes`/`resolves` + whitespace +
+ *      `#` + digits), exits 0 — the agent has already linked an issue.
+ *   5. Otherwise, prints the same advisory banner to stderr and exits
+ *      0 (advisory only — never blocks).
+ *
+ * Wider-net pattern choice: the bash original used `grep -qiE
+ * 'gh\s+pr\s+create'` (free `\s` shorthand). The Node port uses the
+ * equivalent JavaScript regex `/gh\s+pr\s+create/i` — same byte
+ * outcomes for ASCII inputs, which is the only shape `gh` accepts.
+ */
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+const ADVISORY_BANNER = [
+    'PR ISSUE LINK ADVISORY: This PR does not reference a GitHub issue.\n',
+    '\n',
+    'When a PR body includes a closing reference, GitHub automatically:\n',
+    '  - Closes the issue when the PR merges to the default branch\n',
+    '  - Creates a cross-reference in the issue timeline\n',
+    '  - Links the PR in the CHANGELOG context\n',
+    '\n',
+    'Add to the --body:\n',
+    '  closes #N    closes one issue\n',
+    '  fixes #N     same effect\n',
+    '  resolves #N  same effect\n',
+    '  closes #N, closes #M   closes multiple issues\n',
+    '\n',
+    'If this is a chore, release, or hotfix PR with no upstream issue, you may proceed.\n',
+].join('');
+/**
+ * Pure executor — no `process.exit`, no stdin read (when
+ * `stdinOverride` is set), no HALT-check side effects beyond reading
+ * the file. Returns the exit code + full stderr; the CLI wrapper
+ * applies them to the actual process.
+ */
+export async function runPrIssueLinkGate(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    let stderr = '';
+    const writeStderr = (s) => {
+        stderr += s;
+        if (options.stderrWrite)
+            options.stderrWrite(s);
+    };
+    // 1. HALT check — fail-closed (exit 2).
+    const halt = checkHalt(reaRoot);
+    if (halt.halted) {
+        writeStderr(formatHaltBanner(halt.reason));
+        return { exitCode: 2, stderr };
+    }
+    // 2. Read stdin.
+    const stdinRaw = options.stdinOverride !== undefined
+        ? options.stdinOverride
+        : await readStdinWithTimeout(5_000);
+    let toolName = '';
+    let cmd = '';
+    try {
+        const payload = parseHookPayload(stdinRaw);
+        toolName = payload.toolName;
+        cmd = payload.command;
+    }
+    catch (err) {
+        if (err instanceof MalformedPayloadError || err instanceof TypePayloadError) {
+            writeStderr(`pr-issue-link-gate: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr };
+        }
+        throw err;
+    }
+    // 3. Only Bash tool calls.
+    if (toolName !== '' && toolName !== 'Bash') {
+        return { exitCode: 0, stderr };
+    }
+    // 4. Only `gh pr create`.
+    if (!/gh\s+pr\s+create/i.test(cmd)) {
+        return { exitCode: 0, stderr };
+    }
+    // 5. Closing keyword paired with `#N` → satisfied, no advisory.
+    if (/(closes|fixes|resolves)\s+#[0-9]+/i.test(cmd)) {
+        return { exitCode: 0, stderr };
+    }
+    // 6. Advisory.
+    writeStderr(ADVISORY_BANNER);
+    return { exitCode: 0, stderr };
+}
+/**
+ * CLI entry — `rea hook pr-issue-link-gate`. Wires the pure executor
+ * to `process.stderr.write` + `process.exit`. Mirrors the wiring
+ * pattern in `runHookScanBash` / `runHookCodexReview`.
+ */
+export async function runHookPrIssueLinkGate(options = {}) {
+    const result = await runPrIssueLinkGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}
+// Internal export — used by the byte-fidelity test to assert the
+// advisory banner string hasn't drifted vs. the bash hook's
+// `printf` lines.
+export const __INTERNAL_ADVISORY_BANNER_FOR_TESTS = ADVISORY_BANNER;

package/dist/hooks/security-disclosure-gate/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Node-binary port of `hooks/security-disclosure-gate.sh`.
+ *
+ * 0.32.0 Phase 1 Pilot #2 — env-var-policy + body-file-resolver +
+ * mode-aware redirect router for `gh issue create` commands that
+ * mention vulnerability-class keywords.
+ *
+ * Why pilot #2 (and not #3): pilot #2 is the LARGEST of the three
+ * (339 LOC bash) and exercises every primitive landed in Phase 0:
+ *   - `checkHalt` (Phase 0)
+ *   - `parseHookPayload` (Phase 0)
+ *   - `splitSegments` / `anySegmentStartsWith` (Phase 0, used by
+ *     pilot #3 first but in scope here for `gh issue create`)
+ *   - File-IO resolver for `--body-file` / `-F` paths with `..`
+ *     traversal refusal, ABSOLUTE-vs-relative resolution, 64 KiB cap.
+ *   - Read of `REA_DISCLOSURE_MODE` env var with three-state semantics
+ *     (`advisory` / `issues` / `disabled`).
+ *
+ * Behavioral contract — preserves bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read `REA_DISCLOSURE_MODE` env var. `disabled` → exit 0
+ *      immediately (no scan at all).
+ *   3. Read stdin. If `tool_name` isn't `Bash`, exit 0.
+ *   4. Identify `gh issue create` segments via `anySegmentStartsWith`.
+ *      Substring fallback when the segment splitter is unreachable is
+ *      moot in Node — `splitSegments` is always in scope. (The bash
+ *      hook had a fallback only because `cmd-segments.sh` might be
+ *      absent in foreign installs.)
+ *   5. Resolve `--body-file PATH` and `-F PATH` arguments. The
+ *      resolver MUST match the bash quote-aware awk tokenizer for the
+ *      shape `--body-file "path with spaces.md"` — we run our own
+ *      quote-aware walker that yields each `--body-file` / `-F`
+ *      value. Stdin form (`-`) is skipped. Paths whose CANONICAL form
+ *      (after resolving `..` segments) escape REA_ROOT are REFUSED
+ *      with exit 2 + advisory banner (matches the 0.17.0 helix-019 #1
+ *      fix). Readable files contribute the first 64 KiB to the scan
+ *      buffer; unreadable files print a warning and continue.
+ *   6. Build `FULL_TEXT` = body-file contents + command text (both
+ *      lowercased) and scan for SECURITY_PATTERNS (an ordered list of
+ *      ERE patterns mirroring the bash array). First match wins;
+ *      `MATCHED_PATTERN` becomes the body-banner placeholder.
+ *   7. Route on mode:
+ *        - `issues`   → block banner pointing to `gh issue create
+ *                       --label 'security,internal' …` private form
+ *        - `advisory` → block banner pointing to `gh api
+ *                       repos/.../security-advisories` private form
+ *      Both return exit 2.
+ *
+ * Out-of-scope vs. the bash hook (intentional simplifications):
+ *
+ *   - The bash hook emits `json_output "block" "..."` via
+ *     `_lib/common.sh`. The JSON format is a Claude Code-specific
+ *     wrapper that lets the hook present a structured block reason
+ *     to the agent. In the Node tier, the canonical surface is `{
+ *     hookSpecificOutput: { hookEventName: 'PreToolUse', ... } }`
+ *     emitted on STDOUT with exit code 0; the legacy bash hook emits
+ *     it on stdout. We preserve that exact shape via `emitJsonBlock`.
+ *   - The bash hook's `require_jq` check is moot — Node parses JSON
+ *     natively.
+ */
+import { Buffer } from 'node:buffer';
+export type DisclosureMode = 'advisory' | 'issues' | 'disabled';
+export interface SecurityDisclosureGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+    stdoutWrite?: (s: string) => void;
+    /** Override `REA_DISCLOSURE_MODE`. Production reads `process.env`. */
+    disclosureModeOverride?: string;
+    /**
+     * Override `cwd()` for relative `--body-file` path resolution. The
+     * bash hook uses `pwd` (the shell's cwd at hook-execution time).
+     * Tests inject this so they don't have to `process.chdir`.
+     */
+    cwdOverride?: string;
+}
+export interface SecurityDisclosureGateResult {
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+}
+/**
+ * Pure executor.
+ */
+export declare function runSecurityDisclosureGate(options?: SecurityDisclosureGateOptions): Promise<SecurityDisclosureGateResult>;
+/**
+ * CLI entry — `rea hook security-disclosure-gate`.
+ */
+export declare function runHookSecurityDisclosureGate(options?: SecurityDisclosureGateOptions): Promise<void>;
+export declare const __INTERNAL_SECURITY_PATTERNS_FOR_TESTS: readonly string[];