@bookedsolid/rea 0.9.4 → 0.10.0

package/README.md

@@ -480,6 +480,111 @@ and `ClaudeSelfReviewer` is the in-process fallback (tagged
 `degraded: true` in the audit record so self-review is visible and
 countable).
 
+## Agent push workflow — satisfying the push-review gate
+
+When `git push` is blocked by `push-review-gate.sh` the gate prints
+remediation steps. This section is the canonical one-command flow the
+steps reduce to. Agents should copy-paste this verbatim; humans should
+expect agents to.
+
+### 1. Run the adversarial review
+
+```bash
+# From an interactive Claude Code session:
+/codex-review
+```
+
+This invokes the `codex-adversarial` agent, which records a
+`codex.review` audit entry with `verdict: pass | concerns | blocking |
+error` and a `finding_count`. The push gate looks up that entry by
+`head_sha + verdict ∈ {pass, concerns}`.
+
+### 2. Record-and-cache in one CLI call
+
+If you already have a review verdict (from `/codex-review`, or from a
+manual Codex run, or from an offline review) emit the audit record AND
+update the push-review cache with a single command:
+
+```bash
+rea audit record codex-review \
+  --head-sha "$(git rev-parse HEAD)" \
+  --branch   "$(git rev-parse --abbrev-ref HEAD)" \
+  --target   main \
+  --verdict  pass \
+  --finding-count 0 \
+  --summary  "no findings" \
+  --also-set-cache
+```
+
+`--also-set-cache` writes both `.rea/audit.jsonl` and
+`.rea/review-cache.jsonl` in the same invocation (two sequential
+appends, not a two-phase commit — but close enough in practice that the
+push-gate lookup cannot see the audit record without the cache entry
+unless a crash lands between them). Without it, the audit record lands
+but the cache stays cold — and the next `git push` pays for a re-review
+even though the audit trail already shows the review happened.
+`--also-set-cache` is what the gate's remediation text should be reduced
+to.
+
+Verdict mapping for the cache leg:
+
+| `--verdict`  | Cache `result` | Cache `reason` |
+| ------------ | -------------- | -------------- |
+| `pass`       | `pass`         | — (omitted) |
+| `concerns`   | `pass`         | `codex:concerns` |
+| `blocking`   | `fail`         | `codex:blocking` |
+| `error`      | `fail`         | `codex:error` |
+
+### 3. Push
+
+```bash
+git push
+```
+
+The gate hits the cache, sees `{"hit":true,"result":"pass"}`, and exits
+0 on the first attempt. No `!`-bash escapes, no manual audit writing,
+no separate `rea cache set` invocation.
+
+### SDK alternative
+
+When embedding the flow in a TypeScript tool instead of shelling out,
+import the public audit helper:
+
+```ts
+import {
+  appendAuditRecord,
+  CODEX_REVIEW_SERVER_NAME,
+  CODEX_REVIEW_TOOL_NAME,
+  InvocationStatus,
+  Tier,
+} from '@bookedsolid/rea/audit';
+
+await appendAuditRecord(process.cwd(), {
+  tool_name: CODEX_REVIEW_TOOL_NAME,
+  server_name: CODEX_REVIEW_SERVER_NAME,
+  tier: Tier.Read,
+  status: InvocationStatus.Allowed,
+  metadata: {
+    head_sha: headSha,
+    target: 'main',
+    finding_count: 0,
+    verdict: 'pass',
+  },
+});
+```
+
+The CLI wraps exactly this — use the CLI unless the host is already a
+TypeScript process that wants to avoid the subprocess roundtrip.
+
+### Agent autonomy self-consistency
+
+At autonomy `L1`, `rea cache check`, `rea audit record codex-review`,
+`rea doctor`, and `rea status` are classified **Read tier** — they
+cannot be denied by REA's own middleware. `rea cache set` is Write
+tier and is still allowed at L1. `rea freeze` is Destructive tier and
+is denied at L1 (deny-reason includes the subcommand, e.g.
+`Bash (rea freeze)`, not just `Bash`).
+
 ## Hooks
 
 Fourteen hooks. Each does one thing.

package/THREAT_MODEL.md

@@ -1,6 +1,6 @@
 # Threat Model — REA Gateway and Hook Layer
 
-Version: 0.9.x | Last updated: 2026-04-21
+Version: 0.10.x | Last updated: 2026-04-21
 
 ---
 
