@bookedsolid/rea 0.32.0 → 0.33.0

package/dist/cli/hook.js

@@ -39,6 +39,10 @@ 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 { runHookEnvFileProtection } from '../hooks/env-file-protection/index.js';
+import { runHookDependencyAuditGate } from '../hooks/dependency-audit-gate/index.js';
+import { runHookChangesetSecurityGate } from '../hooks/changeset-security-gate/index.js';
+import { runHookArchitectureReviewGate } from '../hooks/architecture-review-gate/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';
@@ -973,6 +977,30 @@ export function registerHookCommand(program) {
         .action(async () => {
         await runHookAttributionAdvisory();
     });
+    hook
+        .command('env-file-protection')
+        .description('Node-binary port of `hooks/env-file-protection.sh` (0.33.0). Reads a Claude Code PreToolUse Bash payload from stdin; when the command sources, cps, or reads a `.env*`/`.envrc` file via text-reading utilities (cat/head/tail/grep/sed/awk/etc.), exits 2 with banner. Same-segment co-occurrence required for the utility-vs-filename match so multi-segment commands do not false-positive.')
+        .action(async () => {
+        await runHookEnvFileProtection();
+    });
+    hook
+        .command('dependency-audit-gate')
+        .description('Node-binary port of `hooks/dependency-audit-gate.sh` (0.33.0). Reads a Claude Code PreToolUse Bash payload from stdin; when the command is `(npm|pnpm|yarn) (install|i|add) <pkg>`, verifies each named package exists on the npm registry via `npm view <pkg> name` (5s timeout, capped at 5 packages/command). Exit 2 with multi-line banner on any missing package, otherwise exit 0.')
+        .action(async () => {
+        await runHookDependencyAuditGate();
+    });
+    hook
+        .command('changeset-security-gate')
+        .description('Node-binary port of `hooks/changeset-security-gate.sh` (0.33.0). Reads a Claude Code PreToolUse Write/Edit/MultiEdit/NotebookEdit payload from stdin; for writes targeting `.changeset/*.md`, blocks GHSA/CVE pre-disclosure and validates frontmatter (`---`-delimited block with `<pkg>: (patch|minor|major)` + non-empty description). MultiEdit short-circuits frontmatter validation because fragments are not full files. Block emissions use the Claude Code JSON-on-stdout protocol.')
+        .action(async () => {
+        await runHookChangesetSecurityGate();
+    });
+    hook
+        .command('architecture-review-gate')
+        .description('Node-binary port of `hooks/architecture-review-gate.sh` (0.33.0). PostToolUse Write/Edit advisory. Reads `policy.architecture_review.patterns` and prints an advisory banner to stderr when the just-written file matches a configured prefix. ALWAYS exits 0 unless HALT (exit 2). Path normalization handles Windows backslashes + URL-encoding; empty/unset patterns short-circuit silently.')
+        .action(async () => {
+        await runHookArchitectureReviewGate();
+    });
     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/payload.d.ts

@@ -68,6 +68,44 @@ export declare class TypePayloadError extends Error {
  *         non-string type.
  */
 export declare function parseHookPayload(raw: string | Buffer): HookPayload;
+/**
+ * Result of a write-tier hook payload extraction. Covers all four
+ * write-class tools (Write, Edit, MultiEdit, NotebookEdit).
+ */
+export interface WriteHookPayload {
+    /** `tool_name` from the payload, or `''` when absent. */
+    toolName: string;
+    /**
+     * `tool_input.file_path` (Write/Edit/MultiEdit) OR
+     * `tool_input.notebook_path` (NotebookEdit), or `''` when absent.
+     */
+    filePath: string;
+    /**
+     * Concatenated content payload. Resolution order matches
+     * `hooks/_lib/payload-read.sh::extract_write_content`:
+     *
+     *   1. `tool_input.content`                     (Write)
+     *   2. `tool_input.new_string`                  (Edit)
+     *   3. `tool_input.edits[].new_string` joined   (MultiEdit, `\n`)
+     *   4. `tool_input.new_source`                  (NotebookEdit cell)
+     *
+     * Returns `''` when none of these are present. Defensive coercion:
+     * a non-string `new_string`, non-array `edits`, or non-string
+     * fragments fail closed (treated as missing) rather than throwing —
+     * mirrors the bash hook's `.tool_input.new_string // ""` + the
+     * type-guard branches added in 0.16.0.
+     */
+    content: string;
+}
+/**
+ * Parse a Claude Code Write/Edit/MultiEdit/NotebookEdit stdin payload.
+ *
+ * Same fail-closed posture as `parseHookPayload`: malformed JSON →
+ * throws `MalformedPayloadError`; type-mismatched fields → throws
+ * `TypePayloadError`. Callers fail-closed on these for blocking-tier
+ * gates (changeset-security-gate refuses on uncertainty).
+ */
+export declare function parseWriteHookPayload(raw: string | Buffer): WriteHookPayload;
 /**
  * Read all of stdin into a string with a soft byte cap and a hard
  * timeout. Mirrors the `readStdinWithTimeout` helper in

package/dist/hooks/_lib/payload.js

@@ -104,6 +104,85 @@ export function parseHookPayload(raw) {
     }
     return { toolName, command };
 }
+/**
+ * Parse a Claude Code Write/Edit/MultiEdit/NotebookEdit stdin payload.
+ *
+ * Same fail-closed posture as `parseHookPayload`: malformed JSON →
+ * throws `MalformedPayloadError`; type-mismatched fields → throws
+ * `TypePayloadError`. Callers fail-closed on these for blocking-tier
+ * gates (changeset-security-gate refuses on uncertainty).
+ */
+export function parseWriteHookPayload(raw) {
+    const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+    if (text.trim().length === 0) {
+        return { toolName: '', filePath: '', content: '' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new MalformedPayloadError(`hook payload is not valid JSON: ${detail}`);
+    }
+    if (parsed === null) {
+        return { toolName: '', filePath: '', content: '' };
+    }
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new MalformedPayloadError(`hook payload top-level is ${Array.isArray(parsed) ? 'array' : typeof parsed}, expected object`);
+    }
+    const toolName = typeof parsed.tool_name === 'string' ? parsed.tool_name : '';
+    const ti = parsed.tool_input;
+    let filePath = '';
+    let content = '';
+    if (ti !== undefined && ti !== null) {
+        if (typeof ti !== 'object') {
+            throw new TypePayloadError(`hook payload tool_input is ${typeof ti}, expected object`);
+        }
+        // file_path or notebook_path. Both are optional; either string or absent.
+        if (ti.file_path !== undefined) {
+            if (typeof ti.file_path !== 'string') {
+                throw new TypePayloadError(`hook payload tool_input.file_path is ${typeof ti.file_path}, expected string`);
+            }
+            filePath = ti.file_path;
+        }
+        else if (ti.notebook_path !== undefined) {
+            if (typeof ti.notebook_path !== 'string') {
+                throw new TypePayloadError(`hook payload tool_input.notebook_path is ${typeof ti.notebook_path}, expected string`);
+            }
+            filePath = ti.notebook_path;
+        }
+        // Content extraction — same priority order as the bash hook.
+        if (typeof ti.content === 'string' && ti.content.length > 0) {
+            content = ti.content;
+        }
+        else if (typeof ti.new_string === 'string' && ti.new_string.length > 0) {
+            content = ti.new_string;
+        }
+        else if (Array.isArray(ti.edits) && ti.edits.length > 0) {
+            // Defensive: non-string `new_string` fragments collapse to ''
+            // (matches the bash helper's `// ""` + `tostring`). The
+            // concatenation order is bash hook's `join("\n")`.
+            const parts = [];
+            for (const edit of ti.edits) {
+                if (edit === null || typeof edit !== 'object')
+                    continue;
+                const e = edit;
+                if (typeof e.new_string === 'string') {
+                    parts.push(e.new_string);
+                }
+                else {
+                    parts.push('');
+                }
+            }
+            content = parts.join('\n');
+        }
+        else if (typeof ti.new_source === 'string' && ti.new_source.length > 0) {
+            content = ti.new_source;
+        }
+    }
+    return { toolName, filePath, content };
+}
 /**
  * Read all of stdin into a string with a soft byte cap and a hard
  * timeout. Mirrors the `readStdinWithTimeout` helper in

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

@@ -69,6 +69,14 @@ export interface CommandSegment {
  * Split `cmd` into segments using the quote-aware masking → split →
  * unmask pipeline. Returns an array of `{ raw, head }` tuples in the
  * order they appeared in the original command.
+ *
+ * 0.33.0 — nested-shell unwrapping was added on top of the original
+ * 0.32.0 splitter. When a segment's head is `bash -c|-lc|--c PAYLOAD`
+ * or `sh -c|-lc|--c PAYLOAD` (any combination of `-l` and `-c` flags),
+ * the PAYLOAD inside the quoted arg becomes additional segments
+ * appended after the wrapper segment. Mirrors the bash counterpart's
+ * `_rea_unwrap_nested_shells` (helix-017 #3 fix). Recurses up to
+ * `MAX_NESTED_DEPTH` levels.
  */
 export declare function splitSegments(cmd: string): CommandSegment[];
 /**
@@ -98,3 +106,20 @@ export declare function anySegmentStartsWith(cmd: string, regexSource: string):
  * Case-INSENSITIVE, extended regex. Same posture as the bash helper.
  */
 export declare function anySegmentMatches(cmd: string, regexSource: string): boolean;
+/**
+ * Returns true if any single segment's RAW text contains matches for
+ * BOTH `regexA` AND `regexB`. Mirrors `any_segment_matches_both` from
+ * the bash counterpart — used by `env-file-protection` to require that
+ * a text-reading utility AND an `.env*` filename co-occur within the
+ * same shell segment (a multi-segment construction like
+ * `echo "log: cat .env stuff" ; touch foo.env` must NOT fire because
+ * the utility and filename live in different segments).
+ *
+ * Case-INSENSITIVE, extended regex on both patterns. Same posture as
+ * the bash helper.
+ *
+ * 0.33.0 port. The bash helper was introduced in 0.16.2 to fix the
+ * helix-017 P2 false-positive class where two independent booleans
+ * (any-utility OR any-env) were AND'd across segments.
+ */
+export declare function anySegmentMatchesBoth(cmd: string, regexA: string, regexB: string): boolean;

package/dist/hooks/_lib/segments.js

@@ -229,22 +229,63 @@ function unmask(text) {
  * (lookbehind).
  */
 function splitOnUnquotedSeparators(masked) {
-    // Negative lookbehind for `\` — `git commit \; foo` shouldn't split.
-    // JS regex supports lookbehind in V8 / Node 12+.
-    const splitter = /(?<!\\)(\&\&|\|\||;|\||\&|\n)/g;
-    // We split AND consume the separator (capture group above). The
-    // result interleaves segment, separator, segment, separator, …; we
-    // keep only the even-indexed entries (the segments).
-    const parts = masked.split(splitter);
+    // 2026-05-15 codex round-3 P1 fix: walk char-by-char tracking
+    // backslash-escape state instead of using regex lookbehind. The
+    // pre-fix regex `(?<!\\)(...)` was a single-char negative lookbehind
+    // which treated `echo \\;` as "preceded by `\` → no split". But in
+    // bash semantics, `\\` is a literal `\` escape PAIR — the `;` that
+    // follows it is NOT escaped, so the command splits into two
+    // segments. The pre-fix splitter let `echo \\; npm install evil`
+    // pass as a single segment, defeating the dependency-audit-gate
+    // segment-anchor check and several other consumers.
+    //
+    // Strategy: walk left-to-right. When we encounter `\`, advance past
+    // the next character (the escape pair consumes 2 bytes). When we
+    // encounter a recognized separator at a non-pair position, emit a
+    // split. This matches bash's argv-tokenizer semantics for
+    // backslash-escape parity.
+    //
+    // The masker is byte-width-preserving so we can walk `masked`
+    // directly without re-syncing with the original.
     const segments = [];
-    for (let i = 0; i < parts.length; i += 2) {
-        const raw = parts[i];
-        if (raw === undefined)
+    let segStart = 0;
+    let i = 0;
+    const n = masked.length;
+    while (i < n) {
+        const ch = masked[i];
+        if (ch === '\\' && i + 1 < n) {
+            // Escape pair — consume both, NEVER treat the next char as a
+            // separator. Bash `\\` is a literal `\`; the char following
+            // the pair is then evaluated for separator status.
+            i += 2;
             continue;
-        const trimmed = raw.trim();
-        if (trimmed.length === 0)
+        }
+        // Separator detection. Order matters: `&&` and `||` are 2-byte
+        // separators; the 1-byte forms must not steal their first byte.
+        let sepLen = 0;
+        if (ch === '&' && masked[i + 1] === '&')
+            sepLen = 2;
+        else if (ch === '|' && masked[i + 1] === '|')
+            sepLen = 2;
+        else if (ch === ';' || ch === '|' || ch === '&' || ch === '\n')
+            sepLen = 1;
+        if (sepLen > 0) {
+            const piece = masked.slice(segStart, i);
+            const trimmed = piece.trim();
+            if (trimmed.length > 0)
+                segments.push(trimmed);
+            i += sepLen;
+            segStart = i;
             continue;
-        segments.push(trimmed);
+        }
+        i += 1;
+    }
+    // Tail.
+    if (segStart < n) {
+        const piece = masked.slice(segStart, n);
+        const trimmed = piece.trim();
+        if (trimmed.length > 0)
+            segments.push(trimmed);
     }
     return segments;
 }
@@ -389,16 +430,272 @@ function stripSegmentPrefix(seg) {
  * Split `cmd` into segments using the quote-aware masking → split →
  * unmask pipeline. Returns an array of `{ raw, head }` tuples in the
  * order they appeared in the original command.
+ *
+ * 0.33.0 — nested-shell unwrapping was added on top of the original
+ * 0.32.0 splitter. When a segment's head is `bash -c|-lc|--c PAYLOAD`
+ * or `sh -c|-lc|--c PAYLOAD` (any combination of `-l` and `-c` flags),
+ * the PAYLOAD inside the quoted arg becomes additional segments
+ * appended after the wrapper segment. Mirrors the bash counterpart's
+ * `_rea_unwrap_nested_shells` (helix-017 #3 fix). Recurses up to
+ * `MAX_NESTED_DEPTH` levels.
  */
 export function splitSegments(cmd) {
     if (cmd.length === 0)
         return [];
+    return splitSegmentsRecursive(cmd, 0);
+}
+const MAX_NESTED_DEPTH = 8;
+function splitSegmentsRecursive(cmd, depth) {
     const masked = maskQuotedSeparators(cmd);
     const rawSegs = splitOnUnquotedSeparators(masked);
-    return rawSegs.map((raw) => {
+    const out = [];
+    for (const raw of rawSegs) {
         const unmaskedRaw = unmask(raw);
-        return { raw: unmaskedRaw, head: stripSegmentPrefix(unmaskedRaw) };
-    });
+        const head = stripSegmentPrefix(unmaskedRaw);
+        out.push({ raw: unmaskedRaw, head });
+        // Try to unwrap a nested shell payload.
+        if (depth < MAX_NESTED_DEPTH) {
+            const inner = extractNestedShellPayload(head);
+            if (inner !== null) {
+                // Append the inner payload's segments AFTER the wrapper segment.
+                // This preserves the bash hook's emit-order: the wrapper IS a
+                // segment too (so a hook that anchors on `bash` for some other
+                // reason still sees it), and the inner segments follow.
+                out.push(...splitSegmentsRecursive(inner, depth + 1));
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Recognize a nested-shell wrapper segment and return the unquoted
+ * payload string. Returns `null` when the segment is not a wrapper.
+ *
+ * 2026-05-15 codex round-1 P1 fix — extends parity with
+ * `_rea_unwrap_nested_shells` in `hooks/_lib/cmd-segments.sh`.
+ *
+ * Bash-parity matrix:
+ *
+ *   1. Shell names: bash | sh | zsh | dash
+ *      (The bash counterpart also includes ksh / mksh / oksh / posh /
+ *      yash / csh / tcsh / fish per the 0.19.0 M1 security review. We
+ *      cover the common quartet here; the rare shells fall through to
+ *      the bash-scanner tier which DOES have full coverage. Extending
+ *      this list later is a one-line change.)
+ *   2. Split-flag forms ANY combination of pre-flags before `-c`:
+ *        bash -l -c '…'     bash -i -c '…'     bash -e -c '…'
+ *        bash -li -c '…'    bash --noprofile -c '…'
+ *      The pre-fix regex `(?:-[a-z]*c|--c)(?:\s+-[a-z]+)*` failed
+ *      because it required `-c` to appear IN the FIRST flag token —
+ *      `bash -l -c 'PAYLOAD'` did not match.
+ *   3. Combined-flag forms: -c, -lc, -lic, -ic, -cl, -cli, -li, -il
+ *      (the bash WRAP pattern's `-(c|lc|lic|ic|cl|cli|li|il)` set).
+ *   4. ANSI-C-quoted payload: `bash -c $'…'`. Pre-fix the introducer
+ *      regex `(['"])` could not match the `$` prefix, so the entire
+ *      ANSI-C wrapper was a single un-unwrapped segment.
+ *
+ * The walker:
+ *   - Tokenizes the head into whitespace-separated tokens.
+ *   - First token must be a recognized shell name.
+ *   - Walks subsequent flag tokens, each `-[A-Za-z]+` or `--[A-Za-z]+`.
+ *   - A flag token containing a `c` letter terminates the flag walk
+ *     (it's the `-c` introducer). The next non-flag token is the
+ *     payload argument.
+ *   - The payload argument's first character determines the quote
+ *     style: `'`, `"`, or `$'` (ANSI-C). Any other character means
+ *     the payload is unquoted and we return null (don't unwrap — the
+ *     payload may already be a bare argv).
+ */
+function extractNestedShellPayload(head) {
+    // Tokenize on whitespace. The head has already passed through
+    // stripSegmentPrefix so leading `sudo`/env-prefixes are gone.
+    const trimmed = head.trimStart();
+    if (trimmed.length === 0)
+        return null;
+    // 1. Shell-name token. Full parity with cmd-segments.sh `WRAP`:
+    //    bash | sh | zsh | dash | ksh | mksh | oksh | posh | yash |
+    //    csh | tcsh | fish. Codex round-2 P1 (2026-05-15): the round-1
+    //    quartet (bash|sh|zsh|dash) left ksh/mksh/oksh/posh/yash/csh/
+    //    tcsh/fish unwrapped — on machines where any of those shells
+    //    are installed, `mksh -c 'source .env'` and
+    //    `ksh -c 'npm install missing-pkg'` would bypass
+    //    env-file-protection / dependency-audit-gate entirely.
+    //    The bash counterpart caught these via the 0.19.0 M1 security
+    //    review (WRAP regex extension).
+    //
+    //    NOTE: pwsh (PowerShell) is intentionally OUT — it accepts -c
+    //    and -Command, and -EncodedCommand base64-decodes at runtime.
+    //    Adding pwsh requires a separate code path with base64 decode
+    //    (mirroring the bash counterpart's explicit pwsh exclusion).
+    const shellMatch = /^(bash|sh|zsh|dash|ksh|mksh|oksh|posh|yash|csh|tcsh|fish)\b/i.exec(trimmed);
+    if (shellMatch === null)
+        return null;
+    let cursor = shellMatch[0].length;
+    // 2. Walk flag tokens. Each token is whitespace-separated and starts
+    //    with `-`. A flag token containing the letter `c` (case-insens.)
+    //    is the `-c` introducer; the NEXT token is the payload.
+    let sawCFlag = false;
+    while (cursor < trimmed.length) {
+        // Skip whitespace.
+        while (cursor < trimmed.length && /\s/.test(trimmed[cursor])) {
+            cursor += 1;
+        }
+        if (cursor >= trimmed.length)
+            return null;
+        // Peek next token.
+        const rest = trimmed.slice(cursor);
+        if (rest[0] !== '-') {
+            // Not a flag — must be the payload argument.
+            break;
+        }
+        // Extract the flag token (contiguous non-whitespace).
+        const flagMatch = /^(\S+)/.exec(rest);
+        if (flagMatch === null)
+            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>`.
+        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(/^--?/, ''))) {
+            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,
+            // but we accept additional flags between -c and the payload for
+            // safety; the bash WRAP regex similarly tolerates trailing
+            // flag-like tokens before the quoted body.)
+        }
+    }
+    if (!sawCFlag)
+        return null;
+    if (cursor >= trimmed.length)
+        return null;
+    // Skip whitespace before payload.
+    while (cursor < trimmed.length && /\s/.test(trimmed[cursor])) {
+        cursor += 1;
+    }
+    if (cursor >= trimmed.length)
+        return null;
+    // 3. Inspect the payload's introducer character.
+    const first = trimmed[cursor];
+    let quote;
+    let isAnsiC = false;
+    let payloadStart = cursor;
+    if (first === '$' && trimmed[cursor + 1] === "'") {
+        // ANSI-C: $'…' — single-quote-style but with C-string escapes.
+        quote = "'";
+        isAnsiC = true;
+        payloadStart = cursor + 2;
+    }
+    else if (first === "'" || first === '"') {
+        quote = first;
+        payloadStart = cursor + 1;
+    }
+    else {
+        // Unquoted payload — refuse to unwrap. The bash counterpart's
+        // WRAP regex requires a quote introducer too.
+        return null;
+    }
+    // 4. Walk the payload, collecting bytes until the matching closing
+    //    quote. Honor quote-specific escape rules.
+    let i = payloadStart;
+    let payload = '';
+    while (i < trimmed.length) {
+        const ch = trimmed[i];
+        if (ch === quote) {
+            // Closing quote found.
+            return payload;
+        }
+        if (isAnsiC && ch === '\\' && i + 1 < trimmed.length) {
+            // ANSI-C escape decoding. Mirror the bash counterpart's escape
+            // table (cmd-segments.sh, _rea_unwrap_at_depth). Only the
+            // common-enough subset is decoded; unknowns pass through as the
+            // literal pair (matches awk default behavior).
+            const nxt = trimmed[i + 1];
+            switch (nxt) {
+                case 'n':
+                    payload += '\n';
+                    break;
+                case 't':
+                    payload += '\t';
+                    break;
+                case 'r':
+                    payload += '\r';
+                    break;
+                case '\\':
+                    payload += '\\';
+                    break;
+                case "'":
+                    payload += "'";
+                    break;
+                case '"':
+                    payload += '"';
+                    break;
+                case 'a':
+                    payload += '\x07';
+                    break;
+                case 'b':
+                    payload += '\x08';
+                    break;
+                case 'e':
+                case 'E':
+                    payload += '\x1b';
+                    break;
+                case 'f':
+                    payload += '\x0c';
+                    break;
+                case 'v':
+                    payload += '\x0b';
+                    break;
+                case '0':
+                    payload += '\x00';
+                    break;
+                case 'x': {
+                    // \xHH or \xH — up to 2 hex digits.
+                    let hex = '';
+                    let k = i + 2;
+                    while (k < trimmed.length && hex.length < 2) {
+                        const hc = trimmed[k];
+                        if (!/[0-9a-fA-F]/.test(hc))
+                            break;
+                        hex += hc;
+                        k += 1;
+                    }
+                    if (hex.length > 0) {
+                        payload += String.fromCharCode(parseInt(hex, 16));
+                        i = k;
+                        continue;
+                    }
+                    // Fall through — `\x` with no hex digits is a literal pair.
+                    payload += '\\x';
+                    break;
+                }
+                default:
+                    // Unknown escape — preserve the literal pair (bash awk
+                    // default). E.g. `\z` → `\z`.
+                    payload += '\\' + nxt;
+                    break;
+            }
+            i += 2;
+            continue;
+        }
+        if (!isAnsiC && quote === '"' && ch === '\\' && i + 1 < trimmed.length) {
+            // Double-quote: backslash escapes the next character.
+            payload += trimmed[i + 1] ?? '';
+            i += 2;
+            continue;
+        }
+        payload += ch;
+        i += 1;
+    }
+    // Unterminated quote — return what we have. The bash counterpart
+    // similarly accepts unterminated quotes as "rest of line is payload".
+    return payload;
 }
 /**
  * Returns true if any segment's prefix-stripped head matches the
@@ -442,3 +739,28 @@ export function anySegmentMatches(cmd, regexSource) {
     }
     return false;
 }
+/**
+ * Returns true if any single segment's RAW text contains matches for
+ * BOTH `regexA` AND `regexB`. Mirrors `any_segment_matches_both` from
+ * the bash counterpart — used by `env-file-protection` to require that
+ * a text-reading utility AND an `.env*` filename co-occur within the
+ * same shell segment (a multi-segment construction like
+ * `echo "log: cat .env stuff" ; touch foo.env` must NOT fire because
+ * the utility and filename live in different segments).
+ *
+ * Case-INSENSITIVE, extended regex on both patterns. Same posture as
+ * the bash helper.
+ *
+ * 0.33.0 port. The bash helper was introduced in 0.16.2 to fix the
+ * helix-017 P2 false-positive class where two independent booleans
+ * (any-utility OR any-env) were AND'd across segments.
+ */
+export function anySegmentMatchesBoth(cmd, regexA, regexB) {
+    const reA = new RegExp(regexA, 'i');
+    const reB = new RegExp(regexB, 'i');
+    for (const seg of splitSegments(cmd)) {
+        if (reA.test(seg.raw) && reB.test(seg.raw))
+            return true;
+    }
+    return false;
+}

package/dist/hooks/architecture-review-gate/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Node-binary port of `hooks/architecture-review-gate.sh`.
+ *
+ * 0.33.0 Phase 1 port #4 — the SIMPLEST tier-1 port.
+ *
+ * PostToolUse Write/Edit advisory. Reads `policy.architecture_review.
+ * patterns` and prints an advisory banner to stderr when the just-
+ * written file path begins with one of the configured prefixes.
+ * ALWAYS exits 0 — this is a nudge, not a gate.
+ *
+ * Behavioral contract preserves the bash hook byte-for-byte:
+ *
+ *   1. HALT check → exit 2 with the shared banner. (Even though the
+ *      gate is advisory, HALT short-circuits ALL hooks.)
+ *   2. `policy.architecture_advisory: false` short-circuit → exit 0
+ *      silently. The bash hook reads the policy file with a grep
+ *      `architecture_advisory: false`; we mirror via the canonical
+ *      YAML loader.
+ *   3. Read stdin → `tool_input.file_path` (the bash hook uses
+ *      `notebook_path` too via fall-through, but the original
+ *      `jq -r '.tool_input.file_path // empty'` expression does NOT
+ *      fall through to notebook_path. We preserve that exactly).
+ *   4. Empty file_path → exit 0.
+ *   5. Path normalization mirrors `_lib/path-normalize.sh::normalize_path`:
+ *        - Convert backslashes to forward slashes (Windows / Git Bash).
+ *        - URL-decode `%xx` sequences.
+ *        - Strip a leading `<REA_ROOT>/` prefix if present so
+ *          `policy.architecture_review.patterns` can use repo-relative
+ *          patterns.
+ *   6. Read `policy.architecture_review.patterns`. Empty / unset →
+ *      silent no-op (exit 0). The bst-internal profile pins rea-
+ *      source patterns; consumer projects opt in by populating their
+ *      own list.
+ *   7. First prefix match wins. Emit the advisory banner to stderr;
+ *      exit 0.
+ *
+ * Distinct from the other 0.33.0 ports: this gate is POSTToolUse
+ * (fires AFTER the write, advisory only). The shim that invokes it
+ * should NOT fail-closed on missing CLI — the pre-0.33.0 bash hook
+ * was already a silent no-op when the policy was unset.
+ */
+import type { Buffer } from 'node:buffer';
+export interface ArchitectureReviewGateOptions {
+    reaRoot?: string;
+    stdinOverride?: string | Buffer;
+    stderrWrite?: (s: string) => void;
+}
+export interface ArchitectureReviewGateResult {
+    exitCode: number;
+    stderr: string;
+    /** Test seam — the matched pattern (or `null`). */
+    matched: string | null;
+}
+export declare function runArchitectureReviewGate(options?: ArchitectureReviewGateOptions): Promise<ArchitectureReviewGateResult>;
+/**
+ * CLI entry — `rea hook architecture-review-gate`.
+ */
+export declare function runHookArchitectureReviewGate(options?: ArchitectureReviewGateOptions): Promise<void>;