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

npx --yes great-cto@3.29.1 codex-host doctor
npx --yes great-cto@3.29.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.

Start

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

npx --yes great-cto@3.29.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.

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.

npx --yes great-cto@3.29.1 codex-host approve RUN_UUID --token GATE_TOKEN
npx --yes great-cto@3.29.1 codex-host approve-release RUN_UUID --token RELEASE_TOKEN
npx --yes great-cto@3.29.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.