---
name: codex-run
description: "Dispara o Codex CLI (codex exec) DENTRO de uma git worktree para implementar um prompt/spec já preparado, com edição autônoma, saída em streaming e captura estruturada; depois AVALIA a entrega (nota 0–10) e PARA para o gate. Use SEMPRE que o usuário disser 'roda o codex na worktree X', 'manda o codex implementar Y', 'executa o codex-prompt/o prompt', 'dispara o Codex' — em QUALQUER projeto. NÃO use para planejar nem para mergear (decisão do dono, após o gate)."
allowed-tools:
  - Bash
  - Read
  - AskUserQuestion
---

# codex-run — disparar o Codex na worktree certa, avaliar a entrega, parar para o gate

Skill **agnóstica** (qualquer repo/projeto) para o passo "rodar o Codex" de um fluxo de delegação: existe uma
**git worktree** com um **prompt/spec** já preparado → esta skill dispara `codex exec` lá dentro (streaming,
não-bloqueante) → **avalia a entrega com nota 0–10** → escala em caso de falha → **para para o gate** (o merge é
decisão do dono). Existe porque rodar o Codex à mão é repetitivo e arrisca: rodar na worktree errada, travar sem
TTY, e esquecer de aferir a qualidade antes de mergear.

> **Dual-use:** executa **edição autônoma** (`--sandbox workspace-write --full-auto`). Confirme a **worktree certa**
> e o **escopo** antes de disparar.

## REGRA (hard) — nunca no thread/checkout principal
`codex-run` **só** roda numa **git worktree dedicada** (off main). **NUNCA** dispare o `codex exec` no
**checkout principal** do repo (a árvore raiz no branch primário, ex.: `~/code/<projeto>` em `main`) — o Codex
edita de forma autônoma e isso corromperia o trabalho ativo / a árvore que o dono usa. Se o diretório alvo for o
checkout principal **ABORTE** (`BLOCKED`) e oriente: crie/uso uma worktree primeiro
(`git worktree add ../<projeto>-<slug> -b <branch> main`). Verificação obrigatória antes de rodar:
`git worktree list` → o alvo é uma worktree secundária (não a marcada como principal) **E** o `cwd` do `codex exec`
é essa worktree.

## Pré-flight (falhar cedo > rodar no lugar errado)
1. `codex --version` responde (CLI + credenciais). Se faltar → `BLOCKED`.
2. `git worktree list` — confirme a worktree alvo e que **não** é o **checkout principal** (a árvore do branch
   primário, ex. `~/code/<projeto>`). O Codex edita ali; rodar no principal corromperia o trabalho ativo.
3. Existe um **prompt/spec** (o que o Codex receberá). Convenções comuns: `.dw/spec/<slug>/codex-prompt.md`
   (dev-workflow), `PROMPT.md`, `TASK.md`, ou um caminho que o dono indicar. **Leia-o** — é o escopo/fence/gate.

## Onde rodar — escolha do VEÍCULO (a thread principal NUNCA roda inline)
A thread principal **orquestra**; a execução vai p/ um destes (ver [[orquestrador-nao-executor]]):
- **Workflow (PREFERIDO)** — quando há pipeline (codex implementa → avalia 0–10 → **gate em fan-out**). Um agente
  de workflow roda o `codex exec` (rede OK, comprovado). Aparece em `/workflows` + paraleliza. Estruture em
  **fases/agentes separados**: `[agente que roda codex]` → `[agentes do gate]`.
- **Agent único (subagent)** — disparo avulso de UM codex, sem fan-out de gate (ou gate à parte). Mais leve;
  background; retorna o relatório. Não aparece em `/workflows`.
- **Bash em background** — só **fallback** (sem harness de workflow/agent). Precisa de rede → sandbox do Bash
  desabilitado p/ o codex alcançar a API.

> **Nesting (importante):** o agente que roda o `codex exec` **não deve spawnar outros subagentes** (limite de
> aninhamento; Workflow aninha só 1 nível). O gate é **outra fase/agente** do workflow — nunca um sub-spawn de
> dentro do agente-codex.

Em qualquer veículo, valem: **REGRA hard** (worktree dedicada), captura detalhada, **nota 0–10 (aceite ≥9)** e STOP-para-gate.

## Protocolo
1. **Resolver alvo.** Worktree + caminho do prompt (do usuário ou inferidos).
2. **Modelo + effort — o parent AVALIA a complexidade e SUGERE/escolhe.** Leia o prompt e dimensione; **proponha**
   modelo+effort com um one-liner de racional; o dono confirma ou sobrescreve; se ele disser "escolhe você",
   **decida** pela heurística.
   - Modelos (forte→leve): `gpt-5.5` · `gpt-5.3-codex` · `gpt-5.4` · `gpt-5.3-codex-spark` · `gpt-5.4-mini`.
     Effort: `low`·`medium`·`high`·`xhigh`.
   - Sinais: nº de tasks; amplitude do fence; superfície sensível (auth/segurança/tenant/migration/financeiro);
     "fundação/redesign/arquitetural" × "fix mecânico/typo/docs"; E2E/secure-audit no gate.
   - Heurística: **Trivial** → leve + `low/medium`; **Padrão** (<10 tasks, 1 área) → `gpt-5.3-codex`/`gpt-5.4` +
     `medium/high`; **Complexa/sensível** (fundação, multi-pacote, segurança) → `gpt-5.5` + `high/xhigh`.
     Comece **um degrau abaixo do teto** e escale se falhar (ver Escalonamento).
3. **Disparar (implementação — padrão).** Streaming (`--json`) p/ acompanhar sem travar; `-o` captura o relatório
   final; rode **em background** (não bloquear o parent):
   ```bash
   cd <WORKTREE> && codex exec --skip-git-repo-check \
     -m <MODEL> --config model_reasoning_effort="<EFFORT>" \
     --sandbox workspace-write --full-auto --json \
     -o <OUT_DIR>/codex-last-message.md \
     "$(cat <PROMPT_PATH>)" </dev/null \
     > <OUT_DIR>/codex-stream.log 2>&1     # <-- log de streaming durável (trilha de auditoria)
   ```
   - `</dev/null` SEMPRE (sem TTY trava). `--json` = eventos parseáveis em streaming; **não** suprima tudo com
     `2>/dev/null` por padrão. `<OUT_DIR>`: dir de spec do projeto (ex.: `.dw/spec/<slug>/QA/`) ou um temp.
   - **LOG DE STREAMING = TRILHA DE AUDITORIA (sempre capture):** redirecione o stdout do `--json` p/ um arquivo
     durável (`> <OUT_DIR>/codex-stream.log 2>&1`). Esse JSONL grava **progressivamente, ao vivo, TUDO** o que o
     codex faz: cada `command_execution` (comando shell rodado), `item.started/completed`, `agent_message`
     (raciocínio + respostas do codex), tool-calls, e o `turn.completed` final (com `usage`/tokens). O `-o`
     captura só a **mensagem final**; o **stream captura o PERCURSO inteiro** — é a auditoria do que o codex
     realmente fez.
   - **DURABILIDADE (crítico p/ "auditar depois"):** o stream-log tem que viver num lugar que **sobreviva ao
     `git worktree remove`**. Se ficar no `QA/` da worktree, o cleanup pós-merge **apaga** e a auditoria some.
     Escreva num dir **fora da worktree** — ex.: `<REPO_PRINCIPAL>/.dw/codex-audit/<slug>-<run>.log` (gitignore)
     ou `~/.claude/codex-audit/<slug>-<run>.log` — **OU** `cp` o stream-log + o `-o` p/ fora **antes** de remover
     a worktree. O relatório `-o` enxuto pode até ser commitado na spec (sobrevive no git); o JSONL bruto é grande,
     mantenha no dir de auditoria durável (não commitar). **Ler/auditar depois:**
     - comandos rodados: `grep -oE '"command":"[^"]*"' <stream-log>`
     - raciocínio/respostas do codex: `grep '"type":"agent_message"' <stream-log>`
     - tokens: `grep -oE '"usage":\{[^}]*\}' <stream-log> | tail -1`
     - transcript legível: extraia `agent_message` + `command` na ordem do arquivo.
   - **Detectar "TERMINOU" (NUNCA por `pgrep` com o caminho da worktree no padrão):** o sinal de pronto é
     `{"type":"turn.completed"}` no stream-log **+** a worktree com commit/relatório (`git -C <worktree> log`,
     `-o` preenchido). Um `pgrep -f "<worktree-path>"` (ou `-f "<...>/codex-last-message"`) **AUTO-CASA com o
     próprio comando que você roda** (o caminho está no argv do grep) → falso "rodando" que pode segurar uma
     entrega **PRONTA por horas** (e um *waiter* `until ! pgrep ...` com esse padrão **nunca termina**, pois
     se auto-vê vivo). Em background (`run_in_background`/Workflow), a **notificação de conclusão** é o sinal.
     Se precisar mesmo de pgrep, restrinja a `pgrep -af "codex exec"` e filtre o `/proc/<pid>/cmdline` — jamais
     `pgrep` do caminho cru. (Lição: o pattern derruba a sessão se usado p/ *matar* subindo a árvore — ver Disciplina.)
   - **GATE PRECISA DE REDE?** O `--sandbox workspace-write` **bloqueia rede** dos comandos shell do codex — então
     `pnpm install`/build/test/E2E falham com `EAI_AGAIN`. Se o codex-prompt manda rodar o gate (install/test/etc.),
     troque por **`--dangerously-bypass-approvals-and-sandbox`** (sem sandbox + sem approvals = full access, com
     rede) para o codex rodar o gate e **se auto-validar**. Justificável porque a **REGRA hard** garante worktree
     isolada (off main). Sem rede no gate, o codex só implementa e reporta `blockers` (aí o gate fica com o parent).
   - **Saída DETALHADA por padrão** (para o parent direcionar o follow-up): passe `--output-schema <schema.json>`
     exigindo um relatório rico — não basta "ok". Schema mínimo:
     ```jsonc
     { "type":"object","required":["summary","tasks","filesChanged","gate","fenceViolations","uncommitted","blockers","nextSteps"],
       "properties":{
         "summary":{"type":"string"},
         "tasks":{"type":"array","items":{"type":"object","required":["id","status","notes"],
           "properties":{"id":{"type":"string"},"status":{"enum":["done","partial","skipped","failed"]},"notes":{"type":"string"}}}},
         "filesChanged":{"type":"array","items":{"type":"string"}},
         "gate":{"type":"object","properties":{"lint":{"type":"string"},"test":{"type":"string"},"build":{"type":"string"},"e2e":{"type":"string"}}},
         "fenceViolations":{"type":"array","items":{"type":"string"}},
         "uncommitted":{"type":"array","items":{"type":"string"}},
         "blockers":{"type":"array","items":{"type":"string"}},
         "nextSteps":{"type":"array","items":{"type":"string"}} } }
     ```
     (Garanta que o `codex-prompt.md` peça "STOP com relatório DETALHADO por task" — schema + prompt se reforçam.)
