@bookedsolid/rea 0.34.0 → 0.36.0

package/dist/cli/doctor.js

@@ -169,22 +169,19 @@ export const EXPECTED_HOOKS = [
     'blocked-paths-enforcer.sh',
     'changeset-security-gate.sh',
     'dangerous-bash-interceptor.sh',
-    // 0.31.0 — `delegation-advisory.sh` is INTENTIONALLY NOT in this list.
-    // It is the brand-new PostToolUse delegation-nudge hook this release
-    // ships; adding it to EXPECTED_HOOKS would make `checkHooksInstalled`
-    // hard-`fail` on every pre-0.31.0 consumer install (and on this repo's
-    // own dogfood) the instant they upgrade the rea binary but before they
-    // run `rea upgrade` to lay down the new hook file — a regression that
-    // turns a green doctor red purely from upgrade lag. This mirrors the
-    // staged rollout `delegation-capture.sh` itself used: the file-presence
-    // entry joins EXPECTED_HOOKS in the SAME future minor that promotes
-    // `checkDelegationAdvisoryHookRegistered` from `warn` to `fail`, once
-    // consumers have had upgrade-lag time. Until then, a missing
-    // `delegation-advisory.sh` surfaces only through that `warn`-tier
-    // registration check — proportionate, since the hook is advisory at
-    // runtime and never blocks a tool call. See `git blame` on the 0.29.0
-    // round-2 P2 comment on `checkDelegationHookRegistered` for the prior
-    // application of this exact discipline.
+    // 0.36.0 — `delegation-advisory.sh` PROMOTED to EXPECTED_HOOKS (charter
+    // follow-through from 0.31.0). Originally held out in 0.31.0 to give
+    // consumers an upgrade-lag window: adding a brand-new hook to
+    // EXPECTED_HOOKS would have hard-`fail`ed `checkHooksInstalled` on
+    // every pre-0.31.0 install the instant they bumped the rea binary, a
+    // regression that turns a green doctor red purely from upgrade lag.
+    // After 4 releases of propagation (0.32, 0.33, 0.34, 0.35), the lag
+    // window has closed — consumers running `rea upgrade` since 0.31.0
+    // have laid the hook down. Same ratchet `delegation-capture.sh` went
+    // through 0.29.0 → 0.30.0. Promotion happens in lockstep with
+    // `checkDelegationAdvisoryHookRegistered` flipping `warn` → `fail`
+    // (see that function for the matching commentary).
+    'delegation-advisory.sh',
     // 0.29.0 — delegation-telemetry MVP. The PreToolUse hook on
     // matcher `Agent|Skill` emits a `rea.delegation_signal` audit record
     // on every subagent / skill dispatch. Observational only — fails
@@ -1126,14 +1123,25 @@ export function checkDelegationHookRegistered(baseDir) {
  */
 export function checkDelegationAdvisoryHookRegistered(baseDir) {
     const label = 'delegation-advisory hook registered';
-    const ADVISORY = 'warn';
+    // 0.36.0 — promoted from `warn` (advisory in 0.31.0) to `fail` (hard)
+    // per the staged-rollout ratchet. After 4 releases of upgrade-lag
+    // propagation (0.32, 0.33, 0.34, 0.35), consumer installs that have
+    // run `rea upgrade` since 0.31.0 already carry the PostToolUse
+    // `Bash|Edit|Write|MultiEdit|NotebookEdit` group. Any install that
+    // still lacks it after that window is genuinely missing the nudge
+    // and `fail` is the proportionate signal. Companion change:
+    // `delegation-advisory.sh` joined `EXPECTED_HOOKS` in the same
+    // commit, so `checkHooksInstalled` also covers the file-presence +
+    // executability checks now (this function still does both directly
+    // as defense-in-depth, mirroring `checkDelegationHookRegistered`).
+    const REFUSE = 'fail';
     const MATCHER = 'Bash|Edit|Write|MultiEdit|NotebookEdit';
     const settingsPath = path.join(baseDir, '.claude', 'settings.json');
     if (!fs.existsSync(settingsPath)) {
         return {
             label,
-            status: ADVISORY,
-            detail: `missing: ${settingsPath} — run \`rea upgrade\` or \`rea init\` (advisory in 0.31.0)`,
+            status: REFUSE,
+            detail: `missing: ${settingsPath} — run \`rea upgrade\` or \`rea init\``,
         };
     }
     let parsed;
@@ -1143,7 +1151,7 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     catch (e) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: e instanceof Error ? e.message : String(e),
         };
     }
@@ -1152,9 +1160,9 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     if (group === undefined) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `no PostToolUse group with matcher "${MATCHER}" found in .claude/settings.json — ` +
-                'run `rea upgrade` to install (advisory in 0.31.0; promoted to fail in a later minor). ' +
+                'run `rea upgrade` to install. ' +
                 'NOTE: the matcher INCLUDES Bash — the delegation nudge counts every write-class ' +
                 'tool call, not just file edits.',
         };
