372 Commits

• Add multi-agent runtime metadata types (#25720)

  Stack split from #25708. Original PR intentionally left open. This first
  PR adds the multi-agent runtime metadata types and catalog plumbing used
  by the rest of the stack.

  jif-oai · 2026-06-02 12:10:14 +02:00
  3f1fb7ed8b
• feat: show enterprise monthly credit limits in status (#24812)

  ## Summary
  
  Enterprise users can have an effective monthly credit limit, but Codex
  `/status` currently drops that metadata from the account-usage response.
  
  This change adds the optional `spend_control.individual_limit`
  projection to the existing rate-limit snapshot flow. The backend client
  reads the monthly limit, app-server exposes it as `individualLimit`, and
  the TUI renders a `Monthly credit limit` row through the existing
  progress-bar renderer.
  
  When the backend does not return an effective monthly limit, existing
  rate-limit behavior is unchanged.
  
  ## Existing backend state
  
  The account-usage backend already returns the effective monthly limit
  and current usage together:
  
  ```json
  {
    "spend_control": {
      "reached": false,
      "individual_limit": {
        "limit": "25000",
        "used": "8000",
        "remaining": "17000",
        "used_percent": 32,
        "remaining_percent": 68,
        "reset_after_seconds": 86400,
        "reset_at": 1778137680
      }
    }
  }
  ```
  
  Before this change, Codex projected rolling `primary` and `secondary`
  windows plus `credits`. It ignored `spend_control.individual_limit`, so
  app-server clients and `/status` could not render the monthly cap.
  
  The updated flow is:
  
  ```text
  account usage backend
    -> backend-client reads spend_control.individual_limit
    -> existing rate-limit snapshot carries optional individual_limit
    -> app-server exposes optional individualLimit
    -> TUI renders Monthly credit limit
  ```
  
  ## App-server contract
  
  `account/rateLimits/read` and sparse `account/rateLimits/updated`
  notifications now include an additive nullable
  `rateLimits.individualLimit` field:
  
  ```json
  {
    "individualLimit": {
      "limit": "25000",
      "used": "8000",
      "remainingPercent": 68,
      "resetsAt": 1778137680
    }
  }
  ```
  
  In an `account/rateLimits/read` response, `null` means no monthly limit
  is available. `account/rateLimits/updated` remains a sparse rolling
  notification: clients merge available values into their most recent
  `account/rateLimits/read` snapshot or refetch. Nullable account metadata
  in a rolling notification does not clear a previously observed value.
  
  ## Design decisions
  
  - Extend the existing rate-limit snapshot instead of introducing a
  separate request or wire-level update protocol.
  - Keep the Codex projection narrow: `/status` needs the effective limit,
  current usage, remaining percentage, and reset timestamp.
  - Render the monthly row through the existing progress-bar renderer,
  with one optional detail line for `8,000 of 25,000 credits used`.
  - Keep the backend response optional so existing accounts and older
  usage states preserve their current behavior.
  - Preserve cached monthly metadata when sparse rolling notifications
  omit it. Live account-usage reads remain authoritative and can clear a
  removed limit.
  
  ## Visual evidence
  
  ```text
   Monthly credit limit:   [██████████████░░░░░░] 68% left (resets 07:08 on 7 May)
                           8,000 of 25,000 credits used
  ```
  
  Snapshot:
  `codex-rs/tui/src/status/snapshots/codex_tui__status__tests__status_snapshot_includes_enterprise_monthly_credit_limit.snap`
  
  ## Testing
  
  Tests: generated app-server schema verification, protocol tests,
  backend-client tests, app-server integration coverage, TUI snapshot
  coverage, formatting, and workspace lint cleanup.

  efrazer-oai · 2026-06-01 21:25:42 -07:00
  c8e5db16c9
• store and expose parent_thread_id on Threads (#25113)

  ## Why
  
  This PR
  https://github.com/openai/codex/pull/24161#discussion_r3325692763
  revealed a subagent data modeling issue, where we overloaded
  `forked_from_id` to also mean `parent_thread_id`. That's incorrect since
  guardian and review subagents can be a subagent and NOT fork the main
  thread's history.
  
  The solution here is to explicitly store a new `parent_thread_id` on
  `SessionMeta`, alongside `forked_from_id` which already exists. While
  we're at it, also expose it in the app-server protocol on the `Thread`
  object.
  
  A thread->subagent relationship and a fork of thread history are
  orthogonal concepts.
  
  ## What Changed
  
  - Added top-level `parent_thread_id` persistence on `SessionMeta` and
  runtime/session plumbing through `SessionConfiguredEvent`,
  `CodexSpawnArgs`, `SessionConfiguration`, `ThreadConfigSnapshot`,
  `TurnContext`, and `ModelClient`.
  - Made turn metadata, request headers, analytics, and subagent-start
  events read the separate runtime/top-level parent field instead of
  deriving general parent lineage from `SessionSource` or
  `forked_from_thread_id`.
  - Passed parent lineage separately at delegated subagent, review,
  guardian, agent-job, and multi-agent spawn construction sites;
  copied-history fork lineage remains derived only from `InitialHistory`.
  - Persisted and exposed parent lineage through rollout/thread-store
  projections and app-server v2 `Thread.parentThreadId`.
  - Updated app-server README text and regenerated app-server schema
  fixtures for the additive `parentThreadId` response field.

  Owen Lin · 2026-06-01 04:33:20 +00:00
  cf0911076f
• Add cloud-managed config layer support (#24620)

  ## Summary
  
  PR 3 of 5 in the cloud-managed config client stack.
  
  Adds enterprise-managed cloud config as a first-class config layer
  source. The layer metadata is preserved through config loading,
  diagnostics, debug output, hook attribution, and app-server protocol
  surfaces.
  
  ## Details
  
  - Enterprise-managed config becomes a normal config layer source with
  backend-supplied `id` and display `name` attached for provenance.
  - These layers are designed to behave like non-file managed config: they
  can surface syntax/type diagnostics by layer name even though there is
  no physical config file.
  - Relative path settings are resolved from a stored config base so
  cloud-delivered config remains consistent with existing MDM-delivered
  config semantics.
  - Hook attribution distinguishes config-delivered hooks from
  requirements-delivered hooks via `HookSource::CloudManagedConfig`.
  - This remains pull-based and snapshot-oriented; the PR adds layer
  identity/diagnostics, not dynamic reload behavior.
  
  ## Validation
  
  Validated through the targeted stack checks after rebasing onto current
  `main`:
  
  - Rust crate tests for
  config/hooks/cloud-config/backend-client/app-server-protocol
  - Filtered `codex-core` and `codex-app-server` `cloud_config_bundle`
  tests
  - Python generated-file contract test
  - `cargo shear --deny-warnings`
  - Targeted `argument-comment-lint` for config/hooks

  joeflorencio-openai · 2026-05-31 15:54:31 -07:00
  8a556296f0
• Add subagent lineage metadata for responsesapi (#24161)

  ## Why
  
  We recently added `forked_from_thread_id` which lets us trace where a
  thread's _context_ comes from, but we also want to understand subagent
  lineage (e.g. which parent thread spawned this subagent? what kind of
  subagent is it?) which is orthogonal.
  
  This PR adds `parent_thread_id` and `subagent_kind` to the
  `x-codex-turn-metadata` header sent to ResponsesAPI.
  
  ## What changed
  
  - Adds `parent_thread_id` and `subagent_kind` to core-owned
  `x-codex-turn-metadata`.
  - Restores persisted `SessionSource` and `ThreadSource` from resumed
  session metadata so cold-resumed subagent threads keep their lineage on
  later Responses API requests.
  - Centralizes parent-thread extraction on `SessionSource` /
  `SubAgentSource` and reuses it in the Responses client, analytics, agent
  control, and state parsing paths.
  - Extends reserved-key, git-enrichment, thread-spawn, and app-server v2
  metadata coverage for the new lineage fields.
  
  ## Verification
  
  - Not run locally per request.
  - Added focused coverage in `core/src/turn_metadata_tests.rs` and
  `app-server/tests/suite/v2/client_metadata.rs`.

  Owen Lin · 2026-05-29 11:28:12 -07:00
  fc9cf62efb
• Surface filesystem permission profiles in prompt context (#23924)

  ## Summary
  Some permission profiles can encode filesystem reads that should remain
  unavailable to the agent. Before this change, the model-visible context
  and automatic approval review prompt summarized the effective
  permissions as a legacy sandbox mode, which can omit permission-profile
  filesystem entries from escalation decisions.
  
  For example, a profile can grant workspace access while denying a
  private subtree across every workspace root:
  
  ```toml
  default_permissions = "restricted-workspace"
  
  [permissions.restricted-workspace.workspace_roots]
  "/Users/alice/project" = true
  "/Users/alice/other-project" = true
  
  [permissions.restricted-workspace.filesystem]
  ":minimal" = "read"
  
  [permissions.restricted-workspace.filesystem.":workspace_roots"]
  "." = "write"
  "private" = "deny"
  "private/**" = "deny"
  ```
  
  The context window now describes the workspace roots and effective
  filesystem side of the `PermissionProfile` directly, with deny entries
  marked as non-escalatable:
  
  ```xml
  <environment_context>
    <cwd>/Users/alice/project</cwd>
    <shell>zsh</shell>
    <filesystem><workspace_roots><root>/Users/alice/project</root><root>/Users/alice/other-project</root></workspace_roots><permission_profile type="managed"><file_system type="restricted"><entry access="read"><special>:minimal</special></entry><entry access="write"><path>/Users/alice/project</path></entry><entry access="write"><path>/Users/alice/other-project</path></entry><entry access="deny" escalatable="false"><path>/Users/alice/project/private</path></entry><entry access="deny" escalatable="false"><path>/Users/alice/other-project/private</path></entry><entry access="deny" escalatable="false"><glob>/Users/alice/project/private/**</glob></entry><entry access="deny" escalatable="false"><glob>/Users/alice/other-project/private/**</glob></entry></file_system></permission_profile></filesystem>
  </environment_context>
  ```
  
  Managed requirements can impose the same kind of deny-read restriction:
  
  ```toml
  [permissions.filesystem]
  deny_read = [
    "/Users/alice/project/private",
    "/Users/alice/project/private/**",
  ]
  ```
  
  The automatic approval review prompt also receives the parent turn's
  denied-read context, so review decisions can account for the active
  permission profile.
  
  ## What Changed
  - Render the effective filesystem profile in `<environment_context>`,
  including profile type, filesystem entries, workspace roots, and
  non-escalatable deny entries.
  - Persist effective `workspace_roots` in `TurnContextItem` so
  resumed/replayed context does not have to bind `:workspace_roots`
  through legacy `cwd` fallback.
  - Add explicit permission instructions that denied reads are policy
  restrictions, not escalation targets.
  - Pass the parent turn's denied-read context into automatic approval
  reviews.
  - Add targeted coverage for prompt rendering, workspace-root
  materialization, replay context, and review prompt context.
  - Keep the prompt-context test expectations platform-aware so the same
  filesystem rendering assertions pass on Unix and Windows paths.
  
  ## Testing
  - `just test -p codex-core
  context::environment_context::tests::serialize_environment_context_with_full_filesystem_profile`
  - `just test -p codex-core
  context::environment_context::tests::turn_context_item_filesystem_uses_workspace_roots_instead_of_cwd`
  - `just test -p codex-core
  context::permissions_instructions::permissions_instructions_tests::builds_permissions_from_profile_with_denied_reads`
  - `just fix -p codex-core`
  
  I also attempted `just test -p codex-core`; the changed prompt-context
  tests passed, but the full local run did not complete cleanly in this
  sandboxed macOS environment due unrelated user-shell `CODEX_SANDBOX*`
  expectations and integration-test timeouts.

  Michael Bolin · 2026-05-28 14:56:53 -07:00
  e7dda8070e
• [codex] Add user input client ids (#24653)

  ## Summary
  
  Adds an optional `clientId` field to app-server v2 `UserInput` and
  carries it through the core `UserInput` model so clients can correlate
  echoed user input items without relying on payload equality.
  
  ## Details
  
  - Adds `client_id: Option<String>` to core `UserInput` variants.
  - Exposes the v2 app-server field as `clientId` on the wire and in
  generated TypeScript.
  - Preserves the id when converting between app-server v2 and core
  protocol types.
  - Regenerates app-server schema fixtures.
  
  ## Validation
  
  - `just fmt`
  - `just write-app-server-schema`
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-protocol`
  - `just fix -p codex-app-server-protocol`
  - `just fix -p codex-protocol`
  - `git diff --check`

  Alexi Christakis · 2026-05-28 14:54:39 -07:00
  e92c952b2e
• Add experimental turn additional context (#24154)

  ## Summary
  
  Adds experimental `additionalContext` support to `turn/start` and
  `turn/steer` so clients can provide ephemeral external context, such as
  browser or automation state, without turning that plumbing into a
  visible user prompt or triggering user-prompt lifecycle behavior.
  
  ## API Shape
  
  The parameter shape is:
  
  ```ts
  additionalContext?: Record<string, {
    value: string
    kind: "untrusted" | "application"
  }> | null
  ```
  
  Example:
  
  ```json
  {
    "additionalContext": {
      "browser_info": {
        "value": "Active tab is CI failures.",
        "kind": "untrusted"
      },
      "automation_info": {
        "value": "CI rerun is in progress.",
        "kind": "application"
      }
    }
  }
  ```
  
  The keys are opaque and caller-defined.
  
  ## Context Injection
  
  When provided, accepted entries are inserted into model context as
  hidden contextual message items, not as visible thread user-message
  items.
  
  `kind: "untrusted"` entries are inserted with role `user`:
  
  ```text
  <external_${key}>${value}</external_${key}>
  ```
  
  `kind: "application"` entries are inserted with role `developer`:
  
  ```text
  <${key}>${value}</${key}>
  ```
  
  Values are not escaped. Each value is truncated to 1k approximate tokens
  before wrapping.
  
  For `turn/start`, accepted additional context is inserted before normal
  user input. For `turn/steer`, additional context is merged only when the
  steer includes non-empty user input; context-only steers still reject as
  empty input.
  
  ## Dedupe Strategy
  
  `AdditionalContextStore` lives on session state and stores the latest
  complete additional-context map.
  
  Each `turn/start` or non-empty `turn/steer` treats its
  `additionalContext` as the current complete set of values. Entries are
  injected only when the key is new or the exact entry for that key
  changed, including `value` or `kind`. After merging, the store is
  replaced with the provided map, so omitted keys are removed from the
  retained set and can be injected again later if reintroduced.
  
  Omitting `additionalContext`, passing `null`, or passing an empty object
  resets the store to empty and injects nothing.
  
  ## What Changed
  
  - Threads experimental v2 `additionalContext` through app-server into
  core turn start and steer handling.
  - Adds separate contextual fragment types for untrusted user-role
  context and application developer-role context.
  - Uses pending response input items so additional context can be
  combined with normal user input without treating it as prompt text.
  - Adds integration coverage for start/steer flow, role routing,
  dedupe/reset behavior, deletion/re-add behavior, hook-blocked input
  behavior, empty context-only steer rejection, external-fragment marker
  matching, and truncation.

  pakrym-oai · 2026-05-26 13:02:34 -07:00
  768848ab6f
• Display workspace usage limit error copy from response header (#24114)

  ## Why
  
  `openai/openai#947613` adds `X-Codex-Rate-Limit-Reached-Type` for Codex
  workspace credit-depletion and spend-cap responses. The CLI currently
  reads the adjacent promo header but otherwise renders generic
  usage-limit copy, so those responses do not explain the
  workspace-specific action the user needs to take.
  
  Backend dependency: https://github.com/openai/openai/pull/947613
  
  ## What Changed
  
  - Parse `X-Codex-Rate-Limit-Reached-Type` in the usage-limit error
  handling path alongside `x-codex-promo-message`.
  - Keep the header value parsing with the shared `RateLimitReachedType`
  enum.
  - Carry the parsed type on `UsageLimitReachedError` and render
  client-owned copy for the four workspace owner/member credit and
  spend-cap values.
  - Preserve existing promo and plan-based text for absent, generic, or
  unknown header values.
  - Keep the existing TUI workspace-owner nudge state path unchanged; the
  response header only selects the displayed error string.
  - Add focused display coverage for all specific type values and the
  generic fallback case.
  
  ## Test Plan
  
  - Added `usage_limit_reached_error_formats_rate_limit_reached_types`
  coverage.
  - Not run manually, per request; CI runs validation on the pushed
  commit.

  dhruvgupta-oai · 2026-05-22 23:58:49 +00:00
  4bcabbfbec
• Add trace_id to TurnStartedEvent (#23980)

  ## Why
  [Recent PR](https://github.com/openai/codex/pull/22709) removed
  `trace_id` from `TurnContextItem`.
  
  ## What changed
  - Add to `TurnStartedEvent` so rollout consumers can correlate turns
  with telemetry traces.
  - Note that the branch name is out of date because I originally re-added
  to `TurnContextItem`, but we decided to move it to `TurnStartedEvent`.
  
  ## Verification
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-core --lib
  regular_turn_emits_turn_started_without_waiting_for_startup_prewarm`
  - `cargo test -p codex-core --test all
  emits_warning_when_resumed_model_differs`
  - `cargo test -p codex-rollout`
  - `cargo test -p codex-state`

  mchen-oai · 2026-05-22 13:10:56 -07:00
  3c83e57bfa
• [codex] Add plugin id to MCP tool call items (#23737)

  Add owning plugin id to MCP tool call items so we can better filter them
  at plugin level.
  
  ## Summary
  - add optional `plugin_id` to MCP tool-call items and legacy begin/end
  events
  - propagate plugin metadata into emitted core items and app-server v2
  `ThreadItem::McpToolCall`
  - preserve plugin ids through app-server replay/redaction paths and
  regenerate v2 schema fixtures
  
  ## Testing
  - `just write-app-server-schema`
  - `just fmt`
  - `just fix -p codex-core`
  - `cargo test -p codex-protocol -p codex-app-server-protocol`
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-core mcp_tool_call_item_includes_plugin_id --lib`
  - `cargo check -p codex-tui --tests`
  - `cargo check -p codex-app-server --tests`
  - `git diff --check`
  
  ## Notes
  - `just fix -p codex-core` completed with two non-fatal
  `too_many_arguments` warnings on the touched MCP notification helpers.
  - A broader `cargo test -p codex-core` run passed core unit tests, then
  hit shell/sandbox/snapshot failures in the integration target.
  - A broader app-server downstream run hit the existing
  `in_process::tests::in_process_start_clamps_zero_channel_capacity` stack
  overflow; `cargo test -p codex-exec` also hit the existing sandbox
  expectation mismatch in
  `thread_lifecycle_params_include_legacy_sandbox_when_no_active_profile`.

  Matthew Zeng · 2026-05-20 17:02:10 -07:00
  0a4179bb19
• Add SubagentStop hook (#22873)

  # What
  
  <img width="1792" height="1024" alt="image"
  src="https://github.com/user-attachments/assets/8f81d232-5813-4994-a61d-e42a05a93a3e"
  />
  
  `SubagentStop` runs when a thread-spawned subagent turn is about to
  finish. Thread-spawned subagents use `SubagentStop` instead of the
  normal root-agent `Stop` hook.
  
  Configured handlers match on `agent_type`. Hook input includes the
  normal stop fields plus:
  
  - `agent_id`: the child thread id.
  - `agent_type`: the resolved subagent type.
  - `agent_transcript_path`: the child subagent transcript path.
  - `transcript_path`: the parent thread transcript path.
  - `last_assistant_message`: the final assistant message from the child
  turn, when available.
  - `stop_hook_active`: `true` when the child is already continuing
  because an earlier stop-like hook blocked completion.
  
  `SubagentStop` shares the same completion-control semantics as `Stop`,
  scoped to the child turn:
  
  - No decision allows the child turn to finish.
  - `decision: "block"` with a non-empty `reason` records that reason as
  hook feedback and continues the child with that prompt.
  - `continue: false` stops the child turn. If `stopReason` is present,
  Codex surfaces it as the stop reason.
  
  # Lifecycle Scope
  
  Only thread-spawned subagents run `SubagentStop`.
  
  Internal/system subagents such as Review, Compact, MemoryConsolidation,
  and Other do not run normal `Stop` hooks and do not run `SubagentStop`.
  This avoids exposing synthetic matcher labels for internal
  implementation paths.
  
  # Stack
  
  1. #22782: add `SubagentStart`.
  2. This PR: add `SubagentStop`.
  3. #22882: add subagent identity to normal hook inputs.

  Abhinav · 2026-05-20 14:59:41 -07:00
  eee3e60db3
• Add SubagentStart hook (#22782)

  # What
  
  `SubagentStart` runs once when Codex creates a thread-spawned subagent,
  before that child sends its first model request. Thread-spawned
  subagents use `SubagentStart` instead of the normal root-agent
  `SessionStart` hook.
  
  Configured handlers match on the subagent `agent_type`, using the same
  value passed to `spawn_agent`. When no agent type is specified, Codex
  uses the default agent type.
  
  Hook input includes the normal session-start fields plus:
  
  - `agent_id`: the child thread id.
  - `agent_type`: the resolved subagent type.
  
  `SubagentStart` may return `hookSpecificOutput.additionalContext`. That
  context is added to the child conversation before the first model
  request.
  
  # Lifecycle Scope
  
  Only thread-spawned subagents run `SubagentStart`.
  
  Internal/system subagents such as Review, Compact, MemoryConsolidation,
  and Other do not run normal `SessionStart` hooks and do not run
  `SubagentStart`. This avoids exposing synthetic matcher labels for
  internal implementation paths.
  
  Also the `SessionStart` hook no longer fires for subagents, this matches
  behavior with other coding agents' implementation
  
  # Stack
  
  1. This PR: add `SubagentStart`.
  2. #22873: add `SubagentStop`.
  3. #22882: add subagent identity to normal hook inputs.

  Abhinav · 2026-05-19 12:45:08 -07:00
  d661ab70ed
• Make deny canonical for filesystem permission entries (#23493)

  ## Why
  Filesystem permission profiles used `none` for deny-read entries, which
  is less direct than the action the entry actually represents. This
  change makes `deny` the canonical filesystem permission spelling while
  preserving compatibility for older configs that still send `none`.
  
  ## What changed
  - rename `FileSystemAccessMode::None` to `Deny`
  - serialize and generate schemas with `deny` as the canonical value
  - retain `none` only as a legacy input alias for temporary config
  compatibility
  - update filesystem glob diagnostics and regression coverage to use the
  canonical spelling
  - refresh config and app-server schema fixtures to match the new wire
  shape
  
  ## Validation
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-core config_toml_deserializes_permission_profiles
  --lib`
  - `cargo test -p codex-core
  read_write_glob_patterns_still_reject_non_subpath_globs --lib`
  
  Earlier in the session, a broad `cargo test -p codex-core` run reached
  unrelated pre-existing failures in timing/snapshot/git-info tests under
  this environment; the targeted surfaces touched by this PR passed
  cleanly.

  viyatb-oai · 2026-05-19 11:03:47 -07:00
  3c76081876
• [5 of 7] Replace OverrideTurnContext with ThreadSettings (#22508)

  **Stack position:** [5 of 7]
  
  ## Summary
  
  This PR adds `Op::ThreadSettings`, a queued settings-only update
  mechanism for changing stored thread settings without starting a new
  turn. It also removes the legacy `Op::OverrideTurnContext` in the same
  layer, so reviewers can see the replacement and deletion together.
  
  ## Changes
  
  - Add `Op::ThreadSettings` for settings-only queued updates.
  - Emit `ThreadSettingsApplied` with the effective thread settings
  snapshot after core applies an update.
  - Route settings-only updates through the same submission queue as user
  input.
  - Migrate remaining `OverrideTurnContext` tests and callers to the
  queued `Op::ThreadSettings` path.
  - Delete `Op::OverrideTurnContext` from the core protocol and submission
  loop.
  
  This stack addresses #20656 and #22090.
  
  ## Stack
  
  1. [1 of 7] [Add thread settings to
  UserInput](https://github.com/openai/codex/pull/23080)
  2. [2 of 7] [Remove
  UserInputWithTurnContext](https://github.com/openai/codex/pull/23081)
  3. [3 of 7] [Remove
  UserTurn](https://github.com/openai/codex/pull/23075)
  4. [4 of 7] [Placeholder for OverrideTurnContext
  cleanup](https://github.com/openai/codex/pull/23087)
  5. [5 of 7] [Replace OverrideTurnContext with
  ThreadSettings](https://github.com/openai/codex/pull/22508) (this PR)
  6. [6 of 7] [Add app-server thread settings
  API](https://github.com/openai/codex/pull/22509)
  7. [7 of 7] [Sync TUI thread
  settings](https://github.com/openai/codex/pull/22510)

  Eric Traut · 2026-05-18 21:03:51 -07:00
  a668379abf
• [3 of 7] Remove UserTurn (#23075)

  **Stack position:** [3 of 7]
  
  ## Summary
  
  This PR finishes the input-op consolidation by moving the remaining
  `Op::UserTurn` callers onto `Op::UserInput` and deleting `Op::UserTurn`.
  This touches a lot of files, but it is a low-risk mechanical migration.
  
  ## Stack
  
  1. [1 of 7] [Add thread settings to
  UserInput](https://github.com/openai/codex/pull/23080)
  2. [2 of 7] [Remove
  UserInputWithTurnContext](https://github.com/openai/codex/pull/23081)
  3. [3 of 7] [Remove
  UserTurn](https://github.com/openai/codex/pull/23075) (this PR)
  4. [4 of 7] [Placeholder for OverrideTurnContext
  cleanup](https://github.com/openai/codex/pull/23087)
  5. [5 of 7] [Replace OverrideTurnContext with
  ThreadSettings](https://github.com/openai/codex/pull/22508)
  6. [6 of 7] [Add app-server thread settings
  API](https://github.com/openai/codex/pull/22509)
  7. [7 of 7] [Sync TUI thread
  settings](https://github.com/openai/codex/pull/22510)

  Eric Traut · 2026-05-18 19:56:00 -07:00
  1a25d8b6e5
• [2 of 7] Remove UserInputWithTurnContext (#23081)

  **Stack position:** [2 of 7]
  
  ## Summary
  
  This PR removes the overlapping `Op::UserInputWithTurnContext` variant
  now that `Op::UserInput` can carry thread settings overrides directly.
  
  ## Stack
  
  1. [1 of 7] [Add thread settings to
  UserInput](https://github.com/openai/codex/pull/23080)
  2. [2 of 7] [Remove
  UserInputWithTurnContext](https://github.com/openai/codex/pull/23081)
  (this PR)
  3. [3 of 7] [Remove
  UserTurn](https://github.com/openai/codex/pull/23075)
  4. [4 of 7] [Placeholder for OverrideTurnContext
  cleanup](https://github.com/openai/codex/pull/23087)
  5. [5 of 7] [Replace OverrideTurnContext with
  ThreadSettings](https://github.com/openai/codex/pull/22508)
  6. [6 of 7] [Add app-server thread settings
  API](https://github.com/openai/codex/pull/22509)
  7. [7 of 7] [Sync TUI thread
  settings](https://github.com/openai/codex/pull/22510)

  Eric Traut · 2026-05-18 19:41:33 -07:00
  e811234484
• [1 of 7] Add thread settings to UserInput (#23080)

  **Stack position:** [1 of 7]
  
  ## Summary
  
  The first three PRs in this stack are a cleanup pass before the actual
  thread settings API work.
  
  Today, core has several overlapping "user input" ops: `UserInput`,
  `UserInputWithTurnContext`, and `UserTurn`. They differ mostly in how
  much next-turn state they carry, which makes the later queued thread
  settings update harder to reason about and review.
  
  This PR starts that cleanup by adding the shared
  `ThreadSettingsOverrides` payload and allowing `Op::UserInput` to carry
  it. Existing variants remain in place here, so this layer is mostly a
  behavior-preserving API shape change plus mechanical constructor
  updates.
  
  ## End State After PR3
  
  By the end of PR3, `Op::UserInput` is the only "user input" core op. It
  can carry optional thread settings overrides for callers that need to
  update stored defaults with a turn, while callers without updates use
  empty settings. `Op::UserInputWithTurnContext` and `Op::UserTurn` are
  deleted.
  
  ## End State After PR5
  
  By the end of PR5, core will have only two ops for this area:
  
  - `Op::UserInput` for user-input-bearing submissions.
  - `Op::ThreadSettings` for settings-only updates.
  
  ## Stack
  
  1. [1 of 7] [Add thread settings to
  UserInput](https://github.com/openai/codex/pull/23080) (this PR)
  2. [2 of 7] [Remove
  UserInputWithTurnContext](https://github.com/openai/codex/pull/23081)
  3. [3 of 7] [Remove
  UserTurn](https://github.com/openai/codex/pull/23075)
  4. [4 of 7] [Placeholder for OverrideTurnContext
  cleanup](https://github.com/openai/codex/pull/23087)
  5. [5 of 7] [Replace OverrideTurnContext with
  ThreadSettings](https://github.com/openai/codex/pull/22508)
  6. [6 of 7] [Add app-server thread settings
  API](https://github.com/openai/codex/pull/22509)
  7. [7 of 7] [Sync TUI thread
  settings](https://github.com/openai/codex/pull/22510)

  Eric Traut · 2026-05-18 18:48:35 -07:00
  84d941d07f
• [codex] Trim unused TurnContextItem fields (#22709)

  ## Why
  
  `TurnContextItem` is the durable baseline used to reconstruct context
  diffs across resume/fork. Most of the old persisted-only fields on it
  are no longer read, so keeping them in rollout snapshots adds schema
  surface and state that can drift without affecting reconstruction.
  
  `summary` is the exception: older Codex versions require it to
  deserialize `turn_context` records, so keep writing a default
  compatibility value until that schema surface can be removed safely.
  
  ## What changed
  
  - Removed the unused persisted fields from `TurnContextItem`: trace ids,
  user/developer instructions, output schema, and truncation policy.
  - Kept `summary` with a compatibility comment and made
  `TurnContext::to_turn_context_item` write `ReasoningSummary::Auto`
  instead of live turn state.
  - Updated rollout/context reconstruction fixtures for the retained
  summary field.
  
  ## Verification
  
  - `cargo test -p codex-protocol --lib turn_context_item`
  - `cargo test -p codex-rollout
  resume_candidate_matches_cwd_reads_latest_turn_context`
  - `cargo test -p codex-state turn_context`
  - `cargo test -p codex-core --lib
  new_default_turn_captures_current_span_trace_id`
  - `cargo test -p codex-core --lib
  record_initial_history_resumed_turn_context_after_compaction_reestablishes_reference_context_item`
  - `cargo test -p codex-core --test all
  emits_warning_when_resumed_model_differs`
  - `git diff --check`

  pakrym-oai · 2026-05-18 21:54:36 +00:00
  f2368b7de6
• goal: pause continuation loops on usage limits and blockers (#23094)

  Addresses #22833, #22245, #23067
  
  ## Why
  `/goal` can keep synthesizing turns even when the next turn cannot make
  meaningful progress. Hard usage exhaustion can replay failing turns, and
  repeated permission or external-resource blockers can keep burning
  tokens while waiting for user or system intervention.
  
  ## What changed
  - Add resumable `blocked` and `usageLimited` goal states. As with
  `paused`, goal continuation stops with these states.
  - Move to `usageLimited` after usage-limit failures.
  - Allow the built-in `update_goal` tool to set `blocked` only under
  explicit repeated-impasse guidance. Updated goal continuation prompt to
  specify that agent should use `blocked` only when it has made at least
  three attempts to get past an impasse.
  
  Most of the files touched by this PR are because of the small app server
  protocol update.
  
  ## Validation
  
  I manually reproduced a number of situations where an agent can run into
  a true impasse and verified that it properly enters `blocked` state. I
  then resumed and verified that it once again entered `blocked` state
  several turns later if the impasse still exists.
  
  I also manually reproduced the usage-limit condition by creating a
  simulated responses API endpoint that returns 429 errors with the
  appropriate error message. Verified that the goal runtime properly moves
  the goal into `usageLimited` state and TUI UI updates appropriately.
  Verified that `/goal resume` resumes (and immediately goes back into
  `ussageLImited` state if appropriate).
  
  
  ## Follow-up PRs
  
  Small changes will be needed to the GUI clients to properly handle the
  two new states.

  Eric Traut · 2026-05-18 11:28:53 -07:00
  0d344aca9b
• Preserve image detail in app-server inputs (#20693)

  ## Summary
  
  - Add optional image detail to user image inputs across core, app-server
  v2, thread history/event mapping, and the generated app-server
  schemas/types.
  - Preserve requested detail when serializing Responses image inputs:
  omitted detail stays on the existing `high` default, while explicit
  `original` keeps local images on the original-resolution path.
  - Support `high`/`original` consistently for tool image outputs,
  including MCP `codex/imageDetail`, code-mode image helpers, and
  `view_image`.

  Curtis 'Fjord' Hawthorne · 2026-05-15 15:04:04 -07:00
  8543e39885
• app-server: use permission ids and runtime workspace roots (#22611)

  ## Why
  
  This PR builds on [#22610](https://github.com/openai/codex/pull/22610)
  and is the app-server side of the migration from mutable per-turn
  `SandboxPolicy` replacement toward selecting immutable permission
  profiles by id plus mutable runtime workspace roots.
  
  Once permission profiles can carry their own immutable
  `workspace_roots`, app-server no longer needs to mutate the selected
  `PermissionProfile` just to represent thread-specific filesystem
  context. The mutable part now lives on the thread as explicit
  `runtimeWorkspaceRoots`, while `:workspace_roots` remains symbolic until
  the sandbox is realized for a turn.
  
  ## What Changed
  
  - Replaced the v2 permission-selection wrapper surface with plain
  profile ids for `thread/start`, `thread/resume`, `thread/fork`, and
  `turn/start`.
  - Removed the API surface for profile modifications
  (`PermissionProfileSelectionParams`,
  `PermissionProfileModificationParams`,
  `ActivePermissionProfileModification`).
  - Added experimental `runtimeWorkspaceRoots` fields to the thread
  lifecycle and turn-start APIs.
  - Threaded runtime workspace roots through core session/thread
  snapshots, turn overrides, app-server request handling, and command
  execution permission resolution.
  - Kept session permission state symbolic so later runtime root updates
  and cwd-only implicit-root retargeting rebind `:workspace_roots`
  correctly.
  - Updated the embedded clients just enough to send and restore the new
  thread state.
  - Refreshed the generated schema/TypeScript artifacts and the app-server
  README to match the new contract.
  
  ## Verification
  
  Targeted coverage for this layer lives in:
  
  - `codex-rs/app-server-protocol/src/protocol/v2/tests.rs`
  - `codex-rs/app-server/tests/suite/v2/thread_start.rs`
  - `codex-rs/app-server/tests/suite/v2/thread_resume.rs`
  - `codex-rs/app-server/tests/suite/v2/turn_start.rs`
  - `codex-rs/core/src/session/tests.rs`
  
  The key regression checks exercise that:
  
  - `runtimeWorkspaceRoots` resolve against the effective cwd on thread
  start.
  - Profile-declared workspace roots are excluded from the runtime
  workspace roots returned by app-server.
  - A turn-level runtime workspace-root update persists onto the thread
  and is returned by `thread/resume`.
  - A named permission profile selected on one turn remains symbolic so a
  later runtime-root-only turn update changes the actual sandbox writes.
  - A cwd-only turn update retargets the implicit runtime cwd root while
  preserving additional runtime roots.
  - The protocol fixtures and generated client artifacts stay in sync with
  the string-based permission selection contract.
  
  
  
  
  
  
  
  
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22611).
  * #22612
  * __->__ #22611

  Michael Bolin · 2026-05-14 23:00:05 -07:00
  8a5306ff88
• Reapply "Move skills watcher to app-server" (#21652)

  ## Why
  
  PR #21460 reverted the earlier move of skills change watching from
  `codex-core` into app-server. This reapplies that boundary change so
  app-server owns client-facing `skills/changed` notifications and core no
  longer carries the watcher.
  
  ## What
  
  - Restore the app-server `SkillsWatcher` and register it from thread
  listener setup.
  - Remove the core-owned skills watcher and its core live-reload
  integration surface.
  - Restore app-server coverage for `skills/changed` notifications after a
  watched skill file changes.
  
  ## Validation
  
  - `cargo test -p codex-app-server --test all
  suite::v2::skills_list::skills_changed_notification_is_emitted_after_skill_change
  -- --exact --nocapture`
  - `cargo test -p codex-core --lib --no-run`

  pakrym-oai · 2026-05-08 17:41:15 -07:00
  408e6218ab
• Revert "Move skills watcher to app-server" (#21460)

  Reverts openai/codex#21287

  pakrym-oai · 2026-05-07 02:24:20 +00:00
  103dc2b6ae
• Add compact lifecycle hooks (started by vincentkoc - external contrib) (#19905)

  Based on work from Vincent K -
  https://github.com/openai/codex/pull/19060
  
  <img width="1836" height="642" alt="CleanShot 2026-04-29 at 20 47 40@2x"
  src="https://github.com/user-attachments/assets/b647bb89-65fe-40c8-80b0-7a6b7c984634"
  />
  
  ## Why
  
  Compaction rewrites the conversation context that future model turns
  receive, but hooks currently have no deterministic lifecycle point
  around that rewrite. This adds compact lifecycle hooks so users can
  audit manual and automatic compaction, surface hook messages in the UI,
  and run post-compaction follow-up without overloading tool or prompt
  hooks.
  
  ## What Changed
  
  - Added `PreCompact` and `PostCompact` hook events across hook config,
  discovery, dispatch, generated schemas, app-server notifications,
  analytics, and TUI hook rendering.
  - Added trigger matching for compact hooks with the documented `manual`
  and `auto` matcher values.
  - Wired `PreCompact` before both local and remote compaction, and
  `PostCompact` after successful local or remote compaction.
  - Kept compact hook command input to lifecycle metadata: session id,
  Codex turn id, transcript path, cwd, hook event name, model, and
  trigger.
  - Made compact stdout handling consistent with other hooks: plain stdout
  is ignored as debug output, while malformed JSON-looking stdout is
  reported as failed hook output.
  - Added integration coverage for compact hook dispatch, trigger
  matching, post-compact execution, and the audited behavior that
  `decision:"block"` does not block compaction.
  
  ## Out of Scope
  
  - Hook-specific compaction blocking is not implemented;
  `decision:"block"` and exit-code-2 blocking semantics are intentionally
  unsupported for `PreCompact`.
  - Custom compaction instructions are not exposed to compact hooks in
  this PR.
  - Compact summaries, summary character counts, and summary previews are
  not exposed to compact hooks in this PR.
  
  ## Verification
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-core
  manual_pre_compact_block_decision_does_not_block_compaction`
  - `cargo test -p codex-app-server hooks_list`
  - `cargo test -p codex-core config_schema_matches_fixture`
  - `cargo test -p codex-tui hooks_browser`
  
  ## Docs
  
  The developer documentation for Codex hooks should be updated alongside
  this feature to document `PreCompact` and `PostCompact`, the
  `manual`/`auto` matcher values, and the compact hook payload fields.
  
  ---------
  
  Co-authored-by: Vincent Koc <vincentkoc@ieee.org>

  Andrei Eternal · 2026-05-06 18:08:31 -07:00
  527d52df03
• Move skills watcher to app-server (#21287)

  ## Why
  
  Skills update notifications are app-server API behavior, but the watcher
  lived in `codex-core` and surfaced through
  `EventMsg::SkillsUpdateAvailable`. Moving the watcher out keeps core
  focused on thread execution and lets app-server own both cache
  invalidation and the `skills/changed` notification.
  
  ## What changed
  
  - Added an app-server-owned skills watcher that watches local skill
  roots, clears the shared skills cache, and emits `skills/changed`
  directly.
  - Registers skill watches from the common app-server thread listener
  attach path, including direct starts, resumes, and app-server-observed
  child or forked threads.
  - Stores the `WatchRegistration` on `ThreadState`, so listener
  replacement, thread teardown, idle unload, and app-server shutdown
  deregister by dropping the RAII guard.
  - Removed `EventMsg::SkillsUpdateAvailable`, the core watcher, and the
  old core live-reload test.
  - Extended the app-server skills change test to verify a cached skills
  list is refreshed after a filesystem change without forcing reload.
  
  ## Validation
  
  - `cargo check -p codex-core -p codex-app-server -p codex-mcp-server -p
  codex-rollout -p codex-rollout-trace`
  - `cargo test -p codex-app-server
  skills_changed_notification_is_emitted_after_skill_change`

  pakrym-oai · 2026-05-06 15:38:11 -07:00
  d5eea229cc
• Remove core MCP list tools op (#21281)

  ## Why
  
  The core `Op::ListMcpTools` request path is no longer needed. Keeping it
  around left a dead request/response surface alongside the app-server MCP
  inventory APIs that own current server status listing.
  
  ## What Changed
  
  - Removed `Op::ListMcpTools`, `EventMsg::McpListToolsResponse`, and the
  core handler that built the MCP snapshot response.
  - Removed the now-unused `codex-mcp` snapshot wrapper/export and passive
  event handling arms in rollout and MCP-server consumers.
  - Updated tests that used the old op as a synchronization hook to wait
  on existing startup/skills events, and deleted the plugin test that only
  exercised the removed listing op.
  
  ## Validation
  
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-mcp`
  - `cargo test -p codex-rollout -p codex-rollout-trace -p
  codex-mcp-server`
  - `cargo test -p codex-core --test all
  pending_input::queued_inter_agent_mail`
  - `cargo test -p codex-core --test all
  rmcp_client::stdio_mcp_tool_call_includes_sandbox_state_meta`
  - `cargo test -p codex-core --test all
  rmcp_client::stdio_image_responses`
  - `just fix -p codex-core -p codex-protocol -p codex-mcp -p
  codex-rollout -p codex-rollout-trace -p codex-mcp-server`

  pakrym-oai · 2026-05-06 11:20:34 -07:00
  712305be47
• Move message history out of core (#21278)

  ## Why
  
  Message history was implemented inside `codex-core` and surfaced through
  core protocol ops and `SessionConfiguredEvent` fields even though the
  current consumer is TUI-local prompt recall. That made core own UI
  history persistence and exposed `history_log_id` / `history_entry_count`
  through surfaces that app-server and other clients do not need.
  
  This change moves message history persistence out of core and keeps the
  recall plumbing local to the TUI.
  
  ## What changed
  
  - Added a new `codex-message-history` crate for appending, looking up,
  trimming, and reading metadata from `history.jsonl`.
  - Removed core protocol history ops/events: `AddToHistory`,
  `GetHistoryEntryRequest`, and `GetHistoryEntryResponse`.
  - Removed `history_log_id` and `history_entry_count` from
  `SessionConfiguredEvent` and updated exec/MCP/test fixtures accordingly.
  - Updated the TUI to dispatch local app events for message-history
  append/lookup and keep its persistent-history metadata in TUI session
  state.
  
  ## Validation
  
  - `cargo test -p codex-message-history -p codex-protocol`
  - `cargo test -p codex-exec event_processor_with_json_output`
  - `cargo test -p codex-mcp-server outgoing_message`
  - `cargo test -p codex-tui`
  - `just fix -p codex-message-history -p codex-protocol -p codex-core -p
  codex-tui -p codex-exec -p codex-mcp-server`

  pakrym-oai · 2026-05-06 08:35:42 -07:00
  2004173cd7
• 2- Use string service tiers in session protocol (#20971)

  ## Summary
  - break service tier session/op/app-server protocol fields from the
  closed enum to string tier ids
  - send the service tier string directly through model requests, prewarm,
  compaction, memories, and TUI/app-server turn starts
  - regenerate app-server protocol JSON/TypeScript schemas, removing the
  standalone ServiceTier TS enum
  
  ## Verification
  - just fmt
  - cargo check -p codex-core -p codex-app-server -p codex-tui
  - just write-app-server-schema
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-05-06 18:00:21 +03:00
  be1d3cff93
• feat: add session_id (#20437)

  ## Summary
  
  Related to
  https://openai.slack.com/archives/C095U48JNL9/p1777537279707449
  TLDR:
  We update the meaning of session ids and thread ids:
  * thread_id stays as now
  * session_id become a shared id between every thread under a /root
  thread (i.e. every sub-agent share the same session id)
  
  This PR introduces an explicit `SessionId` and threads it through the
  protocol/client boundary so `session_id` and `thread_id` can diverge
  when they need to, while preserving compatibility for older serialized
  `session_configured` events.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  jif-oai · 2026-05-06 10:48:37 +02:00
  a98623511b
• [codex-analytics] rework thread_source for thread analytics (#20949)

  ## Summary
  - make `thread_source` an explicit optional thread-level field on
  `thread/start`, `thread/fork`, and returned thread payloads
  - persist `thread_source` in rollout/session metadata so resumed live
  threads retain the original value
  - replace the old best-effort `session_source` -> `thread_source`
  mapping with an explicit caller-supplied analytics classification
  
  ## Why
  Before this change, analytics `thread_source` was populated by a
  best-effort mapping from `session_source`. `session_source` describes
  the runtime/client surface, not the actual thread-level origin, so that
  projection was not accurate enough to distinguish cases such as `user`,
  `subagent`, `memory_consolidation`, and future thread origins reliably.
  
  Making `thread_source` explicit keeps one thread-level analytics field
  while letting callers provide the real classification directly instead
  of recovering it indirectly from `session_source`.
  
  ## Impact
  For new analytics events, `thread_source` now reflects the explicit
  thread-level classification supplied by the caller rather than an
  inferred value derived from `session_source`. Existing protocol fields
  remain optional; callers that omit `threadSource` now produce `null`
  instead of a best-effort inferred value.
  
  ## Validation
  - `just write-app-server-schema`
  - `cargo test -p codex-analytics -p codex-core -p
  codex-app-server-protocol --no-run`
  - `cargo test -p codex-app-server-protocol
  generated_ts_optional_nullable_fields_only_in_params`
  - `cargo test -p codex-analytics
  thread_initialized_event_serializes_expected_shape`
  - `cargo test -p codex-core
  resume_stopped_thread_from_rollout_preserves_thread_source`

  rhan-oai · 2026-05-06 02:12:31 +00:00
  b3d4f1a9f0
• [codex] Remove legacy ListSkills op (#21282)

  ## Why
  
  `skills/list` is already exposed through app-server v2 and covered by
  the app-server test suite. Keeping the separate core `Op::ListSkills`
  path leaves a duplicate legacy protocol surface that no longer needs to
  be maintained.
  
  ## What Changed
  
  - Removed `Op::ListSkills` and `EventMsg::ListSkillsResponse` from the
  core protocol.
  - Deleted the corresponding core session handler and stale core
  integration tests.
  - Removed rollout/MCP ignore branches and protocol v1 docs references
  for the deleted event/op.
  - Left app-server `skills/list` and its existing coverage intact.
  
  ## Validation
  
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-core --test all suite::skills`
  - `cargo check -p codex-mcp-server -p codex-rollout -p
  codex-rollout-trace`
  - `just fix -p codex-core`

  pakrym-oai · 2026-05-05 18:58:18 -07:00
  136e442e95
• [codex] Remove unused ListModels op (#21276)

  ## Why
  
  The core protocol still exposed a `ListModels` submission op even though
  no client sends it and the core submission loop treated it as an ignored
  unknown op. Keeping the dead variant made the protocol surface look
  supported while the active model listing API is the app-server
  `model/list` JSON-RPC request.
  
  ## What Changed
  
  - Removed the unused `Op::ListModels` variant from `codex-rs/protocol`.
  - Removed its `Op::kind()` mapping.
  
  The existing app-server `model/list` endpoint is unchanged.
  
  ## Verification
  
  - `cargo test -p codex-protocol`

  pakrym-oai · 2026-05-06 01:57:17 +00:00
  024118625e
• [codex] Move thread naming to app server (#21260)

  ## Why
  
  Thread names are app-server metadata now, backed by the thread store and
  sqlite state database. Keeping a core `SetThreadName` op plus a rollout
  `thread_name_updated` event made rename persistence live in the wrong
  layer and required historical replay support for an event that new
  app-server flows should not write.
  
  ## What changed
  
  - Removed `Op::SetThreadName` and `EventMsg::ThreadNameUpdated` from the
  core protocol and deleted the core handler path that appended rename
  events to rollouts.
  - Updated app-server `thread/name/set` so both loaded and unloaded
  threads write through thread-store metadata and app-server emits
  `thread/name/updated` notifications.
  - Updated local thread-store name metadata updates to write sqlite title
  metadata and the legacy thread-name index without appending rollout
  events.
  - Removed state extraction and rollout handling for the deleted
  thread-name event.
  
  ## Validation
  
  - `cargo test -p codex-app-server thread_name_updated_broadcasts`
  - `cargo test -p codex-app-server
  thread_name_set_is_reflected_in_read_list_and_resume`
  - `cargo test -p codex-thread-store
  update_thread_metadata_sets_name_on_active_rollout_and_indexes_name`
  - `cargo test -p codex-state`
  - `cargo check -p codex-mcp-server -p codex-rollout-trace`
  - `just fix -p codex-app-server -p codex-thread-store -p codex-state -p
  codex-mcp-server -p codex-rollout-trace`
  
  ## Docs
  
  No external documentation update is expected for this internal ownership
  change.

  pakrym-oai · 2026-05-05 17:16:06 -07:00
  2c1a361a2e
• hook trust metadata and enforcement (#20321)

  # Why
  
  We want shared hook trust that both the app and the TUI can build on,
  but the metadata is only useful if runtime behavior agrees with it. This
  PR adds a single backend trust model for hooks so unmanaged hooks cannot
  run until the current definition has been reviewed, while managed hooks
  remain runnable and non-configurable.
  
  # What
  
  - persist `trusted_hash` alongside hook state in `config.toml`
  - expose `currentHash` and derived `trustStatus` through `hooks/list`
  - derive trust from normalized hook definitions so equivalent hooks from
  `config.toml` and `hooks.json` share the same trust identity
  - gate unmanaged hooks on trust before they enter the runnable handler
  set
  
  # Reviewer Notes
  
  - key file to review is `codex-rs/hooks/src/engine/discovery.rs`
  - the only **core** change is schema related

  Abhinav · 2026-05-05 19:13:55 +00:00
  0452dca986
• [codex-analytics] add item lifecycle timing (#20514)

  ## Why
  
  Tool families already disagree on what their existing `duration` fields
  mean, so lifecycle latency should live on the shared item envelope
  instead of being inferred from per-tool execution fields. Carrying that
  envelope through app-server notifications gives downstream consumers one
  reusable timing signal without pretending every tool has the same
  execution semantics.
  
  ## What changed
  
  - Adds `started_at_ms` to core `ItemStartedEvent` values and
  `completed_at_ms` to core `ItemCompletedEvent` values.
  - Populates those timestamps in the shared session lifecycle emitters,
  so protocol-native items get timing without each producer tracking its
  own clock state.
  - Exposes `startedAtMs` on app-server `item/started` notifications and
  `completedAtMs` on `item/completed` notifications.
  - Maps the lifecycle timestamps through the app-server boundary while
  leaving legacy-converted notifications nullable when no lifecycle
  timestamp exists.
  - Regenerates the app-server JSON schema and TypeScript fixtures for the
  notification-envelope change and updates downstream fixtures that
  construct those notifications directly.
  - Extends the existing web-search and image-generation integration flows
  to assert the new lifecycle timestamps on the native item events.
  
  ## Verification
  
  - `cargo check -p codex-protocol -p codex-core -p
  codex-app-server-protocol -p codex-app-server -p codex-tui -p codex-exec
  -p codex-app-server-client`
  - `cargo test -p codex-core --test all web_search_item_is_emitted`
  - `cargo test -p codex-core --test all
  image_generation_call_event_is_emitted`
  - `cargo test -p codex-app-server-protocol`
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/20514).
  * #18748
  * #18747
  * #17090
  * #17089
  * __->__ #20514

  rhan-oai · 2026-05-04 22:33:20 +00:00
  aee1fe2659
• [codex] Emit MCP tool calls as turn items (#20677)

  ## Why
  
  `McpToolCall` was still an app-server item synthesized from deprecated
  legacy begin/end events. Recent item migrations moved this ownership
  into core `TurnItem`s, so MCP tool calls now follow the same canonical
  lifecycle and leave legacy events as compatibility fanout.
  
  Keeping the core item close to the v2 `ThreadItem::McpToolCall` shape
  also avoids spreading MCP result semantics across app-server conversion
  code. Core now owns whether a completed call is `completed` or `failed`,
  and whether the payload is a tool result or an error.
  
  ## What changed
  
  - Added core `TurnItem::McpToolCall` with flattened `server`, `tool`,
  `arguments`, `status`, `result`, and `error` fields.
  - Updated MCP tool call emitters, including MCP resource tools, to emit
  `ItemStarted`/`ItemCompleted` around directly constructed core MCP
  items.
  - Updated app-server v2 conversion to project the core MCP item into
  `ThreadItem::McpToolCall` without deriving status or splitting `Result`
  locally.
  - Ignored live deprecated MCP legacy fanout in app-server v2 to avoid
  duplicate item notifications, while keeping thread history replay on the
  legacy event path.
  
  ## Verification
  
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-app-server-protocol`
  - `cargo test -p codex-core --lib mcp_tool_call`
  - `cargo check -p codex-app-server`
  - `cargo test -p codex-app-server
  mcp_tool_call_completion_notification_contains_truncated_large_result`

  pakrym-oai · 2026-05-03 22:50:13 -07:00
  c8c30d9d75
• [codex] Emit image view as core item (#20512)

  ## Why
  
  Image-view results should be represented as a core-produced turn item
  instead of being reconstructed by app-server. At the same time, existing
  rollout/history paths still understand the legacy `ViewImageToolCall`
  event, so this keeps that event as compatibility output generated from
  the new item lifecycle.
  
  ## What changed
  
  - Added `TurnItem::ImageView` to `codex-protocol`.
  - Emitted image-view item start/completion directly from the core
  `view_image` handler.
  - Kept `ViewImageToolCall` as a legacy event and generate it from
  completed `TurnItem::ImageView` items.
  - Kept `thread_history.rs` on the legacy `ViewImageToolCall` replay
  path, with `ImageView` item lifecycle events ignored there.
  - Updated app-server protocol conversion, rollout persistence, and
  affected exhaustive event matches for the new item plus legacy fan-out
  shape.
  
  ## Verification
  
  - `cargo test -p codex-protocol -p codex-app-server-protocol -p
  codex-rollout -p codex-rollout-trace -p codex-mcp-server -p
  codex-app-server --lib`
  - `cargo test -p codex-core --test all
  view_image_tool_attaches_local_image`
  - `just fix -p codex-protocol -p codex-core -p codex-app-server-protocol
  -p codex-app-server -p codex-rollout -p codex-rollout-trace -p
  codex-mcp-server`
  - `git diff --check`

  pakrym-oai · 2026-05-01 11:28:30 -07:00
  aed74e5ee4
• Move apply-patch file changes into turn items (#20540)

  ## Why
  
  Apply-patch file changes are now part of the core turn item stream, so
  v2 clients can consume the same first-class item lifecycle path used by
  other turn items instead of relying on app-server-specific remapping
  from legacy patch events.
  
  ## What changed
  
  - Added a core `TurnItem::FileChange` carrying apply-patch changes and
  completion metadata.
  - Updated the apply-patch tool emitter to send `ItemStarted` /
  `ItemCompleted` with the new `FileChange` item while preserving legacy
  `PatchApplyBegin` / `PatchApplyEnd` fan-out.
  - Updated app-server v2 conversion to render the new core item directly
  and stopped `event_mapping` from remapping old patch begin/end events
  into item notifications.
  - Kept thread history reconstruction based on the existing old
  apply-patch events for rollout compatibility.
  
  ## Verification
  
  - `cargo test -p codex-protocol -p codex-app-server-protocol`
  - `cargo test -p codex-core --test all
  apply_patch_tool_executes_and_emits_patch_events`
  - `cargo test -p codex-app-server bespoke_event_handling`

  pakrym-oai · 2026-05-01 08:47:18 -07:00
  f476338f93
• [codex] Remove unused event messages (#20511)

  ## Why
  
  Several legacy `EventMsg` variants were still emitted or mapped even
  though clients either ignored them or had moved to item/lifecycle
  events. `Op::Undo` had also degraded to an unavailable shim, so this
  removes that dead task path instead of preserving a command that cannot
  do useful work.
  
  `McpStartupComplete`, `WebSearchBegin`, and `ImageGenerationBegin` are
  intentionally kept because useful consumers still depend on them: MCP
  startup completion drives readiness behavior, and the begin events let
  app-server/core consumers surface in-progress web-search and
  image-generation items before the final payload arrives.
  
  ## What Changed
  
  - Removed weak legacy event variants and payloads from `codex-protocol`,
  including legacy agent deltas, background events, and undo lifecycle
  events.
  - Kept/restored `EventMsg::McpStartupComplete`,
  `EventMsg::WebSearchBegin`, and `EventMsg::ImageGenerationBegin` with
  serializer and emission coverage.
  - Updated core, rollout, MCP server, app-server thread history,
  review/delegate filtering, and tests to rely on the useful replacement
  events that remain.
  - Removed `Op::Undo`, `UndoTask`, the undo test module, and stale TUI
  slash-command comments.
  - Stopped agent job/background progress and compaction retry notices
  from emitting `BackgroundEvent` payloads.
  
  ## Verification
  
  - `cargo check -p codex-protocol -p codex-app-server-protocol -p
  codex-core -p codex-rollout -p codex-rollout-trace -p codex-mcp-server`
  - `cargo test -p codex-protocol -p codex-app-server-protocol -p
  codex-rollout -p codex-rollout-trace -p codex-mcp-server`
  - `cargo test -p codex-core --test all suite::items`
  - `just fix -p codex-protocol -p codex-app-server-protocol -p codex-core
  -p codex-rollout -p codex-rollout-trace -p codex-mcp-server`
  - Earlier coverage on this PR also included `codex-mcp`, `codex-tui`,
  core library tests, MCP/plugin/delegate/review/agent job tests, and MCP
  startup TUI tests.

  pakrym-oai · 2026-04-30 20:03:26 -07:00
  f50c02d7bc
• Add /hooks browser for lifecycle hooks (#19882)

  ## Why
  
  `hooks/list` and `hooks/config/write` give us read/write access to hooks
  and their state. This hooks up the TUI as a client so users can inspect
  and manage that state directly.
  
  ## What
  
  - add a two-page `/hooks` browser in the TUI: an event overview with
  installed/active counts, followed by a per-event handler page with
  toggle controls and detail rendering
  - thread managed-state metadata through hook discovery and `hooks/list`
  so the UI can label admin-managed hooks and suppress toggles for them
  - persist hook toggles through the existing config-write path and add
  snapshot coverage for the event list, handler list, managed-hook, and
  empty states
  
  ## Stack
  
  1. openai/codex#19705
  2. openai/codex#19778
  3. openai/codex#19840
  4. This PR - openai/codex#19882
  
  ## Reviewer Notes
  
  - Main UI logic is in
  `codex-rs/tui/src/bottom_pane/hooks_browser_view.rs`; most of the diff
  is the new view plus its snapshot coverage
  - Request / write plumbing for opening the browser and persisting
  toggles is in `codex-rs/tui/src/app/background_requests.rs` and
  `codex-rs/tui/src/chatwidget/hooks.rs`
  - Outside the TUI, the only behavioral change in this PR is threading
  `is_managed` through hook discovery and `hooks/list` so managed hooks
  render as non-toggleable
  - The `codex-rs/tui/src/status/snapshots/` churn is unrelated merge
  fallout from the stacked base branch's newer permission-label rendering
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-30 11:58:27 -07:00
  93d53f655b
• realtime: rename provider session ids (#20361)

  ## Summary
  
  Codex is repurposing `session` to mean a thread group, so the realtime
  provider session id should no longer use `session_id` / `sessionId` in
  Codex-facing protocol payloads. This PR renames that provider-specific
  field to `realtime_session_id` / `realtimeSessionId` and intentionally
  breaks clients that still send the old field names.
  
  ## What Changed
  
  - Renamed realtime provider session fields in `ConversationStartParams`,
  `RealtimeConversationStartedEvent`, and `RealtimeEvent::SessionUpdated`.
  - Renamed app-server v2 realtime request and notification fields to
  `realtimeSessionId`.
  - Removed legacy serde aliases for `session_id` / `sessionId`; clients
  must send the new names.
  - Propagated the rename through core realtime startup, app-server
  adapters, codex-api websocket handling, and TUI realtime state.
  - Regenerated app-server protocol schema/TypeScript outputs and updated
  app-server README examples.
  - Kept upstream Realtime API concepts unchanged: provider `session.id`
  parsing and `x-session-id` headers still use the upstream wire names.
  
  ## Testing
  
  - CI is running on the latest pushed commit.
  - Earlier local verification on this PR:
    - `cargo test -p codex-protocol`
  - `CODEX_SKIP_VENDORED_BWRAP=1 cargo test -p codex-core
  realtime_conversation`
    - `cargo test -p codex-app-server-protocol`
  - `CODEX_SKIP_VENDORED_BWRAP=1 cargo test -p codex-app-server
  realtime_conversation`
  - attempted `CODEX_SKIP_VENDORED_BWRAP=1 cargo test -p codex-tui` (local
  linker bus error while linking the test binary)
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Ahmed Ibrahim · 2026-04-30 13:39:48 +03:00
  8a97f3cf03
• Add persisted hook enablement state (#19840)

  ## Why
  
  After `hooks/list` exposes the hook inventory, clients need a way to
  persist user hook preferences, make those changes effective in
  already-open sessions, and distinguish user-controllable hooks from
  managed requirements without adding another bespoke app-server write
  API.
  
  ## What
  
  - Extends `hooks/list` entries with effective `enabled` state.
  - Persists user-level hook state under `hooks.state.<hook-id>` so the
  model can grow beyond a single boolean over time.
  - Uses the existing `config/batchWrite` path for hook state updates
  instead of introducing a dedicated hook write RPC.
  - Refreshes live session hook engines after config writes so
  already-open threads observe updated enablement without a restart.
  
  ## Stack
  
  1. openai/codex#19705
  2. openai/codex#19778
  3. This PR - openai/codex#19840
  4. openai/codex#19882
  
  ## Reviewer Notes
  
  The generated schema files account for much of the raw diff. The core
  behavior is in:
  
  - `hooks/src/config_rules.rs`, which resolves per-hook user state from
  the config layer stack.
  - `hooks/src/engine/discovery.rs`, which projects effective enablement
  into `hooks/list` from source-derived managedness.
  - `config/src/hook_config.rs`, which defines the new `hooks.state`
  representation.
  - `core/src/session/mod.rs`, which rebuilds live hook state after user
  config reloads.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-30 04:46:32 +00:00
  8f3c06cc97
• permissions: expose active profile metadata (#20095)
  Michael Bolin · 2026-04-29 20:54:59 -07:00
  ac4332c05b
• test protocol: lock inter-agent commentary phase (#20046)

  ## Summary
  - add a regression test for
  `InterAgentCommunication::to_response_input_item`
  - assert replayed inter-agent messages keep `phase:
  Some(MessagePhase::Commentary)`
  
  ## Test plan
  - `cargo test -p codex-protocol`
  - `just argument-comment-lint`

  friel-openai · 2026-04-29 11:24:17 -07:00
  05fd904572
• Discover hooks bundled with plugins (#19705)

  ## Why
  
  Plugins can bundle lifecycle hooks, but Codex previously only discovered
  hooks from user, project, and managed config layers. This adds the
  plugin discovery and runtime plumbing needed for plugin-bundled hooks
  while keeping execution behind the `plugin_hooks` feature flag.
  
  ## What
  
  - Discovers plugin hook sources from each plugin's default
  `hooks/hooks.json`.
  - Supports `plugin.json` manifest `hooks` entries as either relative
  paths or inline hook objects.
  - Plumbs discovered plugin hook sources through plugin loading into the
  hook runtime when `plugin_hooks` is enabled.
  - Marks plugin-originated hook runs as `HookSource::Plugin`.
  - Injects `PLUGIN_ROOT` and `CLAUDE_PLUGIN_ROOT` into plugin hook
  command environments.
  - Updates generated schemas and hook source metadata for the plugin hook
  source.
  
  ## Stack
  
  1. This PR - openai/codex#19705
  2. openai/codex#19778
  3. openai/codex#19840
  4. openai/codex#19882
  
  ## Reviewer Notes
  
  - Core logic is in `codex-rs/core-plugins/src/loader.rs` and
  `codex-rs/hooks/src/engine/discovery.rs`
  - Moved existing / adding new tests to
  `codex-rs/core-plugins/src/loader_tests.rs` hence the large diff there
  - Otherwise mostly plumbing and minor schema updates
  
  ### Core Changes
  
  The `codex-rs/core` changes are limited to wiring plugin hook support
  into existing core flows:
  
  - `core/src/session/session.rs` conditionally pulls effective plugin
  hook sources and plugin hook load warnings from `PluginsManager` when
  `plugin_hooks` is enabled, then passes them into `HooksConfig`.
  - `core/src/hook_runtime.rs` adds the `plugin` metric tag for
  `HookSource::Plugin`.
  - `core/config.schema.json` picks up the new `plugin_hooks` feature
  flag, and `core/src/plugins/manager_tests.rs` updates fixtures for the
  added plugin hook fields.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-28 14:17:18 -07:00
  c6e7d564c3
• [sandbox] Enforce protected workspace metadata paths (#19846)

  ## Summary
  
  Make FileSystemSandboxPolicy the semantic source of truth for project
  root metadata protection. Under writable roots, `.git`, `.codex`, and
  `.agents` stay protected unless user policy grants an explicit write
  rule for that metadata path.
  
  ## Scope
  
  1. Add `protected_metadata_names` to `WritableRoot`.
  2. Teach `FileSystemSandboxPolicy::can_write_path_with_cwd` to reject
  protected metadata writes under writable roots unless explicitly
  allowed.
  3. Default workspace write profiles to protect `.git`, `.codex`, and
  `.agents`.
  4. Add the Linux fallback setup needed before Linux enforcement lands
  later in the stack.
  
  ## Reviewer Focus
  
  1. The policy decision belongs in FileSystemSandboxPolicy, not shell
  command parsing.
  2. Legacy SandboxPolicy remains a compatibility projection, not the
  source of the new rule.
  3. Explicit user write rules can still opt into these metadata paths.
  
  ## Stack
  
  1. Policy primitive: this PR
  2. macOS Seatbelt adapter: #19847
  3. Shell preflight UX: #19848
  4. Runtime profile propagation: #19849
  5. Linux bubblewrap adapter: #19852
  
  ## Validation
  
  1. codex protocol permissions tests
  2. formatting for codex protocol and codex linux sandbox
  3. diff whitespace check

  evawong-oai · 2026-04-28 09:10:41 -07:00
  0156b1e61f
• Preserve assistant phase for replayed messages (#19832)
  friel-openai · 2026-04-28 08:46:13 -07:00
  598bbcdb58
• feat: split memories part 2 (#19860)

  Keep extracting memories out of core and moving the write trigger in the
  app-server
  This is temporary and it should move at the client level as a follow-up
  This makes core fully independant from `codex-memories-write`
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  jif-oai · 2026-04-28 13:03:28 +02:00
  431ebeaef7
• permissions: make SessionConfigured profile-only (#19774)

  ## Why
  
  `SessionConfiguredEvent` is the internal event that tells clients what
  permissions are active for a session. Emitting both `sandbox_policy` and
  `permission_profile` leaves two possible authorities and forces every
  consumer to decide which one to honor. At this point in the migration,
  the profile is expressive enough to represent managed, disabled, and
  external sandbox enforcement, so the internal event can be profile-only.
  
  The wire compatibility concern is older serialized events or rollout
  data that only contain `sandbox_policy`; those still need to
  deserialize.
  
  ## What Changed
  
  - Removes `sandbox_policy` from `SessionConfiguredEvent` and makes
  `permission_profile` required.
  - Adds custom deserialization so old payloads with only `sandbox_policy`
  are upgraded to a cwd-anchored `PermissionProfile`.
  - Updates core event emission and TUI session handling to sync
  permissions from the profile directly.
  - Updates app-server response construction to derive the legacy
  `sandbox` response field from the active thread snapshot instead of from
  `SessionConfiguredEvent`.
  - Updates yolo-mode display logic to treat both
  `PermissionProfile::Disabled` and managed unrestricted filesystem plus
  enabled network as full-access, while still preserving the distinction
  between no sandbox and external sandboxing.
  
  ## Verification
  
  - `cargo test -p codex-protocol session_configured_event --lib`
  - `cargo test -p codex-protocol serialize_event --lib`
  - `cargo test -p codex-exec session_configured --lib`
  - `cargo test -p codex-app-server
  thread_response_permission_profile_preserves_enforcement --lib`
  - `cargo test -p codex-core
  session_configured_reports_permission_profile_for_external_sandbox
  --lib`
  - `cargo test -p codex-tui session_configured --lib`
  - `cargo test -p codex-tui
  yolo_mode_includes_managed_full_access_profiles --lib`
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/19774).
  * #19900
  * #19899
  * #19776
  * #19775
  * __->__ #19774

  Michael Bolin · 2026-04-27 22:06:47 -07:00
  bf38def44e