@bookedsolid/rea 0.13.2 → 0.14.0

package/MIGRATING.md

@@ -0,0 +1,352 @@
+# Migrating to `@bookedsolid/rea` from a project with prior tooling
+
+`rea` was originally written for greenfield projects. Real consumers
+arrive with prior infrastructure already in place — commitlint,
+lint-staged, gitleaks, act-CI, branch-policy linters, project-specific
+gates wired into `.husky/`. This guide names the conflict patterns by
+name and shows the supported migration path for each.
+
+If you hit something this doc doesn't cover, file an issue at
+https://github.com/bookedsolidtech/rea/issues with the offending hook
+body and the prior tool name.
+
+## Prerequisite — husky must be installed and `core.hooksPath` configured
+
+The `.husky/{commit-msg,pre-push}.d/` extension surface is sourced from
+the rea-managed bodies under `.husky/<hookname>`. Those bodies only fire
+when git is configured to use husky. Confirm one of the following:
+
+- Husky 9 (recommended): `pnpm dlx husky init` (or `npx husky init`)
+  during onboarding. Husky 9 sets `core.hooksPath=.husky/_` automatically;
+  rea's bodies live at `.husky/<hookname>` and husky's auto-generated
+  stubs at `.husky/_/<hookname>` source them at hook-fire time. `rea
+  doctor` (0.13.1+) follows the husky 9 stub indirection correctly.
+- Husky 4-8 (legacy): `core.hooksPath=.husky` set, husky's
+  `_/husky.sh` runner installed. Functional but unsupported by husky
+  upstream — migrate to husky 9.
+- Vanilla git (no husky): rea installs the fallback at
+  `.git/hooks/pre-push`. **The fragment recipes below DO NOT run** in
+  this configuration — `.git/hooks/pre-push` is not the same body as
+  `.husky/pre-push`. Either install husky (recommended) or chain your
+  per-tool commands directly into the fallback (you'll lose the
+  upgrade-safe property — `rea upgrade` will refresh the fallback and
+  drop your chain).
+
+`pnpm rea doctor` reports the active hook path. If it shows
+`.git/hooks/pre-push` (rea-managed at .../.git/hooks/pre-push), you
+are on the vanilla-git path — install husky first.
+
+## TL;DR
+
+1. Confirm husky is installed (see prereq above).
+2. Run `rea init` (fresh install) or `rea upgrade` (existing).
+3. **Do not lose your existing chain.** rea now refuses to silently
+   overwrite an executable `.husky/pre-push` or `.husky/commit-msg`
+   that is not rea-managed; you'll see a `[fail]` from `rea doctor`
+   pointing here.
+4. Move each chained command from your existing hook body to a
+   per-tool fragment under `.husky/pre-push.d/<NN>-<name>` or
+   `.husky/commit-msg.d/<NN>-<name>` (executable, lex-ordered).
+5. Re-run `rea init`. The fresh hook body delegates to
+   `rea hook push-gate` and then runs your fragments AFTER the
+   governance gate.
+6. `rea doctor` should now report all checks green.
+
+## What rea ships and what it doesn't
+
+`rea init` / `rea upgrade` install:
+
+- `.husky/pre-push` — package-managed; **do not edit**. Refreshed on every
+  `rea upgrade`.
+- `.husky/commit-msg` — package-managed; **do not edit**. Same.
+- `.git/hooks/pre-push` (fallback when `core.hooksPath` is unset).
+- `.claude/hooks/*.sh` — protection + audit + advisory hooks.
+- `.claude/agents/*.md`, `.claude/commands/*.md`.
+- `.rea/policy.yaml`, `.rea/registry.yaml`.
+
+`rea` does **not** install:
+
+- `.husky/pre-commit` — completely yours. Out of scope for the rea
+  push-gate. If you have one, keep it.
+- `.husky/post-commit`, `post-merge`, `post-checkout`, etc. — yours.
+- Any tool's binary (`commitlint`, `gitleaks`, `husky`, etc.) — yours.
+
+The only files rea touches are explicitly enumerated above. Everything
+else is the consumer's surface.
+
+## Extension surface (added in 0.13.0)
+
+`.husky/pre-push.d/*` and `.husky/commit-msg.d/*` are the
+**upgrade-safe** place to layer your own gates. Files in those
+directories must be executable; rea sources them in lex order AFTER
+its own governance work succeeds. A non-zero exit from any fragment
+fails the hook (matches husky's normal chaining).
+
+- Fragment receives positional args from git (`<remote-name> <remote-url>`
+  for pre-push, `<commit-msg-file>` for commit-msg).
+- Missing directory is a no-op (no fragments = no chained checks).
+- Non-executable files are silently skipped (drop a `README` if you
+  want context next to the fragments — it won't run).
+- Fragments run with the current shell's `set -eu`; an unset variable
+  or a non-zero exit anywhere in the fragment short-circuits.
+
+`rea doctor` reports detected fragments at `[info]` level so you can
+confirm the chain.
+
+## Conflict pattern: commitlint
+
+You probably have something like this in `.husky/commit-msg`:
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"   # husky 4-8
+npx --no-install commitlint --edit "$1"
+```
+
+Or, with husky 9, your own command interleaved with `husky 9`'s body.
+
+**rea 0.11.0+ overwrites `.husky/commit-msg` on `rea upgrade --force`.**
+Your commitlint invocation will be lost.
+
+### Migration
+
+Move commitlint to a fragment:
+
+```bash
+mkdir -p .husky/commit-msg.d
+cat > .husky/commit-msg.d/01-commitlint <<'EOF'
+#!/bin/sh
+exec npx --no-install commitlint --edit "$1"
+EOF
+chmod +x .husky/commit-msg.d/01-commitlint
+```
+
+Re-run `rea upgrade`. The package-managed `.husky/commit-msg` body now
+runs first (HALT check, AI-attribution block when policy enables it),
+then runs your fragment.
+
+## Conflict pattern: lint-staged on pre-push
+
+You probably have:
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+npx --no-install lint-staged
+```
+
+### Migration
+
+```bash
+mkdir -p .husky/pre-push.d
+cat > .husky/pre-push.d/02-lint-staged <<'EOF'
+#!/bin/sh
+exec npx --no-install lint-staged
+EOF
+chmod +x .husky/pre-push.d/02-lint-staged
+```
+
+## Conflict pattern: gitleaks (pre-commit)
+
+`rea` does NOT install a pre-commit hook. Your existing
+`.husky/pre-commit` keeps working unchanged. Just confirm:
+
+- Shebang is `#!/usr/bin/env bash` (not `#!/bin/sh`) if the body uses
+  `set -o pipefail`. On Linux where `/bin/sh = dash`, `pipefail`
+  aborts immediately.
+- gitleaks invocation includes `--redact` so detected secrets don't
+  hit terminal scrollback.
+- gitleaks binary is vendored or installed via postinstall (e.g.
+  `gitleaks-secret-scanner` npm wrapper) so fresh clones work without
+  manual install.
+
+If you want gitleaks to run on push instead of commit, add a fragment:
+
+```bash
+cat > .husky/pre-push.d/03-gitleaks <<'EOF'
+#!/bin/sh
+exec gitleaks detect --redact --no-banner
+EOF
+chmod +x .husky/pre-push.d/03-gitleaks
+```
+
+## Conflict pattern: act-CI matrix
+
+If you have a project-specific CI gate like `./scripts/act-ci.sh`
+chained into `.husky/pre-push` (e.g. BST), it gets clobbered by
+`rea upgrade --force`.
+
+### Migration
+
+```bash
+cat > .husky/pre-push.d/00-act-ci <<'EOF'
+#!/bin/sh
+exec ./scripts/act-ci.sh
+EOF
+chmod +x .husky/pre-push.d/00-act-ci
+```
+
+The `00-` prefix puts act-CI first in lex order so it runs before any
+later fragments. Adjust ordering as needed.
+
+## Conflict pattern: branch-policy linter
+
+A common pattern that reads `$1` (remote name) and `$2` (remote URL)
+to allow/deny pushes to specific remotes:
+
+```sh
+#!/bin/sh
+remote="$1"
+url="$2"
+if [ "$remote" = "origin" ] && echo "$url" | grep -q "production"; then
+  echo "Direct push to production blocked. PR via main." >&2
+  exit 1
+fi
+```
+
+This requires the standard pre-push argv. **rea 0.13.2+ preserves
+git's argv unchanged** for fragments — earlier versions (0.13.0 /
+0.13.1) had a known bug where `set --` mutation in the rea dispatch
+clobbered `$@`. Upgrade to `^0.13.2` if branch-policy linters are part
+of your chain.
+
+### Migration
+
+Drop the body into a fragment as-is:
+
+```bash
+cat > .husky/pre-push.d/05-branch-policy <<'EOF'
+#!/bin/sh
+remote="$1"
+url="$2"
+if [ "$remote" = "origin" ] && echo "$url" | grep -q "production"; then
+  echo "Direct push to production blocked. PR via main." >&2
+  exit 1
+fi
+EOF
+chmod +x .husky/pre-push.d/05-branch-policy
+```
+
+## Conflict pattern: pre-existing rea-CLI invocation
+
+Some consumers had `exec rea hook push-gate "$@"` chained inline in a
+foreign hook body. `rea doctor` recognizes this pattern and reports
+the hook as `external (delegates to rea hook push-gate)` — `pass`,
+not `fail`. No migration required, but you cannot benefit from the
+extension-fragment chain unless you let rea own the hook body.
+
+If you want both — rea ownership AND your other commands — migrate the
+other commands to fragments.
+
+## Conflict pattern: husky 9 layout (`core.hooksPath=.husky/_`)
+
+This is the default husky 9 install. rea 0.13.1+ supports it
+correctly: doctor follows the husky 9 stub indirection from
+`.husky/_/<hookname>` through `.husky/_/h` to the canonical
+`.husky/<hookname>`. No migration required.
+
+If you're on rea 0.13.0 and seeing `[fail] pre-push hook` despite a
+correctly-installed `.husky/pre-push`, upgrade to `^0.13.1`.
+
+## What `rea doctor` will tell you
+
+After migration, run `pnpm rea doctor`. The relevant lines:
+
+- `[ok] pre-push hook installed` — rea-managed body active, fragments
+  (if any) detected
+- `[fail] pre-push hook installed` with **"Detected prior tooling: X,
+  Y, Z"** — your existing hook still chains tooling that should be in
+  fragments. Move each named tool to a `.d/` fragment, then re-run
+  `rea init`.
+- `[info] extension-hook fragments detected: N pre-push.d, M
+  commit-msg.d` — your fragment chain is active
+
+## Codex model knobs (added in 0.14.0)
+
+The push-gate now pins the flagship codex model and `high` reasoning
+effort by default. Pre-0.14.0 it used codex's built-in default, which
+is the special-purpose `codex-auto-review` model at `medium`
+reasoning — a meaningfully weaker reviewer than the flagship.
+Same-code-different-verdict thrashing on long-running branches was
+substantially driven by the lower-reasoning default.
+
+**Defaults (0.14.0+):**
+
+```yaml
+review:
+  codex_model: gpt-5.4              # was codex-auto-review (codex's own default)
+  codex_reasoning_effort: high      # was medium (codex's own default)
+```
+
+You don't need to set these — `gpt-5.4` + `high` are baked in at the
+package level. The policy keys exist for cost-bounded environments
+that want to opt into a weaker model:
+
+```yaml
+review:
+  codex_model: codex-auto-review    # opts back into the prior default
+  codex_reasoning_effort: medium
+```
+
+The model name is passed through to codex's TOML config layer
+(`-c model="…"`); codex itself validates it. An unknown model name
+surfaces as a clear runtime error at first push, not a silent
+fallback. Codex's current catalog (as of 2026-05-03):
+
+- `gpt-5.4` — flagship, reasoning-capable (recommended for review)
+- `gpt-5.4-mini` — smaller, faster, cheaper, less reasoning depth
+- `gpt-5.3-codex` — prior generation, code-specialized
+- `gpt-5.3-codex-spark` — even faster prior gen
+- `gpt-5.2` — older, generally avoid for security-relevant review
+- `codex-auto-review` — special-purpose, lower reasoning ceiling
+
+Reasoning effort is `low | medium | high`. `high` spends more compute
+per finding and produces more consistent verdicts — fewer
+same-code-different-verdict round-trips. Trade-off is push-gate
+latency.
+
+## Policy knobs worth setting
+
+For consumers with a long-running migration branch (>30 commits since
+last push), the push-gate auto-narrows the codex review window unless
+you opt out. Pin explicit values to avoid surprises:
+
+```yaml
+# .rea/policy.yaml
+review:
+  codex_required: true
+  timeout_ms: 1800000              # 30 min — explicit pin
+  auto_narrow_threshold: 30        # 0 to disable auto-narrow
+  last_n_commits: 10               # explicit scope window
+  codex_model: gpt-5.4             # 0.14.0+ default; iron-gate
+  codex_reasoning_effort: high     # 0.14.0+ default; iron-gate
+```
+
+## Bypass when you genuinely need to
+
+```bash
+# Audited skip: codex flips on a known-ambivalent file
+REA_SKIP_CODEX_REVIEW="cemPath-ambivalence" git push
+
+# Whole-gate skip: codex CLI itself is broken
+REA_SKIP_PUSH_GATE="codex-cli-crash-pinging-team" git push
+
+# Concerns-only override (P2 findings) without skipping the gate
+REA_ALLOW_CONCERNS=1 git push
+```
+
+Every bypass is audit-logged with the reason in `.rea/audit.jsonl`.
+Reasons should be specific — "skip" is not a reason; the file or
+verdict that triggered it is.
+
+## When to file an issue vs handle in-tree
+
+- **rea hook ate my chain on `rea upgrade`** → file an issue, that's
+  rea's fault. Workaround: migrate to `.d/` fragments.
+- **rea doctor false-positives on my legitimate setup** → file an
+  issue.
+- **codex flips verdicts on the same code** → upstream of rea (codex
+  CLI itself). Use `REA_SKIP_CODEX_REVIEW` with a specific reason and
+  document the ambivalence.
+- **My pre-commit hook breaks on push** → not rea (rea ships no
+  pre-commit). Fix in your repo.

package/dist/hooks/push-gate/codex-runner.d.ts

@@ -72,6 +72,20 @@ export interface CodexRunOptions {
     timeoutMs: number;
     /** Optional custom review prompt; defaults to Codex's built-in. */
     prompt?: string;
+    /**
+     * Codex CLI model override (0.13.4+). When set, the runner passes
+     * `-c model="<value>"` to `codex exec review`. Codex itself validates
+     * the name. `undefined` falls back to codex's own default
+     * (`codex-auto-review` today, NOT the `gpt-5.4` flagship).
+     */
+    model?: string;
+    /**
+     * Codex reasoning effort (0.13.4+). When set, the runner passes
+     * `-c model_reasoning_effort="<value>"`. Only meaningful when paired
+     * with a reasoning-capable model (gpt-5.4, gpt-5.3-codex). Codex's
+     * own default is `medium`.
+     */
+    reasoningEffort?: 'low' | 'medium' | 'high';
     /**
      * Env passthrough. Tests inject a clean env to prevent ambient overrides.
      * Production passes `process.env`.

package/dist/hooks/push-gate/codex-runner.js

@@ -110,6 +110,22 @@ export function createRealGitExecutor(cwd) {
         },
     };
 }
+// ---------------------------------------------------------------------------
+// Codex invocation
+// ---------------------------------------------------------------------------
+/**
+ * Escape a string for safe inclusion inside a TOML basic-string literal.
+ * Codex's `-c key=value` parser runs the value through TOML, so we have to
+ * close over the same escape contract — namely backslash and double-quote
+ * (TOML basic strings forbid raw `"` and `\` in the body). The model names
+ * and reasoning levels we expect (`gpt-5.4`, `high`, etc.) never contain
+ * either character; this guard exists so a future model-name typo with a
+ * shell metacharacter cannot smuggle a TOML escape that codex misparses
+ * into something dangerous.
+ */
+function escapeTomlString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
 /**
  * Execute `codex exec review` and return the concatenated review text on
  * success. Callers then pass the text to `summarizeReview()` to get a
@@ -120,7 +136,27 @@ export function createRealGitExecutor(cwd) {
  */
 export async function runCodexReview(options) {
     const spawner = options.spawnImpl ?? spawn;
-    const baseArgs = ['exec', 'review', '--base', options.baseRef, '--json', '--ephemeral'];
+    // Model + reasoning overrides go BEFORE the `exec` subcommand because
+    // `-c key=value` is a top-level codex CLI flag, not an `exec` flag.
+    // Codex's TOML parser interprets the value, so we wrap strings in TOML
+    // quotes — `-c model="gpt-5.4"` not `-c model=gpt-5.4` — to ensure the
+    // value lands as a string regardless of upstream parsing changes.
+    const overrideArgs = [];
+    if (options.model !== undefined && options.model.length > 0) {
+        overrideArgs.push('-c', `model="${escapeTomlString(options.model)}"`);
+    }
+    if (options.reasoningEffort !== undefined) {
+        overrideArgs.push('-c', `model_reasoning_effort="${escapeTomlString(options.reasoningEffort)}"`);
+    }
+    const baseArgs = [
+        ...overrideArgs,
+        'exec',
+        'review',
+        '--base',
+        options.baseRef,
+        '--json',
+        '--ephemeral',
+    ];
     const args = options.prompt !== undefined && options.prompt.length > 0 ? [...baseArgs, options.prompt] : baseArgs;
     let child;
     try {

package/dist/hooks/push-gate/index.js

@@ -342,6 +342,14 @@ export async function runPushGate(deps) {
             cwd: deps.baseDir,
             timeoutMs: policy.timeout_ms,
             env,
+            // 0.14.0+: pass the resolved policy's model + reasoning overrides so
+            // codex spawns with `-c model="<name>" -c model_reasoning_effort="<level>"`.
+            // Defaults (gpt-5.4 + high) are baked into resolvePushGatePolicy so
+            // policies that omit these keys still get the iron-gate defaults.
+            ...(policy.codex_model !== undefined ? { model: policy.codex_model } : {}),
+            ...(policy.codex_reasoning_effort !== undefined
+                ? { reasoningEffort: policy.codex_reasoning_effort }
+                : {}),
         });
         const summary = summarizeReview(codexResult.reviewText);
         const blocked = summary.verdict === 'blocking'

package/dist/hooks/push-gate/policy.d.ts

@@ -43,6 +43,19 @@ export interface ResolvedReviewPolicy {
      * emits a stderr warning. Defaults to 30 when unset; 0 disables.
      */
     auto_narrow_threshold: number;
+    /**
+     * Codex CLI model override (0.13.4+). When set, the runner passes
+     * `-c model="<value>"` to every `codex exec review`. `undefined` falls
+     * back to codex's own default (currently `codex-auto-review`, NOT the
+     * flagship `gpt-5.4`).
+     */
+    codex_model: string | undefined;
+    /**
+     * Codex reasoning effort (0.13.4+). When set, the runner passes
+     * `-c model_reasoning_effort="<value>"`. `undefined` falls back to
+     * codex's own default (currently `medium`).
+     */
+    codex_reasoning_effort: 'low' | 'medium' | 'high' | undefined;
     /** `true` when `.rea/policy.yaml` was absent; defaults apply. */
     policyMissing: boolean;
 }
@@ -63,6 +76,27 @@ export declare const PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD = 30;
  * recent work.
  */
 export declare const PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK = 10;
+/**
+ * Default codex model for the push-gate (0.14.0+). Pinned to the flagship
+ * (`gpt-5.4`) instead of falling through to codex's own default of
+ * `codex-auto-review` (a lower-reasoning special-purpose model). Verdict
+ * stability matters more than per-push compute cost for adversarial
+ * review of consumer codebases — the helixir 2026-04-26 thrashing came
+ * from the lower-reasoning default.
+ *
+ * Override via `policy.review.codex_model: <name>` in `.rea/policy.yaml`
+ * for cost-bounded environments. `codex-auto-review` is the explicit
+ * opt-in to the prior 0.13.x behavior.
+ */
+export declare const PUSH_GATE_DEFAULT_CODEX_MODEL = "gpt-5.4";
+/**
+ * Default codex reasoning effort (0.14.0+). Pinned to `high` for maximum
+ * compute per finding — fewer same-code-different-verdict round-trips.
+ * Trades latency for stability. Override via
+ * `policy.review.codex_reasoning_effort: medium | low` in
+ * `.rea/policy.yaml` for cost-bounded environments.
+ */
+export declare const PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT: 'low' | 'medium' | 'high';
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,

package/dist/hooks/push-gate/policy.js

@@ -45,6 +45,27 @@ export const PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD = 30;
  * recent work.
  */
 export const PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK = 10;
+/**
+ * Default codex model for the push-gate (0.14.0+). Pinned to the flagship
+ * (`gpt-5.4`) instead of falling through to codex's own default of
+ * `codex-auto-review` (a lower-reasoning special-purpose model). Verdict
+ * stability matters more than per-push compute cost for adversarial
+ * review of consumer codebases — the helixir 2026-04-26 thrashing came
+ * from the lower-reasoning default.
+ *
+ * Override via `policy.review.codex_model: <name>` in `.rea/policy.yaml`
+ * for cost-bounded environments. `codex-auto-review` is the explicit
+ * opt-in to the prior 0.13.x behavior.
+ */
+export const PUSH_GATE_DEFAULT_CODEX_MODEL = 'gpt-5.4';
+/**
+ * Default codex reasoning effort (0.14.0+). Pinned to `high` for maximum
+ * compute per finding — fewer same-code-different-verdict round-trips.
+ * Trades latency for stability. Override via
+ * `policy.review.codex_reasoning_effort: medium | low` in
+ * `.rea/policy.yaml` for cost-bounded environments.
+ */
+export const PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT = 'high';
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,
@@ -64,6 +85,8 @@ export async function resolvePushGatePolicy(baseDir) {
             timeout_ms: PUSH_GATE_DEFAULT_TIMEOUT_MS,
             last_n_commits: undefined,
             auto_narrow_threshold: PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
+            codex_model: PUSH_GATE_DEFAULT_CODEX_MODEL,
+            codex_reasoning_effort: PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT,
             policyMissing: true,
         };
     }
@@ -75,6 +98,8 @@ export async function resolvePushGatePolicy(baseDir) {
         timeout_ms: review.timeout_ms ?? PUSH_GATE_DEFAULT_TIMEOUT_MS,
         last_n_commits: review.last_n_commits,
         auto_narrow_threshold: review.auto_narrow_threshold ?? PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
+        codex_model: review.codex_model ?? PUSH_GATE_DEFAULT_CODEX_MODEL,
+        codex_reasoning_effort: review.codex_reasoning_effort ?? PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT,
         policyMissing: false,
     };
 }

package/dist/policy/loader.d.ts

@@ -45,18 +45,52 @@ declare const PolicySchema: z.ZodObject<{
          * intent and auto-narrow stays out of the way).
          */
         auto_narrow_threshold: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Codex CLI model override (0.13.4+). Pinned via `-c model="<name>"` on
+         * every `codex exec review` invocation. When unset, codex's own default
+         * applies — which today is the special-purpose `codex-auto-review`
+         * model at `medium` reasoning, NOT the flagship.
+         *
+         * For serious adversarial review on consumer codebases (where verdict
+         * stability matters) the recommended setting is `gpt-5.4` with
+         * `codex_reasoning_effort: high`. Higher reasoning trades push-gate
+         * latency for finding consistency — fewer same-code-different-verdict
+         * round-trips like the 2026-04-26 helixir migration session.
+         *
+         * Loose string type: codex's model catalog evolves over time and we do
+         * NOT want to lock consumers to a hardcoded enum that drifts behind
+         * upstream. Codex itself validates the model name at exec time.
+         */
+        codex_model: z.ZodOptional<z.ZodString>;
+        /**
+         * Codex reasoning effort knob (0.13.4+). Pinned via
+         * `-c model_reasoning_effort="<level>"` on every invocation. Only
+         * meaningful when paired with a reasoning-capable model (gpt-5.4,
+         * gpt-5.3-codex, etc.). The `codex-auto-review` model honors this
+         * but caps lower than gpt-5.4.
+         *
+         * Recommended: `high` for serious review on long-running branches
+         * (more compute spent per finding, fewer flips). `medium` is codex's
+         * own default. `low` for cost-bounded environments where consistency
+         * matters less than throughput.
+         */
+        codex_reasoning_effort: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
         auto_narrow_threshold?: number | undefined;
+        codex_model?: string | undefined;
+        codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
     }, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
         auto_narrow_threshold?: number | undefined;
+        codex_model?: string | undefined;
+        codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -152,6 +186,8 @@ declare const PolicySchema: z.ZodObject<{
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
         auto_narrow_threshold?: number | undefined;
+        codex_model?: string | undefined;
+        codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -197,6 +233,8 @@ declare const PolicySchema: z.ZodObject<{
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
         auto_narrow_threshold?: number | undefined;
+        codex_model?: string | undefined;
+        codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -38,6 +38,36 @@ const ReviewPolicySchema = z
      * intent and auto-narrow stays out of the way).
      */
     auto_narrow_threshold: z.number().int().nonnegative().optional(),
+    /**
+     * Codex CLI model override (0.13.4+). Pinned via `-c model="<name>"` on
+     * every `codex exec review` invocation. When unset, codex's own default
+     * applies — which today is the special-purpose `codex-auto-review`
+     * model at `medium` reasoning, NOT the flagship.
+     *
+     * For serious adversarial review on consumer codebases (where verdict
+     * stability matters) the recommended setting is `gpt-5.4` with
+     * `codex_reasoning_effort: high`. Higher reasoning trades push-gate
+     * latency for finding consistency — fewer same-code-different-verdict
+     * round-trips like the 2026-04-26 helixir migration session.
+     *
+     * Loose string type: codex's model catalog evolves over time and we do
+     * NOT want to lock consumers to a hardcoded enum that drifts behind
+     * upstream. Codex itself validates the model name at exec time.
+     */
+    codex_model: z.string().min(1).optional(),
+    /**
+     * Codex reasoning effort knob (0.13.4+). Pinned via
+     * `-c model_reasoning_effort="<level>"` on every invocation. Only
+     * meaningful when paired with a reasoning-capable model (gpt-5.4,
+     * gpt-5.3-codex, etc.). The `codex-auto-review` model honors this
+     * but caps lower than gpt-5.4.
+     *
+     * Recommended: `high` for serious review on long-running branches
+     * (more compute spent per finding, fewer flips). `medium` is codex's
+     * own default. `low` for cost-bounded environments where consistency
+     * matters less than throughput.
+     */
+    codex_reasoning_effort: z.enum(['low', 'medium', 'high']).optional(),
 })
     .strict();
 /**

package/dist/policy/types.d.ts

@@ -130,6 +130,34 @@ export interface ReviewPolicy {
      * Non-negative integer. The loader rejects negative values.
      */
     auto_narrow_threshold?: number;
