Bound blocking Codex waits

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

Author: xuio

README.md

@@ -120,6 +120,10 @@ to `codex://sessions/{session_id}` for milestone and completion updates. For a
 completed first turn, Claude should set `keep_session: true`; for long first
 turns, Claude should set `background: true`.
 
+Blocking waits are capped to responsive slices by default. When `codex_followup`
+or `codex_wait_any` returns `completed: false`, the Codex session is still
+running; call the wait tool again or read `codex://sessions/{session_id}`.
+
 When app-server sessions use the Codex desktop binary, they are recorded as
 normal top-level Codex threads rather than hidden daemon work. The plugin sets the
 thread name from Claude's task label when the installed Codex app-server supports

dist/index.js

@@ -15,6 +15,7 @@ Claude Code development workflow.
 | Model | Codex account or config default unless a tool call supplies one |
 | Reasoning effort | `medium` when a default is needed |
 | Logging | verbose JSONL on stderr |
+| Blocking wait cap | `300000` ms per wait call |
 
 Claude should pass `project_dir` when Codex should inspect the same repository or
 subdirectory that Claude is working in. If omitted, the server uses
@@ -78,6 +79,11 @@ Use this decision path when writing prompts or debugging Claude tool choice:
 supports thread archiving, the plugin best-effort archives that Desktop thread so
 stopped Claude subagent work does not keep cluttering the active thread list.
 
+Blocking wait tools return periodically even when the requested timeout is very
+large. If `completed` is false with `timeoutReason: "wait_timeout"`, the Codex
+session is still managed by the MCP server; call `codex_followup` mode `wait` or
+`codex_wait_any` again, or read `codex://sessions/{session_id}` for live state.
+
 When in doubt, read `codex://usage` and then choose among the native front-door tools.
 
 ## When To Prefer Codex
@@ -222,11 +228,14 @@ To collect whichever background session finishes first:
 ```json
 {
   "session_ids": ["session-a", "session-b"],
-  "wait_timeout_ms": 600000
+  "wait_timeout_ms": 300000
 }
 ```
 
-Use the returned `remaining_session_ids` in the next `codex_wait_any` call.
+Use the returned `remaining_session_ids` in the next `codex_wait_any` call. Long
+requested waits are capped by `CODEX_SUBAGENTS_MAX_BLOCKING_WAIT_MS` so Claude
+does not sit in one MCP call long enough for Desktop's inactivity watchdog to
+kill the parent session.
 
 To stop a background or actively running session:
 
@@ -339,6 +348,7 @@ servers should not be loaded for the run.
 | `CODEX_SUBAGENTS_MAX_SESSIONS` | Maximum retained persistent sessions |
 | `CODEX_SUBAGENTS_MAX_SESSION_QUEUED_TURNS` | Maximum queued turns per session |
 | `CODEX_SUBAGENTS_MAX_SESSION_MILESTONES` | Recent milestone ring size per session, clamped to 10-500 |
+| `CODEX_SUBAGENTS_MAX_BLOCKING_WAIT_MS` | Maximum duration for one blocking wait call, clamped to 25-300000 ms |
 | `CODEX_SUBAGENTS_SESSION_COMPLETED_TTL_SECONDS` | Retention for failed/cancelled sessions |
 | `CODEX_SUBAGENTS_SESSION_IDLE_TTL_SECONDS` | Retention for idle resumable sessions |
 | `CODEX_SUBAGENTS_SESSION_STATE_FILE` | Durable session metadata path |

docs/USAGE.md

@@ -18,6 +18,10 @@ codebases, server/deployment work, difficult debugging, or adversarial security
 and correctness review. Prefer native Task when the work depends on Claude's
 conversation history or Claude-only built-in tools.
 
