mcp-codex-worker 0.1.21 → 0.1.23

package/dist/src/task/task-state.d.ts

@@ -56,6 +56,7 @@ export interface TaskState {
     prompt: string;
     cwd: string;
     model?: string;
+    effort?: 'low' | 'medium' | 'high' | 'xhigh';
     sessionId?: string;
     operationId?: string;
     createdAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-codex-worker",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "MCP server bridge for Codex app-server",
   "type": "module",
   "main": "dist/src/index.js",

package/src/app.ts

@@ -23,6 +23,7 @@ import {
   renderVerboseLog,
 } from './mcp/resource-renderers.js';
 import { validateResponseAgainstCapabilities } from './execution/provider-capabilities.js';
+import { parseReasoning, type ParsedReasoning } from './services/reasoning-options.js';
 // Persistence utilities — re-exported for external use; not called directly in this module.
 import { saveState, loadState, persistenceDir, applyRecovery } from './task/task-persistence.js';
 
@@ -195,6 +196,14 @@ export class CodexWorkerApp {
     const provider = input.provider ?? 'codex';
     const taskType = input.task_type ?? 'coder';
 
+    // Split `gpt-5.4(effort)` into model id + reasoning effort level. The
+    // two travel as separate fields through the adapter chain so Codex can
+    // receive them as `model` + `reasoningEffort`/`effort`.
+    let parsedReasoning: ParsedReasoning | undefined;
+    if (input.reasoning !== undefined) {
+      parsedReasoning = parseReasoning(input.reasoning);
+    }
+
     // 1. Create the task
     const createInput: Parameters<TaskManager['createTask']>[0] = {
       prompt: input.prompt,
@@ -202,7 +211,10 @@ export class CodexWorkerApp {
       provider,
       taskType,
     };
-    if (input.model !== undefined) createInput.model = input.model;
+    if (parsedReasoning !== undefined) {
+      createInput.model = parsedReasoning.model;
+      createInput.effort = parsedReasoning.effort;
+    }
     if (input.timeout_ms !== undefined) createInput.timeoutMs = input.timeout_ms;
     if (input.labels !== undefined) createInput.labels = input.labels;
     if (input.depends_on !== undefined) createInput.dependsOn = input.depends_on;
@@ -227,7 +239,10 @@ export class CodexWorkerApp {
       cwd: input.cwd ?? process.cwd(),
       timeout: input.timeout_ms ?? 0,
     };
-    if (input.model !== undefined) spawnOptions.model = input.model;
+    if (parsedReasoning !== undefined) {
+      spawnOptions.model = parsedReasoning.model;
+      spawnOptions.effort = parsedReasoning.effort;
+    }
 
     // 5. Dispatch asynchronously (don't block MCP response)
     setImmediate(() => {
@@ -352,8 +367,12 @@ export class CodexWorkerApp {
       }
     }
 
-    // Dequeue the pending question
-    const question = handle.dequeuePendingQuestion();
+    // Peek at the head of the pending question queue — do NOT dequeue yet.
+    // We only remove it after the response is successfully forwarded to
+    // Codex, so a transient client crash leaves the question in place for
+    // the orchestrator to retry.
+    const questions = handle.getPendingQuestions();
+    const question = questions[0];
     if (!question) {
       throw new Error(`No pending question for task ${taskId}`);
     }
@@ -387,8 +406,11 @@ export class CodexWorkerApp {
         break;
     }
 
-    // Forward the response to the runtime using the question's requestId
+    // Forward the response to Codex. Only dequeue the question AFTER this
+    // succeeds — if it throws (client crash, process exit), the question
+    // stays in the queue so the orchestrator can retry.
     await this.runtime.respondToServerRequest(question.requestId, payload);
+    handle.dequeuePendingQuestion();
 
     // If queue is now empty and task was WAITING_ANSWER, resume tracking
     // The adapter's executeSession will continue automatically
@@ -417,13 +439,21 @@ export class CodexWorkerApp {
       throw new Error(`Task ${taskId} is in terminal status: ${task.status}`);
     }
 
+    // Parse `gpt-5.4(effort)` → { model, effort } so the runtime can forward
+    // them as separate fields. Fall back to the task's stored values when
+    // the caller did not override reasoning for this follow-up turn.
+    const parsed = input.reasoning ? parseReasoning(input.reasoning) : undefined;
+    const turnModel = parsed?.model ?? task.model;
+    const turnEffort = parsed?.effort ?? task.effort;
+
     // Start a new turn on the existing thread
     const built = await this.runtime.buildTurnStartParams({
       threadId: task.sessionId,
       userInput: input.message,
-      model: input.model,
+      model: turnModel,
+      effort: turnEffort,
     });
-    await this.runtime.ensureThreadLoaded(task.sessionId, input.model);
+    await this.runtime.ensureThreadLoaded(task.sessionId, turnModel, turnEffort);
     const bridged = await this.runtime.requestWithBridge('turn/start', built.params, {
       threadId: task.sessionId,
     });

package/src/execution/base-adapter.ts

@@ -20,6 +20,7 @@ export interface ProviderSpawnOptions {
   cwd: string;
   timeout: number;
   model?: string;
+  effort?: 'low' | 'medium' | 'high' | 'xhigh';
 }
 
 /**

package/src/execution/codex-adapter.ts

@@ -67,11 +67,21 @@ export class CodexAdapter extends BaseProviderAdapter {
   ): Promise<void> {
     const runtime = this.getRuntime();
     let detachPauseFlow: (() => void) | undefined;
+    let removeExitListener: (() => void) | undefined;
+
+    // Clean up listeners only once, regardless of which path triggers it.
+    const cleanup = () => {
+      detachPauseFlow?.();
+      detachPauseFlow = undefined;
+      removeExitListener?.();
+      removeExitListener = undefined;
+    };
 
     try {
       // 1. Create a new thread
       const { params: threadParams } = await runtime.buildThreadStartParams({
         model: options.model,
+        effort: options.effort,
         cwd: options.cwd,
       });
       const threadResult = await runtime.request('thread/start', threadParams) as {
@@ -92,11 +102,24 @@ export class CodexAdapter extends BaseProviderAdapter {
         .getCurrentClient();
       detachPauseFlow = attachPauseFlow(client, handle, threadId);
 
+      // 3b. Listen for app-server crashes. If the process exits while the
+      //     task is paused (WAITING_ANSWER), mark it failed so the
+      //     orchestrator doesn't wait on a ghost.
+      const onExit = () => {
+        if (handle.isAlive()) {
+          handle.markFailed('Codex app-server process exited unexpectedly');
+        }
+        cleanup();
+      };
+      client.on('exit', onExit);
+      removeExitListener = () => client.off('exit', onExit);
+
       // 4. Build turn params and start the turn via bridged request
       const { params: turnParams } = await runtime.buildTurnStartParams({
         threadId,
         userInput: prompt,
         model: options.model,
+        effort: options.effort,
       });
       const bridgeResult = await runtime.requestWithBridge(
         'turn/start',
@@ -107,13 +130,15 @@ export class CodexAdapter extends BaseProviderAdapter {
       // 5. Handle bridge result
       if (bridgeResult.status === 'pending_request') {
         // Pause flow already queued the question on the handle and
-        // markInputRequired was called. Nothing more to do here —
-        // the wait-task / answer-task handlers drive the rest.
+        // markInputRequired was called. Keep listeners attached —
+        // they will be cleaned up when the task reaches a terminal
+        // state via message-task, or when the client exits.
         return;
       }
 
       if (bridgeResult.status === 'completed') {
         handle.markCompleted();
+        cleanup();
         return;
       }
 
@@ -131,8 +156,10 @@ export class CodexAdapter extends BaseProviderAdapter {
       } else {
         handle.markFailed(op.error ?? 'Turn failed');
       }
-    } finally {
-      detachPauseFlow?.();
+      cleanup();
+    } catch (err) {
+      cleanup();
+      throw err;
     }
   }
 

package/src/mcp/resource-renderers.ts

@@ -127,7 +127,10 @@ export function renderTaskDetail(task: TaskState): string {
   }
 
   if (task.model) {
-    lines.push(`| **Model** | \`${task.model}\` |`);
+    const reasoningCell = task.effort
+      ? `\`${task.model}(${task.effort})\``
+      : `\`${task.model}\``;
+    lines.push(`| **Reasoning** | ${reasoningCell} |`);
   }
 
   lines.push(`| **Task type** | ${task.taskType} |`);

package/src/mcp/tool-definitions.ts

@@ -1,14 +1,18 @@
 import { z } from 'zod';
 
+import { REASONING_OPTIONS } from '../services/reasoning-options.js';
+
 // ---------------------------------------------------------------------------
 // Unified task tool schemas (provider-agnostic)
 // ---------------------------------------------------------------------------
 
+const reasoningEnum = z.enum(REASONING_OPTIONS);
+
 const spawnTaskSchema = z.object({
   prompt: z.string().min(1),
   task_type: z.enum(['coder', 'planner', 'tester', 'researcher', 'general']).default('coder'),
   provider: z.enum(['codex', 'copilot', 'claude-cli']).optional(),
-  model: z.string().optional(),
+  reasoning: reasoningEnum.optional(),
   cwd: z.string().optional(),
   timeout_ms: z.number().int().min(1000).max(3_600_000).optional(),
   keep_alive: z.number().optional(),
@@ -60,7 +64,7 @@ const respondTaskSchema = z.discriminatedUnion('type', [
 const messageTaskSchema = z.object({
   task_id: z.string().min(1),
   message: z.string().min(1),
-  model: z.string().optional(),
+  reasoning: reasoningEnum.optional(),
 });
 
 const cancelTaskSchema = z.object({
@@ -89,69 +93,94 @@ function objectSchema(
   };
 }
 
+const REASONING_DESCRIPTION = [
+  'Model + reasoning effort for this task. The value is a single literal — the server splits it into a model id and a reasoning-effort level and passes them to Codex separately.',
+  '',
+  'Picking the level:',
+  '- `gpt-5.4(medium)` — default workhorse. Use for most coding, refactors, and focused debugging.',
+  '- `gpt-5.4(high)` — harder tasks: multi-file reasoning, subtle bugs, non-trivial design decisions.',
+  '- `gpt-5.4(xhigh)` — reserved for exceptional deep research, novel architecture work, or problems where you have already tried `high` and it was not enough.',
+  '- `gpt-5.4(low)` — rare; only for trivial mechanical edits where latency matters more than quality.',
+  '',
+  'Omit to use the server default from config.',
+].join('\n');
+
 export function createToolDefinitions(): ToolDefinition[] {
   return [
     {
       name: 'spawn-task',
       description: [
-        'Create and start a provider-agnostic task.',
+        'Create and start a provider-agnostic task, returning a task_id you can track.',
+        '',
+        'Dispatches the prompt to the provider registered for the given `task_type` (Codex, Copilot, Claude CLI) and returns immediately with a task_id. Use `wait-task` to block until the task reaches a terminal state or needs input, `respond-task` to unblock it, and `message-task` to send follow-ups on the same session.',
         '',
-        'Dispatches work to the configured provider (Codex, Copilot, Claude CLI) based on task_type routing.',
-        'Returns immediately with a task_id for tracking. Use wait-task to block until completion or input_required.',
+        'PARALLEL EXECUTION: Spawn multiple tasks in the same message to fan out work — each task runs in its own isolated agent workspace and reports back independently. Prefer parallel spawns over sequential ones whenever the subtasks do not depend on each other.',
         '',
-        'PARALLEL EXECUTION: Spawn multiple tasks simultaneously — each runs in an independent agent workspace.',
-        'After spawning, check wait-task — the agent may need approval or user input before it can proceed.',
+        'AFTER SPAWNING: Always follow up with `wait-task`. The agent may pause almost immediately to request a command/file approval or structured user input; the bridge window surfaces that pending question so you can answer it without polling forever.',
+        '',
+        'WRITING A GOOD PROMPT: Name the exact files, functions, or symbols involved, state the expected behavior or acceptance criteria, and mention anything the agent must NOT touch. Vague prompts produce vague work.',
       ].join('\n'),
       inputSchema: objectSchema({
-        prompt: { type: 'string', minLength: 1, description: 'What the task should do. Be specific — include file paths, function names, and expected behavior.' },
+        prompt: {
+          type: 'string',
+          minLength: 1,
+          description: 'What the task should do. Be specific: include file paths, function or symbol names, the expected outcome, and any constraints. The agent only sees this prompt — treat it as the full brief.',
+        },
         task_type: {
           type: 'string',
           enum: ['coder', 'planner', 'tester', 'researcher', 'general'],
           default: 'coder',
-          description: 'Type of task. Determines provider routing. Default: coder.',
+          description: 'Routing hint that picks a provider and default prompt shape. `coder` for writing/editing code, `planner` for decomposing work, `tester` for writing or running tests, `researcher` for investigation, `general` for anything else. Defaults to `coder`.',
         },
         provider: {
           type: 'string',
           enum: ['codex', 'copilot', 'claude-cli'],
-          description: 'Override automatic provider selection. Optional — defaults to the provider registered for the task_type.',
+          description: 'Force a specific backend instead of the one registered for the `task_type`. Leave unset in almost all cases — only override when you need a particular provider for capability reasons.',
+        },
+        reasoning: {
+          type: 'string',
+          enum: [...REASONING_OPTIONS],
+          description: REASONING_DESCRIPTION,
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute working directory the task runs in. Defaults to the server process cwd; set this when the work is scoped to a specific repo or subfolder.',
         },
-        model: { type: 'string', description: 'Model to use. Omit to use the provider default.' },
-        cwd: { type: 'string', description: 'Working directory for the task. Defaults to server process cwd.' },
         timeout_ms: {
           type: 'integer',
           minimum: 1000,
           maximum: 3600000,
-          description: 'Max execution time in ms. Default varies by provider.',
+          description: 'Hard time limit for the task in milliseconds. The task is marked `timed_out` if it exceeds this. Defaults to the provider default when omitted.',
         },
         keep_alive: {
           type: 'number',
-          description: 'SEP-1686 result retention period in ms. How long the server keeps the result available after completion.',
+          description: 'SEP-1686 retention window (ms). How long the server keeps the completed task result available for follow-up queries after the task finishes.',
         },
         labels: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Arbitrary labels for filtering and grouping tasks.',
+          description: 'Free-form tags for filtering and grouping in the task scoreboard. Purely organizational — they do not affect execution.',
         },
         depends_on: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Task IDs that must complete before this task starts.',
+          description: 'Task IDs that must reach a terminal state before this task is allowed to start. Use this to chain dependent work.',
         },
         developer_instructions: {
           type: 'string',
-          description: 'System-level instructions injected before user messages. Use for constraints, coding style, or scope boundaries.',
+          description: 'System-level instructions injected ahead of the user prompt. Use this for hard constraints (coding style, allowed directories, forbidden actions) rather than folding them into the prompt.',
         },
         context_files: {
           type: 'array',
           items: {
             type: 'object',
             properties: {
-              path: { type: 'string', description: 'File path to include as context.' },
-              description: { type: 'string', description: 'Optional description of why this file is relevant.' },
+              path: { type: 'string', description: 'Absolute path of a file to include as context for the task.' },
+              description: { type: 'string', description: 'Optional note explaining why this file is relevant so the agent knows what to look at.' },
             },
             required: ['path'],
           },
-          description: 'Files to include as context for the task.',
+          description: 'Files to prepend as additional context. Use sparingly — context is not free; prefer pointing at files from the prompt when the agent can open them itself.',
         },
       }, ['prompt']),
       validate: (value) => spawnTaskSchema.parse(value),
@@ -159,27 +188,27 @@ export function createToolDefinitions(): ToolDefinition[] {
     {
       name: 'wait-task',
       description: [
-        'Block until a task reaches a terminal state or requires input.',
+        'Block until a task settles or asks for input. This is how you synchronously track progress after `spawn-task` or `message-task`.',
+        '',
+        'Returns as soon as the task reaches a terminal state (`completed`, `failed`, `cancelled`, `timed_out`) or enters `waiting_answer` because the agent needs an approval or structured input. If `timeout_ms` elapses first, it returns the current status and you decide whether to wait again.',
         '',
-        'Polls the task store internally at poll_interval_ms. Returns when the task completes, fails, is cancelled, or enters input_required.',
-        'If timeout_ms elapses, returns the current status — the caller decides whether to wait again.',
-        'Use after spawn-task to synchronously track task progress.',
+        'PATTERN: loop `wait-task` → if `waiting_answer`, call `respond-task` with the matching question payload → loop back to `wait-task`. Do not busy-poll with short timeouts; give each call enough time to catch meaningful progress.',
       ].join('\n'),
       inputSchema: objectSchema({
-        task_id: { type: 'string', minLength: 1, description: 'ID of the task to wait on.' },
+        task_id: { type: 'string', minLength: 1, description: 'ID of the task to wait on, as returned by `spawn-task`.' },
         timeout_ms: {
           type: 'integer',
           minimum: 1,
           maximum: 300000,
           default: 30000,
-          description: 'Max wait time in ms. Default 30,000 (30 seconds).',
+          description: 'Maximum time to block in milliseconds. Returns early on terminal state or `waiting_answer`. Defaults to 30,000 (30 seconds).',
         },
         poll_interval_ms: {
           type: 'integer',
           minimum: 250,
           maximum: 30000,
           default: 1000,
-          description: 'Internal poll interval in ms. Default 1,000.',
+          description: 'Internal poll interval in milliseconds. Keep the default (1,000) unless you have a specific reason to tune it.',
         },
       }, ['task_id']),
       validate: (value) => waitTaskSchema.parse(value),
@@ -187,49 +216,49 @@ export function createToolDefinitions(): ToolDefinition[] {
     {
       name: 'respond-task',
       description: [
-        'Respond to a paused task that requires input.',
+        'Unblock a task that is in `waiting_answer` because the agent requested input or an approval.',
         '',
-        'The response shape is discriminated by the `type` field, matching the PendingQuestion type from wait-task:',
-        '- user_input: provide answers as Record<string, string>',
-        '- command_approval: accept or reject the command',
-        '- file_approval: accept or reject file changes',
-        '- elicitation: accept or decline, with optional content',
-        '- dynamic_tool: provide result or error string',
+        'The payload shape is discriminated by `type` and must match the pending question surfaced by `wait-task`:',
+        '- `user_input` — reply with `answers` as a map of question id → string.',
+        '- `command_approval` — `decision: "accept" | "reject"` for a proposed shell command.',
+        '- `file_approval` — `decision: "accept" | "reject"` for a proposed file edit.',
+        '- `elicitation` — `action: "accept" | "decline"`, plus optional structured `content` for MCP elicitation prompts.',
+        '- `dynamic_tool` — return a tool call result via `result`, or an `error` string on failure.',
         '',
-        'After responding, the task resumes execution. Use wait-task again to track further progress.',
+        'After responding the task resumes automatically. Follow up with `wait-task` to track the next step.',
       ].join('\n'),
       inputSchema: objectSchema({
-        task_id: { type: 'string', minLength: 1, description: 'ID of the paused task.' },
+        task_id: { type: 'string', minLength: 1, description: 'ID of the paused task. Must currently be in `waiting_answer`.' },
         type: {
           type: 'string',
           enum: ['user_input', 'command_approval', 'file_approval', 'elicitation', 'dynamic_tool'],
-          description: 'Type of response, must match the pending question type.',
+          description: 'Which pending-question variant you are answering. Must match the `type` of the question returned by `wait-task` exactly.',
         },
         answers: {
           type: 'object',
-          description: 'For user_input: map of question keys to answer strings.',
+          description: 'For `user_input`: map of each question id (as returned in the pending question) to the user-facing answer string.',
         },
         decision: {
           type: 'string',
           enum: ['accept', 'reject'],
-          description: 'For command_approval or file_approval: accept or reject.',
+          description: 'For `command_approval` or `file_approval`: whether the agent may run the proposed command / apply the proposed edit.',
         },
         action: {
           type: 'string',
           enum: ['accept', 'decline'],
-          description: 'For elicitation: accept or decline.',
+          description: 'For `elicitation`: accept the MCP server\'s elicitation request or decline it.',
         },
         content: {
           type: 'object',
-          description: 'For elicitation: optional structured content payload.',
+          description: 'For `elicitation`: optional structured payload that satisfies the requested schema when accepting.',
         },
         result: {
           type: 'string',
-          description: 'For dynamic_tool: the tool result string.',
+          description: 'For `dynamic_tool`: the tool call result string returned to the agent.',
         },
         error: {
           type: 'string',
-          description: 'For dynamic_tool: error string if the tool call failed.',
+          description: 'For `dynamic_tool`: error string if the tool call failed. Sets `success=false` on the response.',
         },
       }, ['task_id', 'type']),
       validate: (value) => respondTaskSchema.parse(value),
@@ -237,15 +266,20 @@ export function createToolDefinitions(): ToolDefinition[] {
     {
       name: 'message-task',
       description: [
-        'Send a follow-up message to an existing task.',
+        'Send a follow-up message to an existing task on its original session.',
         '',
-        'If the task is still running, adds a new turn. If idle, resumes the thread first.',
-        'Use to provide additional instructions, ask the agent to refine its work, or continue a completed task.',
+        'Use this to add instructions to a still-running task, ask a completed task to refine or extend its work, or steer the agent after reviewing partial results. If the task is idle, the session is resumed first; if it is actively running, the message is queued as the next turn.',
+        '',
+        'After calling, follow up with `wait-task` exactly like after `spawn-task`.',
       ].join('\n'),
       inputSchema: objectSchema({
-        task_id: { type: 'string', minLength: 1, description: 'ID of the task to message.' },
-        message: { type: 'string', minLength: 1, description: 'Follow-up instruction or question for the agent.' },
-        model: { type: 'string', description: 'Override model for this follow-up turn.' },
+        task_id: { type: 'string', minLength: 1, description: 'ID of the task whose session should receive the follow-up.' },
+        message: { type: 'string', minLength: 1, description: 'The follow-up instruction or question. Be as specific as the original prompt — reference files and expected behavior.' },
+        reasoning: {
+          type: 'string',
+          enum: [...REASONING_OPTIONS],
+          description: `${REASONING_DESCRIPTION}\n\nOverrides the reasoning used for this follow-up turn only.`,
+        },
       }, ['task_id', 'message']),
       validate: (value) => messageTaskSchema.parse(value),
     },
@@ -254,17 +288,15 @@ export function createToolDefinitions(): ToolDefinition[] {
       description: [
         'Cancel one or more running tasks.',
         '',
-        'Accepts a single task_id string or an array of task_id strings for batch cancellation.',
-        'For running tasks, signals the provider to abort execution.',
-        'Tasks already in a terminal state are counted as already_terminal in the response.',
+        'Accepts a single task_id or an array. For each running task, asks the provider to abort execution and marks the task `cancelled`. Tasks already in a terminal state are returned under `already_terminal`; unknown ids are returned under `not_found`. Safe to call on a batch — each id is handled independently.',
       ].join('\n'),
       inputSchema: objectSchema({
         task_id: {
           oneOf: [
             { type: 'string', minLength: 1, description: 'Single task ID to cancel.' },
-            { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1, description: 'Array of task IDs to cancel.' },
+            { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1, description: 'Array of task IDs to cancel in one call.' },
           ],
-          description: 'Task ID or array of task IDs to cancel.',
+          description: 'Task ID or array of task IDs to cancel. Accepts both a single string and an array for convenience.',
         },
       }, ['task_id']),
       validate: (value) => cancelTaskSchema.parse(value),

package/src/services/codex-runtime.ts

@@ -22,6 +22,7 @@ import {
   ProfileManager,
   type CodexProfile,
 } from './profile-manager.js';
+import type { ReasoningEffortLevel } from './reasoning-options.js';
 
 interface RuntimeRequestOptions {
   timeoutMs?: number | undefined;
@@ -299,6 +300,7 @@ export class CodexRuntime {
 
   buildThreadStartParams(input: {
     model?: string | undefined;
+    effort?: ReasoningEffortLevel | undefined;
     cwd?: string | undefined;
     developerInstructions?: string | undefined;
   }): Promise<{ params: Record<string, unknown>; remappedFrom?: string | undefined; }> {
@@ -308,7 +310,7 @@ export class CodexRuntime {
         cwd: input.cwd ?? process.cwd(),
         approvalPolicy: 'on-request',
         sandbox: 'workspace-write',
-        reasoningEffort: 'high',
+        ...(input.effort ? { reasoningEffort: input.effort } : {}),
         developerInstructions: appendFleetDeveloperInstructions(input.developerInstructions),
         experimentalRawEvents: false,
         persistExtendedHistory: false,
@@ -323,6 +325,7 @@ export class CodexRuntime {
   buildThreadResumeParams(input: {
     threadId: string;
     model?: string | undefined;
+    effort?: ReasoningEffortLevel | undefined;
     cwd?: string | undefined;
     developerInstructions?: string | undefined;
   }): Promise<{ params: Record<string, unknown>; remappedFrom?: string | undefined; }> {
@@ -333,7 +336,7 @@ export class CodexRuntime {
         cwd: input.cwd ?? process.cwd(),
         approvalPolicy: 'on-request',
         sandbox: 'workspace-write',
-        reasoningEffort: 'high',
+        ...(input.effort ? { reasoningEffort: input.effort } : {}),
         developerInstructions: appendFleetDeveloperInstructions(input.developerInstructions),
         persistExtendedHistory: false,
       };
@@ -348,11 +351,13 @@ export class CodexRuntime {
     threadId: string;
     userInput: string;
     model?: string | undefined;
+    effort?: ReasoningEffortLevel | undefined;
   }): Promise<{ params: Record<string, unknown>; remappedFrom?: string | undefined; }> {
     return this.resolveModelIfRequested(input.model).then((resolved) => ({
       params: {
         threadId: input.threadId,
         ...(resolved ? { model: resolved.resolvedModel } : {}),
+        ...(input.effort ? { effort: input.effort } : {}),
         input: [{
           type: 'text',
           text: input.userInput,
@@ -407,12 +412,16 @@ export class CodexRuntime {
     return [...this.knownThreadIds].sort();
   }
 
-  async ensureThreadLoaded(threadId: string, model?: string | undefined): Promise<void> {
+  async ensureThreadLoaded(
+    threadId: string,
+    model?: string | undefined,
+    effort?: ReasoningEffortLevel | undefined,
+  ): Promise<void> {
     if (!this.knownThreadIds.has(threadId) || this.loadedThreadIds.has(threadId)) {
       return;
     }
 
-    const built = await this.buildThreadResumeParams({ threadId, model });
+    const built = await this.buildThreadResumeParams({ threadId, model, effort });
     await this.request('thread/resume', built.params);
   }
 

package/src/services/reasoning-options.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Reasoning option parsing
+//
+// The MCP `reasoning` parameter is a hardcoded allow-list of `gpt-5.4` model
+// variants paired with a Codex reasoning-effort level. Everything flowing
+// through the tools is one of the exact strings in REASONING_OPTIONS — we
+// split it into `{ model, effort }` at the boundary so the adapter chain can
+// pass the two fields independently to Codex (`reasoningEffort` on
+// thread/start, `effort` on turn/start).
+// ---------------------------------------------------------------------------
+
+export type ReasoningEffortLevel = 'low' | 'medium' | 'high' | 'xhigh';
+
+/** The only model we expose. Hardcoded — do not add variants without intent. */
+export const ALLOWED_MODEL = 'gpt-5.4';
+
+/**
+ * The full set of accepted `reasoning` values. Order matters for display:
+ * medium/high first (the common cases), xhigh next (exceptional research),
+ * low last (rare, kept for completeness).
+ */
+export const REASONING_OPTIONS = [
+  'gpt-5.4(medium)',
+  'gpt-5.4(high)',
+  'gpt-5.4(xhigh)',
+  'gpt-5.4(low)',
+] as const;
+
+export type ReasoningOption = (typeof REASONING_OPTIONS)[number];
+
+const REASONING_PATTERN = /^(gpt-5\.4)\((low|medium|high|xhigh)\)$/;
+
+export interface ParsedReasoning {
+  model: string;
+  effort: ReasoningEffortLevel;
+}
+
+export function isReasoningOption(value: unknown): value is ReasoningOption {
+  return typeof value === 'string' && (REASONING_OPTIONS as readonly string[]).includes(value);
+}
+
+/**
+ * Parse a `reasoning` value such as `gpt-5.4(high)` into its model id and
+ * reasoning-effort level. Throws on any value not in {@link REASONING_OPTIONS}.
+ */
+export function parseReasoning(value: string): ParsedReasoning {
+  const match = REASONING_PATTERN.exec(value);
+  if (!match) {
+    throw new Error(
+      `Invalid reasoning option "${value}". Allowed: ${REASONING_OPTIONS.join(', ')}`,
+    );
+  }
+  return {
+    model: match[1]!,
+    effort: match[2] as ReasoningEffortLevel,
+  };
+}