88 Commits

• app-server: Replay pending item requests on thread/resume (#12560)

  Replay pending client requests after `thread/resume` and emit resolved
  notifications when those requests clear so approval/input UI state stays
  in sync after reconnects and across subscribed clients.
  
  Affected RPCs:
  - `item/commandExecution/requestApproval`
  - `item/fileChange/requestApproval`
  - `item/tool/requestUserInput`
  
  Motivation:
  - Resumed clients need to see pending approval/input requests that were
  already outstanding before the reconnect.
  - Clients also need an explicit signal when a pending request resolves
  or is cleared so stale UI can be removed on turn start, completion, or
  interruption.
  
  Implementation notes:
  - Use pending client requests from `OutgoingMessageSender` in order to
  replay them after `thread/resume` attaches the connection, using
  original request ids.
  - Emit `serverRequest/resolved` when pending requests are answered
  or cleared by lifecycle cleanup.
  - Update the app-server protocol schema, generated TypeScript bindings,
  and README docs for the replay/resolution flow.
  
  High-level test plan:
  - Added automated coverage for replaying pending command execution and
  file change approval requests on `thread/resume`.
  - Added automated coverage for resolved notifications in command
  approval, file change approval, request_user_input, turn start, and turn
  interrupt flows.
  - Verified schema/docs updates in the relevant protocol and app-server
  tests.
  
  Manual testing:
  - Tested reconnect/resume with multiple connections.
  - Confirmed state stayed in sync between connections.

  Ruslan Nigmatullin · 2026-02-27 12:45:59 -08:00
  69d7a456bb
• fix: use AbsolutePathBuf for permission profile file roots (#12970)

  ## Why
  `PermissionProfile` should describe filesystem roots as absolute paths
  at the type level. Using `PathBuf` in `FileSystemPermissions` made the
  shared type too permissive and blurred together three different
  deserialization cases:
  
  - skill metadata in `agents/openai.yaml`, where relative paths should
  resolve against the skill directory
  - app-server API payloads, where callers should have to send absolute
  paths
  - local tool-call payloads for commands like `shell_command` and
  `exec_command`, where `additional_permissions.file_system` may
  legitimately be relative to the command `workdir`
  
  This change tightens the shared model without regressing the existing
  local command flow.
  
  ## What Changed
  - changed `protocol::models::FileSystemPermissions` and the app-server
  `AdditionalFileSystemPermissions` mirror to use `AbsolutePathBuf`
  - wrapped skill metadata deserialization in `AbsolutePathBufGuard`, so
  relative permission roots in `agents/openai.yaml` resolve against the
  containing skill directory
  - kept app-server/API deserialization strict, so relative
  `additionalPermissions.fileSystem.*` paths are rejected at the boundary
  - restored cwd/workdir-relative deserialization for local tool-call
  payloads by parsing `shell`, `shell_command`, and `exec_command`
  arguments under an `AbsolutePathBufGuard` rooted at the resolved command
  working directory
  - simplified runtime additional-permission normalization so it only
  canonicalizes and deduplicates absolute roots instead of trying to
  recover relative ones later
  - updated the app-server schema fixtures, `app-server/README.md`, and
  the affected transport/TUI tests to match the final behavior

  Michael Bolin · 2026-02-27 17:42:52 +00:00
  d09a7535ed
• feat: include available decisions in command approval requests (#12758)

  Command-approval clients currently infer which choices to show from
  side-channel fields like `networkApprovalContext`,
  `proposedExecpolicyAmendment`, and `additionalPermissions`. That makes
  the request shape harder to evolve, and it forces each client to
  replicate the server's heuristics instead of receiving the exact
  decision list for the prompt.
  
  This PR introduces a mapping between `CommandExecutionApprovalDecision`
  and `codex_protocol::protocol::ReviewDecision`:
  
  ```rust
  impl From<CoreReviewDecision> for CommandExecutionApprovalDecision {
      fn from(value: CoreReviewDecision) -> Self {
          match value {
              CoreReviewDecision::Approved => Self::Accept,
              CoreReviewDecision::ApprovedExecpolicyAmendment {
                  proposed_execpolicy_amendment,
              } => Self::AcceptWithExecpolicyAmendment {
                  execpolicy_amendment: proposed_execpolicy_amendment.into(),
              },
              CoreReviewDecision::ApprovedForSession => Self::AcceptForSession,
              CoreReviewDecision::NetworkPolicyAmendment {
                  network_policy_amendment,
              } => Self::ApplyNetworkPolicyAmendment {
                  network_policy_amendment: network_policy_amendment.into(),
              },
              CoreReviewDecision::Abort => Self::Cancel,
              CoreReviewDecision::Denied => Self::Decline,
          }
      }
  }
  ```
  
  And updates `CommandExecutionRequestApprovalParams` to have a new field:
  
  ```rust
  available_decisions: Option<Vec<CommandExecutionApprovalDecision>>
  ```
  
  when, if specified, should make it easier for clients to display an
  appropriate list of options in the UI.
  
  This makes it possible for `CoreShellActionProvider::prompt()` in
  `unix_escalation.rs` to specify the `Vec<ReviewDecision>` directly,
  adding support for `ApprovedForSession` when approving a skill script,
  which was previously missing in the TUI.
  
  Note this results in a significant change to `exec_options()` in
  `approval_overlay.rs`, as the displayed options are now derived from
  `available_decisions: &[ReviewDecision]`.
  
  ## What Changed
  
  - Add `available_decisions` to
  [`ExecApprovalRequestEvent`](https://github.com/openai/codex/blob/de00e932dd9801de0a4faac0519162099753f331/codex-rs/protocol/src/approvals.rs#L111-L175),
  including helpers to derive the legacy default choices when older
  senders omit the field.
  - Map `codex_protocol::protocol::ReviewDecision` to app-server
  `CommandExecutionApprovalDecision` and expose the ordered list as
  experimental `availableDecisions` in
  [`CommandExecutionRequestApprovalParams`](https://github.com/openai/codex/blob/de00e932dd9801de0a4faac0519162099753f331/codex-rs/app-server-protocol/src/protocol/v2.rs#L3798-L3807).
  - Thread optional `available_decisions` through the core approval path
  so Unix shell escalation can explicitly request `ApprovedForSession` for
  session-scoped approvals instead of relying on client heuristics.
  [`unix_escalation.rs`](https://github.com/openai/codex/blob/de00e932dd9801de0a4faac0519162099753f331/codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs#L194-L214)
  - Update the TUI approval overlay to build its buttons from the ordered
  decision list, while preserving the legacy fallback when
  `available_decisions` is missing.
  - Update the app-server README, test client output, and generated schema
  artifacts to document and surface the new field.
  
  ## Testing
  
  - Add `approval_overlay.rs` coverage for explicit decision lists,
  including the generic `ApprovedForSession` path and network approval
  options.
  - Update `chatwidget/tests.rs` and app-server protocol tests to populate
  the new optional field and keep older event shapes working.
  
  ## Developers Docs
  
  - If we document `item/commandExecution/requestApproval` on
  [developers.openai.com/codex](https://developers.openai.com/codex), add
  experimental `availableDecisions` as the preferred source of approval
  choices and note that older servers may omit it.

  Michael Bolin · 2026-02-26 01:10:46 +00:00
  14116ade8d
• Revert "Add skill approval event/response (#12633)" (#12811)

  This reverts commit https://github.com/openai/codex/pull/12633. We no
  longer need this PR, because we favor sending normal exec command
  approval server request with `additional_permissions` of skill
  permissions instead

  Celia Chen · 2026-02-26 01:02:42 +00:00
  4f45668106
• feat(app-server): thread/unsubscribe API (#10954)

  Adds a new v2 app-server API for a client to be able to unsubscribe to a
  thread:
  - New RPC method: `thread/unsubscribe`
  - New server notification: `thread/closed`
  
  Today clients can start/resume/archive threads, but there wasn’t a way
  to explicitly unload a live thread from memory without archiving it.
  With `thread/unsubscribe`, a client can indicate it is no longer
  actively working with a live Thread. If this is the only client
  subscribed to that given thread, the thread will be automatically closed
  by app-server, at which point the server will send `thread/closed` and
  `thread/status/changed` with `status: notLoaded` notifications.
  
  This gives clients a way to prevent long-running app-server processes
  from accumulating too many thread (and related) objects in memory.
  
  Closed threads will also be removed from `thread/loaded/list`.

  Owen Lin · 2026-02-25 13:14:30 -08:00
  21f7032dbb
• Add app-server v2 thread realtime API (#12715)

  Add experimental `thread/realtime/*` v2 requests and notifications, then
  route app-server realtime events through that thread-scoped surface with
  integration coverage.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-02-25 09:59:10 -08:00
  947092283a
• Support external agent config detect and import (#12660)

  Migration Behavior
  
  * Config
    *  Migrates settings.json into config.toml
  * Only adds fields when config.toml is missing, or when those fields are
  missing from the existing file
    *  Supported mappings:
      env -> shell_environment_policy
       sandbox.enabled = true -> sandbox_mode = "workspace-write"
  
  * Skills
    *  Copies home and repo .claude/skills into .agents/skills
    *  Existing skill directories are not overwritten
    *  SKILL.md content is rewritten from Claude-related terms to Codex
  
  * AgentsMd
    *  Repo only
    *  Migrates CLAUDE.md into AGENTS.md
  * Detect/import only proceed when AGENTS.md is missing or present but
  empty
    *  Content is rewritten from Claude-related terms to Codex

  alexsong-oai · 2026-02-25 02:11:51 -08:00
  6d6570d89d
• feat(ui): add network approval persistence plumbing (#12358)

  ## Summary
  - add TUI approval options for persistent network host rules
  - add app-server v2 approval payload plumbing for network approval
  context + proposed network policy amendments
  - add app-server handling to translate `applyNetworkPolicyAmendment`
  decisions back into core review decisions
  - update docs/test client output and generated app-server schemas/types

  viyatb-oai · 2026-02-25 07:06:19 +00:00
  c086b36b58
• feat: add experimental additionalPermissions to v2 command execution approval requests (#12737)

  This adds additionalPermissions to the app-server v2
  item/commandExecution/requestApproval payload as an experimental field.
  
  The field is now exposed on CommandExecutionRequestApprovalParams and is
  populated from the existing core approval event when a command requests
  additional sandbox permissions.
  
  This PR also contains changes to make server requests to support
  experiment API.
  
  A real app server test client test:
  
  sample payload with experimental flag off:
  ```
   {
  <   "id": 0,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "command": "/bin/zsh -lc 'mkdir -p ~/some/test && touch ~/some/test/file'",
  <     "commandActions": [
  <       {
  <         "command": "mkdir -p '~/some/test'",
  <         "type": "unknown"
  <       },
  <       {
  <         "command": "touch '~/some/test/file'",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Users/celia/code/codex/codex-rs",
  <     "itemId": "call_QLp0LWkQ1XkU6VW9T2vUZFWB",
  <     "proposedExecpolicyAmendment": [
  <       "mkdir",
  <       "-p",
  <       "~/some/test"
  <     ],
  <     "reason": "Do you want to allow creating ~/some/test/file outside the workspace?",
  <     "threadId": "019c9309-e209-7d82-a01b-dcf9556a354d",
  <     "turnId": "019c9309-e27a-7f33-834f-6011e795c2d6"
  <   }
  < }
  ```
  with experimental flag on: 
  ```
  < {
  <   "id": 0,
  <   "method": "item/commandExecution/requestApproval",
  <   "params": {
  <     "additionalPermissions": {
  <       "fileSystem": null,
  <       "macos": null,
  <       "network": true
  <     },
  <     "command": "/bin/zsh -lc 'install -D /dev/null ~/some/test/file'",
  <     "commandActions": [
  <       {
  <         "command": "install -D /dev/null '~/some/test/file'",
  <         "type": "unknown"
  <       }
  <     ],
  <     "cwd": "/Users/celia/code/codex/codex-rs",
  <     "itemId": "call_K3U4b3dRbj3eMCqslmncbGsq",
  <     "proposedExecpolicyAmendment": [
  <       "install",
  <       "-D"
  <     ],
  <     "reason": "Do you want to allow creating the file at ~/some/test/file outside the workspace sandbox?",
  <     "threadId": "019c9303-3a8e-76e1-81bf-d67ac446d892",
  <     "turnId": "019c9303-3af1-7143-88a1-73132f771234"
  <   }
  < }
  ```

  Celia Chen · 2026-02-25 05:16:35 +00:00
  1151972fb2
• Add skill approval event/response (#12633)

  Set the stage for skill-level permission approval in addition to
  command-level.
  
  Behind a feature flag.

  pakrym-oai · 2026-02-23 22:28:58 -08:00
  58763afa0f
• app-server: expose loaded thread status via read/list and notifications (#11786)

  Motivation
  - Today, a newly connected client has no direct way to determine the
  current runtime status of threads from read/list responses alone.
  - This forces clients to infer state from transient events, which can
  lead to stale or inconsistent UI when reconnecting or attaching late.
  
  Changes
  - Add `status` to `thread/read` responses.
  - Add `statuses` to `thread/list` responses.
  - Emit `thread/status/changed` notifications with `threadId` and the new
  status.
  - Track runtime status for all loaded threads and default unknown
  threads to `idle`.
  - Update protocol/docs/tests/schema fixtures for the revised API.
  
  Testing
  - Validated protocol API changes with automated protocol tests and
  regenerated schema/type fixtures.
  - Validated app-server behavior with unit and integration test suites,
  including status transitions and notifications.

  Ruslan Nigmatullin · 2026-02-18 15:20:03 -08:00
  1f54496c48
• app-server support for Windows sandbox setup. (#12025)

  app-server support for initiating Windows sandbox setup.
  server responds quickly to setup request and makes a future RPC call
  back to client when the setup finishes.
  
  The TUI implementation is unaffected but in a future PR I'll update the
  TUI to use the shared setup helper
  (`windows_sandbox.run_windows_sandbox_setup`)

  iceweasel-oai · 2026-02-18 13:03:16 -08:00
  292542616a
• feat(core): plumb distinct approval ids for command approvals (#12051)

  zsh fork PR stack:
  - https://github.com/openai/codex/pull/12051 👈 
  - https://github.com/openai/codex/pull/12052
  
  With upcoming support for a fork of zsh that allows us to intercept
  `execve` and run execpolicy checks for each subcommand as part of a
  `CommandExecution`, it will be possible for there to be multiple
  approval requests for a shell command like `/path/to/zsh -lc 'git status
  && rg \"TODO\" src && make test'`.
  
  To support that, this PR introduces a new `approval_id` field across
  core, protocol, and app-server so that we can associate approvals
  properly for subcommands.

  Owen Lin · 2026-02-18 01:55:57 +00:00
  db4d2599b5
• app-server: Emit thread archive/unarchive notifications (#12030)

  * Add v2 server notifications `thread/archived` and `thread/unarchived`
  with a `threadId` payload.
  * Wire new events into `thread/archive` and `thread/unarchive` success
  paths.
  * Update app-server protocol/schema/docs accordingly.
  
  Testing:
  - Updated archive/unarchive end-to-end tests to verify both
  notifications are emitted with the expected thread id payload.

  Ruslan Nigmatullin · 2026-02-17 14:53:58 -08:00
  31cbebd3c2
• Add remote skill scope/product_surface/enabled params and cleanup (#11801)

  skills/remote/list: params=hazelnutScope, productSurface, enabled;
  returns=data: { id, name, description }[]
  skills/remote/export: params=hazelnutId; returns={ id, path }

  xl-openai · 2026-02-17 11:05:22 -08:00
  314029ffa3
• Feat: add model reroute notification (#12001)

  ### Summary
  Builiding off
  https://github.com/openai/codex/pull/11964/files/5c75aa7b89a70bc2cc410a6fd238749306ec4c5e#diff-058ae8f109a8b84b4b79bbfa45f522c2233b9d9e139696044ae374d50b6196e0,
  we have created a `model/rerouted` notification that captures the event
  so that consumers can render as expected. Keep the `EventMsg::Warning`
  path in core so that this does not affect TUI rendering.
  
  `model/rerouted` is meant to be generic to account for future usage
  including capacity planning etc.

  Shijie Rao · 2026-02-17 11:02:23 -08:00
  48018e9eac
• fix: send unfiltered models over model/list (#11793)

  ### What
  to unblock filtering models in VSCE, change `model/list` app-server
  endpoint to send all models + visibility field `showInPicker` so
  filtering can be done in VSCE if desired.
  
  ### Tests
  Updated tests.

  sayan-oai · 2026-02-13 16:26:32 -08:00
  6b466df146
• [app-server] add fuzzyFileSearch/sessionCompleted (#11773)

  this is to allow the client to know when to stop showing a spinner.

  Jeremy Rose · 2026-02-13 15:08:14 -08:00
  e4f8263798
• feat(app-server): experimental flag to persist extended history (#11227)

  This PR adds an experimental `persist_extended_history` bool flag to
  app-server thread APIs so rollout logs can retain a richer set of
  EventMsgs for non-lossy Thread > Turn > ThreadItems reconstruction (i.e.
  on `thread/resume`).
  
  ### Motivation
  Today, our rollout recorder only persists a small subset (e.g. user
  message, reasoning, assistant message) of `EventMsg` types, dropping a
  good number (like command exec, file change, etc.) that are important
  for reconstructing full item history for `thread/resume`, `thread/read`,
  and `thread/fork`.
  
  Some clients want to be able to resume a thread without lossiness. This
  lossiness is primarily a UI thing, since what the model sees are
  `ResponseItem` and not `EventMsg`.
  
  ### Approach
  This change introduces an opt-in `persist_full_history` flag to preserve
  those events when you start/resume/fork a thread (defaults to `false`).
  
  This is done by adding an `EventPersistenceMode` to the rollout
  recorder:
  - `Limited` (existing behavior, default)
  - `Extended` (new opt-in behavior)
  
  In `Extended` mode, persist additional `EventMsg` variants needed for
  non-lossy app-server `ThreadItem` reconstruction. We now store the
  following ThreadItems that we didn't before:
  - web search
  - command execution
  - patch/file changes
  - MCP tool calls
  - image view calls
  - collab tool outcomes
  - context compaction
  - review mode enter/exit
  
  For **command executions** in particular, we truncate the output using
  the existing `truncate_text` from core to store an upper bound of 10,000
  bytes, which is also the default value for truncating tool outputs shown
  to the model. This keeps the size of the rollout file and command
  execution items returned over the wire reasonable.
  
  And we also persist `EventMsg::Error` which we can now map back to the
  Turn's status and populates the Turn's error metadata.
  
  #### Updates to EventMsgs
  To truly make `thread/resume` non-lossy, we also needed to persist the
  `status` on `EventMsg::CommandExecutionEndEvent` and
  `EventMsg::PatchApplyEndEvent`. Previously it was not obvious whether a
  command failed or was declined (similar for apply_patch). These
  EventMsgs were never persisted before so I made it a required field.

  Owen Lin · 2026-02-12 19:34:22 +00:00
  efc8d45750
• app-server: add fuzzy search sessions for streaming file search (#10268)
  Jeremy Rose · 2026-02-12 10:49:44 -08:00
  66e0c3aaa3
• feat: opt-out of events in the app-server (#11319)

  Add `optOutNotificationMethods` in the app-server to opt-out events
  based on exact method matching

  jif-oai · 2026-02-10 18:04:52 +00:00
  a364dd8b56
• [apps] Add thread_id param to optionally load thread config for apps feature check. (#11279)

  - [x] Add thread_id param to optionally load thread config for apps
  feature check

  Matthew Zeng · 2026-02-09 23:10:26 -08:00
  005e040f97
• fix(app-server): for external auth, replace id_token with chatgpt_acc… (#11240)

  …ount_id and chatgpt_plan_type
  
  ### Summary
  Following up on external auth mode which was introduced here:
  https://github.com/openai/codex/pull/10012
  
  Turns out some clients have a differently shaped ID token and don't have
  a chosen workspace (aka chatgpt_account_id) encoded in their ID token.
  So, let's replace `id_token` param with `chatgpt_account_id` and
  `chatgpt_plan_type` (optional) when initializing the external ChatGPT
  auth mode (`account/login/start` with `chatgptAuthTokens`).
  
  The client was able to test end-to-end with a Codex build from this
  branch and verified it worked!

  Owen Lin · 2026-02-09 20:48:58 -08:00
  53741013ab
• feat: do not close unified exec processes across turns (#10799)

  With this PR we do not close the unified exec processes (i.e. background
  terminals) at the end of a turn unless:
  * The user interrupt the turn
  * The user decide to clean the processes through `app-server` or
  `/clean`
  
  I made sure that `codex exec` correctly kill all the processes

  jif-oai · 2026-02-09 10:27:46 +00:00
  6cf61725d0
• [apps] Improve app loading. (#10994)

  There are two concepts of apps that we load in the harness:
  
  - Directory apps, which is all the apps that the user can install.
  - Accessible apps, which is what the user actually installed and can be
  $ inserted and be used by the model. These are extracted from the tools
  that are loaded through the gateway MCP.
  
  Previously we wait for both sets of apps before returning the full apps
  list. Which causes many issues because accessible apps won't be
  available to the UI or the model if directory apps aren't loaded or
  failed to load.
  
  In this PR we are separating them so that accessible apps can be loaded
  separately and are instantly available to be shown in the UI and to be
  provided in model context. We also added an app-server event so that
  clients can subscribe to also get accessible apps without being blocked
  on the full app list.
  
  - [x] Separate accessible apps and directory apps loading.
  - [x] `app/list` request will also emit `app/list/updated` notifications
  that app-server clients can subscribe. Which allows clients to get
  accessible apps list to render in the $ menu without being blocked by
  directory apps.
  - [x] Cache both accessible and directory apps with 1 hour TTL to avoid
  reloading them when creating new threads.
  - [x] TUI improvements to redraw $ menu and /apps menu when app list is
  updated.

  Matthew Zeng · 2026-02-08 15:24:56 -08:00
  45b7763c3f
• chore(app-server): add experimental annotation to relevant fields (#10928)

  These fields had always been documented as experimental/unstable with
  docstrings, but now let's actually use the `experimental` annotation to
  be more explicit.
  
  - thread/start.experimentalRawEvents
  - thread/resume.history
  - thread/resume.path
  - thread/fork.path
  - turn/start.collaborationMode
  - account/login/start.chatgptAuthTokens

  Owen Lin · 2026-02-06 20:48:04 +00:00
  1751116ec6
• feat(app-server): turn/steer API (#10821)

  This PR adds a dedicated `turn/steer` API for appending user input to an
  in-flight turn.
  
  ## Motivation
  Currently, steering in the app is implemented by just calling
  `turn/start` while a turn is running. This has some really weird quirks:
  - Client gets back a new `turn.id`, even though streamed
  events/approvals remained tied to the original active turn ID.
  - All the various turn-level override params on `turn/start` do not
  apply to the "steer", and would only apply to the next real turn.
  - There can also be a race condition where the client thinks the turn is
  active but the server has already completed it, so there might be bugs
  if the client has baked in some client-specific behavior thinking it's a
  steer when in fact the server kicked off a new turn. This is
  particularly possible when running a client against a remote app-server.
  
  Having a dedicated `turn/steer` API eliminates all those quirks.
  
  `turn/steer` behavior:
  - Requires an active turn on threadId. Returns a JSON-RPC error if there
  is no active turn.
  - If expectedTurnId is provided, it must match the active turn (more
  useful when connecting to a remote app-server).
  - Does not emit `turn/started`.
  - Does not accept turn overrides (`cwd`, `model`, `sandbox`, etc.) or
  `outputSchema` to accurately reflect that these are not applied when
  steering.

  Owen Lin · 2026-02-06 00:35:04 +00:00
  0d8b2b74c4
• [app-server] Add a method to list experimental features. (#10721)

  - [x] Add a method to list experimental features.

  Matthew Zeng · 2026-02-05 20:04:01 +00:00
  7e81f63698
• Add thread/compact v2 (#10445)

  - add `thread/compact` as a trigger-only v2 RPC that submits
  `Op::Compact` and returns `{}` immediately.
  - add v2 compaction e2e coverage for success and invalid/unknown thread
  ids, and update protocol schemas/docs.

  Ahmed Ibrahim · 2026-02-03 18:15:55 -08:00
  38a47700b5
• feat: add APIs to list and download public remote skills (#10448)

  Add API to list / download from remote public skills

  xl-openai · 2026-02-03 14:09:37 -08:00
  f38d181795
• feat: experimental flags (#10231)

  ## Problem being solved
  - We need a single, reliable way to mark app-server API surface as
  experimental so that:
    1. the runtime can reject experimental usage unless the client opts in
  2. generated TS/JSON schemas can exclude experimental methods/fields for
  stable clients.
  
  Right now that’s easy to drift or miss when done ad-hoc.
  
  ## How to declare experimental methods and fields
  - **Experimental method**: add `#[experimental("method/name")]` to the
  `ClientRequest` variant in `client_request_definitions!`.
  - **Experimental field**: on the params struct, derive `ExperimentalApi`
  and annotate the field with `#[experimental("method/name.field")]` + set
  `inspect_params: true` for the method variant so
  `ClientRequest::experimental_reason()` inspects params for experimental
  fields.
  
  ## How the macro solves it
  - The new derive macro lives in
  `codex-rs/codex-experimental-api-macros/src/lib.rs` and is used via
  `#[derive(ExperimentalApi)]` plus `#[experimental("reason")]`
  attributes.
  - **Structs**:
  - Generates `ExperimentalApi::experimental_reason(&self)` that checks
  only annotated fields.
    - The “presence” check is type-aware:
      - `Option<T>`: `is_some_and(...)` recursively checks inner.
      - `Vec`/`HashMap`/`BTreeMap`: must be non-empty.
      - `bool`: must be `true`.
      - Other types: considered present (returns `true`).
  - Registers each experimental field in an `inventory` with `(type_name,
  serialized field name, reason)` and exposes `EXPERIMENTAL_FIELDS` for
  that type. Field names are converted from `snake_case` to `camelCase`
  for schema/TS filtering.
  - **Enums**:
  - Generates an exhaustive `match` returning `Some(reason)` for annotated
  variants and `None` otherwise (no wildcard arm).
  - **Wiring**:
  - Runtime gating uses `ExperimentalApi::experimental_reason()` in
  `codex-rs/app-server/src/message_processor.rs` to reject requests unless
  `InitializeParams.capabilities.experimental_api == true`.
  - Schema/TS export filters use the inventory list and
  `EXPERIMENTAL_CLIENT_METHODS` from `client_request_definitions!` to
  strip experimental methods/fields when `experimental_api` is false.

  jif-oai · 2026-02-02 11:06:50 +00:00
  3cc9122ee2
• chore: rename ChatGpt -> Chatgpt in type names (#10244)

  When using ChatGPT in names of types, we should be consistent, so this
  renames some types with `ChatGpt` in the name to `Chatgpt`. From
  https://rust-lang.github.io/api-guidelines/naming.html:
  
  > In `UpperCamelCase`, acronyms and contractions of compound words count
  as one word: use `Uuid` rather than `UUID`, `Usize` rather than `USize`
  or `Stdin` rather than `StdIn`. In `snake_case`, acronyms and
  contractions are lower-cased: `is_xid_start`.
  
  This PR updates existing uses of `ChatGpt` and changes them to
  `Chatgpt`. Though in all cases where it could affect the wire format, I
  visually inspected that we don't change anything there. That said, this
  _will_ change the codegen because it will affect the spelling of type
  names.
  
  For example, this renames `AuthMode::ChatGPT` to `AuthMode::Chatgpt` in
  `app-server-protocol`, but the wire format is still `"chatgpt"`.
  
  This PR also updates a number of types in `codex-rs/core/src/auth.rs`.

  Michael Bolin · 2026-01-30 11:18:39 -08:00
  e6d913af2d
• Plan mode: stream proposed plans, emit plan items, and render in TUI (#9786)

  ## Summary
  - Stream proposed plans in Plan Mode using `<proposed_plan>` tags parsed
  in core, emitting plan deltas plus a plan `ThreadItem`, while stripping
  tags from normal assistant output.
  - Persist plan items and rebuild them on resume so proposed plans show
  in thread history.
  - Wire plan items/deltas through app-server protocol v2 and render a
  dedicated proposed-plan view in the TUI, including the “Implement this
  plan?” prompt only when a plan item is present.
  
  ## Changes
  
  ### Core (`codex-rs/core`)
  - Added a generic, line-based tag parser that buffers each line until it
  can disprove a tag prefix; implements auto-close on `finish()` for
  unterminated tags. `codex-rs/core/src/tagged_block_parser.rs`
  - Refactored proposed plan parsing to wrap the generic parser.
  `codex-rs/core/src/proposed_plan_parser.rs`
  - In plan mode, stream assistant deltas as:
    - **Normal text** → `AgentMessageContentDelta`
    - **Plan text** → `PlanDelta` + `TurnItem::Plan` start/completion  
    (`codex-rs/core/src/codex.rs`)
  - Final plan item content is derived from the completed assistant
  message (authoritative), not necessarily the concatenated deltas.
  - Strips `<proposed_plan>` blocks from assistant text in plan mode so
  tags don’t appear in normal messages.
  (`codex-rs/core/src/stream_events_utils.rs`)
  - Persist `ItemCompleted` events only for plan items for rollout replay.
  (`codex-rs/core/src/rollout/policy.rs`)
  - Guard `update_plan` tool in Plan Mode with a clear error message.
  (`codex-rs/core/src/tools/handlers/plan.rs`)
  - Updated Plan Mode prompt to:  
    - keep `<proposed_plan>` out of non-final reasoning/preambles  
    - require exact tag formatting  
    - allow only one `<proposed_plan>` block per turn  
    (`codex-rs/core/templates/collaboration_mode/plan.md`)
  
  ### Protocol / App-server protocol
  - Added `TurnItem::Plan` and `PlanDeltaEvent` to core protocol items.
  (`codex-rs/protocol/src/items.rs`, `codex-rs/protocol/src/protocol.rs`)
  - Added v2 `ThreadItem::Plan` and `PlanDeltaNotification` with
  EXPERIMENTAL markers and note that deltas may not match the final plan
  item. (`codex-rs/app-server-protocol/src/protocol/v2.rs`)
  - Added plan delta route in app-server protocol common mapping.
  (`codex-rs/app-server-protocol/src/protocol/common.rs`)
  - Rebuild plan items from persisted `ItemCompleted` events on resume.
  (`codex-rs/app-server-protocol/src/protocol/thread_history.rs`)
  
  ### App-server
  - Forward plan deltas to v2 clients and map core plan items to v2 plan
  items. (`codex-rs/app-server/src/bespoke_event_handling.rs`,
  `codex-rs/app-server/src/codex_message_processor.rs`)
  - Added v2 plan item tests.
  (`codex-rs/app-server/tests/suite/v2/plan_item.rs`)
  
  ### TUI
  - Added a dedicated proposed plan history cell with special background
  and padding, and moved “• Proposed Plan” outside the highlighted block.
  (`codex-rs/tui/src/history_cell.rs`, `codex-rs/tui/src/style.rs`)
  - Only show “Implement this plan?” when a plan item exists.
  (`codex-rs/tui/src/chatwidget.rs`,
  `codex-rs/tui/src/chatwidget/tests.rs`)
  
  <img width="831" height="847" alt="Screenshot 2026-01-29 at 7 06 24 PM"
  src="https://github.com/user-attachments/assets/69794c8c-f96b-4d36-92ef-c1f5c3a8f286"
  />
  
  ### Docs / Misc
  - Updated protocol docs to mention plan deltas.
  (`codex-rs/docs/protocol_v1.md`)
  - Minor plumbing updates in exec/debug clients to tolerate plan deltas.
  (`codex-rs/debug-client/src/reader.rs`, `codex-rs/exec/...`)
  
  ## Tests
  - Added core integration tests:
    - Plan mode strips plan from agent messages.
    - Missing `</proposed_plan>` closes at end-of-message.  
    (`codex-rs/core/tests/suite/items.rs`)
  - Added unit tests for generic tag parser (prefix buffering, non-tag
  lines, auto-close). (`codex-rs/core/src/tagged_block_parser.rs`)
  - Existing app-server plan item tests in v2.
  (`codex-rs/app-server/tests/suite/v2/plan_item.rs`)
  
  ## Notes / Behavior
  - Plan output no longer appears in standard assistant text in Plan Mode;
  it streams via `PlanDelta` and completes as a `TurnItem::Plan`.
  - The final plan item content is authoritative and may diverge from
  streamed deltas (documented as experimental).
  - Reasoning summaries are not filtered; prompt instructs the model not
  to include `<proposed_plan>` outside the final plan message.
  
  ## Codex Author
  `codex fork 019bec2d-b09d-7450-b292-d7bcdddcdbfb`

  Charley Cunningham · 2026-01-30 18:59:30 +00:00
  ec4a2d07e4
• feat: refactor CodexAuth so invalid state cannot be represented (#10208)

  Previously, `CodexAuth` was defined as follows:
  
  
  https://github.com/openai/codex/blob/d550fbf41afc09d7d7b5ac813aea38de07b2a73f/codex-rs/core/src/auth.rs#L39-L46
  
  But if you looked at its constructors, we had creation for
  `AuthMode::ApiKey` where `storage` was built using a nonsensical path
  (`PathBuf::new()`) and `auth_dot_json` was `None`:
  
  
  https://github.com/openai/codex/blob/d550fbf41afc09d7d7b5ac813aea38de07b2a73f/codex-rs/core/src/auth.rs#L212-L220
  
  By comparison, when `AuthMode::ChatGPT` was used, `api_key` was always
  `None`:
  
  
  https://github.com/openai/codex/blob/d550fbf41afc09d7d7b5ac813aea38de07b2a73f/codex-rs/core/src/auth.rs#L665-L671
  
  https://github.com/openai/codex/pull/10012 took things further because
  it introduced a new `ChatgptAuthTokens` variant to `AuthMode`, which is
  important in when invoking `account/login/start` via the app server, but
  most logic _internal_ to the app server should just reason about two
  `AuthMode` variants: `ApiKey` and `ChatGPT`.
  
  This PR tries to clean things up as follows:
  
  - `LoginAccountParams` and `AuthMode` in `codex-rs/app-server-protocol/`
  both continue to have the `ChatgptAuthTokens` variant, though it is used
  exclusively for the on-the-wire messaging.
  - `codex-rs/core/src/auth.rs` now has its own `AuthMode` enum, which
  only has two variants: `ApiKey` and `ChatGPT`.
  - `CodexAuth` has been changed from a struct to an enum. It is a
  disjoint union where each variant (`ApiKey`, `ChatGpt`, and
  `ChatGptAuthTokens`) have only the associated fields that make sense for
  that variant.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/10208).
  * #10224
  * __->__ #10208

  Michael Bolin · 2026-01-30 09:33:23 -08:00
  377ab0c77c
• Conversation naming (#8991)

  Session renaming:
  - `/rename my_session`
  - `/rename` without arg and passing an argument in `customViewPrompt`
  - AppExitInfo shows resume hint using the session name if set instead of
  uuid, defaults to uuid if not set
  - Names are stored in `CODEX_HOME/sessions.jsonl`
  
  Session resuming:
  - codex resume <name> lookup for `CODEX_HOME/sessions.jsonl` first entry
  matching the name and resumes the session
  
  ---------
  
  Co-authored-by: jif-oai <jif@openai.com>

  pap-openai · 2026-01-30 10:40:09 +00:00
  1ef5455eb6
• chore(app-server): document AuthMode (#10191)

  Explain what this is and what it's used for.

  Owen Lin · 2026-01-29 16:48:15 -08:00
  c6e1288ef1
• feat(app-server): support external auth mode (#10012)

  This enables a new use case where `codex app-server` is embedded into a
  parent application that will directly own the user's ChatGPT auth
  lifecycle, which means it owns the user’s auth tokens and refreshes it
  when necessary. The parent application would just want a way to pass in
  the auth tokens for codex to use directly.
  
  The idea is that we are introducing a new "auth mode" currently only
  exposed via app server: **`chatgptAuthTokens`** which consist of the
  `id_token` (stores account metadata) and `access_token` (the bearer
  token used directly for backend API calls). These auth tokens are only
  stored in-memory. This new mode is in addition to the existing `apiKey`
  and `chatgpt` auth modes.
  
  This PR reuses the shape of our existing app-server account APIs as much
  as possible:
  - Update `account/login/start` with a new `chatgptAuthTokens` variant,
  which will allow the client to pass in the tokens and have codex
  app-server use them directly. Upon success, the server emits
  `account/login/completed` and `account/updated` notifications.
  - A new server->client request called
  `account/chatgptAuthTokens/refresh` which the server can use whenever
  the access token previously passed in has expired and it needs a new one
  from the parent application.
  
  I leveraged the core 401 retry loop which typically triggers auth token
  refreshes automatically, but made it pluggable:
  - **chatgpt** mode refreshes internally, as usual.
  - **chatgptAuthTokens** mode calls the client via
  `account/chatgptAuthTokens/refresh`, the client responds with updated
  tokens, codex updates its in-memory auth, then retries. This RPC has a
  10s timeout and handles JSON-RPC errors from the client.
  
  Also some additional things:
  - chatgpt logins are blocked while external auth is active (have to log
  out first. typically clients will pick one OR the other, not support
  both)
  - `account/logout` clears external auth in memory
  - Ensures that if `forced_chatgpt_workspace_id` is set via the user's
  config, we respect it in both:
  - `account/login/start` with `chatgptAuthTokens` (returns a JSON-RPC
  error back to the client)
  - `account/chatgptAuthTokens/refresh` (fails the turn, and on next
  request app-server will send another `account/chatgptAuthTokens/refresh`
  request to the client).

  Owen Lin · 2026-01-29 23:46:04 +00:00
  81a17bb2c1
• compaction (#10034)

  # External (non-OpenAI) Pull Request Requirements
  
  Before opening this Pull Request, please read the dedicated
  "Contributing" markdown file or your PR may be closed:
  https://github.com/openai/codex/blob/main/docs/contributing.md
  
  If your PR conforms to our contribution guidelines, replace this text
  with a detailed and high quality description of your changes.
  
  Include a link to a bug report or enhancement request.

  Ahmed Ibrahim · 2026-01-28 11:36:11 -08:00
  b7edeee8ca
• Add thread/unarchive to restore archived rollouts (#9843)

  ## Summary
  - Adds a new `thread/unarchive` RPC to move archived thread rollouts
  back into the active `sessions/` tree.
  
  ## What changed
  - **Protocol**
    - Adds `thread/unarchive` request/response types and wiring.
  - **Server**
    - Implements `thread_unarchive` in the app server.
    - Validates the archived rollout path and thread ID.
  - Restores the rollout to `sessions/YYYY/MM/DD/...` based on the rollout
  filename timestamp.
  - **Core**
  - Adds `find_archived_thread_path_by_id_str` helper for archived
  rollouts.
  - **Docs**
    - Documents the new RPC and usage example.
  - **Tests**
    - Adds an end-to-end server test that:
      1) starts a thread,
      2) archives it,
      3) unarchives it,
      4) asserts the file is restored to `sessions/`.
  
  ## How to use
  ```json
  { "method": "thread/unarchive", "id": 24, "params": { "threadId": "<thread-id>" } }
  ```
  
  ## Author Codex Session
  
  `codex resume 019bf158-54b6-7960-a696-9d85df7e1bc1` (soon I'll make this
  kind of session UUID forkable by anyone with the right
  `session_object_storage_url` line in their config, but for now just
  pasting it here for my reference)

  Charley Cunningham · 2026-01-26 11:24:36 -08:00
  62266b13f8
• feat: dynamic tools injection (#9539)

  ## Summary
  Add dynamic tool injection to thread startup in API v2, wire dynamic
  tool calls through the app server to clients, and plumb responses back
  into the model tool pipeline.
  
  ### Flow (high level)
  - Thread start injects `dynamic_tools` into the model tool list for that
  thread (validation is done here).
  - When the model emits a tool call for one of those names, core raises a
  `DynamicToolCallRequest` event.
  - The app server forwards it to the client as `item/tool/call`, waits
  for the client’s response, then submits a `DynamicToolResponse` back to
  core.
  - Core turns that into a `function_call_output` in the next model
  request so the model can continue.
  
  ### What changed
  - Added dynamic tool specs to v2 thread start params and protocol types;
  introduced `item/tool/call` (request/response) for dynamic tool
  execution.
  - Core now registers dynamic tool specs at request time and routes those
  calls via a new dynamic tool handler.
  - App server validates tool names/schemas, forwards dynamic tool call
  requests to clients, and publishes tool outputs back into the session.
  - Integration tests

  jif-oai · 2026-01-26 10:06:44 +00:00
  d594693d1a
• [connectors] Support connectors part 1 - App server & MCP (#9667)

  In order to make Codex work with connectors, we add a built-in gateway
  MCP that acts as a transparent proxy between the client and the
  connectors. The gateway MCP collects actions that are accessible to the
  user and sends them down to the user, when a connector action is chosen
  to be called, the client invokes the action through the gateway MCP as
  well.
  
   - [x] Add the system built-in gateway MCP to list and run connectors.
   - [x] Add the app server methods and protocol

  Matthew Zeng · 2026-01-22 16:48:43 -08:00
  a2c829a808
• feat(app-server): thread/read API (#9569)
  Owen Lin · 2026-01-22 12:22:01 -08:00
  80240b3b67
• Feat: request user input tool (#9472)

  ### Summary
  * Add `requestUserInput` tool that the model can use for gather
  feedback/asking question mid turn.
  
  
  ### Tool input schema
  ```
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "requestUserInput input",
    "type": "object",
    "additionalProperties": false,
    "required": ["questions"],
    "properties": {
      "questions": {
        "type": "array",
        "description": "Questions to show the user (1-3). Prefer 1 unless multiple independent decisions block progress.",
        "minItems": 1,
        "maxItems": 3,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": ["id", "header", "question"],
          "properties": {
            "id": {
              "type": "string",
              "description": "Stable identifier for mapping answers (snake_case)."
            },
            "header": {
              "type": "string",
              "description": "Short header label shown in the UI (12 or fewer chars)."
            },
            "question": {
              "type": "string",
              "description": "Single-sentence prompt shown to the user."
            },
            "options": {
              "type": "array",
              "description": "Optional 2-3 mutually exclusive choices. Put the recommended option first and suffix its label with \"(Recommended)\". Only include \"Other\" option if we want to include a free form option. If the question is free form in nature, do not include any option.",
              "minItems": 2,
              "maxItems": 3,
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["value", "label", "description"],
                "properties": {
                  "value": {
                    "type": "string",
                    "description": "Machine-readable value (snake_case)."
                  },
                  "label": {
                    "type": "string",
                    "description": "User-facing label (1-5 words)."
                  },
                  "description": {
                    "type": "string",
                    "description": "One short sentence explaining impact/tradeoff if selected."
                  }
                }
              }
            }
          }
        }
      }
    }
  }
  ```
  
  ### Tool output schema
  ```
  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "requestUserInput output",
    "type": "object",
    "additionalProperties": false,
    "required": ["answers"],
    "properties": {
      "answers": {
        "type": "object",
        "description": "Map of question id to user answer.",
        "additionalProperties": {
          "type": "object",
          "additionalProperties": false,
          "required": ["selected"],
          "properties": {
            "selected": {
              "type": "array",
              "items": { "type": "string" }
            },
            "other": {
              "type": ["string", "null"]
            }
          }
        }
      }
    }
  }
  ```

  Shijie Rao · 2026-01-19 10:17:30 -08:00
  57ec3a8277
• Expose collaboration presets (#9421)

  Expose collaboration presets for clients
  
  ---------
  
  Co-authored-by: Josh McKinney <joshka@openai.com>

  Ahmed Ibrahim · 2026-01-17 12:32:50 -08:00
  8f0e0300d2
• Support enable/disable skill via config/api. (#9328)

  In config.toml:
  ```
  [[skills.config]]
  path = "/Users/xl/.codex/skills/my_skill/SKILL.md"
  enabled = false
  ```
  
  API:
  skills/list, skills/config/write

  xl-openai · 2026-01-16 20:22:05 -08:00
  ad8bf59cbf
• Improve handling of config and rules errors for app server clients (#9182)

  When an invalid config.toml key or value is detected, the CLI currently
  just quits. This leaves the VSCE in a dead state.
  
  This PR changes the behavior to not quit and bubble up the config error
  to users to make it actionable. It also surfaces errors related to
  "rules" parsing.
  
  This allows us to surface these errors to users in the VSCE, like this:
  
  <img width="342" height="129" alt="Screenshot 2026-01-13 at 4 29 22 PM"
  src="https://github.com/user-attachments/assets/a79ffbe7-7604-400c-a304-c5165b6eebc4"
  />
  
  <img width="346" height="244" alt="Screenshot 2026-01-13 at 4 45 06 PM"
  src="https://github.com/user-attachments/assets/de874f7c-16a2-4a95-8c6d-15f10482e67b"
  />

  Eric Traut · 2026-01-13 17:57:09 -08:00
  31d9b6f4d2
• feat: hot reload mcp servers (#8957)

  ### Summary
  * Added `mcpServer/refresh` command to inform app servers and active
  threads to refresh mcpServer on next turn event.
  * Added `pending_mcp_server_refresh_config` to codex core so that if the
  value is populated, we reinitialize the mcp server manager on the thread
  level.
  * The config is updated on `mcpServer/refresh` command which we iterate
  through threads and provide with the latest config value after last
  write.

  Shijie Rao · 2026-01-12 11:17:50 -08:00
  3e91a95ce1
• feat: fork conversation/thread (#8866)

  ## Summary
  - add thread/conversation fork endpoints to the protocol (v1 + v2)
  - implement fork handling in app-server using thread manager and config
  overrides
  - add fork coverage in app-server tests and document `thread/fork` usage

  Anton Panasenko · 2026-01-08 12:54:20 -08:00
  41a317321d
• feat: add list loaded threads to app server (#8902)
  jif-oai · 2026-01-08 17:48:20 +00:00
  5b7707dfb1
• Feat: appServer.requirementList for requirement.toml (#8800)

  ### Summary
  We are exposing requirements via `requirement/list` method from
  app-server so that we can conditionally disable the agent mode dropdown
  selection in VSCE and correctly setting the default value.
  
  ### Sample output
  #### `etc/codex/requirements.toml`
  <img width="497" height="49" alt="Screenshot 2026-01-06 at 11 32 06 PM"
  src="https://github.com/user-attachments/assets/fbd9402e-515f-4b9e-a158-2abb23e866a0"
  />
  
  #### App server response
  <img width="1107" height="79" alt="Screenshot 2026-01-06 at 11 30 18 PM"
  src="https://github.com/user-attachments/assets/c0d669cd-54ef-4789-a26c-adb2c41950af"
  />

  Shijie Rao · 2026-01-07 13:57:44 -08:00
  efd0c21b9b