---
name: codex-host
description: Run the great_cto controlled Codex lifecycle with controller-owned writes, verifier evidence, human gates and optional artifact release.
when_to_use: Use when the user asks Codex to run or inspect a full great_cto pipeline rather than only use an individual skill.
effort: high
allowed-tools: Read, Bash
---

# Controlled Codex host

Use the version-pinned npm entrypoint below. A Codex plugin install loads skills
and MCP configuration, but it does not add the `great-cto` npm binary to `PATH`.
Do not imitate Claude Code hooks or manually chain roles: the controller reads
`shared/pipeline.toml`, persists the cursor and owns every write and gate
transition.

## Preflight

```sh
npx --yes great-cto@3.59.1 codex-host doctor
npx --yes great-cto@3.59.1 codex-host list --dir /absolute/project
```

`doctor.state=blocked` means do not start. Docker may be unavailable when no
checks/release policy is requested; GitHub CLI may be unavailable when the local
adapter is used. The run store must not be group/world accessible.
For mixed-host runs, also require `doctor.checks.claude.state=available`.

## Start

Policies must be operator-owned absolute files outside the worker project.
Allowed paths are explicit controller write boundaries.

```sh
npx --yes great-cto@3.59.1 codex-host start \
  --dir /absolute/project \
  --prompt "the requested outcome" \
  --allow src,tests,docs \
  --checks-policy /absolute/operator/checks.json \
  --release-policy /absolute/operator/release.json
```

Read the returned `status`, `pending` and `release` object. Never treat exit 2 as
success: it means a gate, manual action or blocked evidence requires attention.

Since 3.47.0, independent
graph roles can run on both hosts with
`--routes qa-engineer=claude-code,security-officer=codex` on `start`. The
controller dispatches only a symmetric join pair concurrently, checks both
proposals for overlap, serializes writes and runs the existing verifier and
human gates. The route map is fixed for the run. An interrupted wave must be
inspected; never start replacement workers against an uncertain wave.

## Gates and recovery

Show the operator the exact gate/release summary and wait for explicit approval.
Then pass back the controller-issued token; never synthesize or persist one in a
project file.

```sh
npx --yes great-cto@3.59.1 codex-host approve RUN_UUID --token GATE_TOKEN
npx --yes great-cto@3.59.1 codex-host approve-release RUN_UUID --token RELEASE_TOKEN
npx --yes great-cto@3.59.1 codex-host resume RUN_UUID
```

Use `recover` only after inspecting the recorded reason. Recovery reuses the
same candidate and refuses unknown partial writes. `cancel` revokes unexecuted
approval but does not delete external audit evidence.

## Release boundary

The local and GitHub Release adapters publish immutable artifacts and declare
`activation: none`. They do not deploy traffic. Local rollback means selecting
a previous directory; GitHub rollback is a newly gated superseding release.
Production activation needs a separate adapter and approval contract.

Detailed policy schemas and limitations are in `docs/HOST-CODEX.md`.