@@ -475,6 +475,24 @@ Ref: `src/registry/fingerprint.ts` (`canonicalize()`, `fingerprintServer()`), `s
 
 Ref: `src/gateway/middleware/injection.ts`, `src/gateway/middleware/injection.test.ts`.
 
+### 5.22 Hook-Patch Session Env Var (0.10.0, Defect I)
+
+**Threat:** `settings-protection.sh` blanket-blocks edits under `.claude/hooks/`. That is the correct default (agents must not silently rewrite safety infrastructure) but it leaves no documented path for applying upstream-sourced CodeRabbit/Codex findings on hook scripts during a live session. Before 0.10.0, operators reached for `!`-bash to sidestep the hook entirely, which dodged every audit surface — a worse outcome than the block it was working around. The source-of-truth `hooks/` directory is intentionally editable by default; `rea init` is the supply-chain step that promotes those edits into `.claude/hooks/`, so gating at the runtime directory is where the runtime-trust decision belongs.
+
+**Mitigations:**
+
+- `REA_HOOK_PATCH_SESSION=<reason>` is a **session-scoped**, **self-revoking** bypass. When set to a non-empty value, `settings-protection.sh` (`hooks/settings-protection.sh:219-336`) allows edits ONLY to paths under `.claude/hooks/` (the runtime directory). Every other protected path (`.rea/policy.yaml`, `.rea/HALT`, `.claude/settings.json`, `.claude/settings.local.json`) remains blocked — this is a hook-maintenance escape hatch, not a policy-editing one.
+- Order of enforcement: (§5a) reject any path containing a `..` segment in either raw or normalized form; (§6) deny hard-protected paths; (§6b) only then consult the patch-session allowlist. This ordering closes a pre-merge Codex-surfaced bypass where `.claude/hooks/../settings.json` slipped through the old patch-session case-glob and reached `.claude/settings.json` on disk with the env var set.
+- The session boundary IS the expiry. A new shell requires a fresh opt-in. There is no auto-expiry countdown to race, no policy-file flag that can silently linger across sessions, no CI refusal — the env var lives and dies with the process that set it.
+- Every allowed edit emits a `hooks.patch.session` audit record routed through the TypeScript `appendAuditRecord()` chain (`src/audit/append.ts`) so the entry extends the hash chain and cannot be silently back-filled. The payload carries: `metadata.reason` (env-var value verbatim, control-character-stripped before display), `metadata.file` (normalized path), `metadata.sha_before` (pre-edit SHA-256 of the file, captured via the portable `sha256sum`/`shasum`/`openssl` fallback chain), `metadata.actor.{name,email}` (from `git config`), `metadata.pid`, `metadata.ppid`. The hook resolves the audit module via two paths, in order: (1) `import("@bookedsolid/rea/audit")` — succeeds for `rea init`-installed consumers via `node_modules/`, and via package self-reference when running inside the rea source repo; (2) `import(REA_ROOT + "/dist/audit/append.js")` — direct file import for development checkouts. If BOTH resolve-paths fail, the edit is **refused outright** (exit 2). There is no bash-native jq fallback because that path would skip `prev_hash`/`hash` computation and silently degrade the chain integrity `rea audit verify` relies on — audit-drop is indistinguishable from chain tampering, and a hook that can drop audit on demand is a governance failure, not a usability win.
+- Note on `codex.review` entries: audit records emitted by `rea audit record codex-review` (and the related hook-append paths) are **local assertions** recorded by the operator's agent runtime. They extend the local hash chain — so retroactive tampering is detectable — but they are not signed by Codex or by any external party. Operators auditing a consumer repo must treat the presence of a `codex.review` record as evidence that SOMEONE claimed a Codex pass at that SHA, not cryptographic proof that Codex itself issued that verdict.
+
+**Trust boundary:** `REA_HOOK_PATCH_SESSION` is advisory for the tool-gate bypass only. It does not raise the autonomy level, does not disable any other hook, and does not relax blocked-paths, attribution, or secret-scanning enforcement. The gateway-layer middleware chain does not read this env var — it only affects the shell hook that guards `.claude/hooks/`. A malicious agent that set the env var for itself without human intent would gain the ability to mutate runtime hooks, but every such mutation is auditable and the session ends with the shell; there is no persistent escalation path.
+
+**Residual risk:** An operator who declares a reason and then forgets to unset the variable carries the bypass across every subsequent hook edit in that shell. Mitigation: treat the env var as a one-use stand and unset it immediately after the intended patch; the audit trail will show repeated `hooks.patch.session` records if the lifetime leaks. A follow-up hardening could scope the var to a single edit by tying it to a nonce committed to the audit record and invalidating on next append — not shipped in 0.10.0 because the session-boundary model matches how operators actually reason about the feature.
+
+Ref: `hooks/settings-protection.sh:86-336`, `.claude/hooks/settings-protection.sh` (dogfood mirror), `__tests__/hooks/settings-protection-patch-session.test.ts`, `src/audit/append.ts`.
+
 ---
 
 ## 6. Residual Risks and Open Issues

package/dist/cli/audit.d.ts

@@ -10,6 +10,7 @@
  * explicit by definition, and verify operates on existing files regardless
  * of policy.
  */
+import { type CodexVerdict } from '../audit/append.js';
 /**
  * Reserved for future rotate knobs (e.g. `--retain N` to prune old rotated
  * files). Empty today — kept as a typed record so the call site's option
@@ -38,3 +39,33 @@ export declare function runAuditRotate(_options: AuditRotateOptions): Promise<vo
  * exit code is the primary signal.
  */
 export declare function runAuditVerify(options: AuditVerifyOptions): Promise<void>;
+export interface AuditRecordCodexReviewOptions {
+    headSha: string;
+    branch: string;
+    target: string;
+    verdict: CodexVerdict;
+    findingCount: number;
+    summary?: string | undefined;
+    sessionId?: string | undefined;
+    alsoSetCache?: boolean | undefined;
+}
+/**
+ * `rea audit record codex-review` (Defect D / rea#77). Emits the single audit
+ * event the push-review cache gate looks up by `tool_name == "codex.review"` +
+ * `metadata.head_sha == <sha>` + `metadata.verdict in {pass, concerns}`. Prior
+ * to this command, agents had to reverse-engineer the canonical `tool_name`
+ * string, the hash-chain append path, and the `CodexReviewMetadata` shape —
+ * the most common failure mode was emitting `tool_name: "codex-adversarial-review"`
+ * (the agent's name) instead of `codex.review` (the event type), which the
+ * gate's jq predicate silently missed.
+ *
+ * `--also-set-cache` performs the audit record AND the review-cache write
+ * in one invocation — two sequential appends in a single process, not a
+ * two-phase commit. A crash between them leaves the audit entry without
+ * a cache row; the cache is recomputable from audit, the audit chain is
+ * the source of truth. What this DOES eliminate is the two-step race where
+ * `rea cache set` is denied by permission middleware (Defect E) after the
+ * audit has already been emitted, leaving the gate stuck on "audit present
+ * but cache cold" with no way forward.
+ */
+export declare function runAuditRecordCodexReview(options: AuditRecordCodexReviewOptions): Promise<void>;

package/dist/cli/audit.js

@@ -13,8 +13,12 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { forceRotate } from '../gateway/audit/rotator.js';
+import { appendAuditRecord, CODEX_REVIEW_SERVER_NAME, CODEX_REVIEW_TOOL_NAME, } from '../audit/append.js';
 import { computeHash, GENESIS_HASH } from '../audit/fs.js';
+import { appendEntry as appendCacheEntry } from '../cache/review-cache.js';
 import { AUDIT_FILE, REA_DIR, err, log, reaPath } from './utils.js';
+import { Tier, InvocationStatus } from '../policy/types.js';
+import { codexVerdictToCacheResult } from './cache.js';
 /**
  * `rea audit rotate`. Forces a rotation now regardless of thresholds.
  * Empty audit files are a no-op — rotating an empty chain would produce a
@@ -203,3 +207,70 @@ export async function runAuditVerify(options) {
     }
     log(`Audit chain verified: ${totalRecords} records across ${filesToVerify.length} file(s) — clean.`);
 }
+/**
+ * `rea audit record codex-review` (Defect D / rea#77). Emits the single audit
+ * event the push-review cache gate looks up by `tool_name == "codex.review"` +
+ * `metadata.head_sha == <sha>` + `metadata.verdict in {pass, concerns}`. Prior
+ * to this command, agents had to reverse-engineer the canonical `tool_name`
+ * string, the hash-chain append path, and the `CodexReviewMetadata` shape —
+ * the most common failure mode was emitting `tool_name: "codex-adversarial-review"`
+ * (the agent's name) instead of `codex.review` (the event type), which the
+ * gate's jq predicate silently missed.
+ *
+ * `--also-set-cache` performs the audit record AND the review-cache write
+ * in one invocation — two sequential appends in a single process, not a
+ * two-phase commit. A crash between them leaves the audit entry without
+ * a cache row; the cache is recomputable from audit, the audit chain is
+ * the source of truth. What this DOES eliminate is the two-step race where
+ * `rea cache set` is denied by permission middleware (Defect E) after the
+ * audit has already been emitted, leaving the gate stuck on "audit present
+ * but cache cold" with no way forward.
+ */
+export async function runAuditRecordCodexReview(options) {
+    if (options.headSha.length === 0) {
+        err('--head-sha must not be empty');
+        process.exit(1);
+    }
+    if (options.branch.length === 0) {
+        err('--branch must not be empty');
+        process.exit(1);
+    }
+    if (options.target.length === 0) {
+        err('--target must not be empty');
+        process.exit(1);
+    }
+    if (!Number.isFinite(options.findingCount) || options.findingCount < 0) {
+        err(`--finding-count must be a non-negative integer; got ${options.findingCount}`);
+        process.exit(1);
+    }
+    const baseDir = process.cwd();
+    const metadata = {
+        head_sha: options.headSha,
+        target: options.target,
+        finding_count: options.findingCount,
+        verdict: options.verdict,
+    };
+    if (options.summary !== undefined && options.summary.length > 0) {
+        metadata.summary = options.summary;
+    }
+    await appendAuditRecord(baseDir, {
+        tool_name: CODEX_REVIEW_TOOL_NAME,
+        server_name: CODEX_REVIEW_SERVER_NAME,
+        tier: Tier.Read,
+        status: InvocationStatus.Allowed,
+        ...(options.sessionId !== undefined ? { session_id: options.sessionId } : {}),
+        metadata,
+    });
+    log(`Recorded codex.review (${options.verdict}, ${options.findingCount} finding${options.findingCount === 1 ? '' : 's'}) for ${options.headSha.slice(0, 12)}.`);
+    if (options.alsoSetCache === true) {
+        const effect = codexVerdictToCacheResult(options.verdict);
+        const cacheEntry = await appendCacheEntry(baseDir, {
+            sha: options.headSha,
+            branch: options.branch,
+            base: options.target,
+            result: effect.result,
+            ...(effect.reason !== undefined ? { reason: effect.reason } : {}),
+        });
+        log(`Cached ${cacheEntry.result} for ${cacheEntry.sha.slice(0, 12)} (${cacheEntry.branch} → ${cacheEntry.base}).`);
+    }
+}

package/dist/cli/cache.d.ts

@@ -20,6 +20,7 @@
  * entirely.
  */
 import { type CacheResult } from '../cache/review-cache.js';
+import type { CodexVerdict } from '../audit/codex-event.js';
 export interface CacheCheckOptions {
     sha: string;
     branch: string;
@@ -48,5 +49,36 @@ export declare function runCacheCheck(options: CacheCheckOptions): Promise<void>
 export declare function runCacheSet(options: CacheSetOptions): Promise<void>;
 export declare function runCacheClear(options: CacheClearOptions): Promise<void>;
 export declare function runCacheList(options: CacheListOptions): Promise<void>;
-/** Parse-and-validate helper for `set` — surfaces a clean error on bad input. */
+/** Parse-and-validate helper for `set` — surfaces a clean error on bad input.
+ *
+ * Accepts the two historical cache values (`pass`, `fail`) AND the four
+ * canonical Codex verdicts (`pass`, `concerns`, `blocking`, `error`) per
+ * Defect D (rea#77). Codex verdicts are mapped to cache semantics at the CLI
+ * boundary: `pass|concerns` → gate-satisfying `pass`; `blocking|error` →
+ * gate-failing `fail`. The cache internal vocabulary stays binary
+ * (`pass`/`fail` = "gate-satisfying?") while the CLI accepts the full Codex
+ * vocabulary so agents can copy the `/codex-review` verdict verbatim.
+ */
 export declare function parseCacheResult(raw: string): CacheResult;
+/** Shape returned by {@link codexVerdictToCacheResult}: the binary cache result
+ * plus an optional machine-readable `reason` string that records the source
+ * Codex verdict. `reason` is populated for non-`pass` verdicts so downstream
+ * listings expose WHY a cache fail was recorded. */
+export interface CodexVerdictCacheEffect {
+    result: CacheResult;
+    reason?: string | undefined;
+}
+/** Map a Codex verdict to the binary cache result the gate compares against.
+ *
+ * Mapping rationale:
+ *   - `pass` → cache `pass` (clean review, gate should pass)
+ *   - `concerns` → cache `pass` (non-blocking findings, gate should pass;
+ *     reviewer captured concerns in the audit record `metadata.summary`)
+ *   - `blocking` → cache `fail` (must address findings before merge)
+ *   - `error` → cache `fail` (Codex itself errored; no clean-bill-of-health)
+ *
+ * Kept separate from `parseCacheResult` so callers that already have a typed
+ * `CodexVerdict` (e.g. `rea audit record codex-review --also-set-cache`) don't
+ * round-trip through string parsing.
+ */
+export declare function codexVerdictToCacheResult(verdict: CodexVerdict): CodexVerdictCacheEffect;

package/dist/cli/cache.js

@@ -103,10 +103,48 @@ export async function runCacheList(options) {
         console.log(`${e.recorded_at}  ${e.result.padEnd(4)}  ${shortSha}  ${e.branch} → ${e.base}${reason}`);
     }
 }
-/** Parse-and-validate helper for `set` — surfaces a clean error on bad input. */
+/** Parse-and-validate helper for `set` — surfaces a clean error on bad input.
+ *
+ * Accepts the two historical cache values (`pass`, `fail`) AND the four
+ * canonical Codex verdicts (`pass`, `concerns`, `blocking`, `error`) per
+ * Defect D (rea#77). Codex verdicts are mapped to cache semantics at the CLI
+ * boundary: `pass|concerns` → gate-satisfying `pass`; `blocking|error` →
+ * gate-failing `fail`. The cache internal vocabulary stays binary
+ * (`pass`/`fail` = "gate-satisfying?") while the CLI accepts the full Codex
+ * vocabulary so agents can copy the `/codex-review` verdict verbatim.
+ */
 export function parseCacheResult(raw) {
     if (raw === 'pass' || raw === 'fail')
         return raw;
-    err(`result must be 'pass' or 'fail'; got ${JSON.stringify(raw)}`);
+    if (raw === 'concerns')
+        return 'pass';
+    if (raw === 'blocking' || raw === 'error')
+        return 'fail';
+    err(`result must be 'pass', 'fail', 'concerns', 'blocking', or 'error'; got ${JSON.stringify(raw)}`);
     process.exit(1);
 }
+/** Map a Codex verdict to the binary cache result the gate compares against.
+ *
+ * Mapping rationale:
+ *   - `pass` → cache `pass` (clean review, gate should pass)
+ *   - `concerns` → cache `pass` (non-blocking findings, gate should pass;
+ *     reviewer captured concerns in the audit record `metadata.summary`)
+ *   - `blocking` → cache `fail` (must address findings before merge)
+ *   - `error` → cache `fail` (Codex itself errored; no clean-bill-of-health)
+ *
+ * Kept separate from `parseCacheResult` so callers that already have a typed
+ * `CodexVerdict` (e.g. `rea audit record codex-review --also-set-cache`) don't
+ * round-trip through string parsing.
+ */
+export function codexVerdictToCacheResult(verdict) {
+    switch (verdict) {
+        case 'pass':
+            return { result: 'pass' };
+        case 'concerns':
+            return { result: 'pass', reason: 'codex:concerns' };
+        case 'blocking':
+            return { result: 'fail', reason: 'codex:blocking' };
+        case 'error':
+            return { result: 'fail', reason: 'codex:error' };
+    }
+}

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { runAuditRotate, runAuditVerify } from './audit.js';
+import { runAuditRecordCodexReview, runAuditRotate, runAuditVerify } from './audit.js';
 import { parseCacheResult, runCacheCheck, runCacheClear, runCacheList, runCacheSet, } from './cache.js';
 import { runCheck } from './check.js';
 import { runDoctor } from './doctor.js';
@@ -102,6 +102,44 @@ async function main() {
         .action(async (opts) => {
         await runAuditVerify({ ...(opts.since !== undefined ? { since: opts.since } : {}) });
     });
+    const auditRecord = audit
+        .command('record')
+        .description('Emit a structured audit record (D).');
+    auditRecord
+        .command('codex-review')
+        .description('Append a codex.review audit entry the push-review cache gate recognizes. With --also-set-cache, writes the review cache in the same invocation (two sequential appends in one process — not a two-phase commit).')
+        .requiredOption('--head-sha <sha>', 'git HEAD SHA the review covers')
+        .requiredOption('--branch <branch>', 'feature branch under review')
+        .requiredOption('--target <target>', 'base ref or SHA diffed against (e.g. main)')
+        .requiredOption('--verdict <verdict>', 'one of: pass | concerns | blocking | error')
+        .requiredOption('--finding-count <N>', 'non-negative integer finding count', (raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isFinite(n) || n < 0) {
+            throw new Error(`--finding-count must be a non-negative integer; got ${JSON.stringify(raw)}`);
+        }
+        return n;
+    })
+        .option('--summary <text>', 'one-sentence review summary (optional)')
+        .option('--session-id <id>', 'session id to attribute (defaults to "external")')
+        .option('--also-set-cache', 'also update .rea/review-cache.jsonl to reflect this verdict, in the same invocation (recommended for post-review push flow)')
+        .action(async (opts) => {
+        if (opts.verdict !== 'pass' &&
+            opts.verdict !== 'concerns' &&
+            opts.verdict !== 'blocking' &&
+            opts.verdict !== 'error') {
+            throw new Error(`--verdict must be one of pass|concerns|blocking|error; got ${JSON.stringify(opts.verdict)}`);
+        }
+        await runAuditRecordCodexReview({
+            headSha: opts.headSha,
+            branch: opts.branch,
+            target: opts.target,
+            verdict: opts.verdict,
+            findingCount: opts.findingCount,
+            ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+            ...(opts.alsoSetCache === true ? { alsoSetCache: true } : {}),
+        });
+    });
     const cache = program
         .command('cache')
         .description('Review-cache operations — check/set/clear/list .rea/review-cache.jsonl (BUG-009). Used by hooks/push-review-gate.sh to skip re-review on a previously-approved diff.');
@@ -115,7 +153,7 @@ async function main() {
     });
     cache
         .command('set <sha> <result>')
-        .description('Record a review outcome. <result> must be "pass" or "fail". Idempotent line-per-invocation; last write wins on (sha, branch, base).')
+        .description('Record a review outcome. <result> accepts pass|fail (historical) or pass|concerns|blocking|error (Codex verdicts). concerns→pass, blocking|error→fail. Idempotent line-per-invocation; last write wins on (sha, branch, base).')
         .requiredOption('--branch <branch>', 'feature branch being pushed')
         .requiredOption('--base <base>', 'base branch the feature targets')
         .option('--reason <text>', 'free-text context for this entry (recommended on fail)')

package/dist/config/tier-map.d.ts

@@ -9,3 +9,4 @@ export declare function classifyTool(toolName: string, serverName: string, gatew
  * Check if a tool is explicitly blocked in gateway config.
  */
 export declare function isToolBlocked(toolName: string, serverName: string, gatewayConfig?: GatewayConfig): boolean;
+export declare function reaCommandTier(command: string): Tier | null;

package/dist/config/tier-map.js

@@ -106,3 +106,213 @@ export function isToolBlocked(toolName, serverName, gatewayConfig) {
     const override = serverConfig?.tool_overrides?.[toolName];
     return override?.blocked === true;
 }
+/**
+ * Classify a `rea <subcommand>` Bash invocation by its own semantics rather
+ * than the generic Bash default.
+ *
+ * Defect E (rea#78): REA's own governance CLI must not be denied by REA's own
+ * middleware. The gate's error messages literally say "Run `rea cache set
+ * <sha> pass --branch <x> --base <y>`" — then the agent is denied at autonomy
+ * L1 because `Bash` is classified Write and the downstream middleware can't
+ * see that the Write is just appending a line to `.rea/review-cache.jsonl`.
+ *
+ * This helper returns the tier appropriate to the rea subcommand when the
+ * command parses as `rea <sub>` or `npx rea <sub>`. Returns `null` if the
+ * command is not a rea invocation — callers then fall back to the generic
+ * Bash tier.
+ *
+ * Tier mapping:
+ *   - Read:        `cache check|list|get`, `audit verify`,
+ *                  `audit record codex-review`, `check`, `doctor`, `status`
+ *   - Write:       `cache set|clear`, `audit rotate`, `init`,
+ *                  `serve`, `upgrade`, `unfreeze`
+ *   - Destructive: `freeze` (writes `.rea/HALT`, suspends the session)
+ *
+ * `audit record codex-review` is Read-tier because it is REA's own append-only
+ * audit surface — the whole point of the command is to let an L1 agent satisfy
+ * the push-review gate without a human in the loop. Write-tier here would
+ * reintroduce exactly the deadlock Defect D/E close.
+ *
+ * SECURITY: returns `null` for any command containing shell metacharacters
+ * that would let an attacker piggyback arbitrary commands onto an allowed
+ * prefix (e.g. `rea check && rm -rf ~`). Bash tokenizes on whitespace, but
+ * the shell itself dispatches the full command string — token[0] matching
+ * is not a sufficient trust decision. Falling back to `null` forces the
+ * generic Write-tier Bash default, which is what the operator expects for
+ * any command they did not explicitly model here.
+ */
+// Reject redirection and chaining operators. Bare `rea check > /etc/passwd`
+// still executes a write the classifier cannot reason about; same for
+// heredocs (`<<`), pipe-process-substitution (`>(`, `<(`), and the
+// chain/substitute operators the prior pass already covered.
+const REA_SHELL_METACHAR_RE = /[;&|`\n\r<>]|\$\(|>\(|<\(/;
+/**
+ * Returns true iff `first` is an invocation shape we trust for Read-tier
+ * downgrade. Implemented as a function because the trust rules are not pure
+ * suffix matching — pass-3 Codex review surfaced two P1 bypasses in the old
+ * suffix-only model:
+ *
+ *   1. A repo-authored `./bin/rea` script satisfied `endsWith('/bin/rea')`
+ *      and classified as Read at L0 → RCE via repo content.
+ *   2. A repo-authored `./dist/cli/index.js` satisfied
+ *      `endsWith('/dist/cli/index.js')` → same.
+ *
+ * The rules now require:
+ *   - The first token is **absolute** (starts with `/`). Relative paths are
+ *     attacker-influenced via CWD and repo content, so they never get the
+ *     Read-tier downgrade. Callers MAY still run relative-path rea — they
+ *     just fall through to weak-trust (bare `rea`) semantics: Destructive
+ *     subcommands still upgrade; Read/Write fall back to the generic Bash
+ *     Write tier.
+ *   - The path matches one of the two *strong* install shapes:
+ *       (a) contains `/node_modules/.bin/rea` anywhere (unambiguous marker
+ *           of an npm install directory tree);
+ *       (b) starts with `/usr/` or `/opt/` AND ends with `/bin/rea`
+ *           (classic root-write system install location). `/home/…/bin/rea`
+ *           is intentionally NOT honored — `/home/<user>/` is writable
+ *           without root, so an attacker with local shell access could
+ *           pre-seed a trusted-looking path there.
+ *
+ * The old `/dist/cli/index.js` suffix is gone entirely. The legitimate
+ * developer invocation `node ./dist/cli/index.js` has `first === 'node'`
+ * which never matches; only a filesystem-marked-executable
+ * `./dist/cli/index.js` would have hit the old suffix, and that shape was
+ * always attacker-authorable inside a repo. Similarly, `/.bin/rea` (exactly
+ * `/.bin/rea`, at filesystem root) was an accident of suffix matching, not
+ * a real install location; it is gone.
+ */
+function isTrustedReaPath(first) {
+    if (!first.startsWith('/'))
+        return false;
+    // npm install marker — absolute path whose tail is `/node_modules/.bin/rea`.
+    // This is unambiguous: an attacker can only seed this path by having already
+    // run a real npm install, at which point they already had execution.
+    if (first.endsWith('/node_modules/.bin/rea'))
+        return true;
+    // Classic global install — absolute path rooted at a system prefix that
+    // requires root write (so attacker-seeded files are out-of-scope for the
+    // repo-content threat model).
+    if (first.endsWith('/bin/rea')) {
+        if (first.startsWith('/usr/'))
+            return true;
+        if (first.startsWith('/opt/'))
+            return true;
+    }
+    return false;
+}
+export function reaCommandTier(command) {
+    if (typeof command !== 'string' || command.length === 0)
+        return null;
+    // Refuse to classify commands that chain/substitute/redirect — the trailing
+    // shell payload is arbitrary, so the prefix's read-tier status tells us
+    // nothing about what the shell will actually execute.
+    if (REA_SHELL_METACHAR_RE.test(command))
+        return null;
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return null;
+    const tokens = trimmed.split(/\s+/);
+    if (tokens.length === 0)
+        return null;
+    const first = tokens[0];
+    if (first === undefined)
+        return null;
+    // Classify the invocation's trust posture. The ONLY fully-trusted shape is
+    // an absolute-path invocation that `isTrustedReaPath()` recognizes as a
+    // strong install marker (npm `/node_modules/.bin/rea` or a root-write
+    // system global under `/usr/` or `/opt/`). Everything else — bare `rea`,
+    // `npx rea …`, relative paths — is treated as *weak trust*: we still
+    // recognize the subcommand for the sake of destructive-tier UPGRADES
+    // (e.g. `rea freeze` at L1 should be blocked whether or not we can prove
+    // the binary is ours), but we refuse to DOWNGRADE anything that could be
+    // piggybacking on a PATH-spoofable name or an `npx` network/install
+    // side-effect.
+    //
+    // npx note (pass-3 Codex Finding 2): `npx rea …` on a machine without the
+    // package locally cached downloads the tarball, writes to the npm cache,
+    // and executes — explicitly not Read-tier semantics. Treating npx as weak
+    // trust forces agents to commit to a deterministic install path (absolute
+    // `/usr/local/bin/rea` from `npm i -g`, or the fully-resolved
+    // `/…/node_modules/.bin/rea` from a project install) if they want the
+    // Read-tier downgrade.
+    let idx = 0;
+    let trust = 'trusted';
+    if (first === 'npx') {
+        if (tokens.length < 2)
+            return null;
+        const second = tokens[1];
+        if (second !== 'rea' && second !== '@bookedsolid/rea')
+            return null;
+        idx = 2;
+        trust = 'weak';
+    }
+    else if (isTrustedReaPath(first)) {
+        idx = 1;
+    }
+    else if (first === 'rea' || first.split('/').pop() === 'rea') {
+        // Bare `rea` OR any path (relative/absolute) whose tail is literally
+        // `rea`. This captures `./bin/rea`, `./node_modules/.bin/rea`,
+        // `/home/user/.npm-global/bin/rea`, `/tmp/fake/rea`, etc. — none of
+        // these are full-trust under `isTrustedReaPath()`, but we still want
+        // Destructive subcommands (`freeze`) to UPGRADE from Bash Write even
+        // here, because destructive intent is invocation-shape-independent.
+        idx = 1;
+        trust = 'weak';
+    }
+    else {
+        return null;
+    }
+    const sub = tokens[idx];
+    if (sub === undefined) {
+        // `rea` with no subcommand is help/version under `commander` — a read.
+        // Under weak trust, we refuse to downgrade; fall back to generic Write.
+        return trust === 'trusted' ? Tier.Read : null;
+    }
+    const sub2 = tokens[idx + 1];
+    const subcommandTier = (() => {
+        switch (sub) {
+            case 'check':
+            case 'doctor':
+            case 'status':
+                return Tier.Read;
+            case 'cache': {
+                if (sub2 === 'check' || sub2 === 'list' || sub2 === 'get')
+                    return Tier.Read;
+                if (sub2 === 'set' || sub2 === 'clear')
+                    return Tier.Write;
+                return Tier.Write;
+            }
+            case 'audit': {
+                if (sub2 === 'verify')
+                    return Tier.Read;
+                if (sub2 === 'record')
+                    return Tier.Read;
+                if (sub2 === 'rotate')
+                    return Tier.Write;
+                return Tier.Write;
+            }
+            case 'init':
+            case 'serve':
+            case 'upgrade':
+            case 'unfreeze':
+                return Tier.Write;
+            case 'freeze':
+                return Tier.Destructive;
+            default:
+                return null;
+        }
+    })();
+    // Trusted path — return whatever the subcommand semantics say.
+    // Unknown subcommand: default Write (safer than Read).
+    if (trust === 'trusted') {
+        return subcommandTier ?? Tier.Write;
+    }
+    // Weak trust (bare `rea`) — only honor upgrades above Write.
+    // Read/Write subcommands: return null so the middleware applies the generic
+    // Bash Write default (same as the pre-helper behavior, no downgrade).
+    // Destructive subcommands: KEEP the upgrade — `rea freeze` at L1 must block
+    // even if we cannot prove the binary on PATH is ours.
+    if (subcommandTier === Tier.Destructive)
+        return Tier.Destructive;
+    return null;
+}

package/dist/gateway/middleware/blocked-paths.js

@@ -376,6 +376,44 @@ function matchesBlockedPattern(value, pattern) {
         }
         return false;
     }
+    // Defect H (rea#79): dot-anchored patterns. A pattern whose base starts with
+    // `.` (e.g. `.rea/`, `.env`, `.husky/`) is meant to block ONLY leading-dot
+    // filesystem entries — never any path segment that happens to be spelled
+    // similarly without the dot. The previous suffix-based match let pattern
+    // `.rea/` trip on `Projects/rea/Bug Reports` (any project folder named
+    // `rea`) because `suffix.startsWith(base)` was false but the final
+    // `segs.includes(base)` fallback conflated `.rea` with `rea` through
+    // normalization downstream in some code paths. By explicitly requiring
+    // leading-dot segment equality, dot-prefixed patterns cannot bleed across
+    // the dot/no-dot boundary regardless of normalization rule drift.
+    const dotAnchored = base.startsWith('.');
+    if (dotAnchored) {
+        // Dot-anchored: segment must equal base exactly. Dir patterns also match
+        // "<base>/..." via the trailing slash marker. Never scans non-dot
+        // segments, so `Projects/rea/...` can never match `.rea/`.
+        for (let i = 0; i < segs.length; i++) {
+            const seg = segs[i];
+            if (seg === base) {
+                // Exact segment match — for a non-dir pattern this matches a FILE
+                // named exactly `.env`; for a dir pattern it matches the directory
+                // entry itself (the trailing-slash below covers its contents).
+                if (!dirPattern && i !== segs.length - 1)
+                    continue;
+                return true;
+            }
+            if (dirPattern && seg === base)
+                return true;
+        }
+        if (dirPattern) {
+            // Dir pattern: any suffix that starts with `<base>/` matches.
+            for (let i = 0; i < segs.length; i++) {
+                const suffix = segs.slice(i).join('/');
+                if (suffix === base || suffix.startsWith(`${base}/`))
+                    return true;
+            }
+        }
+        return false;
+    }
     for (let i = 0; i < segs.length; i++) {
         const suffix = segs.slice(i).join('/');
         if (suffix === base)

package/dist/gateway/middleware/policy.js

@@ -1,6 +1,48 @@
 import { AutonomyLevel, InvocationStatus, Tier } from '../../policy/types.js';
-import { classifyTool, isToolBlocked } from '../../config/tier-map.js';
+import { classifyTool, isToolBlocked, reaCommandTier } from '../../config/tier-map.js';
 import { loadPolicyAsync } from '../../policy/loader.js';
+const BASH_DISPLAY_MAX_LEN = 80;
+/** Extract the `rea <subcommand>` head from a Bash command string for display
+ * in deny messages. Returns `null` when the command is not a rea invocation. */
+function extractReaSubcommand(command) {
+    const tokens = command.trim().split(/\s+/);
+    if (tokens.length === 0)
+        return null;
+    const first = tokens[0];
+    if (first === undefined)
+        return null;
+    let idx = 0;
+    if (first === 'npx' && tokens.length >= 2 && (tokens[1] === 'rea' || tokens[1] === '@bookedsolid/rea')) {
+        idx = 2;
+    }
+    else if (first === 'rea' || first.endsWith('/rea')) {
+        idx = 1;
+    }
+    else {
+        return null;
+    }
+    const sub = tokens[idx];
+    if (sub === undefined)
+        return 'rea';
+    const sub2 = tokens[idx + 1];
+    if (sub2 !== undefined && /^[a-z][a-z-]*$/.test(sub2)) {
+        return `rea ${sub} ${sub2}`;
+    }
+    return `rea ${sub}`;
+}
+/** Build a readable `Bash: <head>` display string for deny messages. Caller
+ * is responsible for only invoking this for tool_name === 'Bash'. Uses
+ * JSON.stringify to escape hostile characters (newlines, control chars). */
+function formatBashDisplay(command, reaDisplay) {
+    if (reaDisplay !== null) {
+        return `Bash (${reaDisplay})`;
+    }
+    const trimmed = command.trim();
+    const truncated = trimmed.length > BASH_DISPLAY_MAX_LEN
+        ? `${trimmed.slice(0, BASH_DISPLAY_MAX_LEN - 1)}…`
+        : trimmed;
+    return `Bash (${JSON.stringify(truncated)})`;
+}
 /**
  * Autonomy level tier permissions:
  * - L0: Read only
@@ -48,7 +90,23 @@ export function createPolicyMiddleware(initialPolicy, gatewayConfig, baseDir) {
         }
         // SECURITY: Re-derive tier from tool_name — do NOT trust ctx.tier from prior middleware.
         // This prevents a rogue middleware from downgrading a destructive tool to read-tier.
-        const tier = classifyTool(ctx.tool_name, ctx.server_name, gatewayConfig);
+        let tier = classifyTool(ctx.tool_name, ctx.server_name, gatewayConfig);
+        // Defect E (rea#78): when the invocation is a `Bash` call whose command
+        // parses as `rea <subcommand>`, classify by subcommand instead of the
+        // generic `Write` Bash default. REA's own CLI must not be denied by REA's
+        // own middleware at the autonomy level the gate's remediation text
+        // targets. Returns null on non-rea commands so the generic tier stands.
+        let reaSubcommandDisplay = null;
+        if (ctx.tool_name === 'Bash') {
+            const command = ctx.arguments['command'];
+            if (typeof command === 'string') {
+                const subTier = reaCommandTier(command);
+                if (subTier !== null) {
+                    tier = subTier;
+                    reaSubcommandDisplay = extractReaSubcommand(command);
+                }
+            }
+        }
         ctx.tier = tier; // Overwrite with authoritative classification
         // Validate autonomy level is known
         const allowed = TIER_ALLOWED[policy.autonomy_level];
@@ -60,7 +118,14 @@ export function createPolicyMiddleware(initialPolicy, gatewayConfig, baseDir) {
         // Check autonomy level vs tier (fail-closed: deny if tier unknown)
         if (!allowed.has(tier)) {
             ctx.status = InvocationStatus.Denied;
-            ctx.error = `Autonomy level ${policy.autonomy_level} does not allow ${tier}-tier tools. Tool: ${ctx.tool_name}`;
+            // Defect E composition: when the denial is a Bash invocation, include
+            // the command head so the deny-reason is actionable. `Bash` alone tells
+            // the operator nothing about WHICH shell command tripped the gate.
+            const toolDisplay = ctx.tool_name === 'Bash' && typeof ctx.arguments['command'] === 'string'
+                ? formatBashDisplay(ctx.arguments['command'], reaSubcommandDisplay)
+                : ctx.tool_name;
+            ctx.error = `Autonomy level ${policy.autonomy_level} does not allow ${tier}-tier tools. Tool: ${toolDisplay}`;
+            ctx.metadata['reason_code'] = 'tier_exceeds_autonomy';
             return;
         }
         // Store current autonomy level in metadata for audit middleware

package/hooks/_lib/push-review-core.sh

@@ -1059,8 +1059,45 @@ pr_core_run() {
   fi
 
   if [[ -n "$PUSH_SHA" ]] && [[ ${#REA_CLI_ARGS[@]} -gt 0 ]]; then
+    # Defect F (rea#75): distinguish cache-miss from cache-error. Prior version
+    # swallowed all non-zero exits and stderr into a silent `{hit:false}`, which
+    # masked Defect A (0.9.2 `node <shim>` SyntaxError) for weeks. Now we
+    # capture stderr + exit code separately and emit a visible WARN with an
+    # actionable filename when the CLI failed.
     local CACHE_RESULT
-    CACHE_RESULT=$("${REA_CLI_ARGS[@]}" cache check "$PUSH_SHA" --branch "$SOURCE_BRANCH" --base "$TARGET_BRANCH" 2>/dev/null || echo '{"hit":false}')
+    local CACHE_STDOUT=""
+    local CACHE_STDERR_FILE
+    # SECURITY (Codex LOW 4): require mktemp. A predictable /tmp path like
+    # /tmp/rea-cache-err.$PID is a TOCTOU attack surface on shared hosts —
+    # another user can pre-create a symlink from that name to a file they
+    # want us to clobber. If mktemp is unavailable, fail loudly rather than
+    # silently falling back to a predictable path.
+    if ! CACHE_STDERR_FILE=$(mktemp -t rea-cache-err.XXXXXX 2>/dev/null); then
+      printf 'rea push-review: mktemp unavailable; cannot capture cache-check stderr. Aborting.\n' >&2
+      return 2
+    fi
+    local CACHE_EXIT=0
+    CACHE_STDOUT=$("${REA_CLI_ARGS[@]}" cache check "$PUSH_SHA" --branch "$SOURCE_BRANCH" --base "$TARGET_BRANCH" 2>"$CACHE_STDERR_FILE") || CACHE_EXIT=$?
+    local CACHE_STDERR=""
+    CACHE_STDERR=$(cat "$CACHE_STDERR_FILE" 2>/dev/null || true)
+    rm -f "$CACHE_STDERR_FILE"
+    if [[ "$CACHE_EXIT" -ne 0 ]]; then
+      # SECURITY (Codex LOW 5): strip C0/C1 control characters from CLI
+      # stderr before echoing to the terminal. A tampered dist/ or hostile
+      # CLI could otherwise emit OSC/CSI sequences that rewrite lines above
+      # the deny message and mislead the operator. We strip both C0 + DEL
+      # AND C1 (0x80-0x9F) — some terminal emulators still honor bare C1
+      # bytes as CSI introducers (0x9B) or OSC (0x9D).
+      local CACHE_STDERR_SAFE
+      CACHE_STDERR_SAFE=$(printf '%s' "$CACHE_STDERR" | LC_ALL=C tr -d '\000-\037\177\200-\237')
+      printf 'rea push-review: CACHE CHECK FAILED (exit=%d): %s\n' "$CACHE_EXIT" "$CACHE_STDERR_SAFE" >&2
+      printf 'rea push-review: treating as miss; file bookedsolidtech/rea issue if unexpected.\n' >&2
+      CACHE_RESULT='{"hit":false,"reason":"query_error"}'
+    elif [[ -z "$CACHE_STDOUT" ]]; then
+      CACHE_RESULT='{"hit":false,"reason":"cold"}'
+    else
+      CACHE_RESULT="$CACHE_STDOUT"
+    fi
     # Require BOTH hit == true AND result == "pass". A cached `fail` verdict
     # (Codex 0.8.0 pass-2 finding #1) must NOT satisfy the gate — cache.ts
     # serializes `result` verbatim, so a negative verdict would otherwise

package/hooks/commit-review-gate.sh

@@ -242,7 +242,31 @@ if [[ -n "$STAGED_SHA" ]]; then
   # predicate at push-review-core.sh §8; the §218-226 direct-cache fallback
   # already enforces `result == "pass"`, so the two paths must agree.
   if [[ ${#REA_CLI_ARGS[@]} -gt 0 ]]; then
-    CACHE_RESULT=$("${REA_CLI_ARGS[@]}" cache check "$STAGED_SHA" --branch "$BRANCH" --base "$BASE_BRANCH" 2>/dev/null || echo '{"hit":false}')
+    # Defect F (rea#75): surface cache-query errors instead of treating them as
+    # legitimate misses. See hooks/_lib/push-review-core.sh for the rationale.
+    # SECURITY (Codex LOW 4): require mktemp. Predictable /tmp paths are a
+    # TOCTOU surface on shared hosts; fall-loud instead of fall-back.
+    if ! CACHE_STDERR_FILE=$(mktemp -t rea-commit-cache-err.XXXXXX 2>/dev/null); then
+      printf 'rea commit-review: mktemp unavailable; cannot capture cache-check stderr. Aborting.\n' >&2
+      exit 2
+    fi
+    CACHE_EXIT=0
+    CACHE_STDOUT=$("${REA_CLI_ARGS[@]}" cache check "$STAGED_SHA" --branch "$BRANCH" --base "$BASE_BRANCH" 2>"$CACHE_STDERR_FILE") || CACHE_EXIT=$?
+    CACHE_STDERR=$(cat "$CACHE_STDERR_FILE" 2>/dev/null || true)
+    rm -f "$CACHE_STDERR_FILE"
+    if [[ "$CACHE_EXIT" -ne 0 ]]; then
+      # SECURITY (Codex LOW 5): strip C0/C1 control chars before echoing CLI
+      # stderr. Includes 0x80-0x9F because some terminals interpret bare C1
+      # bytes (CSI 0x9B, OSC 0x9D) as escape introducers.
+      CACHE_STDERR_SAFE=$(printf '%s' "$CACHE_STDERR" | LC_ALL=C tr -d '\000-\037\177\200-\237')
+      printf 'rea commit-review: CACHE CHECK FAILED (exit=%d): %s\n' "$CACHE_EXIT" "$CACHE_STDERR_SAFE" >&2
+      printf 'rea commit-review: treating as miss; file bookedsolidtech/rea issue if unexpected.\n' >&2
+      CACHE_RESULT='{"hit":false,"reason":"query_error"}'
+    elif [[ -z "$CACHE_STDOUT" ]]; then
+      CACHE_RESULT='{"hit":false,"reason":"cold"}'
+    else
+      CACHE_RESULT="$CACHE_STDOUT"
+    fi
     if printf '%s' "$CACHE_RESULT" | jq -e '.hit == true and .result == "pass"' >/dev/null 2>&1; then
       CACHE_HIT=true
     fi

package/hooks/settings-protection.sh

@@ -59,89 +59,322 @@ normalize_path() {
     p="${p#$root/}"
   fi
 
-  # URL decode common sequences
-  p=$(printf '%s' "$p" | sed 's/%2[Ff]/\//g; s/%2[Ee]/./g; s/%20/ /g')
+  # URL decode common sequences. Include %5C (`\`) so Windows-style or
+  # percent-encoded back-slash traversal (`..%5C`, `\..\`) normalizes to the
+  # forward-slash form the §5a detector sees.
+  p=$(printf '%s' "$p" \
+    | sed 's/%2[Ff]/\//g; s/%2[Ee]/./g; s/%20/ /g; s/%5[Cc]/\\/g')
 
-  # Collapse path traversals
-  # Remove ./ components
-  p=$(printf '%s' "$p" | sed 's|\./||g')
+  # Translate any backslash separators to forward slashes. Keeps the traversal
+  # check in §5a working for `.claude\hooks\..\settings.json`-style inputs.
+  p=$(printf '%s' "$p" | tr '\\\\' '/')
 
-  # Remove leading ./
-  p="${p#./}"
+  # Strip leading ./ components only. We intentionally do NOT strip interior
+  # ./ sequences — that transformation corrupts `..` traversals (e.g. `.../`
+  # collapsed to `../`, or `../` collapsed to `./`) and hides traversal from
+  # the §5a detector.
+  while [[ "$p" == ./* ]]; do
+    p="${p#./}"
+  done
 
   printf '%s' "$p"
 }
 
+# Strip C0/C1 control characters from a string to prevent terminal escape
+# injection when we echo protected paths back to the operator. Escape sequences
+# in file names could otherwise rewrite lines above the deny message.
+#
+# Byte ranges stripped:
+#   \000-\037  — C0 controls (BEL, BS, HT, LF, CR, ESC, …)
+#   \177       — DEL
+#   \200-\237  — C1 controls (CSI 0x9B, OSC 0x9D, …). Many terminals still
+#                interpret these as single-byte CSI introducers; without
+#                stripping, a UTF-8 file name whose bytes fall in this range
+#                could still drive the cursor on older emulators.
+sanitize_for_stderr() {
+  printf '%s' "$1" | LC_ALL=C tr -d '\000-\037\177\200-\237'
+}
+
 NORMALIZED=$(normalize_path "$FILE_PATH")
+SAFE_FILE_PATH=$(sanitize_for_stderr "$FILE_PATH")
+SAFE_NORMALIZED=$(sanitize_for_stderr "$NORMALIZED")
+
+# ── 5a. Reject path traversal segments (Codex HIGH: Defect I bypass) ─────────
+# A path containing `..` segments can be used to bypass the protected-path
+# globs in §6 — e.g. `.claude/hooks/../settings.json` would pass the
+# `.claude/hooks/*` case-glob in the patch-session allowlist but actually
+# refers to `.claude/settings.json`. We refuse any path that contains a `..`
+# segment in either the raw input OR the normalized form. The request must
+# be reissued with a canonical path.
+#
+# For the raw-input check, translate backslashes first so a Windows-style
+# `.claude\hooks\..\settings.json` is rejected at the raw stage too (the
+# normalized form also catches it — this is defense in depth).
+RAW_PATH_SLASHED=$(printf '%s' "$FILE_PATH" | tr '\\\\' '/')
+raw_has_traversal=0
+case "/$RAW_PATH_SLASHED/" in
+  */../*) raw_has_traversal=1 ;;
+esac
+norm_has_traversal=0
+case "/$NORMALIZED/" in
+  */../*) norm_has_traversal=1 ;;
+esac
+if [[ "$raw_has_traversal" -eq 1 ]] || [[ "$norm_has_traversal" -eq 1 ]]; then
+  {
+    printf 'SETTINGS PROTECTION: path traversal rejected\n'
+    printf '\n'
+    printf '  File: %s\n' "$SAFE_FILE_PATH"
+    printf "  Rule: path contains a '..' segment; rewrite to a canonical\n"
+    printf '        project-relative path without traversal.\n'
+  } >&2
+  exit 2
+fi
 
 # ── 6. Protected path patterns ────────────────────────────────────────────────
+# §6 runs BEFORE the patch-session allowlist so hook-patch sessions cannot
+# reach .rea/policy.yaml, .rea/HALT, or .claude/settings.json via any glob
+# creativity.
 PROTECTED_PATTERNS=(
   '.claude/settings.json'
   '.claude/settings.local.json'
-  '.claude/hooks/'
   '.husky/'
   '.rea/policy.yaml'
   '.rea/HALT'
 )
 
-for pattern in "${PROTECTED_PATTERNS[@]}"; do
-  # Exact match
-  if [[ "$NORMALIZED" == "$pattern" ]]; then
-    {
-      printf 'SETTINGS PROTECTION: Modification blocked\n'
-      printf '\n'
-      printf '  File: %s\n' "$FILE_PATH"
-      printf '  Rule: This file is protected from agent modification.\n'
-      printf '\n'
-      printf '  Protected files include hook scripts, settings, policy,\n'
-      printf '  and kill switch files. These must be modified by humans\n'
-      printf '  via rea CLI or direct editing.\n'
-      printf '\n'
-      printf '  Use: rea init (to update hooks/settings)\n'
-      printf '       rea freeze/unfreeze (for HALT file)\n'
-      printf '       Edit .rea/policy.yaml manually\n'
-    } >&2
-    exit 2
-  fi
-
-  # Directory prefix match (patterns ending in /)
-  if [[ "$pattern" == */ ]] && [[ "$NORMALIZED" == "$pattern"* ]]; then
-    {
-      printf 'SETTINGS PROTECTION: Modification blocked\n'
-      printf '\n'
-      printf '  File: %s\n' "$FILE_PATH"
-      printf '  Rule: Files under %s are protected from agent modification.\n' "$pattern"
-      printf '\n'
-      printf '  These files control the hook safety layer and must be\n'
-      printf '  modified by humans via rea CLI or direct editing.\n'
-    } >&2
-    exit 2
-  fi
-done
+# Patterns that are protected from general agent edits but can be unlocked by
+# REA_HOOK_PATCH_SESSION. Kept separate from the hard-protected list above so
+# the patch-session gate in §6b only applies to these directories.
+PATCH_SESSION_PATTERNS=(
+  '.claude/hooks/'
+)
 
-# ── 7. Case-insensitive fallback check ────────────────────────────────────────
-# Catch case-manipulation bypass attempts (e.g., .Claude/Settings.json)
 LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
-for pattern in "${PROTECTED_PATTERNS[@]}"; do
-  LOWER_PATTERN=$(printf '%s' "$pattern" | tr '[:upper:]' '[:lower:]')
-  if [[ "$LOWER_NORM" == "$LOWER_PATTERN" ]]; then
-    {
-      printf 'SETTINGS PROTECTION: Modification blocked (case-insensitive match)\n'
-      printf '\n'
-      printf '  File: %s\n' "$FILE_PATH"
-      printf '  Matched: %s\n' "$pattern"
-    } >&2
-    exit 2
-  fi
-  if [[ "$LOWER_PATTERN" == */ ]] && [[ "$LOWER_NORM" == "$LOWER_PATTERN"* ]]; then
-    {
-      printf 'SETTINGS PROTECTION: Modification blocked (case-insensitive match)\n'
-      printf '\n'
-      printf '  File: %s\n' "$FILE_PATH"
-      printf '  Matched: %s*\n' "$pattern"
-    } >&2
-    exit 2
+
+# Match $NORMALIZED against PROTECTED_PATTERNS (exact or prefix for patterns
+# ending in '/'). Sets $PROTECTED_MATCH to the matched pattern; exit 0 on hit.
+match_protected() {
+  local pattern
+  PROTECTED_MATCH=""
+  for pattern in "${PROTECTED_PATTERNS[@]}"; do
+    if [[ "$NORMALIZED" == "$pattern" ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+    if [[ "$pattern" == */ ]] && [[ "$NORMALIZED" == "$pattern"* ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+  done
+  return 1
+}
+
+match_protected_ci() {
+  local pattern lp
+  PROTECTED_MATCH=""
+  for pattern in "${PROTECTED_PATTERNS[@]}"; do
+    lp=$(printf '%s' "$pattern" | tr '[:upper:]' '[:lower:]')
+    if [[ "$LOWER_NORM" == "$lp" ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+    if [[ "$lp" == */ ]] && [[ "$LOWER_NORM" == "$lp"* ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+  done
+  return 1
+}
+
+match_patch_session() {
+  local pattern
+  PROTECTED_MATCH=""
+  for pattern in "${PATCH_SESSION_PATTERNS[@]}"; do
+    if [[ "$NORMALIZED" == "$pattern" ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+    if [[ "$pattern" == */ ]] && [[ "$NORMALIZED" == "$pattern"* ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+  done
+  return 1
+}
+
+match_patch_session_ci() {
+  local pattern lp
+  PROTECTED_MATCH=""
+  for pattern in "${PATCH_SESSION_PATTERNS[@]}"; do
+    lp=$(printf '%s' "$pattern" | tr '[:upper:]' '[:lower:]')
+    if [[ "$LOWER_NORM" == "$lp" ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+    if [[ "$lp" == */ ]] && [[ "$LOWER_NORM" == "$lp"* ]]; then
+      PROTECTED_MATCH="$pattern"
+      return 0
+    fi
+  done
+  return 1
+}
+
+if match_protected; then
+  {
+    printf 'SETTINGS PROTECTION: Modification blocked\n'
+    printf '\n'
+    printf '  File: %s\n' "$SAFE_FILE_PATH"
+    printf '  Matched: %s\n' "$PROTECTED_MATCH"
+    printf '  Rule: This file is protected from agent modification, including\n'
+    printf '        sessions with REA_HOOK_PATCH_SESSION set.\n'
+  } >&2
+  exit 2
+fi
+
+if match_protected_ci; then
+  {
+    printf 'SETTINGS PROTECTION: Modification blocked (case-insensitive match)\n'
+    printf '\n'
+    printf '  File: %s\n' "$SAFE_FILE_PATH"
+    printf '  Matched: %s\n' "$PROTECTED_MATCH"
+  } >&2
+  exit 2
+fi
+
+# ── 6b. Hook-patch session (Defect I / rea#76) ───────────────────────────────
+# When REA_HOOK_PATCH_SESSION is set to a non-empty reason, allow edits under
+# .claude/hooks/ and hooks/ for this session. The session boundary IS the
+# expiry — a new shell requires a fresh opt-in. Every allowed edit is audited
+# as hooks.patch.session so the bypass is never silent.
+#
+# SECURITY: runs AFTER §5a (traversal reject) and §6 (hard-protected denies),
+# so no glob creativity can reach policy/HALT/settings files from here.
+if [[ -n "${REA_HOOK_PATCH_SESSION:-}" ]]; then
+  if match_patch_session; then
+    SAFE_REASON=$(sanitize_for_stderr "${REA_HOOK_PATCH_SESSION}")
+    # Audit record via the TypeScript chain so the hash chain stays intact.
+    # If the append fails, block the edit — silent failure would let an
+    # attacker disable audit logging and then patch hooks unobserved.
+    SHA_BEFORE=""
+    if [[ -f "$FILE_PATH" ]]; then
+      if command -v sha256sum >/dev/null 2>&1; then
+        SHA_BEFORE=$(sha256sum "$FILE_PATH" 2>/dev/null | awk '{print $1}')
+      elif command -v shasum >/dev/null 2>&1; then
+        SHA_BEFORE=$(shasum -a 256 "$FILE_PATH" 2>/dev/null | awk '{print $1}')
+      elif command -v openssl >/dev/null 2>&1; then
+        SHA_BEFORE=$(openssl dgst -sha256 "$FILE_PATH" 2>/dev/null | awk '{print $NF}')
+      fi
+    fi
+    ACTOR_NAME=$(git -C "$REA_ROOT" config user.name 2>/dev/null || printf 'unknown')
+    ACTOR_EMAIL=$(git -C "$REA_ROOT" config user.email 2>/dev/null || printf 'unknown')
+
+    AUDIT_PAYLOAD=$(
+      cd "$REA_ROOT" 2>/dev/null || true
+      REA_AUDIT_REASON="${REA_HOOK_PATCH_SESSION}" \
+      REA_AUDIT_FILE="$NORMALIZED" \
+      REA_AUDIT_SHA="$SHA_BEFORE" \
+      REA_AUDIT_ACTOR_NAME="$ACTOR_NAME" \
+      REA_AUDIT_ACTOR_EMAIL="$ACTOR_EMAIL" \
+      REA_AUDIT_PID="$$" \
+      REA_AUDIT_PPID="$PPID" \
+      REA_AUDIT_SESSION="${CLAUDE_SESSION_ID:-external}" \
+      REA_AUDIT_ROOT="$REA_ROOT" \
+      node --input-type=module -e '
+        const root = process.env.REA_AUDIT_ROOT;
+        async function loadMod() {
+          // Consumer path: `@bookedsolid/rea` resolvable via node_modules
+          // (how `rea init`-installed consumers reach the published package)
+          // or via package self-reference when the hook runs inside the rea
+          // source repo itself.
+          try {
+            return await import("@bookedsolid/rea/audit");
+          } catch (e1) {
+            // Dev path: direct file import from the source repos dist/.
+            try {
+              return await import(root + "/dist/audit/append.js");
+            } catch (e2) {
+              process.stderr.write(
+                "audit import failed: package=" + (e1 && e1.message ? e1.message : e1) +
+                "; dist=" + (e2 && e2.message ? e2.message : e2) + "\n");
+              process.exit(1);
+            }
+          }
+        }
+        (async () => {
+          const mod = await loadMod();
+          try {
+            await mod.appendAuditRecord(root, {
+              session_id: process.env.REA_AUDIT_SESSION,
+              tool_name: "hooks.patch.session",
+              server_name: "rea",
+              tier: "write",
+              status: "allowed",
+              autonomy_level: "unknown",
+              duration_ms: 0,
+              metadata: {
+                reason: process.env.REA_AUDIT_REASON,
+                file: process.env.REA_AUDIT_FILE,
+                sha_before: process.env.REA_AUDIT_SHA,
+                actor: {
+                  name: process.env.REA_AUDIT_ACTOR_NAME,
+                  email: process.env.REA_AUDIT_ACTOR_EMAIL,
+                },
+                pid: Number(process.env.REA_AUDIT_PID),
+                ppid: Number(process.env.REA_AUDIT_PPID),
+              },
+            });
+            process.exit(0);
+          } catch (e) {
+            process.stderr.write("audit append failed: " + (e && e.message ? e.message : e) + "\n");
+            process.exit(1);
+          }
+        })();
+      ' 2>&1
+    )
+    AUDIT_EXIT=$?
+    if [[ "$AUDIT_EXIT" -ne 0 ]]; then
+      # Fail closed. We deliberately do NOT fall back to a raw `jq … >> audit`
+      # write: that path skips prev_hash/hash computation and would silently
+      # degrade the hash-chain integrity the rest of REA (and `rea audit verify`)
+      # relies on. If the TypeScript chain is unavailable (no `dist/`, missing
+      # Node, broken import), refuse the hook-patch edit and surface why. The
+      # operator resolves by building the package (`pnpm build`) or running
+      # against a published install that ships `dist/`.
+      {
+        printf 'SETTINGS PROTECTION: audit-append failed; refusing hook-patch edit\n'
+        printf '  File: %s\n' "$SAFE_FILE_PATH"
+        printf '  Rule: hash-chained audit is required; no raw-jq fallback.\n'
+        printf '  Detail: %s\n' "$(sanitize_for_stderr "$AUDIT_PAYLOAD")"
+      } >&2
+      exit 2
+    fi
+    printf 'REA_HOOK_PATCH_SESSION: allowing edit to %s (reason: %s)\n' \
+      "$SAFE_NORMALIZED" "$SAFE_REASON" >&2
+    exit 0
   fi
-done
+fi
+
+# ── 6c. Patch-session patterns are still blocked when env var is NOT set ─────
+if match_patch_session; then
+  {
+    printf 'SETTINGS PROTECTION: Modification blocked\n'
+    printf '\n'
+    printf '  File: %s\n' "$SAFE_FILE_PATH"
+    printf '  Matched: %s\n' "$PROTECTED_MATCH"
+    printf '  Rule: Files under this path are protected. To apply an upstream\n'
+    printf '        hook finding, set REA_HOOK_PATCH_SESSION=<reason> and retry.\n'
+  } >&2
+  exit 2
+fi
+
+if match_patch_session_ci; then
+  {
+    printf 'SETTINGS PROTECTION: Modification blocked (case-insensitive match)\n'
+    printf '\n'
+    printf '  File: %s\n' "$SAFE_FILE_PATH"
+    printf '  Matched: %s\n' "$PROTECTED_MATCH"
+  } >&2
+  exit 2
+fi
 
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",