+    /**
+     * Codex CLI model override (0.13.4+). Pinned via `-c model="<name>"` on
+     * every `codex exec review` invocation. When unset, codex's own default
+     * applies — which today is the special-purpose `codex-auto-review` model
+     * at medium reasoning, NOT the flagship.
+     *
+     * Recommended for serious adversarial review: `gpt-5.4` paired with
+     * `codex_reasoning_effort: high`. Higher reasoning trades push-gate
+     * latency for verdict consistency — fewer same-code-different-verdict
+     * round-trips like the 2026-04-26 helixir migration session.
+     *
+     * Loose string type — codex's model catalog evolves. Codex itself
+     * validates the model name at exec time; an unknown name surfaces as
+     * a clear runtime error rather than a silent fallback.
+     */
+    codex_model?: string;
+    /**
+     * Codex reasoning effort (0.13.4+). Pinned via
+     * `-c model_reasoning_effort="<level>"` on every invocation. Only
+     * meaningful when paired with a reasoning-capable model (gpt-5.4,
+     * gpt-5.3-codex). Codex's own default is `medium`.
+     *
+     * Recommended: `high` for serious review on long-running branches
+     * (more compute spent per finding, fewer flips). `low` for
+     * cost-bounded environments where consistency matters less than
+     * throughput.
+     */
+    codex_reasoning_effort?: 'low' | 'medium' | 'high';
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used

