Consult Codex in background (paid)
codex_consult_asyncSubmit a read-only coding question to Codex as a background job and get a job ID immediately, so you can poll for results later without blocking.
Instructions
Ask Codex for a read-only second opinion in the background; get a job_id
back immediately instead of blocking.
PAID — this spends Codex quota on every new call; there is no dry-run preview for a consult, so run codex_status (free) first to confirm the CLI is installed and authenticated.
Same read-only behavior as codex_consult (Codex never edits files), but detached —
prefer it for a high-reasoning_effort or broad repo-grounded consult 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 the consult envelope with
codex_job_result/codex_job_consume_result; stop with codex_job_cancel.
Data egress: same as codex_consult — sends your question, extra_context, and
developer_instructions
(raw, unredacted) to OpenAI via the codex CLI. Its resolved working directory
(workspace_root, your MCP roots, or the server cwd) selects where Codex works, not
what it can read.
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. 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Override the Codex model slug for this call; defaults to the server/Codex default when unset. Control characters are rejected, not stripped. | |
| question | Yes | The question or prompt to send Codex (a different model) for a read-only answer. Must be non-blank: empty or whitespace-only is rejected before any model call. | |
| 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). | |
| extra_context | No | Optional author intent/background context, added as clearly-labeled UNTRUSTED prompt data. Redaction does NOT cover it — no live secrets. Full caveats and bounds: codex://params. | |
| 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. | |
| developer_instructions | No | Optional caller stance/focus text for Codex's developer turn, placed BEHIND this server's always-leading framing; omit for no developer override. UNTRUSTED — never build it from workspace content; grants no tools; Codex is instructed, not compelled — verdicts stay its own, and compliance with the rest is best-effort and may be silent. Rides the codex command line and the background-job record on disk — never put secrets here; meta reports only {sha256, bytes}. Stripped; blank = omitted; max 4096 bytes. Full contract: codex://params. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes |