Refactor Claude-facing Codex tool surface

Expose native-style task and session tools by default, hide legacy compatibility tools behind CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS, and update docs/tests for the new Claude discovery path.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: xuio

README.md

@@ -14,7 +14,7 @@ full-access Codex work when the user asks for it.
 
 ## Why Use It?
 
-- **Native Claude Code workflow:** Claude gets MCP tools and a plugin skill, so it can decide when to ask Codex without shell glue.
+- **Native Claude Code workflow:** Claude gets a small Task-like MCP surface: `codex_task`, `codex_task_group`, and `codex_session_*`.
 - **Read-only by default:** Codex starts with `--sandbox read-only` and non-interactive approvals.
 - **No daemon:** Claude launches the MCP server over stdio for the active session.
 - **Fast parallel review:** Claude can launch several independent Codex agents with bounded concurrency.
@@ -62,15 +62,15 @@ after `dist/index.js` is rebuilt.
 Ask Codex for a second opinion on the session recovery code. Keep it read-only and return concrete findings with file paths.
 ```
 
-Claude should use the `ask_codex` front door.
+Claude should use `codex_task`.
 
 ### Run Parallel Codex Agents
 
 ```text
 Launch three Codex subagents in parallel: one for API behavior, one for tests, and one for security. Keep all of them read-only.
 ```
 
-Claude should use `ask_codex_parallel` and split the work into independent tasks.
+Claude should use `codex_task_group` and split the work into independent tasks.
 
 ### Use Spark
 
@@ -86,8 +86,8 @@ Claude can pass `model_preset: "spark"` instead of remembering the exact Spark m
 Start a long-running Codex session on this repo, then let me send follow-up prompts into the same context.
 ```
 
-Claude should use `start_codex_session_async`, `send_codex_session_prompt`,
-`steer_codex_session`, `get_codex_session`, and `wait_codex_session`.
+Claude should use `codex_session_start`, `codex_session_prompt`,
+`codex_session_steer`, `codex_session_status`, and `codex_session_wait`.
 
 ## Safety Model
 
@@ -125,16 +125,17 @@ use DNS/network, install packages, or behave like a normal unrestricted Codex ru
 
 | Use case | Preferred tools |
 | --- | --- |
-| One read-only Codex task | `ask_codex` |
-| Several independent tasks | `ask_codex_parallel` |
-| Aggregated parallel review | `run_agents_aggregate` |
-| Persistent context | `start_codex_session`, `continue_codex_session` |
-| Long-running sessions | `start_codex_session_async`, `send_codex_session_prompt`, `steer_codex_session`, `wait_codex_session` |
-| Async one-shot jobs | `start_agent_run`, `get_agent_run`, `wait_agent_run`, `cancel_agent_run` |
+| One read-only Codex task | `codex_task` |
+| Several independent tasks | `codex_task_group` |
+| Persistent context | `codex_session_start`, `codex_session_prompt` |
+| Long-running sessions | `codex_session_start`, `codex_session_status`, `codex_session_wait`, `codex_session_steer` |
+| Session recovery | `codex_sessions`, `codex_session_recover`, `codex_session_cancel` |
 | Diagnostics | `codex_status`, `codex_doctor`, `codex_export_debug_bundle` |
 
-Compatibility tools such as `run_agent`, `run_agents`, `start_session`, and
-`send_session_prompt` remain available for lower-level control.
+Legacy tools such as `ask_codex`, `run_agent`, `run_agents`, `start_session`, and
+`send_session_prompt` are hidden by default. Set
+`CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1` only for older clients that still call the
+pre-refactor names.
 
 ## Development
 

dist/index.js

@@ -62,7 +62,7 @@ metadata needed to reattach to a Codex thread; prompt text and environment value
 are not persisted.
 
 After an MCP runtime shutdown, app-server sessions with a Codex thread id are
-preserved as recoverable. `recover_codex_session` reattaches with `thread/resume`
+preserved as recoverable. `codex_session_recover` reattaches with `thread/resume`
 and treats `thread/read` as an optional capability.
 
 Async one-shot jobs are process-local and do not survive MCP restarts. Their tool

docs/ARCHITECTURE.md

