Harden Codex MCP execution

Author: xuio

README.md

@@ -15,12 +15,16 @@ The plugin lets Claude Code launch one Codex agent or several Codex agents in pa
 - Transport: stdio MCP, launched by Claude Code for the active session. No daemon is required.
 - Prompt delivery: stdin, not command-line arguments.
 - Codex home: uses the user's Codex home by default; pass `isolated_codex_home: true` to use a temporary Codex home with auth but without inherited `config.toml` MCP servers.
+- Concurrency: Codex processes run through a global queue. Defaults are `CODEX_SUBAGENTS_MAX_GLOBAL_PROCESSES=4` and `CODEX_SUBAGENTS_MAX_PROJECT_PROCESSES=2`.
 
 Optional environment overrides:
 
 - `CODEX_SUBAGENTS_CODEX_BIN`: explicit Codex CLI path.
 - `CODEX_SUBAGENTS_DEFAULT_MODEL`: model to use when a tool call omits `model`.
 - `CODEX_SUBAGENTS_DEFAULT_REASONING_EFFORT`: `low`, `medium`, `high`, or `xhigh`. `minimal` is ignored as a default and falls back to `medium`.
+- `CODEX_SUBAGENTS_MAX_GLOBAL_PROCESSES`: maximum Codex child processes across this MCP server.
+- `CODEX_SUBAGENTS_MAX_PROJECT_PROCESSES`: maximum Codex child processes per project key.
+- `CODEX_SUBAGENTS_JOB_TTL_SECONDS`: completed async job retention window. Defaults to one hour.
 
 ## Spark And Nested Subagents
 
@@ -63,7 +67,9 @@ npm run test:claude-desktop
 
 `test:ci` is the GitHub-safe suite. It uses the fake Codex binary and does not require Claude Code, the Codex desktop app, or live model credentials.
 
-`test:comprehensive` runs the TypeScript build, unit tests, stdio MCP smoke test, reliability matrix, Codex desktop runtime probe, Claude plugin validation, and desktop-shipped Claude Code CLI plugin/auth checks. The runtime probe validates local Codex capabilities without invoking a model.
+`test:comprehensive` runs the TypeScript build, unit tests, stdio MCP smoke test, reliability matrix, MCP stress test, Codex desktop runtime probe, Claude plugin validation, and desktop-shipped Claude Code CLI plugin/auth checks. The runtime probe validates local Codex capabilities without invoking a model.
+
+`test:stress` uses the fake Codex binary to exercise queued async jobs, noisy output, malformed JSONL, and truncation behavior.
 
 `test:claude-orchestration` is an opt-in live Claude Code test. It loads the plugin inside Claude Code, lets Claude call the plugin MCP tools, and uses the fake Codex binary so no Codex model tokens are spent. It is kept out of `test:comprehensive` because it does spend Claude tokens.
 
@@ -87,14 +93,22 @@ After startup, ask Claude to use Codex subagents, or invoke the plugin skill:
 
 `codex_usage_guide` returns the operating guide and example calls Claude can use when deciding how to delegate to Codex.
 
-`run_agent` launches one Codex `exec` process.
+`run_agent` launches one Codex `exec` process and waits for it. It uses the same bounded queue as async jobs.
+
+`run_agents` launches multiple Codex `exec` processes concurrently with a bounded `max_parallel` setting and the global queue.
+
+`start_agent_run` starts one queued Codex run and returns a `job.id` immediately.
 
-`run_agents` launches multiple Codex `exec` processes concurrently with a bounded `max_parallel` setting.
+`start_agents_run` starts a queued parallel Codex run and returns a `job.id` immediately.
+
+`get_agent_run`, `wait_agent_run`, and `cancel_agent_run` inspect, wait for, or cancel async jobs.
 
 `codex_status` reports the resolved Codex binary, server working directory, Claude project directory, default model, default reasoning effort, and version probe.
 
 Each agent accepts model, reasoning effort, sandbox, project directory, timeout, isolated Codex home, and output-size controls. Pass `project_dir` when Claude Code wants Codex to inspect the same repository or subdirectory Claude is currently working in. If `project_dir` is omitted, the server uses `CLAUDE_PROJECT_DIR` when Claude Code provides it. Omit model to use Codex's configured default or the plugin's optional configured default model.
 
+Prefer `start_agent_run` or `start_agents_run` for work that may run longer than a normal MCP request. The async job API keeps Claude responsive, supports cancellation, and avoids request failures caused by long-running Codex subprocesses.
+
 ## License
 
 MIT