@bookedsolid/rea 0.30.1 → 0.32.0

package/dist/cli/delegation-advisory.js

@@ -0,0 +1,433 @@
+/**
+ * `rea hook delegation-advisory` — the 0.31.0 delegation *nudge*.
+ *
+ * 0.29.0 shipped the delegation-telemetry observability layer (the
+ * `Agent|Skill` PreToolUse capture hook + `rea audit specialists`
+ * reader). It could *see* delegation patterns but said nothing about
+ * them. 0.31.0 closes the loop: the `delegation-advisory.sh` PostToolUse
+ * hook (matcher `Bash|Edit|Write|MultiEdit|NotebookEdit`) pipes each
+ * write-class tool call through this CLI, which maintains a per-session
+ * counter and — the FIRST time the counter crosses
+ * `policy.delegation_advisory.threshold` while the session has recorded
+ * ZERO real delegation signals — prints a one-time stderr advisory.
+ *
+ * # Advisory, never gating
+ *
+ * The CLI ALWAYS exits 0 except under HALT (exit 2, to keep the
+ * kill-switch contract uniform with the rest of the hook tree). It
+ * NEVER blocks a tool call. The whole point is a nudge — "this session
+ * has done a lot of work without delegating to a specialist" — not an
+ * enforcement gate. A consumer who disagrees sets
+ * `policy.delegation_advisory.enabled: false` (the schema default; only
+ * `bst-internal*` profiles pin `true`) and the hook is a silent no-op.
+ *
+ * # State: the per-session counter directory
+ *
+ * State lives under `.rea/.delegation-advisory/`:
+ *
+ *   - `<state-key>.count`  — a single integer, the running write-class
+ *     tool-call count for the session.
+ *   - `<state-key>.fired` — a sentinel file; present once the advisory
+ *     has fired for the session, so it never fires twice.
+ *
+ * The session id comes from the untrusted hook payload, so it is run
+ * through `sessionStateKey` before it touches a filesystem path. That
+ * key is `<readable-prefix>-<hash>`: a sanitized, length-capped prefix
+ * (`[A-Za-z0-9._-]` only — keeps the directory glanceable) plus a short
+ * SHA-256 hex digest of the RAW id. The hash suffix is the correctness
+ * half — a bare sanitized prefix is lossy (`a/b` and `a:b` both
+ * sanitize to `a_b`), so two distinct sessions would otherwise share
+ * `count`/`fired` files and one could inherit the other's counter or
+ * suppress the other's advisory. A missing / empty / non-string session
+ * id collapses to the literal `unknown` key, so sessions Claude Code
+ * didn't tag still get a (deliberately shared) counter rather than
+ * crashing the hook — and that matches the `'unknown'` audit-form id
+ * `runHookDelegationSignal` records for the same untagged sessions.
+ *
+ * The directory is best-effort: any filesystem error (ENOSPC, EACCES,
+ * a read-only `.rea/`) is swallowed and the CLI exits 0. Losing the
+ * nudge is acceptable; breaking tool dispatch is not.
+ *
+ * # The "did this session delegate" predicate
+ *
+ * A session has delegated when `.rea/audit.jsonl` contains at least one
+ * `rea.delegation_signal` record whose `session_id_observed` matches
+ * the current session AND that record counts as a REAL delegation per
+ * `countsAsRealDelegation` (see `src/cli/roster.ts`): every `Skill`
+ * signal counts; an `Agent` signal counts when its `subagent_type` is
+ * a discovered curated specialist and not in the exempt set.
+ *
+ * Scanning the whole audit chain on every write-class tool call would
+ * be wasteful, so the scan is gated: it only runs when the counter has
+ * actually reached the threshold (the rare case). Below the threshold
+ * the CLI just bumps the counter and exits.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { loadDelegationRecords, listRotatedAuditFiles, } from './audit-specialists.js';
+import { discoverRoster, countsAsRealDelegation, DEFAULT_EXEMPT_SUBAGENTS, } from './roster.js';
+import { REA_DIR } from './utils.js';
+const DEFAULT_THRESHOLD = 25;
+/**
+ * Maximum length of the human-readable prefix in a state key. The full
+ * key is `<prefix>-<16-hex-hash>`, so a 64-char cap keeps basenames well
+ * under any filesystem limit while staying glanceable.
+ */
+const STATE_KEY_PREFIX_CAP = 64;
+/**
+ * Derive a filesystem-safe, **collision-free** per-session state-key
+ * basename from an untrusted session id.
+ *
+ * Shape: `<readable-prefix>-<hash>` where
+ *
+ *   - `<readable-prefix>` is the raw id with every byte outside
+ *     `[A-Za-z0-9._-]` replaced by `_`, length-capped at
+ *     `STATE_KEY_PREFIX_CAP`. Path-traversal basenames (`.`, `..`) and
+ *     an empty/all-stripped result collapse to `unknown`. This half is
+ *     purely for human glanceability of the `.rea/.delegation-advisory/`
+ *     directory — it is intentionally lossy.
+ *   - `<hash>` is the first 16 hex chars of `sha256(raw)`. This is the
+ *     correctness half: the sanitized prefix alone is lossy (`a/b` and
+ *     `a:b` both sanitize to `a_b`), so without the hash two distinct
+ *     sessions would share `count`/`fired` files — one could inherit the
+ *     other's counter or suppress the other's advisory. The hash is
+ *     computed over the RAW id, so distinct raw ids always get distinct
+ *     keys.
+ *
+ * A missing / empty / non-string id returns the fixed key `unknown` (no
+ * hash suffix) — every untagged session deliberately shares one counter,
+ * matching the `'unknown'` audit-form id `runHookDelegationSignal`
+ * records for the same sessions.
+ *
+ * The result is always a safe single path segment: no `/`, no `..`, no
+ * leading dot beyond the literal `unknown`, bounded length.
+ */
+export function sessionStateKey(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return 'unknown';
+    const hash = crypto.createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, 16);
+    let prefix = raw.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, STATE_KEY_PREFIX_CAP);
+    // A prefix of `.` / `..` (or an all-stripped empty prefix) would make
+    // the basename start with a traversal-looking token; normalize it.
+    // The hash suffix still guarantees uniqueness, so this only affects
+    // the readable half.
+    if (prefix.length === 0 || prefix === '.' || prefix === '..')
+        prefix = 'session';
+    return `${prefix}-${hash}`;
+}
+/**
+ * Read `.rea/policy.yaml` and resolve the `delegation_advisory` block.
+ * Uses the canonical YAML parser (same as `rea hook policy-get`) so
+ * inline and block forms agree. A missing file / missing block / parse
+ * error all resolve to `enabled: false` — the safe default is "the
+ * nudge is off", matching the schema-layer default and the OSS-profile
+ * posture.
+ *
+ * The policy loader's strict zod schema is NOT used here: this CLI runs
+ * on EVERY write-class tool call and must never fail-loud on an
+ * unrelated policy typo (that's `rea doctor`'s job). A best-effort
+ * shallow read is the right posture for an advisory hook.
+ */
+function resolveAdvisoryPolicy(reaRoot) {
+    const off = {
+        enabled: false,
+        threshold: DEFAULT_THRESHOLD,
+        exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
+    };
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    let raw;
+    try {
+        raw = fs.readFileSync(policyPath, 'utf8');
+    }
+    catch {
+        return off;
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return off;
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return off;
+    const block = parsed['delegation_advisory'];
+    if (block === null || block === undefined || typeof block !== 'object') {
+        return off;
+    }
+    const b = block;
+    const enabled = b['enabled'] === true;
+    if (!enabled)
+        return off;
+    let threshold = DEFAULT_THRESHOLD;
+    if (typeof b['threshold'] === 'number' && Number.isInteger(b['threshold']) && b['threshold'] > 0) {
+        threshold = b['threshold'];
+    }
+    let exemptSubagents = DEFAULT_EXEMPT_SUBAGENTS;
+    if (Array.isArray(b['exempt_subagents'])) {
+        const list = b['exempt_subagents'].filter((x) => typeof x === 'string');
+        // An explicit empty list IS meaningful (the operator wants every
+        // Agent delegation to count) — only fall back to the default when
+        // the key is absent, which is the `=== DEFAULT` identity above.
+        exemptSubagents = list;
+    }
+    return { enabled, threshold, exemptSubagents };
+}
+/**
+ * Read the per-session counter. Missing file / unparseable contents →
+ * 0. Never throws.
+ */
+function readCounter(counterPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(counterPath, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    const n = Number.parseInt(raw.trim(), 10);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+}
+/**
+ * Write the per-session counter. Best-effort — a write failure is
+ * swallowed (the next invocation just re-reads the stale value, which
+ * at worst delays the nudge by one tool call).
+ */
+function writeCounter(counterPath, value) {
+    try {
+        fs.writeFileSync(counterPath, `${String(value)}\n`, 'utf8');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * The advisory text. Factored out so the test can assert on it without
+ * duplicating the prose. Printed to stderr (the hook's only output
+ * channel) exactly once per session.
+ */
+export function advisoryMessage(count, threshold) {
+    return (`\nrea: DELEGATION ADVISORY\n` +
+        `  This session has run ${String(count)} write-class tool calls ` +
+        `(Bash/Edit/Write/MultiEdit/NotebookEdit) — at or past the configured ` +
+        `threshold of ${String(threshold)} — without dispatching a curated ` +
+        `specialist.\n` +
+        `  rea's engineering model routes non-trivial work through the ` +
+        `rea-orchestrator agent (or a domain specialist from .claude/agents/).\n` +
+        `  Consider whether the remaining work would benefit from a specialist: ` +
+        `plan/build/review loops, adversarial review, domain expertise.\n` +
+        `  This is advisory only — it never blocks a tool call, and it fires ` +
+        `at most once per session. Set policy.delegation_advisory.enabled: false ` +
+        `to silence it.\n`);
+}
+/**
+ * Scan the audit chain for a REAL delegation signal in the current
+ * session. Returns `true` as soon as one is found (short-circuits).
+ *
+ * "Real" per `countsAsRealDelegation`: every `Skill` signal counts; an
+ * `Agent` signal counts when its `subagent_type` is a discovered
+ * curated specialist (live `.claude/agents/` roster) and not in the
+ * exempt set.
+ *
+ * Reuses `loadDelegationRecords` from `audit-specialists.ts` so the
+ * audit-record parsing / session filtering logic has a single home.
+ *
+ * # Rotated segments (0.31.0 round-2 P3)
+ *
+ * The scan walks rotated audit segments, not just the current
+ * `.rea/audit.jsonl`. A long session can outlive an audit rotation: its
+ * early `rea.delegation_signal` records land in a rotated file, and only
+ * later write-class calls land in the current `audit.jsonl`. Scanning
+ * the current file alone would miss that delegation and fire a
+ * false-positive nudge at a session that DID delegate. We resolve the
+ * full rotated set via `listRotatedAuditFiles` (the same resolution
+ * `rea audit specialists --since` uses) and hand the EARLIEST rotated
+ * filename to `loadDelegationRecords` as its `since` anchor —
+ * `resolveAuditFileWalk` then walks that file, every later rotated file,
+ * and the current `audit.jsonl` as the tail. No rotated files → the
+ * `since` anchor is `undefined` and behavior is the pre-0.31.0
+ * single-file walk.
+ */
+async function sessionHasRealDelegation(reaRoot, sessionId, exemptSubagents) {
+    let records;
+    try {
+        // Resolve the rotated-file set the same way `rea audit specialists`
+        // does. The earliest rotated filename is the `since` anchor:
+        // `resolveAuditFileWalk` walks from it forward through every later
+        // rotated segment, then the current `audit.jsonl`.
+        const rotated = await listRotatedAuditFiles(path.join(reaRoot, REA_DIR));
+        const sinceAnchor = rotated.length > 0 ? rotated[0] : undefined;
+        const loaded = await loadDelegationRecords(reaRoot, sessionId, sinceAnchor);
+        records = loaded.records;
+    }
+    catch {
+        // Audit log unreadable — we cannot prove the session delegated, so
+        // we DON'T fire (fail toward silence, not toward a false-positive
+        // nudge). Returning `true` here suppresses the advisory.
+        return true;
+    }
+    if (records.length === 0)
+        return false;
+    const roster = discoverRoster(reaRoot);
+    for (const rec of records) {
+        if (countsAsRealDelegation({
+            delegationTool: rec.delegation_tool,
+            subagentType: rec.subagent_type,
+            roster,
+            exempt: exemptSubagents,
+        })) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Read stdin synchronously to EOF. The hook shim feeds a small JSON
+ * blob; a bounded read is fine. Returns '' on any error or when stdin
+ * is a TTY (no harness payload).
+ */
+function readStdinSync() {
+    if (process.stdin.isTTY)
+        return '';
+    try {
+        return fs.readFileSync(0, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export async function computeDelegationAdvisory(options) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    // HALT check — uniform with the rest of the hook tree. The advisory
+    // hook is observational, but refusing to run while frozen keeps the
+    // kill-switch contract simple: every hook exits 2 under HALT.
+    const haltPath = path.join(reaRoot, '.rea', 'HALT');
+    if (fs.existsSync(haltPath)) {
+        return { outcome: 'halt' };
+    }
+    const policy = options.policyOverride ?? resolveAdvisoryPolicy(reaRoot);
+    if (!policy.enabled) {
+        return { outcome: 'disabled' };
+    }
+    const stdinRaw = options.stdinOverride ?? readStdinSync();
+    if (stdinRaw.length === 0) {
+        // No payload — nothing to count. Exit clean.
+        return { outcome: 'no-payload' };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(stdinRaw);
+    }
+    catch {
+        // Malformed payload — observational hook, swallow and exit clean.
+        return { outcome: 'no-payload' };
+    }
+    // Two forms of the session id, deliberately kept distinct:
+    //
+    //   - `auditSessionId` — the value to match against the audit log's
+    //     `session_id_observed` field. This MUST be byte-identical to what
+    //     `delegation-capture.sh` → `runHookDelegationSignal` recorded:
+    //     the untrusted `session_id` verbatim when it is a non-empty
+    //     string, and the literal `'unknown'` when it is missing / empty /
+    //     non-string. Mirroring that exact fallback is load-bearing —
+    //     using a bare `''` here would never match the `'unknown'` records
+    //     the capture hook writes for untagged sessions, so EVERY untagged
+    //     session that had actually delegated would still get a
+    //     false-positive nudge once its counter crossed the threshold.
+    //     (See `runHookDelegationSignal` in `hook.ts` for the canonical
+    //     fallback this kept in sync with — the policy-schema-style "kept
+    //     in sync by hand" contract.)
+    //   - `stateKey` — the `sessionStateKey()`-derived filesystem basename
+    //     (`<readable-prefix>-<sha256-hash>`). Used ONLY to build paths
+    //     under `.rea/.delegation-advisory/`. NEVER used for audit
+    //     matching, and — unlike a bare sanitized id — collision-free, so
+    //     two sessions whose ids only differ in characters sanitization
+    //     would flatten (`a/b` vs `a:b`) still get distinct state files.
+    const auditSessionId = typeof payload.session_id === 'string' && payload.session_id.length > 0
+        ? payload.session_id
+        : 'unknown';
+    const stateKey = sessionStateKey(payload.session_id);
+    // State directory. Best-effort mkdir — a failure here means we can't
+    // keep a counter, so we exit clean (the nudge is lost, tool dispatch
+    // is not).
+    const stateDir = path.join(reaRoot, '.rea', '.delegation-advisory');
+    try {
+        fs.mkdirSync(stateDir, { recursive: true });
+    }
+    catch {
+        return { outcome: 'ran', count: 0, fired: false, sessionId: stateKey };
+    }
+    const counterPath = path.join(stateDir, `${stateKey}.count`);
+    const firedPath = path.join(stateDir, `${stateKey}.fired`);
+    // Increment the counter for this write-class tool call.
+    const next = readCounter(counterPath) + 1;
+    writeCounter(counterPath, next);
+    // Below threshold → nothing more to do. This is the hot path: no
+    // audit scan, no roster discovery.
+    if (next < policy.threshold) {
+        return { outcome: 'ran', count: next, fired: false, sessionId: stateKey };
+    }
+    // Already fired this session → never fire twice.
+    if (fs.existsSync(firedPath)) {
+        return { outcome: 'ran', count: next, fired: false, sessionId: stateKey };
+    }
+    // At/past threshold and not yet fired — run the (rare) audit scan to
+    // decide whether the session has actually delegated. Pass the
+    // audit-form session id: audit records store the untrusted value
+    // verbatim (or `'unknown'` for untagged sessions), so the `stateKey`
+    // filesystem form would never match (see the comment at the
+    // `auditSessionId` / `stateKey` split above).
+    const delegated = await sessionHasRealDelegation(reaRoot, auditSessionId, policy.exemptSubagents);
+    if (delegated) {
+        // Session DID delegate to a real specialist — no nudge warranted.
+        // We deliberately do NOT write the `.fired` sentinel here: if the
+        // session later stops delegating and keeps piling on write-class
+        // calls, a future invocation should still be able to nudge. (The
+        // counter keeps climbing; the predicate is re-evaluated each time
+        // past the threshold.)
+        return { outcome: 'ran', count: next, fired: false, sessionId: stateKey };
+    }
+    // Fire the advisory. Write the sentinel FIRST so a crash between the
+    // print and the sentinel-write doesn't cause a double-fire on the
+    // next call — at-most-once is the contract, and a missed nudge is
+    // better than a repeated one.
+    try {
+        fs.writeFileSync(firedPath, `${new Date().toISOString()}\n`, 'utf8');
+    }
+    catch {
+        // Can't write the sentinel — fire anyway, but accept the small
+        // risk of a second fire. Still better than never nudging.
+    }
+    process.stderr.write(advisoryMessage(next, policy.threshold));
+    return { outcome: 'ran', count: next, fired: true, sessionId: stateKey };
+}
+/**
+ * Commander entrypoint. Reads the hook payload, runs the advisory
+ * logic, exits.
+ *
+ * Exit-code contract:
+ *   0 — always, EXCEPT HALT. Disabled, no-payload, below-threshold,
+ *       already-fired, just-fired — all exit 0. The advisory is a
+ *       nudge, never a gate.
+ *   2 — HALT active (kill-switch contract uniform with the hook tree).
+ */
+export async function runHookDelegationAdvisory(options = {}) {
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    const result = await computeDelegationAdvisory(options);
+    if (result.outcome === 'halt') {
+        // Surface the HALT reason — same shape the other hooks print.
+        let reason = 'Reason unknown';
+        try {
+            const content = fs.readFileSync(path.join(reaRoot, '.rea', 'HALT'), 'utf8');
+            reason = content.slice(0, 1024).trim() || reason;
+        }
+        catch {
+            /* leave default */
+        }
+        process.stderr.write(`REA HALT: ${reason}\nAll agent operations suspended. Run: rea unfreeze\n`);
+        process.exit(2);
+    }
+    process.exit(0);
+}

package/dist/cli/doctor.d.ts

@@ -109,56 +109,127 @@ export declare function checksFromProbeState(state: CodexProbeState): CheckResul
  * `.claude/settings.json` under PreToolUse with matcher `Agent|Skill`
  * AND that the hook file exists at the expected dogfood path.
  *
- * Status posture for 0.29.0:
- *
- * The 0.29.0 release introduces a new desired-hook entry in
- * `defaultDesiredHooks()` that `rea init` and `rea upgrade` will merge
- * into consumer `.claude/settings.json` files. Existing consumer
- * installs (and this repo's own dogfood, which is locked from
- * agent-driven edits by `settings-protection.sh`) won't have the
- * matcher registered until the operator runs `rea upgrade`.
- *
- * To keep the upgrade-lag period from breaking `rea doctor`, the
- * check is `warn` (not `fail`) for 0.29.0. The detail message names
- * the exact command to fix and points at the canonical
- * `delegation-capture.sh` install. After 0.29.0+1 consumer-install
- * cycles have propagated, this should be promoted to `fail` so a
- * skipped upgrade is loud rather than silent. Codex round 2 P2
- * (2026-05-12).
+ * Status posture:
+ *
+ * 0.29.0 shipped this check as `warn` (advisory) — the
+ * `defaultDesiredHooks()` entry was new, and existing consumer
+ * installs (plus this repo's own dogfood, locked from agent-driven
+ * edits by `settings-protection.sh`) wouldn't have the matcher
+ * registered until the operator ran `rea upgrade`. The comments
+ * promised promotion to `fail` "in 0.30.0".
+ *
+ * **0.31.0 makes good on that promise.** The 0.29.0 → 0.30.x consumer
+ * cycles have propagated; the `Agent|Skill` matcher has been in
+ * `defaultDesiredHooks()` for multiple minors. A consumer install
+ * that still lacks the registration is a real governance gap (the
+ * delegation telemetry — and now the 0.31.0 nudge — silently does
+ * nothing), so the check is `fail`. The detail message still names
+ * the exact `rea upgrade` fix.
  *
  * Hook-file presence is verified separately by `checkHooksInstalled`
- * via `EXPECTED_HOOKS` — that path stays at the hard-`fail` posture
- * because file presence is part of the install manifest and doesn't
- * suffer the same template-propagation lag.
+ * via `EXPECTED_HOOKS` — that path was always hard-`fail`.
  */
 export declare function checkDelegationHookRegistered(baseDir: string): CheckResult;
+/**
+ * 0.31.0 — verify the delegation-advisory hook is registered in
+ * `.claude/settings.json` under PostToolUse with matcher
+ * `Bash|Edit|Write|MultiEdit|NotebookEdit`, that a
+ * `delegation-advisory.sh` command is present in that group, AND that
+ * the `.claude/hooks/delegation-advisory.sh` file actually exists.
+ *
+ * Status posture: `warn` (advisory) for 0.31.0. This is a brand-new
+ * `defaultDesiredHooks()` entry — the exact same upgrade-lag situation
+ * `checkDelegationHookRegistered` faced in 0.29.0. Existing consumer
+ * installs (and this repo's own dogfood, locked from agent-driven
+ * edits by `settings-protection.sh`) won't have the PostToolUse group
+ * until the operator runs `rea upgrade`. Holding at `warn` for one
+ * release cycle keeps `rea doctor` green during propagation; a future
+ * minor promotes it to `fail` once consumer installs have caught up —
+ * the same ratchet `checkDelegationHookRegistered` just completed.
+ *
+ * The hook is ALSO advisory at runtime (it never blocks a tool call,
+ * and `policy.delegation_advisory` defaults to disabled), so a missing
+ * registration is a lower-stakes gap than a missing security gate —
+ * `warn` is proportionate even setting the upgrade-lag aside.
+ *
+ * # Why this check verifies file presence AND executability (round-2/3 P2)
+ *
+ * `delegation-advisory.sh` is deliberately NOT in `EXPECTED_HOOKS` for
+ * 0.31.0 (staged rollout — see the `EXPECTED_HOOKS` comment). That
+ * leaves THIS function as the only 0.31.0 doctor signal covering the
+ * new hook, so it must check the file too:
+ *
+ *   - File MISSING — a settings.json that references
+ *     `delegation-advisory.sh` while the actual script is absent (a
+ *     partial `rea upgrade`, manual drift) would otherwise report
+ *     `pass`, and every matching PostToolUse dispatch would shell out
+ *     to a nonexistent path.
+ *   - File present but NOT EXECUTABLE — a script copied without its
+ *     mode bits (a manual `cp`, an archive extracted without `+x`
+ *     preservation) cannot be launched by Claude Code from
+ *     `settings.json` at all. `checkHooksInstalled` performs this exact
+ *     `0o111` check for every `EXPECTED_HOOKS` entry; because
+ *     `delegation-advisory.sh` is held out of that list, the parity
+ *     check has to live here.
+ *
+ * Both failures are held at the same `warn` tier as the registration
+ * failures: consistent posture for 0.31.0, and they promote to `fail`
+ * alongside them — at which point `delegation-advisory.sh` also joins
+ * `EXPECTED_HOOKS` and gets the hard-`fail` `checkHooksInstalled`
+ * coverage (presence + executability) the other hooks have.
+ */
+export declare function checkDelegationAdvisoryHookRegistered(baseDir: string): CheckResult;
 /**
  * 0.29.0 — synthetic round-trip of the delegation-signal audit path.
- * Drives a synthetic Claude Code PreToolUse hook payload through the
- * REAL `rea hook delegation-signal` CLI by spawning a child process
- * (same path the shell hook hits) and asserts:
+ * 0.31.0 — drives the REAL `.claude/hooks/delegation-capture.sh` shell
+ * hook, not just the `rea hook delegation-signal` CLI underneath it.
  *
- *   - The CLI exited 0.
- *   - A new `rea.delegation_signal` record landed on disk.
+ * Feeds a synthetic Claude Code PreToolUse hook payload to the shell
+ * hook (the exact entry point Claude Code's `Agent|Skill` matcher
+ * invokes in production) and asserts:
+ *
+ *   - The shell hook exited 0.
+ *   - A new `rea.delegation_signal` record landed on disk — the smoke
+ *     check POLLS for it, because `delegation-capture.sh` backgrounds
+ *     + disowns the CLI (`& disown`) so the shell hook returns before
+ *     the audit append completes.
  *   - The record's metadata contains the probe tag (so we don't
  *     mistakenly attribute an existing record to our run).
+ *   - The recorded `invocation_description_sha256` matches the
+ *     expected hash of the probe description.
  *   - Chain integrity holds (recomputed hash == stored hash).
  *
- * Codex round 1 P2 (2026-05-12): the previous implementation called
- * `appendAuditRecord()` directly — short-circuiting stdin parsing,
- * SHA-256 hashing, redact-secrets timing, and the `process.exit`
- * ordering that round 1's P1 exposed. That made the smoke check
- * report success even when the real production path was broken.
- *
- * This rewrite exercises the same surface the `Agent|Skill`
- * PreToolUse hook does in production, so future regressions in
- * stdin parsing, hashing, redaction, or process-lifecycle behavior
- * fail the smoke check loudly.
- *
- * Gated behind `--smoke` so a casual `rea doctor` doesn't write
- * probe records on every invocation. Operators run
- * `rea doctor --smoke` after install / upgrade to confirm the
- * pipeline is wired end-to-end.
+ * # Why drive the shell hook, not the CLI directly
+ *
+ * 0.29.0's version spawned `rea hook delegation-signal` directly. That
+ * exercised the CLI's stdin parsing / hashing / redaction / process-
+ * lifecycle — but NOT the shell shim's own logic: the 2-tier sandboxed
+ * CLI resolution, the realpath sandbox check, the `& disown`
+ * backgrounding. A regression in the shim (a botched resolution order,
+ * a sandbox check that rejects the legitimate dogfood CLI, a
+ * backgrounding bug that drops the signal) would pass 0.29.0's smoke
+ * check while breaking production. 0.31.0 closes that gap: the smoke
+ * check now invokes `bash .claude/hooks/delegation-capture.sh` and
+ * the CLI is reached only through the shim.
+ *
+ * # Prerequisites and graceful degradation
+ *
+ * The check needs THREE things and degrades to `warn` (not `fail`)
+ * when any is absent — a missing prerequisite is an environment gap,
+ * not a wiring regression:
+ *
+ *   - `bash` on PATH.
+ *   - `.claude/hooks/delegation-capture.sh` present (the consumer
+ *     install path; absent before `rea init` / `rea upgrade`).
+ *   - A sandboxed rea CLI the shim can resolve — either
+ *     `<baseDir>/node_modules/@bookedsolid/rea/dist/cli/index.js` OR
+ *     `<baseDir>/dist/cli/index.js` (the rea-repo dogfood). Without
+ *     one the shim silently drops the signal by design, so the smoke
+ *     check would time out waiting for a record that will never land.
+ *
+ * Gated behind `--smoke` so a casual `rea doctor` doesn't write probe
+ * records on every invocation. Operators run `rea doctor --smoke`
+ * after install / upgrade to confirm the pipeline is wired end-to-end.
  */
 export declare function checkDelegationRoundTrip(baseDir: string): Promise<CheckResult>;
 /**