Codex Review

---
name: codex-review
description: Use this skill when the Stop hook in this project blocks you with reason "请使用 codex-review skill 审稿,通过后在文件末尾写入标记". Drives a real Codex CLI review of the latest plan in the project's plan directory, and once Codex explicitly signs off, appends the pass marker so the Stop hook lets the session end.
---

# codex-review

Codex is a real, independent reviewer reached via the `codex` CLI. Do not
fake this — actually run the commands below and read Codex's real output.

## Plan directory

The plan directory is configurable per project via the `CODEX_REVIEW_PLAN_DIR`
env var set in this project's `.claude/settings.json` Stop hook command
(defaults to `plans` if unset — check that file to confirm the actual
value for this project). All references to "the plan directory" below
mean that directory, not necessarily a literal `plans/`.

## Codex CLI facts (probed 2026-06-30, codex-cli 0.140.0)

- Non-interactive entrypoint: `codex exec`. Without a subcommand it reads
  the prompt from the argument (or stdin if `-` / no arg given).
- **Always redirect stdin from `/dev/null`** when scripting this — even
  with a prompt argument, codex still tries to read stdin and will hang
  forever if stdin is left attached to a pipe/terminal that never closes.
- **Always pass `--skip-git-repo-check`** if the plan's directory isn't
  guaranteed to be a git repo.
- `-C <dir>` sets the working root codex operates in — use the current
  project root (`$CLAUDE_PROJECT_DIR`), not the script's own directory.
- `--json` streams JSONL events to stdout. The first line is
  `{"type":"thread.started","thread_id":"<uuid>"}` — **this uuid is the
  session id to save for resume.**
- `-o <file>` writes just the final agent message (clean text, no JSON)
  to `<file>`. Prefer this over parsing the JSONL stream for the
  "what did Codex actually say" content.
- To continue the **same** session: `codex exec resume <thread_id> -o
  <file> --json "<prompt>" < /dev/null`. Verified: token usage grows
  across calls and Codex correctly recalls prior-turn content, so this
  is genuine context reuse, not a fresh thread.
- **`codex exec resume` does not accept `-C`** — only the initial
  `codex exec` call takes `-C <dir>`. Passing `-C` to `resume` fails
  with `error: unexpected argument '-C' found` (exit code 2). The
  resumed thread already runs in whatever directory the session
  started in.

### Known environment quirk — budget real time for every call

In this sandbox the Responses WebSocket transport (`wss://chatgpt.com/...`)
times out 5 times before codex falls back to plain HTTPS. Every single
`codex exec` / `codex exec resume` call observed took on the order of
**100-150+ seconds** before producing output, purely from this retry/
fallback dance — independent of how trivial the prompt is. Concretely:

- Run codex calls with a timeout of at least 280s (use Bash tool's
  `timeout` parameter in milliseconds, e.g. 290000).
- Do not interpret the `"Reconnecting... N/5 (request timed out)"` lines
  on stderr/stdout as failure — they are expected noise before the
  HTTPS fallback kicks in. The call has failed only if it exits without
  ever emitting an `item.completed` / `agent_message` event.

### Example commands

First round (new session). Use the actual project root as `-C`, not a
hardcoded path — it has moved before (e.g. `/home/work/prj/harness-lab`).
`$CLAUDE_PROJECT_DIR` or `pwd` are safer than a literal path:
```bash
timeout 290 codex exec --json --skip-git-repo-check -C "$CLAUDE_PROJECT_DIR" \
  -o /tmp/codex_review_round1.txt \
  "$(cat <<'EOF'
Review this implementation plan. List only real design or correctness
problems that would matter to the outcome — ignore wording/style nits.
If there are no real problems, say so explicitly and clearly.

<plan>
... full plan file content ...
</plan>
EOF
)" < /dev/null
```
Capture `thread_id` from the first JSONL line of stdout.

Follow-up rounds (same session, after you fixed the plan or rebutted):
```bash
timeout 290 codex exec resume <thread_id> --json \
  -o /tmp/codex_review_round2.txt \
  "I made these changes: ... / I disagree with point N because: ...
   Here is the updated plan: <plan>...</plan>
   Does this resolve your concerns?" < /dev/null
```

## Review loop

1. Find the most recently modified `*.md` file in the plan directory
   (see above) — this is the plan the Stop hook is blocking on. Read it
   in full.
2. Start a **new** Codex session with the full plan text, asking it to
   list real design/correctness problems only (see prompt template
   above). Save the `thread_id`.
3. For each issue Codex raises, do one of:
   - Fix it directly in the plan file, if it's a real gap.
   - Push back with concrete reasoning, in the same resumed session, if
     it's wrong, based on insufficient context, or over-engineering for
     this scope. Do not silently ignore an issue — always respond to it
     one way or the other.
4. Resume the **same** `thread_id` (never start a new session mid-review)
   with the updated plan and/or your rebuttal, and ask Codex to re-check.
5. Repeat steps 3-4 until Codex's response clearly and explicitly states
   there are no remaining real issues. There is no fixed round limit —
   keep going until genuine consensus, not until a convenient stopping
   point.
6. Once Codex has explicitly signed off, append exactly this line to the
   end of the plan file, on its own line, with nothing else around it:

   ```
   <!-- CODEX-REVIEW-APPROVED -->
   ```

## Ground rules

- Do not write the marker to make the Stop hook pass while privately
  knowing of an unresolved issue — that defeats the entire point of this
  harness.
- Do not rubber-stamp Codex's first response, but do not cave to every
  objection either. If Codex raises something out of scope, lacking
  project context, or over-engineered for what was asked, argue back in
  the same session with specifics. The bar is genuine agreement, not
  Codex's literal sign-off obtained by attrition.
- There is no fixed round cap. Keep resuming the same session until
  Codex explicitly states there are no remaining real issues. Two real
  end-to-end runs (a synthetic security-bug plan and a real Tetris plan)
  needed 2 and 3 rounds respectively — don't be surprised if a non-trivial
  plan takes several.
- Always reuse the same `thread_id` across the whole review. Never start
  a fresh session mid-review — that throws away the context Codex needs
  to judge whether your fixes actually address its prior points.
- If Codex's sign-off message explicitly labels a remaining point as
  non-blocking / a minor suggestion (e.g. "this resolves all concerns,
  one small non-blocking note: ..."), you may apply that fix directly
  and write the marker without spending another round confirming it.
  Spending a whole round to re-confirm something already marked
  non-blocking is pure overhead, not rigor.