agent-composer 0.2.3 → 0.3.1

package/plugin/composer-mastermind/hooks/precommit_codex_review.sh

@@ -0,0 +1,561 @@
+#!/usr/bin/env bash
+# Optional mechanical Codex pre-commit review gate (PreToolUse hook).
+# Blocks Bash `git commit` only when codexReview.enabled and
+# codexReview.preCommitHook.enabled are true, and the Codex review verdict
+# reaches the configured blockOnSeverity threshold.
+#
+# Fail-open by default: reviewer/JQ/plugin/timeout failures warn to stderr and
+# allow the commit unless codexReview.preCommitHook.failClosed is true.
+# Config keys:
+#   codexReview.preCommitCommand, scope, base, model
+#   codexReview.preCommitHook.enabled, blockOnSeverity, timeoutMs, failClosed
+#   codexReview.warmCache.enabled, maxAgeMinutes
+#   codexReview.notify.desktop
+
+set -u
+
+RUN_LOG="/tmp/composer-codex-review-log.jsonl"
+
+composer_disabled() {
+  case "${COMPOSER_ENABLED:-}" in
+    0|false|FALSE|off|OFF|no|NO) return 0 ;;
+  esac
+  case "${COMPOSER_DISABLED:-}" in
+    1|true|TRUE|on|ON|yes|YES) return 0 ;;
+  esac
+  if [[ -n "${COMPOSER_DISABLED_FILE:-}" && -e "$COMPOSER_DISABLED_FILE" ]]; then
+    return 0
+  fi
+  if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -e "$CLAUDE_PROJECT_DIR/.composer-disabled" ]]; then
+    return 0
+  fi
+  if [[ -n "${HOME:-}" && -e "$HOME/.claude/composer.disabled" ]]; then
+    return 0
+  fi
+  return 1
+}
+
+if composer_disabled; then
+  exit 0
+fi
+
+json_escape_fallback() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+emit_json() {
+  local message="$1"
+  jq -nc --arg systemMessage "$message" \
+    '{systemMessage:$systemMessage,suppressOutput:true}' 2>/dev/null \
+    || printf '{"systemMessage":"%s","suppressOutput":true}\n' "$(json_escape_fallback "$message")"
+}
+
+emit_deny() {
+  local reason="$1"
+  local message="${2:-$reason}"
+  jq -nc --arg r "$reason" --arg systemMessage "$message" \
+    '{systemMessage:$systemMessage,suppressOutput:true,hookSpecificOutput:{hookEventName:"PreToolUse", permissionDecision:"deny", permissionDecisionReason:$r}}' 2>/dev/null \
+    || printf '{"systemMessage":"%s","suppressOutput":true,"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$(json_escape_fallback "$message")" "$(json_escape_fallback "$reason")"
+  exit 0
+}
+
+append_run_log() {
+  local verdict="$1"
+  local decision="$2"
+  local source="$3"
+  local duration_ms="$4"
+  local findings="$5"
+  local scope="$6"
+  local diff_hash="$7"
+  jq -nc \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg verdict "$verdict" \
+    --arg decision "$decision" \
+    --arg source "$source" \
+    --arg scope "$scope" \
+    --arg diff_hash "$diff_hash" \
+    --argjson duration_ms "${duration_ms:-0}" \
+    --argjson findings "${findings:-0}" \
+    '{ts:$ts,verdict:$verdict,decision:$decision,source:$source,duration_ms:$duration_ms,findings:$findings,scope:$scope,diff_hash:$diff_hash}' \
+    >> "$RUN_LOG" 2>/dev/null || true
+}
+
+fail_review() {
+  local fail_closed="$1"
+  local reason="$2"
+  local duration_ms="${3:-0}"
+  if [[ "$fail_closed" == "true" ]]; then
+    append_run_log "error" "deny" "sync" "$duration_ms" 0 "${SCOPE:-}" "${DIFF_HASH:-}"
+    emit_deny "codex pre-commit review unavailable (fail-closed): $reason" "⛔ Codex review unavailable (fail-closed): $reason"
+  fi
+  printf 'codex pre-commit review skipped: %s\n' "$reason" >&2
+  append_run_log "skip" "allow" "sync" "$duration_ms" 0 "${SCOPE:-}" "${DIFF_HASH:-}"
+  emit_json "⚠️ Codex pre-commit review skipped: $reason — commit allowed (fail-open)"
+  exit 0
+}
+
+rank_severity() {
+  case "$1" in
+    critical) printf '4' ;;
+    high) printf '3' ;;
+    medium) printf '2' ;;
+    low) printf '1' ;;
+    *) printf '0' ;;
+  esac
+}
+
+severity_for_rank() {
+  case "$1" in
+    4) printf 'critical' ;;
+    3) printf 'high' ;;
+    2) printf 'medium' ;;
+    1) printf 'low' ;;
+    *) printf 'unknown' ;;
+  esac
+}
+
+compact_text() {
+  printf '%s' "$1" | tr '\n\r\t' '   ' | sed 's/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//'
+}
+
+hash_stdin_16() {
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 | awk '{print substr($1,1,16)}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | awk '{print substr($1,1,16)}'
+  else
+    return 1
+  fi
+}
+
+compute_repo_hash() {
+  printf '%s' "$1" | hash_stdin_16
+}
+
+ensure_state_dir() {
+  local dir="${COMPOSER_STATE_DIR:-${HOME:-}/.cache/composer}"
+  [[ -n "$dir" ]] || return 1
+  mkdir -p "$dir" 2>/dev/null || return 1
+  chmod 700 "$dir" 2>/dev/null || return 1
+  [[ -d "$dir" ]] || return 1
+  printf '%s\n' "$dir"
+}
+
+cache_file_is_trusted() {
+  local cache_file="$1"
+  [[ -f "$cache_file" && ! -L "$cache_file" ]] || return 1
+
+  local owner mode current_uid group_digit other_digit stat_out
+  current_uid="$(id -u 2>/dev/null)" || return 1
+  if stat_out="$(stat -f '%u %Lp' "$cache_file" 2>/dev/null)"; then
+    owner="${stat_out%% *}"
+    mode="${stat_out##* }"
+  elif stat_out="$(stat -c '%u %a' "$cache_file" 2>/dev/null)"; then
+    owner="${stat_out%% *}"
+    mode="${stat_out##* }"
+  else
+    return 1
+  fi
+
+  [[ "$owner" == "$current_uid" ]] || return 1
+  [[ "$mode" =~ ^[0-7]+$ ]] || return 1
+  group_digit="${mode: -2:1}"
+  other_digit="${mode: -1}"
+  (( (10#$group_digit & 2) == 0 && (10#$other_digit & 2) == 0 )) || return 1
+  return 0
+}
+
+compute_diff_hash() {
+  local root="$1"
+  local pre_commit_command="$2"
+  local scope="$3"
+  local base="$4"
+  local model="$5"
+  local base_ref merge_base branch_diff
+  # blockOnSeverity is excluded because threshold is re-applied at gate-read time from the cached findings array.
+  {
+    git -C "$root" diff HEAD 2>/dev/null
+    git -C "$root" diff --cached 2>/dev/null
+    if [[ "$scope" == "branch" ]]; then
+      if base_ref="$(git -C "$root" rev-parse --verify "${base}^{commit}" 2>/dev/null)" \
+        && merge_base="$(git -C "$root" merge-base "$base" HEAD 2>/dev/null)" \
+        && branch_diff="$(git -C "$root" diff "$base...HEAD" 2>/dev/null)"; then
+        printf '\ncomposer-codex-review-branch\nbaseRef=%s\nmergeBase=%s\n' "$base_ref" "$merge_base"
+        printf '%s' "$branch_diff"
+        printf '\n'
+      fi
+    fi
+    printf '\ncomposer-codex-review-policy\npreCommitCommand=%s\nscope=%s\nbase=%s\nmodel=%s\n' "$pre_commit_command" "$scope" "$base" "$model"
+  } | hash_stdin_16
+}
+
+find_git_root() {
+  local start="${CLAUDE_PROJECT_DIR:-.}"
+  git -C "$start" rev-parse --show-toplevel 2>/dev/null || git rev-parse --show-toplevel 2>/dev/null
+}
+
+find_codex_plugin_root() {
+  if [[ -n "${COMPOSER_CODEX_PLUGIN_ROOT:-}" && -f "$COMPOSER_CODEX_PLUGIN_ROOT/scripts/codex-companion.mjs" ]]; then
+    printf '%s\n' "$COMPOSER_CODEX_PLUGIN_ROOT"
+    return 0
+  fi
+
+  local marketplace_root="${HOME:-}/.claude/plugins/marketplaces/openai-codex/plugins/codex"
+  if [[ -f "$marketplace_root/scripts/codex-companion.mjs" ]]; then
+    printf '%s\n' "$marketplace_root"
+    return 0
+  fi
+
+  local cache_base="${HOME:-}/.claude/plugins/cache/openai-codex/codex"
+  [[ -d "$cache_base" ]] || return 1
+
+  local versions
+  if versions="$(find "$cache_base" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; 2>/dev/null)"; then
+    if printf '%s\n' "$versions" | sort -V >/dev/null 2>&1; then
+      versions="$(printf '%s\n' "$versions" | sort -V)"
+    else
+      versions="$(printf '%s\n' "$versions" | sort)"
+    fi
+    local version
+    while IFS= read -r version; do
+      [[ -n "$version" ]] || continue
+      if [[ -f "$cache_base/$version/scripts/codex-companion.mjs" ]]; then
+        printf '%s\n' "$cache_base/$version"
+      fi
+    done <<<"$versions" | tail -n 1
+  fi
+}
+
+run_reviewer() {
+  local timeout_seconds="$1"
+  shift
+  if [[ "${COMPOSER_FORCE_BASH_TIMEOUT:-}" != "1" ]] && command -v timeout >/dev/null 2>&1; then
+    timeout "$timeout_seconds" "$@"
+    return $?
+  fi
+  if [[ "${COMPOSER_FORCE_BASH_TIMEOUT:-}" != "1" ]] && command -v gtimeout >/dev/null 2>&1; then
+    gtimeout "$timeout_seconds" "$@"
+    return $?
+  fi
+
+  local pid watchdog status marker
+  marker="${TMPDIR:-/tmp}/composer-timeout.$$.$RANDOM"
+  "$@" &
+  pid=$!
+  (
+    sleeper=""
+    trap '[[ -n "$sleeper" ]] && kill "$sleeper" 2>/dev/null || true; exit 0' TERM INT
+    sleep "$timeout_seconds" &
+    sleeper=$!
+    wait "$sleeper" 2>/dev/null || exit 0
+    printf '1' >"$marker" 2>/dev/null || true
+    kill -TERM "$pid" 2>/dev/null || true
+    sleep 5
+    kill -KILL "$pid" 2>/dev/null || true
+  ) &
+  watchdog=$!
+  wait "$pid"
+  status=$?
+  kill "$watchdog" 2>/dev/null || true
+  wait "$watchdog" 2>/dev/null || true
+  if [[ -f "$marker" ]]; then
+    rm -f "$marker" 2>/dev/null || true
+    return 124
+  fi
+  rm -f "$marker" 2>/dev/null || true
+  return "$status"
+}
+
+run_reviewer_shell() {
+  local timeout_seconds="$1"
+  local command="$2"
+  run_reviewer "$timeout_seconds" bash -c "$command"
+}
+
+notify_desktop() {
+  local message="$1"
+  [[ "${NOTIFY_DESKTOP:-false}" == "true" ]] || return 0
+  command -v osascript >/dev/null 2>&1 || return 0
+  osascript -e "display notification \"$(json_escape_fallback "$message")\" with title \"Composer\"" >/dev/null 2>&1 &
+}
+
+cache_is_fresh_match() {
+  local cache_file="$1"
+  local diff_hash="$2"
+  local max_age_minutes="$3"
+  [[ -f "$cache_file" ]] || return 1
+  jq -e --arg hash "$diff_hash" --argjson maxAge "$max_age_minutes" '
+    (.hash == $hash)
+    and ((.ts | type) == "string")
+    and ((now - (.ts | fromdateiso8601)) <= ($maxAge * 60))
+  ' "$cache_file" >/dev/null 2>&1
+}
+
+write_cache() {
+  local cache_file="$1"
+  local diff_hash="$2"
+  local review_output="$3"
+  local duration_ms="$4"
+  local verdict
+  verdict="$(jq -r '.verdict // empty' <<<"$review_output" 2>/dev/null || true)"
+  case "$verdict" in
+    approve|needs-attention) ;;
+    *) return 0 ;;
+  esac
+  local tmp="${cache_file}.$$"
+  jq -nc \
+    --arg hash "$diff_hash" \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --argjson review "$review_output" \
+    --argjson durationMs "$duration_ms" \
+    '{hash:$hash, verdict:($review.verdict // "error"), summary:($review.summary // ""), findings:(if ($review.findings | type) == "array" then $review.findings else [] end), ts:$ts, durationMs:$durationMs}' \
+    > "$tmp" 2>/dev/null && chmod 600 "$tmp" 2>/dev/null && mv "$tmp" "$cache_file" 2>/dev/null || rm -f "$tmp"
+}
+
+review_from_cache() {
+  local cache_file="$1"
+  jq -c '{verdict:(.verdict // "error"), summary:(.summary // ""), findings:(if (.findings | type) == "array" then .findings else [] end), next_steps:[]}' "$cache_file" 2>/dev/null
+}
+
+cache_age_minutes() {
+  local cache_file="$1"
+  jq -r '((now - (.ts | fromdateiso8601)) / 60 | floor)' "$cache_file" 2>/dev/null || printf '0'
+}
+
+review_has_parse_error() {
+  jq -e '
+    (.parseError // null) as $error
+    | ($error != null and $error != false and (($error | tostring) | length) > 0)
+  ' >/dev/null 2>&1
+}
+
+normalize_review_output() {
+  local review_output="$1"
+  jq -c '
+    def array_or_empty($value): if ($value | type) == "array" then $value else [] end;
+    {
+      verdict: (.result.verdict // .verdict // null),
+      summary: (.result.summary // .summary // ""),
+      findings: array_or_empty(.result.findings // .findings // []),
+      next_steps: array_or_empty(.result.next_steps // .next_steps // [])
+    }
+  ' <<<"$review_output" 2>/dev/null
+}
+
+evaluate_review_output() {
+  local review_output="$1"
+  local source="$2"
+  local duration_ms="$3"
+  local cache_age="${4:-0}"
+  local duration_s=$(( (duration_ms + 999) / 1000 ))
+
+  if ! jq -e . >/dev/null 2>&1 <<<"$review_output"; then
+    fail_review "$FAIL_CLOSED" "review returned unparseable JSON" "$duration_ms"
+  fi
+
+  local verdict
+  verdict="$(jq -r '.verdict // empty' <<<"$review_output" 2>/dev/null || true)"
+  case "$verdict" in
+    approve)
+      printf 'codex pre-commit review: approve\n' >&2
+      append_run_log "approve" "allow" "$source" "$duration_ms" 0 "$SCOPE" "${DIFF_HASH:-}"
+      if [[ "$source" == "cache" ]]; then
+        emit_json "✅ Codex pre-commit review: approve (cached, ${cache_age}m old)"
+      else
+        emit_json "✅ Codex pre-commit review: approve (${duration_s}s)"
+      fi
+      exit 0
+      ;;
+    needs-attention)
+      ;;
+    *)
+      fail_review "$FAIL_CLOSED" "unknown review verdict: ${verdict:-missing}" "$duration_ms"
+      ;;
+  esac
+
+  local summary finding_count max_rank threshold_rank max_severity
+  summary="$(jq -r '.summary // empty' <<<"$review_output" 2>/dev/null || true)"
+  summary="$(compact_text "$summary")"
+  summary="${summary:0:200}"
+  finding_count="$(jq -r 'if (.findings | type) == "array" then (.findings | length) else 0 end' <<<"$review_output" 2>/dev/null || printf '0')"
+
+  max_rank="$(jq -r '
+    def rank: if . == "critical" then 4 elif . == "high" then 3 elif . == "medium" then 2 elif . == "low" then 1 else 0 end;
+    [.findings[]?.severity | rank] | max // 0
+  ' <<<"$review_output" 2>/dev/null || printf '0')"
+  threshold_rank="$(rank_severity "$BLOCK_ON_SEVERITY")"
+  max_severity="$(severity_for_rank "$max_rank")"
+
+  if [[ "$finding_count" -eq 0 || "$max_rank" -ge "$threshold_rank" ]]; then
+    local finding_summary
+    finding_summary="$(jq -r '
+      .findings[:3]
+      | map(
+          "[" + (.severity // "unknown") + "] "
+          + (.file // "<unknown>") + ":"
+          + ((.line_start // 0) | tostring) + " "
+          + (.title // "<untitled>")
+        )
+      | join(" | ")
+    ' <<<"$review_output" 2>/dev/null || true)"
+    finding_summary="$(compact_text "$finding_summary")"
+    notify_desktop "Codex pre-commit review blocked: ${max_severity}"
+    append_run_log "needs-attention" "deny" "$source" "$duration_ms" "$finding_count" "$SCOPE" "${DIFF_HASH:-}"
+    emit_deny "Codex pre-commit review: needs-attention (>= $BLOCK_ON_SEVERITY). $summary | $finding_summary" "⛔ Codex pre-commit review: blocked (${max_severity}, ${duration_s}s)"
+  fi
+
+  printf 'codex pre-commit review: needs-attention but all findings below %s; allowing\n' "$BLOCK_ON_SEVERITY" >&2
+  append_run_log "needs-attention" "allow" "$source" "$duration_ms" "$finding_count" "$SCOPE" "${DIFF_HASH:-}"
+  emit_json "🟡 Codex pre-commit review: needs-attention below ${BLOCK_ON_SEVERITY} threshold — allowing (${duration_s}s)"
+  exit 0
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'codex pre-commit review skipped: jq missing\n' >&2
+  exit 0
+fi
+
+INPUT="$(cat || true)"
+if [[ -z "$INPUT" ]]; then
+  exit 0
+fi
+
+TOOL="$(jq -r '.tool_name // empty' <<<"$INPUT" 2>/dev/null || true)"
+if [[ -z "$TOOL" ]]; then
+  exit 0
+fi
+if [[ "$TOOL" != "Bash" ]]; then
+  exit 0
+fi
+
+COMMAND_TEXT="$(jq -r '.tool_input.command // empty' <<<"$INPUT" 2>/dev/null || true)"
+if [[ -z "$COMMAND_TEXT" ]]; then
+  exit 0
+fi
+if grep -Eq '(^|[^[:alnum:]])(commit-tree|commit-graph)([^[:alnum:]]|$)|--dry-run' <<<"$COMMAND_TEXT"; then
+  exit 0
+fi
+if ! grep -Eq '(^|[^[:alnum:]])git([[:space:]]|[[:space:]].*[[:space:]])commit([[:space:]]|$)' <<<"$COMMAND_TEXT"; then
+  exit 0
+fi
+
+CONFIG_PATH="${COMPOSER_CONFIG:-${CLAUDE_PROJECT_DIR:-.}/composer.config.json}"
+if [[ ! -f "$CONFIG_PATH" ]]; then
+  exit 0
+fi
+
+CONFIG_JSON="$(cat "$CONFIG_PATH" 2>/dev/null || true)"
+if [[ -z "$CONFIG_JSON" ]] || ! jq -e . >/dev/null 2>&1 <<<"$CONFIG_JSON"; then
+  exit 0
+fi
+
+ENABLED="$(jq -r '.codexReview.enabled // false' <<<"$CONFIG_JSON" 2>/dev/null || printf 'false')"
+HOOK_ENABLED="$(jq -r '.codexReview.preCommitHook.enabled // false' <<<"$CONFIG_JSON" 2>/dev/null || printf 'false')"
+if [[ "$ENABLED" != "true" || "$HOOK_ENABLED" != "true" ]]; then
+  exit 0
+fi
+
+REVIEW_COMMAND="$(jq -r '.codexReview.preCommitCommand // "review"' <<<"$CONFIG_JSON" 2>/dev/null || printf 'review')"
+SCOPE="$(jq -r '.codexReview.scope // "working-tree"' <<<"$CONFIG_JSON" 2>/dev/null || printf 'working-tree')"
+BASE="$(jq -r '.codexReview.base // "main"' <<<"$CONFIG_JSON" 2>/dev/null || printf 'main')"
+CODEX_MODEL="$(jq -r '.codexReview.model // empty' <<<"$CONFIG_JSON" 2>/dev/null || true)"
+BLOCK_ON_SEVERITY="$(jq -r '.codexReview.preCommitHook.blockOnSeverity // "high"' <<<"$CONFIG_JSON" 2>/dev/null || printf 'high')"
+TIMEOUT_MS="$(jq -r '.codexReview.preCommitHook.timeoutMs // 120000' <<<"$CONFIG_JSON" 2>/dev/null || printf '120000')"
+FAIL_CLOSED="$(jq -r '.codexReview.preCommitHook.failClosed // false' <<<"$CONFIG_JSON" 2>/dev/null || printf 'false')"
+WARM_CACHE_ENABLED="$(jq -r '.codexReview.warmCache.enabled // false' <<<"$CONFIG_JSON" 2>/dev/null || printf 'false')"
+WARM_CACHE_MAX_AGE_MINUTES="$(jq -r '.codexReview.warmCache.maxAgeMinutes // 30' <<<"$CONFIG_JSON" 2>/dev/null || printf '30')"
+NOTIFY_DESKTOP="$(jq -r '.codexReview.notify.desktop // false' <<<"$CONFIG_JSON" 2>/dev/null || printf 'false')"
+
+case "$REVIEW_COMMAND" in
+  review|adversarial-review) ;;
+  *) fail_review "$FAIL_CLOSED" "invalid preCommitCommand: $REVIEW_COMMAND" ;;
+esac
+case "$BLOCK_ON_SEVERITY" in
+  critical|high|medium|low) ;;
+  *) fail_review "$FAIL_CLOSED" "invalid blockOnSeverity: $BLOCK_ON_SEVERITY" ;;
+esac
+case "$TIMEOUT_MS" in
+  ''|*[!0-9]*) fail_review "$FAIL_CLOSED" "invalid timeoutMs: $TIMEOUT_MS" ;;
+esac
+case "$WARM_CACHE_MAX_AGE_MINUTES" in
+  ''|*[!0-9]*) WARM_CACHE_MAX_AGE_MINUTES=30 ;;
+esac
+
+TIMEOUT_SECONDS=$(( (TIMEOUT_MS + 999) / 1000 ))
+if [[ "$TIMEOUT_SECONDS" -lt 1 ]]; then
+  TIMEOUT_SECONDS=1
+fi
+
+DIFF_HASH=""
+CACHE_FILE=""
+if [[ -n "${COMPOSER_CODEX_REVIEW_CMD:-}" ]]; then
+  : # Test seam commands are not equivalent reviewer policy, so they never read or write warm-cache verdicts.
+elif [[ "$WARM_CACHE_ENABLED" == "true" ]]; then
+  GIT_ROOT="$(find_git_root || true)"
+  if [[ -n "$GIT_ROOT" ]]; then
+    REPO_HASH="$(compute_repo_hash "$GIT_ROOT" 2>/dev/null || true)"
+    DIFF_HASH="$(compute_diff_hash "$GIT_ROOT" "$REVIEW_COMMAND" "$SCOPE" "$BASE" "$CODEX_MODEL" 2>/dev/null || true)"
+    STATE_DIR="$(ensure_state_dir 2>/dev/null || true)"
+    if [[ -n "$REPO_HASH" && -n "$DIFF_HASH" && -n "$STATE_DIR" ]]; then
+      CACHE_FILE="$STATE_DIR/codex-review-cache-${REPO_HASH}.json"
+      if cache_file_is_trusted "$CACHE_FILE" && cache_is_fresh_match "$CACHE_FILE" "$DIFF_HASH" "$WARM_CACHE_MAX_AGE_MINUTES"; then
+        CACHE_OUTPUT="$(review_from_cache "$CACHE_FILE" || true)"
+        CACHE_AGE="$(cache_age_minutes "$CACHE_FILE")"
+        if [[ -n "$CACHE_OUTPUT" ]]; then
+          evaluate_review_output "$CACHE_OUTPUT" "cache" 0 "$CACHE_AGE"
+        fi
+      fi
+    fi
+  fi
+fi
+
+REVIEW_OUTPUT=""
+REVIEW_STATUS=0
+START_SECONDS="$(date +%s)"
+notify_desktop "Codex pre-commit review running…"
+if [[ -n "${COMPOSER_CODEX_REVIEW_CMD:-}" ]]; then
+  REVIEW_OUTPUT="$(run_reviewer_shell "$TIMEOUT_SECONDS" "$COMPOSER_CODEX_REVIEW_CMD" 2>/dev/null)"
+  REVIEW_STATUS=$?
+else
+  CODEX_ROOT="$(find_codex_plugin_root || true)"
+  if [[ -z "$CODEX_ROOT" ]]; then
+    fail_review "$FAIL_CLOSED" "codex companion not found"
+  fi
+  REVIEW_ARGS=("node" "$CODEX_ROOT/scripts/codex-companion.mjs" "$REVIEW_COMMAND" "--wait" "--json" "--scope" "$SCOPE")
+  if [[ "$SCOPE" == "branch" ]]; then
+    REVIEW_ARGS+=("--base" "$BASE")
+  fi
+  if [[ -n "$CODEX_MODEL" ]]; then
+    REVIEW_ARGS+=("--model" "$CODEX_MODEL")
+  fi
+  REVIEW_OUTPUT="$(run_reviewer "$TIMEOUT_SECONDS" "${REVIEW_ARGS[@]}" 2>/dev/null)"
+  REVIEW_STATUS=$?
+fi
+END_SECONDS="$(date +%s)"
+DURATION_MS=$(( (END_SECONDS - START_SECONDS) * 1000 ))
+
+if [[ "$REVIEW_STATUS" -eq 124 ]]; then
+  fail_review "$FAIL_CLOSED" "review timed out after ${TIMEOUT_SECONDS}s" "$DURATION_MS"
+fi
+if [[ "$REVIEW_STATUS" -ne 0 ]]; then
+  fail_review "$FAIL_CLOSED" "review command exited $REVIEW_STATUS" "$DURATION_MS"
+fi
+if [[ -z "$REVIEW_OUTPUT" ]]; then
+  fail_review "$FAIL_CLOSED" "review returned empty output" "$DURATION_MS"
+fi
+if ! jq -e . >/dev/null 2>&1 <<<"$REVIEW_OUTPUT"; then
+  fail_review "$FAIL_CLOSED" "review returned unparseable JSON" "$DURATION_MS"
+fi
+if review_has_parse_error <<<"$REVIEW_OUTPUT"; then
+  fail_review "$FAIL_CLOSED" "review parseError: $(jq -r '.parseError | tostring' <<<"$REVIEW_OUTPUT" 2>/dev/null || printf 'unknown')" "$DURATION_MS"
+fi
+NORMALIZED_REVIEW_OUTPUT="$(normalize_review_output "$REVIEW_OUTPUT" || true)"
+if [[ -z "$NORMALIZED_REVIEW_OUTPUT" ]] || ! jq -e . >/dev/null 2>&1 <<<"$NORMALIZED_REVIEW_OUTPUT"; then
+  fail_review "$FAIL_CLOSED" "review returned unparseable JSON" "$DURATION_MS"
+fi
+
+if [[ -n "$CACHE_FILE" && -n "$DIFF_HASH" ]]; then
+  write_cache "$CACHE_FILE" "$DIFF_HASH" "$NORMALIZED_REVIEW_OUTPUT" "$DURATION_MS"
+fi
+
+evaluate_review_output "$NORMALIZED_REVIEW_OUTPUT" "sync" "$DURATION_MS"

package/plugin/composer-mastermind/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "composer-mastermind",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Multi-agent orchestrator: Claude as brain, GLM/Codex/agy as executors. Dispatches code/research/review work to subagents wired through the @composer-mcp/server MCP server.",
   "claudeCodeVersion": ">=4.6",
   "requires": [
@@ -8,13 +8,15 @@
   ],
   "settings": {
     "PreToolUse": [
-      "bash:hooks/boundary_guard.sh"
+      "bash:hooks/boundary_guard.sh",
+      "bash:hooks/precommit_codex_review.sh"
     ],
     "PostToolUse": [
       "bash:hooks/lint-on-save.sh"
     ],
     "Stop": [
-      "bash:hooks/learn.sh"
+      "bash:hooks/learn.sh",
+      "bash:hooks/codex_warm_review.sh"
     ]
   },
   "skills": [

package/plugin/composer-mastermind/skills/composer-mastermind/SKILL.md

@@ -62,6 +62,31 @@ system — spend it on planning, not on raw worker output.
 | Claude review explicitly requested, or high-risk/security-sensitive second opinion | `composer_review_claude` directly after the default review gate |
 | Anything that mutates state outside the conversation (push, deploy, install) | Escalate to the user. Do not act. |
 
+When an edit targets a project other than the Composer MCP server cwd (for
+example dotfiles or another repo), pass `projectDir: "<absolute path>"` to
+`composer_code_cli` or `composer_code_chain`. Codex must trust that directory
+(a git repo or a `config.toml` projects entry) or it will refuse; do not add
+`--skip-git-repo-check`.
+
+## Codex rescue (second-opinion lane)
+
+Use Codex rescue when the same bug has 2+ failed fix attempts, root-cause
+diagnosis stalls, an architecture/design fork needs cheap cross-model insurance,
+or the user asks for a second opinion.
+
+- Read root `composer.config.json` `codexRescue`: `{enabled, mode, model}`.
+  Omitted means `enabled=true`, `mode=ask`, `model=gpt-5.4-mini`.
+- If `enabled:false`, do not propose or dispatch rescue.
+- If `mode:"ask"`, propose rescue to the user first. If `mode:"auto"`,
+  dispatch only within `spendAuthorization` caps.
+- Route through the `codex:codex-rescue` subagent (Agent tool) or
+  `/codex:rescue` command.
+- ALWAYS pass the configured model. Unpinned rescue defaults to `gpt-5.4`
+  at roughly 3x cost.
+- Rescue prompt includes failing evidence only: error output, file:line refs,
+  latest failing command, changed files, and smallest repro. Do not include the
+  whole transcript, secrets, or `.env.json`.
+
 **Class-based route policy:** route by task class, not by a blanket
 "always dispatch" rule.
 
@@ -147,6 +172,40 @@ dispatch that hits a real-money provider (`anthropic`,
 CLI providers (`Codex`, `agy`) are billed separately by the user's own auth
 and do not count toward these caps. Mock providers are always free.
 
+# Codex review gate (optional)
+
+Optional cross-LLM review lane using the OpenAI `codex` Claude Code plugin:
+a different model catches issues agy / Claude miss. OFF by default via
+`composer.config.json` `codexReview.enabled`. Run `agent-composer doctor`
+to check codex CLI, plugin availability, and current gate config.
+
+Fire Codex review at composer's OWN trigger points. Do NOT enable the plugin's
+global stop-gate; it fires on every stop.
+
+- Before a commit you are about to make (`triggers.preCommit`): run
+  `codexReview.preCommitCommand` (omitted default `review`; repo template pins
+  `adversarial-review` for structured verdicts) on the working-tree diff.
+- After a plan doc is written (`triggers.postPlan`): run
+  `codexReview.postPlanCommand` (default `adversarial-review`) on the plan
+  `.md` via focus text, challenging design before code is written.
+- Invoke via Bash: resolve plugin root from `agent-composer doctor`, then run
+  `node <root>/scripts/codex-companion.mjs <command> --background --scope <scope> [--base <base>] [--model <codexReview.model>] [focus...]`.
+- Default `execution: background`: launch with `run_in_background`, poll
+  `status` / `result`, parse review-output JSON, and surface ONLY `verdict`
+  plus one line per finding. Raw Codex output stays out.
+- Honor `codexReview.mode`: `ask` -> AskUserQuestion once before running;
+  `auto` -> run within `spendAuthorization`.
+
+## Mechanical pre-commit gate
+
+A stronger, optional enforcement: `codexReview.preCommitHook.enabled` turns the
+PreToolUse hook `precommit_codex_review.sh` into a hard gate — a `git commit`
+is DENIED when Codex review returns `needs-attention` with a finding at or above
+`preCommitHook.blockOnSeverity` (default `high`). Fail-open by default
+(`failClosed:false`): if Codex is unavailable the commit proceeds. Run
+`agent-composer doctor` to see the gate state. This is mechanical (hook-enforced),
+unlike the orchestrator-driven triggers above.
+
 # Headless invocation
 
 When composer-mastermind runs inside a headless `claude -p` (eval harness,