@bookedsolid/rea 0.30.1 → 0.31.0

package/dist/cli/roster.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Live `.claude/agents/` roster discovery (0.31.0+).
+ *
+ * 0.29.0 shipped the delegation-telemetry observability layer. 0.31.0
+ * closes the loop with the *nudge* — and the nudge needs to know what
+ * counts as a "real" specialist delegation versus a built-in helper.
+ *
+ * # Why discovery, not a hardcoded list
+ *
+ * `src/cli/doctor.ts` already carries an `EXPECTED_AGENTS` constant,
+ * but it is a deliberately-frozen 10-entry subset — the minimum roster
+ * `rea init` guarantees, pinned so a regression that drops a curated
+ * agent from the install manifest trips a doctor failure. It is NOT
+ * the live roster: this repo ships 23 agents, consumers add their own,
+ * and the curated set grows release over release. Keying the
+ * delegation nudge off `EXPECTED_AGENTS` would mean a session that
+ * delegated exclusively to `principal-engineer` and `data-architect`
+ * (both real, curated, neither in the frozen subset) still got nudged
+ * — exactly the false positive that erodes trust in an advisory.
+ *
+ * So the roster is discovered at read time: every `*.md` file under
+ * `<baseDir>/.claude/agents/` is a curated specialist. The basename
+ * (sans `.md`) is the `subagent_type` Claude Code's `Agent` tool
+ * reports, so the mapping is direct.
+ *
+ * # The exempt set
+ *
+ * Claude Code ships built-in helpers — `general-purpose`, `Explore`,
+ * `Plan`, `output-style-setup`, `statusline-setup` — that are dispatched
+ * through the same `Agent` tool but are NOT curated specialists. A
+ * session that only ever delegated to those has not actually routed
+ * work to the engineering team. The exempt set is policy-configurable
+ * (`policy.delegation_advisory.exempt_subagents`) with a 5-entry
+ * built-in default; this module takes the resolved list as an argument
+ * rather than reading policy itself, so it stays a pure filesystem
+ * helper with no policy-loader dependency.
+ *
+ * # Skills
+ *
+ * The `Skill` delegation tool is intentionally NOT roster-gated. A
+ * skill invocation (`deep-dive`, `due-diligence`, …) is always a real
+ * delegation signal — there is no "built-in skill" equivalent of
+ * `general-purpose`. The advisory's "did this session delegate"
+ * predicate counts every `Skill` signal and every non-exempt `Agent`
+ * signal whose `subagent_type` is in the discovered roster.
+ */
+/**
+ * Default exempt subagent names — Claude Code's built-in helper agents
+ * that are dispatched through the `Agent` tool but are not curated
+ * specialists. Mirrors the schema-layer default in
+ * `DelegationAdvisoryPolicySchema` (`src/policy/loader.ts`). Exported
+ * so callers that have no policy in scope (the bash-hook fallback
+ * path) can still apply the same filter.
+ */
+export declare const DEFAULT_EXEMPT_SUBAGENTS: readonly string[];
+export interface RosterDiscoveryResult {
+    /**
+     * Sorted list of discovered curated-specialist names — the basename
+     * (sans `.md`) of every file under `.claude/agents/`. Empty when the
+     * directory is absent or unreadable.
+     */
+    roster: string[];
+    /**
+     * Absolute path actually scanned. Returned for diagnostics — doctor
+     * surfaces it, the `rea hook` subcommand echoes it in `--json` mode.
+     */
+    agentsDir: string;
+    /**
+     * `true` when `.claude/agents/` exists and was read. `false` when it
+     * is absent or a read error occurred — callers treat that as "no
+     * roster, every Agent delegation is non-exempt-but-also-unverifiable"
+     * and fall back to the exempt-list-only filter.
+     */
+    discovered: boolean;
+}
+/**
+ * Discover the curated-specialist roster by listing `*.md` files under
+ * `<baseDir>/.claude/agents/`. Pure filesystem read — never throws; an
+ * absent or unreadable directory yields `discovered: false` with an
+ * empty roster.
+ *
+ * The `.md` extension match is case-insensitive (`.MD` on a
+ * case-preserving-but-insensitive filesystem still counts) and the
+ * basename is taken verbatim — `rea-orchestrator.md` →
+ * `rea-orchestrator`. Subdirectories and non-`.md` files (READMEs,
+ * `.DS_Store`, editor swap files) are skipped.
+ */
+export declare function discoverRoster(baseDir: string): RosterDiscoveryResult;
+/**
+ * The delegation-nudge predicate, factored out so the CLI subcommand,
+ * the `audit specialists` reader, and the doctor smoke check all apply
+ * identical logic.
+ *
+ * Returns `true` when the given `(delegation_tool, subagent_type)` pair
+ * counts as a REAL delegation — i.e. the kind that should suppress the
+ * advisory nudge:
+ *
+ *   - `Skill` → always counts. There is no "built-in skill" exemption.
+ *   - `Agent` → counts when the `subagent_type` is NOT in `exempt` AND
+ *     (the roster was discovered AND contains the name, OR the roster
+ *     was NOT discovered — in which case we cannot verify and fall
+ *     back to "non-exempt name counts"). The non-discovered fallback
+ *     is deliberately permissive: a consumer who deleted
+ *     `.claude/agents/` has bigger problems than a missed nudge, and a
+ *     false negative (no nudge when one was due) is far less corrosive
+ *     than a false positive.
+ *
+ * `exempt` comparison is case-sensitive — the built-in helper names
+ * (`Explore`, `Plan`) are capitalized and the curated specialists are
+ * kebab-case, so there is no realistic collision, and a case-folded
+ * compare would risk a curated `Plan-something` agent being wrongly
+ * exempted.
+ */
+export declare function countsAsRealDelegation(args: {
+    delegationTool: 'Agent' | 'Skill';
+    subagentType: string;
+    roster: RosterDiscoveryResult;
+    exempt: readonly string[];
+}): boolean;

package/dist/cli/roster.js

@@ -0,0 +1,141 @@
+/**
+ * Live `.claude/agents/` roster discovery (0.31.0+).
+ *
+ * 0.29.0 shipped the delegation-telemetry observability layer. 0.31.0
+ * closes the loop with the *nudge* — and the nudge needs to know what
+ * counts as a "real" specialist delegation versus a built-in helper.
+ *
+ * # Why discovery, not a hardcoded list
+ *
+ * `src/cli/doctor.ts` already carries an `EXPECTED_AGENTS` constant,
+ * but it is a deliberately-frozen 10-entry subset — the minimum roster
+ * `rea init` guarantees, pinned so a regression that drops a curated
+ * agent from the install manifest trips a doctor failure. It is NOT
+ * the live roster: this repo ships 23 agents, consumers add their own,
+ * and the curated set grows release over release. Keying the
+ * delegation nudge off `EXPECTED_AGENTS` would mean a session that
+ * delegated exclusively to `principal-engineer` and `data-architect`
+ * (both real, curated, neither in the frozen subset) still got nudged
+ * — exactly the false positive that erodes trust in an advisory.
+ *
+ * So the roster is discovered at read time: every `*.md` file under
+ * `<baseDir>/.claude/agents/` is a curated specialist. The basename
+ * (sans `.md`) is the `subagent_type` Claude Code's `Agent` tool
+ * reports, so the mapping is direct.
+ *
+ * # The exempt set
+ *
+ * Claude Code ships built-in helpers — `general-purpose`, `Explore`,
+ * `Plan`, `output-style-setup`, `statusline-setup` — that are dispatched
+ * through the same `Agent` tool but are NOT curated specialists. A
+ * session that only ever delegated to those has not actually routed
+ * work to the engineering team. The exempt set is policy-configurable
+ * (`policy.delegation_advisory.exempt_subagents`) with a 5-entry
+ * built-in default; this module takes the resolved list as an argument
+ * rather than reading policy itself, so it stays a pure filesystem
+ * helper with no policy-loader dependency.
+ *
+ * # Skills
+ *
+ * The `Skill` delegation tool is intentionally NOT roster-gated. A
+ * skill invocation (`deep-dive`, `due-diligence`, …) is always a real
+ * delegation signal — there is no "built-in skill" equivalent of
+ * `general-purpose`. The advisory's "did this session delegate"
+ * predicate counts every `Skill` signal and every non-exempt `Agent`
+ * signal whose `subagent_type` is in the discovered roster.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Default exempt subagent names — Claude Code's built-in helper agents
+ * that are dispatched through the `Agent` tool but are not curated
+ * specialists. Mirrors the schema-layer default in
+ * `DelegationAdvisoryPolicySchema` (`src/policy/loader.ts`). Exported
+ * so callers that have no policy in scope (the bash-hook fallback
+ * path) can still apply the same filter.
+ */
+export const DEFAULT_EXEMPT_SUBAGENTS = [
+    'general-purpose',
+    'Explore',
+    'Plan',
+    'output-style-setup',
+    'statusline-setup',
+];
+/**
+ * Discover the curated-specialist roster by listing `*.md` files under
+ * `<baseDir>/.claude/agents/`. Pure filesystem read — never throws; an
+ * absent or unreadable directory yields `discovered: false` with an
+ * empty roster.
+ *
+ * The `.md` extension match is case-insensitive (`.MD` on a
+ * case-preserving-but-insensitive filesystem still counts) and the
+ * basename is taken verbatim — `rea-orchestrator.md` →
+ * `rea-orchestrator`. Subdirectories and non-`.md` files (READMEs,
+ * `.DS_Store`, editor swap files) are skipped.
+ */
+export function discoverRoster(baseDir) {
+    const agentsDir = path.join(baseDir, '.claude', 'agents');
+    let entries;
+    try {
+        entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    }
+    catch {
+        // ENOENT (no .claude/agents/), ENOTDIR, EACCES — all collapse to
+        // "no roster discovered". The caller falls back to the exempt-list
+        // filter alone.
+        return { roster: [], agentsDir, discovered: false };
+    }
+    const roster = [];
+    for (const entry of entries) {
+        // Only regular files. A directory named `foo.md` is not an agent.
+        if (!entry.isFile())
+            continue;
+        const name = entry.name;
+        if (!name.toLowerCase().endsWith('.md'))
+            continue;
+        const base = name.slice(0, name.length - 3);
+        if (base.length === 0)
+            continue;
+        roster.push(base);
+    }
+    roster.sort();
+    return { roster, agentsDir, discovered: true };
+}
+/**
+ * The delegation-nudge predicate, factored out so the CLI subcommand,
+ * the `audit specialists` reader, and the doctor smoke check all apply
+ * identical logic.
+ *
+ * Returns `true` when the given `(delegation_tool, subagent_type)` pair
+ * counts as a REAL delegation — i.e. the kind that should suppress the
+ * advisory nudge:
+ *
+ *   - `Skill` → always counts. There is no "built-in skill" exemption.
+ *   - `Agent` → counts when the `subagent_type` is NOT in `exempt` AND
+ *     (the roster was discovered AND contains the name, OR the roster
+ *     was NOT discovered — in which case we cannot verify and fall
+ *     back to "non-exempt name counts"). The non-discovered fallback
+ *     is deliberately permissive: a consumer who deleted
+ *     `.claude/agents/` has bigger problems than a missed nudge, and a
+ *     false negative (no nudge when one was due) is far less corrosive
+ *     than a false positive.
+ *
+ * `exempt` comparison is case-sensitive — the built-in helper names
+ * (`Explore`, `Plan`) are capitalized and the curated specialists are
+ * kebab-case, so there is no realistic collision, and a case-folded
+ * compare would risk a curated `Plan-something` agent being wrongly
+ * exempted.
+ */
+export function countsAsRealDelegation(args) {
+    if (args.delegationTool === 'Skill')
+        return true;
+    // Agent path.
+    if (args.exempt.includes(args.subagentType))
+        return false;
+    if (!args.roster.discovered) {
+        // Roster unverifiable — a non-exempt Agent name is the best signal
+        // we have. Count it.
+        return true;
+    }
+    return args.roster.roster.includes(args.subagentType);
+}

