---
name: finalize-with-codex
description: Finalize a git commit by delegating quality gates to Codex. Use when Claude is ready to commit changes that could affect runtime behavior. Codex runs format/lint/compile/tests, makes mechanical repairs, and commits using Claude's pre-authored message. Invoked by Claude automatically per the Universal Commit Policy in ~/.claude/CLAUDE.md.
---

# finalize-with-codex

Orchestrates a quality-gated commit via Codex. Claude authors the commit message; Codex owns formatting, linting, compilation, testing, repairs, and the actual commit.

## Inputs

- `checkout_path` — absolute path to the target git checkout
- `commit_message` — the full commit message Claude has drafted
- `task_summary` — one sentence describing what was done

## Steps

1. **Lock check (advisory):** Check for an existing `codex-finalize.lock` in the checkout's git dir and warn early if found. This check is advisory only — the shell helper's atomic lock acquisition is authoritative.

2. **Write request file:** Use the Write tool to create a JSON file in the scratchpad:
   ```json
   {"commit_message": "...", "task_summary": "..."}
   ```
   Never pass the message or summary as shell arguments — only the file path crosses the shell boundary.

3. **Launch helper:** Run `run-finalizer.sh` using the Bash tool with `run_in_background=true`, passing only two arguments: the checkout path and the request file path.
   ```
   ~/.claude/skills/finalize-with-codex/run-finalizer.sh "$CHECKOUT_PATH" "$REQUEST_FILE"
   ```
   Claude is automatically re-invoked when the process completes — no polling required.

4. **Report result:** When notified, parse `$RUN_DIR` from the `FINALIZE_DONE` line in the notification output (fall back to `FINALIZE_STARTED` if the process crashed before completion). Read `$RUN_DIR/result.json` and report:
   - `committed` — show SHA and message
   - `blocked` — show blocker details and any repairs attempted
   - `failed` — show error and log path (`$RUN_DIR/codex.log`)
   - `inspect` — HEAD advanced but Codex exited abnormally; warn user not to retry without checking `git log` first