@bookedsolid/rea 0.46.0 → 0.48.0

package/dist/cli/audit-top-blocks.js

@@ -0,0 +1,419 @@
+/**
+ * `rea audit top-blocks [--since=DUR] [--limit=N] [--json]` — 0.47.0
+ * charter item 3.
+ *
+ * Surface the most recent refusal events from the audit log. Designed
+ * for the question "why was that refused?" — operators see the latest
+ * blocks at a glance with enough context (timestamp, tool, reason) to
+ * grep the offending Bash/Edit/Write call site or fix the policy that
+ * tripped the gate.
+ *
+ * A "refusal" in the rea audit schema is any record whose
+ * `InvocationStatus` is NOT `Allowed` — that's `Denied` (policy
+ * refused) OR `Error` (middleware exception or downstream failure).
+ * Both are interesting to operators debugging "why didn't this run".
+ *
+ * # Walk scope
+ *
+ * Mirrors `audit summary` / `audit by-tool` / `audit timeline`: the
+ * current `.rea/audit.jsonl` PLUS every rotated `audit-…jsonl` segment
+ * is walked regardless of `--since` (the per-record timestamp filter
+ * inside the main loop decides what counts). Rotated filename stamps
+ * mark the rotation INSTANT, not the earliest record contained
+ * (0.41.0 round-3 P2 / 0.42.0 charter item 3) — pruning by filename
+ * would silently drop in-window records from conservatively-rotated
+ * logs. Walking every segment is the only sound shape.
+ *
+ * # Output (default)
+ *
+ *     rea audit top-blocks (last 24h, limit 20)
+ *     ─────────────────────────────────────────
+ *     a1b2c3d4  2026-05-17T12:34:56.789Z  Bash    rm -rf bypass attempted (...)
+ *     deadbeef  2026-05-17T11:20:01.123Z  Write   blocked-path .env write
+ *     …
+ *     total: 4 refusal events in window
+ *     files scanned: 2
+ *
+ * # JSON output
+ *
+ *     {
+ *       "schema_version": 1,
+ *       "since": "24h",
+ *       "limit": 20,
+ *       "window": { "seconds": 86400, "start": "...", "end": "..." },
+ *       "total_matched": 4,
+ *       "events": [
+ *         { "hash": "a1b2c3d4...", "timestamp": "...", "tool": "Bash",
+ *           "status": "denied", "reason": "rm -rf bypass attempted (...)" },
+ *         …
+ *       ],
+ *       "files_scanned": ["/abs/path/.rea/audit.jsonl"]
+ *     }
+ *
+ * `total_matched` is the pre-limit count so dashboards can show "20 of
+ * 47 refusals in window". `events` is sorted newest-first and capped at
+ * `limit`.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { listRotatedAuditFiles } from './audit-specialists.js';
+import { AuditSummarySinceError, parseDurationSeconds, } from './audit-summary.js';
+import { AUDIT_FILE, REA_DIR, err } from './utils.js';
+export const AUDIT_TOP_BLOCKS_SCHEMA_VERSION = 1;
+/** Default `--limit` value. 20 fits a debugging session's eyeballable window. */
+export const DEFAULT_LIMIT = 20;
+/**
+ * Hard ceiling on `--limit`. Refusal events are typically a small slice
+ * of total traffic, but a 1000 cap keeps the renderer / JSON output
+ * bounded under a runaway misconfiguration that's denying everything.
+ */
+export const MAX_LIMIT = 1000;
+/** Max characters of refusal reason to display per row before truncation. */
+const REASON_TRUNCATE = 80;
+/** Short-hash prefix length for the displayed event ID. */
+const SHORT_HASH_LEN = 8;
+/**
+ * Thrown when `--limit` is outside [1, MAX_LIMIT] or `--since` fails to
+ * parse. The commander wrapper catches and exits 1. Distinct from
+ * `AuditByToolOptionError` / `AuditTimelineOptionError` so the
+ * caller-facing message names the right flag.
+ */
+export class AuditTopBlocksOptionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuditTopBlocksOptionError';
+    }
+}
+/**
+ * Resolve the audit files to walk. Identical strategy to the sibling
+ * audit commands — inlined to keep the public surface of
+ * `audit-summary.ts` narrow.
+ */
+async function resolveTopBlocksFileWalk(baseDir) {
+    const reaDir = path.join(baseDir, REA_DIR);
+    const currentAudit = path.join(reaDir, AUDIT_FILE);
+    const files = [];
+    const rotated = await listRotatedAuditFiles(reaDir);
+    for (const name of rotated)
+        files.push(path.join(reaDir, name));
+    try {
+        const stat = await fs.stat(currentAudit);
+        if (stat.isFile())
+            files.push(currentAudit);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    return files;
+}
+function parseTimestamp(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/**
+ * Decide whether an audit record represents a refusal. The rea
+ * InvocationStatus enum has three values (`allowed`, `denied`,
+ * `error`); refusals are the non-`allowed` set. We accept any other
+ * string here too so a future status enum extension (or an unusual
+ * consumer-emitted status) surfaces in the report rather than silently
+ * dropping — the operator can decide whether the new bucket is signal
+ * or noise.
+ */
+function isRefusal(status) {
+    if (typeof status !== 'string')
+        return false;
+    return status !== 'allowed';
+}
+/**
+ * Compute the top-blocks list. Pure (read-only). Throws
+ * `AuditTopBlocksOptionError` on bad `--since` / `--limit`.
+ */
+export async function computeAuditTopBlocks(options = {}) {
+    const baseDir = options.baseDir ?? process.cwd();
+    const now = options.now ?? new Date();
+    // Resolve --limit first so a bad value fails fast before any I/O.
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+        throw new AuditTopBlocksOptionError(`--limit: must be an integer between 1 and ${String(MAX_LIMIT)}; got ${JSON.stringify(limit)}.`);
+    }
+    let windowSeconds = null;
+    let windowStart = null;
+    let windowEnd = null;
+    if (options.since !== undefined && options.since.length > 0) {
+        try {
+            windowSeconds = parseDurationSeconds(options.since);
+        }
+        catch (e) {
+            if (e instanceof AuditSummarySinceError) {
+                throw new AuditTopBlocksOptionError(e.message);
+            }
+            throw e;
+        }
+        windowEnd = now;
+        windowStart = new Date(now.getTime() - windowSeconds * 1000);
+    }
+    const files = await resolveTopBlocksFileWalk(baseDir);
+    const filesScanned = [];
+    // Codex round-10 P2 (0.47.0): in a policy-storm scenario (many
+    // refusals, verbose `error` strings) the prior shape accumulated
+    // every match into a flat array, sorted it, then sliced to
+    // `--limit`. Memory + runtime scaled with the total refusal count
+    // — exactly the case `top-blocks` was designed to debug. The
+    // bounded-buffer shape keeps memory O(limit): we maintain a
+    // sorted "top K newest" list of size <= limit and discard the
+    // oldest entry whenever a newer one displaces it. `totalMatched`
+    // counts every in-window refusal so the JSON shape still
+    // communicates "N of M shown".
+    const topBuf = [];
+    let totalMatched = 0;
+    // Insert into the bounded buffer, keeping it sorted newest-first
+    // by parsed instant (with hash tiebreaker for determinism). Drop
+    // the oldest when capacity exceeded.
+    const insertIntoTop = (event, parsedTime) => {
+        // Find insertion point — small linear scan; for limit=20 (the
+        // default) this is cheaper than a heap and keeps the code
+        // simple. For limit=1000 (the max) we're still O(limit) per
+        // insert in the worst case, well under the prior O(N log N)
+        // sort across N matches.
+        let idx = topBuf.length;
+        for (let i = 0; i < topBuf.length; i += 1) {
+            const cur = topBuf[i];
+            if (parsedTime > cur.parsedTime ||
+                (parsedTime === cur.parsedTime && event.hash.localeCompare(cur.event.hash) < 0)) {
+                idx = i;
+                break;
+            }
+        }
+        if (idx < limit) {
+            topBuf.splice(idx, 0, { event, parsedTime });
+            if (topBuf.length > limit)
+                topBuf.length = limit;
+        }
+    };
+    for (const filePath of files) {
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, 'utf8');
+        }
+        catch (e) {
+            const errno = e.code;
+            if (errno === 'ENOENT')
+                continue;
+            // Mirror the sibling audit commands' stance: any non-ENOENT read
+            // error is fatal. A silent skip on a rotated segment that may
+            // contain in-window refusals would let `top-blocks` exit 0 with
+            // the operator's question unanswered.
+            throw new Error(`rea audit top-blocks: cannot read ${filePath} (${errno ?? 'unknown errno'}). ` +
+                `An unreadable audit segment may contain in-window records, so the ` +
+                `refusal report would be silently incomplete. Fix permissions ` +
+                `(e.g. \`chmod u+r ${filePath}\`), or move the file out of \`.rea/\` ` +
+                `if you no longer need it.`);
+        }
+        filesScanned.push(filePath);
+        for (const line of raw.split('\n')) {
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                // Malformed line — `rea audit verify` is the right tool. Skip
+                // so a single corrupt line doesn't tank the report.
+                continue;
+            }
+            if (!isRefusal(parsed.status))
+                continue;
+            const ts = parseTimestamp(parsed.timestamp);
+            if (windowStart !== null && (ts === null || ts < windowStart))
+                continue;
+            if (windowEnd !== null && (ts === null || ts > windowEnd))
+                continue;
+            totalMatched += 1;
+            const tool = typeof parsed.tool_name === 'string' && parsed.tool_name.length > 0
+                ? parsed.tool_name
+                : '(unknown)';
+            const errorText = typeof parsed.error === 'string' && parsed.error.length > 0
+                ? parsed.error
+                : `${typeof parsed.status === 'string' ? parsed.status : 'refused'}: ${tool}`;
+            const event = {
+                hash: typeof parsed.hash === 'string' ? parsed.hash : '',
+                timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : '',
+                tool,
+                status: typeof parsed.status === 'string' ? parsed.status : '(unknown)',
+                reason: errorText,
+                session_id: typeof parsed.session_id === 'string' ? parsed.session_id : '',
+            };
+            // Codex round-2 P2 (0.47.0): parse the timestamp before
+            // comparing — `appendAuditRecord` accepts any ISO-8601 shape,
+            // so `2026-05-17T23:00:00+02:00` (= 21:00:00Z, OLDER) would
+            // lex-sort ahead of `2026-05-17T22:30:00Z` (NEWER) under a
+            // string compare.
+            const parsedTime = Date.parse(event.timestamp);
+            insertIntoTop(event, Number.isFinite(parsedTime) ? parsedTime : 0);
+        }
+    }
+    const capped = topBuf.map((entry) => entry.event);
+    return {
+        schema_version: AUDIT_TOP_BLOCKS_SCHEMA_VERSION,
+        since: options.since !== undefined && options.since.length > 0 ? options.since : null,
+        limit,
+        window: {
+            seconds: windowSeconds,
+            start: windowStart !== null ? windowStart.toISOString() : null,
+            end: windowEnd !== null ? windowEnd.toISOString() : null,
+        },
+        total_matched: totalMatched,
+        events: capped,
+        files_scanned: filesScanned,
+    };
+}
+/**
+ * Truncate a reason string to `REASON_TRUNCATE` chars for the human
+ * renderer. JSON consumers get the full string — they can render at
+ * any width.
+ *
+ * Codex round-10 P3 (0.47.0): refusal reasons often contain embedded
+ * newlines (shell stderr, Node stack traces). Writing them straight
+ * into a fixed-width row spills a single event across multiple
+ * terminal lines and breaks the hash/timestamp/tool columns. Collapse
+ * `\r`, `\n`, and tabs to single spaces FIRST, then truncate to the
+ * column width. The JSON path preserves the raw `reason` field so
+ * consumers see the full multiline message.
+ */
+function truncateReason(reason) {
+    const collapsed = reason.replace(/[\r\n\t]+/g, ' ').replace(/  +/g, ' ').trim();
+    if (collapsed.length <= REASON_TRUNCATE)
+        return collapsed;
+    return collapsed.slice(0, REASON_TRUNCATE - 1) + '…';
+}
+/**
+ * Short-hash prefix for the displayed event ID. Falls back to the
+ * full string when it's shorter than the prefix length (degenerate
+ * inputs only — real hashes are always 64 hex chars).
+ */
+function shortHash(hash) {
+    if (hash.length <= SHORT_HASH_LEN)
+        return hash || '(no-hash)';
+    return hash.slice(0, SHORT_HASH_LEN);
+}
+/**
+ * Compact human duration label. Mirrors the sibling audit commands.
+ */
+function formatDurationShort(seconds) {
+    const units = [
+        ['w', 60 * 60 * 24 * 7],
+        ['d', 60 * 60 * 24],
+        ['h', 60 * 60],
+        ['m', 60],
+        ['s', 1],
+    ];
+    for (const [unit, factor] of units) {
+        if (seconds % factor === 0) {
+            return `last ${String(seconds / factor)}${unit}`;
+        }
+    }
+    return `last ${String(seconds)}s`;
+}
+/**
+ * Render the result as a human-readable terminal block. JSON callers
+ * bypass this; the rendering is intentionally minimal — a fixed-column
+ * table that scans cleanly in a typical terminal.
+ */
+export function renderAuditTopBlocks(result) {
+    const lines = [];
+    const windowLabel = result.window.seconds !== null ? formatDurationShort(result.window.seconds) : 'all time';
+    lines.push(`rea audit top-blocks (${windowLabel}, limit ${String(result.limit)})`);
+    lines.push('─'.repeat(40));
+    if (result.total_matched === 0) {
+        lines.push(result.window.seconds !== null
+            ? 'No refusal events in the requested window.'
+            : 'No refusal events in the audit log.');
+        if (result.files_scanned.length === 0) {
+            lines.push('(no audit files found — has `rea serve` ever run?)');
+        }
+        lines.push('');
+        return lines.join('\n');
+    }
+    // Stable column widths for the table:
+    //   short hash (8) + 2  | timestamp (24) + 2 | tool (max in view) + 2 | reason
+    const maxToolLen = result.events.reduce((m, ev) => Math.max(m, ev.tool.length), 4);
+    for (const ev of result.events) {
+        const h = shortHash(ev.hash).padEnd(SHORT_HASH_LEN);
+        const ts = ev.timestamp.padEnd(24); // ISO-8601 with ms is 24 chars
+        const tool = ev.tool.padEnd(maxToolLen);
+        const reason = truncateReason(ev.reason);
+        lines.push(`${h}  ${ts}  ${tool}  ${reason}`);
+    }
+    lines.push('');
+    if (result.total_matched > result.events.length) {
+        lines.push(`total: ${String(result.events.length)} of ${String(result.total_matched)} refusal events shown (--limit=${String(result.limit)})`);
+    }
+    else {
+        lines.push(`total: ${String(result.total_matched)} refusal event${result.total_matched === 1 ? '' : 's'} in window`);
+    }
+    lines.push(`files scanned: ${String(result.files_scanned.length)}`);
+    lines.push('');
+    return lines.join('\n');
+}
+/** Commander entrypoint. */
+export async function runAuditTopBlocks(options) {
+    let result;
+    try {
+        result = await computeAuditTopBlocks({
+            ...(options.since !== undefined ? { since: options.since } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+    }
+    catch (e) {
+        if (e instanceof AuditTopBlocksOptionError) {
+            err(`rea audit top-blocks: ${e.message}`);
+            process.exit(1);
+        }
+        throw e;
+    }
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write(renderAuditTopBlocks(result));
+}
+/**
+ * Strict integer parser for the commander `--limit <n>` option.
+ *
+ * Mirrors the `parseTopOption` discipline in `audit-by-tool.ts`:
+ * reject anything that isn't a bare integer so `Number.parseInt`
+ * can't silently truncate (`1.5` → `1`, `10abc` → `10`).
+ */
+export function parseLimitOption(raw) {
+    if (!/^-?\d+$/.test(raw.trim())) {
+        throw new AuditTopBlocksOptionError(`--limit: expected integer; got ${JSON.stringify(raw)}.`);
+    }
+    const n = Number.parseInt(raw.trim(), 10);
+    if (!Number.isFinite(n)) {
+        throw new AuditTopBlocksOptionError(`--limit: expected integer; got ${JSON.stringify(raw)}.`);
+    }
+    return n;
+}
+/**
+ * Register `rea audit top-blocks` under the `audit` command group.
+ */
+export function registerAuditTopBlocksCommand(auditCommand) {
+    auditCommand
+        .command('top-blocks')
+        .description('Recent refusal events from the audit log — `--limit=N` (default 20, max 1000), `--since=DUR` window filter, `--json` for dashboards. Read-only.')
+        .option('--limit <n>', `cap the rendered / serialized list to the most recent N refusals (default ${String(DEFAULT_LIMIT)}, max ${String(MAX_LIMIT)})`, parseLimitOption)
+        .option('--since <duration>', 'filter to records within the last <duration>. Compact form: <N><unit> where unit is s|m|h|d|w (e.g. 24h, 7d).')
+        .option('--json', 'emit a JSON document instead of the human-readable table')
+        .action(async (opts) => {
+        await runAuditTopBlocks({
+            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+            ...(opts.since !== undefined ? { since: opts.since } : {}),
+            ...(opts.json === true ? { json: true } : {}),
+        });
+    });
+}

package/dist/cli/index.js

@@ -17,6 +17,7 @@ import { runUpgradeCheck } from './upgrade-check.js';
 import { registerAuditSummaryCommand } from './audit-summary.js';
 import { registerAuditByToolCommand } from './audit-by-tool.js';
 import { registerAuditTimelineCommand } from './audit-timeline.js';
+import { registerAuditTopBlocksCommand } from './audit-top-blocks.js';
 import { registerVerifyClaimCommand } from './verify-claim.js';
 import { err, getPkgVersion } from './utils.js';
 async function main() {
@@ -154,6 +155,10 @@ async function main() {
     // [--since=DUR] [--json]`. Time-bucketed event counts with inline
     // histogram. Useful for spotting activity spikes + cadence patterns.
     registerAuditTimelineCommand(audit);
+    // 0.47.0 charter item 3 — `rea audit top-blocks [--limit=N]
+    // [--since=DUR] [--json]`. Most-recent refusal events (denied/error).
+    // The "why was that refused?" debugging lens.
+    registerAuditTopBlocksCommand(audit);
     // Register `rea hook push-gate` — the stateless pre-push Codex gate
     // called by `.husky/pre-push` and `.git/hooks/pre-push`.
     registerHookCommand(program);

package/dist/config/tier-map.js

@@ -301,6 +301,38 @@ export function reaCommandTier(command) {
                 // Write-tier default. Codex round 3 P2 (2026-05-12).
                 if (sub2 === 'specialists')
                     return Tier.Read;
+                // 0.47.0 codex round-11 P2: the audit-reader trio
+                // (`summary`, `by-tool`, `timeline`, `top-blocks`) all share
+                // the read-only contract — they walk audit.jsonl + rotated
+                // segments and emit aggregations to stdout. The pre-0.47.0
+                // tier-map only downgraded `verify` + `specialists`, leaving
+                // 0.41.0+ readers misclassified as Write under TRUSTED
+                // invocations — which made them unavailable in L0 sessions
+                // run from `/usr/local/bin/rea` or
+                // `/proj/node_modules/.bin/rea` despite being purely
+                // observational. Close the gap for all four readers here.
+                //
+                // 0.47.0 codex round-12 P2 (DELIBERATE NON-FIX): the weak-
+                // trust branch below intentionally returns null for Read-tier
+                // subcommands, including these audit readers. That keeps a
+                // bare `rea audit summary` (PATH-lookup or relative path) at
+                // generic Bash Write, where an attacker who shadowed `rea` on
+                // PATH cannot trick the gateway into downgrading their
+                // payload via a fake subcommand. Consumers needing Read
+                // semantics under L0 use the trusted invocation shapes
+                // (`/usr/local/bin/rea …`, `npx rea …`,
+                // `./node_modules/.bin/rea …`) — same contract as `verify`
+                // and `specialists` since 0.10.x / 0.29.0. The UX gap is
+                // documented in `docs/cli/trust-model.md` (see also the
+                // weak-trust branch comment below).
+                if (sub2 === 'summary')
+                    return Tier.Read;
+                if (sub2 === 'by-tool')
+                    return Tier.Read;
+                if (sub2 === 'timeline')
+                    return Tier.Read;
+                if (sub2 === 'top-blocks')
+                    return Tier.Read;
                 if (sub2 === 'rotate')
                     return Tier.Write;
                 return Tier.Write;

package/dist/policy/loader.d.ts

@@ -301,6 +301,13 @@ declare const PolicySchema: z.ZodObject<{
         threshold?: number | undefined;
         exempt_subagents?: string[] | undefined;
     }>>;
+    shim_cache: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+    }, {
+        enabled?: boolean | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -379,6 +386,9 @@ declare const PolicySchema: z.ZodObject<{
         threshold: number;
         exempt_subagents: string[];
     } | undefined;
+    shim_cache?: {
+        enabled: boolean;
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -457,6 +467,9 @@ declare const PolicySchema: z.ZodObject<{
         threshold?: number | undefined;
         exempt_subagents?: string[] | undefined;
     } | undefined;
+    shim_cache?: {
+        enabled?: boolean | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -328,6 +328,32 @@ const DelegationAdvisoryPolicySchema = z
     ]),
 })
     .strict();
+/**
+ * 0.48.0 — per-session shim cache policy. The
+ * `hooks/_lib/shim-cache.sh` helper, sourced by every Node-binary
+ * shim via `hooks/_lib/shim-runtime.sh`, caches the (sandbox-ok,
+ * shape-ok) tuple for a given (session, project, CLI realpath,
+ * mtime, size, euid, enforce_shape) key, with a 3600s TTL ceiling.
+ * The cache is an OPTIMIZATION — every cache-miss path falls through
+ * to the existing uncached hot path. See
+ * `docs/shim-session-cache-design.md` for the full contract.
+ *
+ * Strict mode rejects unknown keys so a typo (`enabld`, `enable`)
+ * fails loudly at policy load. The block is optional — vanilla
+ * installs with no `shim_cache:` block get the default behavior
+ * (cache enabled). To disable: `shim_cache: { enabled: false }`.
+ *
+ * The bash-tier helper does a narrow YAML grep for the field
+ * BEFORE the canonical 4-tier policy reader is available (cache
+ * runs in the shim's pre-CLI section). This zod schema validates
+ * the field at CLI load time so wrong types / typos are caught at
+ * the load boundary.
+ */
+const ShimCachePolicySchema = z
+    .object({
+    enabled: z.boolean().default(true),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -387,6 +413,16 @@ const PolicySchema = z
     // when unset/false). When the block IS present the inner schema
     // supplies defaults for any omitted field.
     delegation_advisory: DelegationAdvisoryPolicySchema.optional(),
+    // 0.48.0 per-session shim cache — drives `hooks/_lib/shim-cache.sh`
+    // which short-circuits the sandbox check + version probe in
+    // `hooks/_lib/shim-runtime.sh` on session-warm fires of the same
+    // shim. Optional — vanilla installs get the default behavior
+    // (cache enabled). The bash-tier `shim_cache_disabled` helper
+    // honors `enabled: false` via a narrow inline YAML grep before
+    // the canonical policy reader is reachable. `REA_SHIM_CACHE=0`
+    // in env overrides this to `false` for the current invocation
+    // regardless of policy.
+    shim_cache: ShimCachePolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/types.d.ts

@@ -533,4 +533,56 @@ export interface Policy {
      * blocks. See `DelegationAdvisoryPolicy` for the full contract.
      */
     delegation_advisory?: DelegationAdvisoryPolicy;
+    /**
+     * Per-session shim cache (0.48.0+).
+     *
+     * The `hooks/_lib/shim-cache.sh` helper, sourced by every Node-binary
+     * shim via `hooks/_lib/shim-runtime.sh`, records the answers to the
+     * sandbox check + version probe under a per-user, per-session,
+     * per-CLI key. Subsequent shim fires within the same Claude Code
+     * session against the same CLI (mtime + size unchanged) skip
+     * straight to the forward step.
+     *
+     * The cache is an OPTIMIZATION, not a security boundary. Cache miss
+     * / disabled / corruption all fall through to the existing uncached
+     * hot path — never fail closed.
+     *
+     * `enabled` default: `true`. Set `false` to disable the cache layer
+     * at the policy tier (equivalent effect to setting the
+     * `REA_SHIM_CACHE=0` env var on every invocation). Operators who
+     * want to measure unconditional steady-state latency should use the
+     * env-var form so the cache stays off only for the measurement
+     * window. See `docs/shim-session-cache-design.md` for the security
+     * contract and `docs/hook-perf-baseline.md` for the perf
+     * methodology note.
+     */
+    shim_cache?: ShimCachePolicy;
+}
+/**
+ * Per-session shim cache policy (0.48.0+).
+ *
+ * The cache short-circuits the sandbox check + version probe in
+ * `hooks/_lib/shim-runtime.sh` on session-warm fires of the same
+ * shim. The on-disk entry shape is bound to `schema_version: "v1"`
+ * — a schema bump (future cache field additions) invalidates every
+ * existing entry. TTL is hard-capped at 3600s (1h) inside the
+ * runtime; this block does not expose a TTL knob in 0.48.0 because
+ * the optimization is steady-state-bound and a longer TTL would
+ * extend staleness without measurable benefit.
+ */
+export interface ShimCachePolicy {
+    /**
+     * Master switch. `true` (default) enables the cache. `false`
+     * disables both reads and writes — the runtime falls through to
+     * the existing uncached hot path on every fire. `REA_SHIM_CACHE=0`
+     * in env overrides this to `false` for the current invocation
+     * regardless of policy.
+     *
+     * NOTE 0.48.0: the bash-tier `shim_cache_disabled` helper consults
+     * this field via a narrow YAML grep BEFORE the canonical 4-tier
+     * policy reader is available (cache runs in the shim's pre-CLI
+     * section). The TS loader's schema validation runs at full CLI
+     * load time and catches typos / wrong types.
+     */
+    enabled?: boolean;
 }