package/dist/policy/loader.d.ts

@@ -288,6 +288,19 @@ declare const PolicySchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     }>>;
+    delegation_advisory: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        threshold: z.ZodDefault<z.ZodNumber>;
+        exempt_subagents: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        threshold: number;
+        exempt_subagents: string[];
+    }, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -361,6 +374,11 @@ declare const PolicySchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled: boolean;
+        threshold: number;
+        exempt_subagents: string[];
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -434,6 +452,11 @@ declare const PolicySchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -289,6 +289,45 @@ const AttributionPolicySchema = z
     co_author: AttributionCoAuthorSchema.optional(),
 })
     .strict();
+/**
+ * 0.31.0 — delegation-advisory nudge policy. Drives the
+ * `delegation-advisory.sh` PostToolUse hook (matcher
+ * `Bash|Edit|Write|MultiEdit|NotebookEdit`): when a session crosses
+ * `threshold` write-class tool calls without a `rea.delegation_signal`
+ * record (to a non-exempt subagent), the hook emits a one-time stderr
+ * advisory. The hook is advisory-only — exit 0 always except HALT.
+ *
+ * Defaults live here at the schema layer, not in the hook: a vanilla
+ * install with no `delegation_advisory` block gets `enabled: false`
+ * (silent no-op), `threshold: 25`, and the 5-entry built-in exempt
+ * list. The `bst-internal*` profiles pin `enabled: true`; OSS profiles
+ * leave it `false` so consumers opt in.
+ *
+ * `threshold` is a positive integer — a single write-class count
+ * rather than the 0.29.0 design memo's "15 edits + 5 Bash" split.
+ * Modeling the threshold as one number keeps the hook's counter file
+ * a single integer and the policy surface a single knob; the
+ * distinction between an Edit and a Bash call doesn't change the
+ * signal the nudge exists to send ("you've done a lot solo").
+ *
+ * Strict mode rejects unknown keys so a typo (`thresholds`,
+ * `exempt_subagent`) fails loudly at policy load.
+ */
+const DelegationAdvisoryPolicySchema = z
+    .object({
+    enabled: z.boolean().default(false),
+    threshold: z.number().int().positive().default(25),
+    exempt_subagents: z
+        .array(z.string())
+        .default([
+        'general-purpose',
+        'Explore',
+        'Plan',
+        'output-style-setup',
+        'statusline-setup',
+    ]),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -341,6 +380,13 @@ const PolicySchema = z
     // `AttributionCoAuthorSchema` fails closed when `enabled: true` but
     // `name`/`email` are empty so we never ship a half-configured trailer.
     attribution: AttributionPolicySchema.optional(),
+    // 0.31.0 delegation-advisory nudge — drives the
+    // `delegation-advisory.sh` PostToolUse hook. `.optional()` so a
+    // vanilla install with no block sees the hook as a silent no-op
+    // (the hook reads `enabled` via `rea hook policy-get` and exits 0
+    // when unset/false). When the block IS present the inner schema
+    // supplies defaults for any omitted field.
+    delegation_advisory: DelegationAdvisoryPolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/profiles.d.ts

@@ -108,6 +108,19 @@ export declare const ProfileSchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     }>>;
+    delegation_advisory: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+        exempt_subagents: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    }, {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -142,6 +155,11 @@ export declare const ProfileSchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    } | undefined;
 }, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -176,6 +194,11 @@ export declare const ProfileSchema: z.ZodObject<{
             skip_merge?: boolean | undefined;
         } | undefined;
     } | undefined;
