Codex System

Codex System — Planning, Design & Complex Implementation

Codex CLI handles planning, design, and complex code implementation.

Preflight (SSOT): Update CLIs before each session — claude update && npm install -g @openai/codex@latest. Releases drift frequently (model names, flags, sandbox semantics). Other skills reference this line instead of repeating it. Delegation policy (when to delegate): .claude/rules/codex-delegation.md

Two Roles of Codex

1. Planning & Design

• Architecture design, module composition
• Implementation plan creation (step breakdown, dependency ordering)
• Trade-off evaluation, technology selection
• Code review (quality and correctness analysis)

2. Complex Implementation

• Complex algorithms, optimization
• Debugging with unknown root causes
• Advanced refactoring
• Multi-step implementation tasks

When to Delegate

Delegation policy — when to consult, when NOT to, and trigger criteria — lives in .claude/rules/codex-delegation.md (SSOT). This skill covers how to consult. The other half of "how" is how to verify what came back: root AGENTS.md → Guardrails (Completion Verification) is mandatory for every write-access call, and Verify Before Trusting below is its executable form. A delegated CLI is never trusted on its self-report.

How to Consult

Invoke Codex through the wrapper — .claude/skills/_shared/codex_consult.py — instead of calling codex exec directly. codex exec itself waits for stdin EOF and hangs indefinitely when stdin is left open (e.g. background shells); the wrapper always runs it with stdin closed, so callers never need < /dev/null. It also passes the prompt as a single argv element (no shell, so nested quotes in the prompt body never break it), captures stdout/stderr to timestamped files under .claude/logs/codex/, and reports one JSON result instead of silently discarding stderr.

python3 .claude/skills/_shared/codex_consult.py (--prompt-file PATH | --prompt-stdin) [--label L] [--caller AGENT] [--sandbox {read-only,workspace-write,danger-full-access}] [--model M] [--timeout N] [--cwd DIR] [--project-root DIR] [--skip-git-repo-check] [--config KEY=VALUE]

Consulting a peer CLI instead of Codex. Claude Code and Antigravity go through .claude/skills/_shared/cli_consult.py --cli {claude,antigravity} --prompt-file PATH, unrestricted unless --read-only — which Antigravity refuses, because its headless mode auto-approves every tool call and the restriction cannot be enforced from the caller (--resume SESSION is Claude-only; --cli-arg forwards a native flag; default timeout 900 s; same four exit codes as below). Never shell out to a CLI directly — the wrapper-only rule and the per-callee permission mapping live in root AGENTS.md. Codex's sandbox and --config semantics stay here because they are Codex-specific; everything cross-CLI is in that rule file.

• Write the prompt body (Objective / Constraints / Relevant files / Acceptance checks / Output format) to a file and pass it via --prompt-file; use --prompt-stdin to pipe a short prompt instead. Any path works — the ad-hoc snippets below use mktemp, while skills write to .claude/logs/codex/prompt-{label}.md so the prompt sits next to the response the wrapper writes for it, which is what makes a disappointing answer diagnosable afterwards.
• --sandbox defaults to danger-full-access, matching .codex/config.toml. Pass --sandbox read-only explicitly for planning and review calls — see Sandbox Modes below.
• --model defaults to $CODEX_MODEL, else gpt-5.6-sol. --label is a [a-z0-9-]+ slug used in the log filenames (default consult). --timeout defaults to 600 seconds. --skip-git-repo-check covers the non-Git working directory case — see references/troubleshooting.md.
• --config KEY=VALUE (repeatable) forwards a Codex config override, e.g. --config model_reasoning_effort=low for a cheap question. Keys naming a sandbox or approval setting are refused: --sandbox must stay the single visible statement of what Codex is allowed to touch.
• The wrapper prints exactly one JSON object: {ok, exit_code, model, sandbox, write_access, timed_out, duration_sec, response_file, stderr_file, response_chars, response_head, error}. response_head is only a ~400-char preview — read the file at response_file for the full response, and stderr_file (non-null whenever Codex wrote to stderr) when diagnosing a failure.
• Exit codes: 0 succeeded · 1 bad args or unreadable prompt file · 2 codex not on PATH · 3 codex exited non-zero or timed out.

Subagent Pattern (Recommended)

