@bookedsolid/rea 0.34.0 → 0.35.0

package/dist/cli/hook.js

@@ -46,6 +46,10 @@ import { runHookArchitectureReviewGate } from '../hooks/architecture-review-gate
 import { runHookDangerousBashInterceptor } from '../hooks/dangerous-bash-interceptor/index.js';
 import { runHookLocalReviewGate } from '../hooks/local-review-gate/index.js';
 import { runHookSecretScanner } from '../hooks/secret-scanner/index.js';
+import { runHookBlockedPathsBashGate } from '../hooks/blocked-paths-bash-gate/index.js';
+import { runHookProtectedPathsBashGate } from '../hooks/protected-paths-bash-gate/index.js';
+import { runHookBlockedPathsEnforcer } from '../hooks/blocked-paths-enforcer/index.js';
+import { runHookSettingsProtection } from '../hooks/settings-protection/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';
@@ -1022,6 +1026,30 @@ export function registerHookCommand(program) {
         .action(async () => {
         await runHookSecretScanner();
     });
+    hook
+        .command('blocked-paths-bash-gate')
+        .description('Node-binary port of `hooks/blocked-paths-bash-gate.sh` (0.35.0). PreToolUse Bash gate refusing shell writes to `policy.blocked_paths` entries. Calls the AST-backed `runBlockedScan` directly (no shim→CLI→scanner subprocess hop). Permissive policy read — partial/migrating policy.yaml does NOT collapse the blocked_paths list. Empty list → no-op. Verdict `block` → exit 2; `allow` → exit 0.')
+        .action(async () => {
+        await runHookBlockedPathsBashGate();
+    });
+    hook
+        .command('protected-paths-bash-gate')
+        .description('Node-binary port of `hooks/protected-paths-bash-gate.sh` (0.35.0). PreToolUse Bash gate refusing shell-redirect/cp/mv/install/etc. to protected paths (.claude/settings.json, .claude/hooks/*, .husky/*, .rea/policy.yaml, .rea/HALT). Honors `policy.protected_writes` (full override) + `policy.protected_paths_relax` (subtractor). REA_HOOK_PATCH_SESSION relaxes .claude/hooks/ for the session.')
+        .action(async () => {
+        await runHookProtectedPathsBashGate();
+    });
+    hook
+        .command('blocked-paths-enforcer')
+        .description('Node-binary port of `hooks/blocked-paths-enforcer.sh` (0.35.0). PreToolUse Write/Edit/MultiEdit/NotebookEdit gate refusing writes to `policy.blocked_paths` entries. §5a path-traversal reject + §5a-bis interior `/./` reject + §H.2 intermediate-symlink resolution. Agent-writable allow-list (.rea/tasks.jsonl, .rea/audit/) short-circuits before policy match.')
+        .action(async () => {
+        await runHookBlockedPathsEnforcer();
+    });
+    hook
+        .command('settings-protection')
+        .description('Node-binary port of `hooks/settings-protection.sh` (0.35.0, the LARGEST hook in the repo at 582 LOC of bash). PreToolUse Write/Edit/MultiEdit/NotebookEdit gate protecting .claude/settings.json, .claude/hooks/*, .husky/*, .rea/policy.yaml, .rea/HALT, .rea/last-review.{json,cache.json}. Honors `protected_writes` (full override) + `protected_paths_relax` (subtractor, kill-switch invariants non-relaxable). §5b extension-surface allow-list for .husky/{commit-msg,pre-push,pre-commit,prepare-commit-msg}.d/* with final-component and intermediate-directory symlink refusal. §6c intermediate-symlink resolution. §6b REA_HOOK_PATCH_SESSION unlock for .claude/hooks/ with hash-chained audit append (fail-closed on append failure).')
+        .action(async () => {
+        await runHookSettingsProtection();
+    });
     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/path-normalize.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared path-normalization primitives for the Node-binary hook tier.
+ *
+ * 0.35.0 — TypeScript port of `hooks/_lib/path-normalize.sh`. The bash
+ * helper is the single source of truth shared between settings-
+ * protection.sh and blocked-paths-enforcer.sh (and the Bash-tier
+ * gates' relevance pre-checks). The 4 hooks landing in 0.35.0 all
+ * need the same normalization to stay byte-parity with their bash
+ * counterparts.
+ *
+ * Functions:
+ *   - `normalizePath(p, reaRoot)` — project-relative form. Strip
+ *     reaRoot prefix → URL-decode `%2F`/`%2E`/`%20`/`%5C` → translate
+ *     `\` → `/` → strip leading `./` segments.
+ *   - `hasTraversalSegment(p)` — true if any `..` segment exists.
+ *   - `hasInteriorDotSegment(p)` — true if any interior `/./` segment
+ *     exists (0.29.0 helix-/./-class refusal).
+ *   - `resolveParentRealpath(targetPath)` — pure-Node equivalent of
+ *     the bash `resolve_parent_realpath`. Returns the realpath of the
+ *     parent dir, walking up to the nearest existing ancestor if the
+ *     parent doesn't exist yet, then appending the unresolved tail.
+ *   - `resolveCanonRoot(reaRoot)` — `cd -P && pwd -P` equivalent of
+ *     the project root, with macOS `/var` → `/private/var` collapse.
+ *
+ * All functions are pure (no logging, no exit) — the caller decides
+ * how to surface failures.
+ */
+/**
+ * Project-relative form of a file path. Mirrors the bash helper
+ * byte-for-byte.
+ *
+ * Order of operations (lifted from `hooks/_lib/path-normalize.sh`):
+ *   1. Strip leading `<reaRoot>/` prefix.
+ *   2. URL-decode `%2F`, `%2E`, `%20`, `%5C` (case-insensitive). Other
+ *      percent-encodings are left untouched — the bash helper only
+ *      decodes this fixed set.
+ *   3. Translate backslash separators to forward slashes.
+ *   4. Strip leading `./` segments. Interior `./` is NOT stripped (that
+ *      would corrupt `..` traversals — see §5a-bis).
+ */
+export declare function normalizePath(input: string, reaRoot: string): string;
+/**
+ * True if any `/../` segment is present (bracketing the input with `/`
+ * on each side so leading/trailing `..` segments still count). Mirrors
+ * the bash `case "/$path/" in *<slash>..<slash>*) traversal=1` shape
+ * (the literal asterisk-slash form is omitted to keep the JSDoc block
+ * from terminating early).
+ */
+export declare function hasTraversalSegment(p: string): boolean;
+/**
+ * True if any interior `/./` segment is present. The bash helper uses
+ * the equivalent `*<slash>.<slash>*` case-glob shape; leading `./` is
+ * stripped by normalizePath, so anything that survives is interior.
+ */
+export declare function hasInteriorDotSegment(p: string): boolean;
+/**
+ * Canonicalize a project root the same way bash `cd -P && pwd -P`
+ * would — follow every symlink in the path to the physical form. On
+ * macOS this collapses `/var/...` → `/private/var/...` because `/var`
+ * is itself a symlink. Used to make REA_ROOT prefix comparisons
+ * symmetric against realpath'd children.
+ *
+ * Returns the original `reaRoot` (unmodified) when realpath fails —
+ * the bash helper falls back the same way via `|| resolved=""`.
+ */
+export declare function resolveCanonRoot(reaRoot: string): string;
+/**
+ * Resolve the realpath of the parent directory of `targetPath`. Pure-
+ * Node mirror of `hooks/_lib/path-normalize.sh::resolve_parent_realpath`,
+ * including the 0.21.2 helix-022 #1 nearest-existing-ancestor walk.
+ *
+ * Returns:
+ *   - The resolved realpath of the parent when it exists.
+ *   - When the parent doesn't exist on disk: walk UP looking for the
+ *     nearest existing ancestor, realpath that, then append the
+ *     unresolved tail. This catches symlink walks where the terminal
+ *     directory is created mid-segment (`mkdir -p linkroot/.husky/sub`).
+ *   - Empty string when no existing ancestor inside REA_ROOT could be
+ *     resolved.
+ */
+export declare function resolveParentRealpath(targetPath: string): string;

package/dist/hooks/_lib/path-normalize.js

@@ -0,0 +1,171 @@
+/**
+ * Shared path-normalization primitives for the Node-binary hook tier.
+ *
+ * 0.35.0 — TypeScript port of `hooks/_lib/path-normalize.sh`. The bash
+ * helper is the single source of truth shared between settings-
+ * protection.sh and blocked-paths-enforcer.sh (and the Bash-tier
+ * gates' relevance pre-checks). The 4 hooks landing in 0.35.0 all
+ * need the same normalization to stay byte-parity with their bash
+ * counterparts.
+ *
+ * Functions:
+ *   - `normalizePath(p, reaRoot)` — project-relative form. Strip
+ *     reaRoot prefix → URL-decode `%2F`/`%2E`/`%20`/`%5C` → translate
+ *     `\` → `/` → strip leading `./` segments.
+ *   - `hasTraversalSegment(p)` — true if any `..` segment exists.
+ *   - `hasInteriorDotSegment(p)` — true if any interior `/./` segment
+ *     exists (0.29.0 helix-/./-class refusal).
+ *   - `resolveParentRealpath(targetPath)` — pure-Node equivalent of
+ *     the bash `resolve_parent_realpath`. Returns the realpath of the
+ *     parent dir, walking up to the nearest existing ancestor if the
+ *     parent doesn't exist yet, then appending the unresolved tail.
+ *   - `resolveCanonRoot(reaRoot)` — `cd -P && pwd -P` equivalent of
+ *     the project root, with macOS `/var` → `/private/var` collapse.
+ *
+ * All functions are pure (no logging, no exit) — the caller decides
+ * how to surface failures.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Project-relative form of a file path. Mirrors the bash helper
+ * byte-for-byte.
+ *
+ * Order of operations (lifted from `hooks/_lib/path-normalize.sh`):
+ *   1. Strip leading `<reaRoot>/` prefix.
+ *   2. URL-decode `%2F`, `%2E`, `%20`, `%5C` (case-insensitive). Other
+ *      percent-encodings are left untouched — the bash helper only
+ *      decodes this fixed set.
+ *   3. Translate backslash separators to forward slashes.
+ *   4. Strip leading `./` segments. Interior `./` is NOT stripped (that
+ *      would corrupt `..` traversals — see §5a-bis).
+ */
+export function normalizePath(input, reaRoot) {
+    let p = input;
+    // 1. Strip $REA_ROOT/ prefix.
+    const prefix = reaRoot.endsWith(path.sep) ? reaRoot : reaRoot + '/';
+    if (p === reaRoot || p.startsWith(prefix)) {
+        if (p === reaRoot) {
+            p = '';
+        }
+        else {
+            p = p.slice(prefix.length);
+        }
+    }
+    // 2. URL-decode the fixed set: %2F→/, %2E→., %20→' ', %5C→\.
+    p = p
+        .replace(/%2[Ff]/g, '/')
+        .replace(/%2[Ee]/g, '.')
+        .replace(/%20/g, ' ')
+        .replace(/%5[Cc]/g, '\\');
+    // 3. Translate backslash separators to forward slashes.
+    p = p.replace(/\\/g, '/');
+    // 4. Strip leading `./` segments only.
+    while (p.startsWith('./')) {
+        p = p.slice(2);
+    }
+    return p;
+}
+/**
+ * True if any `/../` segment is present (bracketing the input with `/`
+ * on each side so leading/trailing `..` segments still count). Mirrors
+ * the bash `case "/$path/" in *<slash>..<slash>*) traversal=1` shape
+ * (the literal asterisk-slash form is omitted to keep the JSDoc block
+ * from terminating early).
+ */
+export function hasTraversalSegment(p) {
+    const bracketed = `/${p}/`;
+    return bracketed.includes('/../');
+}
+/**
+ * True if any interior `/./` segment is present. The bash helper uses
+ * the equivalent `*<slash>.<slash>*` case-glob shape; leading `./` is
+ * stripped by normalizePath, so anything that survives is interior.
+ */
+export function hasInteriorDotSegment(p) {
+    const bracketed = `/${p}/`;
+    return bracketed.includes('/./');
+}
+/**
+ * Canonicalize a project root the same way bash `cd -P && pwd -P`
+ * would — follow every symlink in the path to the physical form. On
+ * macOS this collapses `/var/...` → `/private/var/...` because `/var`
+ * is itself a symlink. Used to make REA_ROOT prefix comparisons
+ * symmetric against realpath'd children.
+ *
+ * Returns the original `reaRoot` (unmodified) when realpath fails —
+ * the bash helper falls back the same way via `|| resolved=""`.
+ */
+export function resolveCanonRoot(reaRoot) {
+    try {
+        return fs.realpathSync(reaRoot);
+    }
+    catch {
+        return reaRoot;
+    }
+}
+/**
+ * Resolve the realpath of the parent directory of `targetPath`. Pure-
+ * Node mirror of `hooks/_lib/path-normalize.sh::resolve_parent_realpath`,
+ * including the 0.21.2 helix-022 #1 nearest-existing-ancestor walk.
+ *
+ * Returns:
+ *   - The resolved realpath of the parent when it exists.
+ *   - When the parent doesn't exist on disk: walk UP looking for the
+ *     nearest existing ancestor, realpath that, then append the
+ *     unresolved tail. This catches symlink walks where the terminal
+ *     directory is created mid-segment (`mkdir -p linkroot/.husky/sub`).
+ *   - Empty string when no existing ancestor inside REA_ROOT could be
+ *     resolved.
+ */
+export function resolveParentRealpath(targetPath) {
+    const parentDir = path.dirname(targetPath);
+    // Fast path: parent exists. Resolve directly.
+    let parentStat;
+    try {
+        parentStat = fs.statSync(parentDir);
+    }
+    catch {
+        /* falls through to walk-up below */
+    }
+    if (parentStat?.isDirectory()) {
+        try {
+            return fs.realpathSync(parentDir);
+        }
+        catch {
+            return '';
+        }
+    }
+    // Walk up to the nearest existing ancestor; accumulate the tail.
+    let walk = parentDir;
+    let tail = '';
+    // Bound the walk to avoid pathological loops on relative paths.
+    for (let i = 0; i < 64; i++) {
+        if (!walk || walk === '/' || walk === '.')
+            break;
+        try {
+            const s = fs.statSync(walk);
+            if (s.isDirectory())
+                break;
+        }
+        catch {
+            /* keep walking */
+        }
+        const base = path.basename(walk);
+        tail = tail.length > 0 ? `${base}/${tail}` : base;
+        walk = path.dirname(walk);
+    }
+    if (!walk || walk === '/' || walk === '.') {
+        return '';
+    }
+    let resolvedWalk;
+    try {
+        resolvedWalk = fs.realpathSync(walk);
+    }
+    catch {
+        return '';
+    }
+    if (tail.length === 0)
+        return resolvedWalk;
+    return `${resolvedWalk}/${tail}`;
+}

package/dist/hooks/_lib/payload.js

@@ -97,7 +97,7 @@ export function parseHookPayload(raw) {
         }
         const c = ti.command;
         if (c !== undefined && typeof c !== 'string') {
-            throw new TypePayloadError(`hook payload tool_input.command is ${typeof c}, expected string`);
+            throw new TypePayloadError(`hook payload tool_input.command is non-string (got ${typeof c}); expected string`);
         }
         if (typeof c === 'string')
             command = c;

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/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>;