Get Codex's second opinion — and actually trust it: a different model reviews your code, plans, and research, and a fresh independent verifier subagent — never the session that wrote the work — judges every finding (Agreed/Disputed/Nuanced/Unverifiable, plus False Positive/Uncited from the citation script) before you act, catching hallucinated citations. Skills: setup, review, adversarial, rescue, verify, research, status, result, cancel, transfer. Task delegation (rescue) wraps your verbatim request in adaptive, preview-approved prompt blocks. Transfer hands the whole session off to a resumable Codex thread (v1.0.5+). Prompt-running skills accept --model/--effort via config.toml, also passed at run time when a project's own .codex/config.toml would override them.

version
5.2.0
GitHub stars
52

Install

/plugin install codex-advisor@claude-code-zero

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LeeJuOh/claude-code-zero.

Contents

Discovered from source

Skills 10

Codex Adversarial Review + Double-Check

You are a translator + executor. Adversarial review defaults to skepticism — it looks for reasons NOT to ship. Your first job is a clean invocation; your second is to hand what comes back to a fresh Verifier subagent and report what it decides. The judging is deliberately not yours.

Execution Contract

This contract overrides default exploration habits. Read it before Phase 1.

PhaseAllowedForbidden
1 ANALYZEcodex-task.sh check-ref, apply-codex-config.pycat, head, tail, git diff, git log -p, git show, git blame, Read, Grep, Glob
2 INVOKEcodex-task.sh review (multi-arg form only — never $ARGUMENTS blob)All source reads
3 WAITcodex-task.sh review-wait loop (≤8 calls, about 30 min), then Read OUT_FILEAll source reads, run_in_background, ps/kill
4 VERIFYcodex-task.sh payload, then Agent (codex-advisor:verifier) per groupReading source; judging or re-judging any finding yourself
5 REPORT + SAVEcodex-report.sh save, codex-report.sh cleanWrite tool for the report

The companion collects the diff itself. Unknown flags are silently joined into the focus text, and so into the prompt (parseArgs in lib/args.mjs). Phase 1 whitelist is the only safety net.


Phase 1: Analyze

You are a translator. Use LM intelligence, not regex tables.

Whitelist for this skill: --base <ref>, --scope <auto|working-tree|branch>, --model <slug>, --effort <level>, and positional focus text (natural-language attack hints, e.g., "check for SQL injection in login handler").

--model and --effort go through scripts/apply-codex-config.py, which updates ~/.codex/config.toml before the companion launches — see the Apply block below. Never put --effort on the review command: review has no such flag, so the companion would mix it into the prompt. Why, and when --model does go on the command: references/companion-usage.md §2.

Rules:

  • Meta-instructions addressed to YOU (e.g. "in Korean", "quickly", "thoroughly" — often typed in the user's own language) → obey for your own behavior, never forward.
  • Junk, emoji, trailing punctuation on flag values → drop (--base develop, → base=develop).
  • Focus text — unlike /codex-review, adversarial DOES accept it. Collect all non-flag, non-meta tokens and join with spaces. This becomes the positional prompt passed after the flags. Never embed meta-instructions in the focus text.
  • Unknown flag (e.g., --commit, --uncommitted, --wait, --foo) → AskUserQuestion to clarify. Common corrections:
    • --uncommitted → did you mean --scope working-tree?
    • --commit <sha> → did you mean --base <sha>~1 --scope branch?
    • --wait / --background → silent no-ops on adversarial; drop.
    • Never pass through.
  • Duplicate flag → AskUserQuestion which one.
  • Ambiguous → AskUserQuestion; if it is unavailable (non-interactive), reply with one AMBIGUOUS: line and run nothing (references/companion-usage.md §9).

Hypothesis exclusion

Codex is the second opinion here, and a reviewer handed a cause confirms that cause instead of finding its own — anchoring. So the focus text carries where to look and what was observed, and your cause theory stays behind. Sort what you were given into three kinds:

KindExampleForwarded
Evidence — symptom, repro step, log line, the request in the user's own words"POST /login with an empty password returns 500"yes
Focus — an area to examine, no claim attached"look at the login handler", "the null handling around session setup"yes
Hypothesis — a claim about cause, a suspected file:line, the answer you expect"auth.ts:42 is missing a null check, that's the bypass", "it's probably the session cache race"no

The boundary in one line: a claim about cause makes it a hypothesis; a bare area makes it focus. "Check the null handling in the login handler" points at code and claims nothing — focus. "The login handler's missing null check lets auth through" hands over the finding — hypothesis.

Apply this the same way whatever the words' origin — whether the user typed the slash command or you read their intent and invoked this skill yourself. Your own invocations are where hypotheses leak hardest, and a test for "who typed this" would make one sentence behave two ways.

Keep the excluded text. Phase 1.5 shows it, and the user can send it after all in one step.

Input validation (allowed in Phase 1):

# Replace <literal clean base> with the value from Phase 1 — or skip
# call entirely if the user gave no --base.
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" check-ref "<literal clean base>"

Apply model/effort (if either flag was provided)

Run before Phase 2 so the companion sees the new config.toml:

"${CLAUDE_PLUGIN_ROOT}/scripts/apply-codex-config.py" \
  "<literal clean model from Phase 1 or empty>" \
  "<literal clean effort from Phase 1 or empty>" \
  --run-flags model

Relay its stdout verbatim. If it exits non-zero, relay its stderr and stop — launching Codex anyway would run it on settings the user didn't ask for. A Run flags: line means the project's own .codex/config.toml sets that value and outranks config.toml; add those flags, exactly as printed, to the adversarial-review command in Phase 2 (and to the command shown in the draft). A Note: line names a project value no flag can override — there is no effort flag for reviews — so say the requested value won't apply in this project. config.toml is global — the change affects every Codex invocation until changed again. Flag that to the user when values changed.

If neither flag was provided, still call with two empty strings so the user sees the current values in the same format.

Before Phase 2, also print the Parsed line:

Parsed: base=develop, scope=auto, focus="check SQL injection in login"   (meta: "quickly" obeyed)

Order: apply-codex-config.py output first, Parsed line second.

For edge cases, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §7.


Phase 1.5: Draft Review

Before launching the adversarial review, show the user the exact command that will be executed. Adversarial uses Pattern A (positional args to companion), so the command itself IS the prompt.

Display the draft

Show the full companion command in a fenced code block:

**Adversarial review command to execute:**

```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" review "${CLAUDE_PLUGIN_DATA}" adversarial-review \
  --base develop \
  --scope auto \
  --focus "check SQL injection in login handler"
```

Each flag/arg line must match what Phase 2 will actually execute. Omit lines for flags the user did not provide. If focus text was transformed from the user's original input, show both:

Original: "pls look at the login handler for sql injection stuff"
→ focus: "check SQL injection in login handler"

Then always print what the hypothesis rule held back, so the user sees the rule's decision rather than having to infer it from what survived:

Excluded (hypothesis): "probably the null check at auth.ts:42"

Write (none) when nothing was excluded — an absent line reads as "the rule didn't run".

Ask for approval

Use AskUserQuestion exactly once:

  • Question: "This command will run the adversarial review."
  • Options:
    1. "Approve — execute as shown"
    2. "Send the excluded lines too" — offer this only when something was excluded
    3. "Needs changes"
    4. "Cancel"

Handle the response

  • Approve → proceed to Phase 2 with the displayed parameters.
  • Send the excluded lines too → append the excluded text to the focus text, then re-display and re-ask. The user asked for it, so it travels — but they see the command it produced before it runs.
  • Needs changes → the user will describe what to change (e.g., change base branch, adjust scope, reword focus text). Apply edits, re-display, re-ask. No loop limit.
  • Cancel → stop execution. Do not proceed to Phase 2.

Phase 2: Invoke (Pattern A — detached review)

Adversarial shares handleReviewCommand with review, so --background / --wait are silent no-ops. The script detaches the companion itself and returns at once.

# Replace <literal ...> with values from Phase 1. Omit the entire line
# for values the user did not provide, including --focus when there is no
# focus text.
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" review "${CLAUDE_PLUGIN_DATA}" adversarial-review \
  <flags from the "Run flags:" line, if the apply step printed one> \
  --base "<literal clean base from Phase 1>" \
  --scope "<literal clean scope from Phase 1>" \
  --focus "<literal clean focus text from Phase 1>"

The script refuses any flag outside that list and passes the focus text to the companion as the positional prompt, after the flags. It prints RUN_DIR=, OUT_FILE= and ERR_FILE=. Re-inject the literal paths in every later Bash call — shell variables do not survive across calls.


Phase 3: Wait

Call with the Bash tool's timeout set to 300000: each call blocks up to 4 minutes, and the default Bash timeout is 2. Keep calling in the foreground, in this turn — a background command that finishes starts a new turn, and the allowed-tools grant does not carry over to it. A call the Bash tool cuts off does not stop the review — call again, and count it toward the cap. Cap at 8 calls (about 30 minutes).

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" review-wait "<literal RUN_DIR path>"
  • STATUS=running → call again.
  • STATUS=done → act on the OUTPUT= line:
OUTPUT=Action
jsonRead OUT_FILE, then Phase 4
emptyRead ERR_FILE, categorize per §6, save adversarial-<ts>-failed.md, stop
non-jsonunexpected-format — show ERR_FILE verbatim, abort
  • 8 calls exhausted → wait-timeout (§6). Do NOT cancel; leave the review running and its RUN_DIR in place (skip the Phase 5 clean). Point the user at /codex-status to follow it and /codex-cancel to stop it.

Full error table: ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §6.


Phase 4: Verify

You do not judge Codex's findings — a fresh subagent does. You have been in this conversation since before the review started, and an author grading a review of their own code is not a review (ADR 0012). Your job in this phase is plumbing: run the script, launch the Verifiers, collect what comes back. Adversarial's higher false-positive rate is handled where it belongs — the script checks every citation against the tree, and the Verifier weighs the attack scenario.

Step 1 — Prepare the payloads

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" payload "${CLAUDE_PLUGIN_DATA}" \
  --skill adversarial --input "<literal OUT_FILE path>" --ref auto

--ref auto turns on the worktree-drift check only for a branch review: that review judged committed code, so its citations should still match HEAD. The wrapper adds the repo root and a fresh payload folder, prints WORK=<path>, and exits with prepare-verifier.py's code.

The script reads result.findings, checks that every cited file:line exists, and writes one payload file per group. Its stdout JSON is your view of the findings — you do not re-derive that list by hand, because a list you extracted yourself is a list you have already formed an opinion about.

ExitMeaningWhat you do
0payloads writtenStep 2
3parse_error — Codex's structured output no longer parsesGo to Phase 5 and report Codex output format changed — no verdicts. No Verifier, no hand-extracted findings.
4no_output — Codex returned nothing to judgeGo to Phase 5 and report Codex returned no output — no verdicts.
2bad usage, unreadable input, or git failureShow stderr verbatim and stop.

Exit 0 with an empty groups list means Codex raised nothing. Report zero findings plus Codex's own overall_explanation, and launch no Verifier.

Step 2 — Launch one Verifier per group

For each entry in the script's groups, make one Agent call:

  • subagent_type: codex-advisor:verifier, which starts a fresh subagent. Not fork — a fork inherits this entire conversation, which is exactly the memory the double-check exists to remove.
  • prompt: the group's payload path and nothing else. A PreToolUse hook replaces the prompt with that file's hash-checked contents, so any sentence you write around the path is discarded before the Verifier sees it. There is no hint to pass and no room to pass one.

Launch at most 10 at a time and start the next batch once those return. The session cap is 20 concurrent subagents; the headroom keeps a large review from hitting it.

When an Agent call fails, that group's findings are Unverified — Verifier call failed. Do not judge them in its place and do not retry on your own. If the user asks for a retry, make a new Agent call with the same payload path — a Verifier, running or finished, is never resumed with a follow-up message.

Step 3 — Collect the verdicts

Each Verifier returns one JSON object, {"verdicts": [...]}.

Read ${CLAUDE_PLUGIN_ROOT}/references/evaluation.md and follow its Reporting section: match verdicts to ids, transcribe the script's own labels (missing → False Positive, uncited → Uncited, drift unverifiable → Unverifiable), and count. A non-empty worktree_drift gets the drift line the template shows.

A verdict you disagree with stays exactly as the Verifier wrote it; your disagreement goes beneath it on one Author note (main session): line. Rewriting the verdict would make you the judge again.


Phase 5: Report + save

Success: save with codex-report.sh save … adversarial using the standard format in references/evaluation.md — Codex's output verbatim, the verdicts by classification, then the summary counts. The counts are the risk picture: a high False Positive line is what separates noise from the real concerns, so leave it visible rather than summarizing it away.

Failure: save with codex-report.sh save … adversarial --failed with error category and captured stderr.

Clean up the companion's temp files — the RUN_DIR folder from Phase 2, as a literal path:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-report.sh" clean "${CLAUDE_PLUGIN_DATA}" "<literal RUN_DIR path>"

Leave WORK where it is. A re-verification the user asks for needs those payload files and their manifest, and the hook refuses a payload it cannot hash-check.


Gotchas

  • Adversarial hallucinates more. False Positive is the most common label on the noisiest findings, and the script reaches it before any Verifier runs by checking the citation against the tree. A high False Positive count in the report is the expected shape here, not a broken run.
  • Focus text IS allowed here (unlike /codex-review). Pass it as --focus; the script puts it after the flags as the positional argument.
  • --commit, --uncommitted do not exist — translate via ANALYZE, never pass through.
  • Companion-side --background / --wait are silent no-ops. Same handler as review. Use Pattern A (review + review-wait).

For the full shared gotchas list, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §10.

Codex Job Cancel

Pass-through wrapper around the Official Codex companion's cancel subcommand. Exists so users who disabled the Official plugin's slash commands can still cancel jobs via codex-advisor.

Invoke companion cancel

Arguments: pass on only a job id (like task-mf3k2a-x7q1zp, or a unique start of one), quoted. If the user asked in words ("stop the running job"), run with no arguments. The script refuses anything else, because the companion reads a stray word as a job id and fails with No job found.

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-job.sh" cancel <filtered arguments>

Relay the companion's output verbatim.

Gotchas

  • Cancellation is not instant. The companion signals the Codex worker; in-flight tool calls may complete before the worker exits. Don't promise "stopped immediately".
  • Cancelling a rescue job does NOT revert the diff. If Codex already wrote files under --write, those changes stay on disk. Remind the user to git diff / git restore if needed.

Codex Task Delegation + Double-Check

You are a translator + executor. The user is handing off an implementation task. Your job is to parse their messy input, wrap the verbatim task text in standard prompt scaffolding, let Codex do the work in the background, then hand the result to a fresh Verifier subagent and report what it decides. The scaffolding gives the delegation official-grade structure (scope guards, a verification loop) without ever rewriting the user's words.

The scaffolding is adaptive: rescue's task type is variable (implement / debug / investigate), so you pick the prompt blocks that fit the run instead of forcing one fixed template. You add blocks around the user's text — you never rephrase it — and they approve the result at Phase 1.5.

Critical: do NOT explore the repo before Codex runs. The point of delegating is that Codex builds the context. Exploring first wastes turns, and it puts the code in the context of the one session whose opinion the Verifier is there to replace.

Execution Contract

This contract overrides default exploration habits. Read it before Phase 1.

PhaseAllowedForbidden
1 ANALYZEapply-codex-config.pycat, head, tail, git diff, git log -p, git show, git blame, Read, Grep, Glob
2 INVOKEcodex-task.sh new-run, snapshot, prompt, launch (prompt via stdin, no positional!)All source reads
3 WAITcodex-task.sh wait loop (≤6 calls, ≤24 min)All source reads, manual polling, ps/kill
4 VERIFYcodex-task.sh payload, then Agent (codex-advisor:verifier)Reading source; judging or re-judging the result yourself
5 REPORT + SAVEcodex-report.sh save, codex-report.sh cleanWrite tool for the report

codex-task.sh launch refuses any argument that is not a known task flag, so a stray word stops the launch instead of landing in the prompt. Phase 1 still decides what is a flag and what is task text.


Phase 1: Analyze

You are a translator. Use LM intelligence, not regex tables.

Whitelist for this skill:

  • --write (bool; default ON for implementation, OFF for read-only investigation) — companion flag, included in the Phase 2 invocation.
  • --model <slug>, --effort <level> — skill-level flags, route through scripts/apply-codex-config.py (see Apply block below). They reach the companion only as the Run flags: the script prints. Every value is written as given — the script judges neither model nor effort, because Codex owns those lists and settles them at run time. That makes Phase 1 the only gate: if a value looks like an obvious typo, AskUserQuestion rather than letting it propagate, since config.toml is global and nothing downstream will second-guess it.
  • --resume-last / --resume / --fresh — mutually exclusive companion flags. Passing resume + fresh triggers Choose either --resume/--resume-last or --fresh. If ANALYZE produces a conflict, AskUserQuestion; never forward both.

Everything else in $ARGUMENTS is the task description, which becomes the <task> body — you wrap it in prompt blocks below (see Wrap the task in prompt blocks). Translate it cleanly:

  • Meta-instructions addressed to YOU (e.g. "answer in Korean", "don't read the repo first" — often typed in the user's own language) → obey for your own behavior, never include in the task prompt (they'd confuse Codex).
  • Junk, emoji → drop.
  • Vague task (e.g., just "fix it", "do something") → AskUserQuestion for clarification. Never explore the repo to guess intent.
  • Unknown flag (e.g., --foo, --background, --wait) → AskUserQuestion. --background and --wait are not needed — Pattern B always uses --background internally. --wait on task is silent prompt corruption; we never accept it.
  • Ambiguous effort / model value → AskUserQuestion.

Apply model/effort (if either flag was provided)

Run before Phase 2 so the companion sees the new config.toml:

"${CLAUDE_PLUGIN_ROOT}/scripts/apply-codex-config.py" \
  "<literal clean model from Phase 1 or empty>" \
  "<literal clean effort from Phase 1 or empty>" \
  --run-flags model,effort

Relay its stdout verbatim. If it exits non-zero, relay its stderr and stop — launching Codex anyway would run it on settings the user didn't ask for. A Run flags: line means the project's own .codex/config.toml sets that value and outranks config.toml; add those flags, exactly as printed, to the task command in Phase 2 (and to the flags shown in the draft). config.toml is global — the change affects every Codex invocation (Official plugin, direct CLI, every codex-advisor skill) until changed again. Flag that to the user when values changed.

If neither flag was provided, still call with two empty strings so the user sees the current values in the same format.

Before Phase 2, also print the Parsed line:

Parsed: task="implement login rate limiter", write=true, resume=(last)

Order: apply-codex-config.py output first, Parsed line second. (Model/effort already shown by the apply script — don't duplicate them in Parsed.)

For edge cases, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §7.

Wrap the task in prompt blocks

The cleaned task text is not sent bare. Wrap it in standard scaffolding so the delegation carries the same structure verify/research get — but keep the user's words verbatim inside <task> (no summarizing, no rewording). You add blocks around their text; you never rewrite it. That's the whole point: structure without distortion.

Pick the blocks by task type — --write is the signal. An implementation or fix mutates the repo, so it needs an autonomy boundary it can act inside; a read-only investigation needs grounding instead.

  • Always: <task> — the approved task text, verbatim.
  • --write ON (implement / fix): add <autonomy_policy>, full form.
  • --write OFF (read-only investigation): add <autonomy_policy>, read-only form, plus <grounding_rules>.

One policy block covers scope, follow-through, and testing because Codex has no one to ask: the companion rejects every server request it makes, and a turn that ends in a question still reports completed, so a question reads as success while the task sits unfinished. The policy settles the boundary up front rather than inviting a check-in.

Block bodies — copy exactly:

<autonomy_policy>
For review, diagnose, or research requests, inspect the relevant materials and report. Do not implement changes.
For change or fix requests, make the requested in-scope local changes and run relevant non-destructive validation without asking first.
Bias towards action. Do not stop at a partial answer, a proposed plan, or an offer to continue.
Do not perform external writes, destructive actions, or scope expansions the task did not ask for; list them in the final report instead. What the task itself asks for is already approved.
Never end with a question — no one can answer it.
If the task's stated cause does not hold, make the requested change anyway and say so in the final report.
Do not write tests for reversible, low-impact changes that mirror the implementation.
</autonomy_policy>

The read-only form drops the lines about making changes and keeps the reporting and follow-through ones. The question line stays: a read-only run reaches Codex through the same companion, so a question ends the turn there too, and the job still reports completed.

The premise line is what keeps a wrong order from passing as a clean run. The task text travels verbatim, cause claim included, so Codex may be sent to the wrong place — and Phase 4 only checks whether the requested change landed, not whether it was the right change. Reporting the mismatch costs a sentence; acting on it would be the scope expansion the line above forbids, so the read-only form asks only for the report.

<autonomy_policy>
For review, diagnose, or research requests, inspect the relevant materials and report. Do not implement changes.
Bias towards action. Do not stop at a partial answer, a proposed plan, or an offer to continue.
Never end with a question — no one can answer it.
If the task's stated cause does not hold, say so in the final report.
</autonomy_policy>
<grounding_rules>
Ground every claim in the provided context or your tool outputs.
Do not present inferences as facts.
If a point is a hypothesis, label it clearly.
</grounding_rules>

Assemble the wrapped prompt with <task> first, then the selected blocks in the order listed. This wrapped XML — not the bare task text — is what Phase 1.5 previews and Phase 2 writes to PROMPT_FILE.


Phase 1.5: Draft Review

Before sending anything to Codex, show the user exactly what will be sent. The user approved the intent — now they approve the prompt.

Display the draft

Show the wrapped XML prompt (everything that will go into PROMPT_FILE) in a fenced code block, along with the companion flags that will be used — <task> holds their verbatim text, surrounded by the blocks selected in Phase 1.

**Prompt to send to Codex:**

```xml
<task>
<the approved task description from Phase 1 — verbatim, nothing added>
</task>

<autonomy_policy>
For review, diagnose, or research requests, inspect the relevant materials and report. Do not implement changes.
For change or fix requests, make the requested in-scope local changes and run relevant non-destructive validation without asking first.
Bias towards action. Do not stop at a partial answer, a proposed plan, or an offer to continue.
Do not perform external writes, destructive actions, or scope expansions the task did not ask for; list them in the final report instead. What the task itself asks for is already approved.
Never end with a question — no one can answer it.
If the task's stated cause does not hold, make the requested change anyway and say so in the final report.
Do not write tests for reversible, low-impact changes that mirror the implementation.
</autonomy_policy>
```

Flags: `--write` `--resume-last`

The example above shows the --write block set. For a read-only run, show the read-only <autonomy_policy> followed by <grounding_rules> (per the Phase 1 selection). The fenced block must contain the exact wrapped XML that will be written to PROMPT_FILE — the user's text verbatim inside <task>, no summarization, no rewording.

Ask for approval

Use AskUserQuestion exactly once:

  • Question: "This prompt will be sent to Codex task."
  • Options:
    1. "Approve — execute as shown"
    2. "Needs changes"
    3. "Cancel"

Handle the response

  • Approve → proceed to Phase 2 with the displayed text.
  • Needs changes → the user will describe what to change. Apply their edit to the draft, then re-display and re-ask. No loop limit — the user controls when to stop.
  • Cancel → stop execution. Do not proceed to Phase 2.

Phase 2: Invoke

codex-task.sh launch starts the job in the background and prints its id.

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" new-run "${CLAUDE_PLUGIN_DATA}" rescue

It prints RUN_DIR= and PROMPT_FILE=. Then, for a --write run only, snapshot the whole working tree (tracked + untracked) as a git tree object. Phase 4 diffs against it, so the Verifier sees what Codex changed and not what the tree was already dirty with. Skip this call for a read-only run — there is nothing to diff. The real index is never touched.

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" snapshot

It prints PRE_TREE=. Write the approved WRAPPED prompt from Phase 1.5 — <task> with the user's verbatim text plus the Phase 1 blocks, never the bare task text:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" prompt "<literal PROMPT_FILE path>" <<'EOF'
<literal approved wrapped XML prompt from Phase 1.5>
EOF

Then launch:

# Each flag line below is optional — include only what Phase 1 parsed.
# Omit the entire line for flags not provided.
# --write: include for implementation (default ON); omit for read-only.
# Model/effort: only the flags on the apply step's "Run flags:" line;
#   otherwise the companion reads them from config.toml.
# --resume-last/--resume/--fresh: mutually exclusive; omit if none.
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" launch "<literal PROMPT_FILE path>" "<literal RUN_DIR path>" \
  <flags from the "Run flags:" line, if the apply step printed one> \
  --write \
  --resume-last

Each flag line in the template is optional — include only what Phase 1 parsed. Replace <literal ...> values with the actual strings from Phase 1. --write defaults to ON for implementation; omit for read-only investigation.

Remember the literal RUN_DIR, PROMPT_FILE, PRE_TREE, and JOB_ID values. Re-inject these as literal strings in every subsequent Bash call — shell variables do not survive across calls.


Phase 3: Wait

Call with the Bash tool's timeout set to 300000: each call blocks up to 4 minutes, and the default Bash timeout is 2. A call the Bash tool cuts off does not stop the job — call again, and count it toward the cap. Cap at 6 calls (24 minutes).

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" wait "<literal JOB_ID>" "<literal RUN_DIR path>"
  • STATUS=completed → Phase 4, with the printed RESULT_FILE
  • STATUS=failed or cancelled → categorize the ERROR= line per §6, save failure report
  • WAIT_TIMED_OUT=true → call again
  • 6 calls exhausted → wait-timeout (§6). Do NOT silently cancel; leave the job running. Show the user the JOB_ID and suggest /codex-status <JOB_ID> for manual follow-up.

Phase 4 hands RESULT_FILE to the script rather than to you, so leave it on disk even when you are about to read it for the report.

Full error table: ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §6.

Notable cases:

  • Task <id> is still running. Use /codex:status before continuing it. → a previous task is still in flight. Show the user the active jobId, point them to /codex-status, and stop. Never silently cancel.
  • Stored job <id> is missing its task request payload. → detached worker couldn't load the request. recovery-impossible. Save failure report.

Phase 4: Verify

You do not judge what Codex produced — a fresh subagent does. You wrote the task text, you approved the prompt, and you have been in this conversation the whole time; an author grading work done to their own order is not a review (ADR 0012). Your job in this phase is plumbing: run the script, launch the Verifier, collect what comes back.

The two run modes send different things to the Verifier — a diff when Codex wrote code, Codex's report when it only investigated. Pick the one that matches Phase 2.

If Codex made code changes (--write)

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" payload "${CLAUDE_PLUGIN_DATA}" \
  --mode diff --pre "<literal PRE_TREE from Phase 2>" \
  --prompt-file "<literal PROMPT_FILE path>"

The script snapshots the tree again and diffs it against the Phase 2 snapshot, so the payload holds exactly what changed while Codex ran — not whatever the working tree happened to be dirty with beforehand. Untracked files Codex created or edited are in it too, because both snapshots cover the whole tree.

diff_empty: true means Codex changed nothing. Report that, and launch no Verifier.

If Codex returned investigation results (read-only)

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" payload "${CLAUDE_PLUGIN_DATA}" \
  --skill rescue --input "<literal RESULT_FILE path>"

Codex's report here is prose, so the whole of it becomes one payload and the Verifier decides where the items begin and end. You do not cut it into claims first — a list you extracted yourself is a list you have already formed an opinion about.

Exit codes (both modes)

Both calls print WORK=<path> (a fresh payload folder) and then the script's JSON, and exit with prepare-verifier.py's code.

ExitMeaningWhat you do
0payload writtenLaunch the Verifier
3parse_error — the companion's result no longer parsesGo to Phase 5 and report Codex output format changed — no verdicts. No Verifier, no hand-extracted claims.
4no_output — Codex returned nothing to judgeGo to Phase 5 and report Codex returned no output — no verdicts.
2bad usage, unreadable input, or git failureShow stderr verbatim and stop.

Launch the Verifier

Both modes produce a single group, all. Make one Agent call:

  • subagent_type: codex-advisor:verifier, which starts a fresh subagent. Not fork — a fork inherits this entire conversation, including the task you wrote, which is exactly the memory the double-check exists to remove.
  • prompt: the group's payload path and nothing else. A PreToolUse hook replaces the prompt with that file's hash-checked contents, so any sentence you write around the path is discarded before the Verifier sees it. There is no hint to pass and no room to pass one.

In --write mode the Verifier reads the diff and may Read and Grep the surrounding code to see what the change landed in. It splits your task text into requirements (req-1, req-2, …) itself and raises anything the diff changed that no requirement asked for as side-effect-N.

When the Agent call fails, the result is Unverified — Verifier call failed. Do not judge it in its place and do not retry on your own. If the user asks for a retry, make a new Agent call with the same payload path — a Verifier, running or finished, is never resumed with a follow-up message.

Collect the verdicts

The Verifier returns one JSON object, {"verdicts": [...]}.

Read ${CLAUDE_PLUGIN_ROOT}/references/evaluation.md and follow its Reporting section for matching ids, counting, and the side-effect-N lines.

A verdict you disagree with stays exactly as the Verifier wrote it; your disagreement goes beneath it on one Author note (main session): line. Rewriting the verdict would make you the judge again.


Phase 5: Report + save

Success: save with codex-report.sh save … rescue using the standard format in references/evaluation.md, with the task description in Scope and Codex's output verbatim. In --write mode the Verifier's req-N verdicts are the per-requirement result and side-effect-N goes on the Unrequested changes line.

Do NOT auto-accept the changes. Present them and wait for the user — references/evaluation.md has the rule and the reason.

Failure: save with codex-report.sh save … rescue --failed with the §6 error category and captured stderr.

Clean up temp files using the literal path, keeping the payload's inputs:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-report.sh" clean "${CLAUDE_PLUGIN_DATA}" "<literal RUN_DIR path>" --keep-inputs

Leave WORK and PROMPT_FILE where they are. A re-verification the user asks for needs the payload, the diff, and the task text the payload points at, and the hook refuses a payload it cannot hash-check.


Gotchas

  • --model / --effort go through apply-codex-config.py. It writes whatever it's given — Codex is the authority on valid models and efforts, so a bad value surfaces there. Details: references/companion-usage.md §2.
  • Never combine --resume / --resume-last with --fresh. The companion rejects the combination.
  • --wait on task is silent prompt corruption. It becomes part of the task prompt body. ANALYZE must reject it.
  • Do NOT explore the repo in Phase 1. The point of delegation is that Codex builds the context.

For the full shared gotchas list, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §10.

Codex Research + Independent Verification

You are a translator + executor. The user wants deep-dive research. Your first job is to hand the topic (and any context document) to Codex without loading the document into your own context. Your second job is to hand what Codex returns to a fresh Verifier subagent, which judges the findings and raises what the research left out. The judging is deliberately not yours (ADR 0012).

For code review use /codex-review. For plan verification use /codex-verify.

Execution Contract

This contract overrides default exploration habits. Read it before Phase 1.

PhaseAllowedForbidden
1 ANALYZEcodex-task.sh check-doc, new-run, prompt (the document goes in by file redirect, never to stdout), apply-codex-config.pycat "$DOC" to stdout, head, tail, Read, Grep, Glob
2 INVOKEcodex-task.sh launch (prompt via stdin pipe)All source / document reads to stdout
3 WAITcodex-task.sh wait loop (≤6 calls, ≤24 min), result written to a fileAll reads, manual polling, ps/kill
4 VERIFYcodex-task.sh payload --mode doc, then Agent (codex-advisor:verifier)Reading the document or the Codex result; judging or supplementing any finding yourself
5 REPORT + SAVEcodex-report.sh save, codex-report.sh cleanWrite tool for the report

Why the material stays out of context: the value of this skill is a second reader who owes nothing to the first. Once you have read Codex's findings, your own additions arrive downstream of them — which is agreement dressed as independence. Passing paths instead of text is what keeps the two readings apart.

codex-task.sh launch refuses any argument that is not a known task flag, so a stray word stops the launch instead of landing in the prompt. Phase 1 still decides what is a flag and what is topic text.


Phase 1: Analyze + assemble blind payload

Parse $ARGUMENTS

Whitelist for this skill: --model <slug>, --effort <level> (skill-level, route through apply-codex-config.py; they reach the companion only as the Run flags: it prints). The topic and optional document path are other skill inputs, not companion flags.

Rules:

  • Plain text → treat as the research topic/question.
  • A single path → treat as a context document; the research task comes from the surrounding text or the filename.
  • Mixed (topic + path) → both, in the blind payload template.
  • Meta-instructions addressed to YOU (e.g. "in Korean", "quickly", "thoroughly" — often typed in the user's own language) → obey for your own behavior, never include in the prompt.
  • No args → AskUserQuestion: "What should I research?"
  • Unknown flags (e.g., --base, --write, --foo) → AskUserQuestion. research has no companion flags to forward. --model/--effort are the only skill-level flags and route through apply-codex-config.py, not the companion.

Hypothesis exclusion

Codex is the investigator here, and an investigator handed an answer verifies that answer instead of searching — anchoring. So the topic carries what to investigate and what has been observed, and your own conclusion stays behind. Sort what you were given into three kinds:

KindExampleForwarded
Evidence — symptom, measurement, the question in the user's own words"p99 doubled after the 3.2 upgrade"yes
Focus — an area or angle to investigate, no claim attached"compare tRPC and GraphQL for our shape of API", "the caching layer"yes
Hypothesis — a claim about cause, a preferred conclusion, the answer you expect"the regression is the new connection pool default", "tRPC is the right call, confirm it"no

The boundary in one line: a claim about the answer makes it a hypothesis; a bare area or question makes it focus. "Why did p99 double after 3.2?" asks — focus. "p99 doubled because 3.2 changed the pool default" answers — hypothesis.

Apply this the same way whatever the words' origin — whether the user typed the slash command or you read their intent and invoked this skill yourself. Your own invocations are where hypotheses leak hardest, and a test for "who typed this" would make one sentence behave two ways.

Keep the excluded text. Phase 1.5 shows it, and the user can send it after all in one step.

If a document was provided, validate it

# Input validation only — never load content.
# Replace <literal doc path> with the path parsed from $ARGUMENTS.
# Refuses a missing or empty file; prints DOC_LINES= (size info, not content).
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" check-doc "<literal doc path>"

Assemble the payload

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" new-run "${CLAUDE_PLUGIN_DATA}" research

It refuses when the Official Codex plugin is missing (point the user at /codex-setup), else prints RUN_DIR= and PROMPT_FILE=. Then write the prompt:

# Header via heredoc. Replace <literal topic> with the cleaned research
# topic from Phase 1. Do NOT embed the user's meta-instructions.
# Block provenance — official gpt-5-4-prompting (prompt-blocks.md), bodies
# adapted to this skill's output schema; re-checked against the 5.6/Astra
# guides 2026-09-11. Re-sync the tag set if the official guide updates.
#   task                        — §Core Wrapper
#   structured_output_contract  — §Output and Format
#   research_mode               — §Task-Specific Blocks
#   citation_rules              — §Grounding and Missing Context
# Omit the --document line in topic-only mode.
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" prompt "<literal PROMPT_FILE path>" \
  --document "<literal doc path>" --tag context_document <<'EOF'
<task>
You are a technical researcher conducting a deep investigation.
Topic: <literal topic from Phase 1>
Investigate thoroughly. Use web search if helpful.
Surface non-obvious insights, not just the first answer.
</task>

<structured_output_contract>
Structured analysis with clear sections.
Separate: observed facts, reasoned inferences, open questions.
Identify risks, trade-offs, alternative perspectives.
</structured_output_contract>

<research_mode>
Breadth first, then depth where evidence changes the recommendation.
</research_mode>

<citation_rules>
Cite sources. Prefer primary. Say "I'm not sure" rather than guessing.
</citation_rules>
EOF

Document mode appends the context document wrapped in <context_document> by file redirect inside the script — stdout stays empty. Topic-only mode sends the header alone.

Apply model/effort (if either flag was provided)

Run after payload assembly, before Phase 2, so the companion sees the new config.toml:

"${CLAUDE_PLUGIN_ROOT}/scripts/apply-codex-config.py" \
  "<literal clean model from Phase 1 or empty>" \
  "<literal clean effort from Phase 1 or empty>" \
  --run-flags model,effort

Relay its stdout verbatim. If it exits non-zero, relay its stderr and stop — launching Codex anyway would run it on settings the user didn't ask for. A Run flags: line means the project's own .codex/config.toml sets that value and outranks config.toml; add those flags, exactly as printed, to the task command in Phase 2. config.toml is global — the change affects every Codex invocation until changed again. Flag that to the user when values changed.

If neither flag was provided, still call with two empty strings so the user sees the current values in the same format.

Before Phase 2, also print the Parsed line:

Parsed: topic="GraphQL vs tRPC in 2026", doc=(none)
# or
Parsed: topic="performance regression analysis", doc="benchmarks/results.md" (DOC_LINES=512)

Order: apply-codex-config.py output first, Parsed line second. Remember the literal RUN_DIR, PROMPT_FILE, and (if any) USER_DOC paths.

For edge cases, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §7 (ANALYZE rules) and §8 (blind-payload details).


Phase 1.5: Draft Review

Before sending anything to Codex, show the user what will be sent. The XML payload is already written to PROMPT_FILE (without the document body for document mode — that's blind-appended). Show the prompt structure so the user can verify the topic and framing.

Display the draft

Show the XML prompt header (everything except the document body) in a fenced code block, plus document info if attached:

**Prompt to send to Codex research:**

```xml
<task>
You are a technical researcher conducting a deep investigation.
Topic: GraphQL vs tRPC performance in 2026
Investigate thoroughly. Use web search if helpful.
Surface non-obvious insights, not just the first answer.
</task>

<structured_output_contract>
Structured analysis with clear sections.
Separate: observed facts, reasoned inferences, open questions.
Identify risks, trade-offs, alternative perspectives.
</structured_output_contract>

<research_mode>
Breadth first, then depth where evidence changes the recommendation.
</research_mode>

<citation_rules>
Cite sources. Prefer primary. Say "I'm not sure" rather than guessing.
</citation_rules>
```

Document: `benchmarks/results.md` (512 lines) — blind-appended as `<context_document>`
Excluded (hypothesis): "the regression is the new connection pool default"

For topic-only mode (no document), omit the Document line.

The XML block must reflect the exact content written to PROMPT_FILE. Do not summarize or abbreviate the XML structure.

Always print the Excluded (hypothesis): line, with (none) when nothing was excluded, so the user sees the rule's decision rather than inferring it from what survived.

Ask for approval

Use AskUserQuestion exactly once:

  • Question: "This prompt will be sent to Codex research."
  • Options:
    1. "Approve — execute as shown"
    2. "Send the excluded lines too" — offer this only when something was excluded
    3. "Needs changes"
    4. "Cancel"

Handle the response

  • Approve → proceed to Phase 2 with the current PROMPT_FILE.
  • Send the excluded lines too → fold the excluded text back into the topic, rewrite PROMPT_FILE the same way as below, then re-display and re-ask. The user asked for it, so it travels — but they see the prompt it produced before it runs.
  • Needs changes → the user will describe what to change (e.g., topic rewording, adding/removing XML blocks, changing research framing). Rerun the prompt call with the updated content — it rewrites PROMPT_FILE and, in document mode, re-appends the document — then re-display and re-ask. No loop limit.
  • Cancel → codex-report.sh clean the RUN_DIR (as in Phase 5, without --keep-inputs — no payload exists yet), stop execution.

Phase 2: Invoke

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" launch "<literal PROMPT_FILE path>" "<literal RUN_DIR path>" \
  <flags from the "Run flags:" line, if the apply step printed one>

It prints JOB_ID=<id>. Remember the literal JOB_ID.


Phase 3: Wait

Call with the Bash tool's timeout set to 300000: each call blocks up to 4 minutes, and the default Bash timeout is 2. A call the Bash tool cuts off does not stop the job — call again, and count it toward the cap. Cap at 6 calls (24 minutes).

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" wait "<literal JOB_ID>" "<literal RUN_DIR path>"
  • STATUS=completed → Phase 4, with the printed RESULT_FILE
  • STATUS=failed or cancelled → categorize the ERROR= line per §6, save failure report
  • WAIT_TIMED_OUT=true → call again
  • 6 calls exhausted → wait-timeout (§6). Show JOB_ID, suggest /codex-status <JOB_ID>.

The script keeps the companion's output in files under RUN_DIR. Do not print them: Phase 4 hands RESULT_FILE to the script and to the Verifier, and printing it here would put Codex's answer in your context before anyone independent had looked at it.

Full error table: ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §6.


Phase 4: Verify

You still do not read the Codex result or the context document. A fresh Verifier subagent reads them, judges the findings, opens the sources they cite, and raises what the research left out. Your job here is plumbing: run the script, launch the Verifier, collect what comes back.

Step 1 — Prepare the payload

# Drop the --document line for a topic-only run — there is no document to name,
# and the approved prompt file is the scope the Verifier judges coverage against.
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" payload "${CLAUDE_PLUGIN_DATA}" \
  --mode doc --skill research \
  --prompt-file "<literal PROMPT_FILE path>" \
  --result-file "<literal RESULT_FILE path>" \
  --document "<literal USER_DOC path>"

The payload holds those paths and nothing else — no document text, no Codex text. PROMPT_FILE is the scope the user approved in Phase 1.5, which is what makes "Codex did not cover this" a checkable claim rather than an opinion about the topic.

ExitMeaningWhat you do
0payload writtenStep 2
2bad usage, unreadable input, or git failureShow stderr verbatim and stop.

Step 2 — Launch the Verifier

Make one Agent call:

  • subagent_type: codex-advisor:verifier, which starts a fresh subagent. Not fork — a fork inherits this entire conversation, and with it every framing you and the user built while assembling the topic.
  • prompt: the group-all.json path and nothing else. A PreToolUse hook replaces the prompt with that file's hash-checked contents, so any sentence you write around the path is discarded before the Verifier sees it.

When the Agent call fails, the result is Unverified — Verifier call failed. Do not judge the findings in its place and do not retry on your own. A retry the user asks for is a new Agent call on the same payload path: a Verifier already running or finished takes no follow-up message.

Step 3 — Collect the verdicts

The Verifier returns one JSON object, {"verdicts": [...]}. It split Codex's prose into items itself and ided them item-1, item-2, …, and any part of the approved scope the result does not cover comes back as missing-1, missing-2, … labelled Confirmed or Refuted. Those are the gaps — report them, do not fill them.

Read ${CLAUDE_PLUGIN_ROOT}/references/evaluation.md and follow its Reporting section — match verdicts to ids and count. missing-N items stay out of the agreement rate and get their own line: they are not verdicts on anything Codex claimed.

A verdict you disagree with stays exactly as the Verifier wrote it; your disagreement goes beneath it on one Author note (main session): line. Rewriting the verdict would make you the judge again.


Phase 5: Report + save

Success: save with codex-report.sh save … research using the standard format in references/evaluation.md — the topic (and document path, if any) as the scope, Codex's output verbatim, the verdicts by classification, and the summary counts. The missing-N items go under Gaps in the Codex result, which is where a reader looks to see what the research did not answer.

Failure: save with codex-report.sh save … research --failed with the §6 error category, stderr, and topic/document path.

Clean up temp files using the literal path from Phase 1, keeping the payload's inputs:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-report.sh" clean "${CLAUDE_PLUGIN_DATA}" "<literal RUN_DIR path>" --keep-inputs

Leave WORK where it is. A re-verification the user asks for needs that payload file and its manifest, plus the prompt.txt and result.json the payload points at, and the hook refuses a payload it cannot hash-check.


Gotchas

  • Codex can hallucinate sources and facts — the Verifier opens the URLs and sections it cites, which is why the payload gives paths and the Verifier has WebFetch.
  • The context document never enters your context, in any phase. Phase 1 redirects it into the prompt file and Phase 4 passes its path to the Verifier.
  • Topic-only mode skips the document append entirely — don't accidentally pass an empty <context_document> tag.
  • prompt --document appends by file redirect inside the script, so stdout stays empty. Reading the doc to stdout defeats the entire point.
  • Gaps are reported, not filled. What Codex left out comes back as missing-N from the Verifier, which judged it against the scope the user approved. Writing your own supplement here would put the author back in the analysis.
  • Temp file paths must come from Phase 1 stdout. Re-inject literal absolute paths for RUN_DIR and PROMPT_FILE; Bash shell variables do not survive across calls.

For the full shared gotchas list, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §10.

Codex Job Result + Stored Review Linking

Thin wrapper around the Official Codex companion's result subcommand. If a codex-advisor review file exists for the same timestamp window, also surface its path so the user can read the classified findings (Agreed / Disputed / Nuanced / False Positive / Uncited).

Phase 1: Fetch companion result

Arguments: pass on only a job id (like task-mf3k2a-x7q1zp, or a unique start of one), quoted. If the user asked in words ("show me the last job"), run with no arguments. The script refuses anything else, because the companion reads a stray word as a job id and fails with No job found.

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-job.sh" result <filtered arguments>

Relay the companion's rendered result verbatim (includes the Codex session ID, making codex resume <session-id> possible).

Phase 2: Find the matching codex-advisor report

Codex-advisor stores reports at ${CLAUDE_PLUGIN_DATA}/reviews/<type>-<YYYYMMDD-HHMMSS>.md. These are separate from companion jobs — a given job may or may not have a matching report depending on which skill launched it.

List the 3 most recent reports; the user can pick the one whose timestamp aligns with the job. Skip the section when the script prints nothing.

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-report.sh" list "${CLAUDE_PLUGIN_DATA}" 3

Append:

## Related codex-advisor reports (most recent)

- review-20260414-102530.md
- rescue-20260414-100112.md
- ...

If the timestamp matches the job you fetched, open that file for Claude's double-check classification. Path: ${CLAUDE_PLUGIN_DATA}/reviews/

Don't claim a specific report belongs to the queried job unless timestamps clearly align — the user decides.

Gotchas

  • The companion's result is authoritative for Codex output. codex-advisor's report adds classification on top but the raw Codex text lives in the companion's store.
  • Session ID enables codex resume. If the companion's output includes a session_id, point that out — the user can continue that Codex thread with codex resume <session-id> outside Claude entirely.

Codex Code Review + Double-Check

You are a translator + executor. The user can type anything — flags, Korean, English, meta-instructions, emoji. Your first job is to figure out intent and produce a clean invocation of the Official Codex plugin's companion. Your second job is to hand what Codex returns to a fresh Verifier subagent and report what it decides. The judging is deliberately not yours.

Execution Contract

This contract overrides default exploration habits. Read it before Phase 1.

PhaseAllowedForbidden
1 ANALYZEcodex-task.sh check-ref, apply-codex-config.pycat, head, tail, git diff, git log -p, git show, git blame, Read, Grep, Glob
2 INVOKEcodex-task.sh review (multi-arg form only — never $ARGUMENTS blob)All source reads
3 WAITcodex-task.sh review-wait loop (≤8 calls, about 30 min), then Read OUT_FILEAll source reads, run_in_background, ps/kill
4 VERIFYcodex-task.sh payload, then Agent (codex-advisor:verifier) per groupReading source; judging or re-judging any finding yourself
5 REPORT + SAVEcodex-report.sh save, codex-report.sh cleanWrite tool for the report

The companion collects the diff and context itself. Your value-add is a verdict reached by someone with no stake in the code, not pre-analysis. The companion's parser turns an unknown flag into focus text (parseArgs in lib/args.mjs), and the built-in review rejects focus text, so the run fails. Phase 1 whitelist catches it first.


Phase 1: Analyze

You are a translator. Use LM intelligence, not regex tables.

Whitelist for this skill: --base <ref>, --scope <auto|working-tree|branch>, --model <slug>, --effort <level>. Nothing else.

--model and --effort go through scripts/apply-codex-config.py, which updates ~/.codex/config.toml before the companion launches — see the Apply block below. Never put --effort on the review command: review has no such flag, so the companion would mix it into the prompt. Why, and when --model does go on the command: references/companion-usage.md §2.

Rules:

  • Meta-instructions addressed to YOU (e.g. "don't analyze first", "in Korean", "quickly", "thoroughly" — often typed in the user's own language) → obey for your own behavior, never forward to the companion.
  • Junk, emoji, trailing punctuation → drop. Strip trailing , . ) from flag values (e.g., --base develop, → base=develop).
  • Focus text detected (any natural-language string not addressed to you and not a whitelisted flag) → use AskUserQuestion to offer the adversarial redirect: "This looks like focus text — use /codex-adversarial <focus> instead? The built-in review rejects focus text." Do NOT pass focus text to the companion.
  • Unknown flag (e.g., --commit, --uncommitted, --wait, --foo) → AskUserQuestion to clarify. Common corrections:
    • --uncommitted → did you mean --scope working-tree?
    • --commit <sha> → did you mean --base <sha>~1 --scope branch?
    • --wait / --background → these are silent no-ops on review; drop.
    • Never pass through. The companion has no safety net.
  • Duplicate flag (e.g., --base develop --base main) → AskUserQuestion which one is intended. Never silently pick last.
  • Ambiguous → AskUserQuestion; if it is unavailable (non-interactive), reply with one AMBIGUOUS: line and run nothing (references/companion-usage.md §9).

Input validation (allowed in Phase 1 — these never load source contents):

# Verify the base ref exists, if provided.
# Replace <literal clean base> with the value you parsed — or skip this
# call entirely if the user gave no --base.
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" check-ref "<literal clean base>"

Apply model/effort (if either flag was provided)

Run this before Phase 2 so the companion sees the new config.toml:

# Empty string for either arg = no change. Values are written as given.
"${CLAUDE_PLUGIN_ROOT}/scripts/apply-codex-config.py" \
  "<literal clean model from Phase 1 or empty>" \
  "<literal clean effort from Phase 1 or empty>" \
  --run-flags model

The script's first stdout line is Model: <before> -> <after> | Effort: <before> -> <after>. Relay its stdout verbatim. If it exits non-zero, relay its stderr and stop — launching Codex anyway would run it on settings the user didn't ask for. A Run flags: line means the project's own .codex/config.toml sets that value and outranks config.toml; add those flags, exactly as printed, to the review command in Phase 2. A Note: line names a project value no flag can override — there is no effort flag for reviews — so say the requested value won't apply in this project. config.toml is global: the change affects every Codex invocation (Official plugin, direct CLI, every codex-advisor skill) until the user changes it again. Say so when anything changed.

If the user passed neither flag, still call the script with two empty strings so the user sees the current values in the same format.

Before Phase 2, also print the Parsed line:

Parsed: base=develop, scope=auto   (meta: "don't analyze first" obeyed)

Order: apply-codex-config.py output first, Parsed line second.

For edge cases (flag conflicts, unusual phrasings, classification details), read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §7.


Phase 2: Invoke (Pattern A — detached review)

Review's companion-side --background / --wait are silent no-ops (handleReviewCommand always calls runForegroundCommand), so the script detaches the companion itself and returns at once.

# Replace <literal ...> with values from Phase 1. Omit the entire --base or
# --scope line if the user provided nothing (companion auto-detects).
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" review "${CLAUDE_PLUGIN_DATA}" review \
  <flags from the "Run flags:" line, if the apply step printed one> \
  --base "<literal clean base from Phase 1>" \
  --scope "<literal clean scope from Phase 1>"

The script refuses any flag outside that list and prints RUN_DIR=, OUT_FILE= and ERR_FILE=. Re-inject the literal paths in every later Bash call — shell variables do not survive across calls.


Phase 3: Wait

Call with the Bash tool's timeout set to 300000: each call blocks up to 4 minutes, and the default Bash timeout is 2. Keep calling in the foreground, in this turn — a background command that finishes starts a new turn, and the allowed-tools grant does not carry over to it. A call the Bash tool cuts off does not stop the review — call again, and count it toward the cap. Cap at 8 calls (about 30 minutes).

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" review-wait "<literal RUN_DIR path>"
  • STATUS=running → call again.
  • STATUS=done → act on the OUTPUT= line:
OUTPUT=Action
jsonRead OUT_FILE, then Phase 4
emptyRead ERR_FILE, categorize per §6 of companion-usage.md, save review-<ts>-failed.md, stop
non-jsonunexpected-format — show ERR_FILE verbatim, abort
  • 8 calls exhausted → wait-timeout (§6). Do NOT cancel; leave the review running and its RUN_DIR in place (skip the Phase 5 clean). Point the user at /codex-status to follow it and /codex-cancel to stop it.

The full error categorization table is in ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §6.


Phase 4: Verify

You do not judge Codex's findings — a fresh subagent does. You have been in this conversation since before the review started, and an author grading a review of their own code is not a review (ADR 0012). Your job in this phase is plumbing: run the script, launch the Verifiers, collect what comes back.

Step 1 — Prepare the payloads

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" payload "${CLAUDE_PLUGIN_DATA}" \
  --skill review --input "<literal OUT_FILE path>" --ref auto

--ref auto turns on the worktree-drift check only for a branch review: that review judged committed code, so its citations should still match HEAD. The wrapper adds the repo root and a fresh payload folder, prints WORK=<path>, and exits with prepare-verifier.py's code.

The script cuts the output into findings, checks that every cited file:line exists, and writes one payload file per group. Its stdout JSON is your view of the findings — you do not re-derive that list by hand, because a list you extracted yourself is a list you have already formed an opinion about.

ExitMeaningWhat you do
0payloads writtenStep 2
3parse_error — Codex's output format changedGo to Phase 5 and report Codex output format changed — no verdicts. No Verifier, no hand-extracted findings.
4no_output — Codex returned nothing to judgeGo to Phase 5 and report Codex returned no output — no verdicts.
2bad usage, unreadable input, or git failureShow stderr verbatim and stop.

Exit 0 with an empty groups list means Codex raised nothing. Report zero findings plus Codex's own summary, and launch no Verifier.

Step 2 — Launch one Verifier per group

For each entry in the script's groups, make one Agent call:

  • subagent_type: codex-advisor:verifier, which starts a fresh subagent. Not fork — a fork inherits this entire conversation, which is exactly the memory the double-check exists to remove.
  • prompt: the group's payload path and nothing else. A PreToolUse hook replaces the prompt with that file's hash-checked contents, so any sentence you write around the path is discarded before the Verifier sees it. There is no hint to pass and no room to pass one.

Launch at most 10 at a time and start the next batch once those return. The session cap is 20 concurrent subagents; the headroom keeps a large review from hitting it.

When an Agent call fails, that group's findings are Unverified — Verifier call failed. Do not judge them in its place and do not retry on your own. If the user asks for a retry, make a new Agent call with the same payload path — a Verifier, running or finished, is never resumed with a follow-up message.

Step 3 — Collect the verdicts

Each Verifier returns one JSON object, {"verdicts": [...]}.

Read ${CLAUDE_PLUGIN_ROOT}/references/evaluation.md and follow its Reporting section: match verdicts to ids, transcribe the script's own labels (missing → False Positive, uncited → Uncited, drift unverifiable → Unverifiable), and count. A non-empty worktree_drift gets the drift line the template shows.

A verdict you disagree with stays exactly as the Verifier wrote it; your disagreement goes beneath it on one Author note (main session): line. Rewriting the verdict would make you the judge again.


Phase 5: Report + save

Success (Codex returned a result): save with codex-report.sh save … review using the standard format in references/evaluation.md — Codex's output verbatim, the verdicts by classification, then the summary counts.

Failure (Codex never produced a result, or Phase 3 hit a failure state): save with codex-report.sh save … review --failed with the §6 error category, the captured stderr, and any partial payload.

Clean up the companion's temp files — the RUN_DIR folder from Phase 2, as a literal path:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-report.sh" clean "${CLAUDE_PLUGIN_DATA}" "<literal RUN_DIR path>"

Leave WORK where it is. A re-verification the user asks for needs those payload files and their manifest, and the hook refuses a payload it cannot hash-check.


Gotchas

  • Focus text on codex-review is fatal at the companion (validateNativeReviewRequest). Offer the adversarial redirect in Phase 1 instead of forwarding.
  • Review always runs in the foreground on the companion side — the companion's --background / --wait are silent no-ops. codex-task.sh review detaches it; review-wait is how this turn outlasts it.

For the full shared gotchas list, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §10.

Codex Setup & Configuration

Preflight check and ~/.codex/config.toml configuration helper for codex-advisor.

Mode Selection

Parse $ARGUMENTS:

InputAction
--status or no argsRun preflight + show current config
--model MODELSet default model in config.toml
--effort LEVELSet reasoning effort in config.toml
Combined flagsApply all settings

Preflight Check

One call finds the Official Codex plugin and asks its companion what is installed and signed in:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-job.sh" setup

If it fails with Official Codex plugin not found, guide the user through the full installation process:

  1. Tell the user to run these commands in order (they must type these themselves since they are interactive CLI commands):
    • /plugin marketplace add openai/codex-plugin-cc — adds the Official Codex marketplace
    • /plugin install codex@openai-codex — installs the plugin from that marketplace
    • /reload-plugins — activates the newly installed plugin
  2. After the user completes the steps, re-run the check to verify.

Do NOT just print the steps and move on. Wait for the user to complete them. Until then, report the CLI and authentication rows as unknown — only the companion checks them.

Otherwise fill the status report from the JSON: codex.available and codex.detail for the CLI, auth.loggedIn and auth.detail for authentication. Relay nextSteps, except the review-gate one — --enable-review-gate belongs to the Official plugin's own /codex:setup and Stop hook, which codex-advisor does not wrap.

Configuration Management

Read current config

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-job.sh" config

Set Model / Effort (--model, --effort)

Both flags are handled by one call. Empty string = no change for that field:

"${CLAUDE_PLUGIN_ROOT}/scripts/apply-codex-config.py" "<model or empty>" "<effort or empty>"

The script's first stdout line is:

Model: <before> -> <after> | Effort: <before> -> <after>

Relay that line verbatim to the user — it shows before/after so they can confirm. If it exits non-zero, relay its stderr instead — the file was left untouched. A Note: line means the current project's own .codex/config.toml sets the same key, which outranks config.toml in that project — relay it.

Model and effort handling

The script writes both values as given and judges neither — Codex owns the list of valid models and effort levels, and it decides at run time. Don't add a validity check here or reintroduce one downstream, and don't teach the script a model alias: any model name we keep goes stale the moment OpenAI ships the next one, and then it calls a working value wrong.

So when a user asks which models or efforts they can use, don't answer from memory — availability is account-scoped and changes. Tell them to run codex and open its /model picker.

The effort value lands on the model_reasoning_effort key (none is the exception — it belongs to plan_mode_reasoning_effort, which this plugin doesn't set). The script edits only the top-level keys (above the first [table] header), preserves everything else (e.g. model_context_window, [projects.*]), follows CODEX_HOME, and writes atomically via a temp file. On Python 3.11+ it parses the file before and after and refuses to write if anything other than the requested keys would change.

If a value looks like an obvious typo, AskUserQuestion beats letting it through — config.toml is global, so a typo follows the user into every later session.

Status Report

## Codex Setup Status

| Item | Status |
|------|--------|
| Codex CLI | `codex.detail` or NOT_INSTALLED |
| Authentication | `auth.detail` or NOT LOGGED IN |
| Official Plugin | OK or NOT_INSTALLED (required) |

## Current Configuration (~/.codex/config.toml)

| Setting | Value |
|---------|-------|
| model | <current or "default (not set)"> |
| model_reasoning_effort | <current or "default (not set)"> |
| web_search | <current or "default (not set)"> |

These defaults apply to ALL Codex commands — both Official plugin and direct CLI.
To change: `/codex-setup --model gpt-5.6-sol --effort high`

Gotchas

  • config.toml applies globally. Changes affect all Codex commands system-wide — Official plugin, direct CLI, and every codex-advisor skill. Warn the user when you mutate it.
  • Other skills set these too. review, adversarial, rescue, verify and research accept --model/--effort and write them through the same script. Review and adversarial have no --effort flag, so config.toml is the only way to set their effort — details in references/companion-usage.md §2.
  • Don't create config.toml if the user only asked for status. apply-codex-config.py "" "" is safe (no-op, prints current values) but avoid it when just reporting — codex-job.sh config is enough.

Codex Job Status + Stored Reviews

Thin wrapper around the Official Codex companion's status subcommand, combined with a listing of review files saved by codex-advisor. Useful when the user has disabled the Official plugin's slash commands but still wants job visibility.

Phase 1: Invoke companion status

Arguments: pass on only a job id (like task-mf3k2a-x7q1zp, or a unique start of one) and the flags in argument-hint, quoting the job id and any flag value. If the user asked in words ("what's running?"), run with no arguments. The script refuses anything else, because the companion reads a stray word as a job id and fails with No job found.

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-job.sh" status <filtered arguments>

Relay the companion's output verbatim. Do NOT reformat — the companion already renders a compact table.

Phase 2: List stored review files

Codex-advisor writes reports to ${CLAUDE_PLUGIN_DATA}/reviews/. Add a short section listing the most recent files so the user can correlate jobs with saved reports:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-report.sh" list "${CLAUDE_PLUGIN_DATA}" 10

Format:

## Recent codex-advisor reports

- review-20260414-102530.md
- rescue-20260414-100112.md
- ...

Location: ${CLAUDE_PLUGIN_DATA}/reviews/

If the script prints nothing, skip the section.

Gotchas

  • Don't reformat the companion's table. Its markdown is already compact; reformatting risks dropping columns.
  • --wait blocks up to --timeout-ms (default 240000 = 4 min). If the user passes --wait on a running job, surface a "blocking for up to N seconds" note so they aren't surprised by the pause.
  • Stored reports and companion jobs are not 1:1. A job that failed before codex-advisor's Phase 5 has no report; a review-<ts>-failed.md corresponds to a companion job that completed with an error. Don't assert matching.

Codex Session Transfer

One-way handoff. Unlike every other codex-advisor skill, there is no double-check phase — once the transfer completes, work continues in Codex outside Claude Code, so there is nothing left here to classify. The wrapper's job is whitelisting, error taxonomy, and disable-parity — not verification.

Phase 1: Analyze

Whitelist for this skill: --source <path>, --json. Nothing else — transfer has no prompt, so there is no focus text or model/effort to route.

  • --source <path> — explicit Claude session .jsonl to import. Optional; when omitted the companion falls back to the CODEX_COMPANION_TRANSCRIPT_PATH env var, which codex-advisor's own SessionStart hook (hooks/session-start.mjs) sets automatically — whether or not the Official plugin itself is enabled.
  • --json — when the user passes this, show them the raw JSON payload in Phase 3 instead of the friendly summary: add --show-json to the script call. This is independent of the --json the script always passes to the companion, which is for our own parsing.
  • Unrecognized token (any other flag, or free-standing text) → AskUserQuestion. Transfer has no positional argument — the companion silently discards anything it doesn't recognize as --source/--cwd/--json (handleTransfer destructures only options, never positionals), so passing it through would do nothing rather than corrupt a prompt. Still don't forward it: ask what the user meant. If it looks like a task description, suggest /codex-rescue instead — transfer moves the whole session, it doesn't run a task.

Phase 2: Invoke

Single synchronous call — no --wait/--background, no Pattern A/B. The companion's own import timeout is 2 minutes (EXTERNAL_AGENT_IMPORT_TIMEOUT_MS in lib/codex.mjs), so give the Bash tool call itself a timeout comfortably above that (e.g. 150000) — a shorter tool-side timeout could kill the process right at the companion's own deadline and mask its real error message.

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-job.sh" transfer

Add --source "<literal path from Phase 1>" if the user supplied one, as its own quoted argument — never interpolated into a larger string — and --show-json if they passed --json. The script prints THREAD_ID= and RESUME_COMMAND= from the companion's JSON (then the raw payload with --show-json), or transfer failed: and the companion's stderr.

Phase 3: Report

  • User did not pass --json: show a short summary. Reproduce resumeCommand verbatim, in its own code span — never paraphrase or reconstruct the codex resume <id> string by hand from the thread ID:

    Session transferred to Codex.
    
    Codex session ID: <THREAD_ID>
    Resume it with: `codex resume <THREAD_ID>`
    
    This Claude Code session is done — the conversation continues in Codex from here.
    
  • User passed --json: show the raw payload the script printed instead.

Errors

Full table: ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §6. Highlights:

  • Could not identify the current Claude transcript... — no env, no --source. This codex-advisor's own SessionStart hook (hooks/session-start.mjs) sets CODEX_COMPANION_TRANSCRIPT_PATH automatically in normal environments regardless of whether the Official plugin is enabled, so this shouldn't fire there. It's expected only where CLAUDE_ENV_FILE itself isn't supported — tell the user to pass --source <path-to-claude-jsonl> directly in that case.
  • Codex can import Claude sessions only from ... — resolved path is outside ~/.claude/projects/. Show the exact path from the error, don't guess a fix.
  • Timed out waiting for Codex to finish importing... — 2-minute internal cap hit. Don't silently retry; if the user retries manually and the same file/content was already imported, the ledger returns the same thread ID instead of a duplicate — that repeat is normal, not a second failure.
  • Unknown subcommand: transfer — the resolved companion is older than 1.0.5 (transfer didn't exist yet). Tell the user to update the Official Codex plugin.
  • Codex CLI is not installed or is missing required runtime support. — the companion resolved fine but the codex binary it shells out to isn't on PATH. Not transfer-specific. Direct to npm install -g @openai/codex, then /codex-setup.

Gotchas

  • No --model/--effort/--wait/--background. None of those concepts apply — transfer carries no prompt and always runs synchronously.
  • Don't reconstruct resumeCommand yourself. Use the exact string the companion returned, even though it's predictable (codex resume <threadId>) — if the companion ever changes its resume invocation, a hand-built string would silently go stale while the field would not.
  • This is the last thing this skill does. Don't offer follow-up double-checks, don't suggest re-running verification — there is no artifact left in Claude's hands to check.

Codex Document Verification + Double-Check

You are a translator + executor. The user wants an independent review of a plan or document. Your first job is to hand the document to Codex without ever loading it into your own context. Your second job is to hand what Codex returns to a fresh Verifier subagent and report the verdict it reaches. The judging is deliberately not yours — if you drafted the document in this session, a blind payload cannot erase that memory, and a fresh reader has no such stake (ADR 0012).

For code review use /codex-review. For research use /codex-research.

Execution Contract

This contract overrides default exploration habits. Read it before Phase 1.

PhaseAllowedForbidden
1 ANALYZEcodex-task.sh check-doc, new-run, prompt (the document goes in by file redirect, never to stdout), apply-codex-config.pycat "$DOC" to stdout, head, tail, Read, Grep, Glob
2 INVOKEcodex-task.sh launch (prompt via stdin pipe)All source / document reads to stdout
3 WAITcodex-task.sh wait loop (≤6 calls, ≤24 min), result written to a fileAll reads, manual polling, ps/kill
4 VERIFYcodex-task.sh payload --mode doc, then Agent (codex-advisor:verifier)Reading the document or the Codex result; judging any finding yourself
5 REPORT + SAVEcodex-report.sh save, codex-report.sh cleanWrite tool for the report

Why the document stays out of context: the Verifier judges against the document, and it can only do that honestly if it comes to the document fresh. Your copy would add nothing and cost the independence. codex-task.sh prompt --document appends the document to the prompt file by redirect, not to stdout, so your context stays clean; Phase 4 passes paths, not text, for the same reason.

codex-task.sh launch refuses any argument that is not a known task flag, so a stray word stops the launch instead of landing in the prompt. Phase 1 still decides what is a flag and what is document text.


Phase 1: Analyze + assemble blind payload

Parse $ARGUMENTS

Whitelist for this skill: --model <slug>, --effort <level> (skill-level, route through apply-codex-config.py; they reach the companion only as the Run flags: it prints). The document path and the focus text are other skill inputs, not companion flags.

Take the document path first, then read whatever text is left as focus — natural-language direction for the review, appended to the <task> focus areas.

  • A single path → the document to verify.
  • Text beside the path → the focus text. Join the non-flag, non-meta tokens with spaces. No focus text is the normal case; the payload is then identical to a run with no focus at all.
  • Multiple paths → AskUserQuestion which one.
  • Meta-instructions addressed to YOU (e.g. "evaluate in Korean", "be strict" — often typed in the user's own language) → obey for your own behavior, never include in the prompt.
  • No args → AskUserQuestion: "What document should I verify?"
  • Unknown flags (e.g., --base, --write, --foo) → AskUserQuestion. verify has no companion flags to forward. --model/--effort are skill-level and route through apply-codex-config.py.

Hypothesis exclusion

Codex is the independent reviewer here, and a reviewer handed a conclusion confirms that conclusion instead of forming its own — anchoring. So the focus text carries where to look and what was observed, and your own read of the document stays behind. Sort what you were given into three kinds:

KindExampleForwarded
Evidence — symptom, observed condition, the request in the user's own words"the rollout section changed twice last week"yes
Focus — an area to examine, no claim attached"security angle", "look hard at the migration sequencing"yes
Hypothesis — a claim about what is wrong, a named section plus a verdict, the answer you expect"§4's rollback plan can't work without a feature flag", "the estimates are the weak part"no

The boundary in one line: a claim about what is wrong makes it a hypothesis; a bare area makes it focus. "Check the rollback plan" points somewhere and claims nothing — focus. "The rollback plan is missing a feature flag" hands over the finding — hypothesis.

Apply this the same way whatever the words' origin — whether the user typed the slash command or you read their intent and invoked this skill yourself. Your own invocations are where hypotheses leak hardest, and a test for "who typed this" would make one sentence behave two ways.

Keep the excluded text. Phase 1.5 shows it, and the user can send it after all in one step.

Resolve the document path

# Input validation only — never load content.
# Replace <literal doc path> with the path parsed from $ARGUMENTS.
# Refuses a missing or empty file; prints DOC_LINES= (size info, not content).
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" check-doc "<literal doc path>"

Assemble the blind payload

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" new-run "${CLAUDE_PLUGIN_DATA}" verify

It refuses when the Official Codex plugin is missing (point the user at /codex-setup), else prints RUN_DIR= and PROMPT_FILE=. Then write the prompt:

# Header via heredoc — no document content yet.
# Block provenance — official gpt-5-4-prompting (prompt-blocks.md), bodies
# adapted to this skill's output schema; re-checked against the 5.6/Astra
# guides 2026-09-11. Re-sync the tag set if the official guide updates.
#   task                        — §Core Wrapper
#   structured_output_contract  — §Output and Format
#   grounding_rules             — §Grounding and Missing Context
#   completeness_contract       — §Follow-through and Completion
# --document appends the file wrapped in <document> by redirect — stdout stays
# empty, context stays clean.
"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" prompt "<literal PROMPT_FILE path>" \
  --document "<literal doc path>" --tag document <<'EOF'
<task>
You are a brutally honest technical reviewer. Review the following document for
material issues that would cause implementation failure.
Focus areas:
- Logical gaps and unstated assumptions
- Missing error handling or edge cases
- Overcomplexity (is there a simpler approach?)
- Feasibility risks (what could go wrong?)
- Missing dependencies or sequencing issues
- Internal contradictions or ambiguous requirements
Pay particular attention to: <literal focus text from Phase 1 — omit this whole line when no focus text was given>
</task>

<structured_output_contract>
Return a structured verdict:
1. PASS or FAIL (with clear reasons)
2. Blocking issues (P1) — must fix before proceeding
3. Recommendations (P2) — non-blocking improvements
Be direct. No compliments. Just the problems.
</structured_output_contract>

<grounding_rules>
Ground every finding in the document text. Cite specific sections.
Do not speculate about issues not evidenced in the document.
</grounding_rules>

<completeness_contract>
Review the entire document before finalizing.
Check for interactions between sections that may create contradictions.
</completeness_contract>
EOF

Apply model/effort (if either flag was provided)

Run after payload assembly, before Phase 2, so the companion sees the new config.toml:

"${CLAUDE_PLUGIN_ROOT}/scripts/apply-codex-config.py" \
  "<literal clean model from Phase 1 or empty>" \
  "<literal clean effort from Phase 1 or empty>" \
  --run-flags model,effort

Relay its stdout verbatim. If it exits non-zero, relay its stderr and stop — launching Codex anyway would run it on settings the user didn't ask for. A Run flags: line means the project's own .codex/config.toml sets that value and outranks config.toml; add those flags, exactly as printed, to the task command in Phase 2. config.toml is global — the change affects every Codex invocation until changed again. Flag that to the user when values changed.

If neither flag was provided, still call with two empty strings so the user sees the current values in the same format.

Before Phase 2, also print the Parsed line:

Parsed: doc="docs/plan.md" (DOC_LINES=247), focus="security angle", payload=PROMPT_FILE

Omit focus= when there was none.

Order: apply-codex-config.py output first, Parsed line second. Remember the literal RUN_DIR, PROMPT_FILE, and USER_DOC paths. They are needed in later phases.

For edge cases, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §7 (ANALYZE rules) and §8 (blind-payload details).


Phase 1.5: Draft Review

Before sending anything to Codex, show the user the verification prompt. The XML payload is already written to PROMPT_FILE (with the document blind-appended). Show the prompt structure — especially the focus areas — so the user can verify or customize the review framing.

Display the draft

Show the XML prompt header (everything except the <document> body) in a fenced code block, plus document info:

**Verification prompt to send to Codex:**

```xml
<task>
You are a brutally honest technical reviewer. Review the following document for
material issues that would cause implementation failure.
Focus areas:
- Logical gaps and unstated assumptions
- Missing error handling or edge cases
- Overcomplexity (is there a simpler approach?)
- Feasibility risks (what could go wrong?)
- Missing dependencies or sequencing issues
- Internal contradictions or ambiguous requirements
Pay particular attention to: security angle
</task>

<structured_output_contract>
Return a structured verdict:
1. PASS or FAIL (with clear reasons)
2. Blocking issues (P1) — must fix before proceeding
3. Recommendations (P2) — non-blocking improvements
Be direct. No compliments. Just the problems.
</structured_output_contract>

<grounding_rules>
Ground every finding in the document text. Cite specific sections.
Do not speculate about issues not evidenced in the document.
</grounding_rules>

<completeness_contract>
Review the entire document before finalizing.
Check for interactions between sections that may create contradictions.
</completeness_contract>
```

Document: `docs/plan.md` (247 lines) — blind-appended as `<document>`
Excluded (hypothesis): "§4's rollback plan can't work without a feature flag"

The XML block must reflect the exact content written to PROMPT_FILE (minus the document body). Do not summarize. The example above shows a run with focus text — drop that line when there was none.

Always print the Excluded (hypothesis): line, with (none) when nothing was excluded, so the user sees the rule's decision rather than inferring it from what survived.

Ask for approval

Use AskUserQuestion exactly once:

  • Question: "This verification prompt will be sent to Codex."
  • Options:
    1. "Approve — execute as shown"
    2. "Send the excluded lines too" — offer this only when something was excluded
    3. "Needs changes"
    4. "Cancel"

Handle the response

  • Approve → proceed to Phase 2 with the current PROMPT_FILE.
  • Send the excluded lines too → append the excluded text to the focus text, rewrite PROMPT_FILE the same way as below, then re-display and re-ask. The user asked for it, so it travels — but they see the prompt it produced before it runs.
  • Needs changes → the user will describe what to change. Common edits: reword focus areas, add domain-specific review criteria, remove irrelevant focus areas, change the review tone. Rerun the prompt call with the updated XML header — it rewrites PROMPT_FILE and re-appends the document blind — then re-display and re-ask. No loop limit.
  • Cancel → codex-report.sh clean the RUN_DIR (as in Phase 5, without --keep-inputs — no payload exists yet), stop execution.

Phase 2: Invoke

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" launch "<literal PROMPT_FILE path>" "<literal RUN_DIR path>" \
  <flags from the "Run flags:" line, if the apply step printed one>

It prints JOB_ID=<id>. Remember the literal JOB_ID for Phase 3-4.


Phase 3: Wait

Call with the Bash tool's timeout set to 300000: each call blocks up to 4 minutes, and the default Bash timeout is 2. A call the Bash tool cuts off does not stop the job — call again, and count it toward the cap. Cap at 6 calls (24 minutes).

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" wait "<literal JOB_ID>" "<literal RUN_DIR path>"
  • STATUS=completed → Phase 4, with the printed RESULT_FILE
  • STATUS=failed or cancelled → categorize the ERROR= line per §6, save failure report
  • WAIT_TIMED_OUT=true → call again
  • 6 calls exhausted → wait-timeout (§6). Show JOB_ID, suggest /codex-status <JOB_ID>.

The script keeps the companion's output in files under RUN_DIR: status and result echo the prompt back, and Codex's answer quotes the document you have been keeping out of context. Do not print those files — Phase 4 hands RESULT_FILE to the script and to the Verifier.

Full error table: ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §6.


Phase 4: Verify

You still do not read the document. A fresh Verifier subagent reads it, reads Codex's result, and decides — you never formed an opinion about this document, and this phase keeps it that way. Your job here is plumbing: run the script, launch the Verifier, collect what comes back.

Step 1 — Prepare the payload

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-task.sh" payload "${CLAUDE_PLUGIN_DATA}" \
  --mode doc --skill verify \
  --prompt-file "<literal PROMPT_FILE path>" \
  --result-file "<literal RESULT_FILE path>" \
  --document "<literal USER_DOC path>"

The payload holds those three paths and nothing else — no document text, no Codex text. That is what lets the Verifier read them first-hand while your context stays clean. There is no citation check here: the input is one document, so a section reference either resolves when the Verifier opens the file or it does not.

ExitMeaningWhat you do
0payload writtenStep 2
2bad usage, unreadable input, or git failureShow stderr verbatim and stop.

Step 2 — Launch the Verifier

Make one Agent call:

  • subagent_type: codex-advisor:verifier, which starts a fresh subagent. Not fork — a fork inherits this entire conversation, including whatever you know about this document.
  • prompt: the group-all.json path and nothing else. A PreToolUse hook replaces the prompt with that file's hash-checked contents, so any sentence you write around the path is discarded before the Verifier sees it.

When the Agent call fails, the result is Unverified — Verifier call failed, and by rule 3 in references/evaluation.md that is a FAIL. Do not judge the result in its place and do not retry on your own. A retry the user asks for is a new Agent call on the same payload path: a Verifier already running or finished takes no follow-up message.

Step 3 — Collect the verdicts

The Verifier returns one JSON object, {"verdicts": [...]}. It split Codex's prose into items itself and ided them item-1, item-2, …, because nobody numbered them in advance.

Read ${CLAUDE_PLUGIN_ROOT}/references/evaluation.md and follow its Reporting section — match verdicts to ids, count, and apply the PASS/FAIL rules there. The verdict is a count, not a judgment of yours.

A verdict you disagree with stays exactly as the Verifier wrote it; your disagreement goes beneath it on one Author note (main session): line. Rewriting the verdict would make you the judge again.


Phase 5: Report + save

Success: save with codex-report.sh save … verify using the standard format in references/evaluation.md — the document path as the scope, Codex's output verbatim, the verdicts by classification, the summary counts, and the PASS/FAIL line that section's rules produce.

Failure: save with codex-report.sh save … verify --failed with the §6 error category, stderr, and the document path.

Clean up temp files using the literal path captured in Phase 1, keeping the payload's inputs:

"${CLAUDE_PLUGIN_ROOT}/scripts/codex-report.sh" clean "${CLAUDE_PLUGIN_DATA}" "<literal RUN_DIR path>" --keep-inputs

Leave WORK where it is. A re-verification the user asks for needs that payload file and its manifest, plus the prompt.txt and result.json the payload points at, and the hook refuses a payload it cannot hash-check.


Gotchas

  • The document never enters your context, in any phase. Phase 1 redirects it into the prompt file and Phase 4 passes its path to the Verifier. Reading it yourself at any point puts an opinion where the independence was.
  • prompt --document appends by file redirect inside the script, so stdout stays empty. Printing the document any other way would dump it into your context.
  • Temp file paths must come from Phase 1 stdout. Bash spawns a fresh shell each call, so re-inject the literal absolute RUN_DIR and PROMPT_FILE paths.

For the full shared gotchas list, read ${CLAUDE_PLUGIN_ROOT}/references/companion-usage.md §10.

Agents 1

Verifier

You judge work produced by one party, about code and documents written by another.

The session that launched you is that other party: it wrote much of the code under review and drafted the documents being checked. An author has something to defend, and no instruction erases that — a verdict free of it can only come from someone who was never in the room. That is the whole reason you exist as a separate agent rather than a step in that session (ADR 0012).

Your input

Your entire prompt is one JSON payload, written by scripts/prepare-verifier.py and delivered by a hook that replaced whatever the launching session typed. Anything it tried to say alongside the path was discarded on the way in, by design. So the payload is the whole of what you were asked — there is no missing briefing to infer, and no hint about the expected answer to read between the lines.

FieldWhat it holds
taskWhich section of the rules file applies to this payload
rulesAbsolute path to references/evaluation.md, where the classifications are defined
modefindings, whole, doc, or diff
items(findings mode) numbered items, each with id, severity, citation, existence, and Codex's finding verbatim
codex_output(whole mode) Codex's answer inline
codex_result(doc mode) path to Codex's answer
prompt_filePath to the request Codex was given — the scope the user approved
documentPath to the document under review, when the call had one
diff(diff mode) path to the diff a Codex write run produced
repo_rootRepository root the citations are relative to

Read rules first and work from the section task names. That section tells you how this mode's items are formed: in findings mode they arrive numbered, and everywhere else you draw the item boundaries and assign the ids yourself.

How to judge

Agreement is earned, and so is a dispute. A finding that reads plausibly is not thereby true, and one that reads overconfident is not thereby wrong. Agree when the evidence you opened shows the problem is real; dispute when the evidence you opened shows it is not — a guard upstream, a type that cannot hold the value, a call that never happens. Either way, evidence names what you actually read.

You have no stake in the finding. Codex produced it, the launching session disagreed or agreed with it in private, and neither of them is your client. False positives are ordinary; so are findings that turn out to be worse than stated. Nothing is riding on the number of each that you return.

Answer with JSON and nothing else. Your verdicts are parsed and placed into a report by machine-shaped aggregation. Prose around the object, a summary line, an apology for uncertainty — each one breaks that, and uncertainty already has a place inside the schema.

When you looked and the evidence within reach did not settle it, that is Unverifiable, and evidence says what was missing — the part of the call chain you could not see, the file the proof would live in, the page that would not open. This matters because the user reads the report to decide what to fix: "I found this wrong" and "I could not tell" lead to different actions, and collapsing them into one skeptical-sounding label hides a gap in the review behind a verdict.

Reading the evidence

Read the cited range, plus enough around it to see what governs that code — the guard above it, the caller, the early return. Grep when the claim is about a symbol: whether it exists, where else it is called, whether the pattern repeats. Stay inside what the payload points at; a citation you invented to justify opening a file is not evidence, and the reach of your tools is exactly the line between Disputed and Unverifiable.

WebFetch opens URLs the material itself cites, and only those — you are checking a source, not researching the topic. When a page will not open, that item is Unverifiable with reason external-source. When a page opens and the summary you get back simply does not mention the claim, that is also Unverifiable: WebFetch answers through a small model that returns what it was asked for, so silence about a claim is not evidence against it.

Your output

One JSON object, one verdict per item:

{"verdicts": [
  {"id": "F1", "classification": "Agreed", "severity": "P1",
   "evidence": "auth.py:42-48 builds the query with an f-string; no parameter binding in the call path from handle_request.",
   "reason": "Injection is reachable from unvalidated input."}
]}
  • id — for findings mode, exactly the ids the payload gave you, all of them and nothing else. For the other modes, the ids you assigned, as the rules section describes, including the extra ids that section allows.
  • classification — Agreed, Disputed, Nuanced, or Unverifiable, defined in the rules file. The extra ids some sections let you raise take their own labels there instead — a gap or an unrequested change is not a claim of Codex's, so answering it with Agreed would read as approving it.
  • severity — the payload's value for that item, copied through, or null when the payload has none and the rules section does not have you derive one. null is the ordinary case for the ids you raised yourself.
  • evidence — what you read, specifically enough that someone can reopen it.
  • reason — one line on why that evidence produces that classification.

PASS/FAIL and the agreement summary are arithmetic over these verdicts, done by the session that aggregates them. Leaving them out is not an omission on your part.

Sponsors

Details

Marketplace
LeeJuOh/claude-code-zero
Source
plugins/codex-advisor
Category
Community

More from LeeJuOh/claude-code-zero

All 12