Claude opencode Skill

codex-exec

Run one caller-supplied Codex command non-interactively and capture evidence. Triggers: "run Codex headless", "capture Codex evidence".

LLM Mart · 0 points · 14 views 0 listing impressions 0 install-command copies
Download boshu2-agentops-skills_codex-exec-596942d.zip · 5 KB

Install

skills CLI npx skills add https://github.com/boshu2/agentops/tree/main/skills/codex-exec
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install boshu2-agentops@llmmart
Git git clone https://github.com/boshu2/agentops.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole boshu2/agentops collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Codex Exec — one-shot runtime adapter

Run exactly one caller-supplied Codex prompt as one process and capture its result. This skill does not choose work, retry, validate or continue. It worked when the command closes stdin, uses the sandbox the declared effects need, runs under one deadline fixed before the first attempt, and the report names the exit code's meaning instead of calling a timeout a result.

Rules that change the command

  • Sandbox from declared effects. -s read-only for review or analysis, workspace-write only for authorized edits, and network or wider access only when the caller explicitly requires those effects. "In case it needs it" is not a declared effect. -s limits only Codex's shell commands; the user's config.toml still starts its MCP servers. For review and CI add --ignore-user-config (auth still loads), or report the inherited MCP servers as undeclared effects. A permission denial inside the run (EPERM, "Operation not permitted") shows only what the mode blocks, not whether the host or the code would fail. Quote it and list the check under not_as_briefed as sandbox-limited: neither a pass nor a failed check. A host-side observation still stands; a host run is the caller's decision.
  • Persist the transcript a receipt needs. --ephemeral writes no session file under $CODEX_HOME/sessions. A validator whose judgment receipt the caller requires runs without --ephemeral, and the caller copies that run's rollout-*.jsonl into protected evidence storage. Add --ephemeral only when no receipt is required.
  • Close stdin. codex exec reads the prompt from stdin when no prompt argument is given, and appends piped stdin to a prompt argument. A non-TTY run (CI, a script) with an open stdin can wait forever: the stdin hang. Feed the prompt on stdin and let it end, or redirect </dev/null.
  • One deadline, never renewed. Fix one absolute deadline before the first attempt. Each invocation, including any retry the caller decides to make, gets only the time left before that deadline. A retry never gets a fresh budget: a loop that gives each attempt its own new timeout has silently multiplied the caller's bound. A missing, zero, negative or malformed bound prevents launch; an expired deadline stops before dispatch.
  • No retry here. Report a timeout, error or empty output as it is. Another invocation is the caller's decision, under the same deadline.
  • Capped capture, typed exit. Capture output to a file under a byte cap and report the exit status. A timeout is not a result.

Run it

In an AgentOps source checkout, use the guarded library. It enforces the deadline, the combined output cap (10 MiB default), process-group cleanup and echo detection:

# AGENTOPS_ROOT: the agentops source checkout. DEADLINE_EPOCH: absolute Unix
# time fixed once by the caller and reused by every invocation in its scope.
. "$AGENTOPS_ROOT/scripts/lib/codex-exec.sh"
CODEX_EXEC_EXTRA_ARGS=(--ignore-user-config)  # add --ephemeral only when no receipt is required
CODEX_EXEC_DIR="$WORKSPACE" CODEX_EXEC_SANDBOX=read-only \
CODEX_EXEC_PROMPT_FILE="$PROMPT_FILE" CODEX_EXEC_DEADLINE_EPOCH="$DEADLINE_EPOCH" \
CODEX_EXEC_MAX_OUTPUT_BYTES=10485760 CODEX_EXEC_OUT_FILE="$OUTPUT" \
  codex_exec_guarded </dev/null

Outside a Git repository add CODEX_EXEC_SKIP_GIT_CHECK=1; to keep the final message outside the cap, add -o "$LAST" to that array (assigned on its own line).

An installed skill ships no scripts, so scripts/lib/codex-exec.sh is absent outside a source checkout. Run codex exec directly instead, with bash or zsh (flags as of codex-cli 0.163.0; confirm with codex exec --help; add --skip-git-repo-check and -o <file> as above):

case "${DEADLINE_EPOCH:-}" in ''|0*|*[!0-9]*) echo "no valid deadline; not launched" >&2; exit 2;; esac
TO=$(command -v timeout || command -v gtimeout) || { echo "no timeout; not launched" >&2; exit 2; }
remaining=$(( DEADLINE_EPOCH - $(date +%s) - 10 ))  # keep the 10 s KILL grace inside
[ "$remaining" -gt 0 ] || { echo "deadline passed or within 10 s; not launched" >&2; exit 124; }
set -o pipefail  # bash and zsh: $? is the failing stage, not head's
"$TO" -k 10 "$remaining" \
  codex exec --ignore-user-config -C "$WORKSPACE" -s read-only - <"$PROMPT_FILE" 2>&1 \
  | head -c 10485760 >"$OUTPUT"
