@bookedsolid/rea 0.13.3 → 0.14.0

package/MIGRATING.md

@@ -261,6 +261,50 @@ After migration, run `pnpm rea doctor`. The relevant lines:
 - `[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
@@ -274,6 +318,8 @@ review:
   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

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.3",
+  "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)",