4. **Modo análise/review (read-only):** sem editar → `--sandbox read-only`, sem `--full-auto`.
5. **Resume** (continuar a sessão anterior na mesma worktree):
   `cd <WORKTREE> && echo "<prompt>" | codex exec --skip-git-repo-check resume --last </dev/null`.

## Avaliação obrigatória — nota 0–10 (SEMPRE)
Ao terminar, o parent **AVALIA a entrega do Codex e dá uma nota de 0 a 10** (10 = conformidade total + entrega
completa). Não pule isto — é o sinal que decide gate × escalonamento. Pontue contra o prompt:
- **Conformidade ao escopo/fence** (fez o pedido; ficou dentro do allowlist).
- **Gate técnico** (lint/test/build/E2E conforme o prompt — verde?).
- **Completude** (todas as tasks/itens entregues).
- **Higiene** (commitado, sem lixo, nada fora do fence, sem deps proibidas).
- **Qualidade/sem regressão**.
**Bar de aceite: nota ≥9** (decisão do dono). Faixas: **≥9** = aceitável (pronto pro gate humano); **6–8** =
`FINDINGS` → **escalar** p/ chegar a ≥9; **<6** = falha → **escalar**. `BLOCKED` se a escada esgotar sem atingir 9.
Sempre mostre a nota + o racional curto por critério.

## Dupla avaliação: auto-gate do Codex (effort MÁX) → re-gate do Claude (compara notas)
O codex **não pode corrigir a própria prova sozinho** — daí duas camadas. O codex se auto-gateia barato (perto do
trabalho) e o **Claude audita independente** e **compara as notas** (pega auto-nota inflada).

