Delegate in background (paid)
codex_delegate_asyncSubmit a coding task to run in the background, get a job ID instantly, and retrieve a reviewable diff later without blocking or timeout losing partial work.
Instructions
Delegate a coding task to Codex in the background and get a job_id back
immediately (does not block on the run).
PAID — this spends Codex quota on every new call; use codex_delegate_dry_run or codex_status (both free) first if you only need to check scope or readiness.
Same propose-tier behavior as codex_delegate — Codex works in a throwaway git
worktree and the result carries a reviewable diff that is NOT applied — but
detached; prefer it for a substantial or multi-file implementation task that can exceed the
synchronous deadline (built-in default 300s), since a sync run whose deadline expires loses
its partial work (this job's own deadline is separately configured, built-in default 1800s).
Starting a job commits to spend (it runs to completion or its wall-clock deadline even if
you never poll). Poll codex_job_status; read/consume with
codex_job_result/codex_job_consume_result; stop with codex_job_cancel. Requires a git
repo with at least one commit; pass workspace_root (absolute).
NO NETWORK: like codex_delegate, this runs under workspace-write, which blocks
network egress for commands Codex RUNS in the sandbox — the task must be
self-contained (no push/fetch/gh/curl/publish/dependency install; those fail with
a DNS/host-resolution error in the sandbox). This does NOT mean nothing leaves the
machine: the Codex model call still sends your task (raw) to OpenAI. The worktree
does not bound Codex's writes: codex's workspace-write sandbox also lets commands
write the OS temp roots (/tmp and $TMPDIR) by default. Temp-root writes are neither
captured in the returned diff nor cleaned up.
Codex can read files outside the workspace — up to everything the OS user running it can
read — and send them to OpenAI. The sandbox bounds writes, not reads, so no choice of
workspace is a read boundary. Codex auto-loads the resolved
workspace's AGENTS.md and, in a repository, ancestor AGENTS.md files through its root,
plus a user-global $CODEX_HOME/AGENTS.override.md, else $CODEX_HOME/AGENTS.md; it
discovers skills in
the workspace's .agents/skills/ and user-global $CODEX_HOME/skills/ (default
~/.codex/skills/), reachable from outside the workspace. For delegate, that workspace is
the worktree; scrubbing it
doesn't exclude $CODEX_HOME/skills/. A skill's name and description arrive up
front; selecting one makes the model read its body, which can reach OpenAI even if
your inputs never mention it. Secret redaction is best-effort and
does not cover your task or files Codex reads itself.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | The coding task for Codex to implement inside a throwaway git worktree; the resulting diff is returned for review, not applied to your tree. Must be non-blank: empty or whitespace-only is rejected before any model call. | |
| model | No | Override the Codex model slug for this call; defaults to the server/Codex default when unset. Control characters are rejected, not stripped. | |
| isolation | No | Codex config isolation: 'inherit' | 'ignore-config' | 'ignore-rules'. Defaults to the server's configured value (built-in 'inherit'; `codex_status` reports the resolved one). | |
| workspace_root | No | Absolute path to the target repo root — pass it (or an MCP root) to target the intended repo; otherwise the call falls back to the server's own cwd and sets meta.workspace_warning. On an active call it selects where Codex works, not what it can read — it is not a read boundary. | |
| idempotency_key | No | Optional dedup key scoped to THIS tool + workspace. Same key + same args replays the prior result with no new spend; different args are refused (idempotency_conflict). Sync and _async are separate tools and never share a key. Omit for none; retention is bounded. Lifecycle: codex://params. | |
| reasoning_effort | No | Override the Codex reasoning effort for this call (a model_reasoning_effort override); omit or pass null for the server default (CODEX_IN_CLAUDE_REASONING_EFFORT) or Codex's own resolution. An open, per-model string the backend validates at run time — commonly minimal|low|medium|high|xhigh; codex_models lists each model's advertised set (advisory). Rejection and bounds detail: codex://params. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes |