@bookedsolid/rea 0.30.1 → 0.32.0

package/dist/cli/index.js

@@ -148,7 +148,7 @@ async function main() {
         .description('Validate the install: policy parses, .rea/ layout, hooks, Codex plugin.')
         .option('--metrics', 'also print a 7-day summary of Codex telemetry (G11.5)')
         .option('--drift', 'report drift vs. the install manifest (read-only; does not mutate)')
-        .option('--smoke', 'also run the 0.29.0 delegation-signal round-trip (writes a probe `rea.delegation_signal` audit record and verifies chain integrity)')
+        .option('--smoke', 'also run the delegation-signal round-trip: drives the real `.claude/hooks/delegation-capture.sh` shell hook end-to-end (writes a probe `rea.delegation_signal` audit record and verifies chain integrity)')
         .option('--strict', '0.30.0 Class M — promote settings.json schema warnings (zod parse failures, path traversal, missing rea hooks) to hard fail. Use in CI gates.')
         .action(async (opts) => {
         await runDoctor({

package/dist/cli/install/settings-merge.js

@@ -380,5 +380,30 @@ export function defaultDesiredHooks() {
                 },
             ],
         },
+        {
+            // 0.31.0 delegation-telemetry completion — the *nudge*. The
+            // matcher is `Bash|Edit|Write|MultiEdit|NotebookEdit`: every
+            // write-class tool call (note this group INCLUDES Bash, unlike
+            // the architecture-review group above). The hook maintains a
+            // per-session counter and emits a one-time stderr advisory when
+            // a session crosses `policy.delegation_advisory.threshold`
+            // without dispatching a curated specialist. Advisory only — it
+            // never blocks a tool call, and `policy.delegation_advisory`
+            // defaults to disabled (only `bst-internal*` profiles pin
+            // `enabled: true`), so a vanilla install sees the hook as a
+            // silent no-op. Kept as its own matcher group rather than
+            // chained onto the architecture-review group because the
+            // matcher string differs (Bash is in this one, not that one).
+            event: 'PostToolUse',
+            matcher: 'Bash|Edit|Write|MultiEdit|NotebookEdit',
+            hooks: [
+                {
+                    type: 'command',
+                    command: `${base}/delegation-advisory.sh`,
+                    timeout: 10000,
+                    statusMessage: 'Checking delegation cadence...',
+                },
+            ],
+        },
     ];
 }

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/hooks/_lib/halt-check.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared HALT kill-switch reader for the Node-binary hook tier.
+ *
+ * 0.32.0 — extracted from `src/cli/hook.ts`. Pre-extraction the same
+ * `.rea/HALT` reader inlined twice (`runHookScanBash` lines 204-222 and
+ * `runHookCodexReview` lines 518-531) and `src/hooks/push-gate/halt.ts`
+ * carried a third copy with slightly different error semantics (the
+ * push-gate variant returns `{ halted: true, reason: 'unknown (HALT
+ * file unreadable)' }` on filesystem errors instead of falling through
+ * to allow). The Node-binary hook ports landing in 0.32.0 need the
+ * same primitive, so consolidate here before more copies accumulate.
+ *
+ * Contract:
+ *
+ *   - Returns `{ halted: false }` when `<reaRoot>/.rea/HALT` is absent.
+ *   - Returns `{ halted: true, reason }` when the file exists. `reason`
+ *     is the first non-empty line trimmed and capped at 1024 bytes;
+ *     missing/blank content collapses to `"Reason unknown"`.
+ *   - Filesystem errors during the read collapse to a halted sentinel
+ *     `"unknown (HALT file unreadable)"` — fail-CLOSED. The historical
+ *     `runHookScanBash` inline copy fell through to allow on read
+ *     failure; that is the wrong posture for a kill switch (an
+ *     attacker who can prevent the read should not get a free allow).
+ *     The push-gate's halt.ts already takes this stance; we converge.
+ *   - NEVER throws.
+ *
+ * Used by:
+ *   - `runHookScanBash`, `runHookCodexReview` (existing — migrated to
+ *     this primitive in 0.32.0)
+ *   - `runHookPrIssueLinkGate`, `runHookSecurityDisclosureGate`,
+ *     `runHookAttributionAdvisory` (Phase 1 pilots, 0.32.0)
+ *
+ * Distinct from `src/hooks/push-gate/halt.ts`:
+ *   - The push-gate's `readHalt` is part of the dependency-injected
+ *     test seam (`PushGateDeps.readHalt`) and cannot be replaced
+ *     wholesale without breaking the gate's existing contract.
+ *   - Future-work item: thread `checkHalt` THROUGH the push-gate's
+ *     `readHalt` default so a single primitive backs every consumer.
+ *     Out of scope for 0.32.0 — the push-gate ships green and rotating
+ *     it now would expand the diff without carrying its own bug fix.
+ */
+/**
+ * Result of a HALT probe.
+ *
+ * Discriminated union so callers cannot accidentally read `reason` from
+ * the not-halted case. The `halted: true` arm always carries a non-
+ * empty `reason` — the reader manufactures a placeholder rather than
+ * leaving the field undefined (the operator-facing stderr message
+ * `REA HALT: <reason>` would render `undefined` otherwise).
+ */
+export type HaltState = {
+    halted: true;
+    reason: string;
+} | {
+    halted: false;
+};
+/**
+ * Probe `<reaRoot>/.rea/HALT`. Pure function — does not write, log, or
+ * mutate process state. Caller is responsible for the operator-facing
+ * stderr emission and the exit code.
+ *
+ * @param reaRoot Absolute path to the project root that owns `.rea/`.
+ *                Hooks resolve this from `$CLAUDE_PROJECT_DIR` or
+ *                `process.cwd()` — callers should pre-resolve before
+ *                invoking this primitive.
+ * @returns `{ halted: false }` when the kill switch is clear, or
+ *          `{ halted: true, reason }` with a non-empty reason string.
+ */
+export declare function checkHalt(reaRoot: string): HaltState;
+/**
+ * Render the canonical operator-facing HALT banner. Pulled into a
+ * helper so the 5 hook callers (`runHookScanBash`,
+ * `runHookCodexReview`, and the 3 Phase 1 pilots) emit the same
+ * stderr text byte-for-byte. Matches the historical inline string
+ * exactly so existing consumer-side log parsers (if any) continue to
+ * work.
+ */
+export declare function formatHaltBanner(reason: string): string;

package/dist/hooks/_lib/halt-check.js

@@ -0,0 +1,106 @@
+/**
+ * Shared HALT kill-switch reader for the Node-binary hook tier.
+ *
+ * 0.32.0 — extracted from `src/cli/hook.ts`. Pre-extraction the same
+ * `.rea/HALT` reader inlined twice (`runHookScanBash` lines 204-222 and
+ * `runHookCodexReview` lines 518-531) and `src/hooks/push-gate/halt.ts`
+ * carried a third copy with slightly different error semantics (the
+ * push-gate variant returns `{ halted: true, reason: 'unknown (HALT
+ * file unreadable)' }` on filesystem errors instead of falling through
+ * to allow). The Node-binary hook ports landing in 0.32.0 need the
+ * same primitive, so consolidate here before more copies accumulate.
+ *
+ * Contract:
+ *
+ *   - Returns `{ halted: false }` when `<reaRoot>/.rea/HALT` is absent.
+ *   - Returns `{ halted: true, reason }` when the file exists. `reason`
+ *     is the first non-empty line trimmed and capped at 1024 bytes;
+ *     missing/blank content collapses to `"Reason unknown"`.
+ *   - Filesystem errors during the read collapse to a halted sentinel
+ *     `"unknown (HALT file unreadable)"` — fail-CLOSED. The historical
+ *     `runHookScanBash` inline copy fell through to allow on read
+ *     failure; that is the wrong posture for a kill switch (an
+ *     attacker who can prevent the read should not get a free allow).
+ *     The push-gate's halt.ts already takes this stance; we converge.
+ *   - NEVER throws.
+ *
+ * Used by:
+ *   - `runHookScanBash`, `runHookCodexReview` (existing — migrated to
+ *     this primitive in 0.32.0)
+ *   - `runHookPrIssueLinkGate`, `runHookSecurityDisclosureGate`,
+ *     `runHookAttributionAdvisory` (Phase 1 pilots, 0.32.0)
+ *
+ * Distinct from `src/hooks/push-gate/halt.ts`:
+ *   - The push-gate's `readHalt` is part of the dependency-injected
+ *     test seam (`PushGateDeps.readHalt`) and cannot be replaced
+ *     wholesale without breaking the gate's existing contract.
+ *   - Future-work item: thread `checkHalt` THROUGH the push-gate's
+ *     `readHalt` default so a single primitive backs every consumer.
+ *     Out of scope for 0.32.0 — the push-gate ships green and rotating
+ *     it now would expand the diff without carrying its own bug fix.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Maximum bytes of the HALT file we consider when assembling the
+ * `reason` line. Defends against a runaway-write scenario where
+ * `.rea/HALT` is megabytes large — we always emit the reason on
+ * stderr, and a multi-MB stderr blob can overwhelm a TTY before the
+ * user sees the actual exit. 1 KiB is more than enough for a human-
+ * authored kill-switch reason.
+ */
+const HALT_REASON_MAX_BYTES = 1024;
+/**
+ * Probe `<reaRoot>/.rea/HALT`. Pure function — does not write, log, or
+ * mutate process state. Caller is responsible for the operator-facing
+ * stderr emission and the exit code.
+ *
+ * @param reaRoot Absolute path to the project root that owns `.rea/`.
+ *                Hooks resolve this from `$CLAUDE_PROJECT_DIR` or
+ *                `process.cwd()` — callers should pre-resolve before
+ *                invoking this primitive.
+ * @returns `{ halted: false }` when the kill switch is clear, or
+ *          `{ halted: true, reason }` with a non-empty reason string.
+ */
+export function checkHalt(reaRoot) {
+    const haltPath = path.join(reaRoot, '.rea', 'HALT');
+    if (!fs.existsSync(haltPath)) {
+        return { halted: false };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(haltPath, 'utf8');
+    }
+    catch {
+        // Fail-closed: the file exists (existsSync passed) but we cannot
+        // read it. The operator intended to halt; a permissions glitch or
+        // race that prevents the read should NOT translate into a free
+        // allow. Surface a generic reason so the operator knows the file
+        // was present even when its content was unreadable.
+        return { halted: true, reason: 'unknown (HALT file unreadable)' };
+    }
+    // Cap at HALT_REASON_MAX_BYTES BEFORE splitting to bound the work.
+    // The pre-0.32.0 inline copies sliced the entire file content first
+    // and then trimmed; that is identical behavior for any reasonable
+    // file size but differs unboundedly for pathological inputs.
+    const slice = raw.length > HALT_REASON_MAX_BYTES ? raw.slice(0, HALT_REASON_MAX_BYTES) : raw;
+    const firstNonEmpty = slice
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return {
+        halted: true,
+        reason: firstNonEmpty !== undefined && firstNonEmpty.length > 0 ? firstNonEmpty : 'Reason unknown',
+    };
+}
+/**
+ * Render the canonical operator-facing HALT banner. Pulled into a
+ * helper so the 5 hook callers (`runHookScanBash`,
+ * `runHookCodexReview`, and the 3 Phase 1 pilots) emit the same
+ * stderr text byte-for-byte. Matches the historical inline string
+ * exactly so existing consumer-side log parsers (if any) continue to
+ * work.
+ */
+export function formatHaltBanner(reason) {
+    return `REA HALT: ${reason}\nAll agent operations suspended. Run: rea unfreeze\n`;
+}

package/dist/hooks/_lib/payload.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared stdin payload primitive for the Node-binary hook tier.
+ *
+ * 0.32.0 — extracts the `INPUT=$(cat) ; jq -r '.tool_input.command'`
+ * pattern that every bash hook in `hooks/` repeats. The Node-binary
+ * scan-bash already does this work in `runHookScanBash` (lines 225-258
+ * of `src/cli/hook.ts`); the Phase 1 pilots landing in 0.32.0 need
+ * the same primitive without copy-pasting the parsing + type-guard +
+ * fail-closed-on-malformed-JSON dance into each new hook.
+ *
+ * The shape mirrors the bash hooks' contract verbatim:
+ *
+ *   - `tool_input.command` is the only field we read; bash hooks only
+ *     ever ran `jq -r '.tool_input.command // ""'` against this payload.
+ *   - `tool_name` is also surfaced because two bash hooks
+ *     (`pr-issue-link-gate.sh` and `security-disclosure-gate.sh`)
+ *     short-circuit when the tool isn't `Bash`.
+ *
+ * Failure modes:
+ *
+ *   - Empty stdin → `{ command: '', toolName: '' }`. The bash hooks
+ *     allow on empty command (`[[ -z "$CMD" ]] && exit 0`); the Node
+ *     port preserves this by returning empty strings rather than
+ *     throwing.
+ *   - Malformed JSON → throws `MalformedPayloadError`. The caller
+ *     decides whether to fail-closed (block) or fail-open (allow);
+ *     `runHookScanBash` chose fail-closed (block) and the Phase 1
+ *     pilots match that posture for consistency.
+ *   - `tool_input.command` is non-string → throws `TypePayloadError`.
+ *     A crafted payload like `{"tool_input":{"command":["rm","-rf"]}}`
+ *     would silently coerce to `''` if we used `String(c)`; that
+ *     would translate into a free allow. Refuse instead.
+ */
+import { Buffer } from 'node:buffer';
+/**
+ * Result of parsing a Claude Code hook PreToolUse stdin payload.
+ */
+export interface HookPayload {
+    /** `tool_name` from the payload, or `''` when absent. */
+    toolName: string;
+    /** `tool_input.command` from the payload, or `''` when absent. */
+    command: string;
+}
+/**
+ * Thrown when stdin contains content that is not valid JSON.
+ *
+ * Distinct error class so callers can `instanceof` discriminate without
+ * leaning on string matching of the message.
+ */
+export declare class MalformedPayloadError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the JSON parses but `tool_input.command` is present and
+ * has the wrong type (anything other than `string` / `undefined`).
+ */
+export declare class TypePayloadError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a Claude Code PreToolUse stdin payload. Pure function — no I/O.
+ *
+ * @param raw Bytes / string read from the hook's stdin (the `INPUT=$(cat)`
+ *            equivalent).
+ * @returns A normalized `HookPayload` with both fields always defined.
+ * @throws MalformedPayloadError if the input is not parseable JSON.
+ * @throws TypePayloadError if `tool_input.command` is present with a
+ *         non-string type.
+ */
+export declare function parseHookPayload(raw: string | Buffer): HookPayload;
+/**
+ * Read all of stdin into a string with a soft byte cap and a hard
+ * timeout. Mirrors the `readStdinWithTimeout` helper in
+ * `src/cli/hook.ts` (which scans a fixed timeout but no byte cap).
+ *
+ * The cap (default 1 MiB) defends against a misbehaving caller piping
+ * an unbounded payload — we'd otherwise sit in the read loop forever
+ * even if the caller eventually closed stdin.
+ *
+ * @param timeoutMs How long to wait for stdin to close before resolving
+ *                  with whatever we have. Default 5_000 ms.
+ * @param maxBytes Soft cap on total bytes accepted. Default 1 MiB.
+ *                 Once reached, additional chunks are dropped silently
+ *                 (the caller still gets a parseable string back).
+ */
+export declare function readStdinWithTimeout(timeoutMs?: number, maxBytes?: number): Promise<string>;