@@ -22,18 +22,18 @@ Disable logging entirely:
 export CODEX_SUBAGENTS_LOG_LEVEL=silent
 ```
 
-## Async Jobs Are Not Durable
+## Legacy Async Jobs Are Not Durable
 
-`start_agent_run` and `start_agents_run` are process-local async jobs. They keep
-Claude responsive during long one-shot work, but they do not survive MCP process
-restart.
+Legacy async one-shot jobs are process-local. They keep Claude responsive during
+long one-shot work, but they do not survive MCP process restart. These legacy
+tools are hidden unless `CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1` is set.
 
-Use `start_codex_session_async` for long-running work that should be recoverable
-after Claude Code or the MCP server restarts.
+Use `codex_session_start` for long-running work that should be recoverable after
+Claude Code or the MCP server restarts.
 
 ## Real Steering Requires App-Server
 
-`steer_codex_session` delivers live steering only when the session is running
+`codex_session_steer` delivers live steering only when the session is running
 through Codex app-server and reports `supportsRealSteering: true`.
 
 If app-server is unavailable and the session falls back to `codex exec`, steering
@@ -69,4 +69,3 @@ still make better choices when the user names the intended shape:
 - "run three Codex agents in parallel"
 - "start a long-running Codex session"
 - "steer the running Codex session"
-

docs/KNOWN_LIMITATIONS.md

@@ -56,19 +56,17 @@ the low-level tool names.
 
 Prefer session or async tools for long work:
 
-- `start_codex_session_async`
-- `get_codex_session`
-- `wait_codex_session`
-- `start_agent_run`
-- `get_agent_run`
-- `wait_agent_run`
+- `codex_session_start`
+- `codex_session_status`
+- `codex_session_wait`
+- `codex_session_steer`
 
 Persistent sessions are the better choice when the work must survive an MCP
 restart. Async one-shot jobs are process-local and do not survive restarts.
 
 ## Session Recovery Fails
 
-Use `get_codex_session`, then `recover_codex_session`.
+Use `codex_session_status`, then `codex_session_recover`.
 
 Check:
 

docs/TROUBLESHOOTING.md

@@ -24,30 +24,17 @@ subdirectory that Claude is working in. If omitted, the server uses
 
 Prefer these tools in normal Claude usage:
 
-- `ask_codex` - one blocking Codex task.
-- `ask_codex_parallel` - several independent blocking Codex tasks.
-- `run_agents_aggregate` - parallel tasks plus deterministic aggregation.
-- `start_codex_session` - create a persistent session and wait for the first turn.
-- `continue_codex_session` - send another prompt into an existing session.
-- `start_codex_session_async` - start a persistent session and return immediately.
-- `send_codex_session_prompt` - queue a normal follow-up prompt.
-- `steer_codex_session` - steer the active app-server turn when supported.
-- `get_codex_session` and `wait_codex_session` - inspect or wait on sessions.
-
-Lower-level compatibility tools remain available:
-
-- `run_agent`
-- `run_agents`
-- `start_agent_run`
-- `start_agents_run`
-- `get_agent_run`
-- `wait_agent_run`
-- `cancel_agent_run`
-- `start_session`
-- `send_session_prompt`
-- `get_session`
-- `list_sessions`
-- `cancel_session`
+- `codex_task` - one Task-like Codex subagent with an answer-first result.
+- `codex_task_group` - several independent Task-like Codex subagents in parallel.
+- `codex_session_start` - start a persistent session and return a session id.
+- `codex_session_prompt` - send another prompt into an existing session.
+- `codex_session_steer` - steer the active app-server turn when supported.
+- `codex_session_status` and `codex_session_wait` - inspect or wait on sessions.
+- `codex_sessions`, `codex_session_recover`, and `codex_session_cancel` - manage session lifecycle.
+
+Legacy compatibility tools are hidden by default. Set
+`CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1` only for older clients that still call
+pre-refactor names such as `ask_codex`, `run_agent`, or `start_session`.
 
 Diagnostics tools:
 
@@ -63,15 +50,13 @@ Use this decision path when writing prompts or debugging Claude tool choice:
 
 | User intent | Best tool |
 | --- | --- |
-| One normal read-only second opinion | `ask_codex` |
-| Two or more independent workstreams | `ask_codex_parallel` |
-| Several agents plus a merged summary | `run_agents_aggregate` |
-| Same Codex agent should keep context | `start_codex_session`, then `continue_codex_session` |
-| Long first turn, user wants to keep working | `start_codex_session_async` |
-| Add a normal follow-up to a running session | `send_codex_session_prompt` |
-| Redirect the active app-server turn | `steer_codex_session` |
-| Recover a session after Claude/MCP restart | `recover_codex_session` |
-| Slow one-shot job that need not be durable | `start_agent_run` |
+| One normal read-only second opinion | `codex_task` |
+| Two or more independent workstreams | `codex_task_group` |
+| Same Codex agent should keep context | `codex_session_start`, then `codex_session_prompt` |
+| Long first turn, user wants to keep working | `codex_session_start` |
+| Add a normal follow-up to a running session | `codex_session_prompt` |
+| Redirect the active app-server turn | `codex_session_steer` |
+| Recover a session after Claude/MCP restart | `codex_session_recover` |
 
 When in doubt, ask Claude to call `codex_choose_tool` before delegating.
 
@@ -87,9 +72,9 @@ Representative tool arguments:
 
 ```json
 {
-  "task": "Review the MCP server read-only. Return the top reliability risks with file paths and line references.",
+  "description": "Review MCP server reliability",
+  "prompt": "Review the MCP server read-only. Return the top reliability risks with file paths and line references.",
   "project_dir": "/path/to/project",
-  "model_preset": "spark",
   "reasoning_effort": "medium"
 }
 ```
@@ -109,22 +94,24 @@ Representative tool arguments:
   "tasks": [
     {
       "name": "api",
-      "task": "Review MCP tool schemas and runtime behavior read-only. Return concrete risks with paths.",
+      "description": "Review API behavior",
+      "prompt": "Review MCP tool schemas and runtime behavior read-only. Return concrete risks with paths.",
       "project_dir": "/path/to/project"
     },
     {
       "name": "tests",
-      "task": "Review test coverage read-only. Identify missing scenarios with paths.",
+      "description": "Review tests",
+      "prompt": "Review test coverage read-only. Identify missing scenarios with paths.",
       "project_dir": "/path/to/project"
     },
     {
       "name": "security",
-      "task": "Review sandboxing, env forwarding, and logging read-only. Return concrete risks with paths.",
+      "description": "Review security posture",
+      "prompt": "Review sandboxing, env forwarding, and logging read-only. Return concrete risks with paths.",
       "project_dir": "/path/to/project"
     }
   ],
   "max_parallel": 3,
-  "model_preset": "spark",
   "reasoning_effort": "medium"
 }
 ```
