codex_request
Destructive
Run an OpenAI Codex CLI request synchronously, automatically deferring to a pollable job if needed. Accepts a text prompt or a structured prompt with parts for cache-aware execution.
Instructions
Run an OpenAI Codex CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| oss | No | Codex --oss: use the open-source provider. New sessions only. | |
| color | No | Codex --color: output color mode (always|never|auto). New sessions only. | |
| model | No | Model name or alias (e.g. gpt-5.5, gpt-5.4, latest) | |
| addDir | No | Codex --add-dir <DIR>: additional writable workspace directories. Emitted once per entry on new sessions only; resume inherits the original session's writable-dir policy. Stdio/local callers may pass local paths directly. Remote HTTP/OAuth callers must use relative paths inside a selected registered workspace. Do not call workspace_* tools to fix stdio/local provider path access. | |
| enable | No | Codex --enable <FEATURE> (repeatable): enable a feature for this run (equivalent to -c features.<name>=true). Accepted on resume. | |
| images | No | Codex -i <path>: image attachments. Each path must exist; missing paths fail fast. | |
| prompt | No | Prompt text for Codex (mutually exclusive with promptParts) | |
| search | No | DEPRECATED compatibility input: accepted but ignored because current Codex exec no longer accepts --search. | |
| disable | No | Codex --disable <FEATURE> (repeatable): disable a feature for this run (equivalent to -c features.<name>=false). Accepted on resume. | |
| profile | No | Codex --profile <name>: select a profile from ~/.codex/config.toml. | |
| fullAuto | No | DEPRECATED: prefer `sandboxMode`. Expands to `--sandbox workspace-write`; current Codex no longer accepts approval-policy flags. | |
| worktree | No | Slice λ: run this request inside a dedicated git worktree owned by the gateway. `true` creates a fresh worktree at `<repoRoot>/.worktrees/<uuid>` branched from HEAD. `{ name?, ref? }` lets the caller supply a sanitized name and/or a git ref (default: HEAD). When the request carries a sessionId and the session already has a worktree, that worktree is reused. The gateway spawns the child CLI with `cwd: <worktree-path>` — no `-w`/`--worktree` flag is ever emitted to the underlying CLI. On session_delete or TTL eviction the gateway runs `git worktree remove --force`. Successful responses are prefixed with `[gateway] worktree=<absolute-path>\n` so callers can use the path. NOTE: callers should `.gitignore` the `.worktrees/` directory in their repo (the gateway does NOT auto-gitignore — see slice λ spec Q4). | |
| ephemeral | No | Codex --ephemeral: do not persist the session to disk. | |
| sessionId | No | Codex session UUID to resume via `codex exec resume <ID>`. Must be a real Codex session ID (from `~/.codex/sessions/` or the `codex resume` picker). Gateway-generated `gw-*` IDs are rejected. For a brand-new session no resumable sessionId is returned; continue with resumeLatest:true or a real Codex UUID. | |
| workspace | No | Registered workspace alias for remote HTTP/OAuth provider calls. Do not use this field, workspace_list, or workspace_register_existing_repo as a fallback for stdio/local provider path access; pass workingDir/addDir/includeDirs directly instead. | |
| mcpServers | No | MCP server names for approval tracking (Codex manages its own MCP config) | |
| workingDir | No | Codex -C/--cd <DIR>: working root for this session. Emitted on new sessions only; resume inherits the original session's cwd via CODEX_RESUME_FILTERED_FLAGS. Stdio/local callers may pass local paths directly. Remote HTTP/OAuth callers must use relative paths inside a selected registered workspace. Do not call workspace_* tools to fix stdio/local provider path access. | |
| ignoreRules | No | Codex --ignore-rules: skip project rule files for this run. | |
| promptParts | No | Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking. | |
| sandboxMode | No | Codex --sandbox. Omit = Codex exec built-in default (read-only; cannot write files). Pass workspace-write to let Codex edit files in the working dir, or danger-full-access for unrestricted access. | |
| forceRefresh | No | Bypass dedup and force a fresh CLI run even if a recent identical request exists | |
| outputFormat | No | Codex caller-facing output format. Token/cache usage is recorded in the flight recorder regardless. `text` (default) returns the plain reply; `json` returns the raw `--json` JSONL event stream. | text |
| outputSchema | No | Codex --output-schema. Pass a path (string) or an inline JSON Schema object; object is materialised to a 0o600 temp file under os.tmpdir() and deleted after the run. | |
| resumeLatest | No | Resume the most recent Codex session via `codex exec resume --last`. Ignored if sessionId is set. A brand-new session returns no resumable sessionId; continue with resumeLatest:true or a real Codex UUID. | |
| strictConfig | No | Codex --strict-config: error out when config.toml contains fields not recognized by this Codex version. New sessions only. | |
| correlationId | No | Request trace ID (auto if omitted) | |
| idleTimeoutMs | No | Idle timeout in ms (min 30s, max 1h, omit=CLI default) | |
| localProvider | No | Codex --local-provider: local OSS provider (lmstudio|ollama), used with oss. New sessions only. | |
| approvalPolicy | No | Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy. | |
| askForApproval | No | DEPRECATED compatibility input: accepted but ignored because current Codex no longer accepts --ask-for-approval. | |
| optimizePrompt | No | Optimize prompt before execution | |
| configOverrides | No | Codex -c key=value overrides. Keys: /^[a-zA-Z0-9._]+$/. Values: no CR/LF. | |
| approvalStrategy | No | Approval strategy: legacy (default) lets the provider CLI's own flags decide; mcp_managed routes the run through the gateway approval gate (required for approvalPolicy and approval_list). Under mcp_managed the caller's permissionMode/alwaysApprove may be overridden by the gate. | legacy |
| compressResponse | No | Compress the response display text via the native compressor (default: [compression].enabled in config.toml, off unless opted in). Skipped for structured output. | |
| createNewSession | No | Force a fresh session (no resume) | |
| ignoreUserConfig | No | Codex --ignore-user-config: ignore ~/.codex/config.toml for this run. | |
| optimizeResponse | No | Optimize response output | |
| outputLastMessage | No | Codex -o/--output-last-message <FILE>: write the agent's last message to a file. New sessions only. | |
| useLegacyFullAutoFlag | No | DEPRECATED compatibility input: accepted but ignored because current Codex no longer accepts --full-auto. | |
| dangerouslyBypassHookTrust | No | Codex --dangerously-bypass-hook-trust: run enabled hooks without persisted hook trust for this invocation. DANGEROUS. Explicit opt-in; never defaulted on. | |
| dangerouslyBypassApprovalsAndSandbox | No | Run Codex without approvals/sandbox |