@bookedsolid/rea 0.28.2 → 0.30.0

package/dist/cli/doctor.js

@@ -1,17 +1,24 @@
+import { execFileSync } from 'node:child_process';
+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';
 import { loadFingerprintStore } from '../registry/fingerprints-store.js';
 import { fingerprintServer } from '../registry/fingerprint.js';
 import { CodexProbe } from '../gateway/observability/codex-probe.js';
-import { inspectPrePushState } from './install/pre-push.js';
+import { inspectPrePushState, isHusky9Stub, resolveHusky9StubTarget, } from './install/pre-push.js';
 import { summarizeTelemetry } from '../gateway/observability/codex-telemetry.js';
 import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFiles, } from './install/canonical.js';
 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 { PREPARE_COMMIT_MSG_BODY_MARKER, PREPARE_COMMIT_MSG_MARKER, } from './install/prepare-commit-msg.js';
+import { validateSettings } from '../config/settings-schema.js';
 import { POLICY_FILE, REA_DIR, REGISTRY_FILE, getPkgVersion, log, reaPath } from './utils.js';
 function checkFileExists(label, filePath, fatal) {
     const exists = fs.existsSync(filePath);
@@ -130,7 +137,15 @@ function checkRegistryParses(baseDir, registryPath) {
         };
     }
 }