@@ -135,14 +122,14 @@ Use a persistent session when Codex should keep context across prompts.
 
 ```json
 {
-  "task": "Investigate the session manager read-only. Keep a compact working map of the code.",
+  "description": "Investigate session manager",
+  "prompt": "Investigate the session manager read-only. Keep a compact working map of the code.",
   "project_dir": "/path/to/project",
-  "model_preset": "spark",
   "reasoning_effort": "medium"
 }
 ```
 
-For a long-running first turn, use `start_codex_session_async`. Then:
+`codex_session_start` returns a session id immediately by default. Then:
 
 ```json
 {
@@ -156,7 +143,7 @@ To steer an active app-server turn:
 ```json
 {
   "session_id": "session-...",
-  "steering_prompt": "Prioritize app-server recovery and ignore UI/documentation polish."
+  "prompt": "Prioritize app-server recovery and ignore UI/documentation polish."
 }
 ```
 
@@ -165,8 +152,10 @@ protocol and steering becomes a high-priority queued turn.
 
 ## Spark And Reasoning
 
-Use `model_preset: "spark"` for fast, focused Codex work. Exact `model` still
-wins when both `model` and `model_preset` are provided.
+Do not use `model_preset: "spark"` by default. Use Spark only when the user asks
+for Spark or when a quick focused sidecar check is clearly more appropriate than
+the default Codex model. Exact `model` still wins when both `model` and
+`model_preset` are provided.
 
 Recommended reasoning:
 

docs/USAGE.md

@@ -11,8 +11,8 @@ normal work, or `CODEX_SUBAGENTS_LOG_LEVEL=silent` to disable logging.
 
 ## Async Jobs Are Not Durable
 
-`start_agent_run` and `start_agents_run` are process-local. Use
-`start_codex_session_async` when the work should be recoverable after restart.
+Legacy async one-shot jobs are process-local and hidden by default. Use
+`codex_session_start` when the work should be recoverable after restart.
 
 ## Steering Requires App-Server
 
@@ -23,4 +23,3 @@ exec protocol, steering becomes a high-priority queued turn.
 
 Full local access requires `dangerously_bypass_approvals_and_sandbox: true`. It
 can write files, mutate git state, use network/DNS, and install packages.
-

docs/assets/demo.svg

@@ -4,12 +4,11 @@ Use the intuitive front-door tools first.
 
 | Task | Tool |
 | --- | --- |
-| One Codex task | `ask_codex` |
-| Several independent tasks | `ask_codex_parallel` |
-| Parallel review with merged output | `run_agents_aggregate` |
-| Persistent session | `start_codex_session`, `continue_codex_session` |
-| Long-running session | `start_codex_session_async`, `send_codex_session_prompt`, `steer_codex_session`, `wait_codex_session` |
-| Async one-shot job | `start_agent_run`, `get_agent_run`, `wait_agent_run`, `cancel_agent_run` |
+| One Codex task | `codex_task` |
+| Several independent tasks | `codex_task_group` |
+| Persistent session | `codex_session_start`, `codex_session_prompt` |
+| Long-running session | `codex_session_start`, `codex_session_status`, `codex_session_wait`, `codex_session_steer` |
+| Session lifecycle | `codex_sessions`, `codex_session_recover`, `codex_session_cancel` |
 | Diagnostics | `codex_status`, `codex_doctor`, `codex_export_debug_bundle` |
 
 ## One Agent

docs/wiki/Known-Limitations.md

@@ -36,12 +36,10 @@ Ask Codex to review this repository read-only.
 
 Use persistent or async tools instead of one blocking request:
 
-- `start_codex_session_async`
-- `get_codex_session`
-- `wait_codex_session`
-- `start_agent_run`
-- `get_agent_run`
-- `wait_agent_run`
+- `codex_session_start`
+- `codex_session_status`
+- `codex_session_wait`
+- `codex_session_steer`
 
 Persistent sessions are the right path for work that should be recoverable after
 an MCP restart.