@bookedsolid/rea 0.28.1 → 0.29.0

package/dist/cli/audit-specialists.js

@@ -0,0 +1,220 @@
+/**
+ * `rea audit specialists` — 0.29.0 reader CLI for delegation-telemetry.
+ *
+ * Walks `.rea/audit.jsonl`, filters records by
+ * `tool_name === 'rea.delegation_signal'`, groups by
+ * `metadata.subagent_type`, and prints a table (default) or JSON
+ * document (`--json`).
+ *
+ * # Current-session-only in v1
+ *
+ * v1 has NO `--since` flag and NO `--session=ID` flag. The principal-
+ * engineer scope-cut deferred both to 0.29.1. The filter is:
+ *
+ *   - If `CLAUDE_SESSION_ID` is set, include only records whose
+ *     `metadata.session_id_observed` matches.
+ *   - Otherwise, include all records in the chain and print a note so
+ *     the operator knows what they're seeing.
+ *
+ * # Output shape
+ *
+ *   subagent_type            count   last_seen (UTC)
+ *   rea-orchestrator         12      2026-05-12T21:30:00Z
+ *   code-reviewer             5      2026-05-12T21:28:00Z
+ *   deep-dive                 2      2026-05-12T21:14:00Z
+ *
+ * JSON mode prints `{ session_filter, records, groups }` where
+ * `records` is the raw filtered subset (for piping into jq) and
+ * `groups` is the per-subagent rollup.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DELEGATION_SIGNAL_TOOL_NAME, DELEGATION_SIGNAL_SCHEMA_VERSION, } from '../audit/delegation-event.js';
+import { AUDIT_FILE, REA_DIR, log } from './utils.js';
+/**
+ * Type guard for a record that has the delegation-signal shape. Skips
+ * envelope shape validation (zod runs at write time); checks only the
+ * fields the reader actually uses.
+ */
+function isDelegationRecord(r) {
+    if (r.tool_name !== DELEGATION_SIGNAL_TOOL_NAME)
+        return false;
+    const m = r.metadata;
+    if (m === undefined)
+        return false;
+    if (m.schema_version !== DELEGATION_SIGNAL_SCHEMA_VERSION)
+        return false;
+    if (m.delegation_tool !== 'Agent' && m.delegation_tool !== 'Skill')
+        return false;
+    if (typeof m.subagent_type !== 'string')
+        return false;
+    return true;
+}
+/**
+ * Read the audit file and return delegation records (filtered + parsed
+ * into a reader-friendly shape). Malformed lines are skipped silently
+ * — `rea audit verify` is the right tool for chain integrity.
+ */
+export async function loadDelegationRecords(baseDir, sessionFilter) {
+    const auditFile = path.join(baseDir, REA_DIR, AUDIT_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(auditFile, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            return { records: [], filesScanned: [] };
+        }
+        throw e;
+    }
+    const records = [];
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isDelegationRecord(parsed))
+            continue;
+        const m = parsed.metadata;
+        if (sessionFilter !== null && m.session_id_observed !== sessionFilter)
+            continue;
+        const rec = {
+            timestamp: parsed.timestamp,
+            session_id_observed: m.session_id_observed,
+            delegation_tool: m.delegation_tool,
+            subagent_type: m.subagent_type,
+            parent_subagent_type: m.parent_subagent_type,
+            invocation_description_sha256: m.invocation_description_sha256,
+            ...(m.hook_event_timestamp !== undefined
+                ? { hook_event_timestamp: m.hook_event_timestamp }
+                : {}),
+        };
+        records.push(rec);
+    }
+    return { records, filesScanned: [auditFile] };
+}
+/**
+ * Group records by `subagent_type`. Sorts by descending count, then
+ * alphabetical on tie. `last_seen` is the latest envelope timestamp in
+ * the group.
+ */
+export function groupBySubagent(records) {
+    const byName = new Map();
+    for (const r of records) {
+        let g = byName.get(r.subagent_type);
+        if (g === undefined) {
+            g = {
+                subagent_type: r.subagent_type,
+                count: 0,
+                last_seen: r.timestamp,
+                by_tool: { Agent: 0, Skill: 0 },
+            };
+            byName.set(r.subagent_type, g);
+        }
+        g.count += 1;
+        g.by_tool[r.delegation_tool] += 1;
+        if (r.timestamp > g.last_seen)
+            g.last_seen = r.timestamp;
+    }
+    return Array.from(byName.values()).sort((a, b) => {
+        if (b.count !== a.count)
+            return b.count - a.count;
+        return a.subagent_type.localeCompare(b.subagent_type);
+    });
+}
+/**
+ * Computation-only entrypoint. Returns the full result so callers
+ * (CLI, tests) can render or assert. `runAuditSpecialists` is the thin
+ * commander wrapper that prints + exits.
+ */
+export async function computeAuditSpecialists(options = {}) {
+    const baseDir = options.baseDir ?? process.cwd();
+    let sessionFilter;
+    let source;
+    if (options.sessionFilter === undefined) {
+        const envId = process.env['CLAUDE_SESSION_ID'];
+        if (typeof envId === 'string' && envId.length > 0) {
+            sessionFilter = envId;
+            source = 'env';
+        }
+        else {
+            sessionFilter = null;
+            source = 'none';
+        }
+    }
+    else {
+        sessionFilter = options.sessionFilter;
+        source = options.sessionFilter === null ? 'none' : 'option';
+    }
+    const { records, filesScanned } = await loadDelegationRecords(baseDir, sessionFilter);
+    const groups = groupBySubagent(records);
+    return {
+        session_filter: sessionFilter,
+        session_filter_source: source,
+        records,
+        groups,
+        files_scanned: filesScanned,
+    };
+}
+function renderTable(result) {
+    if (result.groups.length === 0) {
+        const note = result.session_filter !== null
+            ? `No delegation signals recorded for session ${result.session_filter}.`
+            : 'No delegation signals recorded.';
+        return `${note}\n  (Records are written by the .claude/hooks/delegation-capture.sh PreToolUse hook on every Agent/Skill dispatch.)\n`;
+    }
+    const headers = ['subagent_type', 'count', 'agent', 'skill', 'last_seen (UTC)'];
+    const rows = result.groups.map((g) => [
+        g.subagent_type,
+        String(g.count),
+        String(g.by_tool.Agent),
+        String(g.by_tool.Skill),
+        g.last_seen,
+    ]);
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const lines = [];
+    lines.push(headers.map((h, i) => h.padEnd(widths[i])).join('  '));
+    lines.push(widths.map((w) => '-'.repeat(w)).join('  '));
+    for (const row of rows) {
+        lines.push(row.map((c, i) => c.padEnd(widths[i])).join('  '));
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Commander entrypoint. Reads, renders, exits 0. The CLI is read-only
+ * — no audit-chain writes, no exit-code-as-verdict semantics.
+ */
+export async function runAuditSpecialists(options) {
+    const result = await computeAuditSpecialists(options);
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+    }
+    if (result.session_filter !== null) {
+        log(`Delegation signals (session=${result.session_filter}, source=${result.session_filter_source}):`);
+    }
+    else {
+        log('Delegation signals (no session filter — set $CLAUDE_SESSION_ID to scope; v1 omits --since / --session by design):');
+    }
+    process.stdout.write(renderTable(result));
+}
+/**
+ * Attach the `specialists` subcommand to the `rea audit` command group.
+ * Exported as a registrar so `src/cli/index.ts` can wire it next to the
+ * existing `rotate` and `verify` subcommands without leaking commander
+ * knowledge into this module.
+ */
+export function registerAuditSpecialistsSubcommand(auditCommand) {
+    auditCommand
+        .command('specialists')
+        .description('Summarize `rea.delegation_signal` audit records — counts per subagent / skill, last-seen timestamps, agent-vs-skill breakdown. Reads only the current `.rea/audit.jsonl`. Honors $CLAUDE_SESSION_ID for current-session filtering. v1 omits --since / --session by design (deferred to 0.29.1).')
+        .option('--json', 'emit JSON (records + groups) instead of the human-readable table. Composes with jq.')
+        .action(async (opts) => {
+        await runAuditSpecialists({ ...(opts.json === true ? { json: true } : {}) });
+    });
+}

package/dist/cli/doctor.d.ts

@@ -65,6 +65,63 @@ export declare function checkCodexBinaryOnPath(): CheckResult;
  * the real probe.
  */
 export declare function checksFromProbeState(state: CodexProbeState): CheckResult[];
+/**
+ * 0.29.0 — verify the delegation-capture hook is registered in
+ * `.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).
+ *
+ * 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.
+ */
+export declare function checkDelegationHookRegistered(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:
+ *
+ *   - The CLI exited 0.
+ *   - A new `rea.delegation_signal` record landed on disk.
+ *   - The record's metadata contains the probe tag (so we don't
+ *     mistakenly attribute an existing record to our run).
+ *   - 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.
+ */
+export declare function checkDelegationRoundTrip(baseDir: string): Promise<CheckResult>;
 /**
  * Assemble the full checklist for a given baseDir. Exported so tests can
  * exercise the conditional branching without capturing stdout from
@@ -91,6 +148,14 @@ export interface RunDoctorOptions {
      * `rea upgrade` to reconcile).
      */
     drift?: boolean;
+    /**
+     * 0.29.0 — when true, run the synthetic delegation-signal round-trip
+     * check. Writes a probe `rea.delegation_signal` audit record (with
+     * the doctor-smoke session id) and verifies chain integrity. Gated
+     * behind a flag so casual `rea doctor` invocations don't pollute the
+     * audit log with probe records.
+     */
+    smoke?: boolean;
 }
 export interface DriftRow {
     path: string;

package/dist/cli/doctor.js

@@ -1,4 +1,6 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
 import path from 'node:path';
 import { loadPolicy } from '../policy/loader.js';
 import { loadRegistry } from '../registry/loader.js';
@@ -12,6 +14,8 @@ import { buildFragment } from './install/claude-md.js';
 import { canonicalSettingsSubsetHash, defaultDesiredHooks } from './install/settings-merge.js';
 import { manifestExists, readManifest } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
+import { DELEGATION_SIGNAL_TOOL_NAME } from '../audit/delegation-event.js';
+import { computeHash } from '../audit/fs.js';
 import { POLICY_FILE, REA_DIR, REGISTRY_FILE, getPkgVersion, log, reaPath } from './utils.js';
 function checkFileExists(label, filePath, fatal) {
     const exists = fs.existsSync(filePath);
@@ -154,6 +158,13 @@ const EXPECTED_HOOKS = [
     'blocked-paths-enforcer.sh',
     'changeset-security-gate.sh',
     'dangerous-bash-interceptor.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
+    // open so missing rea binary doesn't crash dispatch. Doctor surfaces
+    // a missing hook file so consumers don't silently lose the signal
+    // after upgrade.
+    'delegation-capture.sh',
     'dependency-audit-gate.sh',
     'env-file-protection.sh',
     // 0.26.0 local-first enforcement (CTO directive 2026-05-05).
@@ -707,6 +718,240 @@ function codexRequiredFromPolicy(baseDir) {
         return true;
     }
 }
+/**
+ * 0.29.0 — verify the delegation-capture hook is registered in
+ * `.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).
+ *
+ * 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.
+ */
+export function checkDelegationHookRegistered(baseDir) {
+    const label = 'delegation-capture hook registered';
+    const ADVISORY = 'warn';
+    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.29.0; promoted to fail in 0.30.0)`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    }
+    catch (e) {
+        return {
+            label,
+            status: ADVISORY,
+            detail: e instanceof Error ? e.message : String(e),
+        };
+    }
+    const groups = parsed.hooks?.PreToolUse ?? [];
+    const group = groups.find((g) => g.matcher === 'Agent|Skill');
+    if (group === undefined) {
+        return {
+            label,
+            status: ADVISORY,
+            detail: 'no PreToolUse group with matcher "Agent|Skill" found in .claude/settings.json — ' +
+                'run `rea upgrade` to install (advisory in 0.29.0; promoted to fail in 0.30.0). ' +
+                'NOTE: matcher MUST be exactly `Agent|Skill` ' +
+                '(NOT `Task|Skill` — `TaskCreate`/`TaskList` are unrelated todo-list tools).',
+        };
+    }
+    const cmds = (group.hooks ?? []).map((h) => typeof h.command === 'string' ? h.command : '');
+    if (!cmds.some((c) => c.includes('delegation-capture.sh'))) {
+        return {
+            label,
+            status: ADVISORY,
+            detail: 'Agent|Skill matcher exists but no delegation-capture.sh command found in its hooks list',
+        };
+    }
+    return { label, status: 'pass' };
+}
+/**
+ * 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:
+ *
+ *   - The CLI exited 0.
+ *   - A new `rea.delegation_signal` record landed on disk.
+ *   - The record's metadata contains the probe tag (so we don't
+ *     mistakenly attribute an existing record to our run).
+ *   - 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.
+ */
+export async function checkDelegationRoundTrip(baseDir) {
+    const probeTag = `doctor-smoke-${process.pid}-${Date.now()}`;
+    // Resolve the rea CLI binary the same way the shell hook does.
+    // First-class: this very process is running rea, so `process.argv[1]`
+    // is the right entrypoint. Fall back to the dist path in
+    // node_modules.
+    const cliEntry = process.argv[1];
+    if (cliEntry === undefined || cliEntry.length === 0) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: 'could not resolve the rea CLI entrypoint (process.argv[1] empty)',
+        };
+    }
+    // Codex round 4 P3 (2026-05-12): exercise a NON-EMPTY description
+    // so the smoke check actually validates SHA-256 hashing of prompt
+    // content. Pre-fix the description was '' and the hash was always
+    // the well-known empty-string SHA-256 — a regression that ignored
+    // tool_input.description and substituted an empty hash would have
+    // passed the smoke check.
+    const probeDescription = `doctor-smoke probe (${probeTag})`;
+    const expectedDescriptionHash = crypto
+        .createHash('sha256')
+        .update(probeDescription)
+        .digest('hex');
+    const payload = JSON.stringify({
+        tool_name: 'Agent',
+        session_id: 'doctor-smoke',
+        tool_input: {
+            subagent_type: probeTag,
+            description: probeDescription,
+        },
+    });
+    const auditPath = path.join(baseDir, '.rea', 'audit.jsonl');
+    // Synchronously spawn the CLI. The blocking wait is appropriate for
+    // a doctor check — the operator just typed `rea doctor --smoke` and
+    // is waiting for output anyway. `--detach` is NOT passed: we want
+    // the CLI to await its own append (the post-P1 fix) and exit
+    // cleanly.
+    const { spawnSync } = await import('node:child_process');
+    const res = spawnSync(process.execPath, [cliEntry, 'hook', 'delegation-signal'], {
+        cwd: baseDir,
+        input: payload,
+        encoding: 'utf8',
+        timeout: 15_000,
+        env: { ...process.env, CLAUDE_PROJECT_DIR: baseDir },
+    });
+    if (res.error !== undefined) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: `CLI spawn failed: ${res.error.message}`,
+        };
+    }
+    if (res.status !== 0) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: `CLI exited ${res.status ?? 'null'}; stderr: ${(res.stderr ?? '').slice(0, 240)}`,
+        };
+    }
+    // Read the audit log and find the record carrying our probe tag.
+    let raw;
+    try {
+        raw = await fsPromises.readFile(auditPath, 'utf8');
+    }
+    catch (e) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: `audit log read failed: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    const lines = raw.split('\n').filter((l) => l.length > 0);
+    let matched = null;
+    for (const line of lines) {
+        try {
+            const p = JSON.parse(line);
+            if (p.tool_name === DELEGATION_SIGNAL_TOOL_NAME && p.metadata?.subagent_type === probeTag) {
+                matched = { line, parsed: p };
+            }
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    if (matched === null) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: `CLI exited 0 but no ` +
+                `rea.delegation_signal record with probe-tag ${probeTag} found in audit.jsonl`,
+        };
+    }
+    // Codex round 4 P3 (2026-05-12): assert the recorded
+    // invocation_description_sha256 matches the expected hash of the
+    // probe description we sent. Catches a regression where the parser
+    // ignores tool_input.description and substitutes the empty hash.
+    const recordedDescHash = matched.parsed.metadata?.invocation_description_sha256;
+    if (recordedDescHash !== expectedDescriptionHash) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: `recorded invocation_description_sha256 mismatch: ` +
+                `expected ${expectedDescriptionHash.slice(0, 16)}…, ` +
+                `got ${(recordedDescHash ?? 'undefined').slice(0, 16)}…`,
+        };
+    }
+    // Verify chain integrity for the probe record. Recompute its hash
+    // over the record-minus-hash payload and compare.
+    const recordParsed = JSON.parse(matched.line);
+    const storedHash = recordParsed.hash;
+    if (typeof storedHash !== 'string' || storedHash.length !== 64) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: 'probe record has no valid `hash` field',
+        };
+    }
+    const { hash: _h, ...rest } = recordParsed;
+    void _h;
+    const recomputed = computeHash(rest);
+    if (recomputed !== storedHash) {
+        return {
+            label: 'delegation-signal round-trip',
+            status: 'fail',
+            detail: `chain integrity broken: stored=${storedHash} recomputed=${recomputed}`,
+        };
+    }
+    return {
+        label: 'delegation-signal round-trip',
+        status: 'pass',
+        detail: `probe via real CLI (hash=${storedHash.slice(0, 16)}, tag=${probeTag.slice(-8)})`,
+    };
+}
 /**
  * Assemble the full checklist for a given baseDir. Exported so tests can
  * exercise the conditional branching without capturing stdout from
@@ -733,6 +978,12 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         checkAgentsPresent(baseDir),
         checkHooksInstalled(baseDir),
         checkSettingsJson(baseDir),
+        // 0.29.0 — delegation-telemetry MVP wiring check. Separate from
+        // checkSettingsJson because that check only validates the
+        // existence of the Bash + Write|Edit|MultiEdit|NotebookEdit
+        // matcher groups. The Agent|Skill matcher is new and needs its
+        // own pass/fail signal.
+        checkDelegationHookRegistered(baseDir),
     ];
     // Non-git escape hatch: when `.git/` is absent, both git-hook checks are
     // meaningless (commit-msg + pre-push can't be invoked without git). Emit
@@ -957,6 +1208,13 @@ export async function runDoctor(opts = {}) {
     // existing sync contract stays intact for downstream consumers; appended
     // here so runDoctor surfaces it inline.
     checks.push(await checkFingerprintStore(baseDir));
+    // 0.29.0 — optional synthetic round-trip of the delegation-signal
+    // audit path. Only runs under `--smoke` because it writes a probe
+    // record to the audit chain; default `rea doctor` invocations leave
+    // the chain untouched.
+    if (opts.smoke === true) {
+        checks.push(await checkDelegationRoundTrip(baseDir));
+    }
     console.log('');
     log(`Doctor — ${baseDir}`);
     console.log('');

package/dist/cli/hook.d.ts

@@ -188,18 +188,50 @@ export interface HookCodexReviewOptions {
     rawStdoutDir?: string;
 }
 export declare function runHookCodexReview(options: HookCodexReviewOptions): Promise<void>;
+export interface HookDelegationSignalOptions {
+    /**
+     * Run the audit append in the background and return immediately. The
+     * shell hook stub sets this so the worst-case latency of the
+     * `Agent|Skill` PreToolUse hook stays in the tens-of-milliseconds
+     * range even when the audit chain is under cross-process contention.
+     */
+    detach?: boolean;
+    /**
+     * Override REA_ROOT. Tests set this; the production caller relies on
+     * `process.cwd()` or the `$CLAUDE_PROJECT_DIR` env var.
+     */
+    reaRoot?: string;
+    /**
+     * Lock-acquisition timeout in milliseconds. If `appendAuditRecord`
+     * hasn't returned within this budget, the CLI exits 0 with a stderr
+     * warning. The append is fire-and-forget at that point — we'd rather
+     * drop a single signal than block Claude Code's tool dispatch on
+     * audit-log contention. Default: 2000 ms.
+     */
+    lockTimeoutMs?: number;
+}
+/**
+ * Read the hook stdin payload, redact + hash, and either await the
+ * audit append OR fire-and-forget it (when `--detach` is set).
+ *
+ * Exit-code contract: ALWAYS exit 0. The delegation signal is
+ * observational, not gating — failure to write the record must NOT
+ * block Claude Code's tool dispatch. Errors are surfaced on stderr.
+ */
+export declare function runHookDelegationSignal(options: HookDelegationSignalOptions): Promise<void>;
 /**
  * Attach the `rea hook` subcommand tree to a commander Program.
  *
  * Subcommands:
- *   - `push-gate`     — stateless pre-push Codex review (called by husky).
- *   - `scan-bash`     — parser-backed bash-tier scanner (called by Claude
- *                       Code shim hooks).
- *   - `policy-get`    — single-source-of-truth policy reader for bash hooks.
- *   - `codex-review`  — thin Bash-direct codex invocation (0.27.0+) for
- *                       marathon-mode review cycles. The canonical
- *                       invocation that all agents and slash commands
- *                       route through.
+ *   - `push-gate`           — stateless pre-push Codex review (called by husky).
+ *   - `scan-bash`           — parser-backed bash-tier scanner (called by Claude
+ *                             Code shim hooks).
+ *   - `policy-get`          — single-source-of-truth policy reader for bash hooks.
+ *   - `codex-review`        — thin Bash-direct codex invocation (0.27.0+) for
+ *                             marathon-mode review cycles.
+ *   - `delegation-signal`   — 0.29.0 delegation-telemetry MVP. Reads a Claude
+ *                             Code PreToolUse hook payload for `Agent` / `Skill`
+ *                             and emits a `rea.delegation_signal` audit record.
  *
  * New hooks should land here rather than as top-level commands so the
  * CLI surface stays navigable.