rc=$?  # 124 timed out, 137 killed after grace, 127 no codex, else codex's status

An output file exactly at the cap was truncated, and its status reflects the closed pipe, not a review. The fallback has no survivor check or echo detection; report both as not enforced.

Exit codes (guarded library)

Exit Meaning
0 Codex completed and produced output
2 precondition: binary missing, bounds invalid or missing, capability unavailable, or cleanup unverified; not a result
122 descendants survived Codex's exit; degraded run
123 capture or prompt-preparation cap reached; partial evidence kept
124 deadline expired, or a clean exit with empty output; a stall, not a result
125 output repeats the prompt; not a result
128+N cancelled by signal N (129 HUP, 130 INT, 143 TERM)
other Codex's own nonzero status, preserved

Reserved codes are runtime evidence, never a semantic verdict. A Codex 124 or 137 returns 124 with the STALL line; a Codex 2, 122, 123, 129, 130 or 143 returns with no codex-exec: stderr line, so check stderr, the capture and elapsed time before reading one as the runner's. Guarded runner internals covers inputs, host requirements, process supervision and the external sandbox wrapper.

Report, then stop

command:  exact argv or library call (prompt by reference)
sandbox:  -s value and the declared effect that needs it
bound:    absolute deadline and seconds remaining at launch
capture:  output path, byte cap, truncated yes/no
exit:     status and its meaning from the table
cleanup:  library result, or "not enforced" for the direct fallback
not_as_briefed: steps the output reports refused or sandbox-limited, quoted | none reported

A Codex validator follows the judgment receipt convention and the model-dispatch recipe: a requested model flag or the model's own description does not prove which model ran.