+Blocking waits return in bounded slices so Claude Desktop stays responsive. If
+`completed` is false, call `codex_followup` mode `wait` or `codex_wait_any`
+again, or read `codex://sessions/{session_id}`.
+
 ## One Agent
 
 ```text

docs/wiki/Tool-Guide.md

@@ -0,0 +1,29 @@
+export const defaultBlockingWaitTimeoutMs = 300_000;
+export const hardMaxBlockingWaitTimeoutMs = 300_000;
+export const minBlockingWaitTimeoutMs = 25;
+
+export type BlockingWaitTimeout = {
+  requestedMs: number;
+  effectiveMs: number;
+  capped: boolean;
+};
+
+export function configuredMaxBlockingWaitMs(env: NodeJS.ProcessEnv = process.env): number {
+  const parsed = Number(env.CODEX_SUBAGENTS_MAX_BLOCKING_WAIT_MS);
+  if (!Number.isFinite(parsed) || parsed <= 0) return defaultBlockingWaitTimeoutMs;
+  return Math.max(minBlockingWaitTimeoutMs, Math.min(Math.floor(parsed), hardMaxBlockingWaitTimeoutMs));
+}
+
+export function capBlockingWaitTimeout(
+  requestedMs: number | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): BlockingWaitTimeout {
+  const requested = requestedMs ?? configuredMaxBlockingWaitMs(env);
+  const normalized = Math.max(1, Math.floor(requested));
+  const effective = Math.min(normalized, configuredMaxBlockingWaitMs(env));
+  return {
+    requestedMs: normalized,
+    effectiveMs: effective,
+    capped: effective < normalized,
+  };
+}

src/index.ts

@@ -34,8 +34,8 @@ function assert(condition, message, details) {
   }
 }
 
-async function callTool(name, args) {
-  return client.callTool(
+async function callToolOn(targetClient, name, args) {
+  return targetClient.callTool(
     {
       name,
       arguments: args,
@@ -44,6 +44,10 @@ async function callTool(name, args) {
   );
 }
 
+async function callTool(name, args) {
+  return callToolOn(client, name, args);
+}
+
 async function readJsonResource(uri) {
   const resource = await client.readResource({ uri });
   return JSON.parse(resource.contents[0].text);
@@ -73,6 +77,10 @@ async function recordedCalls() {
 }
 
 async function listToolsWithEnv(env) {
+  return withClientEnv(env, async (debugClient) => debugClient.listTools());
+}
+
+async function withClientEnv(env, run) {
   const debugClient = new Client({ name: "codex-subagents-smoke-debug", version: "0.1.0" });
   const debugTransport = new StdioClientTransport({
     command: path.join(root, "dist/index.js"),
@@ -83,7 +91,7 @@ async function listToolsWithEnv(env) {
   debugTransport.stderr?.resume();
   try {
     await debugClient.connect(debugTransport);
-    return await debugClient.listTools();
+    return await run(debugClient);
   } finally {
     await debugTransport.close().catch(() => {});
   }
@@ -192,6 +200,50 @@ try {
     missingCancel,
   );
 
+  await withClientEnv(
+    {
+      PATH: process.env.PATH ?? "",
+      CODEX_SUBAGENTS_CODEX_BIN: fakeCodex,
+      CLAUDE_PROJECT_DIR: projectDir,
+      CODEX_SUBAGENTS_SESSION_STATE_FILE: path.join(projectDir, "capped-wait-sessions.json"),
+      CODEX_SUBAGENTS_MAX_BLOCKING_WAIT_MS: "50",
+      FAKE_CODEX_RECORD_DIR: recordDir,
+    },
+    async (cappedClient) => {
+      const slow = await callToolOn(cappedClient, "codex_task", {
+        description: "Capped wait smoke",
+        prompt: "capped wait smoke DELAY_MS=500",
+        project_dir: projectDir,
+        background: true,
+      });
+      assert(slow.structuredContent?.session_id, "capped wait smoke should start a background session", slow);
+      const cappedWait = await callToolOn(cappedClient, "codex_wait_any", {
+        session_ids: [slow.structuredContent.session_id],
+        wait_timeout_ms: 5_000,
+      });
+      assert(
+        cappedWait.structuredContent?.completed === false &&
+          cappedWait.structuredContent?.wait_timeout_capped === true &&
+          cappedWait.structuredContent?.effective_wait_timeout_ms === 50 &&
+          cappedWait.structuredContent?.requested_wait_timeout_ms === 5_000,
+        "codex_wait_any should cap long blocking waits and return a running result",
+        cappedWait.structuredContent,
+      );
+      assert(
+        typeof cappedWait.structuredContent?.elapsed_ms === "number" &&
+          cappedWait.structuredContent.elapsed_ms < 1_000,
+        "capped wait should return before Claude Desktop's inactivity watchdog could fire",
+        cappedWait.structuredContent,
+      );
+      const cancelled = await callToolOn(cappedClient, "codex_followup", {
+        session_id: slow.structuredContent.session_id,
+        mode: "cancel",
+        reason: "capped wait smoke cleanup",
+      });
+      assert(cancelled.structuredContent?.status === "cancelled", "capped wait smoke cleanup should cancel the session", cancelled);
+    },
+  );
+
   const invalidReasoning = await callTool("codex_task", {
     description: "Invalid reasoning smoke",
     prompt: "should not start",
@@ -334,6 +386,29 @@ try {
     "codex_followup without an explicit description should not prepend boilerplate",
     followupCall,
   );
+  const followupTimeoutSession = await callTool("codex_task", {
+    description: "Follow-up timeout session",
+    prompt: "follow-up timeout initial",
+    project_dir: projectDir,
+    keep_session: true,
+  });
+  const followupTimedOut = await callTool("codex_followup", {
+    session_id: followupTimeoutSession.structuredContent.session_id,
+    prompt: "follow-up timeout DELAY_MS=500",
+    wait_timeout_ms: 20,
+  });
+  assert(
+    followupTimedOut.structuredContent?.completed === false &&
+      followupTimedOut.structuredContent?.timeoutReason === "wait_timeout" &&
+      followupTimedOut.structuredContent?.effective_wait_timeout_ms === 20,
+    "foreground codex_followup should honor wait_timeout_ms instead of waiting indefinitely",
+    followupTimedOut.structuredContent,
+  );
+  await callTool("codex_followup", {
+    session_id: followupTimeoutSession.structuredContent.session_id,
+    mode: "cancel",
+    reason: "follow-up timeout smoke cleanup",
+  });
   const personaCall = calls.find((call) => call.method === "turn/start" && call.prompt?.includes("persona smoke"));
   assert(personaCall, "expected recorded persona turn/start call", calls);
   assert(

src/wait-timeout.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import {
+  capBlockingWaitTimeout,
+  configuredMaxBlockingWaitMs,
+  defaultBlockingWaitTimeoutMs,
+  hardMaxBlockingWaitTimeoutMs,
+  minBlockingWaitTimeoutMs,
+} from "../src/wait-timeout.js";
+
+describe("blocking wait timeout caps", () => {
+  it("uses a safe default below Claude Desktop's inactivity watchdog", () => {
+    expect(configuredMaxBlockingWaitMs({} as NodeJS.ProcessEnv)).toBe(defaultBlockingWaitTimeoutMs);
+    expect(defaultBlockingWaitTimeoutMs).toBeLessThan(1_000_000);
+  });
+
+  it("caps long requested waits to the configured max", () => {
+    expect(
+      capBlockingWaitTimeout(10_000, {
+        CODEX_SUBAGENTS_MAX_BLOCKING_WAIT_MS: "50",
+      } as NodeJS.ProcessEnv),
+    ).toEqual({
+      requestedMs: 10_000,
+      effectiveMs: 50,
+      capped: true,
+    });
+  });
+
+  it("clamps configured max values to the hard safety ceiling", () => {
+    expect(
+      configuredMaxBlockingWaitMs({
+        CODEX_SUBAGENTS_MAX_BLOCKING_WAIT_MS: "9000000",
+      } as NodeJS.ProcessEnv),
+    ).toBe(hardMaxBlockingWaitTimeoutMs);
+  });
+
+  it("allows very small test caps without busy looping below the floor", () => {
+    expect(
+      configuredMaxBlockingWaitMs({
+        CODEX_SUBAGENTS_MAX_BLOCKING_WAIT_MS: "1",
+      } as NodeJS.ProcessEnv),
+    ).toBe(minBlockingWaitTimeoutMs);
+  });
+});