package/hooks/blocked-paths-enforcer.sh

@@ -113,6 +113,44 @@ normalize_path() {
 
 NORMALIZED=$(normalize_path "$FILE_PATH")
 
+# ── 5a. Path-traversal rejection (0.14.0 iron-gate fix) ───────────────────────
+# Reject any path containing a `..` segment BEFORE the literal-match below.
+# Without this, `foo/../CODEOWNERS` would get past `normalize_path()` (which
+# only strips leading project root + URL-decodes) and the literal-match
+# loop would compare `foo/../CODEOWNERS` against the literal `CODEOWNERS`
+# entry — which doesn't match, so the policy lets the write through. The
+# downstream Write/Edit tool then resolves the traversal and writes to
+# `CODEOWNERS` anyway, defeating the gate.
+#
+# Mirrors settings-protection.sh §5a (which has had this guard since
+# 0.10.x). Both pre- and post-decode forms are checked because
+# normalize_path() URL-decodes earlier and an attacker could split the
+# traversal across encodings (`%2E%2E/`, `..%2F`, etc.).
+raw_has_traversal=0
+norm_has_traversal=0
+case "/$FILE_PATH/" in
+  */../*) raw_has_traversal=1 ;;
+esac
+case "/$NORMALIZED/" in
+  */../*) norm_has_traversal=1 ;;
+esac
+# Also catch URL-encoded traversal in case some tool routes raw-encoded
+# paths through here (e.g. file:// inputs). normalize_path()'s decoder
+# only handles a fixed set; an unrecognized encoding would slip past.
+case "$FILE_PATH" in
+  *%2[Ee]%2[Ee]*|*%2[Ee].*|*.%2[Ee]*) raw_has_traversal=1 ;;
+esac
+if [[ "$raw_has_traversal" -eq 1 ]] || [[ "$norm_has_traversal" -eq 1 ]]; then
+  {
+    printf 'BLOCKED PATH: path traversal rejected\n'
+    printf '\n'
+    printf '  File: %s\n' "$FILE_PATH"
+    printf "  Rule: path contains a '..' segment; rewrite to a canonical\n"
+    printf '        project-relative path without traversal.\n'
+  } >&2
+  exit 2
+fi
+
 for writable in "${AGENT_WRITABLE[@]}"; do
   if [[ "$NORMALIZED" == "$writable" ]] || [[ "$NORMALIZED" == "$writable"* && "$writable" == */ ]]; then
     exit 0