@@ -1163,16 +1171,16 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     if (!cmds.some((c) => c.includes('delegation-advisory.sh'))) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `${MATCHER} matcher exists but no delegation-advisory.sh command found in its hooks list`,
         };
     }
-    // Round-2/3 P2: the registration string is present — now confirm the
-    // hook file it points at actually exists AND is executable. Because
-    // `delegation-advisory.sh` is intentionally out of `EXPECTED_HOOKS`
-    // for 0.31.0, `checkHooksInstalled` does NOT cover it; this is the
-    // only signal, so it owns both the presence and the `0o111` checks
-    // that `checkHooksInstalled` does for every other shipped hook.
+    // 0.31.0 round-2/3 P2: the registration string is present — now
+    // confirm the hook file it points at actually exists AND is
+    // executable. Kept after the 0.36.0 EXPECTED_HOOKS promotion as
+    // defense-in-depth (the same `0o111` check `checkHooksInstalled`
+    // does, scoped to this hook so the failure message can name the
+    // exact remediation rather than a generic "missing X" enumeration).
     const hookFile = path.join(baseDir, '.claude', 'hooks', 'delegation-advisory.sh');
     let hookStat;
     try {
@@ -1181,19 +1189,19 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     catch {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `${MATCHER} matcher references delegation-advisory.sh but the hook file is missing: ` +
-                `${hookFile} — run \`rea upgrade\` to lay it down (advisory in 0.31.0). ` +
+                `${hookFile} — run \`rea upgrade\` to lay it down. ` +
                 'Without the file every matching PostToolUse dispatch shells out to a nonexistent path.',
         };
     }
     if ((hookStat.mode & 0o111) === 0) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `${MATCHER} matcher references delegation-advisory.sh but the hook file is not executable ` +
                 `(mode=${(hookStat.mode & 0o777).toString(8)}): ${hookFile} — ` +
-                'run `rea upgrade` or `chmod +x` it (advisory in 0.31.0). ' +
+                'run `rea upgrade` or `chmod +x` it. ' +
                 'A non-executable hook cannot be launched by Claude Code from settings.json.',
         };
     }
@@ -1469,9 +1477,10 @@ export function collectChecks(baseDir, codexProbeState, prePushState, options =
         checkDelegationHookRegistered(baseDir),
         // 0.31.0 — delegation-telemetry completion. The PostToolUse
         // `Bash|Edit|Write|MultiEdit|NotebookEdit` matcher group drives
-        // the delegation-advisory nudge hook. Advisory (warn) for 0.31.0
-        // — same upgrade-lag ratchet checkDelegationHookRegistered went
-        // through in 0.29.0.
+        // the delegation-advisory nudge hook. 0.36.0 — promoted warn →
+        // fail (same upgrade-lag ratchet checkDelegationHookRegistered
+        // went through in 0.29.0 → 0.30.0, after 4 release cycles of
+        // propagation).
         checkDelegationAdvisoryHookRegistered(baseDir),
     ];
     // Non-git escape hatch: when `.git/` is absent, both git-hook checks are

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;