Make Codex tasks feel native to Claude

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

Author: xuio

README.md

@@ -70,7 +70,8 @@ Claude should use `codex_task`.
 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 `codex_task_group` and split the work into independent tasks.
+Claude can call `codex_task` three times in parallel, or use `codex_task_group`
+when a single rolled-up response is useful.
 
 ### Use Spark
 
@@ -88,7 +89,8 @@ Start a long-running Codex session on this repo, then let me send follow-up prom
 
 Claude should use `codex_task` for the initial prompt, preserve the returned
 `session_id`, and use `codex_followup` to continue, steer, or wait on that same
-Codex context. For long first turns, Claude should set `background: true`.
+Codex context. For a completed first turn, Claude should set `keep_session: true`;
+for long first turns, Claude should set `background: true`.
 
 ## Safety Model
 
@@ -133,7 +135,7 @@ writes and DNS/network remain disabled unless `full_access: true` is set.
 | --- | --- |
 | One read-only Codex task | `codex_task` |
 | Several independent tasks | `codex_task_group` |
-| Persistent context | `codex_task`, then `codex_followup` |
+| Persistent context | `codex_task` with `keep_session: true`, then `codex_followup` |
 | Long-running sessions | `codex_task` with `background: true`, then `codex_followup` |
 | Live steering | `codex_followup` with `mode: "steer"` |
 | Diagnostics | MCP resources `codex://status`, `codex://doctor`, `codex://usage` |

dist/index.js

@@ -65,7 +65,9 @@ are not persisted.
 After an MCP runtime shutdown, app-server sessions with a Codex thread id are
 preserved as recoverable internally. The default Claude-facing flow is to keep the
 `session_id` returned by `codex_task` and use `codex_followup` while the MCP
-process is alive; hidden debug tools can inspect lower-level recovery state.
+process is alive. `codex_task` returns that id for `background: true`,
+`keep_session: true`, or failure cases; hidden debug tools can inspect
+lower-level recovery state.
 
 Async one-shot jobs are process-local and do not survive MCP restarts. Their tool
 results advertise this limitation and recommend persistent sessions for recoverable

docs/ARCHITECTURE.md

@@ -8,7 +8,8 @@ Highlights:
 
 - Default tool surface is now `codex_task`, `codex_task_group`, and
   `codex_followup`.
-- `codex_task` always returns a `session_id` for follow-up, wait, or steering.
+- `codex_task` now defaults to a lean answer-first payload; it returns a
+  `session_id` for `background`, `keep_session`, or failure cases.
 - Power-user knobs moved under `advanced`; routine calls use `description`,
   `prompt`, `project_dir`, `reasoning`, `subagent_type`, and `full_access`.
 - Diagnostics are resources by default: `codex://usage`, `codex://status`, and

docs/RELEASE.md

@@ -27,7 +27,7 @@ Prefer these tools in normal Claude usage:
 - `codex_task` - one Task-like Codex subagent with an answer-first result.
 - `codex_task_group` - several independent Task-like Codex subagents in parallel.
 - `codex_followup` - continue, steer, or wait on the `session_id` returned by
-  `codex_task` or `codex_task_group`.
+  `codex_task` or `codex_task_group` when `background` or `keep_session` is used.
 
 Legacy compatibility tools are hidden by default. Set
 `CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1` only for older clients that still call
@@ -39,6 +39,10 @@ Diagnostic resources are available without cluttering the tool picker:
 - `codex://status`
 - `codex://doctor`
 
+Native tool responses are intentionally lean by default. For a single debugging
+call, set `advanced.include_diagnostics: true` to include cwd/model/sandbox,
+event summaries, command events, and compacted session state in the response.
+
 Tool-callable diagnostics are hidden by default. Set
 `CODEX_SUBAGENTS_ENABLE_DEBUG_TOOLS=1` only when a client needs:
 
@@ -55,8 +59,8 @@ Use this decision path when writing prompts or debugging Claude tool choice:
 | User intent | Best tool |
 | --- | --- |
 | One normal read-only second opinion | `codex_task` |
-| Two or more independent workstreams | `codex_task_group` |
-| Same Codex agent should keep context | `codex_task`, then `codex_followup` |
+| Two or more independent workstreams | Multiple parallel `codex_task` calls, or `codex_task_group` for one rolled-up response |
+| Same Codex agent should keep context | `codex_task` with `keep_session: true`, then `codex_followup` |
 | Long first turn, user wants to keep working | `codex_task` with `background: true` |
 | Add a normal follow-up to a running session | `codex_followup` with `mode: "queue"` |
 | Redirect the active app-server turn | `codex_followup` with `mode: "steer"` |
@@ -129,11 +133,12 @@ Use a persistent session when Codex should keep context across prompts.
   "description": "Investigate session manager",
   "prompt": "Investigate the session manager read-only. Keep a compact working map of the code.",
   "project_dir": "/path/to/project",
-  "reasoning": "medium"
+  "reasoning": "medium",
+  "keep_session": true
 }
 ```
 
-`codex_task` returns a `session_id`. Then:
+`codex_task` returns a `session_id` when `keep_session` is true. Then:
 
 ```json
 {

docs/USAGE.md

@@ -8,8 +8,9 @@ Native Claude-facing tool surface:
 - `codex_task_group`
 - `codex_followup`
 
-Every `codex_task` returns a `session_id`, diagnostics moved to resources, and
-debug/legacy tools are hidden unless explicitly enabled.
+`codex_task` defaults to a lean answer-first result, returns `session_id` only
+for `background`, `keep_session`, or failure cases, diagnostics moved to
+resources, and debug/legacy tools are hidden unless explicitly enabled.
 
 ## v0.2.0
 

docs/wiki/Release-Notes.md

@@ -5,8 +5,8 @@ Use the intuitive front-door tools first.
 | Task | Tool |
 | --- | --- |
 | One Codex task | `codex_task` |
-| Several independent tasks | `codex_task_group` |
-| Persistent session | `codex_task`, then `codex_followup` |
+| Several independent tasks | Multiple `codex_task` calls, or `codex_task_group` for one rollup |
+| Persistent session | `codex_task` with `keep_session: true`, then `codex_followup` |
 | Long-running session | `codex_task` with `background: true`, then `codex_followup` |
 | Live steering | `codex_followup` with `mode: "steer"` |
 | Diagnostics | Resources `codex://status`, `codex://doctor`, `codex://usage` |