Delegate a coding task (paid)
codex_delegateDelegate coding tasks to Codex in an isolated worktree and receive a reviewable, unapplied diff so you can verify changes before merging.
Instructions
Delegate a coding task to Codex (a different model) in an isolated git worktree, and get back a reviewable diff that is NOT applied to your tree.
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.
Codex edits files with workspace-write in a throwaway worktree seeded from
your current tracked state. The returned diff is Codex's changes;
review it, then apply it yourself if you want it. Requires a git repo with at
least one commit. Pass workspace_root (absolute).
NO NETWORK: workspace-write blocks network egress for commands Codex RUNS in the
sandbox, so the task must be self-contained — it cannot git push/fetch, gh
anything, curl, publish, or install dependencies (those fail inside the sandbox
with a DNS/host-resolution error). Ask only for local code changes; do any network
step yourself afterward. This does NOT mean nothing leaves the machine: the Codex
model call still sends your task 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. The plugin's isolation flags don't suppress any of it.
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.
Your task is sent raw — secret redaction is best-effort and does not cover it or
files Codex reads itself.
Progress & recovery: blocks up to the resolved deadline (timeout_seconds, clamped
10-600s; when omitted, the server-configured value, built-in default 300s). If that deadline
expires the run is terminated and its partial output is not recoverable or resumable, so for a
substantial or multi-file task that may exceed it, prefer codex_delegate_async (a background
job, built-in default 1800s deadline; poll codex_job_status). Coarse notifications/progress
streams while it blocks when your client requests it; some MCP clients background a long call
before the deadline, so timeout_seconds bounds the run, not necessarily the inline wait —
either way the detached run (meta.job_id) is recoverable via
codex_job_list→codex_job_status→codex_job_result.
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. | |
| detail | No | Response verbosity: 'summary' (default) omits the raw model text; 'full' includes it. | summary |
| 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. | |
| timeout_seconds | No | Per-call wall-clock timeout in seconds, clamped to 10..600 (out-of-range values are coerced, not rejected). Defaults to the server's configured timeout. | |
| 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 |