codex_delegate_async
Trigger a background coding task with Codex. Get a job ID instantly to poll for results, keeping your workflow unblocked.
Instructions
Delegate a coding task to Codex in the background and get a job_id back
immediately (does not block on the run).
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
it runs detached. Starting a job commits to spend (it runs to completion or its
wall-clock deadline even if you never poll). Poll with codex_job_status, read
with codex_job_result, delete after successful read with codex_job_consume_result,
or 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 and lets Codex
read tracked files in the worktree and send their content — including the tracked
AGENTS.md and .agents/skills/ skills, which auto-load in the worktree. 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. | |
| model | No | Override the Codex model slug for this call; defaults to the server/Codex default when unset. | |
| isolation | No | Codex config isolation: 'inherit', 'ignore-config', or 'ignore-rules'. Defaults to the server's configured isolation (built-in default 'inherit'; `codex_status` reports the resolved value). | |
| workspace_root | No | Absolute path to the target repository root. Pass it (or rely on an MCP root) so the call targets the intended repo; otherwise it falls back to the server's own cwd and meta.workspace_warning is set. | |
| idempotency_key | No | Optional client-supplied dedup key, scoped to THIS concrete tool on the same workspace. Reusing it on the same tool with the same arguments replays the existing run instead of starting — and paying for — a duplicate Codex call (a sync call reattaches to the in-flight run and returns its result; an _async call returns the same job_id). The sync and _async variants are DIFFERENT tools and never share a key's run. Reuse with different arguments — including a different timeout_seconds — is refused (idempotency_conflict); a key whose prior result was already consumed/evicted is idempotency_result_unavailable; a still-publishing reservation is idempotency_in_progress (retry). Omit it for the prior no-dedup behavior. A completed result stays replayable while its job record lives (its TTL), subject to consumption or count-eviction; the fail-closed conflict/in-progress window can last longer — up to the job's max runtime + termination grace + TTL. meta.idempotency_replayed=true marks a replayed (unpaid) response. | |
| reasoning_effort | No | Override the Codex reasoning effort for this call (sent as a `model_reasoning_effort` config 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 Codex backend validates at run time — commonly minimal|low|medium|high|xhigh; codex_models lists each model's advertised set (advisory). A backend-rejected value fails as invalid_reasoning_effort; an explicit empty string is sent as-is (and rejected by the backend), never treated as unset. Control characters, surrogates, and values over 128 chars are rejected as invalid_arguments. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes |