@leo000001/codex-mcp 0.2.0 → 2.0.0

package/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `approvalPolicy`, `sandbox`, and `effort` are now **required** parameters in the `codex` tool — callers must explicitly set based on their own permission level and task complexity
 - `effort` parameter promoted from `advanced.effort` to top-level parameter in the `codex` tool
 - `codex_reply` parameter `sandboxPolicy` renamed to `sandbox`
+- `codex_check` parameter `execpolicyAmendment` renamed to `execpolicy_amendment` to match app-server protocol field naming
 
 ### Changed
 
@@ -23,6 +24,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Approval and user-input timeout timers now call `.unref()` to avoid blocking process exit
 - Documentation aligned with implementation details for event eviction and e2e guidance
 - Tool input defaults are now defined in schema (`cursor`, `maxEvents`, `includeSensitive`, `advanced.approvalTimeoutMs`) and client-facing text avoids duplicated default descriptions
+- `codex_session` adds `clean_background_terminals` action to call `thread/background_terminals/clean`
+- Approval action payloads now expose `approvalId` and `networkApprovalContext` when provided by app-server
 
 ## [0.1.0] - 2026-02-15
 

package/README.md

@@ -57,18 +57,23 @@ Add to your MCP client config (e.g. Claude Desktop, Cursor, etc.):
 }
 ```
 
-### OpenAI Codex CLI
+### Claude Code
 
 ```bash
-codex mcp add codex-mcp -- npx -y @leo000001/codex-mcp
+claude mcp add codex-mcp -- npx -y @leo000001/codex-mcp
 ```
 
-Or add to `~/.codex/config.toml`:
+Or add to `~/.claude/settings.json`:
 
-```toml
-[mcp_servers.codex-mcp]
-command = "npx"
-args = ["-y", "@leo000001/codex-mcp"]
+```json
+{
+  "mcpServers": {
+    "codex-mcp": {
+      "command": "npx",
+      "args": ["-y", "@leo000001/codex-mcp"]
+    }
+  }
+}
 ```
 
 ## STDIO Guard Modes
@@ -95,16 +100,16 @@ $env:CODEX_MCP_STDIO_MODE = "strict"; npx -y @leo000001/codex-mcp
 
 Start a Codex agent session asynchronously. Returns immediately with `sessionId`.
 
-| Parameter        | Type   | Required | Description                                                                                                            |
-| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `prompt`         | string | Yes      | Task or question for the Codex agent                                                                                   |
-| `approvalPolicy` | string | Yes      | Approval policy: `untrusted`, `on-failure`, `on-request`, `never` — caller must set based on its own permission level  |
-| `sandbox`        | string | Yes      | Sandbox mode: `read-only`, `workspace-write`, `danger-full-access` — caller must set based on its own permission level |
+| Parameter        | Type   | Required | Description                                                                                                                       |
+| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt`         | string | Yes      | Task or question for the Codex agent                                                                                              |
+| `approvalPolicy` | string | Yes      | Approval policy: `untrusted`, `on-failure`, `on-request`, `never` — caller must set based on its own permission level             |
+| `sandbox`        | string | Yes      | Sandbox mode: `read-only`, `workspace-write`, `danger-full-access` — caller must set based on its own permission level            |
 | `effort`         | string | No       | Reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. Default: `low`; increase/decrease based on task complexity |
-| `cwd`            | string | No       | Working directory. Default: server cwd                                                                                 |
-| `model`          | string | No       | Model override. Default: from `~/.codex/config.toml`                                                                   |
-| `profile`        | string | No       | `config.toml` profile name (passed as `codex app-server -p`)                                                           |
-| `advanced`       | object | No       | Low-frequency options (see below)                                                                                      |
+| `cwd`            | string | No       | Working directory. Default: server cwd                                                                                            |
+| `model`          | string | No       | Model override. Default: from `~/.codex/config.toml`                                                                              |
+| `profile`        | string | No       | `config.toml` profile name (passed as `codex app-server -p`)                                                                      |
+| `advanced`       | object | No       | Low-frequency options (see below)                                                                                                 |
 
 <details>
 <summary><code>advanced</code> object parameters (9 low-frequency parameters)</summary>
@@ -175,12 +180,12 @@ Send a follow-up message to an existing session.
 
 ### `codex_session` — Manage sessions
 
-List, inspect, cancel, interrupt, or fork sessions.
+List, inspect, cancel, interrupt, fork sessions, or clean background terminals.
 
 | Parameter          | Type    | Required                      | Description                                                            |
 | ------------------ | ------- | ----------------------------- | ---------------------------------------------------------------------- |
-| `action`           | string  | Yes                           | `"list"`, `"get"`, `"cancel"`, `"interrupt"`, or `"fork"`              |
-| `sessionId`        | string  | For get/cancel/interrupt/fork | Target session ID                                                      |
+| `action`           | string  | Yes                           | `"list"`, `"get"`, `"cancel"`, `"interrupt"`, `"fork"`, or `"clean_background_terminals"` |
+| `sessionId`        | string  | For get/cancel/interrupt/fork/clean_background_terminals | Target session ID                                                      |
 | `includeSensitive` | boolean | No                            | Include `cwd`/`profile`/`config`/`threadId` in `get`. Default: `false` |
 
 **Returns:**
@@ -188,6 +193,7 @@ List, inspect, cancel, interrupt, or fork sessions.
 - `action="get"` → `PublicSessionInfo` (or `SensitiveSessionInfo` when `includeSensitive=true`)
 - `action="cancel"|"interrupt"` → `{ success: true, message }`
 - `action="fork"` → `{ sessionId, threadId, status: "idle", pollInterval }`
+- `action="clean_background_terminals"` → `{ success: true, message }`
 
 ```json
 { "action": "list" }
@@ -195,6 +201,7 @@ List, inspect, cancel, interrupt, or fork sessions.
 { "action": "cancel", "sessionId": "sess_abc123" }
 { "action": "interrupt", "sessionId": "sess_abc123" }
 { "action": "fork", "sessionId": "sess_abc123" }
+{ "action": "clean_background_terminals", "sessionId": "sess_abc123" }
 ```
 
 ### `codex_check` — Poll events & respond
@@ -203,15 +210,15 @@ Query a running session for events, respond to approval requests, or answer user
 
 | Parameter             | Type     | Required                          | Description                                                                                                                                                                                      |
 | --------------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `action`              | string   | Yes                               | `"poll"`, `"respond_permission"`, `"respond_approval"` (deprecated alias), or `"respond_user_input"`                                                                                            |
+| `action`              | string   | Yes                               | `"poll"`, `"respond_permission"`, or `"respond_user_input"`                                                                                                                                    |
 | `sessionId`           | string   | Yes                               | Target session ID                                                                                                                                                                                |
-| `cursor`              | number   | No                                | Event cursor for incremental polling (`action="poll"`). For `respond_*`, codex-mcp applies monotonic cursor progression: `max(cursor, sessionLastCursor)`.                                   |
-| `maxEvents`           | number   | No                                | Keep this small. `poll` default: `1` (minimum `1`; increase only for catch-up). `respond_*` default: `0` (recommended; compact ACK, no event replay).                                           |
-| `responseMode`        | string   | No                                | Response shaping mode: `minimal` (default), `delta_compact`, `full`                                                                                                                             |
-| `pollOptions`         | object   | No                                | Optional controls: `includeEvents` (default `true`), `includeActions` (default `true`), `includeResult` (default `true`), `maxBytes` (default unlimited)                                       |
+| `cursor`              | number   | No                                | Event cursor for incremental polling (`action="poll"`). For `respond_*`, codex-mcp applies monotonic cursor progression: `max(cursor, sessionLastCursor)`.                                       |
+| `maxEvents`           | number   | No                                | Keep this small. `poll` default: `1` (minimum `1`; increase only for catch-up). `respond_*` default: `0` (recommended; compact ACK, no event replay).                                            |
+| `responseMode`        | string   | No                                | Response shaping mode: `minimal` (default), `delta_compact`, `full`                                                                                                                              |
+| `pollOptions`         | object   | No                                | Optional controls: `includeEvents` (default `true`), `includeActions` (default `true`), `includeResult` (default `true`), `maxBytes` (default unlimited)                                         |
 | `requestId`           | string   | For respond_permission/user_input | Request ID from `actions[]`                                                                                                                                                                      |
 | `decision`            | string   | For respond_permission            | For command approvals: `"accept"`, `"acceptForSession"`, `"acceptWithExecpolicyAmendment"`, `"decline"`, `"cancel"`; for file changes: `"accept"`, `"acceptForSession"`, `"decline"`, `"cancel"` |
-| `execpolicyAmendment` | string[] | For acceptWithExecpolicyAmendment | Exec policy amendment list (required when `decision="acceptWithExecpolicyAmendment"`)                                                                                                            |
+| `execpolicy_amendment` | string[] | For acceptWithExecpolicyAmendment | Exec policy amendment list (required when `decision="acceptWithExecpolicyAmendment"`)                                                                                                            |
 | `denyMessage`         | string   | No                                | Internal note on deny (not sent to app-server)                                                                                                                                                   |
 | `answers`             | object   | For respond_user_input            | For `respond_user_input`: `questionId -> { answers: string[] }`                                                                                                                                  |
 
@@ -259,8 +266,7 @@ Approvals/results/errors are pinned to reduce eviction risk.
 When the agent requests approval or user input, `poll` includes an `actions[]` list. Respond with:
 
 - `respond_permission`: `decision` is one of `accept`, `acceptForSession`, `decline`, `cancel`.
-  - For command approvals, `acceptWithExecpolicyAmendment` is supported and requires `execpolicyAmendment`.
-- `respond_approval` is still accepted as a deprecated alias for `respond_permission`.
+  - For command approvals, `acceptWithExecpolicyAmendment` is supported and requires `execpolicy_amendment`.
 - `respond_user_input`: send `answers` keyed by `questionId`.
 
 Pending approvals auto-decline after `advanced.approvalTimeoutMs`.

package/dist/index.js

@@ -34,6 +34,7 @@ var Methods = {
   THREAD_START: "thread/start",
   THREAD_RESUME: "thread/resume",
   THREAD_FORK: "thread/fork",
+  THREAD_BACKGROUND_TERMINALS_CLEAN: "thread/backgroundTerminals/clean",
   TURN_START: "turn/start",
   TURN_INTERRUPT: "turn/interrupt",
   TURN_STEER: "turn/steer",
@@ -48,19 +49,31 @@ var Methods = {
   // Server → Client notifications
   ERROR: "error",
   THREAD_STARTED: "thread/started",
+  THREAD_ARCHIVED: "thread/archived",
+  THREAD_UNARCHIVED: "thread/unarchived",
+  THREAD_NAME_UPDATED: "thread/name/updated",
+  THREAD_TOKEN_USAGE_UPDATED: "thread/tokenUsage/updated",
   TURN_STARTED: "turn/started",
   TURN_COMPLETED: "turn/completed",
   TURN_DIFF_UPDATED: "turn/diff/updated",
   TURN_PLAN_UPDATED: "turn/plan/updated",
   ITEM_STARTED: "item/started",
   ITEM_COMPLETED: "item/completed",
+  RAW_RESPONSE_ITEM_COMPLETED: "rawResponseItem/completed",
   AGENT_MESSAGE_DELTA: "item/agentMessage/delta",
   COMMAND_OUTPUT_DELTA: "item/commandExecution/outputDelta",
+  COMMAND_TERMINAL_INTERACTION: "item/commandExecution/terminalInteraction",
   FILE_CHANGE_OUTPUT_DELTA: "item/fileChange/outputDelta",
   REASONING_TEXT_DELTA: "item/reasoning/textDelta",
   REASONING_SUMMARY_DELTA: "item/reasoning/summaryTextDelta",
+  REASONING_SUMMARY_PART_ADDED: "item/reasoning/summaryPartAdded",
   PLAN_DELTA: "item/plan/delta",
   MCP_TOOL_PROGRESS: "item/mcpToolCall/progress",
+  MODEL_REROUTED: "model/rerouted",
+  FUZZY_FILE_SEARCH_SESSION_UPDATED: "fuzzyFileSearch/sessionUpdated",
+  FUZZY_FILE_SEARCH_SESSION_COMPLETED: "fuzzyFileSearch/sessionCompleted",
+  WINDOWS_WORLD_WRITABLE_WARNING: "windows/worldWritableWarning",
+  ACCOUNT_LOGIN_COMPLETED: "account/login/completed",
   SESSION_CONFIGURED: "sessionConfigured"
 };
 
@@ -164,13 +177,15 @@ var SANDBOX_MODES = ["read-only", "workspace-write", "danger-full-access"];
 var PERSONALITIES = ["none", "friendly", "pragmatic"];
 var EFFORT_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh"];
 var SUMMARY_MODES = ["auto", "concise", "detailed", "none"];
-var SESSION_ACTIONS = ["list", "get", "cancel", "interrupt", "fork"];
-var CHECK_ACTIONS = [
-  "poll",
-  "respond_permission",
-  "respond_approval",
-  "respond_user_input"
+var SESSION_ACTIONS = [
+  "list",
+  "get",
+  "cancel",
+  "interrupt",
+  "fork",
+  "clean_background_terminals"
 ];
+var CHECK_ACTIONS = ["poll", "respond_permission", "respond_user_input"];
 var RESPONSE_MODES = ["minimal", "delta_compact", "full"];
 var COMMAND_DECISIONS = [
   "accept",
@@ -218,7 +233,7 @@ var DEFAULT_TERMINAL_CLEANUP_MS = 5 * 60 * 1e3;
 var CLEANUP_INTERVAL_MS = 6e4;
 
 // src/app-server/client.ts
-var CLIENT_VERSION = true ? "0.2.0" : "0.0.0-dev";
+var CLIENT_VERSION = true ? "2.0.0" : "0.0.0-dev";
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var STARTUP_REQUEST_TIMEOUT = 9e4;
 var MAX_WRITE_QUEUE_BYTES = 5 * 1024 * 1024;
@@ -335,6 +350,9 @@ var AppServerClient = class extends EventEmitter {
   async threadResume(params) {
     return this.request(Methods.THREAD_RESUME, params);
   }
+  async threadBackgroundTerminalsClean(params) {
+    return this.request(Methods.THREAD_BACKGROUND_TERMINALS_CLEAN, params);
+  }
   async turnStart(params, timeout = STARTUP_REQUEST_TIMEOUT) {
     return this.request(Methods.TURN_START, params, timeout);
   }
@@ -964,6 +982,32 @@ var SessionManager = class {
       turnId: session.activeTurnId
     });
   }
+  async cleanBackgroundTerminals(sessionId) {
+    const session = this.getSessionOrThrow(sessionId);
+    const client = this.getClientOrThrow(sessionId);
+    if (session.status === "cancelled") {
+      throw new Error(
+        `Error [${"CANCELLED" /* CANCELLED */}]: Session '${sessionId}' has been cancelled and cannot be cleaned`
+      );
+    }
+    if (!session.threadId) {
+      throw new Error(
+        `Error [${"INTERNAL" /* INTERNAL */}]: Session '${sessionId}' has no threadId, cannot clean background terminals`
+      );
+    }
+    await client.threadBackgroundTerminalsClean({ threadId: session.threadId });
+    session.lastActiveAt = (/* @__PURE__ */ new Date()).toISOString();
+    pushEvent(
+      session.eventBuffer,
+      "progress",
+      {
+        method: Methods.THREAD_BACKGROUND_TERMINALS_CLEAN,
+        threadId: session.threadId,
+        status: "requested"
+      },
+      true
+    );
+  }
   async forkSession(sessionId) {
     const session = this.getSessionOrThrow(sessionId);
     const originalClient = this.getClientOrThrow(sessionId);
@@ -1069,6 +1113,8 @@ var SessionManager = class {
             params: req.params,
             itemId: req.itemId,
             reason: req.reason,
+            approvalId: req.approvalId,
+            networkApprovalContext: req.networkApprovalContext,
             createdAt: req.createdAt
           });
         }
@@ -1084,13 +1130,6 @@ var SessionManager = class {
       actions: actions.length > 0 ? actions : void 0,
       result: includeResult && (session.status === "idle" || session.status === "error" || session.status === "cancelled") ? session.lastResult : void 0
     };
-    if (pollOptions?.includeTools === true) {
-      addCompatWarningWithinBudget(
-        result,
-        "pollOptions.includeTools is not yet supported by codex-mcp; returning no tool metadata.",
-        maxBytes
-      );
-    }
     if (typeof maxBytes === "number") {
       const normalizedMaxBytes = Math.max(1, Math.floor(maxBytes));
       const hasAnyPayload = result.events.length > 0 || typeof result.actions !== "undefined" || typeof result.result !== "undefined";
@@ -1179,9 +1218,9 @@ var SessionManager = class {
           `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: Invalid command decision '${decision}'`
         );
       }
-      if (decision === "acceptWithExecpolicyAmendment" && (!extra?.execpolicyAmendment || extra.execpolicyAmendment.length === 0)) {
+      if (decision === "acceptWithExecpolicyAmendment" && (!extra?.execpolicy_amendment || extra.execpolicy_amendment.length === 0)) {
         throw new Error(
-          `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: execpolicyAmendment required for acceptWithExecpolicyAmendment`
+          `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: execpolicy_amendment required for acceptWithExecpolicyAmendment`
         );
       }
     } else if (req.kind === "fileChange") {
@@ -1197,7 +1236,7 @@ var SessionManager = class {
     }
     let response;
     if (req.kind === "command") {
-      response = buildCommandApprovalResponse(decision, extra?.execpolicyAmendment);
+      response = buildCommandApprovalResponse(decision, extra?.execpolicy_amendment);
     } else if (req.kind === "fileChange") {
       response = { decision };
     }
@@ -1216,6 +1255,8 @@ var SessionManager = class {
       {
         requestId,
         kind: req.kind,
+        approvalId: req.approvalId,
+        networkApprovalContext: req.networkApprovalContext,
         decision,
         denyMessage: extra?.denyMessage
       },
@@ -1249,6 +1290,8 @@ var SessionManager = class {
       {
         requestId,
         kind: "user_input",
+        approvalId: req.approvalId,
+        networkApprovalContext: req.networkApprovalContext,
         answers
       },
       true
@@ -1301,10 +1344,39 @@ var SessionManager = class {
       session.lastActiveAt = (/* @__PURE__ */ new Date()).toISOString();
       const p = params;
       switch (method) {
+        case Methods.THREAD_STARTED: {
+          const thread = isRecord(p.thread) ? p.thread : void 0;
+          pushEvent(session.eventBuffer, "progress", {
+            method,
+            ...p,
+            threadId: normalizeOptionalString(p.threadId) ?? normalizeOptionalString(thread?.id),
+            status: normalizeOptionalString(thread?.status)
+          });
+          break;
+        }
+        case Methods.THREAD_ARCHIVED:
+        case Methods.THREAD_UNARCHIVED:
+        case Methods.THREAD_NAME_UPDATED:
+        case Methods.THREAD_TOKEN_USAGE_UPDATED:
+        case Methods.FUZZY_FILE_SEARCH_SESSION_UPDATED:
+        case Methods.FUZZY_FILE_SEARCH_SESSION_COMPLETED:
+        case Methods.WINDOWS_WORLD_WRITABLE_WARNING:
+        case Methods.ACCOUNT_LOGIN_COMPLETED:
+          pushEvent(session.eventBuffer, "progress", { method, ...p });
+          break;
         case Methods.TURN_STARTED:
           if (session.status === "cancelled") break;
-          session.activeTurnId = p.turn?.id ?? (typeof p.turnId === "string" ? p.turnId : void 0);
-          pushEvent(session.eventBuffer, "progress", { method, ...p });
+          {
+            const turnObj = p.turn;
+            const status = normalizeOptionalString(turnObj?.status);
+            session.activeTurnId = normalizeOptionalString(turnObj?.id) ?? (typeof p.turnId === "string" ? p.turnId : void 0);
+            pushEvent(session.eventBuffer, "progress", {
+              method,
+              ...p,
+              turnId: session.activeTurnId,
+              status
+            });
+          }
           break;
         case Methods.TURN_COMPLETED: {
           if (session.status === "cancelled") break;
@@ -1321,7 +1393,17 @@ var SessionManager = class {
             turnError: turnObj?.error,
             completedAt: (/* @__PURE__ */ new Date()).toISOString()
           };
-          pushEvent(session.eventBuffer, "result", { method, ...p }, true);
+          pushEvent(
+            session.eventBuffer,
+            "result",
+            {
+              method,
+              ...p,
+              turnId: completedTurnId,
+              status: normalizeOptionalString(turnObj?.status)
+            },
+            true
+          );
           break;
         }
         case Methods.ERROR: {
@@ -1355,12 +1437,20 @@ var SessionManager = class {
         case Methods.AGENT_MESSAGE_DELTA:
           pushEvent(session.eventBuffer, "output", { method, delta: p.delta, itemId: p.itemId });
           break;
+        case Methods.ITEM_STARTED:
         case Methods.ITEM_COMPLETED:
+        case Methods.RAW_RESPONSE_ITEM_COMPLETED:
           {
             const item = p.item;
             const itemType = item && typeof item.type === "string" ? item.type : void 0;
+            const status = normalizeOptionalString(item?.status);
             const eventType = itemType === "agentMessage" || itemType === "userMessage" ? "output" : "progress";
-            pushEvent(session.eventBuffer, eventType, { method, item: p.item });
+            pushEvent(session.eventBuffer, eventType, {
+              method,
+              ...p,
+              item: p.item,
+              status
+            });
           }
           break;
         case Methods.COMMAND_OUTPUT_DELTA: {
@@ -1373,14 +1463,16 @@ var SessionManager = class {
           }
           break;
         }
+        case Methods.COMMAND_TERMINAL_INTERACTION:
         case Methods.FILE_CHANGE_OUTPUT_DELTA:
         case Methods.REASONING_TEXT_DELTA:
         case Methods.REASONING_SUMMARY_DELTA:
+        case Methods.REASONING_SUMMARY_PART_ADDED:
         case Methods.PLAN_DELTA:
         case Methods.MCP_TOOL_PROGRESS:
-        case Methods.ITEM_STARTED:
         case Methods.TURN_DIFF_UPDATED:
         case Methods.TURN_PLAN_UPDATED:
+        case Methods.MODEL_REROUTED:
           pushEvent(session.eventBuffer, "progress", { method, ...p });
           break;
         default:
@@ -1397,15 +1489,22 @@ var SessionManager = class {
       switch (method) {
         case Methods.COMMAND_APPROVAL: {
           const requestId = `req_${randomUUID().slice(0, 8)}`;
-          const reason = normalizeOptionalString(p.reason);
+          const approvalParams = params;
+          const reason = normalizeOptionalString(approvalParams.reason);
+          const approvalId = normalizeOptionalString(
+            approvalParams.approvalId ?? approvalParams.approval_id
+          );
+          const networkApprovalContext = approvalParams.networkApprovalContext ?? approvalParams.network_approval_context;
           const pending = {
             requestId,
             kind: "command",
             params,
-            itemId: p.itemId,
-            threadId: p.threadId,
-            turnId: p.turnId,
+            itemId: normalizeOptionalString(approvalParams.itemId) ?? "",
+            threadId: normalizeOptionalString(approvalParams.threadId) ?? "",
+            turnId: normalizeOptionalString(approvalParams.turnId) ?? "",
             reason,
+            approvalId,
+            networkApprovalContext,
             createdAt: (/* @__PURE__ */ new Date()).toISOString(),
             resolved: false,
             respond: (result) => client.respondToServer(id, result)
@@ -1427,6 +1526,7 @@ var SessionManager = class {
                 {
                   requestId,
                   kind: "command",
+                  approvalId,
                   decision: "decline",
                   timeout: true
                 },
@@ -1446,9 +1546,12 @@ var SessionManager = class {
             {
               requestId,
               kind: "command",
-              command: p.command,
-              cwd: p.cwd,
-              reason
+              itemId: approvalParams.itemId,
+              approvalId,
+              command: approvalParams.command,
+              cwd: approvalParams.cwd,
+              reason,
+              networkApprovalContext
             },
             true
           );
@@ -1995,17 +2098,17 @@ function toSensitiveInfo(session) {
     config: session.config
   };
 }
-function buildCommandApprovalResponse(decision, execpolicyAmendment) {
+function buildCommandApprovalResponse(decision, execpolicy_amendment) {
   if (decision === "acceptWithExecpolicyAmendment") {
-    if (!execpolicyAmendment || execpolicyAmendment.length === 0) {
+    if (!execpolicy_amendment || execpolicy_amendment.length === 0) {
       throw new Error(
-        `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: execpolicyAmendment required for acceptWithExecpolicyAmendment`
+        `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: execpolicy_amendment required for acceptWithExecpolicyAmendment`
       );
     }
     return {
       decision: {
         acceptWithExecpolicyAmendment: {
-          execpolicy_amendment: execpolicyAmendment
+          execpolicy_amendment
         }
       }
     };
@@ -2106,6 +2209,18 @@ async function executeCodexSession(args, sessionManager) {
         };
       }
       return await sessionManager.forkSession(args.sessionId);
+    case "clean_background_terminals":
+      if (!args.sessionId) {
+        return {
+          error: `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: sessionId required for 'clean_background_terminals'`,
+          isError: true
+        };
+      }
+      await sessionManager.cleanBackgroundTerminals(args.sessionId);
+      return {
+        success: true,
+        message: `Background terminals cleaned for session ${args.sessionId}`
+      };
     default:
       return {
         error: `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: Unknown action '${args.action}'`,
@@ -2126,17 +2241,16 @@ function executeCodexCheck(args, sessionManager) {
         pollOptions
       });
     }
-    case "respond_permission":
-    case "respond_approval": {
+    case "respond_permission": {
       if (!args.requestId || !args.decision) {
         return {
-          error: `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: requestId and decision required for respond_permission/respond_approval`,
+          error: `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: requestId and decision required for respond_permission`,
           isError: true
         };
       }
       try {
         sessionManager.resolveApproval(args.sessionId, args.requestId, args.decision, {
-          execpolicyAmendment: args.execpolicyAmendment,
+          execpolicy_amendment: args.execpolicy_amendment,
           denyMessage: args.denyMessage
         });
       } catch (err) {
@@ -2144,18 +2258,10 @@ function executeCodexCheck(args, sessionManager) {
         return { error: message, isError: true };
       }
       const maxEvents = args.maxEvents ?? RESPOND_DEFAULT_MAX_EVENTS;
-      const result = sessionManager.pollEventsMonotonic(args.sessionId, args.cursor, maxEvents, {
+      return sessionManager.pollEventsMonotonic(args.sessionId, args.cursor, maxEvents, {
         responseMode,
         pollOptions
       });
-      if (args.action === "respond_approval") {
-        return addWarning(
-          result,
-          "Action 'respond_approval' is deprecated, use 'respond_permission'.",
-          pollOptions?.maxBytes
-        );
-      }
-      return result;
     }
     case "respond_user_input": {
       if (!args.requestId || !args.answers) {
@@ -2183,23 +2289,6 @@ function executeCodexCheck(args, sessionManager) {
       };
   }
 }
-function addWarning(result, warning, maxBytes) {
-  if (!result.compatWarnings) result.compatWarnings = [];
-  result.compatWarnings.push(warning);
-  if (typeof maxBytes !== "number") {
-    return result;
-  }
-  const normalizedMaxBytes = Math.max(1, Math.floor(maxBytes));
-  if (Buffer.byteLength(JSON.stringify(result), "utf8") <= normalizedMaxBytes) {
-    return result;
-  }
-  if (result.compatWarnings.length > 1) {
-    result.compatWarnings.pop();
-  } else {
-    result.compatWarnings = void 0;
-  }
-  return result;
-}
 
 // src/resources/register-resources.ts
 import { spawnSync } from "child_process";
@@ -2465,7 +2554,6 @@ function buildGotchasText() {
     `- Poll default is \`maxEvents=${POLL_DEFAULT_MAX_EVENTS}\` (authoritative: tool schema / constants).`,
     `- Poll enforces minimum \`maxEvents=${POLL_MIN_MAX_EVENTS}\`; sending \`0\` is normalized to \`${POLL_MIN_MAX_EVENTS}\`.`,
     `- \`respond_permission\` and \`respond_user_input\` default to compact ACK with \`maxEvents=${RESPOND_DEFAULT_MAX_EVENTS}\`.`,
-    "- `respond_approval` is a deprecated alias for `respond_permission`.",
     "- Default response mode is `minimal`; use `full` if you need full raw event payloads.",
     "- respond_* uses monotonic cursor handling: `max(cursor, sessionLastCursor)`.",
     "- If `cursorResetTo` is present, your cursor is stale (old events were evicted); restart from that value.",
@@ -2771,7 +2859,7 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.2.0" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.0.0" : "0.0.0-dev";
 function formatErrorMessage(err) {
   const message = err instanceof Error ? err.message : String(err);
   const m = /^Error \[([A-Z_]+)\]:\s*(.*)$/.exec(message);
@@ -2922,16 +3010,17 @@ function createServer(serverCwd) {
     "codex_session",
     {
       title: "Manage Sessions",
-      description: `Session actions: list, get, cancel, interrupt, fork.
+      description: `Session actions: list, get, cancel, interrupt, fork, clean_background_terminals.
 
 - list: sessions in memory.
 - get: details. includeSensitive defaults to false; true adds threadId/cwd/profile/config.
 - cancel: terminal.
 - interrupt: stop current turn.
-- fork: clone current thread into a new session; source remains unchanged.`,
+- fork: clone current thread into a new session; source remains unchanged.
+- clean_background_terminals: ask app-server to clean stale background terminals for this thread.`,
       inputSchema: {
         action: z.enum(SESSION_ACTIONS),
-        sessionId: z.string().optional().describe("Required for get/cancel/interrupt/fork"),
+        sessionId: z.string().optional().describe("Required for get/cancel/interrupt/fork/clean_background_terminals"),
         includeSensitive: z.boolean().default(false).optional().describe("Include cwd/config/threadId/profile in get (default: false)")
       },
       outputSchema: {
@@ -3000,8 +3089,6 @@ poll: events since cursor. Default maxEvents=${POLL_DEFAULT_MAX_EVENTS}.
 
 respond_permission: approval decision. Default maxEvents=${RESPOND_DEFAULT_MAX_EVENTS} (compact ACK).
 
-respond_approval: deprecated alias for respond_permission.
-
 respond_user_input: user-input answers. Default maxEvents=${RESPOND_DEFAULT_MAX_EVENTS} (compact ACK).
 
 events[].type is coarse-grained; details are in events[].data.method.
@@ -3018,15 +3105,14 @@ cursor omitted => use session last cursor. cursorResetTo => reset and continue.`
           includeEvents: z.boolean().optional().describe("Default: true. Include events[] in response."),
           includeActions: z.boolean().optional().describe("Default: true. Include actions[] in response."),
           includeResult: z.boolean().optional().describe("Default: true. Include result in response."),
-          maxBytes: z.number().int().positive().optional().describe("Default: unlimited. Best-effort response payload cap in bytes."),
-          includeTools: z.boolean().optional().describe("Default: false. Reserved for future dynamic tool metadata support.")
+          maxBytes: z.number().int().positive().optional().describe("Default: unlimited. Best-effort response payload cap in bytes.")
         }).optional().describe("Optional poll shaping controls."),
-        // respond_permission/respond_approval
+        // respond_permission
         requestId: z.string().optional().describe("Request ID from actions[]"),
         decision: z.enum(ALL_DECISIONS).optional().describe(
-          "Approval decision for respond_permission/respond_approval. acceptWithExecpolicyAmendment requires execpolicyAmendment."
+          "Approval decision for respond_permission. acceptWithExecpolicyAmendment requires execpolicy_amendment."
         ),
-        execpolicyAmendment: z.array(z.string()).optional().describe("For acceptWithExecpolicyAmendment only"),
+        execpolicy_amendment: z.array(z.string()).optional().describe("For acceptWithExecpolicyAmendment only"),
         denyMessage: z.string().optional().describe("Deny reason (not sent to agent)"),
         // respond_user_input
         answers: z.record(