@leo000001/codex-mcp 0.2.1 → 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

@@ -180,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:**
@@ -193,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" }
@@ -200,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
@@ -216,7 +218,7 @@ Query a running session for events, respond to approval requests, or answer user
 | `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[] }`                                                                                                                                  |
 
@@ -264,7 +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`.
+  - 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,7 +177,14 @@ 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 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 = [
@@ -213,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.1" : "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;
@@ -330,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);
   }
@@ -959,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);
@@ -1064,6 +1113,8 @@ var SessionManager = class {
             params: req.params,
             itemId: req.itemId,
             reason: req.reason,
+            approvalId: req.approvalId,
+            networkApprovalContext: req.networkApprovalContext,
             createdAt: req.createdAt
           });
         }
@@ -1167,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") {
@@ -1185,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 };
     }
@@ -1204,6 +1255,8 @@ var SessionManager = class {
       {
         requestId,
         kind: req.kind,
+        approvalId: req.approvalId,
+        networkApprovalContext: req.networkApprovalContext,
         decision,
         denyMessage: extra?.denyMessage
       },
@@ -1237,6 +1290,8 @@ var SessionManager = class {
       {
         requestId,
         kind: "user_input",
+        approvalId: req.approvalId,
+        networkApprovalContext: req.networkApprovalContext,
         answers
       },
       true
@@ -1289,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;
@@ -1309,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: {
@@ -1343,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: {
@@ -1361,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:
@@ -1385,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)
@@ -1415,6 +1526,7 @@ var SessionManager = class {
                 {
                   requestId,
                   kind: "command",
+                  approvalId,
                   decision: "decline",
                   timeout: true
                 },
@@ -1434,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
           );
@@ -1983,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
         }
       }
     };
@@ -2094,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}'`,
@@ -2123,7 +2250,7 @@ function executeCodexCheck(args, sessionManager) {
       }
       try {
         sessionManager.resolveApproval(args.sessionId, args.requestId, args.decision, {
-          execpolicyAmendment: args.execpolicyAmendment,
+          execpolicy_amendment: args.execpolicy_amendment,
           denyMessage: args.denyMessage
         });
       } catch (err) {
@@ -2732,7 +2859,7 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.2.1" : "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);
@@ -2883,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: {
@@ -2982,9 +3110,9 @@ cursor omitted => use session last cursor. cursorResetTo => reset and continue.`
         // respond_permission
         requestId: z.string().optional().describe("Request ID from actions[]"),
         decision: z.enum(ALL_DECISIONS).optional().describe(
-          "Approval decision for respond_permission. 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(