codex_review_changes_async
Review git changes asynchronously, returning a job ID to poll for results. Use for long-running reviews to avoid blocking.
Instructions
Review your git changes in the background; get a job_id back immediately.
Same read-only behavior as codex_review_changes (the diff is gathered, secret-
redacted, and bounded, then reviewed read-only), but it runs detached — use it
when the review may run long. The diff is gathered inside the job, so a bad
base/commit comes back as the same structured error with zero spend (a bad
scope is an out-of-enum value rejected by MCP input validation before the job
starts). Starting a job commits to spend. Poll with codex_job_status, read the
review envelope with codex_job_result, delete it after successful read with
codex_job_consume_result, or stop it with codex_job_cancel. Pass
workspace_root (absolute).
Data egress: same as codex_review_changes — sends the secret-redacted diff plus
your raw (unredacted) extra_context to OpenAI via the codex CLI; Codex may also
read other repo files, including the auto-loaded AGENTS.md/.agents/skills/
workspace context. Redaction is best-effort, not a guarantee.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Base git ref for scope='branch'; the review covers base...HEAD. | |
| model | No | Override the Codex model slug for this call; defaults to the server/Codex default when unset. | |
| paths | No | Repo-relative paths to narrow the review ('/' separators, no '..'); omit to review all changes in scope. | |
| scope | No | Which changes to review: 'working_tree' (tracked changes vs HEAD; untracked files follow the `untracked` policy, off by default), 'branch' (needs base), or 'commit' (needs commit). | working_tree |
| commit | No | Commit SHA or ref to review for scope='commit'. | |
| 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). | |
| untracked | No | How working_tree scope treats untracked files: 'explicit_only' (default) includes only those named in `paths`; 'include' reviews all non-ignored untracked files (SENDS their contents to OpenAI — opt-in egress); 'exclude' includes none. Omitted ones are disclosed in `coverage`. Inert for branch/commit scopes. | explicit_only |
| extra_context | No | Optional author intent / background context, added to the prompt as clearly-labeled UNTRUSTED data. Codex is instructed to treat embedded directives as data, not commands — best-effort prompt-injection mitigation, not a guarantee. Don't include live secrets: Codex can read files it's pointed at, and redaction does not cover this field. | |
| 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 |