141 Commits

• [codex][mcp] Add resource uri meta to tool call item. (#17831)

  - [x] Add resource uri meta to tool call item so that the app-server
  client can start prefetching resources immediately without loading mcp
  server status.

  Matthew Zeng · 2026-04-16 05:09:17 +00:00
  224dad41ac
• feat: add endpoint to delete memories (#17913)
  jif-oai · 2026-04-15 10:35:06 +01:00
  7579d5ad75
• Spread AbsolutePathBuf (#17792)

  Mechanical change to promote absolute paths through code.

  pakrym-oai · 2026-04-14 14:26:10 -07:00
  dd1321d11b
• Add realtime output modality and transcript events (#17701)

  - Add outputModality to thread/realtime/start and wire text/audio output
  selection through app-server, core, API, and TUI.\n- Rename the realtime
  transcript delta notification and add a separate transcript done
  notification that forwards final text from item done without correlating
  it with deltas.

  Ahmed Ibrahim · 2026-04-14 00:13:13 -07:00
  2f6fc7c137
• [codex] Refactor marketplace add into shared core flow (#17717)

  ## Summary
  
  Move `codex marketplace add` onto a shared core implementation so the
  CLI and app-server path can use one source of truth.
  
  This change:
  - adds shared marketplace-add orchestration in `codex-core`
  - switches the CLI command to call that shared implementation
  - removes duplicated CLI-only marketplace add helpers
  - preserves focused parser and add-path coverage while moving the shared
  behavior into core tests
  
  ## Why
  
  The new `marketplace/add` RPC should reuse the same underlying
  marketplace-add flow as the CLI. This refactor lands that consolidation
  first so the follow-up app-server PR can be mostly protocol and handler
  wiring.
  
  ## Validation
  
  - `cargo test -p codex-core marketplace_add`
  - `cargo test -p codex-cli marketplace_cmd`
  - `just fix -p codex-core`
  - `just fix -p codex-cli`
  - `just fmt`

  xli-oai · 2026-04-13 20:37:11 -07:00
  ff584c5a4b
• Add turn item injection API (#17703)

  ## Summary
  - Add `turn/inject_items` app-server v2 request support for appending
  raw Responses API items to a loaded thread history without starting a
  turn.
  - Generate JSON schema and TypeScript protocol artifacts for the new
  params and empty response.
  - Document the new endpoint and include a request/response example.
  - Preserve compatibility with the typo alias `turn/injet_items` while
  returning the canonical method name.
  
  ## Testing
  - Not run (not requested)

  pakrym-oai · 2026-04-13 16:11:05 -07:00
  d4be06adea
• feat: disable memory endpoint (#17626)
  jif-oai · 2026-04-13 18:29:49 +01:00
  46a266cd6a
• Expose instruction sources (AGENTS.md) via app server (#17506)

  Addresses #17498
  
  Problem: The TUI derived /status instruction source paths from the local
  client environment, which could show stale <none> output or incorrect
  paths when connected to a remote app server.
  
  Solution: Add an app-server v2 instructionSources snapshot to thread
  start/resume/fork responses, default it to an empty list when older
  servers omit it, and render TUI /status from that server-provided
  session data.
  
  Additional context: The app-server field is intentionally named
  instructionSources rather than AGENTS.md-specific terminology because
  the loaded instruction sources can include global instructions, project
  AGENTS.md files, AGENTS.override.md, user-defined instruction files, and
  future dynamic sources.

  Eric Traut · 2026-04-12 15:50:12 -07:00
  46ab9974dc
• [mcp] Support MCP Apps part 3 - Add mcp tool call support. (#17364)

  - [x] Add a new app-server method so that MCP Apps can call their own
  MCP server directly.

  Matthew Zeng · 2026-04-11 04:39:19 +00:00
  b7139a7e8f
• Revert "Option to Notify Workspace Owner When Usage Limit is Reached" (#17391)

  Reverts openai/codex#16969
  
  #sev3-2026-04-10-accountscheckversion-500s-for-openai-workspace-7300

  Shijie Rao · 2026-04-10 23:33:13 +00:00
  930e5adb7e
• Option to Notify Workspace Owner When Usage Limit is Reached (#16969)

  ## Summary
  - Replace the manual `/notify-owner` flow with an inline confirmation
  prompt when a usage-based workspace member hits a credits-depleted
  limit.
  - Fetch the current workspace role from the live ChatGPT
  `accounts/check/v4-2023-04-27` endpoint so owner/member behavior matches
  the desktop and web clients.
  - Keep owner, member, and spend-cap messaging distinct so we only offer
  the owner nudge when the workspace is actually out of credits.
  
  ## What Changed
  - `backend-client`
  - Added a typed fetch for the current account role from
  `accounts/check`.
    - Mapped backend role values into a Rust workspace-role enum.
  - `app-server` and protocol
    - Added `workspaceRole` to `account/read` and `account/updated`.
  - Derived `isWorkspaceOwner` from the live role, with a fallback to the
  cached token claim when the role fetch is unavailable.
  - `tui`
    - Removed the explicit `/notify-owner` slash command.
  - When a member is blocked because the workspace is out of credits, the
  error now prompts:
  - `Your workspace is out of credits. Request more from your workspace
  owner? [y/N]`
    - Choosing `y` sends the existing owner-notification request.
  - Choosing `n`, pressing `Esc`, or accepting the default selection
  dismisses the prompt without sending anything.
  - Selection popups now honor explicit item shortcuts, which is how the
  `y` / `n` interaction is wired.
  
  ## Reviewer Notes
  - The main behavior change is scoped to usage-based workspace members
  whose workspace credits are depleted.
  - Spend-cap reached should not show the owner-notification prompt.
  - Owners and admins should continue to see `/usage` guidance instead of
  the member prompt.
  - The live role fetch is best-effort; if it fails, we fall back to the
  existing token-derived ownership signal.
  
  ## Testing
  - Manual verification
    - Workspace owner does not see the member prompt.
  - Workspace member with depleted credits sees the confirmation prompt
  and can send the nudge with `y`.
  - Workspace member with spend cap reached does not see the
  owner-notification prompt.
  
  ### Workspace member out of usage
  
  https://github.com/user-attachments/assets/341ac396-eff4-4a7f-bf0c-60660becbea1
  
  ### Workspace owner
  <img width="1728" height="1086" alt="Screenshot 2026-04-09 at 11 48
  22 AM"
  src="https://github.com/user-attachments/assets/06262a45-e3fc-4cc4-8326-1cbedad46ed6"
  />

  richardopenai · 2026-04-09 21:15:17 -07:00
  9f2a585153
• Forward app-server turn clientMetadata to Responses (#16009)

  ## Summary
  App-server v2 already receives turn-scoped `clientMetadata`, but the
  Rust app-server was dropping it before the outbound Responses request.
  This change keeps the fix lightweight by threading that metadata through
  the existing turn-metadata path rather than inventing a new transport.
  
  ## What we're trying to do and why
  We want turn-scoped metadata from the app-server protocol layer,
  especially fields like Hermes/GAAS run IDs, to survive all the way to
  the actual Responses API request so it is visible in downstream
  websocket request logging and analytics.
  
  The specific bug was:
  - app-server protocol uses camelCase `clientMetadata`
  - Responses transport already has an existing turn metadata carrier:
  `x-codex-turn-metadata`
  - websocket transport already rewrites that header into
  `request.request_body.client_metadata["x-codex-turn-metadata"]`
  - but the Rust app-server never parsed or stored `clientMetadata`, so
  nothing from the app-server request was making it into that existing
  path
  
  This PR fixes that without adding a new header or a second metadata
  channel.
  
  ## How we did it
  ### Protocol surface
  - Add optional `clientMetadata` to v2 `TurnStartParams` and
  `TurnSteerParams`
  - Regenerate the JSON schema / TypeScript fixtures
  - Update app-server docs to describe the field and its behavior
  
  ### Runtime plumbing
  - Add a dedicated core op for app-server user input carrying turn-scoped
  metadata: `Op::UserInputWithClientMetadata`
  - Wire `turn/start` and `turn/steer` through that op / signature path
  instead of dropping the metadata at the message-processor boundary
  - Store the metadata in `TurnMetadataState`
  
  ### Transport behavior
  - Reuse the existing serialized `x-codex-turn-metadata` payload
  - Merge the new app-server `clientMetadata` into that JSON additively
  - Do **not** replace built-in reserved fields already present in the
  turn metadata payload
  - Keep websocket behavior unchanged at the outer shape level: it still
  sends only `client_metadata["x-codex-turn-metadata"]`, but that JSON
  string now contains the merged fields
  - Keep HTTP fallback behavior unchanged except that the existing
  `x-codex-turn-metadata` header now includes the merged fields too
  
  ### Request shape before / after
  Before, a websocket `response.create` looked like:
  ```json
  {
    "type": "response.create",
    "client_metadata": {
      "x-codex-turn-metadata": "{\"session_id\":\"...\",\"turn_id\":\"...\"}"
    }
  }
  ```
  Even if the app-server caller supplied `clientMetadata`, it was not
  represented there.
  
  After, the same request shape is preserved, but the serialized payload
  now includes the new turn-scoped fields:
  ```json
  {
    "type": "response.create",
    "client_metadata": {
      "x-codex-turn-metadata": "{\"session_id\":\"...\",\"turn_id\":\"...\",\"fiber_run_id\":\"fiber-start-123\",\"origin\":\"gaas\"}"
    }
  }
  ```
  
  ## Validation
  ### Targeted tests added / updated
  - protocol round-trip coverage for `clientMetadata` on `turn/start` and
  `turn/steer`
  - protocol round-trip coverage for `Op::UserInputWithClientMetadata`
  - `TurnMetadataState` merge test proving client metadata is added
  without overwriting reserved built-in fields
  - websocket request-shape test proving outbound `response.create`
  contains merged metadata inside
  `client_metadata["x-codex-turn-metadata"]`
  - app-server integration tests proving:
  - `turn/start` forwards `clientMetadata` into the outbound Responses
  request path
    - websocket warmup + real turn request both behave correctly
    - `turn/steer` updates the follow-up request metadata
  
  ### Commands run
  - `just write-app-server-schema`
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-core
  turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields
  --lib`
  - `cargo test -p codex-core --test all
  responses_websocket_preserves_custom_turn_metadata_fields`
  - `cargo test -p codex-app-server --test all client_metadata`
  - `cargo test -p codex-app-server --test all
  turn_start_forwards_client_metadata_to_responses_websocket_request_body_v2
  -- --nocapture`
  - `just fmt`
  - `just fix -p codex-core -p codex-protocol -p codex-app-server-protocol
  -p codex-app-server`
  - `just fix -p codex-exec -p codex-tui-app-server`
  - `just argument-comment-lint`
  
  ### Full suite note
  `cargo test` in `codex-rs` still fails in:
  -
  `suite::v2::turn_interrupt::turn_interrupt_resolves_pending_command_approval_request`
  
  I verified that same failure on a clean detached `HEAD` worktree with an
  isolated `CARGO_TARGET_DIR`, so it is not caused by this patch.

  neil-oai · 2026-04-09 11:52:37 -07:00
  a92a5085bd
• Add realtime voice selection (#17176)

  - Add realtime voice selection for realtime/start.
  - Expose the supported v1/v2 voice lists and cover explicit, configured,
  default, and invalid voice paths.

  Ahmed Ibrahim · 2026-04-08 20:19:15 -07:00
  2f9090be62
• Move default realtime prompt into core (#17165)

  - Adds a core-owned realtime backend prompt template and preparation
  path.
  - Makes omitted realtime start prompts use the core default, while null
  or empty prompts intentionally send empty instructions.
  - Covers the core realtime path and app-server v2 path with integration
  coverage.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-04-08 19:34:40 -07:00
  4c2a1ae31b
• Add WebRTC transport to realtime start (#16960)

  Adds WebRTC startup to the experimental app-server
  `thread/realtime/start` method with an optional transport enum. The
  websocket path remains the default; WebRTC offers create the realtime
  session through the shared start flow and emit the answer SDP via
  `thread/realtime/sdp`.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-04-07 15:43:38 -07:00
  fb3dcfde1d
• [app-server-protocol] introduce generic ServerResponse for app-server-protocol (#17044)

  - introduces `ServerResponse` as the symmetrical typed response union to
  `ServerRequest` for app-server-protocol
  - enables scalable event stream ingestion for use cases such as
  analytics, particularly for tools/approvals
  - no runtime behavior changes, protocol/schema plumbing only
  - mirrors #15921

  rhan-oai · 2026-04-07 14:50:27 -07:00
  f480b98984
• app-server: Move watch_id to request of fs/watch (#17026)

  It's easier for clients to maintain watchers if they define the watch
  id, so move it into the request.
  It's not used yet, so should be a safe change.

  Ruslan Nigmatullin · 2026-04-07 11:22:28 -07:00
  8a13f82204
• [mcp] Support MCP Apps part 1. (#16082)

  - [x] Add `mcpResource/read` method to read mcp resource.

  Matthew Zeng · 2026-04-06 19:17:14 -07:00
  5fe9ef06ce
• Fix fork source display in /status (expose forked_from_id in app server) (#16596)

  Addresses #16560
  
  Problem: `/status` stopped showing the source thread id in forked TUI
  sessions after the app-server migration.
  
  Solution: Carry fork source ids through app-server v2 thread data and
  the TUI session adapter, and update TUI fixtures so `/status` matches
  the old TUI behavior.

  Eric Traut · 2026-04-02 14:05:29 -07:00
  9bb7f0a694
• Add ChatGPT device-code login to app server (#15525)

  ## Problem
  
  App-server clients could only initiate ChatGPT login through the browser
  callback flow, even though the shared login crate already supports
  device-code auth. That left VS Code, Codex App, and other app-server
  clients without a first-class way to use the existing device-code
  backend when browser redirects are brittle or when the client UX wants
  to own the login ceremony.
  
  ## Mental model
  
  This change adds a second ChatGPT login start path to app-server:
  clients can now call `account/login/start` with `type:
  "chatgptDeviceCode"`. App-server immediately returns a `loginId` plus
  the device-code UX payload (`verificationUrl` and `userCode`), then
  completes the login asynchronously in the background using the existing
  `codex_login` polling flow. Successful device-code login still resolves
  to ordinary `chatgpt` auth, and completion continues to flow through the
  existing `account/login/completed` and `account/updated` notifications.
  
  ## Non-goals
  
  This does not introduce a new auth mode, a new account shape, or a
  device-code eligibility discovery API. It also does not add automatic
  fallback to browser login in core; clients remain responsible for
  choosing when to request device code and whether to retry with a
  different UX if the backend/admin policy rejects it.
  
  ## Tradeoffs
  
  We intentionally keep `login_chatgpt_common` as a local validation
  helper instead of turning it into a capability probe. Device-code
  eligibility is checked by actually calling `request_device_code`, which
  means policy-disabled cases surface as an immediate request error rather
  than an async completion event. We also keep the active-login state
  machine minimal: browser and device-code logins share the same public
  cancel contract, but device-code cancellation is implemented with a
  local cancel token rather than a larger cross-crate refactor.
  
  ## Architecture
  
  The protocol grows a new `chatgptDeviceCode` request/response variant in
  app-server v2. On the server side, the new handler reuses the existing
  ChatGPT login precondition checks, calls `request_device_code`, returns
  the device-code payload, and then spawns a background task that waits on
  either cancellation or `complete_device_code_login`. On success, it
  reuses the existing auth reload and cloud-requirements refresh path
  before emitting `account/login/completed` success and `account/updated`.
  On failure or cancellation, it emits only `account/login/completed`
  failure. The existing `account/login/cancel { loginId }` contract
  remains unchanged and now works for both browser and device-code
  attempts.
  
  
  ## Tests
  
  Added protocol serialization coverage for the new request/response
  variant, plus app-server tests for device-code success, failure, cancel,
  and start-time rejection behavior. Existing browser ChatGPT login
  coverage remains in place to show that the callback-based flow is
  unchanged.

  daniel-oai · 2026-03-27 00:27:15 -07:00
  47a9e2e084
• [app-server-protocol] introduce generic ClientResponse for app-server-protocol (#15921)

  - introduces `ClientResponse` as the symmetrical typed response union to
  `ClientRequest` for app-server-protocol
  - enables scalable event stream ingestion for use cases such as
  analytics
  - no runtime behavior changes, protocol/schema plumbing only

  rhan-oai · 2026-03-26 21:33:25 -07:00
  21a03f1671
• permissions: remove macOS seatbelt extension profiles (#15918)

  ## Why
  
  `PermissionProfile` should only describe the per-command permissions we
  still want to grant dynamically. Keeping
  `MacOsSeatbeltProfileExtensions` in that surface forced extra macOS-only
  approval, protocol, schema, and TUI branches for a capability we no
  longer want to expose.
  
  ## What changed
  
  - Removed the macOS-specific permission-profile types from
  `codex-protocol`, the app-server v2 API, and the generated
  schema/TypeScript artifacts.
  - Deleted the core and sandboxing plumbing that threaded
  `MacOsSeatbeltProfileExtensions` through execution requests and seatbelt
  construction.
  - Simplified macOS seatbelt generation so it always includes the fixed
  read-only preferences allowlist instead of carrying a configurable
  profile extension.
  - Removed the macOS additional-permissions UI/docs/test coverage and
  deleted the obsolete macOS permission modules.
  - Tightened `request_permissions` intersection handling so explicitly
  empty requested read lists are preserved only when that field was
  actually granted, avoiding zero-grant responses being stored as active
  permissions.

  Michael Bolin · 2026-03-26 17:12:45 -07:00
  e6e2999209
• chore: remove skill metadata from command approval payloads (#15906)

  ## Why
  
  This is effectively a follow-up to
  [#15812](https://github.com/openai/codex/pull/15812). That change
  removed the special skill-script exec path, but `skill_metadata` was
  still being threaded through command-approval payloads even though the
  approval flow no longer uses it to render prompts or resolve decisions.
  
  Keeping it around added extra protocol, schema, and client surface area
  without changing behavior.
  
  Removing it keeps the command-approval contract smaller and avoids
  carrying a dead field through app-server, TUI, and MCP boundaries.
  
  ## What changed
  
  - removed `ExecApprovalRequestSkillMetadata` and the corresponding
  `skillMetadata` field from core approval events and the v2 app-server
  protocol
  - removed the generated JSON and TypeScript schema output for that field
  - updated app-server, MCP server, TUI, and TUI app-server approval
  plumbing to stop forwarding the field
  - cleaned up tests that previously constructed or asserted
  `skillMetadata`
  
  ## Testing
  
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-app-server-test-client`
  - `cargo test -p codex-mcp-server`
  - `just argument-comment-lint`

  Michael Bolin · 2026-03-26 15:32:03 -07:00
  5906c6a658
• [app-server] Add a method to override feature flags. (#15601)

  - [x] Add a method to override feature flags globally and not just
  thread level.

  Matthew Zeng · 2026-03-25 02:27:00 +00:00
  0b08d89304
• app-server: add filesystem watch support (#14533)

  ### Summary
  Add the v2 app-server filesystem watch RPCs and notifications, wire them
  through the message processor, and implement connection-scoped watches
  with notify-backed change delivery. This also updates the schema
  fixtures, app-server documentation, and the v2 integration coverage for
  watch and unwatch behavior.
  
  This allows clients to efficiently watch for filesystem updates, e.g. to
  react on branch changes.
  
  ### Testing
  - exercise watch lifecycles for directory changes, atomic file
  replacement, missing-file targets, and unwatch cleanup

  Ruslan Nigmatullin · 2026-03-24 15:52:13 -07:00
  301b17c2a1
• Move git utilities into a dedicated crate (#15564)

  - create `codex-git-utils` and move the shared git helpers into it with
  file moves preserved for diff readability
  - move the `GitInfo` helpers out of `core` so stacked rollout work can
  depend on the shared crate without carrying its own git info module
  
  ---------
  
  Co-authored-by: Ahmed Ibrahim <219906144+aibrahim-oai@users.noreply.github.com>
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-03-24 13:26:23 -07:00
  0f957a93cd
• Add realtime transcript notification in v2 (#15344)

  - emit a typed `thread/realtime/transcriptUpdated` notification from
  live realtime transcript deltas
  - expose that notification as flat `threadId`, `role`, and `text` fields
  instead of a nested transcript array
  - continue forwarding raw `handoff_request` items on
  `thread/realtime/itemAdded`, including the accumulated
  `active_transcript`
  - update app-server docs, tests, and generated protocol schema artifacts
  to match the delta-based payloads
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-03-20 15:30:48 -07:00
  3431f01776
• feat(app-server): add mcpServer/startupStatus/updated notification (#15220)

  Exposes the legacy `codex/event/mcp_startup_update` event as an API v2
  notification.
  
  The legacy event has this shape:
  ```
  #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
  pub struct McpStartupUpdateEvent {
      /// Server name being started.
      pub server: String,
      /// Current startup status.
      pub status: McpStartupStatus,
  }
  
  #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
  #[serde(rename_all = "snake_case", tag = "state")]
  #[ts(rename_all = "snake_case", tag = "state")]
  pub enum McpStartupStatus {
      Starting,
      Ready,
      Failed { error: String },
      Cancelled,
  }
  ```

  Owen Lin · 2026-03-19 15:09:59 -07:00
  9e695fe830
• Add thread/shellCommand to app server API surface (#14988)

  This PR adds a new `thread/shellCommand` app server API so clients can
  implement `!` shell commands. These commands are executed within the
  sandbox, and the command text and output are visible to the model.
  
  The internal implementation mirrors the current TUI `!` behavior.
  - persist shell command execution as `CommandExecution` thread items,
  including source and formatted output metadata
  - bridge live and replayed app-server command execution events back into
  the existing `tui_app_server` exec rendering path
  
  This PR also wires `tui_app_server` to submit `!` commands through the
  new API.

  Eric Traut · 2026-03-18 23:42:40 -06:00
  01df50cf42
• Simple directory mentions (#14970)

  - Adds simple support for directory mentions in the TUI.
  - Codex App/VS Code will require minor change to recognize a directory
  mention as such and change the link behavior.
  - Directory mentions have a trailing slash to differentiate from
  extensionless files
  
  
  <img width="972" height="382" alt="image"
  src="https://github.com/user-attachments/assets/8035b1eb-0978-465b-8d7a-4db2e5feca39"
  />
  <img width="978" height="228" alt="image"
  src="https://github.com/user-attachments/assets/af22cf0b-dd10-4440-9bee-a09915f6ba52"
  />

  canvrno-oai · 2026-03-19 05:24:09 +00:00
  10eb3ec7fc
• Gate realtime audio interruption logic to v2 (#14984)

  - thread the realtime version into conversation start and app-server
  notifications
  - keep playback-aware mic gating and playback interruption behavior on
  v2 only, leaving v1 on the legacy path

  Ahmed Ibrahim · 2026-03-17 15:24:37 -07:00
  c6ab4ee537
• Cleanup skills/remote/xxx endpoints. (#14977)

  Remote skills/remote/xxx as they are not in used for now.

  xl-openai · 2026-03-17 15:22:36 -07:00
  1a9555eda9
• [stack 2/4] Align main realtime v2 wire and runtime flow (#14830)

  ## Stack Position
  2/4. Built on top of #14828.
  
  ## Base
  - #14828
  
  ## Unblocks
  - #14829
  - #14827
  
  ## Scope
  - Port the realtime v2 wire parsing, session, app-server, and
  conversation runtime behavior onto the split websocket-method base.
  - Branch runtime behavior directly on the current realtime session kind
  instead of parser-derived flow flags.
  - Keep regression coverage in the existing e2e suites.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-03-16 21:38:07 -07:00
  fbd7f9b986
• Add Smart Approvals guardian review across core, app-server, and TUI (#13860)

  ## Summary
  - add `approvals_reviewer = "user" | "guardian_subagent"` as the runtime
  control for who reviews approval requests
  - route Smart Approvals guardian review through core for command
  execution, file changes, managed-network approvals, MCP approvals, and
  delegated/subagent approval flows
  - expose guardian review in app-server with temporary unstable
  `item/autoApprovalReview/{started,completed}` notifications carrying
  `targetItemId`, `review`, and `action`
  - update the TUI so Smart Approvals can be enabled from `/experimental`,
  aligned with the matching `/approvals` mode, and surfaced clearly while
  reviews are pending or resolved
  
  ## Runtime model
  This PR does not introduce a new `approval_policy`.
  
  Instead:
  - `approval_policy` still controls when approval is needed
  - `approvals_reviewer` controls who reviewable approval requests are
  routed to:
    - `user`
    - `guardian_subagent`
  
  `guardian_subagent` is a carefully prompted reviewer subagent that
  gathers relevant context and applies a risk-based decision framework
  before approving or denying the request.
  
  The `smart_approvals` feature flag is a rollout/UI gate. Core runtime
  behavior keys off `approvals_reviewer`.
  
  When Smart Approvals is enabled from the TUI, it also switches the
  current `/approvals` settings to the matching Smart Approvals mode so
  users immediately see guardian review in the active thread:
  - `approval_policy = on-request`
  - `approvals_reviewer = guardian_subagent`
  - `sandbox_mode = workspace-write`
  
  Users can still change `/approvals` afterward.
  
  Config-load behavior stays intentionally narrow:
  - plain `smart_approvals = true` in `config.toml` remains just the
  rollout/UI gate and does not auto-set `approvals_reviewer`
  - the deprecated `guardian_approval = true` alias migration does
  backfill `approvals_reviewer = "guardian_subagent"` in the same scope
  when that reviewer is not already configured there, so old configs
  preserve their original guardian-enabled behavior
  
  ARC remains a separate safety check. For MCP tool approvals, ARC
  escalations now flow into the configured reviewer instead of always
  bypassing guardian and forcing manual review.
  
  ## Config stability
  The runtime reviewer override is stable, but the config-backed
  app-server protocol shape is still settling.
  
  - `thread/start`, `thread/resume`, and `turn/start` keep stable
  `approvalsReviewer` overrides
  - the config-backed `approvals_reviewer` exposure returned via
  `config/read` (including profile-level config) is now marked
  `[UNSTABLE]` / experimental in the app-server protocol until we are more
  confident in that config surface
  
  ## App-server surface
  This PR intentionally keeps the guardian app-server shape narrow and
  temporary.
  
  It adds generic unstable lifecycle notifications:
  - `item/autoApprovalReview/started`
  - `item/autoApprovalReview/completed`
  
  with payloads of the form:
  - `{ threadId, turnId, targetItemId, review, action? }`
  
  `review` is currently:
  - `{ status, riskScore?, riskLevel?, rationale? }`
  - where `status` is one of `inProgress`, `approved`, `denied`, or
  `aborted`
  
  `action` carries the guardian action summary payload from core when
  available. This lets clients render temporary standalone pending-review
  UI, including parallel reviews, even when the underlying tool item has
  not been emitted yet.
  
  These notifications are explicitly documented as `[UNSTABLE]` and
  expected to change soon.
  
  This PR does **not** persist guardian review state onto `thread/read`
  tool items. The intended follow-up is to attach guardian review state to
  the reviewed tool item lifecycle instead, which would improve
  consistency with manual approvals and allow thread history / reconnect
  flows to replay guardian review state directly.
  
  ## TUI behavior
  - `/experimental` exposes the rollout gate as `Smart Approvals`
  - enabling it in the TUI enables the feature and switches the current
  session to the matching Smart Approvals `/approvals` mode
  - disabling it in the TUI clears the persisted `approvals_reviewer`
  override when appropriate and returns the session to default manual
  review when the effective reviewer changes
  - `/approvals` still exposes the reviewer choice directly
  - the TUI renders:
  - pending guardian review state in the live status footer, including
  parallel review aggregation
    - resolved approval/denial state in history
  
  ## Scope notes
  This PR includes the supporting core/runtime work needed to make Smart
  Approvals usable end-to-end:
  - shell / unified-exec / apply_patch / managed-network / MCP guardian
  review
  - delegated/subagent approval routing into guardian review
  - guardian review risk metadata and action summaries for app-server/TUI
  - config/profile/TUI handling for `smart_approvals`, `guardian_approval`
  alias migration, and `approvals_reviewer`
  - a small internal cleanup of delegated approval forwarding to dedupe
  fallback paths and simplify guardian-vs-parent approval waiting (no
  intended behavior change)
  
  Out of scope for this PR:
  - redesigning the existing manual approval protocol shapes
  - persisting guardian review state onto app-server `ThreadItem`s
  - delegated MCP elicitation auto-review (the current delegated MCP
  guardian shim only covers the legacy `RequestUserInput` path)
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Charley Cunningham · 2026-03-13 15:27:00 -07:00
  bc24017d64
• app-server: add v2 filesystem APIs (#14245)

  Add a protocol-level filesystem surface to the v2 app-server so Codex
  clients can read and write files, inspect directories, and subscribe to
  path changes without relying on host-specific helpers.
  
  High-level changes:
  - define the new v2 fs/readFile, fs/writeFile, fs/createDirectory,
  fs/getMetadata, fs/readDirectory, fs/remove, fs/copy RPCs
  - implement the app-server handlers, including absolute-path validation,
  base64 file payloads, recursive copy/remove semantics
  - document the API, regenerate protocol schemas/types, and add
  end-to-end tests for filesystem operations, copy edge cases
  
  Testing plan:
  - validate protocol serialization and generated schema output for the
  new fs request, response, and notification types
  - run app-server integration coverage for file and directory CRUD paths,
  metadata/readDirectory responses, copy failure modes, and absolute-path
  validation

  Ruslan Nigmatullin · 2026-03-13 14:42:20 -07:00
  f8f82bfc2b
• feat: add plugin/read. (#14445)

  return more information for a specific plugin.

  xl-openai · 2026-03-12 16:52:21 -07:00
  1ea69e8d50
• chore(app-server): stop emitting codex/event/ notifications (#14392)

  ## Description
  
  This PR stops emitting legacy `codex/event/*` notifications from the
  public app-server transports.
  
  It's been a long time coming! app-server was still producing a raw
  notification stream from core, alongside the typed app-server
  notifications and server requests, for compatibility reasons. Now,
  external clients should no longer be depending on those legacy
  notifications, so this change removes them from the stdio and websocket
  contract and updates the surrounding docs, examples, and tests to match.
  
  ### Caveat
  I left the "in-process" version of app-server alone for now, since
  `codex exec` was recently based on top of app-server via this in-process
  form here: https://github.com/openai/codex/pull/14005
  
  Seems like `codex exec` still consumes some legacy notifications
  internally, so this branch only removes `codex/event/*` from app-server
  over stdio and websockets.
  
  ## Follow-up
  
  Once `codex exec` is fully migrated off `codex/event/*` notifications,
  we'll be able to stop emitting them entirely entirely instead of just
  filtering it at the external transport boundary.

  Owen Lin · 2026-03-12 00:45:20 +00:00
  72631755e0
• app-server: propagate nested experimental gating for AskForApproval::Reject (#14191)

  ## Summary
  This change makes `AskForApproval::Reject` gate correctly anywhere it
  appears inside otherwise-stable app-server protocol types.
  
  Previously, experimental gating for `approval_policy: Reject` was
  handled with request-specific logic in `ClientRequest` detection. That
  covered a few request params types, but it did not generalize to other
  nested uses such as `ProfileV2`, `Config`, `ConfigReadResponse`, or
  `ConfigRequirements`.
  
  This PR replaces that ad hoc handling with a generic nested experimental
  propagation mechanism.
  
  ## Testing
  
  seeing this when run app-server-test-client without experimental api
  enabled:
  ```
   initialize response: InitializeResponse { user_agent: "codex-toy-app-server/0.0.0 (Mac OS 26.3.1; arm64) vscode/2.4.36 (codex-toy-app-server; 0.0.0)" }
  > {
  >   "id": "50244f6a-270a-425d-ace0-e9e98205bde7",
  >   "method": "thread/start",
  >   "params": {
  >     "approvalPolicy": {
  >       "reject": {
  >         "mcp_elicitations": false,
  >         "request_permissions": true,
  >         "rules": false,
  >         "sandbox_approval": true
  >       }
  >     },
  >     "baseInstructions": null,
  >     "config": null,
  >     "cwd": null,
  >     "developerInstructions": null,
  >     "dynamicTools": null,
  >     "ephemeral": null,
  >     "experimentalRawEvents": false,
  >     "mockExperimentalField": null,
  >     "model": null,
  >     "modelProvider": null,
  >     "persistExtendedHistory": false,
  >     "personality": null,
  >     "sandbox": null,
  >     "serviceName": null
  >   }
  > }
  < {
  <   "error": {
  <     "code": -32600,
  <     "message": "askForApproval.reject requires experimentalApi capability"
  <   },
  <   "id": "50244f6a-270a-425d-ace0-e9e98205bde7"
  < }
  [verified] thread/start rejected approvalPolicy=Reject without experimentalApi
  ```
  
  ---------
  
  Co-authored-by: celia-oai <celia@openai.com>

  Dylan Hurd · 2026-03-11 12:33:08 -07:00
  d5694529ca
• Implemented thread-level atomic elicitation counter for stopwatch pausing (#12296)

  ### Purpose
  While trying to build out CLI-Tools for the agent to use under skills we
  have found that those tools sometimes need to invoke a user elicitation.
  These elicitations are handled out of band of the codex app-server but
  need to indicate to the exec manager that the command running is not
  going to progress on the usual timeout horizon.
  
  ### Example
  Model calls universal exec:
  `$ download-credit-card-history --start-date 2026-01-19 --end-date
  2026-02-19 > credit_history.jsonl`
  
  download-cred-card-history might hit a hosted/preauthenticated service
  to fetch data. That service might decide that the request requires an
  end user approval the access to the personal data. It should be able to
  signal to the running thread that the command in question is blocked on
  user elicitation. In that case we want the exec to continue, but the
  timeout to not expire on the tool call, essentially freezing time until
  the user approves or rejects the command at which point the tool would
  signal the app-server to decrement the outstanding elicitation count.
  Now timeouts would proceed as normal.
  
  ### What's Added
  
  - New v2 RPC methods:
      - thread/increment_elicitation
      - thread/decrement_elicitation
  - Protocol updates in:
      - codex-rs/app-server-protocol/src/protocol/common.rs
      - codex-rs/app-server-protocol/src/protocol/v2.rs
  - App-server handlers wired in:
      - codex-rs/app-server/src/codex_message_processor.rs
  
  ### Behavior
  
  - Counter starts at 0 per thread.
  - increment atomically increases the counter.
  - decrement atomically decreases the counter; decrement at 0 returns
  invalid request.
  - Transition rules:
  - 0 -> 1: broadcast pause state, pausing all active stopwatches
  immediately.
      - \>0 -> >0: remain paused.
      - 1 -> 0: broadcast unpause state, resuming stopwatches.
  - Core thread/session logic:
      - codex-rs/core/src/codex_thread.rs
      - codex-rs/core/src/codex.rs
      - codex-rs/core/src/mcp_connection_manager.rs
  
  ### Exec-server stopwatch integration
  
  - Added centralized stopwatch tracking/controller:
      - codex-rs/exec-server/src/posix/stopwatch_controller.rs
  - Hooked pause/unpause broadcast handling + stopwatch registration:
      - codex-rs/exec-server/src/posix/mcp.rs
      - codex-rs/exec-server/src/posix/stopwatch.rs
      - codex-rs/exec-server/src/posix.rs

  Channing Conger · 2026-03-09 22:29:26 -07:00
  c6343e0649
• start of hooks engine (#13276)

  (Experimental)
  
  This PR adds a first MVP for hooks, with SessionStart and Stop
  
  The core design is:
  
  - hooks live in a dedicated engine under codex-rs/hooks
  - each hook type has its own event-specific file
  - hook execution is synchronous and blocks normal turn progression while
  running
  - matching hooks run in parallel, then their results are aggregated into
  a normalized HookRunSummary
  
  On the AppServer side, hooks are exposed as operational metadata rather
  than transcript-native items:
  
  - new live notifications: hook/started, hook/completed
  - persisted/replayed hook results live on Turn.hookRuns
  - we intentionally did not add hook-specific ThreadItem variants
  
  Hooks messages are not persisted, they remain ephemeral. The context
  changes they add are (they get appended to the user's prompt)

  Andrei Eternal · 2026-03-10 04:11:31 +00:00
  244b2d53f4
• Stabilize protocol schema fixture generation (#13886)

  ## What changed
  - TypeScript schema fixture generation now goes through in-memory tree
  helpers rather than a heavier on-disk generation path.
  - The comparison logic normalizes generated banner and path differences
  that are not semantically relevant to the exported schema.
  - TypeScript and JSON fixture coverage are split into separate tests,
  and the expensive schema-export tests are serialized in `nextest`.
  
  ## Why this fixes the flake
  - The original fixture coverage mixed several heavy codegen paths into
  one monolithic test and then compared generated output that included
  incidental banner/path differences.
  - On Windows CI, that combination created both runtime pressure and
  output variance unrelated to the schema shapes we actually care about.
  - Splitting the coverage isolates failures by format, in-memory
  generation reduces filesystem churn, normalization strips generator
  noise, and serializing the heavy tests removes parallel resource
  contention.
  
  ## Scope
  - Production helper change plus test changes.

  Ahmed Ibrahim · 2026-03-09 13:51:50 -07:00
  831ee51c86
• chore: plugin/uninstall endpoint (#14111)

  add `plugin/uninstall` app-server endpoint to fully rm plugin from
  plugins cache dir and rm entry from user config file.
  
  plugin-enablement is session-scoped, so uninstalls are only picked up in
  new sessions (like installs).
  
  added tests.

  sayan-oai · 2026-03-09 12:40:25 -07:00
  6ad448b658
• Add request permissions tool (#13092)

  Adds a built-in `request_permissions` tool and wires it through the
  Codex core, protocol, and app-server layers so a running turn can ask
  the client for additional permissions instead of relying on a static
  session policy.
  
  The new flow emits a `RequestPermissions` event from core, tracks the
  pending request by call ID, forwards it through app-server v2 as an
  `item/permissions/requestApproval` request, and resumes the tool call
  once the client returns an approved subset of the requested permission
  profile.

  Jack Mousseau · 2026-03-08 20:23:06 -07:00
  e6b93841c5
• app-server: include experimental skill metadata in exec approval requests (#13929)

  ## Summary
  
  This change surfaces skill metadata on command approval requests so
  app-server clients can tell when an approval came from a skill script
  and identify the originating `SKILL.md`.
  
  - add `skill_metadata` to exec approval events in the shared protocol
  - thread skill metadata through core shell escalation and delegated
  approval handling for skill-triggered approvals
  - expose the field in app-server v2 as experimental `skillMetadata`
  - regenerate the JSON/TypeScript schemas and cover the new field in
  protocol, transport, core, and TUI tests
  
  ## Why
  
  Skill-triggered approvals already carry skill context inside core, but
  app-server clients could not see which skill caused the prompt. Sending
  the skill metadata with the approval request makes it possible for
  clients to present better approval UX and connect the prompt back to the
  relevant skill definition.
  
  
  ## example event in app-server-v2
  verified that we see this event when experimental api is on:
  ```
  < {
  <   "id": 11,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "additionalPermissions": {
  <       "fileSystem": null,
  <       "macos": {
  <         "accessibility": false,
  <         "automations": {
  <           "bundle_ids": [
  <             "com.apple.Notes"
  <           ]
  <         },
  <         "calendar": false,
  <         "preferences": "read_only"
  <       },
  <       "network": null
  <     },
  <     "approvalId": "25d600ee-5a3c-4746-8d17-e2e61fb4c563",
  <     "availableDecisions": [
  <       "accept",
  <       "acceptForSession",
  <       "cancel"
  <     ],
  <     "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <     "commandActions": [
  <       {
  <         "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes",
  <     "itemId": "call_jZp3xFpNg4D8iKAD49cvEvZy",
  <     "skillMetadata": {
  <       "pathToSkillsMd": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/SKILL.md"
  <     },
  <     "threadId": "019ccc10-b7d3-7ff2-84fe-3a75e7681e69",
  <     "turnId": "019ccc10-b848-76f1-81b3-4a1fa225493f"
  <   }
  < }`
  ```
  
  & verified that this is the event when experimental api is off:
  ```
  < {
  <   "id": 13,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "approvalId": "5fbbf776-261b-4cf8-899b-c125b547f2c0",
  <     "availableDecisions": [
  <       "accept",
  <       "acceptForSession",
  <       "cancel"
  <     ],
  <     "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <     "commandActions": [
  <       {
  <         "command": "/Applications/ChatGPT.app/Contents/Resources/CodexAppServer_CodexAppServerBundledSkills.bundle/Contents/Resources/skills/apple-notes/scripts/notes_info",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Users/celia/code/codex/codex-rs",
  <     "itemId": "call_OV2DHzTgYcbYtWaTTBWlocOt",
  <     "threadId": "019ccc16-2a2b-7be1-8500-e00d45b892d4",
  <     "turnId": "019ccc16-2a8e-7961-98ec-649600e7d06a"
  <   }
  < }
  ```

  Celia Chen · 2026-03-08 18:07:46 -07:00
  340f9c9ecb
• Add in-process app server and wire up exec to use it (#14005)

  This is a subset of PR #13636. See that PR for a full overview of the
  architectural change.
  
  This PR implements the in-process app server and modifies the
  non-interactive "exec" entry point to use the app server.
  
  ---------
  
  Co-authored-by: Felipe Coury <felipe.coury@gmail.com>

  Eric Traut · 2026-03-08 18:43:55 -06:00
  da3689f0ef
• app-server: Add streaming and tty/pty capabilities to command/exec (#13640)

  * Add an ability to stream stdin, stdout, and stderr
  * Streaming of stdout and stderr has a configurable cap for total amount
  of transmitted bytes (with an ability to disable it)
  * Add support for overriding environment variables
  * Add an ability to terminate running applications (using
  `command/exec/terminate`)
  * Add TTY/PTY support, with an ability to resize the terminal (using
  `command/exec/resize`)

  Ruslan Nigmatullin · 2026-03-06 17:30:17 -08:00
  e9bd8b20a1
• [elicitations] Switch to use MCP style elicitation payload for mcp tool approvals. (#13621)

  - [x] Switch to use MCP style elicitation payload for mcp tool
  approvals.
  - [ ] TODO: Update the UI to support the full spec.

  Matthew Zeng · 2026-03-06 01:50:26 -08:00
  98dca99db7
• support plugin/list. (#13540)

  Introduce a plugin/list which reads from local marketplace.json.
  Also update the signature for plugin/install.

  xl-openai · 2026-03-05 21:58:50 -05:00
  520ed724d2
• feat(app-server): support mcp elicitations in v2 api (#13425)

  This adds a first-class server request for MCP server elicitations:
  `mcpServer/elicitation/request`.
  
  Until now, MCP elicitation requests only showed up as a raw
  `codex/event/elicitation_request` event from core. That made it hard for
  v2 clients to handle elicitations using the same request/response flow
  as other server-driven interactions (like shell and `apply_patch`
  tools).
  
  This also updates the underlying MCP elicitation request handling in
  core to pass through the full MCP request (including URL and form data)
  so we can expose it properly in app-server.
  
  ### Why not `item/mcpToolCall/elicitationRequest`?
  This is because MCP elicitations are related to MCP servers first, and
  only optionally to a specific MCP tool call.
  
  In the MCP protocol, elicitation is a server-to-client capability: the
  server sends `elicitation/create`, and the client replies with an
  elicitation result. RMCP models it that way as well.
  
  In practice an elicitation is often triggered by an MCP tool call, but
  not always.
  
  ### What changed
  - add `mcpServer/elicitation/request` to the v2 app-server API
  - translate core `codex/event/elicitation_request` events into the new
  v2 server request
  - map client responses back into `Op::ResolveElicitation` so the MCP
  server can continue
  - update app-server docs and generated protocol schema
  - add an end-to-end app-server test that covers the full round trip
  through a real RMCP elicitation flow
  - The new test exercises a realistic case where an MCP tool call
  triggers an elicitation, the app-server emits
  mcpServer/elicitation/request, the client accepts it, and the tool call
  resumes and completes successfully.
  
  ### app-server API flow
  - Client starts a thread with `thread/start`.
  - Client starts a turn with `turn/start`.
  - App-server sends `item/started` for the `mcpToolCall`.
  - While that tool call is in progress, app-server sends
  `mcpServer/elicitation/request`.
  - Client responds to that request with `{ action: "accept" | "decline" |
  "cancel" }`.
  - App-server sends `serverRequest/resolved`.
  - App-server sends `item/completed` for the mcpToolCall.
  - App-server sends `turn/completed`.
  - If the turn is interrupted while the elicitation is pending,
  app-server still sends `serverRequest/resolved` before the turn
  finishes.

  Owen Lin · 2026-03-05 07:20:20 -08:00
  926b2f19e8
• plugin: support local-based marketplace.json + install endpoint. (#13422)

  Support marketplace.json that points to a local file, with
  ```
      "source":
      {
          "source": "local",
          "path": "./plugin-1"
      },
   ```
   
   Add a new plugin/install endpoint which add the plugin to the cache folder and enable it in config.toml.

  xl-openai · 2026-03-04 19:08:18 -05:00
  1e877ccdd2