Task tool parameters:
- subagent_type: "general-purpose-opus"
- run_in_background: true (optional)
- prompt: |
    Consult Codex about: {topic}

    Write the prompt body below to a file, then run the wrapper against it:

    Objective: {single-sentence objective}
    Constraints:
    - {constraint 1}
    Relevant files:
    - {file paths}
    Acceptance checks:
    - {commands}
    Output format:
    ## Analysis
    ## Recommendation
    ## Implementation Plan
    ## Risks
    ## Next Steps

    python3 .claude/skills/_shared/codex_consult.py --prompt-file {prompt_path} --label {short-slug} --sandbox read-only

    Parse the JSON result. ok: true means only that codex exec exited 0 — it is
    not a completion report. Read response_file for the full analysis, and judge
    it yourself: state which claims you verified and which you could not.
    Return CONCISE summary (key recommendation + rationale + what is unverified).

For a write-access subagent call, add the Verify Before Trusting steps to the delegated prompt as well, and require the subagent to return the verify.sh and verify_delegation.py verdicts. A subagent that summarises Codex's self-report without them has not verified anything, and its summary must not be treated as a completion.

Direct Call (short questions, responses up to ~50 lines)

echo "Objective: {brief question}" | python3 .claude/skills/_shared/codex_consult.py --prompt-stdin --label quick-question --sandbox read-only

Having Codex Implement Code

prompt_file="$(mktemp)"
cat > "${prompt_file}" << 'EOF'
Objective: Implement {detailed implementation task}
Constraints:
- Follow existing project conventions
- Keep diffs minimal
Relevant files:
- {file paths}
Acceptance checks:
- {commands}
Output format:
## Changes Made
## Validation
## Remaining Risks
EOF
python3 .claude/skills/_shared/codex_consult.py --prompt-file "${prompt_file}" --label implement --sandbox danger-full-access

The call is not finished here. Continue with the next section.

Verify Before Trusting

Mandatory after every workspace-write / danger-full-access call (Codex or a peer CLI), per root AGENTS.md → Guardrails. ok: true from the wrapper means only that codex exec exited 0; it says nothing about whether the change is correct, complete, or honest.

1. Run the acceptance checks from your own prompt, plus the project gates:

bash .claude/skills/_shared/verify.sh

Exit 0 = overall: "pass". Exit 2 = a gate failed, or no gate ran at all (overall: "no_gates") — a delegated code change must never be accepted with zero checks executed. Exit 1 bad arguments, 3 the log file could not be written. Read log_file for the full output.

2. Collect the Guardrail evidence from the diff, naming the scope the prompt actually authorised:

python3 .claude/skills/_shared/verify_delegation.py --base HEAD \
  --expect-files {file the task was supposed to change} \
  --forbid-outside {directory the task was scoped to}

It reports deletions, placeholders, weakened_tests, out_of_scope_files, missing_expected_files, scope_empty, and the captured diff at diff_file. Exit 0 = nothing actionable and no violated expectation — deletions alone land here, reported but not actionable on their own, and exit 0 is still not an accept. Exit 2 = an actionable finding (placeholders, weakened_tests) or a violated expectation (out_of_scope_files, missing_expected_files, scope_empty). Use --base <pre-delegation ref> when Codex committed its work; the default HEAD covers the usual uncommitted case.

3. Read the diff and decide. verdict is always needs-review and there is no verdict that means "accepted" — deliberately. The pattern list is heuristic (a legitimate test deletion exists, and a TODO in a docstring is not a stub), and only you know what the prompt authorised. Reject the completion when the diff shows any of:

• tests deleted, skipped (@pytest.mark.skip), or weakened (assertions removed or loosened) to make the suite pass;
• exceptions silently swallowed (except: pass or equivalent) to hide failures;
• hard-coded return values substituted for real logic — the one Guardrail item no script screens for, so it is listed under not_automated and only your read of the diff catches it;
• stub or placeholder completions where real logic was requested;
• files changed that the task never mentioned, or unapproved deletions.

4. On failure, follow the re-delegate-once protocol (cli-execution.md (c)): report the specific failures with evidence, re-delegate once with the original prompt plus the failure context appended, and if the second attempt also fails verification, halt and require explicit user approval before proceeding. Never patch over a failed delegation silently.