Files (agentops)
  • references
    • guarded-runner.md 3.8 KB
      Loading…
  • SKILL.md 7.3 KB
    ---
    name: codex-exec
    description: 'Run one prompt through headless Codex and capture the result. Use when: wanting a one-shot `codex exec` run or CI step. Not for batches or retries.'
    skill_api_version: 1
    user-invocable: true
    hexagonal_role: driving-adapter
    practices:
    - pragmatic-programmer
    consumes:
    - codex-command-packet
    produces:
    - codex-run-output
    context_rel:
    - kind: supplier-to
      with: validate
    metadata:
      capabilities: [codex_exec]
      effects: [run_codex_process, sandbox_tiered_workspace_and_network_effects]
      canonical_status: canonical
      disposition: keep_optional_adapter
      tier: orchestration
      dependencies: []
      stability: stable
    output_contract: process exit status and captured Codex output artifact
    ---
    # Codex Exec — one-shot runtime adapter
    
    Run exactly one caller-supplied Codex prompt as one process and capture its
    result. This skill does not choose work, retry, validate or continue. It worked
    when the command closes stdin, uses the sandbox the declared effects need,
    runs under one deadline fixed before the first attempt, and the report names
    the exit code's meaning instead of calling a timeout a result.
    
    ## Rules that change the command
    
    - **Sandbox from declared effects.** `-s read-only` for review or analysis,
      `workspace-write` only for authorized edits, and network or wider access only
      when the caller explicitly requires those effects. "In case it needs it" is
      not a declared effect. `-s` limits only Codex's shell commands; the user's
      `config.toml` still starts its MCP servers. For review and CI add
      `--ignore-user-config` (auth still loads), or report the inherited MCP
      servers as undeclared effects. A permission denial inside the run (`EPERM`,
      "Operation not permitted") shows only what the mode blocks, not whether the
      host or the code would fail. Quote it and list the check under
      `not_as_briefed` as sandbox-limited: neither a pass nor a failed check. A
      host-side observation still stands; a host run is the caller's decision.
    - **Persist the transcript a receipt needs.** `--ephemeral` writes no session
      file under `$CODEX_HOME/sessions`. A validator whose
      [judgment receipt](../validate/references/judgment-receipts.md) the
      caller requires runs without `--ephemeral`, and the caller copies that
      run's `rollout-*.jsonl` into protected evidence storage. Add `--ephemeral`
      only when no receipt is required.
    - **Close stdin.** `codex exec` reads the prompt from stdin when no prompt
      argument is given, and appends piped stdin to a prompt argument. A non-TTY run
      (CI, a script) with an open stdin can wait forever: the **stdin hang**. Feed
      the prompt on stdin and let it end, or redirect `</dev/null`.
    - **One deadline, never renewed.** Fix one absolute deadline before the first
      attempt. Each invocation, including any retry the caller decides to make,
      gets only the time left before that deadline. A retry never gets a fresh
      budget: a loop that gives each attempt its own new timeout has silently
      multiplied the caller's bound. A missing, zero, negative or malformed bound
      prevents launch; an expired deadline stops before dispatch.
    - **No retry here.** Report a timeout, error or empty output as it is. Another
      invocation is the caller's decision, under the same deadline.
    - **Capped capture, typed exit.** Capture output to a file under a byte cap and
      report the exit status. A timeout is not a result.
    
    ## Run it
    
    In an AgentOps source checkout, use the guarded library. It enforces the
    deadline, the combined output cap (10 MiB default), process-group cleanup and
    echo detection:
    
    ```bash
    # AGENTOPS_ROOT: the agentops source checkout. DEADLINE_EPOCH: absolute Unix
    # time fixed once by the caller and reused by every invocation in its scope.
    . "$AGENTOPS_ROOT/scripts/lib/codex-exec.sh"
    CODEX_EXEC_EXTRA_ARGS=(--ignore-user-config)  # add --ephemeral only when no receipt is required
    CODEX_EXEC_DIR="$WORKSPACE" CODEX_EXEC_SANDBOX=read-only \
    CODEX_EXEC_PROMPT_FILE="$PROMPT_FILE" CODEX_EXEC_DEADLINE_EPOCH="$DEADLINE_EPOCH" \
    CODEX_EXEC_MAX_OUTPUT_BYTES=10485760 CODEX_EXEC_OUT_FILE="$OUTPUT" \
      codex_exec_guarded </dev/null
    ```
    
    Outside a Git repository add `CODEX_EXEC_SKIP_GIT_CHECK=1`; to keep the final
    message outside the cap, add `-o "$LAST"` to that array (assigned on its own line).
    
    An installed skill ships no scripts, so `scripts/lib/codex-exec.sh` is absent
    outside a source checkout. Run `codex exec` directly instead, with bash or zsh
    (flags as of codex-cli 0.163.0; confirm with `codex exec --help`; add
    `--skip-git-repo-check` and `-o <file>` as above):
    
    ```bash
    case "${DEADLINE_EPOCH:-}" in ''|0*|*[!0-9]*) echo "no valid deadline; not launched" >&2; exit 2;; esac
    TO=$(command -v timeout || command -v gtimeout) || { echo "no timeout; not launched" >&2; exit 2; }
    remaining=$(( DEADLINE_EPOCH - $(date +%s) - 10 ))  # keep the 10 s KILL grace inside
    [ "$remaining" -gt 0 ] || { echo "deadline passed or within 10 s; not launched" >&2; exit 124; }
    set -o pipefail  # bash and zsh: $? is the failing stage, not head's
    "$TO" -k 10 "$remaining" \
      codex exec --ignore-user-config -C "$WORKSPACE" -s read-only - <"$PROMPT_FILE" 2>&1 \
      | head -c 10485760 >"$OUTPUT"
    rc=$?  # 124 timed out, 137 killed after grace, 127 no codex, else codex's status
    ```
    
    An output file exactly at the cap was truncated, and its status reflects the
    closed pipe, not a review. The fallback has no survivor check or echo
    detection; report both as not enforced.
    
    ## Exit codes (guarded library)
    
    | Exit | Meaning |
    |---|---|
    | 0 | Codex completed and produced output |
    | 2 | precondition: binary missing, bounds invalid or missing, capability unavailable, or cleanup unverified; not a result |
    | 122 | descendants survived Codex's exit; degraded run |
    | 123 | capture or prompt-preparation cap reached; partial evidence kept |
    | 124 | deadline expired, or a clean exit with empty output; a stall, not a result |
    | 125 | output repeats the prompt; not a result |
    | 128+N | cancelled by signal N (129 HUP, 130 INT, 143 TERM) |
    | other | Codex's own nonzero status, preserved |
    
    Reserved codes are runtime evidence, never a semantic verdict. A Codex 124 or
    137 returns 124 with the STALL line; a Codex 2, 122, 123, 129, 130 or 143
    returns with no `codex-exec:` stderr line, so check stderr, the capture and
    elapsed time before reading one as the runner's.
    [Guarded runner internals](references/guarded-runner.md) covers inputs, host
    requirements, process supervision and the external sandbox wrapper.
    
    ## Report, then stop
    
    ```text
    command:  exact argv or library call (prompt by reference)
    sandbox:  -s value and the declared effect that needs it
    bound:    absolute deadline and seconds remaining at launch
    capture:  output path, byte cap, truncated yes/no
    exit:     status and its meaning from the table
    cleanup:  library result, or "not enforced" for the direct fallback
    not_as_briefed: steps the output reports refused or sandbox-limited, quoted | none reported
    ```
    
    A Codex validator follows the
    [judgment receipt convention](../validate/references/judgment-receipts.md)
    and the [model-dispatch recipe](../validate/references/model-dispatch.md#association-before-execution):
    a requested model flag or the model's own description does not prove which
    model ran.
    
    - Use [claude-exec](../claude-exec/SKILL.md) for one headless Claude prompt.
    - Use [agy-native](../agy-native/SKILL.md) when AGY is named.
    - Use [orchestrate](../orchestrate/SKILL.md) for a batch of workers.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.