mcp-agents 0.10.2 → 0.12.0

package/README.md

@@ -86,10 +86,11 @@ or Gemini during bridge calls.
 | `--model` | `gpt-5.5` | `model` |
 | `--model_reasoning_effort` | `xhigh` | `model_reasoning_effort` |
 
-Hardcoded defaults: `sandbox_mode=read-only`, `approval_policy=never`,
-`features.multi_agent=false`.
+Other startup defaults: `sandbox_mode=workspace-write`, `approval_policy=never`
+(both configurable via `--sandbox_mode` / `--approval_policy`, and steerable per
+call); `features.multi_agent=false` is fixed.
 
-Startup flags (`--model`, `--model_reasoning_effort`) set the model and effort for the native Codex MCP server. Per-call `model` and `config` arguments are stripped from `tools/call` before they reach Codex, so a client cannot override the pinned model/effort (or the read-only/never sandbox config) for a single call. For example, this request:
+Startup flags (`--model`, `--model_reasoning_effort`) set the model and effort for the native Codex MCP server. Per-call `model` and the model/effort keys inside a `config` override are stripped from `tools/call` before they reach Codex, so a client cannot override the pinned model/effort for a single call (`sandbox`, `cwd`, and `approval-policy` — top-level and the matching `config` keys — are intentionally left steerable per call). For example, this request:
 
 ```json
 {
@@ -101,6 +102,67 @@ Startup flags (`--model`, `--model_reasoning_effort`) set the model and effort f
 
 is forwarded to Codex as `{ "prompt": "Review this diff" }`. Change the model or effort at server startup instead.
 
+**Goal injection.** You can give Codex a persistent objective. Set one at server
+startup with `--goal "<text>"`, or per call with a `goal` argument in `tools/call`:
+
+```json
+{ "prompt": "Refactor the parser", "goal": "Keep the public API unchanged" }
+```
+
+For the initial `codex` call the objective is injected into Codex's native
+`developer-instructions` field (a developer-role message), so this is forwarded
+to Codex as:
+
+```json
+{
+  "prompt": "Refactor the parser",
+  "developer-instructions": "Persistent objective for this Codex thread (a standing goal — keep pursuing it across turns unless explicitly superseded):\nKeep the public API unchanged"
+}
+```
+
+A developer message persists for the whole thread, so `codex-reply` follow-ups
+inherit the objective automatically. Because `codex-reply` has no
+`developer-instructions` field, a per-call `goal` on a reply is instead added as
+a concise `Reminder — standing objective for this thread: …` preamble on the
+prompt. Any caller-supplied `developer-instructions` are preserved, with the
+objective merged ahead of them.
+
+The wrapper-only `goal` argument is always stripped before it reaches Codex (its
+schema has no `goal`). A per-call `goal` overrides the `--goal` default for that
+call; a per-call empty `goal` (`""`) suppresses the default for that one call; a
+non-string `goal` is ignored (the `--goal` default still applies).
+
+**Precedence within a thread.** The objective set on the initial `codex` call is
+a developer-role message and persists for the whole thread, so it takes
+precedence: a *different* `goal` supplied later on a `codex-reply` is only a
+prompt-level reminder and will not reliably override the standing objective
+(verified live — a reply goal that conflicts with the initial one is ignored in
+favor of the standing one). The reply reminder works when it is *not* opposed by
+a conflicting standing objective. To genuinely change the objective mid-stream,
+start a new `codex` call rather than changing it on a `codex-reply`.
+
+> **Note — this is not Codex's native `/goal`.** Codex's `/goal` slash command
+> (durable, thread-scoped goal state with lifecycle/budget/evidence-based
+> completion) is a TUI-only feature — it is parsed in the Codex terminal UI and
+> is *not* reachable through `codex mcp-server`. Prefixing an MCP prompt with
+> `/goal …` does **not** activate it; the text is just passed through as a user
+> message. This wrapper therefore steers Codex with `developer-instructions`
+> (the MCP-native vehicle for a standing objective), which is prompt/role
+> conditioning, not the native goal-lifecycle subsystem.
+
+**Idle watchdog.** The codex pass-through is transparent, so a Codex session that
+stalls after doing work (e.g. its final model turn hangs, or it waits on an
+elicitation the client never answers) would otherwise hang the caller's
+`tools/call` forever. `--codex_idle_timeout <seconds>` (default `600`, `0`
+disables) bounds this: if Codex emits nothing while a request is in flight for
+that long, the wrapper returns a JSON-RPC error (`-32001`) for the open
+request(s), kills the Codex process group, and exits — turning an unbounded stall
+into a surfaced error. The timer resets on any Codex output or inbound client
+activity and is suspended while the client backpressures stdout, so healthy long
+or interactive runs are not killed. The wrapper also exits (instead of lingering)
+if Codex dies or fails to start, so a dead Codex can never leave the caller
+hanging.
+
 ## Integration with Claude Code
 
 Add entries to your project's `.mcp.json` (requires `npm i -g mcp-agents`):
@@ -133,7 +195,7 @@ Override codex defaults at server startup:
 }
 ```
 
-The model and effort are fixed at server startup. Per-call `model` and `config` arguments sent to the native `codex` tool are stripped before reaching Codex, so they cannot override the startup defaults.
+The model and effort are fixed at server startup. Per-call `model` and the model/effort keys inside a `config` override sent to the native `codex` tool are stripped before reaching Codex, so they cannot override the startup model/effort (per-call `sandbox`/`cwd`/`approval-policy` are left intact). Add `"--goal", "<text>"` to `args` to inject a persistent objective into every Codex call (see [Goal injection](#codex-pass-through) above).
 
 Because the bridge runs in an isolated Codex home, inherited MCP servers from your normal
 `~/.codex/config.toml` are intentionally unavailable inside bridged Codex sessions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-agents",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "MCP server that wraps AI CLI tools (Claude Code, Gemini CLI, Codex CLI) for use by any MCP client",
   "type": "module",
   "bin": {

package/server.js

@@ -31,6 +31,11 @@ const DEFAULT_CODEX_MODEL = "gpt-5.5";
 const DEFAULT_CODEX_MODEL_REASONING_EFFORT = "xhigh";
 const DEFAULT_CODEX_SANDBOX_MODE = "workspace-write";
 const DEFAULT_CODEX_APPROVAL_POLICY = "never";
+// Idle watchdog for the codex pass-through: if a request is in flight and codex
+// emits nothing on stdout/stderr for this long, the wrapper synthesizes a
+// JSON-RPC error for the open request(s) and tears codex down — converting an
+// unbounded post-completion stall into a surfaced error. 0 disables it.
+const DEFAULT_CODEX_IDLE_TIMEOUT_MS = 600_000;
 const DEFAULT_CLAUDE_MODEL = "claude-opus-4-8";
 const DEFAULT_CLAUDE_EFFORT = "xhigh";
 // tools/call argument keys stripped from the codex pass-through so callers
@@ -61,7 +66,7 @@ const CODEX_STRIPPED_CONFIG_KEYS = [
 ];
 const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const CLAUDE_EMPTY_OUTPUT_MAX_ATTEMPTS = 2;
-const SIGNAL_CODES = { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 };
+const SIGNAL_CODES = { SIGHUP: 1, SIGINT: 2, SIGKILL: 9, SIGTERM: 15 };
 const SHUTDOWN_TIMEOUT_MS = 3_000;
 let fatalShutdown;
 
@@ -187,6 +192,12 @@ Options:
                                  danger-full-access [default: ${DEFAULT_CODEX_SANDBOX_MODE}]
   --approval_policy <policy>     Codex approval policy: untrusted, on-failure,
                                  on-request, never [default: ${DEFAULT_CODEX_APPROVAL_POLICY}]
+  --goal <text>                  Persistent objective injected into every Codex
+                                 call (as developer-instructions, or a prompt
+                                 reminder on codex-reply); per-call \`goal\` arg
+                                 overrides it [default: none]
+  --codex_idle_timeout <secs>    Codex pass-through idle watchdog; 0 disables
+                                 [default: ${DEFAULT_CODEX_IDLE_TIMEOUT_MS / 1000}]
   --timeout <seconds>            Default timeout per call [default: 300]
   --help, -h                     Show this help message
   --version, -v                  Show version number`);
@@ -195,8 +206,9 @@ Options:
 /**
  * Parse CLI flags from process.argv.
  * Handles --help, --version, --provider, --model, --model_reasoning_effort,
- * --sandbox_mode, --approval_policy, and unknown flags.
- * @returns {{ provider: string, model?: string, modelReasoningEffort?: string, sandboxMode?: string, approvalPolicy?: string, defaultTimeoutMs?: number }}
+ * --sandbox_mode, --approval_policy, --goal, --codex_idle_timeout, and unknown
+ * flags.
+ * @returns {{ provider: string, model?: string, modelReasoningEffort?: string, sandboxMode?: string, approvalPolicy?: string, goal?: string, codexIdleTimeoutMs?: number, defaultTimeoutMs?: number }}
  */
 function parseArgs() {
   const args = process.argv.slice(2);
@@ -205,6 +217,8 @@ function parseArgs() {
   let modelReasoningEffort;
   let sandboxMode;
   let approvalPolicy;
+  let goal;
+  let codexIdleTimeoutMs;
   let defaultTimeoutMs;
 
   for (let i = 0; i < args.length; i++) {
@@ -256,6 +270,28 @@ function parseArgs() {
         }
         approvalPolicy = args[++i];
         break;
+      case "--goal":
+        if (i + 1 >= args.length) {
+          process.stderr.write("error: --goal requires a value\n");
+          process.exit(1);
+        }
+        goal = args[++i];
+        break;
+      case "--codex_idle_timeout": {
+        if (i + 1 >= args.length) {
+          process.stderr.write("error: --codex_idle_timeout requires a value\n");
+          process.exit(1);
+        }
+        const secs = Number(args[++i]);
+        if (!Number.isFinite(secs) || secs < 0) {
+          process.stderr.write(
+            "error: --codex_idle_timeout must be a non-negative number\n",
+          );
+          process.exit(1);
+        }
+        codexIdleTimeoutMs = Math.round(secs * 1000);
+        break;
+      }
       case "--timeout": {
         if (i + 1 >= args.length) {
           process.stderr.write("error: --timeout requires a value\n");
@@ -281,6 +317,8 @@ function parseArgs() {
     modelReasoningEffort,
     sandboxMode,
     approvalPolicy,
+    goal,
+    codexIdleTimeoutMs,
     defaultTimeoutMs,
   };
 }
@@ -459,41 +497,98 @@ function createIsolatedCodexHome({
   approvalPolicy,
 }) {
   const codexHome = mkdtempSync(join(tmpdir(), "mcp-agents-codex-"));
-  const sourceAuthPath = join(resolveCodexHome(), "auth.json");
-  const targetAuthPath = join(codexHome, "auth.json");
-  const configPath = join(codexHome, "config.toml");
+  // If auth copy or config write throws after the dir exists, remove the
+  // partially-prepared dir before rethrowing so it is never leaked.
+  try {
+    const sourceAuthPath = join(resolveCodexHome(), "auth.json");
+    const targetAuthPath = join(codexHome, "auth.json");
+    const configPath = join(codexHome, "config.toml");
+
+    if (existsSync(sourceAuthPath)) {
+      copyFileSync(sourceAuthPath, targetAuthPath);
+    }
+
+    writeFileSync(
+      configPath,
+      buildCodexBridgeConfig({
+        model,
+        modelReasoningEffort,
+        sandboxMode,
+        approvalPolicy,
+      }),
+      "utf8",
+    );
 
-  if (existsSync(sourceAuthPath)) {
-    copyFileSync(sourceAuthPath, targetAuthPath);
+    return codexHome;
+  } catch (err) {
+    try { rmSync(codexHome, { recursive: true, force: true }); } catch {}
+    throw err;
   }
+}
 
-  writeFileSync(
-    configPath,
-    buildCodexBridgeConfig({
-      model,
-      modelReasoningEffort,
-      sandboxMode,
-      approvalPolicy,
-    }),
-    "utf8",
-  );
+/**
+ * Build the text for codex's native `developer-instructions` field (a
+ * developer-role message) from a goal. This is the MCP-correct vehicle for a
+ * standing objective: it is higher-altitude than the user prompt and persists
+ * across the thread. It is NOT codex's `/goal` subsystem — that is a TUI-only
+ * slash command (parsed in codex-rs/tui, e.g. chatwidget/slash_dispatch.rs) and
+ * is not reachable through the MCP `codex`/`codex-reply` tool surface. Any
+ * caller-supplied developer instructions are preserved after the objective.
+ * @param {string} goal
+ * @param {string} [existing] caller-supplied developer-instructions, if any
+ * @returns {string}
+ */
+function buildGoalDeveloperInstructions(goal, existing) {
+  const directive =
+    "Persistent objective for this Codex thread (a standing goal — keep " +
+    "pursuing it across turns unless explicitly superseded):\n" +
+    goal.trim();
+  const prior = typeof existing === "string" ? existing.trim() : "";
+  return prior ? `${directive}\n\n---\n\n${prior}` : directive;
+}
 
-  return codexHome;
+/**
+ * Prepend a concise goal reminder to a prompt. Used for `codex-reply` turns,
+ * which expose no `developer-instructions` field, so the prompt is the only
+ * vehicle left to restate the standing objective. A blank goal leaves the
+ * prompt untouched.
+ * @param {string} prompt
+ * @param {string} goal
+ * @returns {string}
+ */
+function applyGoalPreamble(prompt, goal) {
+  const trimmedGoal = (goal ?? "").trim();
+  const body = prompt ?? "";
+  if (!trimmedGoal) return body;
+  return `Reminder — standing objective for this thread: ${trimmedGoal}\n\n${body}`;
 }
 
 /**
  * Filter a single newline-delimited JSON-RPC message on its way to the codex
- * pass-through. Strips per-call model/effort overrides from `tools/call` so the
- * client cannot escape the pinned model/effort — both the top-level `model` arg
- * and the model-envelope keys inside a `config` override map. sandbox/cwd/
- * approval-policy (top-level and inside `config`) are intentionally left intact
- * so callers can steer them per call. Non-`tools/call`, unparseable, and
- * nothing-to-strip lines are returned byte-for-byte unchanged so the MCP framing
- * is preserved.
+ * pass-through. Two transforms, both confined to `tools/call`:
+ *   1. Strip per-call model/effort overrides — the top-level `model` arg and the
+ *      model-envelope keys inside a `config` override map — so the client cannot
+ *      escape the pinned model/effort. sandbox/cwd/approval-policy (top-level and
+ *      inside `config`) are intentionally left intact so callers can steer them
+ *      per call.
+ *   2. Goal injection — codex's native `/goal` is a TUI-only slash command, not
+ *      reachable via MCP, so a wrapper-only `goal` arg is always stripped and the
+ *      objective is injected the MCP-correct way: into `developer-instructions`
+ *      (a developer-role message) for the initial `codex` call, or as a concise
+ *      prompt reminder for a `codex-reply` turn (which has no
+ *      `developer-instructions` field). A per-call `goal` overrides the
+ *      server-wide `--goal` default (`opts.serverGoal`); only a string per-call
+ *      goal overrides (a blank one suppresses the default for that call), while a
+ *      non-string `goal` is dropped without disturbing the default.
+ * Non-`tools/call`, unparseable, and nothing-to-change lines are returned
+ * byte-for-byte unchanged so the MCP framing is preserved; any actual mutation
+ * re-serializes the message (the intended, framing-safe path for a changed
+ * message).
  * @param {string} line
+ * @param {{ serverGoal?: string }} [opts]
  * @returns {string}
  */
-function filterCodexToolCall(line) {
+function filterCodexToolCall(line, opts = {}) {
   const trimmed = line.trim();
   if (!trimmed) return line;
 
@@ -536,31 +631,83 @@ function filterCodexToolCall(line) {
     if (Object.keys(cfg).length === 0) delete args.config;
   }
 
-  if (removed.length === 0) return line; // nothing pinned to strip — keep framing
+  // ── Goal injection ────────────────────────────────────────────────────────
+  // A per-call `goal` (any value) is always stripped — codex's schema has no
+  // `goal`, so it must never be forwarded. Only a STRING per-call goal counts as
+  // an override: a string (including "") replaces the server default for this
+  // call, so "" suppresses it. A non-string `goal` is malformed and is dropped
+  // without disturbing the configured server default. A blank effective goal
+  // injects nothing.
+  let goalLog;
+  let goalSource = "server";
+  let effectiveGoal = opts.serverGoal;
+  if ("goal" in args) {
+    const perCallGoal = args.goal;
+    delete args.goal;
+    goalLog = "stripped per-call goal arg";
+    if (typeof perCallGoal === "string") {
+      effectiveGoal = perCallGoal;
+      goalSource = "per-call";
+    }
+  }
+  if (effectiveGoal && effectiveGoal.trim()) {
+    if (msg.params?.name === "codex") {
+      // Initial `codex` call: the native developer-instructions field is the
+      // correct, thread-persistent vehicle for a standing objective.
+      args["developer-instructions"] = buildGoalDeveloperInstructions(
+        effectiveGoal,
+        args["developer-instructions"],
+      );
+      goalLog = `injected ${goalSource} goal into developer-instructions`;
+    } else if (msg.params?.name === "codex-reply" && typeof args.prompt === "string") {
+      // codex-reply has no developer-instructions field, so restate the
+      // objective as a concise prompt reminder. Any other (unknown/future) tool
+      // is left untouched — only the wrapper-only `goal` arg stripped above is
+      // removed, never the prompt — so the byte-for-byte invariant holds for
+      // tools this wrapper does not explicitly support.
+      args.prompt = applyGoalPreamble(args.prompt, effectiveGoal);
+      goalLog = `injected ${goalSource} goal into codex-reply prompt`;
+    }
+  }
 
-  logErr(
-    `[mcp-agents] codex passthrough: pinning model/effort, stripped: ${removed.join(", ")}`,
-  );
+  if (removed.length === 0 && !goalLog) return line; // nothing changed — keep framing
+
+  if (removed.length > 0) {
+    logErr(
+      `[mcp-agents] codex passthrough: pinning model/effort, stripped: ${removed.join(", ")}`,
+    );
+  }
+  if (goalLog) {
+    logErr(`[mcp-agents] codex passthrough: ${goalLog}`);
+  }
   return JSON.stringify(msg);
 }
 
 /**
- * Spawn codex mcp-server as a pass-through. stdout/stderr flow straight back to
- * the client, but the client's stdin is intercepted line-by-line so per-call
- * model/config overrides are stripped before reaching codex.
- * @param {{ model?: string, modelReasoningEffort?: string, sandboxMode?: string, approvalPolicy?: string }} opts
+ * Spawn codex mcp-server as a pass-through. codex stdout is forwarded back to
+ * the client byte-for-byte, but the client's stdin is intercepted line-by-line
+ * so per-call model/config overrides are stripped before reaching codex. An
+ * idle watchdog converts an unbounded codex stall (no stdout/stderr while a
+ * request is in flight) into a synthesized JSON-RPC error so the caller never
+ * hangs forever.
+ * @param {{ model?: string, modelReasoningEffort?: string, sandboxMode?: string, approvalPolicy?: string, idleTimeoutMs?: number, goal?: string }} opts
  */
 function runCodexPassthrough({
   model,
   modelReasoningEffort,
   sandboxMode,
   approvalPolicy,
+  idleTimeoutMs,
+  goal,
 }) {
   const resolvedModel = model || DEFAULT_CODEX_MODEL;
   const resolvedModelReasoningEffort =
     modelReasoningEffort || DEFAULT_CODEX_MODEL_REASONING_EFFORT;
   const resolvedSandboxMode = sandboxMode || DEFAULT_CODEX_SANDBOX_MODE;
   const resolvedApprovalPolicy = approvalPolicy || DEFAULT_CODEX_APPROVAL_POLICY;
+  const resolvedIdleTimeoutMs = idleTimeoutMs ?? DEFAULT_CODEX_IDLE_TIMEOUT_MS;
+  // Server-wide default goal (string or undefined); per-call `goal` overrides it.
+  const resolvedGoal = goal;
   let isolatedCodexHome;
 
   try {
@@ -595,70 +742,480 @@ function runCodexPassthrough({
     `[mcp-agents] passthrough: codex ${args.join(" ")} ` +
       `(model=${resolvedModel}, reasoning_effort=${resolvedModelReasoningEffort}, ` +
       `sandbox_mode=${resolvedSandboxMode}, approval_policy=${resolvedApprovalPolicy}, ` +
-      `isolated_home=true)`,
+      `goal=${resolvedGoal && resolvedGoal.trim() ? "set" : "none"}, ` +
+      `idle_timeout_ms=${resolvedIdleTimeoutMs}, isolated_home=true)`,
   );
 
   const child = spawn("codex", args, {
     env: { ...process.env, CODEX_HOME: isolatedCodexHome },
-    // stdin is piped (not inherited) so we can strip per-call overrides;
-    // stdout stays inherited so codex responses reach the client untouched.
-    stdio: ["pipe", "inherit", "pipe"],
+    // stdin is piped so we can strip per-call overrides; stdout is piped (not
+    // inherited) so the wrapper can both forward responses byte-for-byte AND
+    // observe them for the idle watchdog. detached:true puts codex in its own
+    // process group so a stall is torn down group-wide (mirrors runCli).
+    detached: true,
+    stdio: ["pipe", "pipe", "pipe"],
   });
 
+  const NEWLINE = 0x0a;
+  // Clean the isolated home on any exit path, not just the ones we route through
+  // hardExit() (e.g. a global uncaughtException handler calling process.exit).
+  process.once("exit", () => cleanupIsolatedCodexHome());
+
+  // Install signal teardown IMMEDIATELY after spawn (before the heavier wiring
+  // below) so a signal in the startup window can never orphan the detached
+  // group. `finalize` is a forward reference — safe because the handler body
+  // only runs when a signal fires, which is after this synchronous setup
+  // completes and `finalize` is defined.
+  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.once(sig, () => {
+      finalize({
+        reason: `signal ${sig}`,
+        emit: false,
+        exitCode: 128 + SIGNAL_CODES[sig],
+      });
+    });
+  }
+
+  // ── In-flight request tracking ──────────────────────────────────────────
+  // Client requests (id + method) awaiting a codex response. Keyed by a
+  // type-preserving key so JSON-RPC `1` (number) and `"1"` (string) never
+  // collide. `canceled` marks ids the client gave up on (notifications/
+  // cancelled): we never synthesize a response for them, but they still count
+  // toward teardown so a canceled-but-wedged codex is not left running.
+  const inFlight = new Map();
+  const idKey = (id) => `${typeof id}:${id}`;
+  const addInFlight = (id) => {
+    if (id == null) return;
+    const key = idKey(id);
+    if (!inFlight.has(key)) inFlight.set(key, { id, canceled: false });
+  };
+  const clearInFlight = (id) => {
+    if (id != null) inFlight.delete(idKey(id));
+  };
+  const cancelInFlight = (id) => {
+    const entry = id == null ? undefined : inFlight.get(idKey(id));
+    if (entry) entry.canceled = true;
+  };
+  const hasEmittableInFlight = () => {
+    for (const entry of inFlight.values()) if (!entry.canceled) return true;
+    return false;
+  };
+
+  // ── Liveness / lifecycle state ──────────────────────────────────────────
+  let finalizing = false;
+  let exited = false;
+  let stdoutPaused = false; // process.stdout backpressured (downstream, not idle)
+  let idleTimer;
+  let lastForwardedByteWasNewline = true; // nothing forwarded yet
+  let stdoutObsBuf = Buffer.alloc(0); // observation copy of codex stdout
+  let skippingFrame = false; // mid-skip of an oversized stdout frame (resync at \n)
+  let droppedFrameResponseId; // partial oversized frame's classified id (cleared at its newline)
+  let observationDropLogged = false; // log the first observation-cap drop only
+
+  const killGroup = (signal) => {
+    try {
+      if (child.pid) process.kill(-child.pid, signal);
+      else child.kill(signal);
+    } catch {
+      try { child.kill(signal); } catch {}
+    }
+  };
+
+  const clearIdle = () => {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = undefined;
+    }
+  };
+  const armIdle = () => {
+    clearIdle();
+    // No watchdog when disabled, while finalizing, or while downstream is
+    // backpressured (blocked downstream != idle upstream).
+    if (!(resolvedIdleTimeoutMs > 0) || finalizing || stdoutPaused) return;
+    idleTimer = setTimeout(onIdle, resolvedIdleTimeoutMs);
+  };
+  const resetIdle = armIdle;
+
+  // Parse one complete codex->client stdout frame (observation only — the raw
+  // bytes are forwarded separately). Clears an id once its result/error lands.
+  const observeOutgoingLine = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try { msg = JSON.parse(trimmed); } catch { return; }
+    if (
+      msg && typeof msg === "object" && "id" in msg &&
+      ("result" in msg || "error" in msg)
+    ) {
+      clearInFlight(msg.id);
+    }
+  };
+
+  // Classify a (possibly oversized) frame from a bounded prefix: return the
+  // request id iff it is clearly a RESPONSE — a top-level "result"/"error" with
+  // the "id" appearing before it and no top-level "method" preceding it.
+  // Assumes codex's (serde_json) serialization order: a response is
+  // {jsonrpc,id,result|error} (id/result within the first handful of bytes), and
+  // a notification/request emits its top-level "method" before "params". Under
+  // that contract a nested "result"/"id" inside a non-response's params cannot be
+  // misread as a response. Only ever consulted for frames too large to buffer.
+  const FRAME_HEADER_SCAN = 8192;
+  const peekResponseId = (prefix) => {
+    const s = prefix
+      .subarray(0, Math.min(prefix.length, FRAME_HEADER_SCAN))
+      .toString("utf8");
+    const resultAt = s.search(/"(?:result|error)"\s*:/);
+    if (resultAt === -1) return undefined; // no result/error -> not a response
+    const methodAt = s.search(/"method"\s*:/);
+    if (methodAt !== -1 && methodAt < resultAt) return undefined; // request/notif
+    // Capture the full id TOKEN (number or quoted string) and JSON-decode it so
+    // the value matches what noteInbound stored via JSON.parse — otherwise an
+    // escaped string id (e.g. "a\\b") would not equal the tracked key.
+    const idMatch = s
+      .slice(0, resultAt)
+      .match(/"id"\s*:\s*(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|"(?:[^"\\]|\\.)*")/);
+    if (!idMatch) return undefined;
+    try { return JSON.parse(idMatch[1]); } catch { return undefined; }
+  };
+
+  const logObservationDropOnce = () => {
+    if (!observationDropLogged) {
+      logErr(
+        "[mcp-agents] codex passthrough: stdout frame exceeded observation cap; " +
+          "classifying it via a bounded header scan (forwarding unaffected)",
+      );
+      observationDropLogged = true;
+    }
+  };
+
+  // Resolve a dropped frame's effect on id-tracking. The frame's raw bytes were
+  // already forwarded to the client. If a bounded header scan proves it is the
+  // RESPONSE for an in-flight id, clear exactly that id — so we neither
+  // double-respond with a synthetic error nor falsely idle-kill a healthy
+  // session once codex goes quiet. If it is NOT a response (notification /
+  // server->client request) or cannot be classified, leave the in-flight ids
+  // tracked so a genuine post-frame stall is still caught. ONLY call this once
+  // the frame is COMPLETE (its terminating newline has been seen): clearing on a
+  // still-partial frame would prematurely untrack an id whose response codex may
+  // never finish writing, re-introducing a hang.
+  const resolveDroppedFrame = (prefix) => {
+    const id = peekResponseId(prefix);
+    if (id !== undefined) clearInFlight(id);
+  };
+
+  // Accumulate codex stdout into the observation buffer and parse each complete
+  // frame to clear in-flight ids. Soft-bounded by MAX_BUFFER_BYTES so a
+  // pathologically large single frame cannot exhaust memory — the bound is
+  // approximate (a frame may transiently allocate up to one stream chunk beyond
+  // the cap before being dropped). The RAW bytes are always forwarded untouched
+  // by the caller regardless. A dropped frame is handled by onObservedFrameDropped().
+  const observeOutgoing = (chunk) => {
+    let data = chunk;
+    if (skippingFrame) {
+      const nl = data.indexOf(NEWLINE);
+      if (nl === -1) return; // still inside the oversized frame
+      // The oversized frame just COMPLETED. Apply the deferred clear now: if its
+      // header looked like a response, the response genuinely finished, so clear
+      // that id. (If codex had stalled mid-frame, this newline never arrives and
+      // the id stays tracked so the watchdog still catches the stall.)
+      skippingFrame = false;
+      if (droppedFrameResponseId !== undefined) {
+        clearInFlight(droppedFrameResponseId);
+        droppedFrameResponseId = undefined;
+      }
+      data = data.subarray(nl + 1); // resume parsing after the frame boundary
+    }
+    stdoutObsBuf = stdoutObsBuf.length ? Buffer.concat([stdoutObsBuf, data]) : data;
+    let nl;
+    while ((nl = stdoutObsBuf.indexOf(NEWLINE)) !== -1) {
+      if (nl > MAX_BUFFER_BYTES) {
+        // A COMPLETE frame larger than the cap: it fully arrived, so classify it
+        // from a bounded header prefix and clear its id now (no huge alloc).
+        logObservationDropOnce();
+        resolveDroppedFrame(stdoutObsBuf.subarray(0, nl));
+        stdoutObsBuf = stdoutObsBuf.subarray(nl + 1);
+        continue;
+      }
+      const line = stdoutObsBuf.subarray(0, nl).toString("utf8");
+      stdoutObsBuf = stdoutObsBuf.subarray(nl + 1);
+      observeOutgoingLine(line);
+    }
+    if (stdoutObsBuf.length > MAX_BUFFER_BYTES) {
+      // A PARTIAL frame already past the cap with no newline yet: classify the
+      // prefix but DEFER clearing to the frame's newline (above) — clearing now
+      // would untrack an id whose response codex might never finish, hanging it.
+      logObservationDropOnce();
+      droppedFrameResponseId = peekResponseId(stdoutObsBuf);
+      stdoutObsBuf = Buffer.alloc(0);
+      skippingFrame = true;
+    }
+  };
+
+  const hardExit = (code) => {
+    if (exited) return;
+    exited = true;
+    clearIdle();
+    cleanupIsolatedCodexHome();
+    process.exit(code);
+  };
+  const flushThenExit = (code) => {
+    if (exited) return;
+    if (process.stdout.writableLength === 0) {
+      hardExit(code);
+      return;
+    }
+    // Ref'd safety timer guarantees exit if 'drain' never fires (client gone).
+    const safety = setTimeout(() => hardExit(code), 2_000);
+    process.stdout.once("drain", () => {
+      clearTimeout(safety);
+      hardExit(code);
+    });
+  };
+
+  // Single, idempotent teardown. `emit` controls whether open (non-canceled)
+  // requests get a synthetic JSON-RPC error before exit. The detached group is
+  // killed on EVERY teardown path so codex and any descendants are never
+  // orphaned.
+  const finalize = ({ reason, emit, exitCode }) => {
+    if (finalizing) return;
+    finalizing = true;
+    clearIdle();
+    logErr(`[mcp-agents] codex passthrough finalize: ${reason}`);
+
+    // Stop forwarding further codex stdout so a late real response cannot race
+    // the synthetic error onto the wire after we've taken over the stream.
+    try { child.stdout?.pause(); } catch {}
+
+    // Kill the whole detached group so codex AND any descendants it spawned are
+    // reaped on EVERY teardown path — never orphaned. On abort paths (idle /
+    // signal / EPIPE / fatal) codex is still alive, so there is no PID-reuse
+    // risk; on a natural close/spawn-error this runs synchronously right after
+    // the child was reaped (a negligible reuse window) to clean up anything
+    // codex left behind in its group. A SIGKILL on an already-empty group is a
+    // harmless ESRCH (swallowed by killGroup).
+    killGroup("SIGKILL");
+
+    if (emit && hasEmittableInFlight()) {
+      // Framing recovery: if codex left a dangling partial line on the wire, try
+      // to parse it (it may itself be the real response) and terminate it with a
+      // newline so the synthetic frame cannot glue onto a half-written line.
+      if (stdoutObsBuf.length > 0) {
+        observeOutgoingLine(stdoutObsBuf.toString("utf8"));
+        stdoutObsBuf = Buffer.alloc(0);
+        try { process.stdout.write("\n"); } catch {}
+        lastForwardedByteWasNewline = true;
+      } else if (!lastForwardedByteWasNewline) {
+        try { process.stdout.write("\n"); } catch {}
+        lastForwardedByteWasNewline = true;
+      }
+
+      for (const entry of inFlight.values()) {
+        if (entry.canceled) continue;
+        const frame = {
+          jsonrpc: "2.0",
+          id: entry.id,
+          error: {
+            code: -32001,
+            message:
+              `mcp-agents: codex pass-through aborted before responding ` +
+              `(${reason}); the request was still open. Any applied edits may ` +
+              `exist — verify the tree.`,
+          },
+        };
+        try { process.stdout.write(`${JSON.stringify(frame)}\n`); } catch {}
+      }
+    }
+
+    flushThenExit(exitCode);
+  };
+
+  // Route the global uncaughtException/unhandledRejection handlers through the
+  // same teardown so codex's DETACHED group is always killed — otherwise those
+  // handlers call process.exit() directly and orphan codex (the 'exit' handler
+  // only deletes CODEX_HOME, it cannot reap a detached group).
+  fatalShutdown = (reason, code) =>
+    finalize({ reason: `fatal: ${reason}`, emit: true, exitCode: code ?? 1 });
+
+  function onIdle() {
+    idleTimer = undefined;
+    if (finalizing) return;
+    if (hasEmittableInFlight()) {
+      finalize({
+        reason: `idle timeout (${Math.round(resolvedIdleTimeoutMs / 1000)}s)`,
+        emit: true,
+        exitCode: 1,
+      });
+      return;
+    }
+    // Only canceled requests left -> tear down quietly. Nothing open at all ->
+    // healthy idle between calls, just re-arm.
+    if (inFlight.size > 0) {
+      finalize({
+        reason: "idle timeout (canceled-only)",
+        emit: false,
+        exitCode: 1,
+      });
+    } else {
+      armIdle();
+    }
+  }
+
   child.stderr.on("data", (chunk) => {
+    resetIdle();
     logErr(`[codex] ${chunk.toString().trimEnd()}`);
   });
 
+  // Forward codex stdout to the client byte-for-byte (raw Buffer) and keep a
+  // parallel observation buffer (split on the newline BYTE) to clear in-flight
+  // ids as their responses land. Raw chunks are forwarded; reconstructed lines
+  // are never written back.
+  child.stdout.on("data", (chunk) => {
+    if (finalizing) return; // stream ownership has been taken over
+    resetIdle();
+
+    // Forward the raw bytes FIRST so a bug in observation can never affect the
+    // byte-for-byte passthrough (observation is best-effort id-tracking only).
+    if (chunk.length > 0) {
+      lastForwardedByteWasNewline = chunk[chunk.length - 1] === NEWLINE;
+    }
+    const ok = process.stdout.write(chunk);
+    try {
+      observeOutgoing(chunk); // bounded parse-for-ids; never alters forwarded bytes
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logErr(`[mcp-agents] codex passthrough: stdout observation error (ignored): ${msg}`);
+    }
+    if (!ok) {
+      // Downstream full: pause codex and suspend the idle watchdog until the
+      // client drains, so a slow reader is never mistaken for a stalled codex.
+      // Trade-off: a client that never drains keeps the request open with no
+      // watchdog — but a synthetic error could not be delivered to it anyway.
+      stdoutPaused = true;
+      clearIdle();
+      child.stdout.pause();
+    }
+  });
+
+  process.stdout.on("drain", () => {
+    if (!stdoutPaused) return;
+    stdoutPaused = false;
+    if (finalizing) return;
+    child.stdout.resume();
+    resetIdle();
+  });
+
+  process.stdout.on("error", (err) => {
+    // Client went away mid-write: nothing left to answer, tear codex down.
+    if (err && err.code === "EPIPE") {
+      finalize({ reason: "stdout EPIPE", emit: false, exitCode: 0 });
+    }
+  });
+
   // Pump client stdin -> codex stdin, splitting on the newline BYTE (0x0a) that
   // delimits MCP stdio JSON-RPC frames. Buffering raw bytes (not per-chunk
   // strings) avoids corrupting a multibyte UTF-8 sequence that straddles two
   // read chunks, which would otherwise break the byte-for-byte passthrough.
   child.stdin.on("error", () => {}); // ignore EPIPE if codex exits early
-  const NEWLINE = 0x0a;
+
+  // Read-only inbound tracking: record client requests (id + method) as
+  // in-flight and honor cancellations. Never mutates what is forwarded —
+  // filterCodexToolCall remains the sole authority on the forwarded bytes.
+  const noteInbound = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try { msg = JSON.parse(trimmed); } catch { return; }
+    if (!msg || typeof msg !== "object") return;
+    // (Watchdog liveness is reset at the byte level in the stdin 'data' handler,
+    // so even an elicitation response — bare id, no method — keeps a healthy
+    // interactive flow alive.)
+    if (msg.method === "notifications/cancelled") {
+      cancelInFlight(msg.params?.requestId);
+      return;
+    }
+    // A client message awaits a response iff it carries BOTH an id and a method.
+    // A bare id with no method is a *response* to a codex elicitation — skip it
+    // for in-flight tracking.
+    if (msg.id != null && typeof msg.method === "string") {
+      addInFlight(msg.id);
+    }
+  };
+
   let stdinBuf = Buffer.alloc(0);
   process.stdin.on("data", (chunk) => {
+    // ANY inbound bytes mean the client side of the exchange is alive — even a
+    // large/slow elicitation response arriving across chunks without a newline.
+    // Reset the watchdog here at the BYTE level (not per parsed line): a truly
+    // stalled exchange (codex silent AND client sending nothing) still produces
+    // no inbound, so the genuine stall is still caught.
+    resetIdle();
     stdinBuf = stdinBuf.length ? Buffer.concat([stdinBuf, chunk]) : chunk;
     let nl;
     while ((nl = stdinBuf.indexOf(NEWLINE)) !== -1) {
       const line = stdinBuf.subarray(0, nl).toString("utf8");
       stdinBuf = stdinBuf.subarray(nl + 1);
-      child.stdin.write(`${filterCodexToolCall(line)}\n`);
+      noteInbound(line);
+      child.stdin.write(`${filterCodexToolCall(line, { serverGoal: resolvedGoal })}\n`);
     }
   });
   process.stdin.on("error", () => {});
   process.stdin.on("end", () => {
     if (stdinBuf.length > 0) {
-      child.stdin.write(filterCodexToolCall(stdinBuf.toString("utf8")));
+      const line = stdinBuf.toString("utf8");
+      noteInbound(line);
+      child.stdin.write(filterCodexToolCall(line, { serverGoal: resolvedGoal }));
     }
     child.stdin.end();
   });
 
-  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
-    process.once(sig, () => {
-      child.kill(sig);
-      setTimeout(() => {
-        child.kill("SIGKILL");
-        cleanupIsolatedCodexHome();
-        process.exit(128 + SIGNAL_CODES[sig]);
-      }, 5000).unref();
-    });
-  }
-
   child.on("error", (err) => {
-    cleanupIsolatedCodexHome();
     logErr(`[mcp-agents] failed to start codex: ${err.message}`);
-    process.exitCode = 1;
+    // codex failed to start. The fix that matters is that we EXIT (instead of
+    // leaving a childless wrapper alive on the client's open stdin, which used
+    // to hang). `emit` synthesizes an error only if a request was already
+    // tracked; spawn 'error' usually fires before any stdin is read, so the
+    // client typically just sees the server exit — the conventional
+    // "server failed to start".
+    finalize({
+      reason: `codex spawn error: ${err.message}`,
+      emit: true,
+      exitCode: 1,
+    });
   });
 
-  child.on("exit", (code, signal) => {
-    cleanupIsolatedCodexHome();
-    if (signal) {
-      logErr(`[mcp-agents] codex killed by ${signal}`);
-      process.exitCode = 128 + (SIGNAL_CODES[signal] ?? 0);
-    } else {
-      if (code !== 0) logErr(`[mcp-agents] codex exited with code ${code}`);
-      process.exitCode = code ?? 1;
+  // codex death is handled via BOTH 'exit' and 'close':
+  //  - 'exit' fires when the codex PROCESS terminates. A descendant that
+  //    inherited codex's stdio can hold those pipes open, delaying or even
+  //    preventing 'close' (and would be orphaned), so we kill the group here to
+  //    reap it — which also lets 'close' fire. A ref'd fallback guarantees
+  //    teardown even if a descendant escaped the group (setsid) so 'close'
+  //    never arrives.
+  //  - 'close' fires once all stdio is drained, so codex's final response has
+  //    been delivered and its id cleared — only THEN do we decide whether to
+  //    synthesize, which avoids double-responding.
+  let childExitInfo = null;
+  const onChildGone = () => {
+    const code = childExitInfo?.code;
+    const signal = childExitInfo?.signal;
+    if (signal) logErr(`[mcp-agents] codex killed by ${signal}`);
+    else if (code != null && code !== 0) {
+      logErr(`[mcp-agents] codex exited with code ${code}`);
     }
+    finalize({
+      reason: signal ? `codex killed by ${signal}` : `codex exited (code ${code})`,
+      emit: true,
+      exitCode: signal ? 128 + (SIGNAL_CODES[signal] ?? 0) : (code ?? 1),
+    });
+  };
+
+  child.on("exit", (code, signal) => {
+    childExitInfo = { code, signal };
+    killGroup("SIGKILL");
+    setTimeout(onChildGone, 2_000);
+  });
+  child.on("close", (code, signal) => {
+    if (!childExitInfo) childExitInfo = { code, signal };
+    onChildGone();
   });
 }
 
@@ -673,6 +1230,8 @@ async function main() {
     modelReasoningEffort,
     sandboxMode,
     approvalPolicy,
+    goal,
+    codexIdleTimeoutMs,
     defaultTimeoutMs,
   } = parseArgs();
   const backend = CLI_BACKENDS[providerName];
@@ -690,6 +1249,8 @@ async function main() {
       modelReasoningEffort,
       sandboxMode,
       approvalPolicy,
+      goal,
+      idleTimeoutMs: codexIdleTimeoutMs,
     });
     return;
   }