@bookedsolid/rea 0.34.0 → 0.36.0

package/dist/hooks/_lib/protected-paths.js

@@ -0,0 +1,232 @@
+/**
+ * Shared protected-paths catalog for the Node-binary hook tier.
+ *
+ * 0.35.0 — TypeScript port of `hooks/_lib/protected-paths.sh`. The
+ * canonical hard-protected list shared between the Write/Edit tier
+ * (`settings-protection`) and the Bash tier (`protected-paths-bash-
+ * gate` → already in the bash-scanner module via `runProtectedScan`).
+ *
+ * # Why a TS port at all?
+ *
+ * The bash helper is sourced into both `settings-protection.sh` and
+ * the Bash-tier scanner caller. Now that settings-protection.sh is
+ * being moved to Node-binary in 0.35.0, the protected-list resolution
+ * needs to land in TypeScript too — otherwise the new `runSettingsProtection`
+ * would have to shell out to bash to read the list, which defeats the
+ * point of the Node-binary migration.
+ *
+ * # Kill-switch invariants (NON-RELAXABLE)
+ *
+ * These are ALWAYS protected, even when listed in `protected_paths_relax`:
+ *
+ *   .rea/HALT                      — the kill switch itself
+ *   .rea/policy.yaml               — the policy that defines all enforcement
+ *   .claude/settings.json          — the hook registration that activates rea
+ *   .rea/last-review.cache.json    — verdict-cache security boundary
+ *   .rea/last-review.json          — operator forensic snapshot
+ *
+ * # Policy interaction
+ *
+ *   - `protected_writes` (optional list): when set, FULLY REPLACES the
+ *     hardcoded default. Kill-switch invariants are added back
+ *     defensively. The override pattern set is tracked separately so
+ *     `isProtected()` can prioritize override matches over the
+ *     extension-surface allow-list (helix-020 G2 fix).
+ *   - `protected_paths_relax` (list): SUBTRACTS from whatever the
+ *     effective set is. Kill-switch invariants in this list are silently
+ *     dropped + an advisory is emitted to stderr (caller's responsibility
+ *     to surface).
+ */
+export const KILL_SWITCH_INVARIANTS = [
+    '.claude/settings.json',
+    '.rea/policy.yaml',
+    '.rea/HALT',
+    '.rea/last-review.cache.json',
+    '.rea/last-review.json',
+];
+/**
+ * Hardcoded historical default — the 7 patterns the bash helper ships
+ * (`REA_PROTECTED_PATTERNS_FULL`). Suffix `/` indicates prefix match;
+ * no suffix means case-insensitive exact match.
+ */
+export const PROTECTED_PATTERNS_FULL = [
+    '.claude/settings.json',
+    '.claude/settings.local.json',
+    '.husky/',
+    '.rea/policy.yaml',
+    '.rea/HALT',
+    '.rea/last-review.cache.json',
+    '.rea/last-review.json',
+];
+/**
+ * Patch-session patterns — protected from agents by default but
+ * unlockable by setting `REA_HOOK_PATCH_SESSION=<reason>`. Mirrors
+ * `PATCH_SESSION_PATTERNS` in settings-protection.sh §6b.
+ */
+export const PATCH_SESSION_PATTERNS = ['.claude/hooks/'];
+/**
+ * Documented husky extension surface — `.husky/{commit-msg,pre-push,
+ * pre-commit,prepare-commit-msg}.d/*`. Consumers write extension
+ * fragments here freely; the §6 prefix block on `.husky/` would
+ * otherwise catch them.
+ *
+ * The bare directory itself (e.g. `.husky/pre-push.d/`) is NOT
+ * considered extension-surface — only fragments INSIDE the surface.
+ */
+export function isExtensionSurface(p) {
+    const lower = p.toLowerCase();
+    const surfaces = [
+        '.husky/commit-msg.d/',
+        '.husky/pre-push.d/',
+        '.husky/pre-commit.d/',
+        '.husky/prepare-commit-msg.d/',
+    ];
+    // Refuse the bare directory itself.
+    for (const s of surfaces) {
+        if (lower === s)
+            return false;
+        if (lower === s.slice(0, -1))
+            return false; // without trailing slash
+    }
+    for (const s of surfaces) {
+        if (lower.startsWith(s) && lower.length > s.length) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolve the effective hard-protected pattern set against policy.
+ * Pure function — no I/O, no stderr emission. Stderr advisories come
+ * back as strings so the caller can route them appropriately.
+ */
+export function resolveProtectedPatterns(input = {}) {
+    const writes = input.protectedWrites;
+    const relax = input.protectedPathsRelax ?? [];
+    // 1. Compose the BASE list.
+    const baseList = [];
+    if (writes !== undefined) {
+        // protected_writes set — replaces the default.
+        for (const w of writes) {
+            if (typeof w === 'string' && w.length > 0)
+                baseList.push(w);
+        }
+        // Add kill-switch invariants if not already present (case-insensitive).
+        for (const inv of KILL_SWITCH_INVARIANTS) {
+            const invLc = inv.toLowerCase();
+            if (!baseList.some((b) => b.toLowerCase() === invLc)) {
+                baseList.push(inv);
+            }
+        }
+    }
+    else {
+        for (const pat of PROTECTED_PATTERNS_FULL)
+            baseList.push(pat);
+    }
+    // 2. Validate relax entries — kill-switch invariants are non-relaxable.
+    const advisories = [];
+    const relaxedSet = [];
+    for (const r of relax) {
+        if (typeof r !== 'string' || r.length === 0)
+            continue;
+        if (KILL_SWITCH_INVARIANTS.some((inv) => inv.toLowerCase() === r.toLowerCase())) {
+            advisories.push(`rea: protected_paths_relax: ${r} is a kill-switch invariant and cannot be relaxed; ignoring.\n`);
+        }
+        else {
+            relaxedSet.push(r);
+        }
+    }
+    // 3. Build the effective list — base entries NOT in relaxed set
+    //    (case-insensitive comparison).
+    const patterns = [];
+    for (const pat of baseList) {
+        const patLc = pat.toLowerCase();
+        const relaxed = relaxedSet.some((r) => r.toLowerCase() === patLc);
+        if (!relaxed)
+            patterns.push(pat);
+    }
+    // 4. Build the OVERRIDE subset (only entries from `protected_writes`,
+    //    NOT kill-switch invariants added back defensively). Mirrors
+    //    REA_PROTECTED_OVERRIDE_PATTERNS in the bash helper.
+    const overridePatterns = [];
+    if (writes !== undefined) {
+        for (const w of writes) {
+            if (typeof w !== 'string' || w.length === 0)
+                continue;
+            const wLc = w.toLowerCase();
+            const relaxed = relaxedSet.some((r) => r.toLowerCase() === wLc);
+            if (!relaxed)
+                overridePatterns.push(w);
+        }
+    }
+    return { patterns, overridePatterns, advisories };
+}
+/**
+ * Match a project-relative path against a pattern list. Mirrors the
+ * shell exact-equal AND the trailing-slash prefix-glob shapes,
+ * case-INSENSITIVE.
+ *
+ * Returns the matched pattern (preserving its original case) or `null`.
+ */
+export function matchAny(pathLc, patterns) {
+    for (const pattern of patterns) {
+        const patternLc = pattern.toLowerCase();
+        if (pathLc === patternLc)
+            return pattern;
+        if (patternLc.endsWith('/') && pathLc.startsWith(patternLc))
+            return pattern;
+    }
+    return null;
+}
+/**
+ * Full equivalent of `rea_path_is_protected` from the bash helper.
+ * Three-step decision:
+ *
+ *   1. Explicit `protected_writes` overrides win FIRST (helix-020 G2).
+ *   2. Extension-surface allow-list short-circuits "not protected"
+ *      for `.husky/{commit-msg,pre-push,pre-commit,prepare-commit-msg}.d`
+ *      fragments.
+ *   3. Default hard-protected list (kill-switch invariants + the
+ *      historical patterns from PROTECTED_PATTERNS_FULL).
+ */
+export function isProtected(pathRel, resolution) {
+    const lower = pathRel.toLowerCase();
+    // 1. Explicit overrides win.
+    const overrideHit = matchAny(lower, resolution.overridePatterns);
+    if (overrideHit !== null) {
+        return { protected: true, matchedPattern: overrideHit };
+    }
+    // 2. Extension-surface short-circuit.
+    if (isExtensionSurface(pathRel)) {
+        return { protected: false, matchedPattern: null };
+    }
+    // 3. Default protected list.
+    const defaultHit = matchAny(lower, resolution.patterns);
+    if (defaultHit !== null) {
+        return { protected: true, matchedPattern: defaultHit };
+    }
+    return { protected: false, matchedPattern: null };
+}
+/**
+ * Strip C0/C1 control characters from a string before echoing it back to
+ * the operator. Mirrors `sanitize_for_stderr` in settings-protection.sh.
+ *
+ * Byte ranges stripped (after UTF-16→code-point):
+ *   –  — C0 controls (BEL, BS, HT, LF, CR, ESC, …)
+ *            — DEL
+ *   €–Ÿ  — C1 controls (CSI, OSC, …)
+ *
+ * String-level filter — does NOT operate on raw bytes. Sufficient for
+ * the bash helper's use case: file-name display in error messages.
+ */
+export function sanitizeForStderr(s) {
+    let out = '';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if ((cp >= 0x00 && cp <= 0x1f) || cp === 0x7f || (cp >= 0x80 && cp <= 0x9f)) {
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}

package/dist/hooks/_lib/segments.js

@@ -467,6 +467,50 @@ function splitSegmentsRecursive(cmd, depth) {
     }
     return out;
 }
+/**
+ * Test whether a flag token is a `-c`-class introducer.
+ *
+ * Bash accepts `-c` combined with any other short single-char flags in
+ * a single short-flag bundle: `-c`, `-lc`, `-lic`, `-cli`, `-lci`,
+ * `-cil`, `-ilc`, etc. The bash cmd-segments.sh `WRAP` regex lists
+ * a non-exhaustive defensive subset (`c|lc|lic|ic|cl|cli|li|il`) but
+ * bash itself accepts ANY short-flag bundle that contains a `c`.
+ *
+ * The TS detector mirrors bash semantics: a SHORT-flag bundle
+ * (`-letters`, single leading `-`) whose letter set contains `c` is
+ * an introducer. The separated `--c` long-flag form is also
+ * recognized for parity with the bash WRAP regex's `--c` alternation.
+ *
+ * Long flags (`--rcfile`, `--noprofile`, `--login`, `--init-file`)
+ * are NOT introducers regardless of whether they contain the letter
+ * `c` — bash's long-options namespace is disjoint from the `-c`
+ * payload-execute semantics.
+ *
+ * 0.36.0 audit-trail:
+ *   - Charter item 4 / 0.34.0 codex round-7 P2 #1: pre-fix the test
+ *     was `/c/i.test(flag.replace(/^--?/, ''))` which over-matched on
+ *     every flag with a `c` in its name (`--rcfile`, `--noprofile`).
+ *   - 0.36.0 codex round-1 P1: the first fix attempt used an explicit
+ *     allowlist `Set` mirroring the bash WRAP regex's explicit
+ *     alternation, which was a NARROWING vs the pre-fix behavior —
+ *     valid combined-flag forms like `-lci`, `-cil`, `-ilc` were not
+ *     in the allowlist and stopped unwrapping, reopening a bypass
+ *     surface against env-file-protection / dependency-audit-gate /
+ *     dangerous-bash matchers. This function restores parity with
+ *     bash itself: any short-flag bundle containing `c` qualifies.
+ */
+function isCDashIntroducer(flag) {
+    // Separated long-flag form (rare but bash accepts it).
+    if (flag === '--c')
+        return true;
+    // Short-flag bundle: single leading `-`, then one-or-more letters.
+    // The bundle is a `-c` introducer iff it contains the letter `c`
+    // (any position, any other-letters mix).
+    const m = /^-([A-Za-z]+)$/.exec(flag);
+    if (m === null)
+        return false;
+    return /c/i.test(m[1] ?? '');
+}
 /**
  * Recognize a nested-shell wrapper segment and return the unquoted
  * payload string. Returns `null` when the segment is not a wrapper.
@@ -554,15 +598,29 @@ function extractNestedShellPayload(head) {
             return null;
         const flag = flagMatch[0] ?? '';
         cursor += flag.length;
-        // Recognized flag-token shapes:
-        //   `-c` `-l` `-i` `-e` `-lc` `-lic` `-ic` `-cl` `-cli` `-li` `-il`
-        //   `--c` `--noprofile` (etc.) — we don't enforce the full list,
-        //   just that it's `-<letters>` or `--<letters>`.
+        // Recognized flag-token shapes (parity with cmd-segments.sh WRAP):
+        //   - pre-flags (no `-c` yet): `-l`, `-i`, `-e`, `-li`, `-il`,
+        //     `--noprofile`, `--rcfile`, `--login` (etc.)
+        //   - `-c`-class introducer: exactly `-c`, `-lc`, `-lic`, `-cl`,
+        //     `-cli`, `-li`, `-il`, `-ic` (the bash WRAP regex's
+        //     `-(c|lc|lic|ic|cl|cli|li|il)` set), OR separated `--c`.
+        //
+        // 0.36.0 audit-trail (charter item 4 / 0.34.0 codex round-7 P2 #1):
+        // pre-fix the test `/c/i.test(flag.replace(/^--?/, ''))` treated
+        // ANY flag containing the letter `c` as a `-c` introducer. This
+        // false-positived on benign flags like `--rcfile`, `--noprofile`
+        // (with `c` in the name), causing the walker to "commit" to a -c
+        // unwrap, advance past the flag, and then either fail to find a
+        // quoted payload or unwrap something that was never a shell-payload
+        // body. Net effect: over-trigger of nested-shell unwrap, with
+        // downstream advisory matchers seeing payloads that weren't ever
+        // shell-payloads. Fix restricts the introducer set to the exact
+        // WRAP-regex shapes; any other flag shape continues the flag walk
+        // (still valid — pre-flags before `-c` are accepted) but does NOT
+        // mark `sawCFlag = true`.
         if (!/^--?[A-Za-z]+$/.test(flag))
             return null;
-        // Does this flag contain `c` (the -c introducer letter)?
-        // `--c` also counts (rare but bash accepts).
-        if (/c/i.test(flag.replace(/^--?/, ''))) {
+        if (isCDashIntroducer(flag)) {
             sawCFlag = true;
             // Continue the loop — the payload is the NEXT non-flag token.
             // (Bash's argv parser stops walking flags as soon as it sees -c,
@@ -570,6 +628,8 @@ function extractNestedShellPayload(head) {
             // safety; the bash WRAP regex similarly tolerates trailing
             // flag-like tokens before the quoted body.)
         }
+        // Else: a pre-flag (e.g. `-l`, `--rcfile`, `--noprofile`) — keep
+        // walking; if a later token IS in `CDASH_INTRODUCERS` we'll fire.
     }
     if (!sawCFlag)
         return null;

package/dist/hooks/blocked-paths-bash-gate/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Node-binary port of `hooks/blocked-paths-bash-gate.sh`.
+ *
+ * 0.35.0 Phase 3 port (paired tier-1 scanner-shim). This was a thin
+ * bash shim over `rea hook scan-bash --mode blocked` — the heavy
+ * lifting (the parser-backed AST walker that closes 9 bypass classes
+ * from helix-023 + discord-ops Round 13) lives in `src/hooks/bash-
+ * scanner/`.
+ *
+ * The Node-binary port preserves the same byte-for-byte verdict shape
+ * and exit-code contract but eliminates the bash-shim → node-CLI →
+ * scanner-module subprocess hop. The caller is now `rea hook blocked-
+ * paths-bash-gate`, which calls `runBlockedScan` directly.
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin via `parseHookPayload`. Empty/missing command → exit 0
+ *      (the bash gate's `[[ -z "$payload" ]] && exit 0` guard).
+ *   3. Non-Bash tool calls bypass — Claude Code's hook matcher already
+ *      filters to Bash but defense-in-depth.
+ *   4. Load policy permissively (a partial/migrating policy.yaml with
+ *      unknown keys must NOT collapse the `blocked_paths` list — same
+ *      lesson from 0.33.0 round-1 P3 + 0.34.0 round-2 P2).
+ *   5. Empty `blocked_paths` → allow (no-op). Mirrors
+ *      `runBlockedScan({ blockedPaths: [] }, cmd)` short-circuit.
+ *   6. Run `runBlockedScan` against the command.
+ *   7. Verdict `block` → exit 2 with the scanner's reason. Verdict
+ *      `allow` → exit 0.
+ *
+ * Audit-log parity: emits a `rea.hook.blocked-paths-bash-gate` entry
+ * (best-effort, never blocks the verdict on audit failure).
+ */
+import type { Buffer } from 'node:buffer';
+import { type Verdict } from '../bash-scanner/index.js';
+export interface BlockedPathsBashGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+}
+export interface BlockedPathsBashGateResult {
+    exitCode: number;
+    stderr: string;
+    /** Final verdict from the scanner (test seam). */
+    verdict: Verdict | null;
+}
+/**
+ * Pure executor. Returns `{ exitCode, stderr, verdict }`; the CLI
+ * wrapper translates them into `process.stderr.write` + `process.exit`.
+ */
+export declare function runBlockedPathsBashGate(options?: BlockedPathsBashGateOptions): Promise<BlockedPathsBashGateResult>;
+/**
+ * CLI entry point — `rea hook blocked-paths-bash-gate`.
+ */
+export declare function runHookBlockedPathsBashGate(options?: BlockedPathsBashGateOptions): Promise<void>;

package/dist/hooks/blocked-paths-bash-gate/index.js

@@ -0,0 +1,175 @@
+/**
+ * Node-binary port of `hooks/blocked-paths-bash-gate.sh`.
+ *
+ * 0.35.0 Phase 3 port (paired tier-1 scanner-shim). This was a thin
+ * bash shim over `rea hook scan-bash --mode blocked` — the heavy
+ * lifting (the parser-backed AST walker that closes 9 bypass classes
+ * from helix-023 + discord-ops Round 13) lives in `src/hooks/bash-
+ * scanner/`.
+ *
+ * The Node-binary port preserves the same byte-for-byte verdict shape
+ * and exit-code contract but eliminates the bash-shim → node-CLI →
+ * scanner-module subprocess hop. The caller is now `rea hook blocked-
+ * paths-bash-gate`, which calls `runBlockedScan` directly.
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin via `parseHookPayload`. Empty/missing command → exit 0
+ *      (the bash gate's `[[ -z "$payload" ]] && exit 0` guard).
+ *   3. Non-Bash tool calls bypass — Claude Code's hook matcher already
+ *      filters to Bash but defense-in-depth.
+ *   4. Load policy permissively (a partial/migrating policy.yaml with
+ *      unknown keys must NOT collapse the `blocked_paths` list — same
+ *      lesson from 0.33.0 round-1 P3 + 0.34.0 round-2 P2).
+ *   5. Empty `blocked_paths` → allow (no-op). Mirrors
+ *      `runBlockedScan({ blockedPaths: [] }, cmd)` short-circuit.
+ *   6. Run `runBlockedScan` against the command.
+ *   7. Verdict `block` → exit 2 with the scanner's reason. Verdict
+ *      `allow` → exit 0.
+ *
+ * Audit-log parity: emits a `rea.hook.blocked-paths-bash-gate` entry
+ * (best-effort, never blocks the verdict on audit failure).
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
+import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
+import { runBlockedScan } from '../bash-scanner/index.js';
+import { appendAuditRecord, InvocationStatus, Tier } from '../../audit/append.js';
+/**
+ * Load `blocked_paths` from `<reaRoot>/.rea/policy.yaml` permissively.
+ *
+ * Why not `loadPolicy`? The strict zod loader refuses partial / unknown
+ * keys (it's strict-mode by design). A consumer running a migrating
+ * policy.yaml or holding legacy keys would have their `blocked_paths`
+ * effectively wiped — silently. The bash gate's pre-0.35.0 yaml grep
+ * scanned for the key directly with no schema validation; we mirror
+ * that permissive posture by reading `blocked_paths` from the parsed
+ * YAML directly without validation.
+ *
+ * Returns `[]` on any failure (missing file, bad YAML, missing key,
+ * unexpected type). Empty list is the "no enforcement" no-op state.
+ */
+function loadBlockedPathsPermissive(reaRoot) {
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    if (!fs.existsSync(policyPath))
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const obj = parsed;
+    const bp = obj['blocked_paths'];
+    if (!Array.isArray(bp))
+        return [];
+    const out = [];
+    for (const entry of bp) {
+        if (typeof entry === 'string' && entry.length > 0) {
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Pure executor. Returns `{ exitCode, stderr, verdict }`; the CLI
+ * wrapper translates them into `process.stderr.write` + `process.exit`.
+ */
+export async function runBlockedPathsBashGate(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, verdict: { verdict: 'block', reason: 'rea HALT active' } };
+    }
+    // 2. Read + parse 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(`blocked-paths-bash-gate: ${err.message} — refusing on uncertainty.\n`);
+            return { exitCode: 2, stderr, verdict: { verdict: 'block', reason: err.message } };
+        }
+        throw err;
+    }
+    // 3. Non-Bash tool calls bypass.
+    if (toolName !== '' && toolName !== 'Bash') {
+        return { exitCode: 0, stderr, verdict: null };
+    }
+    // 4. Empty command → allow.
+    if (cmd.length === 0) {
+        return { exitCode: 0, stderr, verdict: null };
+    }
+    // 5. Load policy permissively.
+    const blockedPaths = loadBlockedPathsPermissive(reaRoot);
+    // 6. Empty list → allow.
+    if (blockedPaths.length === 0) {
+        return { exitCode: 0, stderr, verdict: { verdict: 'allow' } };
+    }
+    // 7. Scan.
+    const verdict = runBlockedScan({ reaRoot, blockedPaths }, cmd);
+    // 8. Audit — best-effort, never changes verdict.
+    try {
+        await appendAuditRecord(reaRoot, {
+            tool_name: 'rea.hook.blocked-paths-bash-gate',
+            server_name: 'rea',
+            tier: Tier.Read,
+            status: verdict.verdict === 'allow' ? InvocationStatus.Allowed : InvocationStatus.Denied,
+            metadata: {
+                verdict: verdict.verdict,
+                ...(verdict.detected_form !== undefined ? { detected_form: verdict.detected_form } : {}),
+                ...(verdict.hit_pattern !== undefined ? { hit_pattern: verdict.hit_pattern } : {}),
+                command_preview: cmd.slice(0, 256),
+            },
+        });
+    }
+    catch {
+        /* best-effort */
+    }
+    if (verdict.verdict === 'block') {
+        if (typeof verdict.reason === 'string' && verdict.reason.length > 0) {
+            writeStderr(verdict.reason + '\n');
+        }
+        return { exitCode: 2, stderr, verdict };
+    }
+    return { exitCode: 0, stderr, verdict };
+}
+/**
+ * CLI entry point — `rea hook blocked-paths-bash-gate`.
+ */
+export async function runHookBlockedPathsBashGate(options = {}) {
+    const result = await runBlockedPathsBashGate({
+        ...options,
+        stderrWrite: (s) => process.stderr.write(s),
+    });
+    process.exit(result.exitCode);
+}