package/hooks/secret-scanner.sh

@@ -40,11 +40,41 @@ fi
 FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
 CONTENT_WRITE=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null)
 CONTENT_EDIT=$(printf '%s' "$INPUT"  | jq -r '.tool_input.new_string // empty' 2>/dev/null)
+# MultiEdit (0.14.0 fix): the payload is at tool_input.edits[].new_string —
+# an array, not a scalar — and the prior versions of this hook never read
+# it. Result: any agent could route credential writes through MultiEdit and
+# bypass the secret scanner entirely. We extract every `new_string` value
+# from the edits array and concatenate them with newlines so the awk-based
+# pattern scan below treats them like any other write content.
+#
+# Defensive coercion (codex round-1 P1): a malformed payload where
+# `new_string` is a number, object, or array would make jq error out, the
+# `2>/dev/null` would swallow stderr, `CONTENT_MULTIEDIT` would be empty,
+# and the precedence chain below would fall through to `exit 0` —
+# silently allowing the write. Same fail-open mode for a non-array
+# `edits` value. We:
+#
+#   1. Coerce `.tool_input.edits` to `[]` if it's anything other than an
+#      array (`if type=="array" then . else [] end`)
+#   2. Coerce every `new_string` to a string via `tostring` so jq cannot
+#      fail on heterogeneous types
+#
+# Both layers fail closed: a malformed payload either yields the empty
+# string (no scan needed, exit 0 from the precedence chain) or yields a
+# pattern-scannable string. There is no path where jq errors silently and
+# the hook falls through to allow.
+CONTENT_MULTIEDIT=$(printf '%s' "$INPUT" | jq -r '
+  (.tool_input.edits // [] | if type=="array" then . else [] end)
+  | map((.new_string // "") | tostring)
+  | join("\n")
+' 2>/dev/null)
 
 if [[ -n "$CONTENT_WRITE" ]]; then
   CONTENT="$CONTENT_WRITE"
 elif [[ -n "$CONTENT_EDIT" ]]; then
   CONTENT="$CONTENT_EDIT"
+elif [[ -n "$CONTENT_MULTIEDIT" ]]; then
+  CONTENT="$CONTENT_MULTIEDIT"
 else
   exit 0
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.13.2",
+  "version": "0.14.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)",
@@ -49,6 +49,7 @@
     ".husky/",
     "LICENSE",
     "README.md",
+    "MIGRATING.md",
     "SECURITY.md",
     "THREAT_MODEL.md"
   ],