name: codex-exec\ndescription: 'Run one caller-supplied Codex command non-interactively and capture evidence. Triggers: \"run Codex headless\", \"capture Codex evidence\".'\nskill_api_version: 1\nuser-invocable: false\nhexagonal_role: driving-adapter\npractices:
\nRun exactly one caller-supplied Codex prompt and capture its result. This skill\ndoes not choose work, retry failures, validate by itself, or control continuation.
\nOne prompt, one process, one captured artifact is what makes the run auditable:\nwhen nothing loops, every byte of output traces to exactly one invocation, and\na disagreement about what happened is settled by the artifact.
\nNamed failure mode — stdin hang: a non-TTY run left waiting forever on an\nopen stdin nobody will write to; always pipe the prompt or close the stream.
\nAnti-pattern: granting workspace-write or network access \"in case the prompt\nneeds it\". Corrective: match the sandbox to the declared effects; a review\nprompt runs read-only, full stop.
\n-C.scripts/lib/codex-exec.sh and codex_exec_guarded. Pipe the prompt,\nprovide a prompt file/argument, or close stdin in non-TTY execution.CODEX_EXEC_TIMEOUT as positive finite seconds or inherit an\nabsolute CODEX_EXEC_DEADLINE_EPOCH. There is no fixed ten-minute default:\nwithout an explicit timeout, use the deadline's remaining time; with both,\nthe earlier bound wins, including capability probes and prompt preparation.\nPass the same deadline to successive calls; a new invocation cannot renew\nit. Missing both bounds, or empty, zero, negative or malformed explicit\nvalues, prevents launch. An expired deadline times out before dispatch.CODEX_EXEC_OUT_FILE and optionally separate stderr with\nCODEX_EXEC_STDERR_FILE. CODEX_EXEC_MAX_OUTPUT_BYTES defaults to 10 MiB\n(10485760 bytes) and must be a positive finite integer. It caps stdout and\nstderr combined; file-prompt copies and AGY/local-mlx stdin preparation\neach use the same cap. Capture sinks must be regular files (or /dev/null).\nReviewer workspace writes, including files it writes with -o, are outside\nthis capture cap.The supported host must have /usr/bin/perl with its core POSIX, IOSelect,\nFcntl, and TimeHiRes modules, a monotonic clock, process-group signalling,\nand a resolved timeout/gtimeout supporting --foreground. Missing capability\nfails closed. The embedded adapter mechanism establishes one owned process\ngroup before launching the reviewer. It sends TERM then KILL after 200 ms on\nexpiry, cancellation, excess output, or direct-parent exit; it bounds pipe\ndraining to a further short cleanup window rather than waiting indefinitely\nfor descendants to close inherited pipes. This includes ordinary descendants\nleft by a successful parent and TERM-resistant children. It does not promise\ncleanup of processes that deliberately escape the owned group or session.\nGroup members remaining after direct-parent exit are reported as rep-survivor\n(exit 122): the run remains degraded even when cleanup subsequently succeeds.\nAfter its cleanup window the adapter checks whether the owned group still\nexists. Remaining membership, including zombies it cannot independently reap,\nis reported as CLEANUP-UNVERIFIED (exit 2), never successful cleanup.
CODEX_EXEC_WRAP remains Codex-only: the sealed launch order is wrapper →\nresolved timeout → reviewer, with Codex's sandbox bypass only when the external\nwrapper supplies the sandbox. The capture/cleanup supervisor runs outside that\nsealed launch. No process-wide file-size limit restricts reviewer work products.
Terminal outcomes are explicit: unavailable/invalid limits → 2;\ndescendants left after direct-parent exit → 122;\ncapture/input limit → 123; deadline expiry or empty consumed output →\n124; prompt echo → 125; cancellation → 128 + signal number. Other genuine\nreviewer exit codes are preserved. These reserved codes describe runtime\nevidence, never a semantic verdict. On timeout, cancellation, or excess output,\npartial capture stays in caller-provided files; an adapter-owned output sink is\nstreamed before removal. Failed prompt preparation reports its preserved partial\ninput path. The caller decides whether to launch another invocation.
\n# REVIEW_TIMEOUT_SECONDS is selected by the caller. Alternatively export\n# CODEX_EXEC_DEADLINE_EPOCH once and omit CODEX_EXEC_TIMEOUT below; retain\n# that same absolute deadline for every invocation in its scope.\n. \"$AGENTOPS_ROOT/scripts/lib/codex-exec.sh\"\nCODEX_EXEC_DIR=\"$WORKSPACE\" CODEX_EXEC_SANDBOX=read-only \\\nCODEX_EXEC_PROMPT_ARG=\"$PROMPT\" CODEX_EXEC_TIMEOUT=\"$REVIEW_TIMEOUT_SECONDS\" \\\nCODEX_EXEC_MAX_OUTPUT_BYTES=10485760 CODEX_EXEC_OUT_FILE=\"$OUTPUT\" \\\n codex_exec_guarded </dev/null\nFor a validator, the prompt must name the acceptance digest, exact subject\nmanifest digest, author context ID, evidence, and required checked/not-checked\nreport. The validator context ID must be distinct from the author's before a\nPASS verdict is possible. When the caller elects a cross-model fresh\nvalidator, record model identities per\nthe agent-native model-dispatch recipe and match the sandbox to\ndeclared effects.