@leo000001/codex-mcp 0.2.1 → 2.0.2

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,17 @@ 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` when provided by app-server
+- Documentation was de-duplicated by splitting responsibilities between `AGENTS.md` (execution handbook) and `docs/DESIGN.md` (single source upgrade playbook), and a one-shot schema refresh runbook/record was added (`2026-02-21`, no schema diff)
+- `src/app-server/protocol.ts` is now aligned to current v2 schema coverage for thread/turn params (`dynamicTools`, `persistExtendedHistory`, `collaborationMode`, richer `SandboxPolicy`, strict `UserInput` union, `turn/steer` params)
+- `codex_check` input validation is now action-aware at schema level (`poll` vs `respond_permission` vs `respond_user_input`), including conditional `execpolicy_amendment` rules and forbidden-field checks
+- Auth refresh request handling now uses explicit unsupported semantics (`-32000`) instead of `-32601` for `account/chatgptAuthTokens/refresh`
+- Compatibility policy is now explicitly strict: removed non-essential alias compatibility (`approval_id`, `network_approval_context`, `questionId`) and documented a single necessary-compatibility whitelist (v1/v2 thread/turn id extraction)
+- Command approval context is now surfaced directly in `actions[]` / `approval_request` payloads (`commandActions`, `proposedExecpolicyAmendment`) for richer client-side approval UX
+- `turn/started` and `turn/completed` notification handling now only uses canonical `turn.id` shape (plus runtime `activeTurnId` fallback), and corresponding v1 top-level `turnId` compatibility tests were removed
+- `compat-report` now correctly advertises `respondApprovalAlias: false` to match strict no-alias behavior
+- Upgrade-policy docs were further de-duplicated: `docs/DESIGN.md` remains the single detailed compatibility source, and `AGENTS.md` now stays as a concise execution gate
 
 ## [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,9 +218,9 @@ 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[] }`                                                                                                                                  |
+| `answers`             | object   | For respond_user_input            | For `respond_user_input`: `question-id -> { answers: string[] }`                                                                                                                                  |
 
 **Returns (poll and respond_*):** `{ sessionId, status, pollInterval?, cursorResetTo?, events, nextCursor, actions?, result? }`
 
@@ -264,11 +266,14 @@ 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_user_input`: send `answers` keyed by `questionId`.
+  - For command approvals, `acceptWithExecpolicyAmendment` is supported and requires `execpolicy_amendment`.
+- `respond_user_input`: send `answers` keyed by the question `id`.
+- For command approvals, `actions[]` may include `commandActions` and `proposedExecpolicyAmendment` for richer review UI.
 
 Pending approvals auto-decline after `advanced.approvalTimeoutMs`.
 
+Auth callback note: if app-server sends `account/chatgptAuthTokens/refresh`, codex-mcp returns JSON-RPC error `-32000` because external ChatGPT token refresh is out of scope for this server.
+
 ## Session Lifecycle & Cleanup
 
 Sessions auto-clean up in the background: