mcp-agents 0.11.0 → 0.12.1

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,62 @@ 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 (it
+is never a native Codex parameter). 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).
+
+So a client's model knows it can pass `goal`, the pass-through advertises it: it
+rewrites its own `tools/list` response to declare an optional `goal` property on
+the `codex` and `codex-reply` tool schemas (models only generate arguments
+declared in a tool's `inputSchema`). Only `properties` is augmented — `required`
+and `additionalProperties` are left intact — and the rewrite touches only the
+`tools/list` response; every other frame is forwarded byte-for-byte.
+
+**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
@@ -146,7 +203,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.11.0",
+  "version": "0.12.1",
   "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

@@ -192,6 +192,10 @@ 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]
@@ -202,8 +206,9 @@ Options:
 /**
  * Parse CLI flags from process.argv.
  * Handles --help, --version, --provider, --model, --model_reasoning_effort,
- * --sandbox_mode, --approval_policy, --codex_idle_timeout, and unknown flags.
- * @returns {{ provider: string, model?: string, modelReasoningEffort?: string, sandboxMode?: string, approvalPolicy?: string, codexIdleTimeoutMs?: number, 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);
@@ -212,6 +217,7 @@ function parseArgs() {
   let modelReasoningEffort;
   let sandboxMode;
   let approvalPolicy;
+  let goal;
   let codexIdleTimeoutMs;
   let defaultTimeoutMs;
 
@@ -264,6 +270,13 @@ 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");
@@ -304,6 +317,7 @@ function parseArgs() {
     modelReasoningEffort,
     sandboxMode,
     approvalPolicy,
+    goal,
     codexIdleTimeoutMs,
     defaultTimeoutMs,
   };
@@ -512,19 +526,69 @@ function createIsolatedCodexHome({
   }
 }
 
+/**
+ * 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;
+}
+
+/**
+ * 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;
 
@@ -567,14 +631,100 @@ 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);
 }
 
+// Tools whose advertised inputSchema gains a wrapper-only `goal` property so a
+// client's model knows it can pass one (the model only emits args declared in
+// the schema). The arg is stripped inbound by filterCodexToolCall before it
+// reaches codex; advertising it here is purely for discoverability.
+const CODEX_GOAL_TOOLS = new Set(["codex", "codex-reply"]);
+const CODEX_GOAL_PROPERTY_DESCRIPTION =
+  "Optional standing objective for this Codex session. mcp-agents injects it as " +
+  "`developer-instructions` (codex) or a prompt reminder (codex-reply); it is not a " +
+  "native Codex parameter. Overrides the server-wide --goal default for this call; " +
+  "pass an empty string to suppress that default.";
+
+/**
+ * Mutate a parsed `tools/list` RESPONSE in place, adding a `goal` property to the
+ * advertised inputSchema of the `codex` and `codex-reply` tools. Returns true iff
+ * it added `goal` to at least one tool. Only `properties` is touched — `required`
+ * and `additionalProperties` are left intact (a declared property is not an
+ * "additional" one, so `additionalProperties:false` stays valid). Best-effort per
+ * tool: a target tool that already declares `goal` (idempotent) or whose
+ * inputSchema.properties is missing/malformed (drifted schema) is simply skipped;
+ * other valid targets are still augmented. Returns false (→ the caller forwards the
+ * original bytes byte-for-byte) for an error response, a non-array `result.tools`,
+ * or when no `codex`/`codex-reply` target was augmentable.
+ * @param {any} msg
+ * @returns {boolean}
+ */
+function injectGoalIntoToolsListMessage(msg) {
+  const tools = msg?.result?.tools;
+  if (!Array.isArray(tools)) return false;
+  let changed = false;
+  for (const tool of tools) {
+    if (!tool || typeof tool !== "object" || !CODEX_GOAL_TOOLS.has(tool.name)) continue;
+    const schema = tool.inputSchema;
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) continue;
+    const props = schema.properties;
+    if (!props || typeof props !== "object" || Array.isArray(props)) continue;
+    if ("goal" in props) continue; // idempotent — respect an existing declaration
+    props.goal = { type: "string", description: CODEX_GOAL_PROPERTY_DESCRIPTION };
+    changed = true;
+  }
+  return changed;
+}
+
 /**
  * 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
@@ -582,7 +732,7 @@ function filterCodexToolCall(line) {
  * 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 }} opts
+ * @param {{ model?: string, modelReasoningEffort?: string, sandboxMode?: string, approvalPolicy?: string, idleTimeoutMs?: number, goal?: string }} opts
  */
 function runCodexPassthrough({
   model,
@@ -590,6 +740,7 @@ function runCodexPassthrough({
   sandboxMode,
   approvalPolicy,
   idleTimeoutMs,
+  goal,
 }) {
   const resolvedModel = model || DEFAULT_CODEX_MODEL;
   const resolvedModelReasoningEffort =
@@ -597,6 +748,8 @@ function runCodexPassthrough({
   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 {
@@ -631,6 +784,7 @@ function runCodexPassthrough({
     `[mcp-agents] passthrough: codex ${args.join(" ")} ` +
       `(model=${resolvedModel}, reasoning_effort=${resolvedModelReasoningEffort}, ` +
       `sandbox_mode=${resolvedSandboxMode}, approval_policy=${resolvedApprovalPolicy}, ` +
+      `goal=${resolvedGoal && resolvedGoal.trim() ? "set" : "none"}, ` +
       `idle_timeout_ms=${resolvedIdleTimeoutMs}, isolated_home=true)`,
   );
 
@@ -700,6 +854,18 @@ function runCodexPassthrough({
   let droppedFrameResponseId; // partial oversized frame's classified id (cleared at its newline)
   let observationDropLogged = false; // log the first observation-cap drop only
 
+  // ── tools/list goal-advertising rewrite (contained latch) ────────────────
+  // While a `tools/list` request id is outstanding the forwarder switches from
+  // raw passthrough to buffer-and-rewrite, injecting a `goal` property into the
+  // advertised codex/codex-reply schemas of that one response, then returns to
+  // raw. Observation above stays the SOLE authority for inFlight/the watchdog;
+  // this path only changes HOW bytes reach the wire.
+  const pendingToolsListIds = new Set(); // idKey(id) of outstanding tools/list requests (the latch)
+  let rewriteBuf = Buffer.alloc(0); // buffer-mode accumulator; holds ≤1 trailing partial after a flush
+  let rewriteSkipUntilNewline = false; // forwarding raw to the next newline (oversized frame or mode-boundary align)
+  let rewriteSkipReleaseId; // idKey to release when the skipped frame's newline lands (oversized response only)
+  let oversizedToolsListLogged = false; // log the first rewrite-cap drop only
+
   const killGroup = (signal) => {
     try {
       if (child.pid) process.kill(-child.pid, signal);
@@ -884,10 +1050,53 @@ function runCodexPassthrough({
     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) {
+      // Framing recovery. Precedence handles bytes WITHHELD by buffer mode (which
+      // the plain stdoutObsBuf recovery would mis-handle). EVERY write here is
+      // try/catch-guarded: finalize runs synchronously from close/exit/idle/signal
+      // handlers, so an unguarded EPIPE would escape into uncaughtException ->
+      // fatalShutdown -> a re-entrant finalize early-return, skipping
+      // flushThenExit/process.exit and hanging the wrapper.
+      if (rewriteSkipUntilNewline) {
+        // Oversized/align mid-skip: head already forwarded raw, remainder
+        // unrecoverable. Discard; the -32001 loop covers the still-open id.
+        rewriteBuf = Buffer.alloc(0);
+        rewriteSkipUntilNewline = false;
+        stdoutObsBuf = Buffer.alloc(0);
+        if (!lastForwardedByteWasNewline) {
+          try { process.stdout.write("\n"); } catch {}
+          lastForwardedByteWasNewline = true;
+        }
+      } else if (rewriteBuf.length > 0) {
+        // A withheld buffered partial (never forwarded). If it parses as a COMPLETE
+        // message (only its trailing newline missing) — possible only when the whole
+        // frame arrived post-latch, so NONE of it is on the wire — deliver it
+        // (rewritten if a pending tools/list response, else raw) + "\n" and clear its
+        // id (no -32001). Otherwise (a mode-boundary tail — pre-empted by the
+        // align-skip — or codex died mid-frame) discard; the -32001 loop covers it.
+        const frameStr = rewriteBuf.toString("utf8");
+        let outStr = null;
+        try {
+          const m = JSON.parse(frameStr);
+          outStr = frameStr;
+          if (
+            m && typeof m === "object" && "id" in m &&
+            ("result" in m || "error" in m) &&
+            pendingToolsListIds.has(idKey(m.id)) && injectGoalIntoToolsListMessage(m)
+          ) {
+            outStr = JSON.stringify(m);
+          }
+        } catch { outStr = null; }
+        rewriteBuf = Buffer.alloc(0);
+        stdoutObsBuf = Buffer.alloc(0);
+        if (outStr !== null) {
+          try { process.stdout.write(`${outStr}\n`); } catch {}
+          observeOutgoingLine(frameStr); // clear its id -> no synthetic error for it
+          lastForwardedByteWasNewline = true;
+        } else if (!lastForwardedByteWasNewline) {
+          try { process.stdout.write("\n"); } catch {}
+          lastForwardedByteWasNewline = true;
+        }
+      } else if (stdoutObsBuf.length > 0) {
         observeOutgoingLine(stdoutObsBuf.toString("utf8"));
         stdoutObsBuf = Buffer.alloc(0);
         try { process.stdout.write("\n"); } catch {}
@@ -914,6 +1123,12 @@ function runCodexPassthrough({
       }
     }
 
+    // Hygiene: drop the rewrite latch/skip state (forwarding has stopped).
+    pendingToolsListIds.clear();
+    rewriteSkipUntilNewline = false;
+    rewriteSkipReleaseId = undefined;
+    rewriteBuf = Buffer.alloc(0);
+
     flushThenExit(exitCode);
   };
 
@@ -953,35 +1168,153 @@ function runCodexPassthrough({
     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.
+  const logRewriteDropOnce = () => {
+    if (!oversizedToolsListLogged) {
+      logErr(
+        "[mcp-agents] codex passthrough: tools/list-window frame exceeded rewrite cap; " +
+          "forwarding raw (goal not advertised on this response)",
+      );
+      oversizedToolsListLogged = true;
+    }
+  };
+
+  // Raw forward of one buffer plus the existing first-`!ok` backpressure handling
+  // (pause codex + suspend the watchdog until drain). Returns the write result.
+  // Used by BOTH the raw fast path and buffer mode, so the wire-state tracking and
+  // backpressure contract live in exactly one place.
+  const forwardChunk = (buf) => {
+    if (buf.length === 0) return true;
+    lastForwardedByteWasNewline = buf[buf.length - 1] === NEWLINE;
+    const ok = process.stdout.write(buf);
+    if (!ok && !stdoutPaused) {
+      // Downstream full: pause codex and suspend the idle watchdog until the
+      // client drains, so a slow reader is never mistaken for a stalled codex.
+      stdoutPaused = true;
+      clearIdle();
+      child.stdout.pause();
+    }
+    return ok;
+  };
+
+  // Once no tools/list id is outstanding (and not mid-skip), a trailing partial in
+  // rewriteBuf is a NON-tools/list frame (no response expected), so it must not stay
+  // withheld in buffer mode — raw mode forwards partials as they arrive, and
+  // withholding it would byte-lose it if codex dies before its newline. Forward it
+  // raw and drop back to the fast path. Called from BOTH paths that can clear the
+  // latch: the end of flushRewriteBuf (a response completed) and noteInbound's
+  // cancel branch (a tools/list was canceled on stdin, which never runs the flush).
+  const returnToRawIfLatchClear = () => {
+    if (
+      !finalizing && pendingToolsListIds.size === 0 &&
+      !rewriteSkipUntilNewline && rewriteBuf.length > 0
+    ) {
+      forwardChunk(rewriteBuf);
+      rewriteBuf = Buffer.alloc(0);
+    }
+  };
+
+  // Flush every COMPLETE frame from rewriteBuf, rewriting only the matched
+  // tools/list response and forwarding everything else byte-for-byte. NEVER
+  // early-returns on backpressure: forwardChunk pauses codex on the first `!ok`,
+  // but this chunk's frames are all queued (Node buffers regardless), so no
+  // COMPLETE frame is ever stranded — exactly today's "one write(chunk), then
+  // pause the source" semantics. After this returns rewriteBuf holds at most one
+  // trailing INCOMPLETE partial.
+  const flushRewriteBuf = () => {
+    if (rewriteSkipUntilNewline) {
+      const nl = rewriteBuf.indexOf(NEWLINE);
+      if (nl === -1) {
+        // Still inside the skipped/aligned frame: forward it all raw, stay skipping.
+        forwardChunk(rewriteBuf);
+        rewriteBuf = Buffer.alloc(0);
+        return;
+      }
+      forwardChunk(rewriteBuf.subarray(0, nl + 1)); // forward through the newline raw
+      rewriteBuf = rewriteBuf.subarray(nl + 1);
+      if (rewriteSkipReleaseId !== undefined) {
+        pendingToolsListIds.delete(rewriteSkipReleaseId);
+        rewriteSkipReleaseId = undefined;
+      }
+      rewriteSkipUntilNewline = false;
+    }
+    let nl;
+    while ((nl = rewriteBuf.indexOf(NEWLINE)) !== -1) {
+      const frameBytes = rewriteBuf.subarray(0, nl + 1); // original bytes incl. delimiter
+      rewriteBuf = rewriteBuf.subarray(nl + 1); // consume-first: never re-forward, never wedge
+      if (nl > MAX_BUFFER_BYTES) {
+        // Complete frame larger than the cap: forward raw without parsing (mirrors
+        // observeOutgoing's oversized branch), releasing only a matching pending id.
+        logRewriteDropOnce();
+        const pid = peekResponseId(frameBytes);
+        if (pid !== undefined && pendingToolsListIds.has(idKey(pid))) {
+          pendingToolsListIds.delete(idKey(pid));
+        }
+        forwardChunk(frameBytes);
+        continue;
+      }
+      let outBuf = frameBytes; // default: byte-for-byte
+      try {
+        const msg = JSON.parse(
+          frameBytes.subarray(0, frameBytes.length - 1).toString("utf8"),
+        );
+        if (
+          msg && typeof msg === "object" && "id" in msg &&
+          ("result" in msg || "error" in msg) &&
+          pendingToolsListIds.has(idKey(msg.id))
+        ) {
+          pendingToolsListIds.delete(idKey(msg.id));
+          if (injectGoalIntoToolsListMessage(msg)) {
+            outBuf = Buffer.from(`${JSON.stringify(msg)}\n`, "utf8");
+          }
+        }
+      } catch {
+        outBuf = frameBytes; // unparseable (mode-boundary tail / partial) — forward original bytes
+      }
+      forwardChunk(outBuf);
+    }
+    if (rewriteBuf.length > MAX_BUFFER_BYTES) {
+      // Partial frame already past the cap with no newline: abandon rewriting for
+      // THIS frame, forward what we have raw, and skip to its newline. Release only
+      // a matching id, deferred to that newline.
+      logRewriteDropOnce();
+      const pid = peekResponseId(rewriteBuf);
+      rewriteSkipReleaseId =
+        pid !== undefined && pendingToolsListIds.has(idKey(pid)) ? idKey(pid) : undefined;
+      forwardChunk(rewriteBuf);
+      rewriteBuf = Buffer.alloc(0);
+      rewriteSkipUntilNewline = true;
+    }
+    // Latch boundary: a response just completed may have emptied the latch — if so,
+    // flush any trailing NON-tools/list partial raw and return to the fast path.
+    returnToRawIfLatchClear();
+  };
+  const bufferModeForward = (chunk) => {
+    rewriteBuf = rewriteBuf.length ? Buffer.concat([rewriteBuf, chunk]) : chunk;
+    flushRewriteBuf();
+  };
+
+  // Forward codex stdout to the client. Steady state is a byte-for-byte raw
+  // passthrough (forwardChunk); while a tools/list response is pending the
+  // forwarder buffers and rewrites that one frame (bufferModeForward) to advertise
+  // `goal`. Observation runs on the ORIGINAL bytes and stays the sole authority for
+  // clearing in-flight ids — by the time it runs, every complete frame in this
+  // chunk was already forwarded/queued, so it never leads forwarding.
   child.stdout.on("data", (chunk) => {
     if (finalizing) return; // stream ownership has been taken over
-    resetIdle();
+    resetIdle(); // UNCONDITIONAL, before the mode branch — buffer-mode activity must keep the watchdog alive
 
-    // 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;
+    if (pendingToolsListIds.size > 0 || rewriteBuf.length > 0 || rewriteSkipUntilNewline) {
+      bufferModeForward(chunk);
+    } else {
+      forwardChunk(chunk);
     }
-    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", () => {
@@ -1018,7 +1351,16 @@ function runCodexPassthrough({
     // so even an elicitation response — bare id, no method — keeps a healthy
     // interactive flow alive.)
     if (msg.method === "notifications/cancelled") {
-      cancelInFlight(msg.params?.requestId);
+      const rid = msg.params?.requestId;
+      cancelInFlight(rid);
+      // A canceled/never-answered tools/list must not wedge buffer mode open. If
+      // this cancel cleared the last pending tools/list id while a NON-tools/list
+      // partial is withheld in rewriteBuf, flush it raw — otherwise a codex exit
+      // with only-canceled work would drop those bytes (finalize skips recovery).
+      if (rid != null) {
+        pendingToolsListIds.delete(idKey(rid));
+        returnToRawIfLatchClear();
+      }
       return;
     }
     // A client message awaits a response iff it carries BOTH an id and a method.
@@ -1026,6 +1368,22 @@ function runCodexPassthrough({
     // for in-flight tracking.
     if (msg.id != null && typeof msg.method === "string") {
       addInFlight(msg.id);
+      if (msg.method === "tools/list") {
+        // Arm the goal-advertising rewrite latch for this tools/list response. If
+        // buffer mode would START mid-frame (a pre-latch frame's head was already
+        // raw-forwarded and its newline hasn't arrived), first align by raw-skipping
+        // the orphan tail to its next newline — so the tail is forwarded
+        // byte-for-byte and never mis-parsed as a standalone frame nor byte-lost at
+        // finalize. Equivalent to today's raw behaviour for that straddled frame.
+        if (
+          pendingToolsListIds.size === 0 && rewriteBuf.length === 0 &&
+          !rewriteSkipUntilNewline && !lastForwardedByteWasNewline
+        ) {
+          rewriteSkipUntilNewline = true;
+          rewriteSkipReleaseId = undefined;
+        }
+        pendingToolsListIds.add(idKey(msg.id));
+      }
     }
   };
 
@@ -1043,7 +1401,7 @@ function runCodexPassthrough({
       const line = stdinBuf.subarray(0, nl).toString("utf8");
       stdinBuf = stdinBuf.subarray(nl + 1);
       noteInbound(line);
-      child.stdin.write(`${filterCodexToolCall(line)}\n`);
+      child.stdin.write(`${filterCodexToolCall(line, { serverGoal: resolvedGoal })}\n`);
     }
   });
   process.stdin.on("error", () => {});
@@ -1051,7 +1409,7 @@ function runCodexPassthrough({
     if (stdinBuf.length > 0) {
       const line = stdinBuf.toString("utf8");
       noteInbound(line);
-      child.stdin.write(filterCodexToolCall(line));
+      child.stdin.write(filterCodexToolCall(line, { serverGoal: resolvedGoal }));
     }
     child.stdin.end();
   });
@@ -1118,6 +1476,7 @@ async function main() {
     modelReasoningEffort,
     sandboxMode,
     approvalPolicy,
+    goal,
     codexIdleTimeoutMs,
     defaultTimeoutMs,
   } = parseArgs();
@@ -1136,6 +1495,7 @@ async function main() {
       modelReasoningEffort,
       sandboxMode,
       approvalPolicy,
+      goal,
       idleTimeoutMs: codexIdleTimeoutMs,
     });
     return;