Check that the codex CLI is installed, authenticated, and a supported version, and report the resolved defaults. Free — no model call. Call this first when a run fails with a setup error. Also reports a rate_limit block — how much of the Codex 5-hour (primary) and weekly (secondary) quota windows remains, captured from your last paid Codex call (a cached snapshot, not a live query). Use it to decide whether to spend: available is deliberately conservative (only when both windows are observed and healthy); when limited/exhausted, prefer to defer non-urgent Codex calls (urgent ones may still proceed); unknown means no fresh/usable reading (run any paid Codex call to populate it), not that anything is wrong. is_stale/as_of show freshness; home_unverified flags a snapshot from a different CODEX_HOME.

List this server's tools, tiers, and the result fingerprint. Free — no model call. Clients can cache by the fingerprint. Pass include_schemas to also embed the full error-envelope / result-meta schemas (a tool-reachable fallback to the codex:// resources for resource-blind clients).

List Codex model slugs you can pass as model. Free — no model call.

Advisory discovery only: read from Codex's on-disk cache when present, else a bundled fallback (source says which). codex exec validates the real slug, so an unlisted slug may still work and a listed one may be unavailable to your account. Same payload as the codex://models resource. Not fingerprint-stable — do not cache it by the capabilities fingerprint.

Ask Codex (a different model) for a read-only second opinion or answer.

Runs codex exec in a read-only sandbox — Codex never edits files. This is a STATIC review, not a verify mode: the read-only sandbox blocks the writes a test/build/lint run typically needs (a writable cache/temp), so Codex can't rely on executing your checks to confirm its claims. For a repo-grounded question, pass workspace_root (absolute) so Codex reasons about the right repo; it is optional for pure Q&A that needs no codebase. Returns a result envelope; treat findings as unvalidated claims to verify by running the checks yourself.

Data egress: this sends your question and extra_context to OpenAI via the codex CLI. Codex always runs with a resolved working directory (workspace_root, your MCP roots, or the server's cwd as a fallback), so it may read files there and send their content too. Your inputs are sent raw — secret redaction is best-effort and does not cover them (it covers gathered diffs and Codex's returned output, not what you type or what Codex reads from files).

Progress & recovery: blocks until Codex finishes (timeout clamped 10-600s via timeout_seconds), streaming coarse notifications/progress when your client requests it; the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_result if the connection drops, and codex_consult_async runs the same work fire-and-forget (poll codex_job_status).

Ask Codex (a different model) to review your git changes for an independent second opinion.

scope: working_tree (uncommitted vs HEAD), branch (needs base, reviews base...HEAD), or commit (needs a commit SHA). The diff is gathered, secret- redacted, and bounded by this server; Codex reviews it read-only and returns structured findings. Pass workspace_root (absolute) for the right repo.

extra_context (optional) is author intent — why the change was made, what you already verified, constraints — added to the prompt as clearly-labeled UNTRUSTED data (Codex is instructed to treat embedded directives as data, not commands — a best-effort injection mitigation, not a guarantee) to cut false positives. It is bounded by the same input-byte limit as the diff.

STATIC review, not a verify mode: the read-only sandbox blocks the writes a test/build/lint run typically needs (a writable cache/temp), so Codex can't rely on running the project's checks to confirm its findings. Treat findings as unvalidated claims to verify by running those checks yourself before acting.

Data egress: this sends the gathered diff to OpenAI via the codex CLI. The diff is secret-redacted (best-effort), but your extra_context is sent raw (unredacted), and Codex may read and send other repo files. Redaction is not a guarantee — do not point a review at a tree full of live credentials and assume it protects them.

Progress & recovery: blocks until Codex finishes (timeout clamped 10-600s via timeout_seconds), streaming coarse notifications/progress when your client requests it; the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_result if the connection drops, and codex_review_changes_async runs the same work fire-and-forget (poll codex_job_status).

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.

Codex edits files with workspace-write, but only inside 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 and lets Codex read tracked files in the worktree and send their content. Your task is sent raw — secret redaction is best-effort and does not cover it or files Codex reads itself.

