codex_submit_task
Queue a durable Codex write operation and return an operationId for tracking. Supports chat, execution, and thread operations with retry-safe submission.
Instructions
Queue a durable Codex write operation and return operationId immediately. For project-scoped work, pass project_id from codex_list_projects.projectId; project name or project path are accepted aliases and MCP stores the canonical projectId. Always pass client_request_id and poll codex_get_operation_status.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation_type | Yes | ||
| client_request_id | No | Stable retry idempotency key. If omitted, MCP creates a new operation and relies on prompt deduplication to prevent active duplicate turns. | |
| agent_id | No | Optional orchestrator/agent id used by the central worker scheduler for per-agent limits. | |
| resource_keys | No | Optional write-scope keys. Disjoint keys allow parallel workspace-write/danger-full-access turns in the same project. | |
| priority | No | normal | |
| estimated_cost_class | No | normal | |
| thread_mode | No | Explicit thread intent. Defaults to new_thread for start_chat and continue_thread for send_message/execute_plan. | |
| dedup_policy | No | Controls prompt duplicate handling without changing client_request_id idempotency. | |
| allow_historical_continuation | No | Opt-in only. Allows fuzzy duplicate matching to continue a completed historical thread. | |
| project_id | No | Project reference for start_chat and other project-scoped operations. Prefer the canonical projectId returned by codex_list_projects; the listed project name or full project path are also accepted and canonicalized before durable writes. | |
| chat_id | No | ||
| thread_id | No | Required for operation_type='steer_turn'. Target thread that owns the active turn. | |
| source_thread_id | No | Required for operation_type='fork_thread'. Source thread to fork from. | |
| expected_turn_id | No | Required for operation_type='steer_turn'. Active turn id precondition passed to Codex app-server. | |
| workflow_id | No | ||
| message | No | Required for all operation types except fork_thread. For fork_thread, omit it for fork-only or provide it to start the first turn in the forked thread. | |
| input_items | No | Optional image inputs appended to the text message for operation types that start a new turn. Supports image URL and localImage file path items only. | |
| title | No | ||
| cwd | No | ||
| model | No | ||
| fork_config | No | ||
| ephemeral | No | ||
| output_schema | No | Optional JSON Schema passed to app-server outputSchema for this turn final assistant message. | |
| collaboration_mode | No | ||
| approval_policy | No | on-request | |
| sandbox | No | read-only | |
| force | No | ||
| timeout_seconds | No | ||
| first_message_max_chars | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| error | No | ||
| agentGuidance | No | ||
| agentGuidanceText | No | ||
| recoveryAttemptState | No |