+    delegation_advisory?: {
+        enabled?: boolean | undefined;
+        threshold?: number | undefined;
+        exempt_subagents?: string[] | undefined;
+    } | undefined;
 }>;
 export type Profile = z.infer<typeof ProfileSchema>;
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/profiles.js

@@ -100,6 +100,22 @@ export const ProfileSchema = z
     })
         .strict()
         .optional(),
+    // 0.31.0+ delegation-advisory nudge. `bst-internal*` profiles pin
+    // `enabled: true`; external profiles ship `enabled: false`. The
+    // profile-layer schema mirrors the policy-loader's
+    // `DelegationAdvisoryPolicySchema` but leaves every field optional
+    // — defaults are applied at the policy-loader layer when the
+    // materialized file is parsed, so a profile that only declares
+    // `enabled` doesn't need to also restate `threshold`. Strict mode
+    // still rejects typos at init time.
+    delegation_advisory: z
+        .object({
+        enabled: z.boolean().optional(),
+        threshold: z.number().int().positive().optional(),
+        exempt_subagents: z.array(z.string()).optional(),
+    })
+        .strict()
+        .optional(),
 })
     .strict();
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/types.d.ts

@@ -367,6 +367,59 @@ export interface AttributionCoAuthorPolicy {
     email?: string;
     skip_merge?: boolean;
 }
+/**
+ * Delegation-advisory nudge policy (0.31.0+).
+ *
+ * 0.29.0 shipped the delegation-telemetry *observability* layer (the
+ * `Agent|Skill` PreToolUse capture hook + `rea audit specialists`
+ * reader). 0.31.0 closes the loop with the *nudge*: the
+ * `delegation-advisory.sh` PostToolUse hook (matcher
+ * `Bash|Edit|Write|MultiEdit|NotebookEdit`) counts the current
+ * session's write-class tool calls and, when that count crosses
+ * `threshold` WITHOUT a `rea.delegation_signal` record landing in the
+ * session, prints a one-time stderr advisory: "this session has done a
+ * lot of work without delegating to a specialist".
+ *
+ * The advisory is purely informational — the hook always exits 0
+ * (except under HALT, which exits 2 to keep the kill-switch contract
+ * uniform). It NEVER blocks a tool call.
+ *
+ * Profile defaults: `enabled: true` for the `bst-internal*` profiles
+ * (BST's own delegation discipline is load-bearing); `enabled: false`
+ * for every external profile (`open-source*`, `minimal`,
+ * `client-engagement`, `lit-wc`) — OSS consumers opt in per-repo via
+ * `.rea/policy.yaml`, since "you should delegate more" is an opinion
+ * not every team shares.
+ */
+export interface DelegationAdvisoryPolicy {
+    /**
+     * Master switch. When `false` (or the whole block is omitted) the
+     * `delegation-advisory.sh` hook is a silent no-op. Default `false` at
+     * the schema layer; `bst-internal*` profiles pin `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Write-class tool-call count at which the advisory fires. The
+     * `delegation-advisory.sh` hook maintains a per-session counter file
+     * and emits the nudge the first time the counter reaches this value
+     * with zero delegation signals recorded for the session. Default
+     * `25` — a session that has run 25 Bash/Edit/Write/MultiEdit/
+     * NotebookEdit calls without once dispatching a specialist is doing
+     * meaningful work solo. Must be a positive integer.
+     */
+    threshold?: number;
+    /**
+     * Subagent / skill names that do NOT count as "real delegation" for
+     * the purpose of suppressing the advisory. A session that only ever
+     * delegated to `general-purpose` / `Explore` / `Plan` (the built-in
+     * Claude Code helpers) has not actually routed work to a curated
+     * specialist, so those signals don't reset the nudge. Default:
+     * `["general-purpose", "Explore", "Plan", "output-style-setup",
+     * "statusline-setup"]`. A delegation signal whose `subagent_type` is
+     * in this list is ignored when deciding whether to fire.
+     */
+    exempt_subagents?: string[];
+}
 /**
  * G9 — injection tier escalation knobs. The classifier bucketed matches into
  * `clean` / `suspicious` / `likely_injection`; this block governs what happens
@@ -472,4 +525,12 @@ export interface Policy {
      * trailer are no-ops. See `AttributionPolicy` for the full contract.
      */
     attribution?: AttributionPolicy;
+    /**
+     * Delegation-advisory nudge (0.31.0+). When `enabled: true`, the
+     * `delegation-advisory.sh` PostToolUse hook emits a one-time stderr
+     * advisory when a session crosses `threshold` write-class tool calls
+     * without dispatching a curated specialist. Advisory only — never
+     * blocks. See `DelegationAdvisoryPolicy` for the full contract.
+     */
+    delegation_advisory?: DelegationAdvisoryPolicy;
 }

package/hooks/delegation-advisory.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+# PostToolUse hook: delegation-advisory.sh
+# 0.31.0+ — delegation-telemetry completion (the *nudge*).
+#
+# Fires AFTER every write-class tool call. The settings.json matcher is
+# `Bash|Edit|Write|MultiEdit|NotebookEdit`. Reads the Claude Code hook
+# payload from stdin, pipes it to `rea hook delegation-advisory`, and
+# exits 0.
+#
+# 0.29.0 shipped the delegation-telemetry *observability* layer
+# (`delegation-capture.sh` + `rea audit specialists`). 0.31.0 closes the
+# loop with the *nudge*: `rea hook delegation-advisory` maintains a
+# per-session write-class counter and, the FIRST time that counter
+# crosses `policy.delegation_advisory.threshold` while the session has
+# recorded zero real delegation signals, prints a one-time stderr
+# advisory ("this session has done a lot of work without delegating to
+# a specialist").
+#
+# # Advisory, never gating
+#
+# This hook ALWAYS exits 0 (under normal operation). The advisory is a
+# nudge — it never blocks a tool call. The ONLY non-zero exit is 2
+# under HALT, to keep the kill-switch contract uniform with the rest of
+# the hook tree.
+#
+# # Synchronous, NOT detached
+#
+# Unlike `delegation-capture.sh` (which backgrounds `rea hook
+# delegation-signal` with `& disown` because the audit write must not
+# block tool dispatch), this hook runs the CLI SYNCHRONOUSLY. The
+# advisory text must reach the operator's stderr before the hook
+# returns — backgrounding it would race the hook's own exit and the
+# message could be lost or interleaved with the next tool call's
+# output. The CLI is cheap on the hot path: below the threshold it
+# only bumps an integer counter file and exits, no audit scan, no
+# roster discovery.
+#
+# # CLI-resolution trust boundary
+#
+# Same 2-tier sandboxed resolution `delegation-capture.sh`,
+# `protected-paths-bash-gate.sh`, and `blocked-paths-bash-gate.sh` use:
+#   1. node_modules/@bookedsolid/rea/dist/cli/index.js (consumer-side
+#      published artifact)
+#   2. dist/cli/index.js under CLAUDE_PROJECT_DIR (the rea repo's own
+#      dogfood install)
+# PATH lookup is INTENTIONALLY OMITTED — agent-controlled $PATH would
+# let a forged `rea` binary intercept this hook on every write-class
+# tool call. A realpath sandbox check ensures the resolved CLI lives
+# INSIDE realpath(CLAUDE_PROJECT_DIR) with an ancestor package.json
+# declaring `@bookedsolid/rea`.
+#
+# Exit codes:
+#   0 — always (under normal operation). Disabled-by-policy,
+#       below-threshold, already-fired, just-fired — all exit 0.
+#   2 — HALT active.
+
+set -uo pipefail
+
+# 1. HALT check. Even though this hook is advisory, refusing to run
+#    while frozen matches the rest of the hook tree and keeps the
+#    kill-switch contract uniform.
+# shellcheck source=_lib/halt-check.sh
+source "$(dirname "$0")/_lib/halt-check.sh"
+check_halt
+REA_ROOT=$(rea_root)
+
+proj="${CLAUDE_PROJECT_DIR:-$REA_ROOT}"
+
+# 2. Resolve the rea CLI through the fixed 2-tier sandboxed order.
+#    PATH lookup is omitted on purpose (see header). Other install
+#    shapes silently drop the advisory — matching the bash-gate
+#    posture; the nudge is a convenience, not a security claim.
+REA_ARGV=()
+RESOLVED_CLI_PATH=""
+if [ -f "$proj/node_modules/@bookedsolid/rea/dist/cli/index.js" ]; then
+  REA_ARGV=(node "$proj/node_modules/@bookedsolid/rea/dist/cli/index.js")
+  RESOLVED_CLI_PATH="$proj/node_modules/@bookedsolid/rea/dist/cli/index.js"
+elif [ -f "$proj/dist/cli/index.js" ]; then
+  # rea repo dogfood: the project IS @bookedsolid/rea.
+  REA_ARGV=(node "$proj/dist/cli/index.js")
+  RESOLVED_CLI_PATH="$proj/dist/cli/index.js"
+fi
+
+if [ "${#REA_ARGV[@]}" -eq 0 ]; then
+  # No rea CLI in scope — drop the advisory silently. This is the
+  # expected state during bootstrap (consumer ran `rea init` but
+  # hasn't installed the npm package yet) or in non-rea repos. A
+  # noisy stderr warning here would fire on every write-class tool
+  # call and drown legitimate output.
+  exit 0
+fi
+
+# 3. Realpath sandbox check — mirrors delegation-capture.sh §3 and
+#    protected-paths-bash-gate.sh §6. The resolved CLI MUST live inside
+#    realpath(CLAUDE_PROJECT_DIR) AND have an ancestor package.json
+#    declaring `@bookedsolid/rea` as its `name`. Catches symlink-out
+#    attacks where an attacker writes
+#    node_modules/@bookedsolid/rea → /tmp/forged-tree.
+if ! command -v node >/dev/null 2>&1; then
+  # Node not on PATH — we can't verify the CLI shape. Fail safe by
+  # dropping the advisory (it is not a security claim; the rest of
+  # the Bash gate suite refuses on this path).
+  exit 0
+fi
+
+sandbox_check=$(node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const cli = process.argv[1];
+  const projDir = process.argv[2];
+  let real, realProj;
+  try { real = fs.realpathSync(cli); } catch (e) {
+    process.stdout.write("bad:realpath");
+    process.exit(1);
+  }
+  try { realProj = fs.realpathSync(projDir); } catch (e) {
+    process.stdout.write("bad:realpath-proj");
+    process.exit(1);
+  }
+  const sep = path.sep;
+  const projWithSep = realProj.endsWith(sep) ? realProj : realProj + sep;
+  if (!(real === realProj || real.startsWith(projWithSep))) {
+    process.stdout.write("bad:cli-escapes-project");
+    process.exit(1);
+  }
+  // Walk up looking for package.json with the protected name.
+  let cur = path.dirname(path.dirname(path.dirname(real))); // pkg root
+  let found = false;
+  for (let i = 0; i < 20 && cur && cur !== path.dirname(cur); i += 1) {
+    const pj = path.join(cur, "package.json");
+    if (fs.existsSync(pj)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(pj, "utf8"));
+        if (data && data.name === "@bookedsolid/rea") { found = true; break; }
+      } catch (e) { /* keep walking */ }
+    }
+    cur = path.dirname(cur);
+  }
+  if (!found) {
+    process.stdout.write("bad:no-rea-pkg-json");
+    process.exit(1);
+  }
+  process.stdout.write("ok");
+' -- "$RESOLVED_CLI_PATH" "$proj" 2>/dev/null)
+
+if [ "$sandbox_check" != "ok" ]; then
+  # CLI failed the sandbox check — silent drop. The forensic
+  # breadcrumb in stderr is intentional but trimmed so this doesn't
+  # become spammy on every tool call.
+  printf 'rea: delegation-advisory skipped (sandbox check: %s)\n' "$sandbox_check" >&2
+  exit 0
+fi
+
+# 4. Read stdin and pipe to the CLI SYNCHRONOUSLY. The advisory must
+#    print before this hook returns — see the "Synchronous" note in
+#    the header. We pass CLAUDE_PROJECT_DIR through explicitly so the
+#    CLI resolves the same REA_ROOT this shim did. The CLI's own exit
+#    code is the hook's exit code: 0 normally, 2 under HALT (the CLI
+#    re-checks HALT itself for defense-in-depth).
+INPUT=$(cat)
+printf '%s' "$INPUT" | "${REA_ARGV[@]}" hook delegation-advisory
+exit $?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",