package/dist/hooks/blocked-paths-enforcer/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Node-binary port of `hooks/blocked-paths-enforcer.sh`.
+ *
+ * 0.35.0 Phase 4 port (paired Write/Edit tier). Enforces
+ * `policy.blocked_paths` against Write/Edit/MultiEdit/NotebookEdit
+ * tool calls. Sibling of `blocked-paths-bash-gate` (Bash-tier) — same
+ * policy data, different surface.
+ *
+ * Behavioral contract — preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with shared banner.
+ *   2. Read stdin, extract `tool_input.file_path` (or `notebook_path`).
+ *      Missing/empty → exit 0.
+ *   3. Load policy permissively (a partial / migrating policy.yaml
+ *      must NOT collapse the blocked_paths list).
+ *   4. Empty `blocked_paths` → exit 0.
+ *   5. §5a path-traversal rejection. Refuses any path with a `..`
+ *      segment in EITHER the raw form OR the normalized form. Also
+ *      catches URL-encoded traversal (`%2E%2E/`, `..%2F`, etc.)
+ *      against the raw input.
+ *   6. §5a-bis interior `/./` segment rejection (0.29.0 helix-/./-class).
+ *      NORMALIZED form only — `normalize_path` already strips leading
+ *      `./` segments, so anything remaining is interior by construction.
+ *   7. Agent-writable allow-list short-circuit (`.rea/tasks.jsonl`,
+ *      `.rea/audit/`) — even if blocked_paths includes `.rea/` as a
+ *      prefix block, these are PM-data writeables.
+ *   8. Match the normalized path against each blocked entry:
+ *        - directory prefix (entry ends with `/`)
+ *        - glob (entry contains `*`)
+ *        - exact (lower-case, case-INSENSITIVE)
+ *      Match → exit 2 with reason.
+ *   9. §H.2 intermediate-symlink resolution. If the parent dir exists,
+ *      resolve its realpath. If the resolved target falls inside a
+ *      blocked entry, refuse.
+ *
+ * Audit-log parity: emits a `rea.hook.blocked-paths-enforcer` entry.
+ */
+import type { Buffer } from 'node:buffer';
+export interface BlockedPathsEnforcerOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+}
+export interface BlockedPathsEnforcerResult {
+    exitCode: number;
+    stderr: string;
+    /** Test seam — when the gate blocks, the matched blocked-paths entry. */
+    matched: string | null;
+}
+export declare function runBlockedPathsEnforcer(options?: BlockedPathsEnforcerOptions): Promise<BlockedPathsEnforcerResult>;
+export declare function runHookBlockedPathsEnforcer(options?: BlockedPathsEnforcerOptions): Promise<void>;