-const EXPECTED_AGENTS = [
+/**
+ * 0.30.0 (Class M settings.json schema) — `EXPECTED_HOOKS` is exported
+ * so the schema validator at `src/config/settings-schema.ts` can
+ * cross-check rea-shipped hook filenames against entries it sees in
+ * a consumer's `.claude/settings.json`. The validator's `--strict`
+ * mode FAILS when a known rea-managed hook is missing from the
+ * consumer's registration; default mode logs a warn.
+ */
+export const EXPECTED_AGENTS = [
     'accessibility-engineer.md',
     'backend-engineer.md',
     'code-reviewer.md',
@@ -142,7 +157,7 @@ const EXPECTED_AGENTS = [
     'technical-writer.md',
     'typescript-specialist.md',
 ];
-const EXPECTED_HOOKS = [
+export const EXPECTED_HOOKS = [
     'architecture-review-gate.sh',
     'attribution-advisory.sh',
     // 0.22.0 — Bash-tier parity with `blocked-paths-enforcer.sh`.
@@ -154,6 +169,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).
@@ -220,6 +242,85 @@ function checkHooksInstalled(baseDir) {
     }
     return { label: 'hooks installed + executable', status: 'fail', detail: issues.join('; ') };
 }
+/**
+ * 0.30.0 Class M — validate `.claude/settings.json` against the zod
+ * schema in `src/config/settings-schema.ts`.
+ *
+ * Status posture:
+ *
+ *   - `strict: false` (default `rea doctor`) — emit a warn when:
+ *       - zod parse fails (unknown top-level key, missing matcher,
+ *         malformed hook entry, etc.),
+ *       - any `command` contains a `..` traversal after stripping
+ *         `$CLAUDE_PROJECT_DIR`,
+ *       - any rea-shipped hook from `EXPECTED_HOOKS` is missing from
+ *         the consumer's registrations.
+ *     The harness keeps working — the schema only refuses to call
+ *     malformed hook entries; we surface the issue without breaking
+ *     the install.
+ *
+ *   - `strict: true` (`rea doctor --strict`) — fail (hard) on the
+ *     same conditions. Used by CI gates that want a hard floor on
+ *     consumer settings.
+ *
+ * Returns `pass` when everything cleared. Returns one `CheckResult`
+ * per concern; called once and emits one result. Combined with the
+ * existing `checkSettingsJson` (which checks for the historical Bash
+ * + Write|Edit|MultiEdit|NotebookEdit matchers), gives consumers a
+ * complete picture.
+ */
+export function checkSettingsSchema(baseDir, strict) {
+    const label = strict ? 'settings.json schema (strict)' : 'settings.json schema (advisory)';
+    const settingsPath = path.join(baseDir, '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+        return {
+            label,
+            status: strict ? 'fail' : 'warn',
+            detail: `missing: ${settingsPath}`,
+        };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(settingsPath, 'utf8');
+    }
+    catch (e) {
+        return {
+            label,
+            status: strict ? 'fail' : 'warn',
+            detail: e instanceof Error ? e.message : String(e),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return {
+            label,
+            status: 'fail',
+            detail: `malformed JSON: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    const result = validateSettings(parsed);
+    const issues = [];
+    if (!result.parsed) {
+        issues.push(...result.errors.map((e) => `schema: ${e}`));
+    }
+    for (const t of result.traversalFindings) {
+        issues.push(`traversal: ${t.event}[${t.matcher}].hooks[${t.index}].command — ${t.reason}`);
+    }
+    for (const missing of result.missingReaHooks) {
+        issues.push(`missing rea hook: ${missing} not registered in PreToolUse/PostToolUse`);
+    }
+    if (issues.length === 0) {
+        return { label, status: 'pass' };
+    }
+    return {
+        label,
+        status: strict ? 'fail' : 'warn',
+        detail: issues.join('; '),
+    };
+}
 function checkSettingsJson(baseDir) {
     const settingsPath = path.join(baseDir, '.claude', 'settings.json');
     if (!fs.existsSync(settingsPath)) {
@@ -333,6 +434,165 @@ export function isGitRepo(baseDir) {
     const resolved = path.isAbsolute(targetPath) ? targetPath : path.join(baseDir, targetPath);
     return fs.existsSync(resolved);
 }
+/**
+ * 0.30.0 attribution augmenter — verify the husky `prepare-commit-msg`
+ * hook state matches what `policy.attribution.co_author.enabled` asks
+ * for. Four buckets:
+ *
+ *   1. `enabled: true` + hook present + rea-managed marker → pass.
+ *   2. `enabled: true` + hook missing OR marker mismatched → fail.
+ *      Defense in depth: the loader's cross-field refinement should
+ *      already have rejected `enabled: true` without identity, but
+ *      we surface a missing hook file separately.
+ *   3. `enabled: true` + name OR email empty → fail. The loader should
+ *      have already caught this; surfacing here ensures `rea doctor`
+ *      reports a clean state for the entire augmenter surface.
+ *   4. `enabled: false` (or absent) + hook present (rea-managed) → pass
+ *      (no-op — hook ships under every install).
+ *   5. `enabled: false` (or absent) + foreign file → warn. The operator
+ *      has a `prepare-commit-msg` outside rea's marker; their commits
+ *      get whatever it does, which is fine.
+ *   6. `enabled: false` + hook absent → pass (vanilla state).
+ *
+ * Returns `info` when the rea-shipped `.git/hooks/prepare-commit-msg`
+ * lives under a hooksPath we couldn't resolve (treat as same as case
+ * 6 from doctor's perspective).
+ */
+/**
+ * Resolve the active git hooks directory for the doctor's prepare-commit-msg
+ * check. Mirrors `installCommitMsgHook`'s `readHooksPathFromGit` but
+ * synchronous (doctor is sync end-to-end). Honors `core.hooksPath` when set
+ * (husky 9 installs land at `.husky/_/`); falls back to `.git/hooks/`
+ * otherwise. Codex round 1 P2: prior implementation always looked at
+ * `.git/hooks/prepare-commit-msg`, false-reporting missing on any consumer
+ * running husky.
+ */
+function resolveHooksDirSync(baseDir) {
+    try {
+        const out = execFileSync('git', ['-C', baseDir, 'config', '--get', 'core.hooksPath'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const trimmed = out.trim();
+        if (trimmed.length > 0) {
+            return path.isAbsolute(trimmed) ? trimmed : path.join(baseDir, trimmed);
+        }
+    }
+    catch {
+        // git missing or `core.hooksPath` unset — fall through to default.
+    }
+    return path.join(baseDir, '.git', 'hooks');
+}
+export function checkPrepareCommitMsgHook(baseDir) {
+    const label = 'prepare-commit-msg hook (attribution augmenter)';
+    const hooksDir = resolveHooksDirSync(baseDir);
+    const hookPath = path.join(hooksDir, 'prepare-commit-msg');
+    let policyAttr;
+    try {
+        const policy = loadPolicy(baseDir);
+        policyAttr = policy.attribution?.co_author;
+    }
+    catch {
+        // policy-parse failure is surfaced elsewhere; default to "absent"
+        policyAttr = undefined;
+    }
+    const enabled = policyAttr?.enabled === true;
+    const hookExists = fs.existsSync(hookPath);
+    let hookIsReaManaged = false;
+    let hookMarkerMismatch = false;
+    if (hookExists) {
+        try {
+            let content = fs.readFileSync(hookPath, 'utf8');
+            // Codex round 3 P2: Husky 9 (`core.hooksPath=.husky/_`) auto-
+            // generates a stub like `. "${0%/*}/h"` at the active hooks path.
+            // Git dispatches through that stub to `.husky/prepare-commit-msg`
+            // (the canonical body, which IS rea-managed). Follow the
+            // indirection so doctor classifies the canonical body, not the
+            // stub. Same pattern as installer + pre-push doctor checks.
+            if (isHusky9Stub(content)) {
+                const target = resolveHusky9StubTarget(hookPath);
+                if (target !== null && target !== hookPath && fs.existsSync(target)) {
+                    try {
+                        content = fs.readFileSync(target, 'utf8');
+                    }
+                    catch {
+                        // canonical body unreadable — fall through with stub content,
+                        // which will classify as foreign and surface a clear error.
+                    }
+                }
+            }
+            const lines = content.split('\n');
+            hookIsReaManaged =
+                content.startsWith('#!/bin/sh\n') &&
+                    lines[1] === PREPARE_COMMIT_MSG_MARKER &&
+                    lines[2] === PREPARE_COMMIT_MSG_BODY_MARKER;
+            if (!hookIsReaManaged &&
+                content.includes('rea:prepare-commit-msg') &&
+                lines[1] !== PREPARE_COMMIT_MSG_MARKER) {
+                hookMarkerMismatch = true;
+            }
+        }
+        catch {
+            hookIsReaManaged = false;
+        }
+    }
+    if (enabled) {
+        if (!hookExists) {
+            return {
+                label,
+                status: 'fail',
+                detail: 'attribution.co_author.enabled: true but .git/hooks/prepare-commit-msg is missing — ' +
+                    'run `rea init` to install the hook, or set enabled: false.',
+            };
+        }
+        if (!hookIsReaManaged) {
+            const reason = hookMarkerMismatch
+                ? 'marker mismatch (older rea or hand-edited)'
+                : 'no rea marker';
+            return {
+                label,
+                status: 'fail',
+                detail: `attribution.co_author.enabled: true but the prepare-commit-msg hook is foreign (${reason}) — ` +
+                    'remove the existing hook and re-run `rea init`, or set enabled: false.',
+            };
+        }
+        const name = (policyAttr?.name ?? '').trim();
+        const email = (policyAttr?.email ?? '').trim();
+        if (name.length === 0 || email.length === 0) {
+            const which = name.length === 0 ? 'name' : 'email';
+            return {
+                label,
+                status: 'fail',
+                detail: `attribution.co_author.enabled: true but ${which} is empty — ` +
+                    'the policy loader should have rejected this; if you are seeing this, edit ' +
+                    '.rea/policy.yaml and either set both name+email or set enabled: false.',
+            };
+        }
+        return {
+            label,
+            status: 'pass',
+            detail: `enabled — trailer: ${name} <${email}>`,
+        };
+    }
+    // enabled: false (or absent).
+    if (!hookExists) {
+        return { label, status: 'pass', detail: 'disabled (no hook installed — vanilla state)' };
+    }
+    if (hookIsReaManaged) {
+        return {
+            label,
+            status: 'pass',
+            detail: 'disabled (rea-managed hook present, runs as no-op)',
+        };
+    }
+    return {
+        label,
+        status: 'warn',
+        detail: 'foreign prepare-commit-msg hook present — rea would refuse to overwrite. ' +
+            'When you enable attribution.co_author.enabled, the existing hook must be ' +
+            'removed or migrated to a fragment first.',
+    };
+}
 function checkCommitMsgHook(baseDir) {
     const hookPath = path.join(baseDir, '.git', 'hooks', 'commit-msg');
     if (!fs.existsSync(hookPath)) {
@@ -707,6 +967,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
@@ -722,7 +1216,7 @@ function codexRequiredFromPolicy(baseDir) {
  *
  * `activeForeign` always yields `fail` — a foreign hook bypassing the gate is a hard governance gap.
  */
-export function collectChecks(baseDir, codexProbeState, prePushState) {
+export function collectChecks(baseDir, codexProbeState, prePushState, options = {}) {
     const policyPath = reaPath(baseDir, POLICY_FILE);
     const registryPath = reaPath(baseDir, REGISTRY_FILE);
     const reaDirPath = path.join(baseDir, REA_DIR);
@@ -733,6 +1227,17 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         checkAgentsPresent(baseDir),
         checkHooksInstalled(baseDir),
         checkSettingsJson(baseDir),
+        // 0.30.0 Class M — strict zod schema check of the full
+        // .claude/settings.json shape. Complements checkSettingsJson
+        // (matcher coverage) and checkDelegationHookRegistered (Agent|Skill
+        // wiring). Hard fail under `--strict`, warn by default.
+        checkSettingsSchema(baseDir, options.strict === true),
+        // 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
@@ -740,6 +1245,10 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
     // other non-source-code directories that consume rea governance.
     if (isGitRepo(baseDir)) {
         checks.push(checkCommitMsgHook(baseDir));
+        // 0.30.0 attribution augmenter — only check when policy.attribution
+        // is declared. Vanilla installs without the block see no check
+        // (cleaner output for consumers who don't opt in).
+        checks.push(checkPrepareCommitMsgHook(baseDir));
         if (prePushState !== undefined) {
             checks.push(checkPrePushHook(prePushState));
         }
@@ -952,11 +1461,20 @@ export async function runDoctor(opts = {}) {
     catch {
         prePushState = undefined;
     }
-    const checks = collectChecks(baseDir, probeState, prePushState);
+    const checks = collectChecks(baseDir, probeState, prePushState, {
+        strict: opts.strict === true,
+    });
     // G7: async fingerprint-store check. Kept out of `collectChecks` so the
     // 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.