Progress & recovery: blocks until Codex finishes (timeout clamped 10-600s via timeout_seconds), streaming coarse notifications/progress when your client requests it; the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_result if the connection drops, and codex_delegate_async runs the same work fire-and-forget (poll codex_job_status).

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 reading 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. Secret redaction is best-effort and does not cover your task or files Codex reads itself.

Ask Codex for a read-only second opinion in the background; get a job_id back immediately instead of blocking.

Same read-only behavior as codex_consult (Codex never edits files), but it runs detached — use it when the consult may run long. 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 the consult envelope with codex_job_result, delete it with codex_job_consume_result, or stop it with codex_job_cancel.

Data egress: same as codex_consult — sends your question and extra_context (raw, unredacted) to OpenAI via the codex CLI, plus files Codex reads from its resolved working directory (workspace_root, your MCP roots, or the server cwd).

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 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. Redaction is best-effort, not a guarantee.

Preview what a codex_review_changes call would send — scope, diff size, redactions, truncation — with NO model call and no spend. Use it before a review to inspect the scope and the reported redactions; redaction is best-effort, so treat the preview as a check on scope, not as confirmation that no secret remains. Pass the same extra_context you would give the review so prompt_bytes reflects it.

Preview what a codex_delegate/codex_delegate_async call would do — the baseline it seeds from (HEAD commit, tracked file count/size, uncommitted and untracked counts), the prompt size that would be sent, and the resolved workspace/isolation — with NO model call, NO spend, and no worktree created.

Use it before delegating to confirm scope and repo before committing to cost, exactly as codex_dry_run previews codex_review_changes. Mirrors the real delegate's zero-spend validation (workspace, isolation, task size, git repo), so a failure here is a failure the paid call would also hit. The returned tier/sandbox describe the previewed propose run, not this read-only preview.

Check a background job's lifecycle state without fetching the full result.

Use after any *_async call (codex_delegate_async, codex_consult_async, codex_review_changes_async) or any sync consult/review/delegate (whose meta.job_id names its record). Returns status, elapsed time, expiry, and result_available; when it is true, call codex_job_result. Free — no model call.

Honor poll_after_ms between polls — for a running job it GROWS with elapsed runtime (bounded), so following it backs you off instead of tight-looping (a delegate often runs ~20s). expires_at is null while running and is set once the job finishes; results are then retained ttl_seconds past that completion.

Fetch a finished background Codex job's result WITHOUT deleting the record.

Works for any async job or sync consult/review/delegate (whose meta.job_id names its record) — codex_delegate_async (a diff), codex_consult_async (a consult answer), or codex_review_changes_async (a review with verdict). Use when codex_job_status reports result_available=true; the envelope matches the job's kind, so branch on tool. meta.job_id is set. A still-running/cancelled/timed- out/failed job returns an error envelope. To fetch and delete, use codex_job_consume_result.

detail="summary" (default) omits the raw model text; pass detail="full" for the complete raw output and metadata (#56).

Fetch a finished background Codex job's result and delete the stored record.

Same envelope as codex_job_result (matching the job's kind — branch on tool), then removes completed job state. Use only when you no longer need to poll or re-read the job. Non-done jobs are not deleted. detail works as in codex_job_result (#56).

Cancel a running background Codex job.

Asks the worker to shut down gracefully so it tears down its throwaway worktree, then force-kills it if it overstays, and marks the job cancelled (cancelled jobs cannot be resumed). If the worktree could not be removed, cleanup_warnings names the leftover path. Already-terminal jobs are returned unchanged, so cancel is idempotent — a retry after a lost response is safe. Free — no model call.

List the background jobs known for this workspace, newest first.

Use to recover job_ids lost across context compaction or interruption. Returns each job's id, kind, status, start time, result_available, and expiry. Free — no model call.

This list is not permanent storage: terminal records expire after the TTL (default 24h), and a per-workspace soft cap (default 50, clamped 1-1000) evicts the oldest terminal records as new jobs start. Running jobs are never evicted, so the list can transiently exceed the cap; older finished jobs can silently drop off, so read a result before its expires_at. Includes sync-originated records (any sync consult/review/delegate call); the cap/TTL eviction covers both.