1. **Auto-gate do Codex (loop, effort MÁXIMO).** O codex-prompt DEVE instruir: após implementar, **rode o MESMO
   gate** (lint/test/build/E2E/secure-audit conforme o prompt) e **dê uma auto-nota 0–10** pela mesma rubrica;
   **corrija e re-rode enquanto a auto-nota <9 ou o gate não estiver verde**, com **effort máximo** (`xhigh`).
   Pare ao auto-nota ≥9 + gate verde (ou reporte `blockers`). O relatório final traz a **auto-nota + por critério**.
2. **Re-gate do Claude (independente).** Quando o codex declara aprovado, o parent **re-roda o MESMO gate**
   (fan-out, preferir Workflow → `/workflows`) e dá a **própria nota 0–10** — sem confiar na auto-nota.
3. **Comparar + decidir.**
   - **Claude ≥9 e gap pequeno** vs a auto-nota → **PASS** (pronto p/ decisão de merge do dono).
   - **Claude <9** OU **gap grande** (codex superestimou) → o re-gate expôs lacunas → **reexecutar**: devolver os
     gaps ao codex (effort máximo) e repetir 1→2→3 **até convergir** (Claude ≥9 e consistente).
   - **A nota que vale para o aceite é a do CLAUDE** (auditor independente); a auto-nota do codex é sinal +
     detector de inflação. Sempre registre **as duas notas + o gap** no Structured Return.

## Escalonamento gradual em falha
Se a nota ficou baixa / o gate falhou / o Codex não concluiu, **re-rode a MESMA tarefa subindo um degrau** —
gradual, sem desistir no 1º tropeço nem pular pro topo.
- **Escada (1 por vez):** primeiro **effort** `low→medium→high→xhigh`; esgotado, suba o **modelo** um tier e
  volte o effort a `high`. Re-rode e **reavalie a nota**.
- **Continuar × recomeçar:** edições parciais coerentes → `resume --last` (mantém contexto). Worktree
  quebrada/suja → **resete antes** (`git -C <worktree> reset --hard && git clean -fd`) e rode fresco no degrau
  maior — não empilhe erro sobre erro.
- **Parada:** pare ao atingir **nota ≥9** (pronto pro gate) OU ao **esgotar** (modelo mais forte + `xhigh` ainda
  abaixo) → `BLOCKED` com evidência. Anuncie cada degrau; com autonomia, escale sozinho até o teto.

## Saída detalhada → direcionar o trabalho depois
A entrega do Codex tem que ser **detalhada o bastante para o parent (Claude) decidir o próximo passo** — não um
"pronto" opaco. Ao terminar:
- **Leia o `-o` por inteiro** (o relatório estruturado) + varra o stream `--json`; complemente com `git -C
  <worktree> status` e `git diff --stat` para ver o que realmente mudou (não confie só no que o Codex disse).
- **Produza um DIRECIONAMENTO** (handoff para o follow-up com o parent): o que o **gate** deve focar, o que
  **ajustar/refazer**, se **escalar** (nota baixa), o que ficou **fora do fence/uncommitted**, e os **blockers**.
  Esse direcionamento é o que guia o trabalho seguinte — registre-o no Structured Return (Evidence/Artifacts/
  Next Step) e na resposta ao dono.
- Se o relatório do Codex vier raso (sem o detalhe do schema), trate como `FINDINGS` e peça o detalhe (resume) ou
  reconstrua o detalhe a partir do diff antes de seguir.

## Telemetria (tokens + tempo) — sempre reportar
O `codex exec --json` emite, no fim, `{"type":"turn.completed","usage":{...}}` com **tokens**:
`input_tokens`, `cached_input_tokens`, `output_tokens`, `reasoning_output_tokens`. Extraia do stream:
```bash
grep -oE '"usage":\{[^}]*\}' <STREAM_LOG> | tail -1
```
- **Billável efetivo ≈ `(input_tokens − cached_input_tokens) + output_tokens`** — o `input` costuma ser ~95%+
  **cache**; reportar só o bruto engana. Mostre os dois (bruto + efetivo).
- **Wall-clock:** o `turn.completed` **não** traz duração → meça você: envolva o `codex exec` com
  `/usr/bin/time` ou `date +%s` antes/depois (ou aproxime por `stat -c %Y` − `%W/%X` do stream). Reporte em minutos.
- **Nº de comandos:** `grep -c command_execution <STREAM_LOG>` (proxy de esforço).
- Registre tudo no **Structured Return → Telemetria**. Útil p/ custo, escalonamento e comparar fases de um fan-out.

## Disciplina (ao terminar)
- **STOP — não foi mergeado.** O Codex implementou na worktree; **rode o gate** (testes/lint/build + revisão;
  se o projeto usa dev-workflow: `/dw-review` + `/dw-qa` + `/dw-secure-audit`) **antes** de qualquer merge.
- **Merge = decisão explícita do dono.** Nunca automático aqui.
- Sinalize trabalho **uncommitted** ou edição **fora do fence**.
- **Parar/abortar um codex em andamento:** use **`TaskStop <task_id>`** (se foi `run_in_background`/Workflow) OU
  **`git worktree remove --force <worktree>`** (puxa o tapete — o codex fica sem onde escrever e morre). Fallback:
  `kill -9` **só** nos PIDs de `pgrep -af "codex exec"` que casam o tag da worktree no `/proc/<pid>/cmdline`.
  **NUNCA suba a árvore de processos (ppid → ppid…) p/ matar "o supervisor":** o codex em background é **filho da
  própria sessão Claude** (`codex ← claude ← bash ← init`) → matar os ancestrais **derruba a sessão**. Os
  "respawns" aparentes são só os workers node de UM mesmo codex. Ver memória `nunca-tree-walk-kill-codex`.

## Anti-patterns
- Rodar no checkout principal / sem confirmar a worktree — corrompe o trabalho ativo. *(pré-flight 2)*
- Mergear/empurrar dentro da skill — o merge vive fora, após o gate.
- Pular a nota 0–10 — perde-se o sinal de qualidade/escalonamento.
- Suprimir todo o output por padrão (ou não capturar o stream num log) — perde-se a auditoria do que o Codex fez.
- **Detectar "terminou" por `pgrep` do caminho da worktree** — auto-casa com o próprio comando → falso "rodando" que segura entregas prontas. Use `turn.completed` + worktree. *(ver §3)*
- **Matar codex subindo a árvore de PIDs** — derruba a própria sessão Claude. Use `TaskStop`/`worktree remove`. *(ver Disciplina)*
- `--dangerously-bypass-approvals-and-sandbox` — só com pedido explícito + ambiente já isolado.

## Structured Return
- **Status:** `PASS` (rodou, nota ≥9, parou limpo na worktree certa, pronto pro gate) · `FINDINGS` (rodou, nota
  6–8 ou ressalvas: uncommitted/fora-do-fence/parcial) · `BLOCKED` (faltou CLI/credencial/worktree/prompt, ou
  escalonamento esgotado sem atingir 9) · `NOT_APPLICABLE` (sem worktree+prompt → ainda em planejamento).
- **Score:** a **nota do CLAUDE** (0–10 — vale p/ o aceite, bar ≥9) + a **auto-nota do Codex** + o **gap** entre
  elas; racional por critério (conformidade/gate/completude/higiene/qualidade). Gap grande = sinal de auto-nota inflada.
- **Scope:** worktree + branch + prompt usado; modelo + effort + sandbox; degraus de escalonamento percorridos.
- **Evidence:** caminho do `-o`, trecho do stream JSONL, `git status`/diff da worktree pós-run.
- **Artifacts:** arquivos criados/alterados (resumo do diff).
- **Decisions:** modelo/effort e por quê; implementação × read-only; continuar × resetar no retry.
- **Risks:** fora do fence, uncommitted, gate não rodado, dual-use (edição autônoma).
- **Telemetria:** tokens do `turn.completed` (input/cached/output/reasoning + **billável efetivo**) + **wall-clock** + nº de comandos.
- **Next Step:** "rodar o gate na worktree; merge é decisão do dono".

## Notas
- `codex exec` flags-chave: `-m`, `--config model_reasoning_effort=`, `-s/--sandbox {read-only,workspace-write,
  danger-full-access}`, `--full-auto`, `--skip-git-repo-check`, `--json`, `-o/--output-last-message`,
  `--output-schema`, `resume --last`. Testado: codex-cli 0.141.0. Sem dependência de projeto específico.