compact

We were assembling the skill roots in two different places, and the
admin root was missing in one of them. This change centralizes root
selection into a helper so both paths stay in sync.

.codespellignore

@@ -1,2 +1,3 @@
 iTerm
+iTerm2
 psuedo

.codespellrc

@@ -3,4 +3,4 @@
 skip = .git*,vendor,*-lock.yaml,*.lock,.codespellrc,*test.ts,*.jsonl,frame*.txt
 check-hidden = true
 ignore-regex = ^\s*"image/\S+": ".*|\b(afterAll)\b
-ignore-words-list = ratatui,ser
+ignore-words-list = ratatui,ser,iTerm,iterm2,iterm

.github/actions/macos-code-sign/action.yml

@@ -4,6 +4,14 @@ inputs:
   target:
     description: Rust compilation target triple (e.g. aarch64-apple-darwin).
     required: true
+  sign-binaries:
+    description: Whether to sign and notarize the macOS binaries.
+    required: false
+    default: "true"
+  sign-dmg:
+    description: Whether to sign and notarize the macOS dmg.
+    required: false
+    default: "true"
   apple-certificate:
     description: Base64-encoded Apple signing certificate (P12).
     required: true
@@ -107,6 +115,7 @@ runs:
         echo "::add-mask::$APPLE_CODESIGN_IDENTITY"
 
     - name: Sign macOS binaries
+      if: ${{ inputs.sign-binaries == 'true' }}
       shell: bash
       run: |
         set -euo pipefail
@@ -127,6 +136,7 @@ runs:
         done
 
     - name: Notarize macOS binaries
+      if: ${{ inputs.sign-binaries == 'true' }}
       shell: bash
       env:
         APPLE_NOTARIZATION_KEY_P8: ${{ inputs.apple-notarization-key-p8 }}
@@ -149,6 +159,8 @@ runs:
         }
         trap cleanup_notary EXIT
 
+        source "$GITHUB_ACTION_PATH/notary_helpers.sh"
+
         notarize_binary() {
           local binary="$1"
           local source_path="codex-rs/target/${{ inputs.target }}/release/${binary}"
@@ -162,32 +174,54 @@ runs:
           rm -f "$archive_path"
           ditto -c -k --keepParent "$source_path" "$archive_path"
 
-          submission_json=$(xcrun notarytool submit "$archive_path" \
-            --key "$notary_key_path" \
-            --key-id "$APPLE_NOTARIZATION_KEY_ID" \
-            --issuer "$APPLE_NOTARIZATION_ISSUER_ID" \
-            --output-format json \
-            --wait)
-
-          status=$(printf '%s\n' "$submission_json" | jq -r '.status // "Unknown"')
-          submission_id=$(printf '%s\n' "$submission_json" | jq -r '.id // ""')
-
-          if [[ -z "$submission_id" ]]; then
-            echo "Failed to retrieve submission ID for $binary"
-            exit 1
-          fi
-
-          echo "::notice title=Notarization::$binary submission ${submission_id} completed with status ${status}"
-
-          if [[ "$status" != "Accepted" ]]; then
-            echo "Notarization failed for ${binary} (submission ${submission_id}, status ${status})"
-            exit 1
-          fi
+          notarize_submission "$binary" "$archive_path" "$notary_key_path"
         }
 
         notarize_binary "codex"
         notarize_binary "codex-responses-api-proxy"
 
+    - name: Sign and notarize macOS dmg
+      if: ${{ inputs.sign-dmg == 'true' }}
+      shell: bash
+      env:
+        APPLE_NOTARIZATION_KEY_P8: ${{ inputs.apple-notarization-key-p8 }}
+        APPLE_NOTARIZATION_KEY_ID: ${{ inputs.apple-notarization-key-id }}
+        APPLE_NOTARIZATION_ISSUER_ID: ${{ inputs.apple-notarization-issuer-id }}
+      run: |
+        set -euo pipefail
+
+        for var in APPLE_CODESIGN_IDENTITY APPLE_NOTARIZATION_KEY_P8 APPLE_NOTARIZATION_KEY_ID APPLE_NOTARIZATION_ISSUER_ID; do
+          if [[ -z "${!var:-}" ]]; then
+            echo "$var is required"
+            exit 1
+          fi
+        done
+
+        notary_key_path="${RUNNER_TEMP}/notarytool.key.p8"
+        echo "$APPLE_NOTARIZATION_KEY_P8" | base64 -d > "$notary_key_path"
+        cleanup_notary() {
+          rm -f "$notary_key_path"
+        }
+        trap cleanup_notary EXIT
+
+        source "$GITHUB_ACTION_PATH/notary_helpers.sh"
+
+        dmg_path="codex-rs/target/${{ inputs.target }}/release/codex-${{ inputs.target }}.dmg"
+
+        if [[ ! -f "$dmg_path" ]]; then
+          echo "dmg $dmg_path not found"
+          exit 1
+        fi
+
+        keychain_args=()
+        if [[ -n "${APPLE_CODESIGN_KEYCHAIN:-}" && -f "${APPLE_CODESIGN_KEYCHAIN}" ]]; then
+          keychain_args+=(--keychain "${APPLE_CODESIGN_KEYCHAIN}")
+        fi
+
+        codesign --force --timestamp --sign "$APPLE_CODESIGN_IDENTITY" "${keychain_args[@]}" "$dmg_path"
+        notarize_submission "codex-${{ inputs.target }}.dmg" "$dmg_path" "$notary_key_path"
+        xcrun stapler staple "$dmg_path"
+
     - name: Remove signing keychain
       if: ${{ always() }}
       shell: bash

.github/actions/macos-code-sign/notary_helpers.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+notarize_submission() {
+  local label="$1"
+  local path="$2"
+  local notary_key_path="$3"
+
+  if [[ -z "${APPLE_NOTARIZATION_KEY_ID:-}" || -z "${APPLE_NOTARIZATION_ISSUER_ID:-}" ]]; then
+    echo "APPLE_NOTARIZATION_KEY_ID and APPLE_NOTARIZATION_ISSUER_ID are required for notarization"
+    exit 1
+  fi
+
+  if [[ -z "$notary_key_path" || ! -f "$notary_key_path" ]]; then
+    echo "Notary key file $notary_key_path not found"
+    exit 1
+  fi
+
+  if [[ ! -f "$path" ]]; then
+    echo "Notarization payload $path not found"
+    exit 1
+  fi
+
+  local submission_json
+  submission_json=$(xcrun notarytool submit "$path" \
+    --key "$notary_key_path" \
+    --key-id "$APPLE_NOTARIZATION_KEY_ID" \
+    --issuer "$APPLE_NOTARIZATION_ISSUER_ID" \
+    --output-format json \
+    --wait)
+
+  local status submission_id
+  status=$(printf '%s\n' "$submission_json" | jq -r '.status // "Unknown"')
+  submission_id=$(printf '%s\n' "$submission_json" | jq -r '.id // ""')
+
+  if [[ -z "$submission_id" ]]; then
+    echo "Failed to retrieve submission ID for $label"
+    exit 1
+  fi
+
+  echo "::notice title=Notarization::$label submission ${submission_id} completed with status ${status}"
+
+  if [[ "$status" != "Accepted" ]]; then
+    echo "Notarization failed for ${label} (submission ${submission_id}, status ${status})"
+    exit 1
+  fi
+}

.github/workflows/ci.yml

@@ -36,7 +36,8 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
-          CODEX_VERSION=0.40.0
+          # Use a rust-release version that includes all native binaries.
+          CODEX_VERSION=0.74.0
           OUTPUT_DIR="${RUNNER_TEMP}"
           python3 ./scripts/stage_npm_packages.py \
             --release-version "$CODEX_VERSION" \

.github/workflows/rust-ci.yml

@@ -28,9 +28,11 @@ jobs:
 
           if [[ "${{ github.event_name }}" == "pull_request" ]]; then
             BASE_SHA='${{ github.event.pull_request.base.sha }}'
+            HEAD_SHA='${{ github.event.pull_request.head.sha }}'
             echo "Base SHA: $BASE_SHA"
-            # List files changed between base and current HEAD (merge-base aware)
-            mapfile -t files < <(git diff --name-only --no-renames "$BASE_SHA"...HEAD)
+            echo "Head SHA: $HEAD_SHA"
+            # List files changed between base and PR head
+            mapfile -t files < <(git diff --name-only --no-renames "$BASE_SHA" "$HEAD_SHA")
           else
             # On push / manual runs, default to running everything
             files=("codex-rs/force" ".github/force")

.github/workflows/rust-release-prepare.yml

@@ -49,4 +49,3 @@ jobs:
           branch: "bot/update-models-json"
           reviewers: "pakrym-oai,aibrahim-oai"
           delete-branch: true
-          path: codex-rs

.github/workflows/rust-release.yml

@@ -128,11 +128,72 @@ jobs:
           account-name: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
           certificate-profile-name: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME }}
 
-      - if: ${{ matrix.runner == 'macos-15-xlarge' }}
-        name: MacOS code signing
+      - if: ${{ runner.os == 'macOS' }}
+        name: MacOS code signing (binaries)
         uses: ./.github/actions/macos-code-sign
         with:
           target: ${{ matrix.target }}
+          sign-binaries: "true"
+          sign-dmg: "false"
+          apple-certificate: ${{ secrets.APPLE_CERTIFICATE_P12 }}
+          apple-certificate-password: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          apple-notarization-key-p8: ${{ secrets.APPLE_NOTARIZATION_KEY_P8 }}
+          apple-notarization-key-id: ${{ secrets.APPLE_NOTARIZATION_KEY_ID }}
+          apple-notarization-issuer-id: ${{ secrets.APPLE_NOTARIZATION_ISSUER_ID }}
+
+      - if: ${{ runner.os == 'macOS' }}
+        name: Build macOS dmg
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          target="${{ matrix.target }}"
+          release_dir="target/${target}/release"
+          dmg_root="${RUNNER_TEMP}/codex-dmg-root"
+          volname="Codex (${target})"
+          dmg_path="${release_dir}/codex-${target}.dmg"
+
+          # The previous "MacOS code signing (binaries)" step signs + notarizes the
+          # built artifacts in `${release_dir}`. This step packages *those same*
+          # signed binaries into a dmg.
+          codex_binary_path="${release_dir}/codex"
+          proxy_binary_path="${release_dir}/codex-responses-api-proxy"
+
+          rm -rf "$dmg_root"
+          mkdir -p "$dmg_root"
+
+          if [[ ! -f "$codex_binary_path" ]]; then
+            echo "Binary $codex_binary_path not found"
+            exit 1
+          fi
+          if [[ ! -f "$proxy_binary_path" ]]; then
+            echo "Binary $proxy_binary_path not found"
+            exit 1
+          fi
+
+          ditto "$codex_binary_path" "${dmg_root}/codex"
+          ditto "$proxy_binary_path" "${dmg_root}/codex-responses-api-proxy"
+
+          rm -f "$dmg_path"
+          hdiutil create \
+            -volname "$volname" \
+            -srcfolder "$dmg_root" \
+            -format UDZO \
+            -ov \
+            "$dmg_path"
+
+          if [[ ! -f "$dmg_path" ]]; then
+            echo "dmg $dmg_path not found after build"
+            exit 1
+          fi
+
+      - if: ${{ runner.os == 'macOS' }}
+        name: MacOS code signing (dmg)
+        uses: ./.github/actions/macos-code-sign
+        with:
+          target: ${{ matrix.target }}
+          sign-binaries: "false"
+          sign-dmg: "true"
           apple-certificate: ${{ secrets.APPLE_CERTIFICATE_P12 }}
           apple-certificate-password: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
           apple-notarization-key-p8: ${{ secrets.APPLE_NOTARIZATION_KEY_P8 }}
@@ -160,6 +221,10 @@ jobs:
             cp target/${{ matrix.target }}/release/codex-responses-api-proxy.sigstore "$dest/codex-responses-api-proxy-${{ matrix.target }}.sigstore"
           fi
 
+          if [[ "${{ matrix.target }}" == *apple-darwin ]]; then
+            cp target/${{ matrix.target }}/release/codex-${{ matrix.target }}.dmg "$dest/codex-${{ matrix.target }}.dmg"
+          fi
+
       - if: ${{ matrix.runner == 'windows-11-arm' }}
         name: Install zstd
         shell: powershell
@@ -194,7 +259,7 @@ jobs:
             base="$(basename "$f")"
             # Skip files that are already archives (shouldn't happen, but be
             # safe).
-            if [[ "$base" == *.tar.gz || "$base" == *.zip ]]; then
+            if [[ "$base" == *.tar.gz || "$base" == *.zip || "$base" == *.dmg ]]; then
               continue
             fi
 

.gitignore

@@ -85,3 +85,8 @@ CHANGELOG.ignore.md
 # nix related
 .direnv
 .envrc
+
+# Python bytecode files
+__pycache__/
+*.pyc
+

codex-rs/Cargo.lock

@@ -1000,6 +1000,7 @@ dependencies = [
  "codex-login",
  "codex-protocol",
  "codex-rmcp-client",
+ "codex-utils-absolute-path",
  "codex-utils-json-to-toml",
  "core_test_support",
  "mcp-types",
@@ -1243,6 +1244,8 @@ dependencies = [
  "codex-lmstudio",
  "codex-ollama",
  "codex-protocol",
+ "codex-utils-absolute-path",
+ "pretty_assertions",
  "serde",
  "toml 0.9.5",
 ]
@@ -1290,6 +1293,7 @@ dependencies = [
  "futures",
  "http 1.3.1",
  "image",
+ "include_dir",
  "indexmap 2.12.0",
  "keyring",
  "landlock",
@@ -1314,14 +1318,12 @@ dependencies = [
  "sha2",
  "shlex",
  "similar",
- "strum_macros 0.27.2",
  "tempfile",
  "test-case",
  "test-log",
  "thiserror 2.0.17",
  "time",
  "tokio",
- "tokio-test",
  "tokio-util",
  "toml 0.9.5",
  "toml_edit",
@@ -1912,6 +1914,7 @@ dependencies = [
  "codex-utils-absolute-path",
  "dirs-next",
  "dunce",
+ "pretty_assertions",
  "rand 0.8.5",
  "serde",
  "serde_json",
@@ -2204,6 +2207,16 @@ dependencies = [
  "darling_macro 0.21.3",
 ]
 
+[[package]]
+name = "darling"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d"
+dependencies = [
+ "darling_core 0.23.0",
+ "darling_macro 0.23.0",
+]
+
 [[package]]
 name = "darling_core"
 version = "0.20.11"
@@ -2232,6 +2245,19 @@ dependencies = [
  "syn 2.0.104",
 ]
 
+[[package]]
+name = "darling_core"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9865a50f7c335f53564bb694ef660825eb8610e0a53d3e11bf1b0d3df31e03b0"
+dependencies = [
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim 0.11.1",
+ "syn 2.0.104",
+]
+
 [[package]]
 name = "darling_macro"
 version = "0.20.11"
@@ -2254,6 +2280,17 @@ dependencies = [
  "syn 2.0.104",
 ]
 
+[[package]]
+name = "darling_macro"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d"
+dependencies = [
+ "darling_core 0.23.0",
+ "quote",
+ "syn 2.0.104",
+]
+
 [[package]]
 name = "dbus"
 version = "0.9.9"
@@ -3365,7 +3402,7 @@ dependencies = [
  "libc",
  "percent-encoding",
  "pin-project-lite",
- "socket2 0.5.10",
+ "socket2 0.6.1",
  "system-configuration",
  "tokio",
  "tower-service",
@@ -3588,6 +3625,25 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e8a5a9a0ff0086c7a148acb942baaabeadf9504d10400b5a05645853729b9cd2"
 
+[[package]]
+name = "include_dir"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "923d117408f1e49d914f1a379a309cffe4f18c05cf4e3d12e613a15fc81bd0dd"
+dependencies = [
+ "include_dir_macros",
+]
+
+[[package]]
+name = "include_dir_macros"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7cab85a7ed0bd5f0e76d93846e0147172bed2e2d3f859bcc33a8d9699cad1a75"
+dependencies = [
+ "proc-macro2",
+ "quote",
+]
+
 [[package]]
 name = "indenter"
 version = "0.3.3"
@@ -5051,9 +5107,9 @@ dependencies = [
 
 [[package]]
 name = "process-wrap"
-version = "8.2.1"
+version = "9.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a3ef4f2f0422f23a82ec9f628ea2acd12871c81a9362b02c43c1aa86acfc3ba1"
+checksum = "5e5fd83ab7fa55fd06f5e665e3fc52b8bca451c0486b8ea60ad649cd1c10a5da"
 dependencies = [
  "futures",
  "indexmap 2.12.0",
@@ -5151,7 +5207,7 @@ dependencies = [
  "quinn-udp",
  "rustc-hash",
  "rustls",
- "socket2 0.5.10",
+ "socket2 0.6.1",
  "thiserror 2.0.17",
  "tokio",
  "tracing",
@@ -5188,7 +5244,7 @@ dependencies = [
  "cfg_aliases 0.2.1",
  "libc",
  "once_cell",
- "socket2 0.5.10",
+ "socket2 0.6.1",
  "tracing",
  "windows-sys 0.60.2",
 ]
@@ -5463,9 +5519,9 @@ dependencies = [
 
 [[package]]
 name = "rmcp"
-version = "0.10.0"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "38b18323edc657390a6ed4d7a9110b0dec2dc3ed128eb2a123edfbafabdbddc5"
+checksum = "528d42f8176e6e5e71ea69182b17d1d0a19a6b3b894b564678b74cd7cab13cfa"
 dependencies = [
  "async-trait",
  "base64",
@@ -5498,11 +5554,11 @@ dependencies = [
 
 [[package]]
 name = "rmcp-macros"
-version = "0.10.0"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c75d0a62676bf8c8003c4e3c348e2ceb6a7b3e48323681aaf177fdccdac2ce50"
+checksum = "e3f81daaa494eb8e985c9462f7d6ce1ab05e5299f48aafd76cdd3d8b060e6f59"
 dependencies = [
- "darling 0.21.3",
+ "darling 0.23.0",
  "proc-macro2",
  "quote",
  "serde_json",

codex-rs/Cargo.toml

@@ -141,6 +141,7 @@ icu_locale_core = "2.1"
 icu_provider = { version = "2.1", features = ["sync"] }
 ignore = "0.4.23"
 image = { version = "^0.25.9", default-features = false }
+include_dir = "0.7.4"
 indexmap = "2.12.0"
 insta = "1.44.3"
 itertools = "0.14.0"
@@ -177,7 +178,7 @@ ratatui-macros = "0.6.0"
 regex = "1.12.2"
 regex-lite = "0.1.7"
 reqwest = "0.12"
-rmcp = { version = "0.10.0", default-features = false }
+rmcp = { version = "0.12.0", default-features = false }
 schemars = "0.8.22"
 seccompiler = "0.5.0"
 sentry = "0.46.0"

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -539,6 +539,7 @@ server_notification_definitions! {
     ReasoningSummaryPartAdded => "item/reasoning/summaryPartAdded" (v2::ReasoningSummaryPartAddedNotification),
     ReasoningTextDelta => "item/reasoning/textDelta" (v2::ReasoningTextDeltaNotification),
     ContextCompacted => "thread/compacted" (v2::ContextCompactedNotification),
+    DeprecationNotice => "deprecationNotice" (v2::DeprecationNoticeNotification),
 
     /// Notifies the user of world-writable directories on Windows, which cannot be protected by the sandbox.
     WindowsWorldWritableWarning => "windows/worldWritableWarning" (v2::WindowsWorldWritableWarningNotification),

codex-rs/app-server-protocol/src/protocol/v2.rs

@@ -18,6 +18,7 @@ use codex_protocol::plan_tool::StepStatus as CorePlanStepStatus;
 use codex_protocol::protocol::AskForApproval as CoreAskForApproval;
 use codex_protocol::protocol::CodexErrorInfo as CoreCodexErrorInfo;
 use codex_protocol::protocol::CreditsSnapshot as CoreCreditsSnapshot;
+use codex_protocol::protocol::NetworkAccess as CoreNetworkAccess;
 use codex_protocol::protocol::RateLimitSnapshot as CoreRateLimitSnapshot;
 use codex_protocol::protocol::RateLimitWindow as CoreRateLimitWindow;
 use codex_protocol::protocol::SessionSource as CoreSessionSource;
@@ -208,14 +209,72 @@ v2_enum_from_core!(
     }
 );
 
+// TODO(mbolin): Support in-repo layer.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
-#[serde(rename_all = "camelCase")]
+#[serde(tag = "type", rename_all = "camelCase")]
+#[ts(tag = "type")]
 #[ts(export_to = "v2/")]
-pub enum ConfigLayerName {
-    Mdm,
-    System,
+pub enum ConfigLayerSource {
+    /// Managed preferences layer delivered by MDM (macOS only).
+    #[serde(rename_all = "camelCase")]
+    #[ts(rename_all = "camelCase")]
+    Mdm {
+        domain: String,
+        key: String,
+    },
+
+    /// Managed config layer from a file (usually `managed_config.toml`).
+    #[serde(rename_all = "camelCase")]
+    #[ts(rename_all = "camelCase")]
+    System {
+        file: AbsolutePathBuf,
+    },
+
+    /// User config layer from $CODEX_HOME/config.toml. This layer is special
+    /// in that it is expected to be:
+    /// - writable by the user
+    /// - generally outside the workspace directory
+    #[serde(rename_all = "camelCase")]
+    #[ts(rename_all = "camelCase")]
+    User {
+        file: AbsolutePathBuf,
+    },
+
+    /// Session-layer overrides supplied via `-c`/`--config`.
     SessionFlags,
-    User,
+
+    /// `managed_config.toml` was designed to be a config that was loaded
+    /// as the last layer on top of everything else. This scheme did not quite
+    /// work out as intended, but we keep this variant as a "best effort" while
+    /// we phase out `managed_config.toml` in favor of `requirements.toml`.
+    LegacyManagedConfigTomlFromFile {
+        file: AbsolutePathBuf,
+    },
+
+    LegacyManagedConfigTomlFromMdm,
+}
+
+impl ConfigLayerSource {
+    /// A settings from a layer with a higher precedence will override a setting
+    /// from a layer with a lower precedence.
+    pub fn precedence(&self) -> i16 {
+        match self {
+            ConfigLayerSource::Mdm { .. } => 0,
+            ConfigLayerSource::System { .. } => 10,
+            ConfigLayerSource::User { .. } => 20,
+            ConfigLayerSource::SessionFlags => 30,
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile { .. } => 40,
+            ConfigLayerSource::LegacyManagedConfigTomlFromMdm => 50,
+        }
+    }
+}
+
+/// Compares [ConfigLayerSource] by precedence, so `A < B` means settings from
+/// layer `A` will be overridden by settings from layer `B`.
+impl PartialOrd for ConfigLayerSource {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.precedence().cmp(&other.precedence()))
+    }
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema, TS)]
@@ -288,8 +347,7 @@ pub struct Config {
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
 pub struct ConfigLayerMetadata {
-    pub name: ConfigLayerName,
-    pub source: String,
+    pub name: ConfigLayerSource,
     pub version: String,
 }
 
@@ -297,8 +355,7 @@ pub struct ConfigLayerMetadata {
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
 pub struct ConfigLayer {
-    pub name: ConfigLayerName,
-    pub source: String,
+    pub name: ConfigLayerSource,
     pub version: String,
     pub config: JsonValue,
 }
@@ -335,7 +392,7 @@ pub struct ConfigWriteResponse {
     pub status: WriteStatus,
     pub version: String,
     /// Canonical path to the config file that was written.
-    pub file_path: String,
+    pub file_path: AbsolutePathBuf,
     pub overridden_metadata: Option<OverriddenMetadata>,
 }
 
@@ -348,6 +405,7 @@ pub enum ConfigWriteErrorCode {
     ConfigValidationError,
     ConfigPathNotFound,
     ConfigSchemaUnknownKey,
+    UserLayerNotFound,
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
@@ -413,6 +471,15 @@ pub enum ApprovalDecision {
     Cancel,
 }
 
+#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub enum NetworkAccess {
+    #[default]
+    Restricted,
+    Enabled,
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
 #[serde(tag = "type", rename_all = "camelCase")]
 #[ts(tag = "type")]
@@ -422,6 +489,12 @@ pub enum SandboxPolicy {
     ReadOnly,
     #[serde(rename_all = "camelCase")]
     #[ts(rename_all = "camelCase")]
+    ExternalSandbox {
+        #[serde(default)]
+        network_access: NetworkAccess,
+    },
+    #[serde(rename_all = "camelCase")]
+    #[ts(rename_all = "camelCase")]
     WorkspaceWrite {
         #[serde(default)]
         writable_roots: Vec<AbsolutePathBuf>,
@@ -441,6 +514,14 @@ impl SandboxPolicy {
                 codex_protocol::protocol::SandboxPolicy::DangerFullAccess
             }
             SandboxPolicy::ReadOnly => codex_protocol::protocol::SandboxPolicy::ReadOnly,
+            SandboxPolicy::ExternalSandbox { network_access } => {
+                codex_protocol::protocol::SandboxPolicy::ExternalSandbox {
+                    network_access: match network_access {
+                        NetworkAccess::Restricted => CoreNetworkAccess::Restricted,
+                        NetworkAccess::Enabled => CoreNetworkAccess::Enabled,
+                    },
+                }
+            }
             SandboxPolicy::WorkspaceWrite {
                 writable_roots,
                 network_access,
@@ -463,6 +544,14 @@ impl From<codex_protocol::protocol::SandboxPolicy> for SandboxPolicy {
                 SandboxPolicy::DangerFullAccess
             }
             codex_protocol::protocol::SandboxPolicy::ReadOnly => SandboxPolicy::ReadOnly,
+            codex_protocol::protocol::SandboxPolicy::ExternalSandbox { network_access } => {
+                SandboxPolicy::ExternalSandbox {
+                    network_access: match network_access {
+                        CoreNetworkAccess::Restricted => NetworkAccess::Restricted,
+                        CoreNetworkAccess::Enabled => NetworkAccess::Enabled,
+                    },
+                }
+            }
             codex_protocol::protocol::SandboxPolicy::WorkspaceWrite {
                 writable_roots,
                 network_access,
@@ -971,6 +1060,10 @@ pub struct SkillsListParams {
     /// When empty, defaults to the current session working directory.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub cwds: Vec<PathBuf>,
+
+    /// When true, bypass the skills cache and re-scan skills from disk.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub force_reload: bool,
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
@@ -987,6 +1080,8 @@ pub struct SkillsListResponse {
 pub enum SkillScope {
     User,
     Repo,
+    System,
+    Admin,
 }
 
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
@@ -995,6 +1090,9 @@ pub enum SkillScope {
 pub struct SkillMetadata {
     pub name: String,
     pub description: String,
+    #[ts(optional)]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub short_description: Option<String>,
     pub path: PathBuf,
     pub scope: SkillScope,
 }
@@ -1021,6 +1119,7 @@ impl From<CoreSkillMetadata> for SkillMetadata {
         Self {
             name: value.name,
             description: value.description,
+            short_description: value.short_description,
             path: value.path,
             scope: value.scope.into(),
         }
@@ -1032,6 +1131,8 @@ impl From<CoreSkillScope> for SkillScope {
         match value {
             CoreSkillScope::User => Self::User,
             CoreSkillScope::Repo => Self::Repo,
+            CoreSkillScope::System => Self::System,
+            CoreSkillScope::Admin => Self::Admin,
         }
     }
 }
@@ -1830,6 +1931,16 @@ pub struct AccountLoginCompletedNotification {
     pub error: Option<String>,
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct DeprecationNoticeNotification {
+    /// Concise summary of what is deprecated.
+    pub summary: String,
+    /// Optional extra guidance, such as migration steps or rationale.
+    pub details: Option<String>,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1839,11 +1950,30 @@ mod tests {
     use codex_protocol::items::TurnItem;
     use codex_protocol::items::UserMessageItem;
     use codex_protocol::items::WebSearchItem;
+    use codex_protocol::protocol::NetworkAccess as CoreNetworkAccess;
     use codex_protocol::user_input::UserInput as CoreUserInput;
     use pretty_assertions::assert_eq;
     use serde_json::json;
     use std::path::PathBuf;
 
+    #[test]
+    fn sandbox_policy_round_trips_external_sandbox_network_access() {
+        let v2_policy = SandboxPolicy::ExternalSandbox {
+            network_access: NetworkAccess::Enabled,
+        };
+
+        let core_policy = v2_policy.to_core();
+        assert_eq!(
+            core_policy,
+            codex_protocol::protocol::SandboxPolicy::ExternalSandbox {
+                network_access: CoreNetworkAccess::Enabled,
+            }
+        );
+
+        let back_to_v2 = SandboxPolicy::from(core_policy);
+        assert_eq!(back_to_v2, v2_policy);
+    }
+
     #[test]
     fn core_turn_item_into_thread_item_converts_supported_variants() {
         let user_item = TurnItem::UserMessage(UserMessageItem {
@@ -1928,6 +2058,30 @@ mod tests {
         );
     }
 
+    #[test]
+    fn skills_list_params_serialization_uses_force_reload() {
+        assert_eq!(
+            serde_json::to_value(SkillsListParams {
+                cwds: Vec::new(),
+                force_reload: false,
+            })
+            .unwrap(),
+            json!({}),
+        );
+
+        assert_eq!(
+            serde_json::to_value(SkillsListParams {
+                cwds: vec![PathBuf::from("/repo")],
+                force_reload: true,
+            })
+            .unwrap(),
+            json!({
+                "cwds": ["/repo"],
+                "forceReload": true,
+            }),
+        );
+    }
+
     #[test]
     fn codex_error_info_serializes_http_status_code_in_camel_case() {
         let value = CodexErrorInfo::ResponseTooManyFailedAttempts {

codex-rs/app-server/Cargo.toml

@@ -27,6 +27,7 @@ codex-protocol = { workspace = true }
 codex-app-server-protocol = { workspace = true }
 codex-feedback = { workspace = true }
 codex-rmcp-client = { workspace = true }
+codex-utils-absolute-path = { workspace = true }
 codex-utils-json-to-toml = { workspace = true }
 chrono = { workspace = true }
 serde = { workspace = true, features = ["derive"] }

codex-rs/app-server/README.md

@@ -77,7 +77,7 @@ Example (from OpenAI's official VSCode extension):
 - `review/start` — kick off Codex’s automated reviewer for a thread; responds like `turn/start` and emits `item/started`/`item/completed` notifications with `enteredReviewMode` and `exitedReviewMode` items, plus a final assistant `agentMessage` containing the review.
 - `command/exec` — run a single command under the server sandbox without starting a thread/turn (handy for utilities and validation).
 - `model/list` — list available models (with reasoning effort options).
-- `skills/list` — list skills for one or more `cwd` values.
+- `skills/list` — list skills for one or more `cwd` values (optional `forceReload`).
 - `mcpServer/oauth/login` — start an OAuth login for a configured MCP server; returns an `authorization_url` and later emits `mcpServer/oauthLogin/completed` once the browser flow finishes.
 - `mcpServerStatus/list` — enumerate configured MCP servers with their tools, resources, resource templates, and auth status; supports cursor+limit pagination.
 - `feedback/upload` — submit a feedback report (classification + optional reason/logs and conversation_id); returns the tracking thread id.
@@ -172,7 +172,7 @@ You can optionally specify config overrides on the new turn. If specified, these
     "cwd": "/Users/me/project",
     "approvalPolicy": "unlessTrusted",
     "sandboxPolicy": {
-        "mode": "workspaceWrite",
+        "type": "workspaceWrite",
         "writableRoots": ["/Users/me/project"],
         "networkAccess": true
     },
@@ -285,10 +285,12 @@ Run a standalone command (argv vector) in the server’s sandbox without creatin
 { "id": 32, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }
 ```
 
+- For clients that are already sandboxed externally, set `sandboxPolicy` to `{"type":"externalSandbox","networkAccess":"enabled"}` (or omit `networkAccess` to keep it restricted). Codex will not enforce its own sandbox in this mode; it tells the model it has full file-system access and passes the `networkAccess` state through `environment_context`.
+
 Notes:
 
 - Empty `command` arrays are rejected.
-- `sandboxPolicy` accepts the same shape used by `turn/start` (e.g., `dangerFullAccess`, `readOnly`, `workspaceWrite` with flags).
+- `sandboxPolicy` accepts the same shape used by `turn/start` (e.g., `dangerFullAccess`, `readOnly`, `workspaceWrite` with flags, `externalSandbox` with `networkAccess` `restricted|enabled`).
 - When omitted, `timeoutMs` falls back to the server default.
 
 ## Events

codex-rs/app-server/src/bespoke_event_handling.rs

@@ -15,6 +15,7 @@ use codex_app_server_protocol::CommandExecutionRequestApprovalParams;
 use codex_app_server_protocol::CommandExecutionRequestApprovalResponse;
 use codex_app_server_protocol::CommandExecutionStatus;
 use codex_app_server_protocol::ContextCompactedNotification;
+use codex_app_server_protocol::DeprecationNoticeNotification;
 use codex_app_server_protocol::ErrorNotification;
 use codex_app_server_protocol::ExecCommandApprovalParams;
 use codex_app_server_protocol::ExecCommandApprovalResponse;
@@ -283,6 +284,15 @@ pub(crate) async fn apply_bespoke_event_handling(
                 .send_server_notification(ServerNotification::ContextCompacted(notification))
                 .await;
         }
+        EventMsg::DeprecationNotice(event) => {
+            let notification = DeprecationNoticeNotification {
+                summary: event.summary,
+                details: event.details,
+            };
+            outgoing
+                .send_server_notification(ServerNotification::DeprecationNotice(notification))
+                .await;
+        }
         EventMsg::ReasoningContentDelta(event) => {
             let notification = ReasoningSummaryTextDeltaNotification {
                 thread_id: conversation_id.to_string(),

codex-rs/app-server/src/codex_message_processor.rs

@@ -282,7 +282,7 @@ impl CodexMessageProcessor {
     }
 
     async fn load_latest_config(&self) -> Result<Config, JSONRPCErrorError> {
-        Config::load_with_cli_overrides(self.cli_overrides.clone(), ConfigOverrides::default())
+        Config::load_with_cli_overrides(self.cli_overrides.clone())
             .await
             .map_err(|err| JSONRPCErrorError {
                 code: INTERNAL_ERROR_CODE,
@@ -393,7 +393,14 @@ impl CodexMessageProcessor {
                 self.handle_list_conversations(request_id, params).await;
             }
             ClientRequest::ModelList { request_id, params } => {
-                self.list_models(request_id, params).await;
+                let outgoing = self.outgoing.clone();
+                let conversation_manager = self.conversation_manager.clone();
+                let config = self.config.clone();
+
+                tokio::spawn(async move {
+                    Self::list_models(outgoing, conversation_manager, config, request_id, params)
+                        .await;
+                });
             }
             ClientRequest::McpServerOauthLogin { request_id, params } => {
                 self.mcp_server_oauth_login(request_id, params).await;
@@ -1896,9 +1903,17 @@ impl CodexMessageProcessor {
         Ok((items, next_cursor))
     }
 
-    async fn list_models(&self, request_id: RequestId, params: ModelListParams) {
+    async fn list_models(
+        outgoing: Arc<OutgoingMessageSender>,
+        conversation_manager: Arc<ConversationManager>,
+        config: Arc<Config>,
+        request_id: RequestId,
+        params: ModelListParams,
+    ) {
         let ModelListParams { limit, cursor } = params;
-        let models = supported_models(self.conversation_manager.clone(), &self.config).await;
+        let mut config = (*config).clone();
+        config.features.enable(Feature::RemoteModels);
+        let models = supported_models(conversation_manager, &config).await;
         let total = models.len();
 
         if total == 0 {
@@ -1906,7 +1921,7 @@ impl CodexMessageProcessor {
                 data: Vec::new(),
                 next_cursor: None,
             };
-            self.outgoing.send_response(request_id, response).await;
+            outgoing.send_response(request_id, response).await;
             return;
         }
 
@@ -1921,7 +1936,7 @@ impl CodexMessageProcessor {
                         message: format!("invalid cursor: {cursor}"),
                         data: None,
                     };
-                    self.outgoing.send_error(request_id, error).await;
+                    outgoing.send_error(request_id, error).await;
                     return;
                 }
             },
@@ -1934,7 +1949,7 @@ impl CodexMessageProcessor {
                 message: format!("cursor {start} exceeds total models {total}"),
                 data: None,
             };
-            self.outgoing.send_error(request_id, error).await;
+            outgoing.send_error(request_id, error).await;
             return;
         }
 
@@ -1949,7 +1964,7 @@ impl CodexMessageProcessor {
             data: items,
             next_cursor,
         };
-        self.outgoing.send_response(request_id, response).await;
+        outgoing.send_response(request_id, response).await;
     }
 
     async fn mcp_server_oauth_login(
@@ -2061,6 +2076,7 @@ impl CodexMessageProcessor {
         request_id: RequestId,
         params: ListMcpServerStatusParams,
     ) {
+        let outgoing = Arc::clone(&self.outgoing);
         let config = match self.load_latest_config().await {
             Ok(config) => config,
             Err(error) => {
@@ -2069,6 +2085,17 @@ impl CodexMessageProcessor {
             }
         };
 
+        tokio::spawn(async move {
+            Self::list_mcp_server_status_task(outgoing, request_id, params, config).await;
+        });
+    }
+
+    async fn list_mcp_server_status_task(
+        outgoing: Arc<OutgoingMessageSender>,
+        request_id: RequestId,
+        params: ListMcpServerStatusParams,
+        config: Config,
+    ) {
         let snapshot = collect_mcp_snapshot(&config).await;
 
         let tools_by_server = group_tools_by_server(&snapshot.tools);
@@ -2096,7 +2123,7 @@ impl CodexMessageProcessor {
                         message: format!("invalid cursor: {cursor}"),
                         data: None,
                     };
-                    self.outgoing.send_error(request_id, error).await;
+                    outgoing.send_error(request_id, error).await;
                     return;
                 }
             },
@@ -2109,7 +2136,7 @@ impl CodexMessageProcessor {
                 message: format!("cursor {start} exceeds total MCP servers {total}"),
                 data: None,
             };
-            self.outgoing.send_error(request_id, error).await;
+            outgoing.send_error(request_id, error).await;
             return;
         }
 
@@ -2143,7 +2170,7 @@ impl CodexMessageProcessor {
 
         let response = ListMcpServerStatusResponse { data, next_cursor };
 
-        self.outgoing.send_response(request_id, response).await;
+        outgoing.send_response(request_id, response).await;
     }
 
     async fn handle_resume_conversation(
@@ -2613,36 +2640,27 @@ impl CodexMessageProcessor {
     }
 
     async fn skills_list(&self, request_id: RequestId, params: SkillsListParams) {
-        let SkillsListParams { cwds } = params;
+        let SkillsListParams { cwds, force_reload } = params;
         let cwds = if cwds.is_empty() {
             vec![self.config.cwd.clone()]
         } else {
             cwds
         };
 
-        let data = if self.config.features.enabled(Feature::Skills) {
-            let skills_manager = self.conversation_manager.skills_manager();
-            cwds.into_iter()
-                .map(|cwd| {
-                    let outcome = skills_manager.skills_for_cwd(&cwd);
-                    let errors = errors_to_info(&outcome.errors);
-                    let skills = skills_to_info(&outcome.skills);
-                    codex_app_server_protocol::SkillsListEntry {
-                        cwd,
-                        skills,
-                        errors,
-                    }
-                })
-                .collect()
-        } else {
-            cwds.into_iter()
-                .map(|cwd| codex_app_server_protocol::SkillsListEntry {
+        let skills_manager = self.conversation_manager.skills_manager();
+        let data = cwds
+            .into_iter()
+            .map(|cwd| {
+                let outcome = skills_manager.skills_for_cwd_with_options(&cwd, force_reload);
+                let errors = errors_to_info(&outcome.errors);
+                let skills = skills_to_info(&outcome.skills);
+                codex_app_server_protocol::SkillsListEntry {
                     cwd,
-                    skills: Vec::new(),
-                    errors: Vec::new(),
-                })
-                .collect()
-        };
+                    skills,
+                    errors,
+                }
+            })
+            .collect();
         self.outgoing
             .send_response(request_id, SkillsListResponse { data })
             .await;
@@ -3301,6 +3319,7 @@ fn skills_to_info(
         .map(|skill| codex_app_server_protocol::SkillMetadata {
             name: skill.name.clone(),
             description: skill.description.clone(),
+            short_description: skill.short_description.clone(),
             path: skill.path.clone(),
             scope: skill.scope.into(),
         })
@@ -3321,7 +3340,7 @@ fn errors_to_info(
 
 async fn derive_config_from_params(
     overrides: ConfigOverrides,
-    cli_overrides: Option<std::collections::HashMap<String, serde_json::Value>>,
+    cli_overrides: Option<HashMap<String, serde_json::Value>>,
 ) -> std::io::Result<Config> {
     let cli_overrides = cli_overrides
         .unwrap_or_default()
@@ -3329,7 +3348,7 @@ async fn derive_config_from_params(
         .map(|(k, v)| (k, json_to_toml(v)))
         .collect();
 
-    Config::load_with_cli_overrides(cli_overrides, overrides).await
+    Config::load_with_cli_overrides_and_harness_overrides(cli_overrides, overrides).await
 }
 
 async fn read_summary_from_rollout(

codex-rs/app-server/src/lib.rs

@@ -2,7 +2,6 @@
 
 use codex_common::CliConfigOverrides;
 use codex_core::config::Config;
-use codex_core::config::ConfigOverrides;
 use std::io::ErrorKind;
 use std::io::Result as IoResult;
 use std::path::PathBuf;
@@ -81,12 +80,11 @@ pub async fn run_main(
             format!("error parsing -c overrides: {e}"),
         )
     })?;
-    let config =
-        Config::load_with_cli_overrides(cli_kv_overrides.clone(), ConfigOverrides::default())
-            .await
-            .map_err(|e| {
-                std::io::Error::new(ErrorKind::InvalidData, format!("error loading config: {e}"))
-            })?;
+    let config = Config::load_with_cli_overrides(cli_kv_overrides.clone())
+        .await
+        .map_err(|e| {
+            std::io::Error::new(ErrorKind::InvalidData, format!("error loading config: {e}"))
+        })?;
 
     let feedback = CodexFeedback::new();
 

codex-rs/app-server/tests/common/models_cache.rs

@@ -42,6 +42,7 @@ fn preset_to_info(preset: &ModelPreset, priority: i32) -> ModelInfo {
     }
 }
 
+// todo(aibrahim): fix the priorities to be the opposite here.
 /// Write a models_cache.json file to the codex home directory.
 /// This prevents ModelsManager from making network requests to refresh models.
 /// The cache will be treated as fresh (within TTL) and used instead of fetching from the network.

codex-rs/app-server/tests/suite/user_agent.rs

@@ -25,12 +25,13 @@ async fn get_user_agent_returns_current_codex_user_agent() -> Result<()> {
     .await??;
 
     let os_info = os_info::get();
+    let originator = codex_core::default_client::originator().value.as_str();
+    let os_type = os_info.os_type();
+    let os_version = os_info.version();
+    let architecture = os_info.architecture().unwrap_or("unknown");
+    let terminal_ua = codex_core::terminal::user_agent();
     let user_agent = format!(
-        "codex_cli_rs/0.0.0 ({} {}; {}) {} (codex-app-server-tests; 0.1.0)",
-        os_info.os_type(),
-        os_info.version(),
-        os_info.architecture().unwrap_or("unknown"),
-        codex_core::terminal::user_agent()
+        "{originator}/0.0.0 ({os_type} {os_version}; {architecture}) {terminal_ua} (codex-app-server-tests; 0.1.0)"
     );
 
     let received: GetUserAgentResponse = to_response(response)?;

codex-rs/app-server/tests/suite/v2/config_rpc.rs

@@ -6,7 +6,7 @@ use app_test_support::to_response;
 use codex_app_server_protocol::AskForApproval;
 use codex_app_server_protocol::ConfigBatchWriteParams;
 use codex_app_server_protocol::ConfigEdit;
-use codex_app_server_protocol::ConfigLayerName;
+use codex_app_server_protocol::ConfigLayerSource;
 use codex_app_server_protocol::ConfigReadParams;
 use codex_app_server_protocol::ConfigReadResponse;
 use codex_app_server_protocol::ConfigValueWriteParams;
@@ -18,6 +18,7 @@ use codex_app_server_protocol::RequestId;
 use codex_app_server_protocol::SandboxMode;
 use codex_app_server_protocol::ToolsV2;
 use codex_app_server_protocol::WriteStatus;
+use codex_utils_absolute_path::AbsolutePathBuf;
 use pretty_assertions::assert_eq;
 use serde_json::json;
 use tempfile::TempDir;
@@ -42,6 +43,8 @@ model = "gpt-user"
 sandbox_mode = "workspace-write"
 "#,
     )?;
+    let codex_home_path = codex_home.path().canonicalize()?;
+    let user_file = AbsolutePathBuf::try_from(codex_home_path.join("config.toml"))?;
 
     let mut mcp = McpProcess::new(codex_home.path()).await?;
     timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
@@ -65,12 +68,13 @@ sandbox_mode = "workspace-write"
     assert_eq!(config.model.as_deref(), Some("gpt-user"));
     assert_eq!(
         origins.get("model").expect("origin").name,
-        ConfigLayerName::User
+        ConfigLayerSource::User {
+            file: user_file.clone(),
+        }
     );
     let layers = layers.expect("layers present");
-    assert_eq!(layers.len(), 2);
-    assert_eq!(layers[0].name, ConfigLayerName::SessionFlags);
-    assert_eq!(layers[1].name, ConfigLayerName::User);
+    assert_eq!(layers.len(), 1);
+    assert_eq!(layers[0].name, ConfigLayerSource::User { file: user_file });
 
     Ok(())
 }
@@ -88,6 +92,8 @@ web_search = true
 view_image = false
 "#,
     )?;
+    let codex_home_path = codex_home.path().canonicalize()?;
+    let user_file = AbsolutePathBuf::try_from(codex_home_path.join("config.toml"))?;
 
     let mut mcp = McpProcess::new(codex_home.path()).await?;
     timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
@@ -118,17 +124,20 @@ view_image = false
     );
     assert_eq!(
         origins.get("tools.web_search").expect("origin").name,
-        ConfigLayerName::User
+        ConfigLayerSource::User {
+            file: user_file.clone(),
+        }
     );
     assert_eq!(
         origins.get("tools.view_image").expect("origin").name,
-        ConfigLayerName::User
+        ConfigLayerSource::User {
+            file: user_file.clone(),
+        }
     );
 
     let layers = layers.expect("layers present");
-    assert_eq!(layers.len(), 2);
-    assert_eq!(layers[0].name, ConfigLayerName::SessionFlags);
-    assert_eq!(layers[1].name, ConfigLayerName::User);
+    assert_eq!(layers.len(), 1);
+    assert_eq!(layers[0].name, ConfigLayerSource::User { file: user_file });
 
     Ok(())
 }
@@ -153,8 +162,11 @@ network_access = true
             serde_json::json!(user_dir)
         ),
     )?;
+    let codex_home_path = codex_home.path().canonicalize()?;
+    let user_file = AbsolutePathBuf::try_from(codex_home_path.join("config.toml"))?;
 
     let managed_path = codex_home.path().join("managed_config.toml");
+    let managed_file = AbsolutePathBuf::try_from(managed_path.clone())?;
     std::fs::write(
         &managed_path,
         format!(
@@ -197,19 +209,25 @@ writable_roots = [{}]
     assert_eq!(config.model.as_deref(), Some("gpt-system"));
     assert_eq!(
         origins.get("model").expect("origin").name,
-        ConfigLayerName::System
+        ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+            file: managed_file.clone(),
+        }
     );
 
     assert_eq!(config.approval_policy, Some(AskForApproval::Never));
     assert_eq!(
         origins.get("approval_policy").expect("origin").name,
-        ConfigLayerName::System
+        ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+            file: managed_file.clone(),
+        }
     );
 
     assert_eq!(config.sandbox_mode, Some(SandboxMode::WorkspaceWrite));
     assert_eq!(
         origins.get("sandbox_mode").expect("origin").name,
-        ConfigLayerName::User
+        ConfigLayerSource::User {
+            file: user_file.clone(),
+        }
     );
 
     let sandbox = config
@@ -222,7 +240,9 @@ writable_roots = [{}]
             .get("sandbox_workspace_write.writable_roots.0")
             .expect("origin")
             .name,
-        ConfigLayerName::System
+        ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+            file: managed_file.clone(),
+        }
     );
 
     assert!(sandbox.network_access);
@@ -231,29 +251,34 @@ writable_roots = [{}]
             .get("sandbox_workspace_write.network_access")
             .expect("origin")
             .name,
-        ConfigLayerName::User
+        ConfigLayerSource::User {
+            file: user_file.clone(),
+        }
     );
 
     let layers = layers.expect("layers present");
-    assert_eq!(layers.len(), 3);
-    assert_eq!(layers[0].name, ConfigLayerName::System);
-    assert_eq!(layers[1].name, ConfigLayerName::SessionFlags);
-    assert_eq!(layers[2].name, ConfigLayerName::User);
+    assert_eq!(layers.len(), 2);
+    assert_eq!(
+        layers[0].name,
+        ConfigLayerSource::LegacyManagedConfigTomlFromFile { file: managed_file }
+    );
+    assert_eq!(layers[1].name, ConfigLayerSource::User { file: user_file });
 
     Ok(())
 }
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn config_value_write_replaces_value() -> Result<()> {
-    let codex_home = TempDir::new()?;
+    let temp_dir = TempDir::new()?;
+    let codex_home = temp_dir.path().canonicalize()?;
     write_config(
-        &codex_home,
+        &temp_dir,
         r#"
 model = "gpt-old"
 "#,
     )?;
 
-    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    let mut mcp = McpProcess::new(&codex_home).await?;
     timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
 
     let read_id = mcp
@@ -284,13 +309,7 @@ model = "gpt-old"
     )
     .await??;
     let write: ConfigWriteResponse = to_response(write_resp)?;
-    let expected_file_path = codex_home
-        .path()
-        .join("config.toml")
-        .canonicalize()
-        .unwrap()
-        .display()
-        .to_string();
+    let expected_file_path = AbsolutePathBuf::resolve_path_against_base("config.toml", codex_home)?;
 
     assert_eq!(write.status, WriteStatus::Ok);
     assert_eq!(write.file_path, expected_file_path);
@@ -353,16 +372,17 @@ model = "gpt-old"
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn config_batch_write_applies_multiple_edits() -> Result<()> {
-    let codex_home = TempDir::new()?;
-    write_config(&codex_home, "")?;
+    let tmp_dir = TempDir::new()?;
+    let codex_home = tmp_dir.path().canonicalize()?;
+    write_config(&tmp_dir, "")?;
 
-    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    let mut mcp = McpProcess::new(&codex_home).await?;
     timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
 
     let writable_root = test_tmp_path_buf();
     let batch_id = mcp
         .send_config_batch_write_request(ConfigBatchWriteParams {
-            file_path: Some(codex_home.path().join("config.toml").display().to_string()),
+            file_path: Some(codex_home.join("config.toml").display().to_string()),
             edits: vec![
                 ConfigEdit {
                     key_path: "sandbox_mode".to_string(),
@@ -388,13 +408,7 @@ async fn config_batch_write_applies_multiple_edits() -> Result<()> {
     .await??;
     let batch_write: ConfigWriteResponse = to_response(batch_resp)?;
     assert_eq!(batch_write.status, WriteStatus::Ok);
-    let expected_file_path = codex_home
-        .path()
-        .join("config.toml")
-        .canonicalize()
-        .unwrap()
-        .display()
-        .to_string();
+    let expected_file_path = AbsolutePathBuf::resolve_path_against_base("config.toml", codex_home)?;
     assert_eq!(batch_write.file_path, expected_file_path);
 
     let read_id = mcp

codex-rs/app-server/tests/suite/v2/model_list.rs

@@ -47,75 +47,6 @@ async fn list_models_returns_all_models_with_large_limit() -> Result<()> {
     } = to_response::<ModelListResponse>(response)?;
 
     let expected_models = vec![
-        Model {
-            id: "gpt-5.1-codex-max".to_string(),
-            model: "gpt-5.1-codex-max".to_string(),
-            display_name: "gpt-5.1-codex-max".to_string(),
-            description: "Latest Codex-optimized flagship for deep and fast reasoning.".to_string(),
-            supported_reasoning_efforts: vec![
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::Low,
-                    description: "Fast responses with lighter reasoning".to_string(),
-                },
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::Medium,
-                    description: "Balances speed and reasoning depth for everyday tasks"
-                        .to_string(),
-                },
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::High,
-                    description: "Greater reasoning depth for complex problems".to_string(),
-                },
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::XHigh,
-                    description: "Extra high reasoning depth for complex problems".to_string(),
-                },
-            ],
-            default_reasoning_effort: ReasoningEffort::Medium,
-            is_default: true,
-        },
-        Model {
-            id: "gpt-5.1-codex".to_string(),
-            model: "gpt-5.1-codex".to_string(),
-            display_name: "gpt-5.1-codex".to_string(),
-            description: "Optimized for codex.".to_string(),
-            supported_reasoning_efforts: vec![
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::Low,
-                    description: "Fastest responses with limited reasoning".to_string(),
-                },
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::Medium,
-                    description: "Dynamically adjusts reasoning based on the task".to_string(),
-                },
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::High,
-                    description: "Maximizes reasoning depth for complex or ambiguous problems"
-                        .to_string(),
-                },
-            ],
-            default_reasoning_effort: ReasoningEffort::Medium,
-            is_default: false,
-        },
-        Model {
-            id: "gpt-5.1-codex-mini".to_string(),
-            model: "gpt-5.1-codex-mini".to_string(),
-            display_name: "gpt-5.1-codex-mini".to_string(),
-            description: "Optimized for codex. Cheaper, faster, but less capable.".to_string(),
-            supported_reasoning_efforts: vec![
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::Medium,
-                    description: "Dynamically adjusts reasoning based on the task".to_string(),
-                },
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::High,
-                    description: "Maximizes reasoning depth for complex or ambiguous problems"
-                        .to_string(),
-                },
-            ],
-            default_reasoning_effort: ReasoningEffort::Medium,
-            is_default: false,
-        },
         Model {
             id: "gpt-5.2".to_string(),
             model: "gpt-5.2".to_string(),
@@ -138,7 +69,7 @@ async fn list_models_returns_all_models_with_large_limit() -> Result<()> {
                 },
                 ReasoningEffortOption {
                     reasoning_effort: ReasoningEffort::High,
-                    description: "Greater reasoning depth for complex or ambiguous problems"
+                    description: "Maximizes reasoning depth for complex or ambiguous problems"
                         .to_string(),
                 },
                 ReasoningEffortOption {
@@ -147,25 +78,17 @@ async fn list_models_returns_all_models_with_large_limit() -> Result<()> {
                 },
             ],
             default_reasoning_effort: ReasoningEffort::Medium,
-            is_default: false,
+            is_default: true,
         },
         Model {
-            id: "gpt-5.1".to_string(),
-            model: "gpt-5.1".to_string(),
-            display_name: "gpt-5.1".to_string(),
-            description: "Broad world knowledge with strong general reasoning.".to_string(),
+            id: "gpt-5.1-codex-mini".to_string(),
+            model: "gpt-5.1-codex-mini".to_string(),
+            display_name: "gpt-5.1-codex-mini".to_string(),
+            description: "Optimized for codex. Cheaper, faster, but less capable.".to_string(),
             supported_reasoning_efforts: vec![
-                ReasoningEffortOption {
-                    reasoning_effort: ReasoningEffort::Low,
-                    description: "Balances speed with some reasoning; useful for straightforward \
-                                   queries and short explanations"
-                        .to_string(),
-                },
                 ReasoningEffortOption {
                     reasoning_effort: ReasoningEffort::Medium,
-                    description: "Provides a solid balance of reasoning depth and latency for \
-                         general-purpose tasks"
-                        .to_string(),
+                    description: "Dynamically adjusts reasoning based on the task".to_string(),
                 },
                 ReasoningEffortOption {
                     reasoning_effort: ReasoningEffort::High,
@@ -176,6 +99,60 @@ async fn list_models_returns_all_models_with_large_limit() -> Result<()> {
             default_reasoning_effort: ReasoningEffort::Medium,
             is_default: false,
         },
+        Model {
+            id: "gpt-5.1-codex-max".to_string(),
+            model: "gpt-5.1-codex-max".to_string(),
+            display_name: "gpt-5.1-codex-max".to_string(),
+            description: "Codex-optimized flagship for deep and fast reasoning.".to_string(),
+            supported_reasoning_efforts: vec![
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::Low,
+                    description: "Fast responses with lighter reasoning".to_string(),
+                },
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::Medium,
+                    description: "Balances speed and reasoning depth for everyday tasks"
+                        .to_string(),
+                },
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::High,
+                    description: "Greater reasoning depth for complex problems".to_string(),
+                },
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::XHigh,
+                    description: "Extra high reasoning depth for complex problems".to_string(),
+                },
+            ],
+            default_reasoning_effort: ReasoningEffort::Medium,
+            is_default: false,
+        },
+        Model {
+            id: "gpt-5.2-codex".to_string(),
+            model: "gpt-5.2-codex".to_string(),
+            display_name: "gpt-5.2-codex".to_string(),
+            description: "Latest frontier agentic coding model.".to_string(),
+            supported_reasoning_efforts: vec![
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::Low,
+                    description: "Fast responses with lighter reasoning".to_string(),
+                },
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::Medium,
+                    description: "Balances speed and reasoning depth for everyday tasks"
+                        .to_string(),
+                },
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::High,
+                    description: "Greater reasoning depth for complex problems".to_string(),
+                },
+                ReasoningEffortOption {
+                    reasoning_effort: ReasoningEffort::XHigh,
+                    description: "Extra high reasoning depth for complex problems".to_string(),
+                },
+            ],
+            default_reasoning_effort: ReasoningEffort::Medium,
+            is_default: false,
+        },
     ];
 
     assert_eq!(items, expected_models);
@@ -210,7 +187,7 @@ async fn list_models_pagination_works() -> Result<()> {
     } = to_response::<ModelListResponse>(first_response)?;
 
     assert_eq!(first_items.len(), 1);
-    assert_eq!(first_items[0].id, "gpt-5.1-codex-max");
+    assert_eq!(first_items[0].id, "gpt-5.2");
     let next_cursor = first_cursor.ok_or_else(|| anyhow!("cursor for second page"))?;
 
     let second_request = mcp
@@ -232,7 +209,7 @@ async fn list_models_pagination_works() -> Result<()> {
     } = to_response::<ModelListResponse>(second_response)?;
 
     assert_eq!(second_items.len(), 1);
-    assert_eq!(second_items[0].id, "gpt-5.1-codex");
+    assert_eq!(second_items[0].id, "gpt-5.1-codex-mini");
     let third_cursor = second_cursor.ok_or_else(|| anyhow!("cursor for third page"))?;
 
     let third_request = mcp
@@ -254,7 +231,7 @@ async fn list_models_pagination_works() -> Result<()> {
     } = to_response::<ModelListResponse>(third_response)?;
 
     assert_eq!(third_items.len(), 1);
-    assert_eq!(third_items[0].id, "gpt-5.1-codex-mini");
+    assert_eq!(third_items[0].id, "gpt-5.1-codex-max");
     let fourth_cursor = third_cursor.ok_or_else(|| anyhow!("cursor for fourth page"))?;
 
     let fourth_request = mcp
@@ -276,30 +253,8 @@ async fn list_models_pagination_works() -> Result<()> {
     } = to_response::<ModelListResponse>(fourth_response)?;
 
     assert_eq!(fourth_items.len(), 1);
-    assert_eq!(fourth_items[0].id, "gpt-5.2");
-    let fifth_cursor = fourth_cursor.ok_or_else(|| anyhow!("cursor for fifth page"))?;
-
-    let fifth_request = mcp
-        .send_list_models_request(ModelListParams {
-            limit: Some(1),
-            cursor: Some(fifth_cursor.clone()),
-        })
-        .await?;
-
-    let fifth_response: JSONRPCResponse = timeout(
-        DEFAULT_TIMEOUT,
-        mcp.read_stream_until_response_message(RequestId::Integer(fifth_request)),
-    )
-    .await??;
-
-    let ModelListResponse {
-        data: fifth_items,
-        next_cursor: fifth_cursor,
-    } = to_response::<ModelListResponse>(fifth_response)?;
-
-    assert_eq!(fifth_items.len(), 1);
-    assert_eq!(fifth_items[0].id, "gpt-5.1");
-    assert!(fifth_cursor.is_none());
+    assert_eq!(fourth_items[0].id, "gpt-5.2-codex");
+    assert!(fourth_cursor.is_none());
     Ok(())
 }
 

codex-rs/chatgpt/src/apply_command.rs

@@ -3,7 +3,6 @@ use std::path::PathBuf;
 use clap::Parser;
 use codex_common::CliConfigOverrides;
 use codex_core::config::Config;
-use codex_core::config::ConfigOverrides;
 
 use crate::chatgpt_token::init_chatgpt_token_from_auth;
 use crate::get_task::GetTaskResponse;
@@ -28,7 +27,6 @@ pub async fn run_apply_command(
             .config_overrides
             .parse_overrides()
             .map_err(anyhow::Error::msg)?,
-        ConfigOverrides::default(),
     )
     .await?;
 

codex-rs/cli/src/debug_sandbox.rs

@@ -109,7 +109,7 @@ async fn run_command_under_sandbox(
     log_denials: bool,
 ) -> anyhow::Result<()> {
     let sandbox_mode = create_sandbox_mode(full_auto);
-    let config = Config::load_with_cli_overrides(
+    let config = Config::load_with_cli_overrides_and_harness_overrides(
         config_overrides
             .parse_overrides()
             .map_err(anyhow::Error::msg)?,

codex-rs/cli/src/login.rs

@@ -6,7 +6,6 @@ use codex_core::auth::CLIENT_ID;
 use codex_core::auth::login_with_api_key;
 use codex_core::auth::logout;
 use codex_core::config::Config;
-use codex_core::config::ConfigOverrides;
 use codex_login::ServerOptions;
 use codex_login::run_device_code_login;
 use codex_login::run_login_server;
@@ -210,8 +209,7 @@ async fn load_config_or_exit(cli_config_overrides: CliConfigOverrides) -> Config
         }
     };
 
-    let config_overrides = ConfigOverrides::default();
-    match Config::load_with_cli_overrides(cli_overrides, config_overrides).await {
+    match Config::load_with_cli_overrides(cli_overrides).await {
         Ok(config) => config,
         Err(e) => {
             eprintln!("Error loading configuration: {e}");

codex-rs/cli/src/main.rs

@@ -410,7 +410,7 @@ fn stage_str(stage: codex_core::features::Stage) -> &'static str {
     use codex_core::features::Stage;
     match stage {
         Stage::Experimental => "experimental",
-        Stage::Beta => "beta",
+        Stage::Beta { .. } => "beta",
         Stage::Stable => "stable",
         Stage::Deprecated => "deprecated",
         Stage::Removed => "removed",
@@ -631,7 +631,11 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
                     ..Default::default()
                 };
 
-                let config = Config::load_with_cli_overrides(cli_kv_overrides, overrides).await?;
+                let config = Config::load_with_cli_overrides_and_harness_overrides(
+                    cli_kv_overrides,
+                    overrides,
+                )
+                .await?;
                 for def in codex_core::features::FEATURES.iter() {
                     let name = def.key;
                     let stage = stage_str(def.stage);

codex-rs/cli/src/mcp_cmd.rs

@@ -8,7 +8,6 @@ use clap::ArgGroup;
 use codex_common::CliConfigOverrides;
 use codex_common::format_env_display::format_env_display;
 use codex_core::config::Config;
-use codex_core::config::ConfigOverrides;
 use codex_core::config::edit::ConfigEditsBuilder;
 use codex_core::config::find_codex_home;
 use codex_core::config::load_global_mcp_servers;
@@ -200,7 +199,7 @@ async fn run_add(config_overrides: &CliConfigOverrides, add_args: AddArgs) -> Re
     let overrides = config_overrides
         .parse_overrides()
         .map_err(anyhow::Error::msg)?;
-    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+    let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
 
@@ -349,7 +348,7 @@ async fn run_login(config_overrides: &CliConfigOverrides, login_args: LoginArgs)
     let overrides = config_overrides
         .parse_overrides()
         .map_err(anyhow::Error::msg)?;
-    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+    let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
 
@@ -392,7 +391,7 @@ async fn run_logout(config_overrides: &CliConfigOverrides, logout_args: LogoutAr
     let overrides = config_overrides
         .parse_overrides()
         .map_err(anyhow::Error::msg)?;
-    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+    let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
 
@@ -421,7 +420,7 @@ async fn run_list(config_overrides: &CliConfigOverrides, list_args: ListArgs) ->
     let overrides = config_overrides
         .parse_overrides()
         .map_err(anyhow::Error::msg)?;
-    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+    let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
 
@@ -678,7 +677,7 @@ async fn run_get(config_overrides: &CliConfigOverrides, get_args: GetArgs) -> Re
     let overrides = config_overrides
         .parse_overrides()
         .map_err(anyhow::Error::msg)?;
-    let config = Config::load_with_cli_overrides(overrides, ConfigOverrides::default())
+    let config = Config::load_with_cli_overrides(overrides)
         .await
         .context("failed to load configuration")?;
 

codex-rs/cloud-tasks/Cargo.toml

@@ -37,6 +37,9 @@ unicode-width = { workspace = true }
 owo-colors = { workspace = true, features = ["supports-colors"] }
 supports-color = { workspace = true }
 
+[dependencies.async-trait]
+workspace = true
+
 [dev-dependencies]
 async-trait = { workspace = true }
 pretty_assertions = { workspace = true }

codex-rs/cloud-tasks/src/cli.rs

@@ -34,10 +34,6 @@ pub struct ExecCommand {
     #[arg(long = "env", value_name = "ENV_ID")]
     pub environment: String,
 
-    /// Git branch to run in Codex Cloud.
-    #[arg(long = "branch", value_name = "BRANCH", default_value = "main")]
-    pub branch: String,
-
     /// Number of assistant attempts (best-of-N).
     #[arg(
         long = "attempts",
@@ -45,6 +41,10 @@ pub struct ExecCommand {
         value_parser = parse_attempts
     )]
     pub attempts: usize,
+
+    /// Git branch to run in Codex Cloud (defaults to current branch).
+    #[arg(long = "branch", value_name = "BRANCH")]
+    pub branch: Option<String>,
 }
 
 fn parse_attempts(input: &str) -> Result<usize, String> {

codex-rs/cloud-tasks/src/lib.rs

@@ -104,6 +104,54 @@ async fn init_backend(user_agent_suffix: &str) -> anyhow::Result<BackendContext>
     })
 }
 
+#[async_trait::async_trait]
+trait GitInfoProvider {
+    async fn default_branch_name(&self, path: &std::path::Path) -> Option<String>;
+
+    async fn current_branch_name(&self, path: &std::path::Path) -> Option<String>;
+}
+
+struct RealGitInfo;
+
+#[async_trait::async_trait]
+impl GitInfoProvider for RealGitInfo {
+    async fn default_branch_name(&self, path: &std::path::Path) -> Option<String> {
+        codex_core::git_info::default_branch_name(path).await
+    }
+
+    async fn current_branch_name(&self, path: &std::path::Path) -> Option<String> {
+        codex_core::git_info::current_branch_name(path).await
+    }
+}
+
+async fn resolve_git_ref(branch_override: Option<&String>) -> String {
+    resolve_git_ref_with_git_info(branch_override, &RealGitInfo).await
+}
+
+async fn resolve_git_ref_with_git_info(
+    branch_override: Option<&String>,
+    git_info: &impl GitInfoProvider,
+) -> String {
+    if let Some(branch) = branch_override {
+        let branch = branch.trim();
+        if !branch.is_empty() {
+            return branch.to_string();
+        }
+    }
+
+    if let Ok(cwd) = std::env::current_dir() {
+        if let Some(branch) = git_info.current_branch_name(&cwd).await {
+            branch
+        } else if let Some(branch) = git_info.default_branch_name(&cwd).await {
+            branch
+        } else {
+            "main".to_string()
+        }
+    } else {
+        "main".to_string()
+    }
+}
+
 async fn run_exec_command(args: crate::cli::ExecCommand) -> anyhow::Result<()> {
     let crate::cli::ExecCommand {
         query,
@@ -114,11 +162,12 @@ async fn run_exec_command(args: crate::cli::ExecCommand) -> anyhow::Result<()> {
     let ctx = init_backend("codex_cloud_tasks_exec").await?;
     let prompt = resolve_query_input(query)?;
     let env_id = resolve_environment_id(&ctx, &environment).await?;
+    let git_ref = resolve_git_ref(branch.as_ref()).await;
     let created = codex_cloud_tasks_client::CloudBackend::create_task(
         &*ctx.backend,
         &env_id,
         &prompt,
-        &branch,
+        &git_ref,
         false,
         attempts,
     )
@@ -1362,17 +1411,7 @@ pub async fn run_main(cli: Cli, _codex_linux_sandbox_exe: Option<PathBuf>) -> an
                                                 let backend = Arc::clone(&backend);
                                                 let best_of_n = page.best_of_n;
                                                 tokio::spawn(async move {
-                                                    let git_ref = if let Ok(cwd) = std::env::current_dir() {
-                                                        if let Some(branch) = codex_core::git_info::default_branch_name(&cwd).await {
-                                                            branch
-                                                        } else if let Some(branch) = codex_core::git_info::current_branch_name(&cwd).await {
-                                                            branch
-                                                        } else {
-                                                            "main".to_string()
-                                                        }
-                                                    } else {
-                                                        "main".to_string()
-                                                    };
+                                                    let git_ref = resolve_git_ref(None).await;
 
                                                     let result = codex_cloud_tasks_client::CloudBackend::create_task(&*backend, &env, &text, &git_ref, false, best_of_n).await;
                                                     let evt = match result {
@@ -1991,6 +2030,7 @@ fn pretty_lines_from_error(raw: &str) -> Vec<String> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::resolve_git_ref_with_git_info;
     use codex_cloud_tasks_client::DiffSummary;
     use codex_cloud_tasks_client::MockClient;
     use codex_cloud_tasks_client::TaskId;
@@ -2005,6 +2045,85 @@ mod tests {
     use ratatui::buffer::Buffer;
     use ratatui::layout::Rect;
 
+    struct StubGitInfo {
+        default_branch: Option<String>,
+        current_branch: Option<String>,
+    }
+
+    impl StubGitInfo {
+        fn new(default_branch: Option<String>, current_branch: Option<String>) -> Self {
+            Self {
+                default_branch,
+                current_branch,
+            }
+        }
+    }
+
+    #[async_trait::async_trait]
+    impl super::GitInfoProvider for StubGitInfo {
+        async fn default_branch_name(&self, _path: &std::path::Path) -> Option<String> {
+            self.default_branch.clone()
+        }
+
+        async fn current_branch_name(&self, _path: &std::path::Path) -> Option<String> {
+            self.current_branch.clone()
+        }
+    }
+
+    #[tokio::test]
+    async fn branch_override_is_used_when_provided() {
+        let git_ref = resolve_git_ref_with_git_info(
+            Some(&"feature/override".to_string()),
+            &StubGitInfo::new(None, None),
+        )
+        .await;
+
+        assert_eq!(git_ref, "feature/override");
+    }
+
+    #[tokio::test]
+    async fn trims_override_whitespace() {
+        let git_ref = resolve_git_ref_with_git_info(
+            Some(&"  feature/spaces  ".to_string()),
+            &StubGitInfo::new(None, None),
+        )
+        .await;
+
+        assert_eq!(git_ref, "feature/spaces");
+    }
+
+    #[tokio::test]
+    async fn prefers_current_branch_when_available() {
+        let git_ref = resolve_git_ref_with_git_info(
+            None,
+            &StubGitInfo::new(
+                Some("default-main".to_string()),
+                Some("feature/current".to_string()),
+            ),
+        )
+        .await;
+
+        assert_eq!(git_ref, "feature/current");
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_current_branch_when_default_is_missing() {
+        let git_ref = resolve_git_ref_with_git_info(
+            None,
+            &StubGitInfo::new(None, Some("develop".to_string())),
+        )
+        .await;
+
+        assert_eq!(git_ref, "develop");
+    }
+
+    #[tokio::test]
+    async fn falls_back_to_main_when_no_git_info_is_available() {
+        let git_ref = resolve_git_ref_with_git_info(None, &StubGitInfo::new(None, None)).await;
+
+        assert_eq!(git_ref, "main");
+    }
+
     #[test]
     fn format_task_status_lines_with_diff_and_label() {
         let now = Utc::now();

codex-rs/cloud-tasks/src/util.rs

@@ -5,7 +5,6 @@ use chrono::Utc;
 use reqwest::header::HeaderMap;
 
 use codex_core::config::Config;
-use codex_core::config::ConfigOverrides;
 use codex_login::AuthManager;
 
 pub fn set_user_agent_suffix(suffix: &str) {
@@ -62,9 +61,7 @@ pub fn extract_chatgpt_account_id(token: &str) -> Option<String> {
 
 pub async fn load_auth_manager() -> Option<AuthManager> {
     // TODO: pass in cli overrides once cloud tasks properly support them.
-    let config = Config::load_with_cli_overrides(Vec::new(), ConfigOverrides::default())
-        .await
-        .ok()?;
+    let config = Config::load_with_cli_overrides(Vec::new()).await.ok()?;
     Some(AuthManager::new(
         config.codex_home,
         false,

codex-rs/codex-api/src/endpoint/models.rs

@@ -5,6 +5,7 @@ use crate::provider::Provider;
 use crate::telemetry::run_with_request_telemetry;
 use codex_client::HttpTransport;
 use codex_client::RequestTelemetry;
+use codex_protocol::openai_models::ModelInfo;
 use codex_protocol::openai_models::ModelsResponse;
 use http::HeaderMap;
 use http::Method;
@@ -41,7 +42,7 @@ impl<T: HttpTransport, A: AuthProvider> ModelsClient<T, A> {
         &self,
         client_version: &str,
         extra_headers: HeaderMap,
-    ) -> Result<ModelsResponse, ApiError> {
+    ) -> Result<(Vec<ModelInfo>, Option<String>), ApiError> {
         let builder = || {
             let mut req = self.provider.build_request(Method::GET, self.path());
             req.headers.extend(extra_headers.clone());
@@ -66,7 +67,7 @@ impl<T: HttpTransport, A: AuthProvider> ModelsClient<T, A> {
             .and_then(|value| value.to_str().ok())
             .map(ToString::to_string);
 
-        let ModelsResponse { models, etag } = serde_json::from_slice::<ModelsResponse>(&resp.body)
+        let ModelsResponse { models } = serde_json::from_slice::<ModelsResponse>(&resp.body)
             .map_err(|e| {
                 ApiError::Stream(format!(
                     "failed to decode models response: {e}; body: {}",
@@ -74,9 +75,7 @@ impl<T: HttpTransport, A: AuthProvider> ModelsClient<T, A> {
                 ))
             })?;
 
-        let etag = header_etag.unwrap_or(etag);
-
-        Ok(ModelsResponse { models, etag })
+        Ok((models, header_etag))
     }
 }
 
@@ -102,16 +101,15 @@ mod tests {
     struct CapturingTransport {
         last_request: Arc<Mutex<Option<Request>>>,
         body: Arc<ModelsResponse>,
+        response_etag: Arc<Option<String>>,
     }
 
     impl Default for CapturingTransport {
         fn default() -> Self {
             Self {
                 last_request: Arc::new(Mutex::new(None)),
-                body: Arc::new(ModelsResponse {
-                    models: Vec::new(),
-                    etag: String::new(),
-                }),
+                body: Arc::new(ModelsResponse { models: Vec::new() }),
+                response_etag: Arc::new(None),
             }
         }
     }
@@ -122,8 +120,8 @@ mod tests {
             *self.last_request.lock().unwrap() = Some(req);
             let body = serde_json::to_vec(&*self.body).unwrap();
             let mut headers = HeaderMap::new();
-            if !self.body.etag.is_empty() {
-                headers.insert(ETAG, self.body.etag.parse().unwrap());
+            if let Some(etag) = self.response_etag.as_ref().as_deref() {
+                headers.insert(ETAG, etag.parse().unwrap());
             }
             Ok(Response {
                 status: StatusCode::OK,
@@ -166,14 +164,12 @@ mod tests {
 
     #[tokio::test]
     async fn appends_client_version_query() {
-        let response = ModelsResponse {
-            models: Vec::new(),
-            etag: String::new(),
-        };
+        let response = ModelsResponse { models: Vec::new() };
 
         let transport = CapturingTransport {
             last_request: Arc::new(Mutex::new(None)),
             body: Arc::new(response),
+            response_etag: Arc::new(None),
         };
 
         let client = ModelsClient::new(
@@ -182,12 +178,12 @@ mod tests {
             DummyAuth,
         );
 
-        let result = client
+        let (models, _etag) = client
             .list_models("0.99.0", HeaderMap::new())
             .await
             .expect("request should succeed");
 
-        assert_eq!(result.models.len(), 0);
+        assert_eq!(models.len(), 0);
 
         let url = transport
             .last_request
@@ -232,12 +228,12 @@ mod tests {
                 }))
                 .unwrap(),
             ],
-            etag: String::new(),
         };
 
         let transport = CapturingTransport {
             last_request: Arc::new(Mutex::new(None)),
             body: Arc::new(response),
+            response_etag: Arc::new(None),
         };
 
         let client = ModelsClient::new(
@@ -246,27 +242,25 @@ mod tests {
             DummyAuth,
         );
 
-        let result = client
+        let (models, _etag) = client
             .list_models("0.99.0", HeaderMap::new())
             .await
             .expect("request should succeed");
 
-        assert_eq!(result.models.len(), 1);
-        assert_eq!(result.models[0].slug, "gpt-test");
-        assert_eq!(result.models[0].supported_in_api, true);
-        assert_eq!(result.models[0].priority, 1);
+        assert_eq!(models.len(), 1);
+        assert_eq!(models[0].slug, "gpt-test");
+        assert_eq!(models[0].supported_in_api, true);
+        assert_eq!(models[0].priority, 1);
     }
 
     #[tokio::test]
     async fn list_models_includes_etag() {
-        let response = ModelsResponse {
-            models: Vec::new(),
-            etag: "\"abc\"".to_string(),
-        };
+        let response = ModelsResponse { models: Vec::new() };
 
         let transport = CapturingTransport {
             last_request: Arc::new(Mutex::new(None)),
             body: Arc::new(response),
+            response_etag: Arc::new(Some("\"abc\"".to_string())),
         };
 
         let client = ModelsClient::new(
@@ -275,12 +269,12 @@ mod tests {
             DummyAuth,
         );
 
-        let result = client
+        let (models, etag) = client
             .list_models("0.1.0", HeaderMap::new())
             .await
             .expect("request should succeed");
 
-        assert_eq!(result.models.len(), 0);
-        assert_eq!(result.etag, "\"abc\"");
+        assert_eq!(models.len(), 0);
+        assert_eq!(etag.as_deref(), Some("\"abc\""));
     }
 }

codex-rs/codex-api/src/endpoint/responses.rs

@@ -32,6 +32,7 @@ pub struct ResponsesOptions {
     pub store_override: Option<bool>,
     pub conversation_id: Option<String>,
     pub session_source: Option<SessionSource>,
+    pub extra_headers: HeaderMap,
 }
 
 impl<T: HttpTransport, A: AuthProvider> ResponsesClient<T, A> {
@@ -73,6 +74,7 @@ impl<T: HttpTransport, A: AuthProvider> ResponsesClient<T, A> {
             store_override,
             conversation_id,
             session_source,
+            extra_headers,
         } = options;
 
         let request = ResponsesRequestBuilder::new(model, &prompt.instructions, &prompt.input)
@@ -85,6 +87,7 @@ impl<T: HttpTransport, A: AuthProvider> ResponsesClient<T, A> {
             .conversation(conversation_id)
             .session_source(session_source)
             .store_override(store_override)
+            .extra_headers(extra_headers)
             .build(self.streaming.provider())?;
 
         self.stream_request(request).await

codex-rs/codex-api/tests/models_integration.rs

@@ -90,7 +90,6 @@ async fn models_client_hits_models_endpoint() {
             reasoning_summary_format: ReasoningSummaryFormat::None,
             experimental_supported_tools: Vec::new(),
         }],
-        etag: String::new(),
     };
 
     Mock::given(method("GET"))
@@ -106,13 +105,13 @@ async fn models_client_hits_models_endpoint() {
     let transport = ReqwestTransport::new(reqwest::Client::new());
     let client = ModelsClient::new(transport, provider(&base_url), DummyAuth);
 
-    let result = client
+    let (models, _etag) = client
         .list_models("0.1.0", HeaderMap::new())
         .await
         .expect("models request should succeed");
 
-    assert_eq!(result.models.len(), 1);
-    assert_eq!(result.models[0].slug, "gpt-test");
+    assert_eq!(models.len(), 1);
+    assert_eq!(models[0].slug, "gpt-test");
 
     let received = server
         .received_requests()

codex-rs/common/Cargo.toml

@@ -21,3 +21,10 @@ toml = { workspace = true, optional = true }
 cli = ["clap", "serde", "toml"]
 elapsed = []
 sandbox_summary = []
+
+[dev-dependencies]
+clap = { workspace = true, features = ["derive", "wrap_help"] }
+codex-utils-absolute-path = { workspace = true }
+pretty_assertions = { workspace = true }
+serde = { workspace = true }
+toml = { workspace = true }

codex-rs/common/src/config_summary.rs

@@ -9,7 +9,7 @@ pub fn create_config_summary_entries(config: &Config, model: &str) -> Vec<(&'sta
         ("workdir", config.cwd.display().to_string()),
         ("model", model.to_string()),
         ("provider", config.model_provider_id.clone()),
-        ("approval", config.approval_policy.to_string()),
+        ("approval", config.approval_policy.value().to_string()),
         ("sandbox", summarize_sandbox_policy(&config.sandbox_policy)),
     ];
     if config.model_provider.wire_api == WireApi::Responses {

codex-rs/common/src/sandbox_mode_cli_arg.rs

@@ -26,3 +26,22 @@ impl From<SandboxModeCliArg> for SandboxMode {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn maps_cli_args_to_protocol_modes() {
+        assert_eq!(SandboxMode::ReadOnly, SandboxModeCliArg::ReadOnly.into());
+        assert_eq!(
+            SandboxMode::WorkspaceWrite,
+            SandboxModeCliArg::WorkspaceWrite.into()
+        );
+        assert_eq!(
+            SandboxMode::DangerFullAccess,
+            SandboxModeCliArg::DangerFullAccess.into()
+        );
+    }
+}

codex-rs/common/src/sandbox_summary.rs

@@ -1,9 +1,17 @@
+use codex_core::protocol::NetworkAccess;
 use codex_core::protocol::SandboxPolicy;
 
 pub fn summarize_sandbox_policy(sandbox_policy: &SandboxPolicy) -> String {
     match sandbox_policy {
         SandboxPolicy::DangerFullAccess => "danger-full-access".to_string(),
         SandboxPolicy::ReadOnly => "read-only".to_string(),
+        SandboxPolicy::ExternalSandbox { network_access } => {
+            let mut summary = "external-sandbox".to_string();
+            if matches!(network_access, NetworkAccess::Enabled) {
+                summary.push_str(" (network access enabled)");
+            }
+            summary
+        }
         SandboxPolicy::WorkspaceWrite {
             writable_roots,
             network_access,
@@ -34,3 +42,45 @@ pub fn summarize_sandbox_policy(sandbox_policy: &SandboxPolicy) -> String {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn summarizes_external_sandbox_without_network_access_suffix() {
+        let summary = summarize_sandbox_policy(&SandboxPolicy::ExternalSandbox {
+            network_access: NetworkAccess::Restricted,
+        });
+        assert_eq!(summary, "external-sandbox");
+    }
+
+    #[test]
+    fn summarizes_external_sandbox_with_enabled_network() {
+        let summary = summarize_sandbox_policy(&SandboxPolicy::ExternalSandbox {
+            network_access: NetworkAccess::Enabled,
+        });
+        assert_eq!(summary, "external-sandbox (network access enabled)");
+    }
+
+    #[test]
+    fn workspace_write_summary_still_includes_network_access() {
+        let root = if cfg!(windows) { "C:\\repo" } else { "/repo" };
+        let writable_root = AbsolutePathBuf::try_from(root).unwrap();
+        let summary = summarize_sandbox_policy(&SandboxPolicy::WorkspaceWrite {
+            writable_roots: vec![writable_root.clone()],
+            network_access: true,
+            exclude_tmpdir_env_var: true,
+            exclude_slash_tmp: true,
+        });
+        assert_eq!(
+            summary,
+            format!(
+                "workspace-write [workdir, {}] (network access enabled)",
+                writable_root.to_string_lossy()
+            )
+        );
+    }
+}

codex-rs/core/Cargo.toml

@@ -43,6 +43,7 @@ env-flags = { workspace = true }
 eventsource-stream = { workspace = true }
 futures = { workspace = true }
 http = { workspace = true }
+include_dir = { workspace = true }
 indexmap = { workspace = true }
 keyring = { workspace = true, features = ["crypto-rust"] }
 libc = { workspace = true }
@@ -60,7 +61,6 @@ sha1 = { workspace = true }
 sha2 = { workspace = true }
 shlex = { workspace = true }
 similar = { workspace = true }
-strum_macros = { workspace = true }
 tempfile = { workspace = true }
 test-case = "3.3.1"
 test-log = { workspace = true }
@@ -131,7 +131,6 @@ predicates = { workspace = true }
 pretty_assertions = { workspace = true }
 serial_test = { workspace = true }
 tempfile = { workspace = true }
-tokio-test = { workspace = true }
 tracing-subscriber = { workspace = true }
 tracing-test = { workspace = true, features = ["no-env-filter"] }
 walkdir = { workspace = true }

codex-rs/core/gpt-5.2-codex_prompt.md

@@ -0,0 +1,117 @@
+You are Codex, based on GPT-5. You are running as a coding agent in the Codex CLI on a user's computer.
+
+## General
+
+- When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)
+
+## Editing constraints
+
+- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
+- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
+- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
+- You may be in a dirty git worktree.
+    * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
+    * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
+    * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
+    * If the changes are in unrelated files, just ignore them and don't revert them.
+- Do not amend a commit unless explicitly requested to do so.
+- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
+- **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user.
+
+## Plan tool
+
+When using the planning tool:
+- Skip using the planning tool for straightforward tasks (roughly the easiest 25%).
+- Do not make single-step plans.
+- When you made a plan, update it after having performed one of the sub-tasks that you shared on the plan.
+
+## Codex CLI harness, sandboxing, and approvals
+
+The Codex CLI harness supports several different configurations for sandboxing and escalation approvals that the user can choose from.
+
+Filesystem sandboxing defines which files can be read or written. The options for `sandbox_mode` are:
+- **read-only**: The sandbox only permits reading files.
+- **workspace-write**: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval.
+- **danger-full-access**: No filesystem sandboxing - all commands are permitted.
+
+Network sandboxing defines whether network can be accessed without approval. Options for `network_access` are:
+- **restricted**: Requires approval
+- **enabled**: No approval needed
+
+Approvals are your mechanism to get user consent to run shell commands without the sandbox. Possible configuration options for `approval_policy` are
+- **untrusted**: The harness will escalate most commands for user approval, apart from a limited allowlist of safe "read" commands.
+- **on-failure**: The harness will allow all commands to run in the sandbox (if enabled), and failures will be escalated to the user for approval to run again without the sandbox.
+- **on-request**: Commands will be run in the sandbox by default, and you can specify in your tool call if you want to escalate a command to run without sandboxing. (Note that this mode is not always available. If it is, you'll see parameters for it in the `shell` command description.)
+- **never**: This is a non-interactive mode where you may NEVER ask the user for approval to run commands. Instead, you must always persist and work around constraints to solve the task for the user. You MUST do your utmost best to finish the task and validate your work before yielding. If this mode is paired with `danger-full-access`, take advantage of it to deliver the best outcome for the user. Further, in this mode, your default testing philosophy is overridden: Even if you don't see local patterns for testing, you may add tests and scripts to validate your work. Just remove them before yielding.
+
+When you are running with `approval_policy == on-request`, and sandboxing enabled, here are scenarios where you'll need to request approval:
+- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var)
+- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.
+- You are running sandboxed and need to run a command that requires network access (e.g. installing packages)
+- If you run a command that is important to solving the user's query, but it fails because of sandboxing, rerun the command with approval. ALWAYS proceed to use the `sandbox_permissions` and `justification` parameters - do not message the user before requesting approval for the command.
+- You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for
+- (for all of these, you should weigh alternative paths that do not require approval)
+
+When `sandbox_mode` is set to read-only, you'll need to request approval for any command that isn't a read.
+
+You will be told what filesystem sandboxing, network sandboxing, and approval mode are active in a developer or user message. If you are not told about this, assume that you are running with workspace-write, network sandboxing enabled, and approval on-failure.
+
+Although they introduce friction to the user because your work is paused until the user responds, you should leverage them when necessary to accomplish important work. If the completing the task requires escalated permissions, Do not let these settings or the sandbox deter you from attempting to accomplish the user's task unless it is set to "never", in which case never ask for approvals.
+
+When requesting approval to execute a command that will require escalated privileges:
+  - Provide the `sandbox_permissions` parameter with the value `"require_escalated"`
+  - Include a short, 1 sentence explanation for why you need escalated permissions in the justification parameter
+
+## Special user requests
+
+- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so.
+- If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response - keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.
+
+## Frontend tasks
+When doing frontend design tasks, avoid collapsing into "AI slop" or safe, average-looking layouts.
+Aim for interfaces that feel intentional, bold, and a bit surprising.
+- Typography: Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
+- Color & Look: Choose a clear visual direction; define CSS variables; avoid purple-on-white defaults. No purple bias or dark mode bias.
+- Motion: Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
+- Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
+- Overall: Avoid boilerplate layouts and interchangeable UI patterns. Vary themes, type families, and visual languages across outputs.
+- Ensure the page loads properly on both desktop and mobile
+
+Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
+
+## Presenting your work and final message
+
+You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
+
+- Default: be very concise; friendly coding teammate tone.
+- Ask only when needed; suggest ideas; mirror the user's style.
+- For substantial work, summarize clearly; follow final‑answer formatting.
+- Skip heavy formatting for simple confirmations.
+- Don't dump large files you've written; reference paths only.
+- No "save/copy this file" - User is on the same machine.
+- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
+- For code changes:
+  * Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in.
+  * If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.
+  * When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.
+- The user does not command execution outputs. When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines so the user understands the result.
+
+### Final answer structure and style guidelines
+
+- Plain text; CLI handles styling. Use structure only when it helps scanability.
+- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.
+- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.
+- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.
+- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.
+- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.
+- Tone: collaborative, concise, factual; present tense, active voice; self‑contained; no "above/below"; parallel wording.
+- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.
+- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.
+- File References: When referencing files in your response follow the below rules:
+  * Use inline code to make file paths clickable.
+  * Each reference should have a stand alone path. Even if it's the same file.
+  * Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
+  * Optionally include line/column (1‑based): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
+  * Do not use URIs like file://, vscode://, or https://.
+  * Do not provide range of lines
+  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5

codex-rs/core/src/api_bridge.rs

@@ -67,6 +67,11 @@ pub(crate) fn map_api_error(err: ApiError) -> CodexErr {
                         status,
                         request_id: extract_request_id(headers.as_ref()),
                     })
+                } else if status == http::StatusCode::PRECONDITION_FAILED
+                    && body_text
+                        .contains("Models catalog has changed. Please refresh your models list.")
+                {
+                    CodexErr::OutdatedModels
                 } else {
                     CodexErr::UnexpectedStatus(UnexpectedResponseError {
                         status,

codex-rs/core/src/auth.rs

@@ -636,8 +636,7 @@ mod tests {
     use crate::auth::storage::FileAuthStorage;
     use crate::auth::storage::get_auth_file;
     use crate::config::Config;
-    use crate::config::ConfigOverrides;
-    use crate::config::ConfigToml;
+    use crate::config::ConfigBuilder;
     use crate::token_data::IdTokenInfo;
     use crate::token_data::KnownPlan as InternalKnownPlan;
     use crate::token_data::PlanType as InternalPlanType;
@@ -862,17 +861,16 @@ mod tests {
         Ok(fake_jwt)
     }
 
-    fn build_config(
+    async fn build_config(
         codex_home: &Path,
         forced_login_method: Option<ForcedLoginMethod>,
         forced_chatgpt_workspace_id: Option<String>,
     ) -> Config {
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.to_path_buf(),
-        )
-        .expect("config should load");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.to_path_buf())
+            .build()
+            .await
+            .expect("config should load");
         config.forced_login_method = forced_login_method;
         config.forced_chatgpt_workspace_id = forced_chatgpt_workspace_id;
         config
@@ -915,7 +913,7 @@ mod tests {
         login_with_api_key(codex_home.path(), "sk-test", AuthCredentialsStoreMode::File)
             .expect("seed api key");
 
-        let config = build_config(codex_home.path(), Some(ForcedLoginMethod::Chatgpt), None);
+        let config = build_config(codex_home.path(), Some(ForcedLoginMethod::Chatgpt), None).await;
 
         let err = super::enforce_login_restrictions(&config)
             .await
@@ -941,7 +939,7 @@ mod tests {
         )
         .expect("failed to write auth file");
 
-        let config = build_config(codex_home.path(), None, Some("org_mine".to_string()));
+        let config = build_config(codex_home.path(), None, Some("org_mine".to_string())).await;
 
         let err = super::enforce_login_restrictions(&config)
             .await
@@ -967,7 +965,7 @@ mod tests {
         )
         .expect("failed to write auth file");
 
-        let config = build_config(codex_home.path(), None, Some("org_mine".to_string()));
+        let config = build_config(codex_home.path(), None, Some("org_mine".to_string())).await;
 
         super::enforce_login_restrictions(&config)
             .await
@@ -985,7 +983,7 @@ mod tests {
         login_with_api_key(codex_home.path(), "sk-test", AuthCredentialsStoreMode::File)
             .expect("seed api key");
 
-        let config = build_config(codex_home.path(), None, Some("org_mine".to_string()));
+        let config = build_config(codex_home.path(), None, Some("org_mine".to_string())).await;
 
         super::enforce_login_restrictions(&config)
             .await
@@ -1002,7 +1000,7 @@ mod tests {
         let _guard = EnvVarGuard::set(CODEX_API_KEY_ENV_VAR, "sk-env");
         let codex_home = tempdir().unwrap();
 
-        let config = build_config(codex_home.path(), Some(ForcedLoginMethod::Chatgpt), None);
+        let config = build_config(codex_home.path(), Some(ForcedLoginMethod::Chatgpt), None).await;
 
         let err = super::enforce_login_restrictions(&config)
             .await

codex-rs/core/src/client.rs

@@ -33,6 +33,7 @@ use http::StatusCode as HttpStatusCode;
 use reqwest::StatusCode;
 use serde_json::Value;
 use std::time::Duration;
+use tokio::sync::RwLock;
 use tokio::sync::mpsc;
 use tracing::warn;
 
@@ -45,6 +46,7 @@ use crate::config::Config;
 use crate::default_client::build_reqwest_client;
 use crate::error::CodexErr;
 use crate::error::Result;
+use crate::features::FEATURES;
 use crate::flags::CODEX_RS_SSE_FIXTURE;
 use crate::model_provider_info::ModelProviderInfo;
 use crate::model_provider_info::WireApi;
@@ -52,11 +54,12 @@ use crate::openai_models::model_family::ModelFamily;
 use crate::tools::spec::create_tools_json_for_chat_completions_api;
 use crate::tools::spec::create_tools_json_for_responses_api;
 
-#[derive(Debug, Clone)]
+#[derive(Debug)]
 pub struct ModelClient {
     config: Arc<Config>,
     auth_manager: Option<Arc<AuthManager>>,
-    model_family: ModelFamily,
+    model_family: RwLock<ModelFamily>,
+    models_etag: RwLock<Option<String>>,
     otel_manager: OtelManager,
     provider: ModelProviderInfo,
     conversation_id: ConversationId,
@@ -71,6 +74,7 @@ impl ModelClient {
         config: Arc<Config>,
         auth_manager: Option<Arc<AuthManager>>,
         model_family: ModelFamily,
+        models_etag: Option<String>,
         otel_manager: OtelManager,
         provider: ModelProviderInfo,
         effort: Option<ReasoningEffortConfig>,
@@ -81,7 +85,8 @@ impl ModelClient {
         Self {
             config,
             auth_manager,
-            model_family,
+            model_family: RwLock::new(model_family),
+            models_etag: RwLock::new(models_etag),
             otel_manager,
             provider,
             conversation_id,
@@ -91,8 +96,8 @@ impl ModelClient {
         }
     }
 
-    pub fn get_model_context_window(&self) -> Option<i64> {
-        let model_family = self.get_model_family();
+    pub async fn get_model_context_window(&self) -> Option<i64> {
+        let model_family = self.get_model_family().await;
         let effective_context_window_percent = model_family.effective_context_window_percent;
         model_family
             .context_window
@@ -145,7 +150,7 @@ impl ModelClient {
         }
 
         let auth_manager = self.auth_manager.clone();
-        let model_family = self.get_model_family();
+        let model_family = self.get_model_family().await;
         let instructions = prompt.get_full_instructions(&model_family).into_owned();
         let tools_json = create_tools_json_for_chat_completions_api(&prompt.tools)?;
         let api_prompt = build_api_prompt(prompt, instructions, tools_json);
@@ -166,7 +171,7 @@ impl ModelClient {
 
             let stream_result = client
                 .stream_prompt(
-                    &self.get_model(),
+                    &self.get_model().await,
                     &api_prompt,
                     Some(conversation_id.clone()),
                     Some(session_source.clone()),
@@ -199,7 +204,7 @@ impl ModelClient {
         }
 
         let auth_manager = self.auth_manager.clone();
-        let model_family = self.get_model_family();
+        let model_family = self.get_model_family().await;
         let instructions = prompt.get_full_instructions(&model_family).into_owned();
         let tools_json: Vec<Value> = create_tools_json_for_responses_api(&prompt.tools)?;
 
@@ -261,10 +266,14 @@ impl ModelClient {
                 store_override: None,
                 conversation_id: Some(conversation_id.clone()),
                 session_source: Some(session_source.clone()),
+                extra_headers: beta_feature_headers(
+                    &self.config,
+                    self.get_models_etag().await.clone(),
+                ),
             };
 
             let stream_result = client
-                .stream_prompt(&self.get_model(), &api_prompt, options)
+                .stream_prompt(&self.get_model().await, &api_prompt, options)
                 .await;
 
             match stream_result {
@@ -295,13 +304,25 @@ impl ModelClient {
     }
 
     /// Returns the currently configured model slug.
-    pub fn get_model(&self) -> String {
-        self.get_model_family().get_model_slug().to_string()
+    pub async fn get_model(&self) -> String {
+        self.get_model_family().await.get_model_slug().to_string()
     }
 
     /// Returns the currently configured model family.
-    pub fn get_model_family(&self) -> ModelFamily {
-        self.model_family.clone()
+    pub async fn get_model_family(&self) -> ModelFamily {
+        self.model_family.read().await.clone()
+    }
+
+    pub async fn get_models_etag(&self) -> Option<String> {
+        self.models_etag.read().await.clone()
+    }
+
+    pub async fn update_models_etag(&self, etag: Option<String>) {
+        *self.models_etag.write().await = etag;
+    }
+
+    pub async fn update_model_family(&self, model_family: ModelFamily) {
+        *self.model_family.write().await = model_family;
     }
 
     /// Returns the current reasoning effort setting.
@@ -338,10 +359,10 @@ impl ModelClient {
             .with_telemetry(Some(request_telemetry));
 
         let instructions = prompt
-            .get_full_instructions(&self.get_model_family())
+            .get_full_instructions(&self.get_model_family().await)
             .into_owned();
         let payload = ApiCompactionInput {
-            model: &self.get_model(),
+            model: &self.get_model().await,
             input: &prompt.input,
             instructions: &instructions,
         };
@@ -396,6 +417,32 @@ fn build_api_prompt(prompt: &Prompt, instructions: String, tools_json: Vec<Value
     }
 }
 
+fn beta_feature_headers(config: &Config, models_etag: Option<String>) -> ApiHeaderMap {
+    let enabled = FEATURES
+        .iter()
+        .filter_map(|spec| {
+            if spec.stage.beta_menu_description().is_some() && config.features.enabled(spec.id) {
+                Some(spec.key)
+            } else {
+                None
+            }
+        })
+        .collect::<Vec<_>>();
+    let value = enabled.join(",");
+    let mut headers = ApiHeaderMap::new();
+    if !value.is_empty()
+        && let Ok(header_value) = HeaderValue::from_str(value.as_str())
+    {
+        headers.insert("x-codex-beta-features", header_value);
+    }
+    if let Some(etag) = models_etag
+        && let Ok(header_value) = HeaderValue::from_str(&etag)
+    {
+        headers.insert("X-If-Models-Match", header_value);
+    }
+    headers
+}
+
 fn map_response_stream<S>(api_stream: S, otel_manager: OtelManager) -> ResponseStream
 where
     S: futures::Stream<Item = std::result::Result<ResponseEvent, ApiError>>

codex-rs/core/src/client_common.rs

@@ -1,6 +1,10 @@
 use crate::client_common::tools::ToolSpec;
+use crate::codex::Session;
+use crate::codex::TurnContext;
 use crate::error::Result;
+use crate::features::Feature;
 use crate::openai_models::model_family::ModelFamily;
+use crate::tools::ToolRouter;
 pub use codex_api::common::ResponseEvent;
 use codex_apply_patch::APPLY_PATCH_TOOL_INSTRUCTIONS;
 use codex_protocol::models::ResponseItem;
@@ -44,6 +48,28 @@ pub struct Prompt {
 }
 
 impl Prompt {
+    pub(crate) async fn new(
+        sess: &Session,
+        turn_context: &TurnContext,
+        router: &ToolRouter,
+        input: &[ResponseItem],
+    ) -> Prompt {
+        let model_supports_parallel = turn_context
+            .client
+            .get_model_family()
+            .await
+            .supports_parallel_tool_calls;
+
+        Prompt {
+            input: input.to_vec(),
+            tools: router.specs(),
+            parallel_tool_calls: model_supports_parallel
+                && sess.enabled(Feature::ParallelToolCalls),
+            base_instructions_override: turn_context.base_instructions.clone(),
+            output_schema: turn_context.final_output_json_schema.clone(),
+        }
+    }
+
     pub(crate) fn get_full_instructions<'a>(&'a self, model: &'a ModelFamily) -> Cow<'a, str> {
         let base = self
             .base_instructions_override

codex-rs/core/src/codex.rs

@@ -77,6 +77,9 @@ use crate::client_common::Prompt;
 use crate::client_common::ResponseEvent;
 use crate::compact::collect_user_messages;
 use crate::config::Config;
+use crate::config::Constrained;
+use crate::config::ConstraintError;
+use crate::config::ConstraintResult;
 use crate::config::GhostSnapshotConfig;
 use crate::config::types::ShellEnvironmentPolicy;
 use crate::context_manager::ContextManager;
@@ -96,6 +99,7 @@ use crate::protocol::ApplyPatchApprovalRequestEvent;
 use crate::protocol::AskForApproval;
 use crate::protocol::BackgroundEventEvent;
 use crate::protocol::DeprecationNoticeEvent;
+use crate::protocol::ErrorEvent;
 use crate::protocol::Event;
 use crate::protocol::EventMsg;
 use crate::protocol::ExecApprovalRequestEvent;
@@ -215,11 +219,10 @@ impl Codex {
         let (tx_sub, rx_sub) = async_channel::bounded(SUBMISSION_CHANNEL_CAPACITY);
         let (tx_event, rx_event) = async_channel::unbounded();
 
-        let loaded_skills = if config.features.enabled(Feature::Skills) {
-            Some(skills_manager.skills_for_cwd(&config.cwd))
-        } else {
-            None
-        };
+        let loaded_skills = config
+            .features
+            .enabled(Feature::Skills)
+            .then(|| skills_manager.skills_for_cwd(&config.cwd));
 
         if let Some(outcome) = &loaded_skills {
             for err in &outcome.errors {
@@ -246,7 +249,7 @@ impl Codex {
 
         let config = Arc::new(config);
         if config.features.enabled(Feature::RemoteModels)
-            && let Err(err) = models_manager.refresh_available_models(&config).await
+            && let Err(err) = models_manager.try_refresh_available_models(&config).await
         {
             error!("failed to refresh available models: {err:?}");
         }
@@ -260,7 +263,7 @@ impl Codex {
             user_instructions,
             base_instructions: config.base_instructions.clone(),
             compact_prompt: config.compact_prompt.clone(),
-            approval_policy: config.approval_policy,
+            approval_policy: config.approval_policy.clone(),
             sandbox_policy: config.sandbox_policy.clone(),
             cwd: config.cwd.clone(),
             original_config_do_not_use: Arc::clone(&config),
@@ -411,7 +414,7 @@ pub(crate) struct SessionConfiguration {
     compact_prompt: Option<String>,
 
     /// When to escalate for approval for execution
-    approval_policy: AskForApproval,
+    approval_policy: Constrained<AskForApproval>,
     /// How to sandbox commands executed in the system
     sandbox_policy: SandboxPolicy,
 
@@ -434,7 +437,7 @@ pub(crate) struct SessionConfiguration {
 }
 
 impl SessionConfiguration {
-    pub(crate) fn apply(&self, updates: &SessionSettingsUpdate) -> Self {
+    pub(crate) fn apply(&self, updates: &SessionSettingsUpdate) -> ConstraintResult<Self> {
         let mut next_configuration = self.clone();
         if let Some(model) = updates.model.clone() {
             next_configuration.model = model;
@@ -446,7 +449,7 @@ impl SessionConfiguration {
             next_configuration.model_reasoning_summary = summary;
         }
         if let Some(approval_policy) = updates.approval_policy {
-            next_configuration.approval_policy = approval_policy;
+            next_configuration.approval_policy.set(approval_policy)?;
         }
         if let Some(sandbox_policy) = updates.sandbox_policy.clone() {
             next_configuration.sandbox_policy = sandbox_policy;
@@ -454,7 +457,7 @@ impl SessionConfiguration {
         if let Some(cwd) = updates.cwd.clone() {
             next_configuration.cwd = cwd;
         }
-        next_configuration
+        Ok(next_configuration)
     }
 }
 
@@ -489,6 +492,7 @@ impl Session {
         session_configuration: &SessionConfiguration,
         per_turn_config: Config,
         model_family: ModelFamily,
+        models_etag: Option<String>,
         conversation_id: ConversationId,
         sub_id: String,
     ) -> TurnContext {
@@ -502,6 +506,7 @@ impl Session {
             per_turn_config.clone(),
             auth_manager,
             model_family.clone(),
+            models_etag,
             otel_manager,
             provider,
             session_configuration.model_reasoning_effort,
@@ -523,7 +528,7 @@ impl Session {
             base_instructions: session_configuration.base_instructions.clone(),
             compact_prompt: session_configuration.compact_prompt.clone(),
             user_instructions: session_configuration.user_instructions.clone(),
-            approval_policy: session_configuration.approval_policy,
+            approval_policy: session_configuration.approval_policy.value(),
             sandbox_policy: session_configuration.sandbox_policy.clone(),
             shell_environment_policy: per_turn_config.shell_environment_policy.clone(),
             tools_config,
@@ -640,7 +645,7 @@ impl Session {
             config.model_reasoning_summary,
             config.model_context_window,
             config.model_auto_compact_token_limit,
-            config.approval_policy,
+            config.approval_policy.value(),
             config.sandbox_policy.clone(),
             config.mcp_servers.keys().map(String::as_str).collect(),
             config.active_profile.clone(),
@@ -690,7 +695,7 @@ impl Session {
                 session_id: conversation_id,
                 model: session_configuration.model.clone(),
                 model_provider_id: config.model_provider_id.clone(),
-                approval_policy: session_configuration.approval_policy,
+                approval_policy: session_configuration.approval_policy.value(),
                 sandbox_policy: session_configuration.sandbox_policy.clone(),
                 cwd: session_configuration.cwd.clone(),
                 reasoning_effort: session_configuration.model_reasoning_effort,
@@ -762,7 +767,7 @@ impl Session {
     }
 
     async fn record_initial_history(&self, conversation_history: InitialHistory) {
-        let turn_context = self.new_turn(SessionSettingsUpdate::default()).await;
+        let turn_context = self.new_default_turn().await;
         match conversation_history {
             InitialHistory::New => {
                 // Build and record initial items (user instructions + environment context)
@@ -785,7 +790,7 @@ impl Session {
                         }
                     })
                 {
-                    let curr = turn_context.client.get_model();
+                    let curr = turn_context.client.get_model().await;
                     if prev != curr {
                         warn!(
                             "resuming session with different model: previous={prev}, current={curr}"
@@ -821,30 +826,76 @@ impl Session {
         }
     }
 
-    pub(crate) async fn update_settings(&self, updates: SessionSettingsUpdate) {
+    pub(crate) async fn update_settings(
+        &self,
+        updates: SessionSettingsUpdate,
+    ) -> ConstraintResult<()> {
         let mut state = self.state.lock().await;
 
-        state.session_configuration = state.session_configuration.apply(&updates);
-    }
-
-    pub(crate) async fn new_turn(&self, updates: SessionSettingsUpdate) -> Arc<TurnContext> {
-        let sub_id = self.next_internal_sub_id();
-        self.new_turn_with_sub_id(sub_id, updates).await
+        match state.session_configuration.apply(&updates) {
+            Ok(updated) => {
+                state.session_configuration = updated;
+                Ok(())
+            }
+            Err(err) => {
+                let wrapped = ConstraintError {
+                    message: format!("Could not update config: {err}"),
+                };
+                warn!(%wrapped, "rejected session settings update");
+                Err(wrapped)
+            }
+        }
     }
 
     pub(crate) async fn new_turn_with_sub_id(
         &self,
         sub_id: String,
         updates: SessionSettingsUpdate,
-    ) -> Arc<TurnContext> {
+    ) -> ConstraintResult<Arc<TurnContext>> {
         let (session_configuration, sandbox_policy_changed) = {
             let mut state = self.state.lock().await;
-            let session_configuration = state.session_configuration.clone().apply(&updates);
-            let sandbox_policy_changed =
-                state.session_configuration.sandbox_policy != session_configuration.sandbox_policy;
-            state.session_configuration = session_configuration.clone();
-            (session_configuration, sandbox_policy_changed)
+            match state.session_configuration.clone().apply(&updates) {
+                Ok(next) => {
+                    let sandbox_policy_changed =
+                        state.session_configuration.sandbox_policy != next.sandbox_policy;
+                    state.session_configuration = next.clone();
+                    (next, sandbox_policy_changed)
+                }
+                Err(err) => {
+                    drop(state);
+                    let wrapped = ConstraintError {
+                        message: format!("Could not update config: {err}"),
+                    };
+                    self.send_event_raw(Event {
+                        id: sub_id.clone(),
+                        msg: EventMsg::Error(ErrorEvent {
+                            message: wrapped.to_string(),
+                            codex_error_info: Some(CodexErrorInfo::BadRequest),
+                        }),
+                    })
+                    .await;
+                    return Err(wrapped);
+                }
+            }
         };
+
+        Ok(self
+            .new_turn_from_configuration(
+                sub_id,
+                session_configuration,
+                updates.final_output_json_schema,
+                sandbox_policy_changed,
+            )
+            .await)
+    }
+
+    async fn new_turn_from_configuration(
+        &self,
+        sub_id: String,
+        session_configuration: SessionConfiguration,
+        final_output_json_schema: Option<Option<Value>>,
+        sandbox_policy_changed: bool,
+    ) -> Arc<TurnContext> {
         let per_turn_config = Self::build_per_turn_config(&session_configuration);
 
         if sandbox_policy_changed {
@@ -870,6 +921,7 @@ impl Session {
             .models_manager
             .construct_model_family(session_configuration.model.as_str(), &per_turn_config)
             .await;
+        let models_etag = self.services.models_manager.get_models_etag().await;
         let mut turn_context: TurnContext = Self::make_turn_context(
             Some(Arc::clone(&self.services.auth_manager)),
             &self.services.otel_manager,
@@ -877,15 +929,30 @@ impl Session {
             &session_configuration,
             per_turn_config,
             model_family,
+            models_etag,
             self.conversation_id,
             sub_id,
         );
-        if let Some(final_schema) = updates.final_output_json_schema {
+        if let Some(final_schema) = final_output_json_schema {
             turn_context.final_output_json_schema = final_schema;
         }
         Arc::new(turn_context)
     }
 
+    pub(crate) async fn new_default_turn(&self) -> Arc<TurnContext> {
+        self.new_default_turn_with_sub_id(self.next_internal_sub_id())
+            .await
+    }
+
+    pub(crate) async fn new_default_turn_with_sub_id(&self, sub_id: String) -> Arc<TurnContext> {
+        let session_configuration = {
+            let state = self.state.lock().await;
+            state.session_configuration.clone()
+        };
+        self.new_turn_from_configuration(sub_id, session_configuration, None, false)
+            .await
+    }
+
     fn build_environment_update_item(
         &self,
         previous: Option<&Arc<TurnContext>>,
@@ -1271,7 +1338,7 @@ impl Session {
             if let Some(token_usage) = token_usage {
                 state.update_token_info_from_usage(
                     token_usage,
-                    turn_context.client.get_model_context_window(),
+                    turn_context.client.get_model_context_window().await,
                 );
             }
         }
@@ -1283,6 +1350,7 @@ impl Session {
             .clone_history()
             .await
             .estimate_token_count(turn_context)
+            .await
         else {
             return;
         };
@@ -1303,7 +1371,7 @@ impl Session {
             };
 
             if info.model_context_window.is_none() {
-                info.model_context_window = turn_context.client.get_model_context_window();
+                info.model_context_window = turn_context.client.get_model_context_window().await;
             }
 
             state.set_token_info(Some(info));
@@ -1333,7 +1401,7 @@ impl Session {
     }
 
     pub(crate) async fn set_total_tokens_full(&self, turn_context: &TurnContext) {
-        let context_window = turn_context.client.get_model_context_window();
+        let context_window = turn_context.client.get_model_context_window().await;
         if let Some(context_window) = context_window {
             {
                 let mut state = self.state.lock().await;
@@ -1529,8 +1597,7 @@ impl Session {
 
 async fn submission_loop(sess: Arc<Session>, config: Arc<Config>, rx_sub: Receiver<Submission>) {
     // Seed with context in case there is an OverrideTurnContext first.
-    let mut previous_context: Option<Arc<TurnContext>> =
-        Some(sess.new_turn(SessionSettingsUpdate::default()).await);
+    let mut previous_context: Option<Arc<TurnContext>> = Some(sess.new_default_turn().await);
 
     // To break out of this loop, send Op::Shutdown.
     while let Ok(sub) = rx_sub.recv().await {
@@ -1549,6 +1616,7 @@ async fn submission_loop(sess: Arc<Session>, config: Arc<Config>, rx_sub: Receiv
             } => {
                 handlers::override_turn_context(
                     &sess,
+                    sub.id.clone(),
                     SessionSettingsUpdate {
                         cwd,
                         approval_policy,
@@ -1584,8 +1652,8 @@ async fn submission_loop(sess: Arc<Session>, config: Arc<Config>, rx_sub: Receiv
             Op::ListCustomPrompts => {
                 handlers::list_custom_prompts(&sess, sub.id.clone()).await;
             }
-            Op::ListSkills { cwds } => {
-                handlers::list_skills(&sess, sub.id.clone(), cwds).await;
+            Op::ListSkills { cwds, force_reload } => {
+                handlers::list_skills(&sess, sub.id.clone(), cwds, force_reload).await;
             }
             Op::Undo => {
                 handlers::undo(&sess, sub.id.clone()).await;
@@ -1666,8 +1734,21 @@ mod handlers {
         sess.interrupt_task().await;
     }
 
-    pub async fn override_turn_context(sess: &Session, updates: SessionSettingsUpdate) {
-        sess.update_settings(updates).await;
+    pub async fn override_turn_context(
+        sess: &Session,
+        sub_id: String,
+        updates: SessionSettingsUpdate,
+    ) {
+        if let Err(err) = sess.update_settings(updates).await {
+            sess.send_event_raw(Event {
+                id: sub_id,
+                msg: EventMsg::Error(ErrorEvent {
+                    message: err.to_string(),
+                    codex_error_info: Some(CodexErrorInfo::BadRequest),
+                }),
+            })
+            .await;
+        }
     }
 
     pub async fn user_input_or_turn(
@@ -1702,7 +1783,10 @@ mod handlers {
             _ => unreachable!(),
         };
 
-        let current_context = sess.new_turn_with_sub_id(sub_id, updates).await;
+        let Ok(current_context) = sess.new_turn_with_sub_id(sub_id, updates).await else {
+            // new_turn_with_sub_id already emits the error event.
+            return;
+        };
         current_context
             .client
             .get_otel_manager()
@@ -1729,9 +1813,7 @@ mod handlers {
         command: String,
         previous_context: &mut Option<Arc<TurnContext>>,
     ) {
-        let turn_context = sess
-            .new_turn_with_sub_id(sub_id, SessionSettingsUpdate::default())
-            .await;
+        let turn_context = sess.new_default_turn_with_sub_id(sub_id).await;
         sess.spawn_task(
             Arc::clone(&turn_context),
             Vec::new(),
@@ -1885,7 +1967,12 @@ mod handlers {
         sess.send_event_raw(event).await;
     }
 
-    pub async fn list_skills(sess: &Session, sub_id: String, cwds: Vec<PathBuf>) {
+    pub async fn list_skills(
+        sess: &Session,
+        sub_id: String,
+        cwds: Vec<PathBuf>,
+        force_reload: bool,
+    ) {
         let cwds = if cwds.is_empty() {
             let state = sess.state.lock().await;
             vec![state.session_configuration.cwd.clone()]
@@ -1896,7 +1983,7 @@ mod handlers {
             let skills_manager = &sess.services.skills_manager;
             cwds.into_iter()
                 .map(|cwd| {
-                    let outcome = skills_manager.skills_for_cwd(&cwd);
+                    let outcome = skills_manager.skills_for_cwd_with_options(&cwd, force_reload);
                     let errors = super::errors_to_info(&outcome.errors);
                     let skills = super::skills_to_info(&outcome.skills);
                     SkillsListEntry {
@@ -1923,17 +2010,13 @@ mod handlers {
     }
 
     pub async fn undo(sess: &Arc<Session>, sub_id: String) {
-        let turn_context = sess
-            .new_turn_with_sub_id(sub_id, SessionSettingsUpdate::default())
-            .await;
+        let turn_context = sess.new_default_turn_with_sub_id(sub_id).await;
         sess.spawn_task(turn_context, Vec::new(), UndoTask::new())
             .await;
     }
 
     pub async fn compact(sess: &Arc<Session>, sub_id: String) {
-        let turn_context = sess
-            .new_turn_with_sub_id(sub_id, SessionSettingsUpdate::default())
-            .await;
+        let turn_context = sess.new_default_turn_with_sub_id(sub_id).await;
 
         sess.spawn_task(
             Arc::clone(&turn_context),
@@ -1987,9 +2070,7 @@ mod handlers {
         sub_id: String,
         review_request: ReviewRequest,
     ) {
-        let turn_context = sess
-            .new_turn_with_sub_id(sub_id.clone(), SessionSettingsUpdate::default())
-            .await;
+        let turn_context = sess.new_default_turn_with_sub_id(sub_id.clone()).await;
         match resolve_review_request(review_request, config.cwd.as_path()) {
             Ok(resolved) => {
                 spawn_review_thread(
@@ -2029,6 +2110,7 @@ async fn spawn_review_thread(
         .models_manager
         .construct_model_family(&model, &config)
         .await;
+    let models_etag = sess.services.models_manager.get_models_etag().await;
     // For reviews, disable web_search and view_image regardless of global settings.
     let mut review_features = sess.features.clone();
     review_features
@@ -2061,6 +2143,7 @@ async fn spawn_review_thread(
         per_turn_config.clone(),
         auth_manager,
         model_family.clone(),
+        models_etag,
         otel_manager,
         provider,
         per_turn_config.model_reasoning_effort,
@@ -2111,6 +2194,7 @@ fn skills_to_info(skills: &[SkillMetadata]) -> Vec<ProtocolSkillMetadata> {
         .map(|skill| ProtocolSkillMetadata {
             name: skill.name.clone(),
             description: skill.description.clone(),
+            short_description: skill.short_description.clone(),
             path: skill.path.clone(),
             scope: skill.scope,
         })
@@ -2154,6 +2238,7 @@ pub(crate) async fn run_task(
     let auto_compact_limit = turn_context
         .client
         .get_model_family()
+        .await
         .auto_compact_token_limit()
         .unwrap_or(i64::MAX);
     let total_usage_tokens = sess.get_total_token_usage().await;
@@ -2161,19 +2246,15 @@ pub(crate) async fn run_task(
         run_auto_compact(&sess, &turn_context).await;
     }
     let event = EventMsg::TaskStarted(TaskStartedEvent {
-        model_context_window: turn_context.client.get_model_context_window(),
+        model_context_window: turn_context.client.get_model_context_window().await,
     });
     sess.send_event(&turn_context, event).await;
 
-    let skills_outcome = if sess.enabled(Feature::Skills) {
-        Some(
-            sess.services
-                .skills_manager
-                .skills_for_cwd(&turn_context.cwd),
-        )
-    } else {
-        None
-    };
+    let skills_outcome = sess.enabled(Feature::Skills).then(|| {
+        sess.services
+            .skills_manager
+            .skills_for_cwd(&turn_context.cwd)
+    });
 
     let SkillInjections {
         items: skill_items,
@@ -2230,7 +2311,7 @@ pub(crate) async fn run_task(
             .collect::<Vec<String>>();
         match run_turn(
             Arc::clone(&sess),
-            Arc::clone(&turn_context),
+            &turn_context,
             Arc::clone(&turn_diff_tracker),
             turn_input,
             cancellation_token.child_token(),
@@ -2289,6 +2370,36 @@ pub(crate) async fn run_task(
     last_agent_message
 }
 
+pub(crate) async fn refresh_models_and_reset_turn_context(
+    sess: &Arc<Session>,
+    turn_context: &Arc<TurnContext>,
+) {
+    let config = {
+        let state = sess.state.lock().await;
+        state
+            .session_configuration
+            .original_config_do_not_use
+            .clone()
+    };
+    if let Err(err) = sess
+        .services
+        .models_manager
+        .refresh_available_models(&config)
+        .await
+    {
+        error!("failed to refresh models after outdated models error: {err}");
+    }
+    let model = turn_context.client.get_model().await;
+    let model_family = sess
+        .services
+        .models_manager
+        .construct_model_family(&model, &config)
+        .await;
+    let models_etag = sess.services.models_manager.get_models_etag().await;
+    turn_context.client.update_model_family(model_family).await;
+    turn_context.client.update_models_etag(models_etag).await;
+}
+
 async fn run_auto_compact(sess: &Arc<Session>, turn_context: &Arc<TurnContext>) {
     if should_use_remote_compact_task(sess.as_ref(), &turn_context.client.get_provider()) {
         run_inline_remote_auto_compact_task(Arc::clone(sess), Arc::clone(turn_context)).await;
@@ -2301,17 +2412,19 @@ async fn run_auto_compact(sess: &Arc<Session>, turn_context: &Arc<TurnContext>)
     skip_all,
     fields(
         turn_id = %turn_context.sub_id,
-        model = %turn_context.client.get_model(),
+        model = tracing::field::Empty,
         cwd = %turn_context.cwd.display()
     )
 )]
 async fn run_turn(
     sess: Arc<Session>,
-    turn_context: Arc<TurnContext>,
+    turn_context: &Arc<TurnContext>,
     turn_diff_tracker: SharedTurnDiffTracker,
     input: Vec<ResponseItem>,
     cancellation_token: CancellationToken,
 ) -> CodexResult<TurnRunResult> {
+    let model = turn_context.client.get_model().await;
+    tracing::Span::current().record("model", field::display(&model));
     let mcp_tools = sess
         .services
         .mcp_connection_manager
@@ -2320,37 +2433,32 @@ async fn run_turn(
         .list_all_tools()
         .or_cancel(&cancellation_token)
         .await?;
-    let router = Arc::new(ToolRouter::from_config(
-        &turn_context.tools_config,
-        Some(
-            mcp_tools
-                .into_iter()
-                .map(|(name, tool)| (name, tool.tool))
-                .collect(),
-        ),
-    ));
-
-    let model_supports_parallel = turn_context
-        .client
-        .get_model_family()
-        .supports_parallel_tool_calls;
-
-    let prompt = Prompt {
-        input,
-        tools: router.specs(),
-        parallel_tool_calls: model_supports_parallel && sess.enabled(Feature::ParallelToolCalls),
-        base_instructions_override: turn_context.base_instructions.clone(),
-        output_schema: turn_context.final_output_json_schema.clone(),
-    };
 
     let mut retries = 0;
     loop {
+        let router = Arc::new(ToolRouter::from_config(
+            &turn_context.tools_config,
+            Some(
+                mcp_tools
+                    .clone()
+                    .into_iter()
+                    .map(|(name, tool)| (name, tool.tool))
+                    .collect(),
+            ),
+        ));
+        let prompt = Prompt::new(
+            sess.as_ref(),
+            turn_context.as_ref(),
+            router.as_ref(),
+            &input,
+        );
+
         match try_run_turn(
             Arc::clone(&router),
             Arc::clone(&sess),
-            Arc::clone(&turn_context),
+            Arc::clone(turn_context),
             Arc::clone(&turn_diff_tracker),
-            &prompt,
+            &prompt.await,
             cancellation_token.child_token(),
         )
         .await
@@ -2364,13 +2472,13 @@ async fn run_turn(
             Err(CodexErr::EnvVar(var)) => return Err(CodexErr::EnvVar(var)),
             Err(e @ CodexErr::Fatal(_)) => return Err(e),
             Err(e @ CodexErr::ContextWindowExceeded) => {
-                sess.set_total_tokens_full(&turn_context).await;
+                sess.set_total_tokens_full(turn_context).await;
                 return Err(e);
             }
             Err(CodexErr::UsageLimitReached(e)) => {
                 let rate_limits = e.rate_limits.clone();
                 if let Some(rate_limits) = rate_limits {
-                    sess.update_rate_limits(&turn_context, rate_limits).await;
+                    sess.update_rate_limits(turn_context, rate_limits).await;
                 }
                 return Err(CodexErr::UsageLimitReached(e));
             }
@@ -2384,6 +2492,11 @@ async fn run_turn(
                 let max_retries = turn_context.client.get_provider().stream_max_retries();
                 if retries < max_retries {
                     retries += 1;
+                    // Refresh models if we got an outdated models error
+                    if matches!(e, CodexErr::OutdatedModels) {
+                        refresh_models_and_reset_turn_context(&sess, turn_context).await;
+                        continue;
+                    }
                     let delay = match e {
                         CodexErr::Stream(_, Some(delay)) => delay,
                         _ => backoff(retries),
@@ -2396,7 +2509,7 @@ async fn run_turn(
                     // user understands what is happening instead of staring
                     // at a seemingly frozen screen.
                     sess.notify_stream_error(
-                        &turn_context,
+                        turn_context,
                         format!("Reconnecting... {retries}/{max_retries}"),
                         e,
                     )
@@ -2441,7 +2554,7 @@ async fn drain_in_flight(
     skip_all,
     fields(
         turn_id = %turn_context.sub_id,
-        model = %turn_context.client.get_model()
+        model = tracing::field::Empty,
     )
 )]
 async fn try_run_turn(
@@ -2452,11 +2565,13 @@ async fn try_run_turn(
     prompt: &Prompt,
     cancellation_token: CancellationToken,
 ) -> CodexResult<TurnRunResult> {
+    let model = turn_context.client.get_model().await;
+    tracing::Span::current().record("model", field::display(&model));
     let rollout_item = RolloutItem::TurnContext(TurnContextItem {
         cwd: turn_context.cwd.clone(),
         approval_policy: turn_context.approval_policy,
         sandbox_policy: turn_context.sandbox_policy.clone(),
-        model: turn_context.client.get_model(),
+        model,
         effort: turn_context.client.get_reasoning_effort(),
         summary: turn_context.client.get_reasoning_summary(),
     });
@@ -2464,7 +2579,6 @@ async fn try_run_turn(
     sess.persist_rollout_items(&[rollout_item]).await;
     let mut stream = turn_context
         .client
-        .clone()
         .stream(prompt)
         .instrument(trace_span!("stream_request"))
         .or_cancel(&cancellation_token)
@@ -2677,8 +2791,7 @@ pub(crate) use tests::make_session_and_context_with_rx;
 mod tests {
     use super::*;
     use crate::CodexAuth;
-    use crate::config::ConfigOverrides;
-    use crate::config::ConfigToml;
+    use crate::config::ConfigBuilder;
     use crate::exec::ExecToolCallOutput;
     use crate::function_tool::FunctionCallError;
     use crate::shell::default_user_shell;
@@ -2705,6 +2818,7 @@ mod tests {
     use codex_app_server_protocol::AuthMode;
     use codex_protocol::models::ContentItem;
     use codex_protocol::models::ResponseItem;
+    use std::path::Path;
     use std::time::Duration;
     use tokio::time::sleep;
 
@@ -2717,9 +2831,9 @@ mod tests {
     use std::sync::Arc;
     use std::time::Duration as StdDuration;
 
-    #[test]
-    fn reconstruct_history_matches_live_compactions() {
-        let (session, turn_context) = make_session_and_context();
+    #[tokio::test]
+    async fn reconstruct_history_matches_live_compactions() {
+        let (session, turn_context) = make_session_and_context().await;
         let (rollout_items, expected) = sample_rollout(&session, &turn_context);
 
         let reconstructed = session.reconstruct_history_from_rollout(&turn_context, &rollout_items);
@@ -2727,47 +2841,40 @@ mod tests {
         assert_eq!(expected, reconstructed);
     }
 
-    #[test]
-    fn record_initial_history_reconstructs_resumed_transcript() {
-        let (session, turn_context) = make_session_and_context();
+    #[tokio::test]
+    async fn record_initial_history_reconstructs_resumed_transcript() {
+        let (session, turn_context) = make_session_and_context().await;
         let (rollout_items, expected) = sample_rollout(&session, &turn_context);
 
-        tokio_test::block_on(session.record_initial_history(InitialHistory::Resumed(
-            ResumedHistory {
+        session
+            .record_initial_history(InitialHistory::Resumed(ResumedHistory {
                 conversation_id: ConversationId::default(),
                 history: rollout_items,
                 rollout_path: PathBuf::from("/tmp/resume.jsonl"),
-            },
-        )));
+            }))
+            .await;
 
-        let actual = tokio_test::block_on(async {
-            session.state.lock().await.clone_history().get_history()
-        });
+        let actual = session.state.lock().await.clone_history().get_history();
         assert_eq!(expected, actual);
     }
 
-    #[test]
-    fn record_initial_history_reconstructs_forked_transcript() {
-        let (session, turn_context) = make_session_and_context();
+    #[tokio::test]
+    async fn record_initial_history_reconstructs_forked_transcript() {
+        let (session, turn_context) = make_session_and_context().await;
         let (rollout_items, expected) = sample_rollout(&session, &turn_context);
 
-        tokio_test::block_on(session.record_initial_history(InitialHistory::Forked(rollout_items)));
+        session
+            .record_initial_history(InitialHistory::Forked(rollout_items))
+            .await;
 
-        let actual = tokio_test::block_on(async {
-            session.state.lock().await.clone_history().get_history()
-        });
+        let actual = session.state.lock().await.clone_history().get_history();
         assert_eq!(expected, actual);
     }
 
-    #[test]
-    fn set_rate_limits_retains_previous_credits() {
+    #[tokio::test]
+    async fn set_rate_limits_retains_previous_credits() {
         let codex_home = tempfile::tempdir().expect("create temp dir");
-        let config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let config = build_test_config(codex_home.path()).await;
         let config = Arc::new(config);
         let model = ModelsManager::get_model_offline(config.model.as_deref());
         let session_configuration = SessionConfiguration {
@@ -2779,7 +2886,7 @@ mod tests {
             user_instructions: config.user_instructions.clone(),
             base_instructions: config.base_instructions.clone(),
             compact_prompt: config.compact_prompt.clone(),
-            approval_policy: config.approval_policy,
+            approval_policy: config.approval_policy.clone(),
             sandbox_policy: config.sandbox_policy.clone(),
             cwd: config.cwd.clone(),
             original_config_do_not_use: Arc::clone(&config),
@@ -2831,15 +2938,10 @@ mod tests {
         );
     }
 
-    #[test]
-    fn set_rate_limits_updates_plan_type_when_present() {
+    #[tokio::test]
+    async fn set_rate_limits_updates_plan_type_when_present() {
         let codex_home = tempfile::tempdir().expect("create temp dir");
-        let config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let config = build_test_config(codex_home.path()).await;
         let config = Arc::new(config);
         let model = ModelsManager::get_model_offline(config.model.as_deref());
         let session_configuration = SessionConfiguration {
@@ -2851,7 +2953,7 @@ mod tests {
             user_instructions: config.user_instructions.clone(),
             base_instructions: config.base_instructions.clone(),
             compact_prompt: config.compact_prompt.clone(),
-            approval_policy: config.approval_policy,
+            approval_policy: config.approval_policy.clone(),
             sandbox_policy: config.sandbox_policy.clone(),
             cwd: config.cwd.clone(),
             original_config_do_not_use: Arc::clone(&config),
@@ -2929,8 +3031,8 @@ mod tests {
         assert_eq!(expected, got);
     }
 
-    #[test]
-    fn includes_timed_out_message() {
+    #[tokio::test]
+    async fn includes_timed_out_message() {
         let exec = ExecToolCallOutput {
             exit_code: 0,
             stdout: StreamOutput::new(String::new()),
@@ -2939,7 +3041,7 @@ mod tests {
             duration: StdDuration::from_secs(1),
             timed_out: true,
         };
-        let (_, turn_context) = make_session_and_context();
+        let (_, turn_context) = make_session_and_context().await;
 
         let out = format_exec_output_str(&exec, turn_context.truncation_policy);
 
@@ -3012,6 +3114,14 @@ mod tests {
         })
     }
 
+    async fn build_test_config(codex_home: &Path) -> Config {
+        ConfigBuilder::default()
+            .codex_home(codex_home.to_path_buf())
+            .build()
+            .await
+            .expect("load default test config")
+    }
+
     fn otel_manager(
         conversation_id: ConversationId,
         config: &Config,
@@ -3031,15 +3141,10 @@ mod tests {
         )
     }
 
-    pub(crate) fn make_session_and_context() -> (Session, TurnContext) {
+    pub(crate) async fn make_session_and_context() -> (Session, TurnContext) {
         let (tx_event, _rx_event) = async_channel::unbounded();
         let codex_home = tempfile::tempdir().expect("create temp dir");
-        let config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let config = build_test_config(codex_home.path()).await;
         let config = Arc::new(config);
         let conversation_id = ConversationId::default();
         let auth_manager =
@@ -3055,7 +3160,7 @@ mod tests {
             user_instructions: config.user_instructions.clone(),
             base_instructions: config.base_instructions.clone(),
             compact_prompt: config.compact_prompt.clone(),
-            approval_policy: config.approval_policy,
+            approval_policy: config.approval_policy.clone(),
             sandbox_policy: config.sandbox_policy.clone(),
             cwd: config.cwd.clone(),
             original_config_do_not_use: Arc::clone(&config),
@@ -3099,6 +3204,7 @@ mod tests {
             &session_configuration,
             per_turn_config,
             model_family,
+            None,
             conversation_id,
             "turn_id".to_string(),
         );
@@ -3118,19 +3224,14 @@ mod tests {
 
     // Like make_session_and_context, but returns Arc<Session> and the event receiver
     // so tests can assert on emitted events.
-    pub(crate) fn make_session_and_context_with_rx() -> (
+    pub(crate) async fn make_session_and_context_with_rx() -> (
         Arc<Session>,
         Arc<TurnContext>,
         async_channel::Receiver<Event>,
     ) {
         let (tx_event, rx_event) = async_channel::unbounded();
         let codex_home = tempfile::tempdir().expect("create temp dir");
-        let config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let config = build_test_config(codex_home.path()).await;
         let config = Arc::new(config);
         let conversation_id = ConversationId::default();
         let auth_manager =
@@ -3146,7 +3247,7 @@ mod tests {
             user_instructions: config.user_instructions.clone(),
             base_instructions: config.base_instructions.clone(),
             compact_prompt: config.compact_prompt.clone(),
-            approval_policy: config.approval_policy,
+            approval_policy: config.approval_policy.clone(),
             sandbox_policy: config.sandbox_policy.clone(),
             cwd: config.cwd.clone(),
             original_config_do_not_use: Arc::clone(&config),
@@ -3190,6 +3291,7 @@ mod tests {
             &session_configuration,
             per_turn_config,
             model_family,
+            None,
             conversation_id,
             "turn_id".to_string(),
         ));
@@ -3209,7 +3311,7 @@ mod tests {
 
     #[tokio::test]
     async fn record_model_warning_appends_user_message() {
-        let (mut session, turn_context) = make_session_and_context();
+        let (mut session, turn_context) = make_session_and_context().await;
         let mut features = Features::with_defaults();
         features.enable(Feature::ModelWarnings);
         session.features = features;
@@ -3268,7 +3370,7 @@ mod tests {
     #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
     #[test_log::test]
     async fn abort_regular_task_emits_turn_aborted_only() {
-        let (sess, tc, rx) = make_session_and_context_with_rx();
+        let (sess, tc, rx) = make_session_and_context_with_rx().await;
         let input = vec![UserInput::Text {
             text: "hello".to_string(),
         }];
@@ -3297,7 +3399,7 @@ mod tests {
 
     #[tokio::test]
     async fn abort_gracefuly_emits_turn_aborted_only() {
-        let (sess, tc, rx) = make_session_and_context_with_rx();
+        let (sess, tc, rx) = make_session_and_context_with_rx().await;
         let input = vec![UserInput::Text {
             text: "hello".to_string(),
         }];
@@ -3323,7 +3425,7 @@ mod tests {
 
     #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
     async fn abort_review_task_emits_exited_then_aborted_and_records_history() {
-        let (sess, tc, rx) = make_session_and_context_with_rx();
+        let (sess, tc, rx) = make_session_and_context_with_rx().await;
         let input = vec![UserInput::Text {
             text: "start review".to_string(),
         }];
@@ -3371,7 +3473,7 @@ mod tests {
 
     #[tokio::test]
     async fn fatal_tool_error_stops_turn_and_reports_error() {
-        let (session, turn_context, _rx) = make_session_and_context_with_rx();
+        let (session, turn_context, _rx) = make_session_and_context_with_rx().await;
         let tools = {
             session
                 .services
@@ -3534,7 +3636,7 @@ mod tests {
         use crate::turn_diff_tracker::TurnDiffTracker;
         use std::collections::HashMap;
 
-        let (session, mut turn_context_raw) = make_session_and_context();
+        let (session, mut turn_context_raw) = make_session_and_context().await;
         // Ensure policy is NOT OnRequest so the early rejection path triggers
         turn_context_raw.approval_policy = AskForApproval::OnFailure;
         let session = Arc::new(session);
@@ -3665,7 +3767,7 @@ mod tests {
         use crate::sandboxing::SandboxPermissions;
         use crate::turn_diff_tracker::TurnDiffTracker;
 
-        let (session, mut turn_context_raw) = make_session_and_context();
+        let (session, mut turn_context_raw) = make_session_and_context().await;
         turn_context_raw.approval_policy = AskForApproval::OnFailure;
         let session = Arc::new(session);
         let turn_context = Arc::new(turn_context_raw);

codex-rs/core/src/codex_delegate.rs

@@ -366,7 +366,7 @@ mod tests {
             rx_event: rx_events,
         });
 
-        let (session, ctx, _rx_evt) = crate::codex::make_session_and_context_with_rx();
+        let (session, ctx, _rx_evt) = crate::codex::make_session_and_context_with_rx().await;
 
         let (tx_out, rx_out) = bounded(1);
         tx_out

codex-rs/core/src/command_safety/is_dangerous_command.rs

@@ -21,8 +21,11 @@ pub fn requires_initial_appoval(
     match policy {
         AskForApproval::Never | AskForApproval::OnFailure => false,
         AskForApproval::OnRequest => {
-            // In DangerFullAccess, only prompt if the command looks dangerous.
-            if matches!(sandbox_policy, SandboxPolicy::DangerFullAccess) {
+            // In DangerFullAccess or ExternalSandbox, only prompt if the command looks dangerous.
+            if matches!(
+                sandbox_policy,
+                SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. }
+            ) {
                 return command_might_be_dangerous(command);
             }
 
@@ -83,6 +86,7 @@ fn is_dangerous_to_call_with_exec(command: &[String]) -> bool {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use codex_protocol::protocol::NetworkAccess;
 
     fn vec_str(items: &[&str]) -> Vec<String> {
         items.iter().map(std::string::ToString::to_string).collect()
@@ -150,4 +154,23 @@ mod tests {
     fn rm_f_is_dangerous() {
         assert!(command_might_be_dangerous(&vec_str(&["rm", "-f", "/"])));
     }
+
+    #[test]
+    fn external_sandbox_only_prompts_for_dangerous_commands() {
+        let external_policy = SandboxPolicy::ExternalSandbox {
+            network_access: NetworkAccess::Restricted,
+        };
+        assert!(!requires_initial_appoval(
+            AskForApproval::OnRequest,
+            &external_policy,
+            &vec_str(&["ls"]),
+            SandboxPermissions::UseDefault,
+        ));
+        assert!(requires_initial_appoval(
+            AskForApproval::OnRequest,
+            &external_policy,
+            &vec_str(&["rm", "-rf", "/"]),
+            SandboxPermissions::UseDefault,
+        ));
+    }
 }

codex-rs/core/src/compact.rs

@@ -6,6 +6,7 @@ use crate::client_common::ResponseEvent;
 use crate::codex::Session;
 use crate::codex::TurnContext;
 use crate::codex::get_last_assistant_message_from_turn;
+use crate::codex::refresh_models_and_reset_turn_context;
 use crate::error::CodexErr;
 use crate::error::Result as CodexResult;
 use crate::features::Feature;
@@ -55,7 +56,7 @@ pub(crate) async fn run_compact_task(
     input: Vec<UserInput>,
 ) {
     let start_event = EventMsg::TaskStarted(TaskStartedEvent {
-        model_context_window: turn_context.client.get_model_context_window(),
+        model_context_window: turn_context.client.get_model_context_window().await,
     });
     sess.send_event(&turn_context, start_event).await;
     run_compact_task_inner(sess.clone(), turn_context, input).await;
@@ -83,7 +84,7 @@ async fn run_compact_task_inner(
         cwd: turn_context.cwd.clone(),
         approval_policy: turn_context.approval_policy,
         sandbox_policy: turn_context.sandbox_policy.clone(),
-        model: turn_context.client.get_model(),
+        model: turn_context.client.get_model().await,
         effort: turn_context.client.get_reasoning_effort(),
         summary: turn_context.client.get_reasoning_summary(),
     });
@@ -132,6 +133,10 @@ async fn run_compact_task_inner(
             Err(e) => {
                 if retries < max_retries {
                     retries += 1;
+                    if matches!(e, CodexErr::OutdatedModels) {
+                        refresh_models_and_reset_turn_context(&sess, &turn_context).await;
+                        continue;
+                    }
                     let delay = backoff(retries);
                     sess.notify_stream_error(
                         turn_context.as_ref(),
@@ -290,7 +295,7 @@ async fn drain_to_completed(
     turn_context: &TurnContext,
     prompt: &Prompt,
 ) -> CodexResult<()> {
-    let mut stream = turn_context.client.clone().stream(prompt).await?;
+    let mut stream = turn_context.client.stream(prompt).await?;
     loop {
         let maybe_event = stream.next().await;
         let Some(event) = maybe_event else {

codex-rs/core/src/compact_remote.rs

@@ -20,7 +20,7 @@ pub(crate) async fn run_inline_remote_auto_compact_task(
 
 pub(crate) async fn run_remote_compact_task(sess: Arc<Session>, turn_context: Arc<TurnContext>) {
     let start_event = EventMsg::TaskStarted(TaskStartedEvent {
-        model_context_window: turn_context.client.get_model_context_window(),
+        model_context_window: turn_context.client.get_model_context_window().await,
     });
     sess.send_event(&turn_context, start_event).await;
 

codex-rs/core/src/config/constraint.rs

@@ -0,0 +1,233 @@
+use std::fmt;
+use std::sync::Arc;
+
+use thiserror::Error;
+
+#[derive(Debug, Error, PartialEq, Eq)]
+#[error("{message}")]
+pub struct ConstraintError {
+    pub message: String,
+}
+
+impl ConstraintError {
+    pub fn invalid_value(candidate: impl Into<String>, allowed: impl Into<String>) -> Self {
+        Self {
+            message: format!(
+                "value `{}` is not in the allowed set {}",
+                candidate.into(),
+                allowed.into()
+            ),
+        }
+    }
+
+    pub fn empty_field(field_name: impl Into<String>) -> Self {
+        Self {
+            message: format!("field `{}` cannot be empty", field_name.into()),
+        }
+    }
+}
+
+pub type ConstraintResult<T> = Result<T, ConstraintError>;
+
+impl From<ConstraintError> for std::io::Error {
+    fn from(err: ConstraintError) -> Self {
+        std::io::Error::new(std::io::ErrorKind::InvalidInput, err)
+    }
+}
+
+type ConstraintValidator<T> = dyn Fn(&T) -> ConstraintResult<()> + Send + Sync;
+
+#[derive(Clone)]
+pub struct Constrained<T> {
+    value: T,
+    validator: Arc<ConstraintValidator<T>>,
+}
+
+impl<T: Send + Sync> Constrained<T> {
+    pub fn new(
+        initial_value: T,
+        validator: impl Fn(&T) -> ConstraintResult<()> + Send + Sync + 'static,
+    ) -> ConstraintResult<Self> {
+        let validator: Arc<ConstraintValidator<T>> = Arc::new(validator);
+        validator(&initial_value)?;
+        Ok(Self {
+            value: initial_value,
+            validator,
+        })
+    }
+
+    pub fn allow_any(initial_value: T) -> Self {
+        Self {
+            value: initial_value,
+            validator: Arc::new(|_| Ok(())),
+        }
+    }
+
+    pub fn allow_only(value: T) -> Self
+    where
+        T: PartialEq + Send + Sync + fmt::Debug + Clone + 'static,
+    {
+        #[expect(clippy::expect_used)]
+        Self::new(value.clone(), move |candidate| {
+            if *candidate == value {
+                Ok(())
+            } else {
+                Err(ConstraintError::invalid_value(
+                    format!("{candidate:?}"),
+                    format!("{value:?}"),
+                ))
+            }
+        })
+        .expect("initial value should always be valid")
+    }
+
+    /// Allow any value of T, using T's Default as the initial value.
+    pub fn allow_any_from_default() -> Self
+    where
+        T: Default,
+    {
+        Self::allow_any(T::default())
+    }
+
+    pub fn allow_values(initial_value: T, allowed: Vec<T>) -> ConstraintResult<Self>
+    where
+        T: PartialEq + Send + Sync + fmt::Debug + 'static,
+    {
+        Self::new(initial_value, move |candidate| {
+            if allowed.contains(candidate) {
+                Ok(())
+            } else {
+                Err(ConstraintError::invalid_value(
+                    format!("{candidate:?}"),
+                    format!("{allowed:?}"),
+                ))
+            }
+        })
+    }
+
+    pub fn get(&self) -> &T {
+        &self.value
+    }
+
+    pub fn value(&self) -> T
+    where
+        T: Copy,
+    {
+        self.value
+    }
+
+    pub fn can_set(&self, candidate: &T) -> ConstraintResult<()> {
+        (self.validator)(candidate)
+    }
+
+    pub fn set(&mut self, value: T) -> ConstraintResult<()> {
+        (self.validator)(&value)?;
+        self.value = value;
+        Ok(())
+    }
+}
+
+impl<T> std::ops::Deref for Constrained<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.value
+    }
+}
+
+impl<T: fmt::Debug> fmt::Debug for Constrained<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Constrained")
+            .field("value", &self.value)
+            .finish()
+    }
+}
+
+impl<T: PartialEq> PartialEq for Constrained<T> {
+    fn eq(&self, other: &Self) -> bool {
+        self.value == other.value
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn constrained_allow_any_accepts_any_value() {
+        let mut constrained = Constrained::allow_any(5);
+        constrained.set(-10).expect("allow any accepts all values");
+        assert_eq!(constrained.value(), -10);
+    }
+
+    #[test]
+    fn constrained_allow_any_default_uses_default_value() {
+        let constrained = Constrained::<i32>::allow_any_from_default();
+        assert_eq!(constrained.value(), 0);
+    }
+
+    #[test]
+    fn constrained_new_rejects_invalid_initial_value() {
+        let result = Constrained::new(0, |value| {
+            if *value > 0 {
+                Ok(())
+            } else {
+                Err(ConstraintError::invalid_value(
+                    value.to_string(),
+                    "positive values",
+                ))
+            }
+        });
+
+        assert_eq!(
+            result,
+            Err(ConstraintError::invalid_value("0", "positive values"))
+        );
+    }
+
+    #[test]
+    fn constrained_set_rejects_invalid_value_and_leaves_previous() {
+        let mut constrained = Constrained::new(1, |value| {
+            if *value > 0 {
+                Ok(())
+            } else {
+                Err(ConstraintError::invalid_value(
+                    value.to_string(),
+                    "positive values",
+                ))
+            }
+        })
+        .expect("initial value should be accepted");
+
+        let err = constrained
+            .set(-5)
+            .expect_err("negative values should be rejected");
+        assert_eq!(err, ConstraintError::invalid_value("-5", "positive values"));
+        assert_eq!(constrained.value(), 1);
+    }
+
+    #[test]
+    fn constrained_can_set_allows_probe_without_setting() {
+        let constrained = Constrained::new(1, |value| {
+            if *value > 0 {
+                Ok(())
+            } else {
+                Err(ConstraintError::invalid_value(
+                    value.to_string(),
+                    "positive values",
+                ))
+            }
+        })
+        .expect("initial value should be accepted");
+
+        constrained
+            .can_set(&2)
+            .expect("can_set should accept positive value");
+        let err = constrained
+            .can_set(&-1)
+            .expect_err("can_set should reject negative value");
+        assert_eq!(err, ConstraintError::invalid_value("-1", "positive values"));
+        assert_eq!(constrained.value(), 1);
+    }
+}

codex-rs/core/src/config/edit.rs

@@ -694,7 +694,6 @@ mod tests {
     use codex_protocol::openai_models::ReasoningEffort;
     use pretty_assertions::assert_eq;
     use tempfile::tempdir;
-    use tokio::runtime::Builder;
     use toml::Value as TomlValue;
 
     #[test]
@@ -1455,22 +1454,16 @@ model_reasoning_effort = "high"
         assert_eq!(contents, initial_expected);
     }
 
-    #[test]
-    fn blocking_set_asynchronous_helpers_available() {
-        let rt = Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .expect("runtime");
+    #[tokio::test]
+    async fn blocking_set_asynchronous_helpers_available() {
         let tmp = tempdir().expect("tmpdir");
         let codex_home = tmp.path().to_path_buf();
 
-        rt.block_on(async {
-            ConfigEditsBuilder::new(&codex_home)
-                .set_hide_full_access_warning(true)
-                .apply()
-                .await
-                .expect("persist");
-        });
+        ConfigEditsBuilder::new(&codex_home)
+            .set_hide_full_access_warning(true)
+            .apply()
+            .await
+            .expect("persist");
 
         let raw = std::fs::read_to_string(codex_home.join(CONFIG_TOML_FILE)).expect("read config");
         let notice = toml::from_str::<TomlValue>(&raw)

codex-rs/core/src/config/mod.rs

@@ -12,6 +12,8 @@ use crate::config::types::ShellEnvironmentPolicy;
 use crate::config::types::ShellEnvironmentPolicyToml;
 use crate::config::types::Tui;
 use crate::config::types::UriBasedFileOpener;
+use crate::config_loader::ConfigRequirements;
+use crate::config_loader::LoaderOverrides;
 use crate::config_loader::load_config_layers_state;
 use crate::features::Feature;
 use crate::features::FeatureOverrides;
@@ -26,7 +28,6 @@ use crate::project_doc::DEFAULT_PROJECT_DOC_FILENAME;
 use crate::project_doc::LOCAL_PROJECT_DOC_FILENAME;
 use crate::protocol::AskForApproval;
 use crate::protocol::SandboxPolicy;
-use crate::util::resolve_path;
 use codex_app_server_protocol::Tools;
 use codex_app_server_protocol::UserSavedConfig;
 use codex_protocol::config_types::ForcedLoginMethod;
@@ -54,10 +55,14 @@ use crate::config::profile::ConfigProfile;
 use toml::Value as TomlValue;
 use toml_edit::DocumentMut;
 
+mod constraint;
 pub mod edit;
 pub mod profile;
 pub mod service;
 pub mod types;
+pub use constraint::Constrained;
+pub use constraint::ConstraintError;
+pub use constraint::ConstraintResult;
 
 pub use service::ConfigService;
 pub use service::ConfigServiceError;
@@ -106,7 +111,7 @@ pub struct Config {
     pub model_provider: ModelProviderInfo,
 
     /// Approval policy for executing commands.
-    pub approval_policy: AskForApproval,
+    pub approval_policy: Constrained<AskForApproval>,
 
     pub sandbox_policy: SandboxPolicy,
 
@@ -301,41 +306,108 @@ pub struct Config {
     pub otel: crate::config::types::OtelConfig,
 }
 
-impl Config {
-    pub async fn load_with_cli_overrides(
-        cli_overrides: Vec<(String, TomlValue)>,
-        overrides: ConfigOverrides,
-    ) -> std::io::Result<Self> {
-        let codex_home = find_codex_home()?;
+#[derive(Debug, Clone, Default)]
+pub struct ConfigBuilder {
+    codex_home: Option<PathBuf>,
+    cli_overrides: Option<Vec<(String, TomlValue)>>,
+    harness_overrides: Option<ConfigOverrides>,
+    loader_overrides: Option<LoaderOverrides>,
+}
 
-        let root_value = load_resolved_config(
-            &codex_home,
+impl ConfigBuilder {
+    pub fn codex_home(mut self, codex_home: PathBuf) -> Self {
+        self.codex_home = Some(codex_home);
+        self
+    }
+
+    pub fn cli_overrides(mut self, cli_overrides: Vec<(String, TomlValue)>) -> Self {
+        self.cli_overrides = Some(cli_overrides);
+        self
+    }
+
+    pub fn harness_overrides(mut self, harness_overrides: ConfigOverrides) -> Self {
+        self.harness_overrides = Some(harness_overrides);
+        self
+    }
+
+    pub fn loader_overrides(mut self, loader_overrides: LoaderOverrides) -> Self {
+        self.loader_overrides = Some(loader_overrides);
+        self
+    }
+
+    pub async fn build(self) -> std::io::Result<Config> {
+        let Self {
+            codex_home,
             cli_overrides,
-            crate::config_loader::LoaderOverrides::default(),
+            harness_overrides,
+            loader_overrides,
+        } = self;
+        let codex_home = codex_home.map_or_else(find_codex_home, std::io::Result::Ok)?;
+        let cli_overrides = cli_overrides.unwrap_or_default();
+        let harness_overrides = harness_overrides.unwrap_or_default();
+        let loader_overrides = loader_overrides.unwrap_or_default();
+        let config_layer_stack =
+            load_config_layers_state(&codex_home, &cli_overrides, loader_overrides).await?;
+        let merged_toml = config_layer_stack.effective_config();
+
+        // Note that each layer in ConfigLayerStack should have resolved
+        // relative paths to absolute paths based on the parent folder of the
+        // respective config file, so we should be safe to deserialize without
+        // AbsolutePathBufGuard here.
+        let config_toml: ConfigToml = merged_toml
+            .try_into()
+            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
+        Config::load_config_with_requirements(
+            config_toml,
+            harness_overrides,
+            codex_home,
+            config_layer_stack.requirements().clone(),
         )
-        .await?;
-
-        let cfg = deserialize_config_toml_with_base(root_value, &codex_home).map_err(|e| {
-            tracing::error!("Failed to deserialize overridden config: {e}");
-            e
-        })?;
-
-        Self::load_from_base_config_with_overrides(cfg, overrides, codex_home)
     }
 }
 
+impl Config {
+    /// This is the preferred way to create an instance of [Config].
+    pub async fn load_with_cli_overrides(
+        cli_overrides: Vec<(String, TomlValue)>,
+    ) -> std::io::Result<Self> {
+        ConfigBuilder::default()
+            .cli_overrides(cli_overrides)
+            .build()
+            .await
+    }
+
+    /// This is a secondary way of creating [Config], which is appropriate when
+    /// the harness is meant to be used with a specific configuration that
+    /// ignores user settings. For example, the `codex exec` subcommand is
+    /// designed to use [AskForApproval::Never] exclusively.
+    ///
+    /// Further, [ConfigOverrides] contains some options that are not supported
+    /// in [ConfigToml], such as `cwd` and `codex_linux_sandbox_exe`.
+    pub async fn load_with_cli_overrides_and_harness_overrides(
+        cli_overrides: Vec<(String, TomlValue)>,
+        harness_overrides: ConfigOverrides,
+    ) -> std::io::Result<Self> {
+        ConfigBuilder::default()
+            .cli_overrides(cli_overrides)
+            .harness_overrides(harness_overrides)
+            .build()
+            .await
+    }
+}
+
+/// DEPRECATED: Use [Config::load_with_cli_overrides()] instead because working
+/// with [ConfigToml] directly means that [ConfigRequirements] have not been
+/// applied yet, which risks failing to enforce required constraints.
 pub async fn load_config_as_toml_with_cli_overrides(
     codex_home: &Path,
     cli_overrides: Vec<(String, TomlValue)>,
 ) -> std::io::Result<ConfigToml> {
-    let root_value = load_resolved_config(
-        codex_home,
-        cli_overrides,
-        crate::config_loader::LoaderOverrides::default(),
-    )
-    .await?;
+    let config_layer_stack =
+        load_config_layers_state(codex_home, &cli_overrides, LoaderOverrides::default()).await?;
 
-    let cfg = deserialize_config_toml_with_base(root_value, codex_home).map_err(|e| {
+    let merged_toml = config_layer_stack.effective_config();
+    let cfg = deserialize_config_toml_with_base(merged_toml, codex_home).map_err(|e| {
         tracing::error!("Failed to deserialize overridden config: {e}");
         e
     })?;
@@ -343,15 +415,6 @@ pub async fn load_config_as_toml_with_cli_overrides(
     Ok(cfg)
 }
 
-async fn load_resolved_config(
-    codex_home: &Path,
-    cli_overrides: Vec<(String, TomlValue)>,
-    overrides: crate::config_loader::LoaderOverrides,
-) -> std::io::Result<TomlValue> {
-    let layers = load_config_layers_state(codex_home, &cli_overrides, overrides).await?;
-    Ok(layers.effective_config())
-}
-
 fn deserialize_config_toml_with_base(
     root_value: TomlValue,
     config_base_dir: &Path,
@@ -367,13 +430,18 @@ fn deserialize_config_toml_with_base(
 pub async fn load_global_mcp_servers(
     codex_home: &Path,
 ) -> std::io::Result<BTreeMap<String, McpServerConfig>> {
-    let root_value = load_resolved_config(
-        codex_home,
-        Vec::new(),
-        crate::config_loader::LoaderOverrides::default(),
-    )
-    .await?;
-    let Some(servers_value) = root_value.get("mcp_servers") else {
+    // In general, Config::load_with_cli_overrides() should be used to load the
+    // full config with requirements.toml applied, but in this case, we need
+    // access to the raw TOML in order to warn the user about deprecated fields.
+    //
+    // Note that a more precise way to do this would be to audit the individual
+    // config layers for deprecated fields rather than reporting on the merged
+    // result.
+    let cli_overrides = Vec::<(String, TomlValue)>::new();
+    let config_layer_stack =
+        load_config_layers_state(codex_home, &cli_overrides, LoaderOverrides::default()).await?;
+    let merged_toml = config_layer_stack.effective_config();
+    let Some(servers_value) = merged_toml.get("mcp_servers") else {
         return Ok(BTreeMap::new());
     };
 
@@ -688,8 +756,8 @@ pub struct ConfigToml {
     pub notice: Option<Notice>,
 
     /// Legacy, now use features
-    pub experimental_instructions_file: Option<PathBuf>,
-    pub experimental_compact_prompt_file: Option<PathBuf>,
+    pub experimental_instructions_file: Option<AbsolutePathBuf>,
+    pub experimental_compact_prompt_file: Option<AbsolutePathBuf>,
     pub experimental_use_unified_exec_tool: Option<bool>,
     pub experimental_use_rmcp_client: Option<bool>,
     pub experimental_use_freeform_apply_patch: Option<bool>,
@@ -762,9 +830,11 @@ pub struct GhostSnapshotToml {
     #[serde(alias = "ignore_untracked_files_over_bytes")]
     pub ignore_large_untracked_files: Option<i64>,
     /// Ignore untracked directories that contain this many files or more.
-    /// (Still emits a warning.)
+    /// (Still emits a warning unless warnings are disabled.)
     #[serde(alias = "large_untracked_dir_warning_threshold")]
     pub ignore_large_untracked_dirs: Option<i64>,
+    /// Disable all ghost snapshot warning events.
+    pub disable_warnings: Option<bool>,
 }
 
 #[derive(Debug, PartialEq, Eq)]
@@ -922,12 +992,22 @@ pub fn resolve_oss_provider(
 }
 
 impl Config {
-    /// Meant to be used exclusively for tests: `load_with_overrides()` should
-    /// be used in all other cases.
-    pub fn load_from_base_config_with_overrides(
+    #[cfg(test)]
+    fn load_from_base_config_with_overrides(
         cfg: ConfigToml,
         overrides: ConfigOverrides,
         codex_home: PathBuf,
+    ) -> std::io::Result<Self> {
+        // Note this ignores requirements.toml enforcement for tests.
+        let requirements = ConfigRequirements::default();
+        Self::load_config_with_requirements(cfg, overrides, codex_home, requirements)
+    }
+
+    fn load_config_with_requirements(
+        cfg: ConfigToml,
+        overrides: ConfigOverrides,
+        codex_home: PathBuf,
+        requirements: ConfigRequirements,
     ) -> std::io::Result<Self> {
         let user_instructions = Self::load_instructions(Some(&codex_home));
 
@@ -1026,15 +1106,15 @@ impl Config {
             .or(cfg.approval_policy)
             .unwrap_or_else(|| {
                 if active_project.is_trusted() {
-                    // If no explicit approval policy is set, but we trust cwd, default to OnRequest
                     AskForApproval::OnRequest
                 } else if active_project.is_untrusted() {
-                    // If project is explicitly marked untrusted, require approval for non-safe commands
                     AskForApproval::UnlessTrusted
                 } else {
                     AskForApproval::default()
                 }
             });
+        // TODO(dylan): We should be able to leverage ConfigLayerStack so that
+        // we can reliably check this at every config level.
         let did_user_set_custom_approval_policy_or_sandbox_mode = approval_policy_override
             .is_some()
             || config_profile.approval_policy.is_some()
@@ -1084,6 +1164,11 @@ impl Config {
                 config.ignore_large_untracked_dirs =
                     if threshold > 0 { Some(threshold) } else { None };
             }
+            if let Some(ghost_snapshot) = cfg.ghost_snapshot.as_ref()
+                && let Some(disable_warnings) = ghost_snapshot.disable_warnings
+            {
+                config.disable_warnings = disable_warnings;
+            }
             config
         };
 
@@ -1122,9 +1207,8 @@ impl Config {
             .experimental_instructions_file
             .as_ref()
             .or(cfg.experimental_instructions_file.as_ref());
-        let file_base_instructions = Self::load_override_from_file(
+        let file_base_instructions = Self::try_read_non_empty_file(
             experimental_instructions_path,
-            &resolved_cwd,
             "experimental instructions file",
         )?;
         let base_instructions = base_instructions.or(file_base_instructions);
@@ -1134,9 +1218,8 @@ impl Config {
             .experimental_compact_prompt_file
             .as_ref()
             .or(cfg.experimental_compact_prompt_file.as_ref());
-        let file_compact_prompt = Self::load_override_from_file(
+        let file_compact_prompt = Self::try_read_non_empty_file(
             experimental_compact_prompt_path,
-            &resolved_cwd,
             "experimental compact prompt file",
         )?;
         let compact_prompt = compact_prompt.or(file_compact_prompt);
@@ -1148,6 +1231,16 @@ impl Config {
 
         let check_for_update_on_startup = cfg.check_for_update_on_startup.unwrap_or(true);
 
+        // Ensure that every field of ConfigRequirements is applied to the final
+        // Config.
+        let ConfigRequirements {
+            approval_policy: mut constrained_approval_policy,
+        } = requirements;
+
+        constrained_approval_policy
+            .set(approval_policy)
+            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidInput, format!("{e}")))?;
+
         let config = Self {
             model,
             review_model,
@@ -1156,7 +1249,7 @@ impl Config {
             model_provider_id,
             model_provider,
             cwd: resolved_cwd,
-            approval_policy,
+            approval_policy: constrained_approval_policy,
             sandbox_policy,
             did_user_set_custom_approval_policy_or_sandbox_mode,
             forced_auto_mode_downgraded_on_windows,
@@ -1268,21 +1361,21 @@ impl Config {
         None
     }
 
-    fn load_override_from_file(
-        path: Option<&PathBuf>,
-        cwd: &Path,
-        description: &str,
+    /// If `path` is `Some`, attempts to read the file at the given path and
+    /// returns its contents as a trimmed `String`. If the file is empty, or
+    /// is `Some` but cannot be read, returns an `Err`.
+    fn try_read_non_empty_file(
+        path: Option<&AbsolutePathBuf>,
+        context: &str,
     ) -> std::io::Result<Option<String>> {
-        let Some(p) = path else {
+        let Some(path) = path else {
             return Ok(None);
         };
 
-        let full_path = resolve_path(cwd, p);
-
-        let contents = std::fs::read_to_string(&full_path).map_err(|e| {
+        let contents = std::fs::read_to_string(path).map_err(|e| {
             std::io::Error::new(
                 e.kind(),
-                format!("failed to read {description} {}: {e}", full_path.display()),
+                format!("failed to read {context} {}: {e}", path.display()),
             )
         })?;
 
@@ -1290,7 +1383,7 @@ impl Config {
         if s.is_empty() {
             Err(std::io::Error::new(
                 std::io::ErrorKind::InvalidData,
-                format!("{description} is empty: {}", full_path.display()),
+                format!("{context} is empty: {}", path.display()),
             ))
         } else {
             Ok(Some(s))
@@ -1847,18 +1940,22 @@ trust_level = "trusted"
         std::fs::write(&config_path, "mcp_oauth_credentials_store = \"file\"\n")?;
         std::fs::write(&managed_path, "mcp_oauth_credentials_store = \"keyring\"\n")?;
 
-        let overrides = crate::config_loader::LoaderOverrides {
+        let overrides = LoaderOverrides {
             managed_config_path: Some(managed_path.clone()),
             #[cfg(target_os = "macos")]
             managed_preferences_base64: None,
         };
 
-        let root_value = load_resolved_config(codex_home.path(), Vec::new(), overrides).await?;
-        let cfg =
-            deserialize_config_toml_with_base(root_value, codex_home.path()).map_err(|e| {
-                tracing::error!("Failed to deserialize overridden config: {e}");
-                e
-            })?;
+        let config_layer_stack =
+            load_config_layers_state(codex_home.path(), &Vec::new(), overrides).await?;
+        let cfg = deserialize_config_toml_with_base(
+            config_layer_stack.effective_config(),
+            codex_home.path(),
+        )
+        .map_err(|e| {
+            tracing::error!("Failed to deserialize overridden config: {e}");
+            e
+        })?;
         assert_eq!(
             cfg.mcp_oauth_credentials_store,
             Some(OAuthCredentialsStoreMode::Keyring),
@@ -1962,24 +2059,27 @@ trust_level = "trusted"
         )?;
         std::fs::write(&managed_path, "model = \"managed_config\"\n")?;
 
-        let overrides = crate::config_loader::LoaderOverrides {
+        let overrides = LoaderOverrides {
             managed_config_path: Some(managed_path),
             #[cfg(target_os = "macos")]
             managed_preferences_base64: None,
         };
 
-        let root_value = load_resolved_config(
+        let config_layer_stack = load_config_layers_state(
             codex_home.path(),
-            vec![("model".to_string(), TomlValue::String("cli".to_string()))],
+            &[("model".to_string(), TomlValue::String("cli".to_string()))],
             overrides,
         )
         .await?;
 
-        let cfg =
-            deserialize_config_toml_with_base(root_value, codex_home.path()).map_err(|e| {
-                tracing::error!("Failed to deserialize overridden config: {e}");
-                e
-            })?;
+        let cfg = deserialize_config_toml_with_base(
+            config_layer_stack.effective_config(),
+            codex_home.path(),
+        )
+        .map_err(|e| {
+            tracing::error!("Failed to deserialize overridden config: {e}");
+            e
+        })?;
 
         assert_eq!(cfg.model.as_deref(), Some("managed_config"));
         Ok(())
@@ -2794,7 +2894,9 @@ model = "gpt-5.1-codex"
         std::fs::write(&prompt_path, "  summarize differently  ")?;
 
         let cfg = ConfigToml {
-            experimental_compact_prompt_file: Some(PathBuf::from("compact_prompt.txt")),
+            experimental_compact_prompt_file: Some(AbsolutePathBuf::from_absolute_path(
+                prompt_path,
+            )?),
             ..Default::default()
         };
 
@@ -2945,7 +3047,7 @@ model_verbosity = "high"
                 model_auto_compact_token_limit: None,
                 model_provider_id: "openai".to_string(),
                 model_provider: fixture.openai_provider.clone(),
-                approval_policy: AskForApproval::Never,
+                approval_policy: Constrained::allow_any(AskForApproval::Never),
                 sandbox_policy: SandboxPolicy::new_read_only_policy(),
                 did_user_set_custom_approval_policy_or_sandbox_mode: true,
                 forced_auto_mode_downgraded_on_windows: false,
@@ -3020,7 +3122,7 @@ model_verbosity = "high"
             model_auto_compact_token_limit: None,
             model_provider_id: "openai-chat-completions".to_string(),
             model_provider: fixture.openai_chat_completions_provider.clone(),
-            approval_policy: AskForApproval::UnlessTrusted,
+            approval_policy: Constrained::allow_any(AskForApproval::UnlessTrusted),
             sandbox_policy: SandboxPolicy::new_read_only_policy(),
             did_user_set_custom_approval_policy_or_sandbox_mode: true,
             forced_auto_mode_downgraded_on_windows: false,
@@ -3110,7 +3212,7 @@ model_verbosity = "high"
             model_auto_compact_token_limit: None,
             model_provider_id: "openai".to_string(),
             model_provider: fixture.openai_provider.clone(),
-            approval_policy: AskForApproval::OnFailure,
+            approval_policy: Constrained::allow_any(AskForApproval::OnFailure),
             sandbox_policy: SandboxPolicy::new_read_only_policy(),
             did_user_set_custom_approval_policy_or_sandbox_mode: true,
             forced_auto_mode_downgraded_on_windows: false,
@@ -3186,7 +3288,7 @@ model_verbosity = "high"
             model_auto_compact_token_limit: None,
             model_provider_id: "openai".to_string(),
             model_provider: fixture.openai_provider.clone(),
-            approval_policy: AskForApproval::OnFailure,
+            approval_policy: Constrained::allow_any(AskForApproval::OnFailure),
             sandbox_policy: SandboxPolicy::new_read_only_policy(),
             did_user_set_custom_approval_policy_or_sandbox_mode: true,
             forced_auto_mode_downgraded_on_windows: false,
@@ -3500,26 +3602,21 @@ trust_level = "untrusted"
     }
 
     #[test]
-    fn test_untrusted_project_gets_unless_trusted_approval_policy() -> std::io::Result<()> {
+    fn test_untrusted_project_gets_unless_trusted_approval_policy() -> anyhow::Result<()> {
         let codex_home = TempDir::new()?;
         let test_project_dir = TempDir::new()?;
         let test_path = test_project_dir.path();
 
-        let mut projects = std::collections::HashMap::new();
-        projects.insert(
-            test_path.to_string_lossy().to_string(),
-            ProjectConfig {
-                trust_level: Some(TrustLevel::Untrusted),
-            },
-        );
-
-        let cfg = ConfigToml {
-            projects: Some(projects),
-            ..Default::default()
-        };
-
         let config = Config::load_from_base_config_with_overrides(
-            cfg,
+            ConfigToml {
+                projects: Some(HashMap::from([(
+                    test_path.to_string_lossy().to_string(),
+                    ProjectConfig {
+                        trust_level: Some(TrustLevel::Untrusted),
+                    },
+                )])),
+                ..Default::default()
+            },
             ConfigOverrides {
                 cwd: Some(test_path.to_path_buf()),
                 ..Default::default()
@@ -3529,7 +3626,7 @@ trust_level = "untrusted"
 
         // Verify that untrusted projects get UnlessTrusted approval policy
         assert_eq!(
-            config.approval_policy,
+            config.approval_policy.value(),
             AskForApproval::UnlessTrusted,
             "Expected UnlessTrusted approval policy for untrusted project"
         );

codex-rs/core/src/config/profile.rs

@@ -1,5 +1,5 @@
+use codex_utils_absolute_path::AbsolutePathBuf;
 use serde::Deserialize;
-use std::path::PathBuf;
 
 use crate::protocol::AskForApproval;
 use codex_protocol::config_types::ReasoningSummary;
@@ -21,8 +21,8 @@ pub struct ConfigProfile {
     pub model_reasoning_summary: Option<ReasoningSummary>,
     pub model_verbosity: Option<Verbosity>,
     pub chatgpt_base_url: Option<String>,
-    pub experimental_instructions_file: Option<PathBuf>,
-    pub experimental_compact_prompt_file: Option<PathBuf>,
+    pub experimental_instructions_file: Option<AbsolutePathBuf>,
+    pub experimental_compact_prompt_file: Option<AbsolutePathBuf>,
     pub include_apply_patch_tool: Option<bool>,
     pub experimental_use_unified_exec_tool: Option<bool>,
     pub experimental_use_rmcp_client: Option<bool>,

codex-rs/core/src/config/service.rs

@@ -11,7 +11,7 @@ use crate::path_utils;
 use codex_app_server_protocol::Config as ApiConfig;
 use codex_app_server_protocol::ConfigBatchWriteParams;
 use codex_app_server_protocol::ConfigLayerMetadata;
-use codex_app_server_protocol::ConfigLayerName;
+use codex_app_server_protocol::ConfigLayerSource;
 use codex_app_server_protocol::ConfigReadParams;
 use codex_app_server_protocol::ConfigReadResponse;
 use codex_app_server_protocol::ConfigValueWriteParams;
@@ -20,7 +20,9 @@ use codex_app_server_protocol::ConfigWriteResponse;
 use codex_app_server_protocol::MergeStrategy;
 use codex_app_server_protocol::OverriddenMetadata;
 use codex_app_server_protocol::WriteStatus;
+use codex_utils_absolute_path::AbsolutePathBuf;
 use serde_json::Value as JsonValue;
+use std::borrow::Cow;
 use std::path::Path;
 use std::path::PathBuf;
 use thiserror::Error;
@@ -146,7 +148,13 @@ impl ConfigService {
         Ok(ConfigReadResponse {
             config,
             origins: layers.origins(),
-            layers: params.include_layers.then(|| layers.layers_high_to_low()),
+            layers: params.include_layers.then(|| {
+                layers
+                    .layers_high_to_low()
+                    .iter()
+                    .map(|layer| layer.as_layer())
+                    .collect()
+            }),
         })
     }
 
@@ -194,11 +202,14 @@ impl ConfigService {
         expected_version: Option<String>,
         edits: Vec<(String, JsonValue, MergeStrategy)>,
     ) -> Result<ConfigWriteResponse, ConfigServiceError> {
-        let allowed_path = self.codex_home.join(CONFIG_TOML_FILE);
-        let provided_path = file_path
-            .as_ref()
-            .map(PathBuf::from)
-            .unwrap_or_else(|| allowed_path.clone());
+        let allowed_path =
+            AbsolutePathBuf::resolve_path_against_base(CONFIG_TOML_FILE, &self.codex_home)
+                .map_err(|err| ConfigServiceError::io("failed to resolve user config path", err))?;
+        let provided_path = match file_path {
+            Some(path) => AbsolutePathBuf::from_absolute_path(PathBuf::from(path))
+                .map_err(|err| ConfigServiceError::io("failed to resolve user config path", err))?,
+            None => allowed_path.clone(),
+        };
 
         if !paths_match(&allowed_path, &provided_path) {
             return Err(ConfigServiceError::write(
@@ -211,9 +222,13 @@ impl ConfigService {
             .load_layers_state()
             .await
             .map_err(|err| ConfigServiceError::io("failed to load configuration", err))?;
+        let user_layer = match layers.get_user_layer() {
+            Some(layer) => Cow::Borrowed(layer),
+            None => Cow::Owned(create_empty_user_layer(&allowed_path).await?),
+        };
 
         if let Some(expected) = expected_version.as_deref()
-            && expected != layers.user.version
+            && expected != user_layer.version
         {
             return Err(ConfigServiceError::write(
                 ConfigWriteErrorCode::ConfigVersionConflict,
@@ -221,7 +236,7 @@ impl ConfigService {
             ));
         }
 
-        let mut user_config = layers.user.config.clone();
+        let mut user_config = user_layer.config.clone();
         let mut parsed_segments = Vec::new();
         let mut config_edits = Vec::new();
 
@@ -273,7 +288,7 @@ impl ConfigService {
             )
         })?;
 
-        let updated_layers = layers.with_user_config(user_config.clone());
+        let updated_layers = layers.with_user_config(&provided_path, user_config.clone());
         let effective = updated_layers.effective_config();
         validate_config(&effective).map_err(|err| {
             ConfigServiceError::write(
@@ -296,16 +311,19 @@ impl ConfigService {
             .map(|_| WriteStatus::OkOverridden)
             .unwrap_or(WriteStatus::Ok);
 
-        let file_path = provided_path
-            .canonicalize()
-            .unwrap_or(provided_path.clone())
-            .display()
-            .to_string();
-
         Ok(ConfigWriteResponse {
             status,
-            version: updated_layers.user.version.clone(),
-            file_path,
+            version: updated_layers
+                .get_user_layer()
+                .ok_or_else(|| {
+                    ConfigServiceError::write(
+                        ConfigWriteErrorCode::UserLayerNotFound,
+                        "user layer not found in updated layers",
+                    )
+                })?
+                .version
+                .clone(),
+            file_path: provided_path,
             overridden_metadata: overridden,
         })
     }
@@ -320,6 +338,32 @@ impl ConfigService {
     }
 }
 
+async fn create_empty_user_layer(
+    config_toml: &AbsolutePathBuf,
+) -> Result<ConfigLayerEntry, ConfigServiceError> {
+    let toml_value = match tokio::fs::read_to_string(config_toml).await {
+        Ok(contents) => toml::from_str(&contents).map_err(|e| {
+            ConfigServiceError::toml("failed to parse existing user config.toml", e)
+        })?,
+        Err(e) => {
+            if e.kind() == std::io::ErrorKind::NotFound {
+                tokio::fs::write(config_toml, "").await.map_err(|e| {
+                    ConfigServiceError::io("failed to create empty user config.toml", e)
+                })?;
+                TomlValue::Table(toml::map::Map::new())
+            } else {
+                return Err(ConfigServiceError::io("failed to read user config.toml", e));
+            }
+        }
+    };
+    Ok(ConfigLayerEntry::new(
+        ConfigLayerSource::User {
+            file: config_toml.clone(),
+        },
+        toml_value,
+    ))
+}
+
 fn parse_value(value: JsonValue) -> Result<Option<TomlValue>, String> {
     if value.is_null() {
         return Ok(None);
@@ -470,15 +514,15 @@ fn validate_config(value: &TomlValue) -> Result<(), toml::de::Error> {
     Ok(())
 }
 
-fn paths_match(expected: &Path, provided: &Path) -> bool {
+fn paths_match(expected: impl AsRef<Path>, provided: impl AsRef<Path>) -> bool {
     if let (Ok(expanded_expected), Ok(expanded_provided)) = (
-        path_utils::normalize_for_path_comparison(expected),
-        path_utils::normalize_for_path_comparison(provided),
+        path_utils::normalize_for_path_comparison(&expected),
+        path_utils::normalize_for_path_comparison(&provided),
     ) {
-        return expanded_expected == expanded_provided;
+        expanded_expected == expanded_provided
+    } else {
+        expected.as_ref() == provided.as_ref()
     }
-
-    expected == provided
 }
 
 fn value_at_path<'a>(root: &'a TomlValue, segments: &[String]) -> Option<&'a TomlValue> {
@@ -499,12 +543,27 @@ fn value_at_path<'a>(root: &'a TomlValue, segments: &[String]) -> Option<&'a Tom
     Some(current)
 }
 
-fn override_message(layer: &ConfigLayerName) -> String {
+fn override_message(layer: &ConfigLayerSource) -> String {
     match layer {
-        ConfigLayerName::Mdm => "Overridden by managed policy (mdm)".to_string(),
-        ConfigLayerName::System => "Overridden by managed config (system)".to_string(),
-        ConfigLayerName::SessionFlags => "Overridden by session flags".to_string(),
-        ConfigLayerName::User => "Overridden by user config".to_string(),
+        ConfigLayerSource::Mdm { domain, key: _ } => {
+            format!("Overridden by managed policy (MDM): {domain}")
+        }
+        ConfigLayerSource::System { file } => {
+            format!("Overridden by managed config (system): {}", file.display())
+        }
+        ConfigLayerSource::SessionFlags => "Overridden by session flags".to_string(),
+        ConfigLayerSource::User { file } => {
+            format!("Overridden by user config: {}", file.display())
+        }
+        ConfigLayerSource::LegacyManagedConfigTomlFromFile { file } => {
+            format!(
+                "Overridden by legacy managed_config.toml: {}",
+                file.display()
+            )
+        }
+        ConfigLayerSource::LegacyManagedConfigTomlFromMdm => {
+            "Overridden by legacy managed configuration from MDM".to_string()
+        }
     }
 }
 
@@ -513,7 +572,10 @@ fn compute_override_metadata(
     effective: &TomlValue,
     segments: &[String],
 ) -> Option<OverriddenMetadata> {
-    let user_value = value_at_path(&layers.user.config, segments);
+    let user_value = match layers.get_user_layer() {
+        Some(user_layer) => value_at_path(&user_layer.config, segments),
+        None => return None,
+    };
     let effective_value = value_at_path(effective, segments);
 
     if user_value.is_some() && user_value == effective_value {
@@ -524,8 +586,7 @@ fn compute_override_metadata(
         return None;
     }
 
-    let effective_layer = find_effective_layer(layers, segments);
-    let overriding_layer = effective_layer.unwrap_or_else(|| layers.user.metadata());
+    let overriding_layer = find_effective_layer(layers, segments)?;
     let message = override_message(&overriding_layer.name);
 
     Some(OverriddenMetadata {
@@ -554,23 +615,13 @@ fn find_effective_layer(
     layers: &ConfigLayerStack,
     segments: &[String],
 ) -> Option<ConfigLayerMetadata> {
-    let check =
-        |state: &ConfigLayerEntry| value_at_path(&state.config, segments).map(|_| state.metadata());
+    for layer in layers.layers_high_to_low() {
+        if let Some(meta) = value_at_path(&layer.config, segments).map(|_| layer.metadata()) {
+            return Some(meta);
+        }
+    }
 
-    if let Some(mdm) = &layers.mdm
-        && let Some(meta) = check(mdm)
-    {
-        return Some(meta);
-    }
-    if let Some(system) = &layers.system
-        && let Some(meta) = check(system)
-    {
-        return Some(meta);
-    }
-    if let Some(meta) = check(&layers.session_flags) {
-        return Some(meta);
-    }
-    check(&layers.user)
+    None
 }
 
 #[cfg(test)]
@@ -578,6 +629,7 @@ mod tests {
     use super::*;
     use anyhow::Result;
     use codex_app_server_protocol::AskForApproval;
+    use codex_utils_absolute_path::AbsolutePathBuf;
     use pretty_assertions::assert_eq;
     use tempfile::tempdir;
 
@@ -679,16 +731,19 @@ remote_compaction = true
     #[tokio::test]
     async fn read_includes_origins_and_layers() {
         let tmp = tempdir().expect("tempdir");
-        std::fs::write(tmp.path().join(CONFIG_TOML_FILE), "model = \"user\"").unwrap();
+        let user_path = tmp.path().join(CONFIG_TOML_FILE);
+        std::fs::write(&user_path, "model = \"user\"").unwrap();
+        let user_file = AbsolutePathBuf::try_from(user_path.clone()).expect("user file");
 
         let managed_path = tmp.path().join("managed_config.toml");
         std::fs::write(&managed_path, "approval_policy = \"never\"").unwrap();
+        let managed_file = AbsolutePathBuf::try_from(managed_path.clone()).expect("managed file");
 
         let service = ConfigService::with_overrides(
             tmp.path().to_path_buf(),
             vec![],
             LoaderOverrides {
-                managed_config_path: Some(managed_path),
+                managed_config_path: Some(managed_path.clone()),
                 #[cfg(target_os = "macos")]
                 managed_preferences_base64: None,
             },
@@ -709,12 +764,20 @@ remote_compaction = true
                 .get("approval_policy")
                 .expect("origin")
                 .name,
-            ConfigLayerName::System
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+                file: managed_file.clone()
+            },
         );
         let layers = response.layers.expect("layers present");
-        assert_eq!(layers.first().unwrap().name, ConfigLayerName::System);
-        assert_eq!(layers.get(1).unwrap().name, ConfigLayerName::SessionFlags);
-        assert_eq!(layers.last().unwrap().name, ConfigLayerName::User);
+        assert_eq!(layers.len(), 2, "expected two layers");
+        assert_eq!(
+            layers.first().unwrap().name,
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile { file: managed_file }
+        );
+        assert_eq!(
+            layers.get(1).unwrap().name,
+            ConfigLayerSource::User { file: user_file }
+        );
     }
 
     #[tokio::test]
@@ -728,12 +791,13 @@ remote_compaction = true
 
         let managed_path = tmp.path().join("managed_config.toml");
         std::fs::write(&managed_path, "approval_policy = \"never\"").unwrap();
+        let managed_file = AbsolutePathBuf::try_from(managed_path.clone()).expect("managed file");
 
         let service = ConfigService::with_overrides(
             tmp.path().to_path_buf(),
             vec![],
             LoaderOverrides {
-                managed_config_path: Some(managed_path),
+                managed_config_path: Some(managed_path.clone()),
                 #[cfg(target_os = "macos")]
                 managed_preferences_base64: None,
             },
@@ -766,7 +830,9 @@ remote_compaction = true
                 .get("approval_policy")
                 .expect("origin")
                 .name,
-            ConfigLayerName::System
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+                file: managed_file.clone()
+            }
         );
         assert_eq!(result.status, WriteStatus::Ok);
         assert!(result.overridden_metadata.is_none());
@@ -775,7 +841,8 @@ remote_compaction = true
     #[tokio::test]
     async fn version_conflict_rejected() {
         let tmp = tempdir().expect("tempdir");
-        std::fs::write(tmp.path().join(CONFIG_TOML_FILE), "model = \"user\"").unwrap();
+        let user_path = tmp.path().join(CONFIG_TOML_FILE);
+        std::fs::write(&user_path, "model = \"user\"").unwrap();
 
         let service = ConfigService::new(tmp.path().to_path_buf(), vec![]);
         let error = service
@@ -832,7 +899,7 @@ remote_compaction = true
             tmp.path().to_path_buf(),
             vec![],
             LoaderOverrides {
-                managed_config_path: Some(managed_path),
+                managed_config_path: Some(managed_path.clone()),
                 #[cfg(target_os = "macos")]
                 managed_preferences_base64: None,
             },
@@ -862,10 +929,13 @@ remote_compaction = true
     #[tokio::test]
     async fn read_reports_managed_overrides_user_and_session_flags() {
         let tmp = tempdir().expect("tempdir");
-        std::fs::write(tmp.path().join(CONFIG_TOML_FILE), "model = \"user\"").unwrap();
+        let user_path = tmp.path().join(CONFIG_TOML_FILE);
+        std::fs::write(&user_path, "model = \"user\"").unwrap();
+        let user_file = AbsolutePathBuf::try_from(user_path.clone()).expect("user file");
 
         let managed_path = tmp.path().join("managed_config.toml");
         std::fs::write(&managed_path, "model = \"system\"").unwrap();
+        let managed_file = AbsolutePathBuf::try_from(managed_path.clone()).expect("managed file");
 
         let cli_overrides = vec![(
             "model".to_string(),
@@ -876,7 +946,7 @@ remote_compaction = true
             tmp.path().to_path_buf(),
             cli_overrides,
             LoaderOverrides {
-                managed_config_path: Some(managed_path),
+                managed_config_path: Some(managed_path.clone()),
                 #[cfg(target_os = "macos")]
                 managed_preferences_base64: None,
             },
@@ -892,12 +962,20 @@ remote_compaction = true
         assert_eq!(response.config.model.as_deref(), Some("system"));
         assert_eq!(
             response.origins.get("model").expect("origin").name,
-            ConfigLayerName::System
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+                file: managed_file.clone()
+            },
         );
         let layers = response.layers.expect("layers");
-        assert_eq!(layers.first().unwrap().name, ConfigLayerName::System);
-        assert_eq!(layers.get(1).unwrap().name, ConfigLayerName::SessionFlags);
-        assert_eq!(layers.get(2).unwrap().name, ConfigLayerName::User);
+        assert_eq!(
+            layers.first().unwrap().name,
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile { file: managed_file }
+        );
+        assert_eq!(layers.get(1).unwrap().name, ConfigLayerSource::SessionFlags);
+        assert_eq!(
+            layers.get(2).unwrap().name,
+            ConfigLayerSource::User { file: user_file }
+        );
     }
 
     #[tokio::test]
@@ -907,12 +985,13 @@ remote_compaction = true
 
         let managed_path = tmp.path().join("managed_config.toml");
         std::fs::write(&managed_path, "approval_policy = \"never\"").unwrap();
+        let managed_file = AbsolutePathBuf::try_from(managed_path.clone()).expect("managed file");
 
         let service = ConfigService::with_overrides(
             tmp.path().to_path_buf(),
             vec![],
             LoaderOverrides {
-                managed_config_path: Some(managed_path),
+                managed_config_path: Some(managed_path.clone()),
                 #[cfg(target_os = "macos")]
                 managed_preferences_base64: None,
             },
@@ -931,7 +1010,10 @@ remote_compaction = true
 
         assert_eq!(result.status, WriteStatus::OkOverridden);
         let overridden = result.overridden_metadata.expect("overridden metadata");
-        assert_eq!(overridden.overriding_layer.name, ConfigLayerName::System);
+        assert_eq!(
+            overridden.overriding_layer.name,
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile { file: managed_file }
+        );
         assert_eq!(overridden.effective_value, serde_json::json!("never"));
     }
 

codex-rs/core/src/config/types.rs

@@ -474,17 +474,17 @@ pub type EnvironmentVariablePattern = WildMatchPattern<'*', '?'>;
 /// Deriving the `env` based on this policy works as follows:
 /// 1. Create an initial map based on the `inherit` policy.
 /// 2. If `ignore_default_excludes` is false, filter the map using the default
-///    exclude pattern(s), which are: `"*KEY*"` and `"*TOKEN*"`.
+///    exclude pattern(s), which are: `"*KEY*"`, `"*SECRET*"`, and `"*TOKEN*"`.
 /// 3. If `exclude` is not empty, filter the map using the provided patterns.
 /// 4. Insert any entries from `r#set` into the map.
 /// 5. If non-empty, filter the map using the `include_only` patterns.
-#[derive(Debug, Clone, PartialEq, Default)]
+#[derive(Debug, Clone, PartialEq)]
 pub struct ShellEnvironmentPolicy {
     /// Starting point when building the environment.
     pub inherit: ShellEnvironmentPolicyInherit,
 
     /// True to skip the check to exclude default environment variables that
-    /// contain "KEY" or "TOKEN" in their name.
+    /// contain "KEY", "SECRET", or "TOKEN" in their name. Defaults to true.
     pub ignore_default_excludes: bool,
 
     /// Environment variable names to exclude from the environment.
@@ -504,7 +504,7 @@ impl From<ShellEnvironmentPolicyToml> for ShellEnvironmentPolicy {
     fn from(toml: ShellEnvironmentPolicyToml) -> Self {
         // Default to inheriting the full environment when not specified.
         let inherit = toml.inherit.unwrap_or(ShellEnvironmentPolicyInherit::All);
-        let ignore_default_excludes = toml.ignore_default_excludes.unwrap_or(false);
+        let ignore_default_excludes = toml.ignore_default_excludes.unwrap_or(true);
         let exclude = toml
             .exclude
             .unwrap_or_default()
@@ -531,6 +531,19 @@ impl From<ShellEnvironmentPolicyToml> for ShellEnvironmentPolicy {
     }
 }
 
+impl Default for ShellEnvironmentPolicy {
+    fn default() -> Self {
+        Self {
+            inherit: ShellEnvironmentPolicyInherit::All,
+            ignore_default_excludes: true,
+            exclude: Vec::new(),
+            r#set: HashMap::new(),
+            include_only: Vec::new(),
+            use_profile: false,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

codex-rs/core/src/config_loader/README.md

@@ -16,7 +16,7 @@ Exported from `codex_core::config_loader`:
   - `origins() -> HashMap<String, ConfigLayerMetadata>`
   - `layers_high_to_low() -> Vec<ConfigLayer>`
   - `with_user_config(user_config) -> ConfigLayerStack`
-- `ConfigLayerEntry` (one layer’s `{name, source, config, version}`)
+- `ConfigLayerEntry` (one layer’s `{name, config, version}`; `name` carries source metadata)
 - `LoaderOverrides` (test/override hooks for managed config sources)
 - `merge_toml_values(base, overlay)` (public helper used elsewhere)
 
@@ -61,4 +61,3 @@ Implementation is split by concern:
 - `merge.rs`: recursive TOML merge.
 - `fingerprint.rs`: stable per-layer hashing and per-key origins traversal.
 - `macos.rs`: managed preferences integration (macOS only).
-

codex-rs/core/src/config_loader/config_requirements.rs

@@ -0,0 +1,107 @@
+use codex_protocol::protocol::AskForApproval;
+use serde::Deserialize;
+
+use crate::config::Constrained;
+use crate::config::ConstraintError;
+
+/// Normalized version of [`ConfigRequirementsToml`] after deserialization and
+/// normalization.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ConfigRequirements {
+    pub approval_policy: Constrained<AskForApproval>,
+}
+
+impl Default for ConfigRequirements {
+    fn default() -> Self {
+        Self {
+            approval_policy: Constrained::allow_any_from_default(),
+        }
+    }
+}
+
+/// Base config deserialized from /etc/codex/requirements.toml or MDM.
+#[derive(Deserialize, Debug, Clone, Default, PartialEq)]
+pub struct ConfigRequirementsToml {
+    pub allowed_approval_policies: Option<Vec<AskForApproval>>,
+}
+
+impl ConfigRequirementsToml {
+    /// For every field in `other` that is `Some`, if the corresponding field in
+    /// `self` is `None`, copy the value from `other` into `self`.
+    pub fn merge_unset_fields(&mut self, mut other: ConfigRequirementsToml) {
+        macro_rules! fill_missing_take {
+            ($base:expr, $other:expr, { $($field:ident),+ $(,)? }) => {
+                $(
+                    if $base.$field.is_none() {
+                        if let Some(value) = $other.$field.take() {
+                            $base.$field = Some(value);
+                        }
+                    }
+                )+
+            };
+        }
+
+        fill_missing_take!(self, other, { allowed_approval_policies });
+    }
+}
+
+impl TryFrom<ConfigRequirementsToml> for ConfigRequirements {
+    type Error = ConstraintError;
+
+    fn try_from(toml: ConfigRequirementsToml) -> Result<Self, Self::Error> {
+        let approval_policy: Constrained<AskForApproval> = match toml.allowed_approval_policies {
+            Some(policies) => {
+                let default_value = AskForApproval::default();
+                if policies.contains(&default_value) {
+                    Constrained::allow_values(default_value, policies)?
+                } else if let Some(first) = policies.first() {
+                    Constrained::allow_values(*first, policies)?
+                } else {
+                    return Err(ConstraintError::empty_field("allowed_approval_policies"));
+                }
+            }
+            None => Constrained::allow_any_from_default(),
+        };
+        Ok(ConfigRequirements { approval_policy })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use anyhow::Result;
+    use pretty_assertions::assert_eq;
+    use toml::from_str;
+
+    #[test]
+    fn merge_unset_fields_only_fills_missing_values() -> Result<()> {
+        let source: ConfigRequirementsToml = from_str(
+            r#"
+                allowed_approval_policies = ["on-request"]
+            "#,
+        )?;
+
+        let mut empty_target: ConfigRequirementsToml = from_str(
+            r#"
+                # intentionally left unset
+            "#,
+        )?;
+        empty_target.merge_unset_fields(source.clone());
+        assert_eq!(
+            empty_target.allowed_approval_policies,
+            Some(vec![AskForApproval::OnRequest])
+        );
+
+        let mut populated_target: ConfigRequirementsToml = from_str(
+            r#"
+                allowed_approval_policies = ["never"]
+            "#,
+        )?;
+        populated_target.merge_unset_fields(source);
+        assert_eq!(
+            populated_target.allowed_approval_policies,
+            Some(vec![AskForApproval::Never])
+        );
+        Ok(())
+    }
+}

codex-rs/core/src/config_loader/layer_io.rs

@@ -1,7 +1,7 @@
 use super::LoaderOverrides;
+#[cfg(target_os = "macos")]
 use super::macos::load_managed_admin_config_layer;
-use super::overrides::default_empty_table;
-use crate::config::CONFIG_TOML_FILE;
+use codex_utils_absolute_path::AbsolutePathBuf;
 use std::io;
 use std::path::Path;
 use std::path::PathBuf;
@@ -11,11 +11,18 @@ use toml::Value as TomlValue;
 #[cfg(unix)]
 const CODEX_MANAGED_CONFIG_SYSTEM_PATH: &str = "/etc/codex/managed_config.toml";
 
+#[derive(Debug, Clone)]
+pub(super) struct MangedConfigFromFile {
+    pub managed_config: TomlValue,
+    pub file: AbsolutePathBuf,
+}
+
 #[derive(Debug, Clone)]
 pub(super) struct LoadedConfigLayers {
-    pub base: TomlValue,
-    pub managed_config: Option<TomlValue>,
-    pub managed_preferences: Option<TomlValue>,
+    /// If present, data read from a file such as `/etc/codex/managed_config.toml`.
+    pub managed_config: Option<MangedConfigFromFile>,
+    /// If present, data read from managed preferences (macOS only).
+    pub managed_config_from_mdm: Option<TomlValue>,
 }
 
 pub(super) async fn load_config_layers_internal(
@@ -33,49 +40,52 @@ pub(super) async fn load_config_layers_internal(
         managed_config_path,
     } = overrides;
 
-    let managed_config_path =
-        managed_config_path.unwrap_or_else(|| managed_config_default_path(codex_home));
+    let managed_config_path = AbsolutePathBuf::from_absolute_path(
+        managed_config_path.unwrap_or_else(|| managed_config_default_path(codex_home)),
+    )?;
 
-    let user_config_path = codex_home.join(CONFIG_TOML_FILE);
-    let user_config = read_config_from_path(&user_config_path, true).await?;
-    let managed_config = read_config_from_path(&managed_config_path, false).await?;
+    let managed_config = read_config_from_path(&managed_config_path, false)
+        .await?
+        .map(|managed_config| MangedConfigFromFile {
+            managed_config,
+            file: managed_config_path.clone(),
+        });
 
     #[cfg(target_os = "macos")]
     let managed_preferences =
         load_managed_admin_config_layer(managed_preferences_base64.as_deref()).await?;
 
     #[cfg(not(target_os = "macos"))]
-    let managed_preferences = load_managed_admin_config_layer(None).await?;
+    let managed_preferences = None;
 
     Ok(LoadedConfigLayers {
-        base: user_config.unwrap_or_else(default_empty_table),
         managed_config,
-        managed_preferences,
+        managed_config_from_mdm: managed_preferences,
     })
 }
 
 pub(super) async fn read_config_from_path(
-    path: &Path,
+    path: impl AsRef<Path>,
     log_missing_as_info: bool,
 ) -> io::Result<Option<TomlValue>> {
-    match fs::read_to_string(path).await {
+    match fs::read_to_string(path.as_ref()).await {
         Ok(contents) => match toml::from_str::<TomlValue>(&contents) {
             Ok(value) => Ok(Some(value)),
             Err(err) => {
-                tracing::error!("Failed to parse {}: {err}", path.display());
+                tracing::error!("Failed to parse {}: {err}", path.as_ref().display());
                 Err(io::Error::new(io::ErrorKind::InvalidData, err))
             }
         },
         Err(err) if err.kind() == io::ErrorKind::NotFound => {
             if log_missing_as_info {
-                tracing::info!("{} not found, using defaults", path.display());
+                tracing::info!("{} not found, using defaults", path.as_ref().display());
             } else {
-                tracing::debug!("{} not found", path.display());
+                tracing::debug!("{} not found", path.as_ref().display());
             }
             Ok(None)
         }
         Err(err) => {
-            tracing::error!("Failed to read {}: {err}", path.display());
+            tracing::error!("Failed to read {}: {err}", path.as_ref().display());
             Err(err)
         }
     }

codex-rs/core/src/config_loader/macos.rs

@@ -1,118 +1,100 @@
+use base64::Engine;
+use base64::prelude::BASE64_STANDARD;
+use core_foundation::base::TCFType;
+use core_foundation::string::CFString;
+use core_foundation::string::CFStringRef;
+use std::ffi::c_void;
 use std::io;
+use tokio::task;
 use toml::Value as TomlValue;
 
-#[cfg(target_os = "macos")]
-mod native {
-    use super::*;
-    use base64::Engine;
-    use base64::prelude::BASE64_STANDARD;
-    use core_foundation::base::TCFType;
-    use core_foundation::string::CFString;
-    use core_foundation::string::CFStringRef;
-    use std::ffi::c_void;
-    use tokio::task;
+const MANAGED_PREFERENCES_APPLICATION_ID: &str = "com.openai.codex";
+const MANAGED_PREFERENCES_CONFIG_KEY: &str = "config_toml_base64";
 
-    pub(crate) async fn load_managed_admin_config_layer(
-        override_base64: Option<&str>,
-    ) -> io::Result<Option<TomlValue>> {
-        if let Some(encoded) = override_base64 {
-            let trimmed = encoded.trim();
-            return if trimmed.is_empty() {
-                Ok(None)
-            } else {
-                parse_managed_preferences_base64(trimmed).map(Some)
-            };
-        }
-
-        const LOAD_ERROR: &str = "Failed to load managed preferences configuration";
-
-        match task::spawn_blocking(load_managed_admin_config).await {
-            Ok(result) => result,
-            Err(join_err) => {
-                if join_err.is_cancelled() {
-                    tracing::error!("Managed preferences load task was cancelled");
-                } else {
-                    tracing::error!("Managed preferences load task failed: {join_err}");
-                }
-                Err(io::Error::other(LOAD_ERROR))
-            }
-        }
-    }
-
-    pub(super) fn load_managed_admin_config() -> io::Result<Option<TomlValue>> {
-        #[link(name = "CoreFoundation", kind = "framework")]
-        unsafe extern "C" {
-            fn CFPreferencesCopyAppValue(
-                key: CFStringRef,
-                application_id: CFStringRef,
-            ) -> *mut c_void;
-        }
-
-        const MANAGED_PREFERENCES_APPLICATION_ID: &str = "com.openai.codex";
-        const MANAGED_PREFERENCES_CONFIG_KEY: &str = "config_toml_base64";
-
-        let application_id = CFString::new(MANAGED_PREFERENCES_APPLICATION_ID);
-        let key = CFString::new(MANAGED_PREFERENCES_CONFIG_KEY);
-
-        let value_ref = unsafe {
-            CFPreferencesCopyAppValue(
-                key.as_concrete_TypeRef(),
-                application_id.as_concrete_TypeRef(),
-            )
-        };
-
-        if value_ref.is_null() {
-            tracing::debug!(
-                "Managed preferences for {} key {} not found",
-                MANAGED_PREFERENCES_APPLICATION_ID,
-                MANAGED_PREFERENCES_CONFIG_KEY
-            );
-            return Ok(None);
-        }
-
-        let value = unsafe { CFString::wrap_under_create_rule(value_ref as _) };
-        let contents = value.to_string();
-        let trimmed = contents.trim();
-
-        parse_managed_preferences_base64(trimmed).map(Some)
-    }
-
-    pub(super) fn parse_managed_preferences_base64(encoded: &str) -> io::Result<TomlValue> {
-        let decoded = BASE64_STANDARD.decode(encoded.as_bytes()).map_err(|err| {
-            tracing::error!("Failed to decode managed preferences as base64: {err}");
-            io::Error::new(io::ErrorKind::InvalidData, err)
-        })?;
-
-        let decoded_str = String::from_utf8(decoded).map_err(|err| {
-            tracing::error!("Managed preferences base64 contents were not valid UTF-8: {err}");
-            io::Error::new(io::ErrorKind::InvalidData, err)
-        })?;
-
-        match toml::from_str::<TomlValue>(&decoded_str) {
-            Ok(TomlValue::Table(parsed)) => Ok(TomlValue::Table(parsed)),
-            Ok(other) => {
-                tracing::error!(
-                    "Managed preferences TOML must have a table at the root, found {other:?}",
-                );
-                Err(io::Error::new(
-                    io::ErrorKind::InvalidData,
-                    "managed preferences root must be a table",
-                ))
-            }
-            Err(err) => {
-                tracing::error!("Failed to parse managed preferences TOML: {err}");
-                Err(io::Error::new(io::ErrorKind::InvalidData, err))
-            }
-        }
-    }
-}
-
-#[cfg(target_os = "macos")]
-pub(crate) use native::load_managed_admin_config_layer;
-
-#[cfg(not(target_os = "macos"))]
 pub(crate) async fn load_managed_admin_config_layer(
-    _override_base64: Option<&str>,
+    override_base64: Option<&str>,
 ) -> io::Result<Option<TomlValue>> {
-    Ok(None)
+    if let Some(encoded) = override_base64 {
+        let trimmed = encoded.trim();
+        return if trimmed.is_empty() {
+            Ok(None)
+        } else {
+            parse_managed_preferences_base64(trimmed).map(Some)
+        };
+    }
+
+    const LOAD_ERROR: &str = "Failed to load managed preferences configuration";
+
+    match task::spawn_blocking(load_managed_admin_config).await {
+        Ok(result) => result,
+        Err(join_err) => {
+            if join_err.is_cancelled() {
+                tracing::error!("Managed preferences load task was cancelled");
+            } else {
+                tracing::error!("Managed preferences load task failed: {join_err}");
+            }
+            Err(io::Error::other(LOAD_ERROR))
+        }
+    }
+}
+
+fn load_managed_admin_config() -> io::Result<Option<TomlValue>> {
+    #[link(name = "CoreFoundation", kind = "framework")]
+    unsafe extern "C" {
+        fn CFPreferencesCopyAppValue(key: CFStringRef, application_id: CFStringRef) -> *mut c_void;
+    }
+
+    let application_id = CFString::new(MANAGED_PREFERENCES_APPLICATION_ID);
+    let key = CFString::new(MANAGED_PREFERENCES_CONFIG_KEY);
+
+    let value_ref = unsafe {
+        CFPreferencesCopyAppValue(
+            key.as_concrete_TypeRef(),
+            application_id.as_concrete_TypeRef(),
+        )
+    };
+
+    if value_ref.is_null() {
+        tracing::debug!(
+            "Managed preferences for {} key {} not found",
+            MANAGED_PREFERENCES_APPLICATION_ID,
+            MANAGED_PREFERENCES_CONFIG_KEY
+        );
+        return Ok(None);
+    }
+
+    let value = unsafe { CFString::wrap_under_create_rule(value_ref as _) };
+    let contents = value.to_string();
+    let trimmed = contents.trim();
+
+    parse_managed_preferences_base64(trimmed).map(Some)
+}
+
+fn parse_managed_preferences_base64(encoded: &str) -> io::Result<TomlValue> {
+    let decoded = BASE64_STANDARD.decode(encoded.as_bytes()).map_err(|err| {
+        tracing::error!("Failed to decode managed preferences as base64: {err}");
+        io::Error::new(io::ErrorKind::InvalidData, err)
+    })?;
+
+    let decoded_str = String::from_utf8(decoded).map_err(|err| {
+        tracing::error!("Managed preferences base64 contents were not valid UTF-8: {err}");
+        io::Error::new(io::ErrorKind::InvalidData, err)
+    })?;
+
+    match toml::from_str::<TomlValue>(&decoded_str) {
+        Ok(TomlValue::Table(parsed)) => Ok(TomlValue::Table(parsed)),
+        Ok(other) => {
+            tracing::error!(
+                "Managed preferences TOML must have a table at the root, found {other:?}",
+            );
+            Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "managed preferences root must be a table",
+            ))
+        }
+        Err(err) => {
+            tracing::error!("Failed to parse managed preferences TOML: {err}");
+            Err(io::Error::new(io::ErrorKind::InvalidData, err))
+        }
+    }
 }

codex-rs/core/src/config_loader/mod.rs

@@ -1,5 +1,7 @@
+mod config_requirements;
 mod fingerprint;
 mod layer_io;
+#[cfg(target_os = "macos")]
 mod macos;
 mod merge;
 mod overrides;
@@ -9,66 +11,244 @@ mod state;
 mod tests;
 
 use crate::config::CONFIG_TOML_FILE;
-use codex_app_server_protocol::ConfigLayerName;
+use crate::config_loader::config_requirements::ConfigRequirementsToml;
+use crate::config_loader::layer_io::LoadedConfigLayers;
+use codex_app_server_protocol::ConfigLayerSource;
+use codex_protocol::protocol::AskForApproval;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::Deserialize;
 use std::io;
 use std::path::Path;
-use std::path::PathBuf;
 use toml::Value as TomlValue;
 
+pub use config_requirements::ConfigRequirements;
 pub use merge::merge_toml_values;
 pub use state::ConfigLayerEntry;
 pub use state::ConfigLayerStack;
 pub use state::LoaderOverrides;
 
-const SESSION_FLAGS_SOURCE: &str = "--config";
-const MDM_SOURCE: &str = "com.openai.codex/config_toml_base64";
+/// On Unix systems, load requirements from this file path, if present.
+const DEFAULT_REQUIREMENTS_TOML_FILE_UNIX: &str = "/etc/codex/requirements.toml";
 
-/// Configuration layering pipeline (top overrides bottom):
+/// To build up the set of admin-enforced constraints, we build up from multiple
+/// configuration layers in the following order, but a constraint defined in an
+/// earlier layer cannot be overridden by a later layer:
 ///
-///        +-------------------------+
-///        | Managed preferences (*) |
-///        +-------------------------+
-///                    ^
-///                    |
-///        +-------------------------+
-///        |  managed_config.toml   |
-///        +-------------------------+
-///                    ^
-///                    |
-///        +-------------------------+
-///        |    config.toml (base)   |
-///        +-------------------------+
+/// - admin:    managed preferences (*)
+/// - system    `/etc/codex/requirements.toml`
+///
+/// For backwards compatibility, we also load from
+/// `/etc/codex/managed_config.toml` and map it to
+/// `/etc/codex/requirements.toml`.
+///
+/// Configuration is built up from multiple layers in the following order:
+///
+/// - admin:    managed preferences (*)
+/// - system    `/etc/codex/config.toml`
+/// - user      `${CODEX_HOME}/config.toml`
+/// - cwd       `${PWD}/config.toml`
+/// - tree      parent directories up to root looking for `./.codex/config.toml`
+/// - repo      `$(git rev-parse --show-toplevel)/.codex/config.toml`
+/// - runtime   e.g., --config flags, model selector in UI
 ///
 /// (*) Only available on macOS via managed device profiles.
+///
+/// See https://developers.openai.com/codex/security for details.
 pub async fn load_config_layers_state(
     codex_home: &Path,
     cli_overrides: &[(String, TomlValue)],
     overrides: LoaderOverrides,
 ) -> io::Result<ConfigLayerStack> {
-    let managed_config_path = overrides
-        .managed_config_path
-        .clone()
-        .unwrap_or_else(|| layer_io::managed_config_default_path(codex_home));
+    let mut config_requirements_toml = ConfigRequirementsToml::default();
 
-    let layers = layer_io::load_config_layers_internal(codex_home, overrides).await?;
-    let cli_overrides = overrides::build_cli_overrides_layer(cli_overrides);
+    // TODO(mbolin): Support an entry in MDM for config requirements and use it
+    // with `config_requirements_toml.merge_unset_fields(...)`, if present.
 
-    Ok(ConfigLayerStack {
-        user: ConfigLayerEntry::new(
-            ConfigLayerName::User,
-            codex_home.join(CONFIG_TOML_FILE),
-            layers.base,
-        ),
-        session_flags: ConfigLayerEntry::new(
-            ConfigLayerName::SessionFlags,
-            PathBuf::from(SESSION_FLAGS_SOURCE),
-            cli_overrides,
-        ),
-        system: layers.managed_config.map(|cfg| {
-            ConfigLayerEntry::new(ConfigLayerName::System, managed_config_path.clone(), cfg)
-        }),
-        mdm: layers
-            .managed_preferences
-            .map(|cfg| ConfigLayerEntry::new(ConfigLayerName::Mdm, PathBuf::from(MDM_SOURCE), cfg)),
-    })
+    // Honor /etc/codex/requirements.toml.
+    if cfg!(unix) {
+        load_requirements_toml(
+            &mut config_requirements_toml,
+            DEFAULT_REQUIREMENTS_TOML_FILE_UNIX,
+        )
+        .await?;
+    }
+
+    // Make a best-effort to support the legacy `managed_config.toml` as a
+    // requirements specification.
+    let loaded_config_layers = layer_io::load_config_layers_internal(codex_home, overrides).await?;
+    load_requirements_from_legacy_scheme(
+        &mut config_requirements_toml,
+        loaded_config_layers.clone(),
+    )
+    .await?;
+
+    let mut layers = Vec::<ConfigLayerEntry>::new();
+
+    // TODO(mbolin): Honor managed preferences (macOS only).
+    // TODO(mbolin): Honor /etc/codex/config.toml.
+
+    // Add a layer for $CODEX_HOME/config.toml if it exists. Note if the file
+    // exists, but is malformed, then this error should be propagated to the
+    // user.
+    let user_file = AbsolutePathBuf::resolve_path_against_base(CONFIG_TOML_FILE, codex_home)?;
+    match tokio::fs::read_to_string(&user_file).await {
+        Ok(contents) => {
+            let user_config: TomlValue = toml::from_str(&contents).map_err(|e| {
+                io::Error::new(
+                    io::ErrorKind::InvalidData,
+                    format!(
+                        "Error parsing user config file {}: {e}",
+                        user_file.as_path().display(),
+                    ),
+                )
+            })?;
+            layers.push(ConfigLayerEntry::new(
+                ConfigLayerSource::User { file: user_file },
+                user_config,
+            ));
+        }
+        Err(e) => {
+            if e.kind() != io::ErrorKind::NotFound {
+                return Err(io::Error::new(
+                    e.kind(),
+                    format!(
+                        "Failed to read user config file {}: {e}",
+                        user_file.as_path().display(),
+                    ),
+                ));
+            }
+        }
+    }
+
+    // TODO(mbolin): Add layers for cwd, tree, and repo config files.
+
+    // Add a layer for runtime overrides from the CLI or UI, if any exist.
+    if !cli_overrides.is_empty() {
+        let cli_overrides_layer = overrides::build_cli_overrides_layer(cli_overrides);
+        layers.push(ConfigLayerEntry::new(
+            ConfigLayerSource::SessionFlags,
+            cli_overrides_layer,
+        ));
+    }
+
+    // Make a best-effort to support the legacy `managed_config.toml` as a
+    // config layer on top of everything else. For fields in
+    // `managed_config.toml` that do not have an equivalent in
+    // `ConfigRequirements`, note users can still override these values on a
+    // per-turn basis in the TUI and VS Code.
+    let LoadedConfigLayers {
+        managed_config,
+        managed_config_from_mdm,
+    } = loaded_config_layers;
+    if let Some(config) = managed_config {
+        layers.push(ConfigLayerEntry::new(
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+                file: config.file.clone(),
+            },
+            config.managed_config,
+        ));
+    }
+    if let Some(config) = managed_config_from_mdm {
+        layers.push(ConfigLayerEntry::new(
+            ConfigLayerSource::LegacyManagedConfigTomlFromMdm,
+            config,
+        ));
+    }
+
+    ConfigLayerStack::new(layers, config_requirements_toml.try_into()?)
+}
+
+/// If available, apply requirements from `/etc/codex/requirements.toml` to
+/// `config_requirements_toml` by filling in any unset fields.
+async fn load_requirements_toml(
+    config_requirements_toml: &mut ConfigRequirementsToml,
+    requirements_toml_file: impl AsRef<Path>,
+) -> io::Result<()> {
+    match tokio::fs::read_to_string(&requirements_toml_file).await {
+        Ok(contents) => {
+            let requirements_config: ConfigRequirementsToml =
+                toml::from_str(&contents).map_err(|e| {
+                    io::Error::new(
+                        io::ErrorKind::InvalidData,
+                        format!(
+                            "Error parsing requirements file {}: {e}",
+                            requirements_toml_file.as_ref().display(),
+                        ),
+                    )
+                })?;
+            config_requirements_toml.merge_unset_fields(requirements_config);
+        }
+        Err(e) => {
+            if e.kind() != io::ErrorKind::NotFound {
+                return Err(io::Error::new(
+                    e.kind(),
+                    format!(
+                        "Failed to read requirements file {}: {e}",
+                        requirements_toml_file.as_ref().display(),
+                    ),
+                ));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+async fn load_requirements_from_legacy_scheme(
+    config_requirements_toml: &mut ConfigRequirementsToml,
+    loaded_config_layers: LoadedConfigLayers,
+) -> io::Result<()> {
+    // In this implementation, earlier layers cannot be overwritten by later
+    // layers, so list managed_config_from_mdm first because it has the highest
+    // precedence.
+    let LoadedConfigLayers {
+        managed_config,
+        managed_config_from_mdm,
+    } = loaded_config_layers;
+    for config in [
+        managed_config_from_mdm,
+        managed_config.map(|c| c.managed_config),
+    ]
+    .into_iter()
+    .flatten()
+    {
+        let legacy_config: LegacyManagedConfigToml =
+            config.try_into().map_err(|err: toml::de::Error| {
+                io::Error::new(
+                    io::ErrorKind::InvalidData,
+                    format!("Failed to parse config requirements as TOML: {err}"),
+                )
+            })?;
+
+        let new_requirements_toml = ConfigRequirementsToml::from(legacy_config);
+        config_requirements_toml.merge_unset_fields(new_requirements_toml);
+    }
+
+    Ok(())
+}
+
+/// The legacy mechanism for specifying admin-enforced configuration is to read
+/// from a file like `/etc/codex/managed_config.toml` that has the same
+/// structure as `config.toml` where fields like `approval_policy` can specify
+/// exactly one value rather than a list of allowed values.
+///
+/// If present, re-interpret `managed_config.toml` as a `requirements.toml`
+/// where each specified field is treated as a constraint allowing only that
+/// value.
+#[derive(Deserialize, Debug, Clone, Default, PartialEq)]
+struct LegacyManagedConfigToml {
+    approval_policy: Option<AskForApproval>,
+}
+
+impl From<LegacyManagedConfigToml> for ConfigRequirementsToml {
+    fn from(legacy: LegacyManagedConfigToml) -> Self {
+        let mut config_requirements_toml = ConfigRequirementsToml::default();
+
+        let LegacyManagedConfigToml { approval_policy } = legacy;
+        if let Some(approval_policy) = approval_policy {
+            config_requirements_toml.allowed_approval_policies = Some(vec![approval_policy]);
+        }
+
+        config_requirements_toml
+    }
 }

codex-rs/core/src/config_loader/state.rs

@@ -1,9 +1,12 @@
+use crate::config_loader::ConfigRequirements;
+
 use super::fingerprint::record_origins;
 use super::fingerprint::version_for_toml;
 use super::merge::merge_toml_values;
 use codex_app_server_protocol::ConfigLayer;
 use codex_app_server_protocol::ConfigLayerMetadata;
-use codex_app_server_protocol::ConfigLayerName;
+use codex_app_server_protocol::ConfigLayerSource;
+use codex_utils_absolute_path::AbsolutePathBuf;
 use serde_json::Value as JsonValue;
 use std::collections::HashMap;
 use std::path::PathBuf;
@@ -18,18 +21,16 @@ pub struct LoaderOverrides {
 
 #[derive(Debug, Clone)]
 pub struct ConfigLayerEntry {
-    pub name: ConfigLayerName,
-    pub source: PathBuf,
+    pub name: ConfigLayerSource,
     pub config: TomlValue,
     pub version: String,
 }
 
 impl ConfigLayerEntry {
-    pub fn new(name: ConfigLayerName, source: PathBuf, config: TomlValue) -> Self {
+    pub fn new(name: ConfigLayerSource, config: TomlValue) -> Self {
         let version = version_for_toml(&config);
         Self {
             name,
-            source,
             config,
             version,
         }
@@ -38,7 +39,6 @@ impl ConfigLayerEntry {
     pub fn metadata(&self) -> ConfigLayerMetadata {
         ConfigLayerMetadata {
             name: self.name.clone(),
-            source: self.source.display().to_string(),
             version: self.version.clone(),
         }
     }
@@ -46,7 +46,6 @@ impl ConfigLayerEntry {
     pub fn as_layer(&self) -> ConfigLayer {
         ConfigLayer {
             name: self.name.clone(),
-            source: self.source.display().to_string(),
             version: self.version.clone(),
             config: serde_json::to_value(&self.config).unwrap_or(JsonValue::Null),
         }
@@ -55,34 +54,90 @@ impl ConfigLayerEntry {
 
 #[derive(Debug, Clone)]
 pub struct ConfigLayerStack {
-    pub user: ConfigLayerEntry,
-    pub session_flags: ConfigLayerEntry,
-    pub system: Option<ConfigLayerEntry>,
-    pub mdm: Option<ConfigLayerEntry>,
+    /// Layers are listed from lowest precedence (base) to highest (top), so
+    /// later entries in the Vec override earlier ones.
+    layers: Vec<ConfigLayerEntry>,
+
+    /// Index into [layers] of the user config layer, if any.
+    user_layer_index: Option<usize>,
+
+    /// Constraints that must be enforced when deriving a [Config] from the
+    /// layers.
+    requirements: ConfigRequirements,
 }
 
 impl ConfigLayerStack {
-    pub fn with_user_config(&self, user_config: TomlValue) -> Self {
-        Self {
-            user: ConfigLayerEntry::new(
-                self.user.name.clone(),
-                self.user.source.clone(),
-                user_config,
-            ),
-            session_flags: self.session_flags.clone(),
-            system: self.system.clone(),
-            mdm: self.mdm.clone(),
+    pub fn new(
+        layers: Vec<ConfigLayerEntry>,
+        requirements: ConfigRequirements,
+    ) -> std::io::Result<Self> {
+        let user_layer_index = verify_layer_ordering(&layers)?;
+        Ok(Self {
+            layers,
+            user_layer_index,
+            requirements,
+        })
+    }
+
+    /// Returns the user config layer, if any.
+    pub fn get_user_layer(&self) -> Option<&ConfigLayerEntry> {
+        self.user_layer_index
+            .and_then(|index| self.layers.get(index))
+    }
+
+    pub fn requirements(&self) -> &ConfigRequirements {
+        &self.requirements
+    }
+
+    /// Creates a new [ConfigLayerStack] using the specified values to inject a
+    /// "user layer" into the stack. If such a layer already exists, it is
+    /// replaced; otherwise, it is inserted into the stack at the appropriate
+    /// position based on precedence rules.
+    pub fn with_user_config(&self, config_toml: &AbsolutePathBuf, user_config: TomlValue) -> Self {
+        let user_layer = ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_toml.clone(),
+            },
+            user_config,
+        );
+
+        let mut layers = self.layers.clone();
+        match self.user_layer_index {
+            Some(index) => {
+                layers[index] = user_layer;
+                Self {
+                    layers,
+                    user_layer_index: self.user_layer_index,
+                    requirements: self.requirements.clone(),
+                }
+            }
+            None => {
+                let user_layer_index = match layers
+                    .iter()
+                    .position(|layer| layer.name.precedence() > user_layer.name.precedence())
+                {
+                    Some(index) => {
+                        layers.insert(index, user_layer);
+                        index
+                    }
+                    None => {
+                        layers.push(user_layer);
+                        layers.len() - 1
+                    }
+                };
+                Self {
+                    layers,
+                    user_layer_index: Some(user_layer_index),
+                    requirements: self.requirements.clone(),
+                }
+            }
         }
     }
 
     pub fn effective_config(&self) -> TomlValue {
-        let mut merged = self.user.config.clone();
-        merge_toml_values(&mut merged, &self.session_flags.config);
-        if let Some(system) = &self.system {
-            merge_toml_values(&mut merged, &system.config);
-        }
-        if let Some(mdm) = &self.mdm {
-            merge_toml_values(&mut merged, &mdm.config);
+        let mut merged = TomlValue::Table(toml::map::Map::new());
+        for layer in &self.layers {
+            merge_toml_values(&mut merged, &layer.config);
         }
         merged
     }
@@ -91,38 +146,42 @@ impl ConfigLayerStack {
         let mut origins = HashMap::new();
         let mut path = Vec::new();
 
-        record_origins(
-            &self.user.config,
-            &self.user.metadata(),
-            &mut path,
-            &mut origins,
-        );
-        record_origins(
-            &self.session_flags.config,
-            &self.session_flags.metadata(),
-            &mut path,
-            &mut origins,
-        );
-        if let Some(system) = &self.system {
-            record_origins(&system.config, &system.metadata(), &mut path, &mut origins);
-        }
-        if let Some(mdm) = &self.mdm {
-            record_origins(&mdm.config, &mdm.metadata(), &mut path, &mut origins);
+        for layer in &self.layers {
+            record_origins(&layer.config, &layer.metadata(), &mut path, &mut origins);
         }
 
         origins
     }
 
-    pub fn layers_high_to_low(&self) -> Vec<ConfigLayer> {
-        let mut layers = Vec::new();
-        if let Some(mdm) = &self.mdm {
-            layers.push(mdm.as_layer());
-        }
-        if let Some(system) = &self.system {
-            layers.push(system.as_layer());
-        }
-        layers.push(self.session_flags.as_layer());
-        layers.push(self.user.as_layer());
-        layers
+    /// Returns the highest-precedence to lowest-precedence layers, so
+    /// `ConfigLayerSource::SessionFlags` would be first, if present.
+    pub fn layers_high_to_low(&self) -> Vec<&ConfigLayerEntry> {
+        self.layers.iter().rev().collect()
     }
 }
+
+/// Ensures precedence ordering of config layers is correct. Returns the index
+/// of the user config layer, if any (at most one should exist).
+fn verify_layer_ordering(layers: &[ConfigLayerEntry]) -> std::io::Result<Option<usize>> {
+    if !layers.iter().map(|layer| &layer.name).is_sorted() {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "config layers are not in correct precedence order",
+        ));
+    }
+
+    let mut user_layer_index: Option<usize> = None;
+    for (index, layer) in layers.iter().enumerate() {
+        if matches!(layer.name, ConfigLayerSource::User { .. }) {
+            if user_layer_index.is_some() {
+                return Err(std::io::Error::new(
+                    std::io::ErrorKind::InvalidData,
+                    "multiple user config layers found",
+                ));
+            }
+            user_layer_index = Some(index);
+        }
+    }
+
+    Ok(user_layer_index)
+}

codex-rs/core/src/config_loader/tests.rs

@@ -1,6 +1,11 @@
 use super::LoaderOverrides;
 use super::load_config_layers_state;
 use crate::config::CONFIG_TOML_FILE;
+use crate::config_loader::ConfigRequirements;
+use crate::config_loader::config_requirements::ConfigRequirementsToml;
+use crate::config_loader::load_requirements_toml;
+use codex_protocol::protocol::AskForApproval;
+use pretty_assertions::assert_eq;
 use tempfile::tempdir;
 use toml::Value as TomlValue;
 
@@ -66,13 +71,24 @@ async fn returns_empty_when_all_layers_missing() {
     let layers = load_config_layers_state(tmp.path(), &[] as &[(String, TomlValue)], overrides)
         .await
         .expect("load layers");
-    let base_table = layers.user.config.as_table().expect("base table expected");
+    assert!(
+        layers.get_user_layer().is_none(),
+        "no user layer when CODEX_HOME/config.toml does not exist"
+    );
+
+    let binding = layers.effective_config();
+    let base_table = binding.as_table().expect("base table expected");
     assert!(
         base_table.is_empty(),
         "expected empty base layer when configs missing"
     );
-    assert!(
-        layers.system.is_none(),
+    let num_system_layers = layers
+        .layers_high_to_low()
+        .iter()
+        .filter(|layer| matches!(layer.name, super::ConfigLayerSource::System { .. }))
+        .count();
+    assert_eq!(
+        num_system_layers, 0,
         "managed config layer should be absent when file missing"
     );
 
@@ -136,3 +152,40 @@ flag = true
     );
     assert_eq!(nested.get("flag"), Some(&TomlValue::Boolean(false)));
 }
+
+#[tokio::test(flavor = "current_thread")]
+async fn load_requirements_toml_produces_expected_constraints() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let requirements_file = tmp.path().join("requirements.toml");
+    tokio::fs::write(
+        &requirements_file,
+        r#"
+allowed_approval_policies = ["never", "on-request"]
+"#,
+    )
+    .await?;
+
+    let mut config_requirements_toml = ConfigRequirementsToml::default();
+    load_requirements_toml(&mut config_requirements_toml, &requirements_file).await?;
+
+    assert_eq!(
+        config_requirements_toml.allowed_approval_policies,
+        Some(vec![AskForApproval::Never, AskForApproval::OnRequest])
+    );
+
+    let config_requirements: ConfigRequirements = config_requirements_toml.try_into()?;
+    assert_eq!(
+        config_requirements.approval_policy.value(),
+        AskForApproval::OnRequest
+    );
+    config_requirements
+        .approval_policy
+        .can_set(&AskForApproval::Never)?;
+    assert!(
+        config_requirements
+            .approval_policy
+            .can_set(&AskForApproval::OnFailure)
+            .is_err()
+    );
+    Ok(())
+}

codex-rs/core/src/context_manager/history.rs

@@ -79,8 +79,8 @@ impl ContextManager {
 
     // Estimate token usage using byte-based heuristics from the truncation helpers.
     // This is a coarse lower bound, not a tokenizer-accurate count.
-    pub(crate) fn estimate_token_count(&self, turn_context: &TurnContext) -> Option<i64> {
-        let model_family = turn_context.client.get_model_family();
+    pub(crate) async fn estimate_token_count(&self, turn_context: &TurnContext) -> Option<i64> {
+        let model_family = turn_context.client.get_model_family().await;
         let base_tokens =
             i64::try_from(approx_token_count(model_family.base_instructions.as_str()))
                 .unwrap_or(i64::MAX);

codex-rs/core/src/conversation_manager.rs

@@ -379,9 +379,9 @@ mod tests {
         assert_matches!(truncated2, InitialHistory::New);
     }
 
-    #[test]
-    fn ignores_session_prefix_messages_when_truncating() {
-        let (session, turn_context) = make_session_and_context();
+    #[tokio::test]
+    async fn ignores_session_prefix_messages_when_truncating() {
+        let (session, turn_context) = make_session_and_context().await;
         let mut items = session.build_initial_context(&turn_context);
         items.push(user_msg("feature request"));
         items.push(assistant_msg("ack"));

codex-rs/core/src/default_client.rs

@@ -163,7 +163,9 @@ mod tests {
     #[test]
     fn test_get_codex_user_agent() {
         let user_agent = get_codex_user_agent();
-        assert!(user_agent.starts_with("codex_cli_rs/"));
+        let originator = originator().value.as_str();
+        let prefix = format!("{originator}/");
+        assert!(user_agent.starts_with(&prefix));
     }
 
     #[tokio::test]
@@ -204,7 +206,7 @@ mod tests {
         let originator_header = headers
             .get("originator")
             .expect("originator header missing");
-        assert_eq!(originator_header.to_str().unwrap(), "codex_cli_rs");
+        assert_eq!(originator_header.to_str().unwrap(), originator().value);
 
         // User-Agent matches the computed Codex UA for that originator
         let expected_ua = get_codex_user_agent();
@@ -241,9 +243,10 @@ mod tests {
     fn test_macos() {
         use regex_lite::Regex;
         let user_agent = get_codex_user_agent();
-        let re = Regex::new(
-            r"^codex_cli_rs/\d+\.\d+\.\d+ \(Mac OS \d+\.\d+\.\d+; (x86_64|arm64)\) (\S+)$",
-        )
+        let originator = regex_lite::escape(originator().value.as_str());
+        let re = Regex::new(&format!(
+            r"^{originator}/\d+\.\d+\.\d+ \(Mac OS \d+\.\d+\.\d+; (x86_64|arm64)\) (\S+)$"
+        ))
         .unwrap();
         assert!(re.is_match(&user_agent));
     }

codex-rs/core/src/environment_context.rs

@@ -1,10 +1,6 @@
-use codex_utils_absolute_path::AbsolutePathBuf;
-use serde::Deserialize;
-use serde::Serialize;
-use strum_macros::Display as DeriveDisplay;
-
 use crate::codex::TurnContext;
 use crate::protocol::AskForApproval;
+use crate::protocol::NetworkAccess;
 use crate::protocol::SandboxPolicy;
 use crate::shell::Shell;
 use codex_protocol::config_types::SandboxMode;
@@ -12,15 +8,11 @@ use codex_protocol::models::ContentItem;
 use codex_protocol::models::ResponseItem;
 use codex_protocol::protocol::ENVIRONMENT_CONTEXT_CLOSE_TAG;
 use codex_protocol::protocol::ENVIRONMENT_CONTEXT_OPEN_TAG;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::Deserialize;
+use serde::Serialize;
 use std::path::PathBuf;
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, DeriveDisplay)]
-#[serde(rename_all = "kebab-case")]
-#[strum(serialize_all = "kebab-case")]
-pub enum NetworkAccess {
-    Restricted,
-    Enabled,
-}
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename = "environment_context", rename_all = "snake_case")]
 pub(crate) struct EnvironmentContext {
@@ -45,12 +37,14 @@ impl EnvironmentContext {
             sandbox_mode: match sandbox_policy {
                 Some(SandboxPolicy::DangerFullAccess) => Some(SandboxMode::DangerFullAccess),
                 Some(SandboxPolicy::ReadOnly) => Some(SandboxMode::ReadOnly),
+                Some(SandboxPolicy::ExternalSandbox { .. }) => Some(SandboxMode::DangerFullAccess),
                 Some(SandboxPolicy::WorkspaceWrite { .. }) => Some(SandboxMode::WorkspaceWrite),
                 None => None,
             },
             network_access: match sandbox_policy {
                 Some(SandboxPolicy::DangerFullAccess) => Some(NetworkAccess::Enabled),
                 Some(SandboxPolicy::ReadOnly) => Some(NetworkAccess::Restricted),
+                Some(SandboxPolicy::ExternalSandbox { network_access }) => Some(network_access),
                 Some(SandboxPolicy::WorkspaceWrite { network_access, .. }) => {
                     if network_access {
                         Some(NetworkAccess::Enabled)
@@ -272,6 +266,48 @@ mod tests {
         assert_eq!(context.serialize_to_xml(), expected);
     }
 
+    #[test]
+    fn serialize_external_sandbox_environment_context() {
+        let context = EnvironmentContext::new(
+            None,
+            Some(AskForApproval::OnRequest),
+            Some(SandboxPolicy::ExternalSandbox {
+                network_access: NetworkAccess::Enabled,
+            }),
+            fake_shell(),
+        );
+
+        let expected = r#"<environment_context>
+  <approval_policy>on-request</approval_policy>
+  <sandbox_mode>danger-full-access</sandbox_mode>
+  <network_access>enabled</network_access>
+  <shell>bash</shell>
+</environment_context>"#;
+
+        assert_eq!(context.serialize_to_xml(), expected);
+    }
+
+    #[test]
+    fn serialize_external_sandbox_with_restricted_network_environment_context() {
+        let context = EnvironmentContext::new(
+            None,
+            Some(AskForApproval::OnRequest),
+            Some(SandboxPolicy::ExternalSandbox {
+                network_access: NetworkAccess::Restricted,
+            }),
+            fake_shell(),
+        );
+
+        let expected = r#"<environment_context>
+  <approval_policy>on-request</approval_policy>
+  <sandbox_mode>danger-full-access</sandbox_mode>
+  <network_access>restricted</network_access>
+  <shell>bash</shell>
+</environment_context>"#;
+
+        assert_eq!(context.serialize_to_xml(), expected);
+    }
+
     #[test]
     fn serialize_full_access_environment_context() {
         let context = EnvironmentContext::new(

codex-rs/core/src/error.rs

@@ -90,6 +90,10 @@ pub enum CodexErr {
     #[error("spawn failed: child stdout/stderr not captured")]
     Spawn,
 
+    /// Returned when the models list is outdated and needs to be refreshed.
+    #[error("remote models list is outdated")]
+    OutdatedModels,
+
     /// Returned by run_command_stream when the user pressed Ctrl‑C (SIGINT). Session uses this to
     /// surface a polite FunctionCallOutput back to the model instead of crashing the CLI.
     #[error("interrupted (Ctrl-C). Something went wrong? Hit `/feedback` to report the issue.")]

codex-rs/core/src/exec.rs

@@ -135,7 +135,9 @@ pub async fn process_exec_tool_call(
     stdout_stream: Option<StdoutStream>,
 ) -> Result<ExecToolCallOutput> {
     let sandbox_type = match &sandbox_policy {
-        SandboxPolicy::DangerFullAccess => SandboxType::None,
+        SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. } => {
+            SandboxType::None
+        }
         _ => get_platform_sandbox().unwrap_or(SandboxType::None),
     };
     tracing::debug!("Sandbox type: {sandbox_type:?}");
@@ -523,7 +525,10 @@ async fn exec(
 ) -> Result<RawExecToolCallOutput> {
     #[cfg(target_os = "windows")]
     if sandbox == SandboxType::WindowsRestrictedToken
-        && !matches!(sandbox_policy, SandboxPolicy::DangerFullAccess)
+        && !matches!(
+            sandbox_policy,
+            SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. }
+        )
     {
         return exec_windows_sandbox(params, sandbox_policy).await;
     }

codex-rs/core/src/exec_env.rs

@@ -82,7 +82,7 @@ mod tests {
     }
 
     #[test]
-    fn test_core_inherit_and_default_excludes() {
+    fn test_core_inherit_defaults_keep_sensitive_vars() {
         let vars = make_vars(&[
             ("PATH", "/usr/bin"),
             ("HOME", "/home/user"),
@@ -90,7 +90,32 @@ mod tests {
             ("SECRET_TOKEN", "t"),
         ]);
 
-        let policy = ShellEnvironmentPolicy::default(); // inherit Core, default excludes on
+        let policy = ShellEnvironmentPolicy::default(); // inherit All, default excludes ignored
+        let result = populate_env(vars, &policy);
+
+        let expected: HashMap<String, String> = hashmap! {
+            "PATH".to_string() => "/usr/bin".to_string(),
+            "HOME".to_string() => "/home/user".to_string(),
+            "API_KEY".to_string() => "secret".to_string(),
+            "SECRET_TOKEN".to_string() => "t".to_string(),
+        };
+
+        assert_eq!(result, expected);
+    }
+
+    #[test]
+    fn test_core_inherit_with_default_excludes_enabled() {
+        let vars = make_vars(&[
+            ("PATH", "/usr/bin"),
+            ("HOME", "/home/user"),
+            ("API_KEY", "secret"),
+            ("SECRET_TOKEN", "t"),
+        ]);
+
+        let policy = ShellEnvironmentPolicy {
+            ignore_default_excludes: false, // apply KEY/SECRET/TOKEN filter
+            ..Default::default()
+        };
         let result = populate_env(vars, &policy);
 
         let expected: HashMap<String, String> = hashmap! {
@@ -162,6 +187,7 @@ mod tests {
 
         let policy = ShellEnvironmentPolicy {
             inherit: ShellEnvironmentPolicyInherit::All,
+            ignore_default_excludes: false,
             ..Default::default()
         };
 

codex-rs/core/src/features.rs

@@ -18,12 +18,41 @@ pub(crate) use legacy::LegacyFeatureToggles;
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Stage {
     Experimental,
-    Beta,
+    Beta {
+        name: &'static str,
+        menu_description: &'static str,
+        announcement: &'static str,
+    },
     Stable,
     Deprecated,
     Removed,
 }
 
+impl Stage {
+    pub fn beta_menu_name(self) -> Option<&'static str> {
+        match self {
+            Stage::Beta { name, .. } => Some(name),
+            _ => None,
+        }
+    }
+
+    pub fn beta_menu_description(self) -> Option<&'static str> {
+        match self {
+            Stage::Beta {
+                menu_description, ..
+            } => Some(menu_description),
+            _ => None,
+        }
+    }
+
+    pub fn beta_announcement(self) -> Option<&'static str> {
+        match self {
+            Stage::Beta { announcement, .. } => Some(announcement),
+            _ => None,
+        }
+    }
+}
+
 /// Unique features toggled via configuration.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Feature {
@@ -58,12 +87,12 @@ pub enum Feature {
     RemoteModels,
     /// Allow model to call multiple tools in parallel (only for models supporting it).
     ParallelToolCalls,
-    /// Experimental skills injection (CLI flag-driven).
-    Skills,
     /// Experimental shell snapshotting.
     ShellSnapshot,
     /// Experimental TUI v2 (viewport) implementation.
     Tui2,
+    /// Enable discovery and injection of skills.
+    Skills,
 }
 
 impl Feature {
@@ -292,13 +321,34 @@ pub const FEATURES: &[FeatureSpec] = &[
         stage: Stage::Stable,
         default_enabled: true,
     },
-    // Unstable features.
+    FeatureSpec {
+        id: Feature::WebSearchRequest,
+        key: "web_search_request",
+        stage: Stage::Stable,
+        default_enabled: false,
+    },
+    // Beta program. Rendered in the `/experimental` menu for users.
     FeatureSpec {
         id: Feature::UnifiedExec,
         key: "unified_exec",
-        stage: Stage::Experimental,
+        stage: Stage::Beta {
+            name: "Background terminal",
+            menu_description: "Run long-running terminal commands in the background.",
+            announcement: "NEW! Try Background terminals for long running processes. Enable in /experimental!",
+        },
         default_enabled: false,
     },
+    FeatureSpec {
+        id: Feature::ShellSnapshot,
+        key: "shell_snapshot",
+        stage: Stage::Beta {
+            name: "Shell snapshot",
+            menu_description: "Snapshot your shell environment to avoid re-running login scripts for every command.",
+            announcement: "NEW! Try shell snapshotting to make your Codex faster. Enable in /experimental!",
+        },
+        default_enabled: false,
+    },
+    // Unstable features.
     FeatureSpec {
         id: Feature::RmcpClient,
         key: "rmcp_client",
@@ -308,13 +358,7 @@ pub const FEATURES: &[FeatureSpec] = &[
     FeatureSpec {
         id: Feature::ApplyPatchFreeform,
         key: "apply_patch_freeform",
-        stage: Stage::Beta,
-        default_enabled: false,
-    },
-    FeatureSpec {
-        id: Feature::WebSearchRequest,
-        key: "web_search_request",
-        stage: Stage::Stable,
+        stage: Stage::Experimental,
         default_enabled: false,
     },
     FeatureSpec {
@@ -351,13 +395,7 @@ pub const FEATURES: &[FeatureSpec] = &[
         id: Feature::Skills,
         key: "skills",
         stage: Stage::Experimental,
-        default_enabled: false,
-    },
-    FeatureSpec {
-        id: Feature::ShellSnapshot,
-        key: "shell_snapshot",
-        stage: Stage::Experimental,
-        default_enabled: false,
+        default_enabled: true,
     },
     FeatureSpec {
         id: Feature::Tui2,

codex-rs/core/src/lib.rs

@@ -35,7 +35,7 @@ pub mod mcp;
 mod mcp_connection_manager;
 pub mod openai_models;
 pub use mcp_connection_manager::MCP_SANDBOX_STATE_CAPABILITY;
-pub use mcp_connection_manager::MCP_SANDBOX_STATE_NOTIFICATION;
+pub use mcp_connection_manager::MCP_SANDBOX_STATE_METHOD;
 pub use mcp_connection_manager::SandboxState;
 mod mcp_tool_call;
 mod message_history;

codex-rs/core/src/mcp_connection_manager.rs

@@ -184,17 +184,20 @@ struct ManagedClient {
 }
 
 impl ManagedClient {
+    /// Returns once the server has ack'd the sandbox state update.
     async fn notify_sandbox_state_change(&self, sandbox_state: &SandboxState) -> Result<()> {
         if !self.server_supports_sandbox_state_capability {
             return Ok(());
         }
 
-        self.client
-            .send_custom_notification(
-                MCP_SANDBOX_STATE_NOTIFICATION,
+        let _response = self
+            .client
+            .send_custom_request(
+                MCP_SANDBOX_STATE_METHOD,
                 Some(serde_json::to_value(sandbox_state)?),
             )
-            .await
+            .await?;
+        Ok(())
     }
 }
 
@@ -253,9 +256,9 @@ impl AsyncManagedClient {
 
 pub const MCP_SANDBOX_STATE_CAPABILITY: &str = "codex/sandbox-state";
 
-/// Custom MCP notification for sandbox state updates.
+/// Custom MCP request to push sandbox state updates.
 /// When used, the `params` field of the notification is [`SandboxState`].
-pub const MCP_SANDBOX_STATE_NOTIFICATION: &str = "codex/sandbox-state/update";
+pub const MCP_SANDBOX_STATE_METHOD: &str = "codex/sandbox-state/update";
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]

codex-rs/core/src/message_history.rs

@@ -401,9 +401,7 @@ fn history_log_id(_metadata: &std::fs::Metadata) -> Option<u64> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::config::Config;
-    use crate::config::ConfigOverrides;
-    use crate::config::ConfigToml;
+    use crate::config::ConfigBuilder;
     use codex_protocol::ConversationId;
     use pretty_assertions::assert_eq;
     use std::fs::File;
@@ -493,12 +491,11 @@ mod tests {
     async fn append_entry_trims_history_when_beyond_max_bytes() {
         let codex_home = TempDir::new().expect("create temp dir");
 
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load config");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("load config");
 
         let conversation_id = ConversationId::new();
 
@@ -541,12 +538,11 @@ mod tests {
     async fn append_entry_trims_history_to_soft_cap() {
         let codex_home = TempDir::new().expect("create temp dir");
 
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load config");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("load config");
 
         let conversation_id = ConversationId::new();
 

codex-rs/core/src/openai_models/model_family.rs

@@ -16,6 +16,7 @@ const GPT_5_CODEX_INSTRUCTIONS: &str = include_str!("../../gpt_5_codex_prompt.md
 const GPT_5_1_INSTRUCTIONS: &str = include_str!("../../gpt_5_1_prompt.md");
 const GPT_5_2_INSTRUCTIONS: &str = include_str!("../../gpt_5_2_prompt.md");
 const GPT_5_1_CODEX_MAX_INSTRUCTIONS: &str = include_str!("../../gpt-5.1-codex-max_prompt.md");
+const GPT_5_2_CODEX_INSTRUCTIONS: &str = include_str!("../../gpt-5.2-codex_prompt.md");
 pub(crate) const CONTEXT_WINDOW_272K: i64 = 272_000;
 
 /// A model family is a group of models that share certain characteristics.
@@ -198,6 +199,7 @@ macro_rules! model_family {
 
 /// Internal offline helper for `ModelsManager` that returns a `ModelFamily` for the given
 /// model slug.
+#[allow(clippy::if_same_then_else)]
 pub(super) fn find_family_for_model(slug: &str) -> ModelFamily {
     if slug.starts_with("o3") {
         model_family!(
@@ -270,7 +272,7 @@ pub(super) fn find_family_for_model(slug: &str) -> ModelFamily {
             slug, slug,
             supports_reasoning_summaries: true,
             reasoning_summary_format: ReasoningSummaryFormat::Experimental,
-            base_instructions: GPT_5_1_CODEX_MAX_INSTRUCTIONS.to_string(),
+            base_instructions: GPT_5_2_CODEX_INSTRUCTIONS.to_string(),
             apply_patch_tool_type: Some(ApplyPatchToolType::Freeform),
             shell_type: ConfigShellToolType::ShellCommand,
             supports_parallel_tool_calls: true,
@@ -294,6 +296,32 @@ pub(super) fn find_family_for_model(slug: &str) -> ModelFamily {
         )
 
     // Production models.
+    } else if slug.starts_with("gpt-5.2-codex") {
+        model_family!(
+            slug, slug,
+            supports_reasoning_summaries: true,
+            reasoning_summary_format: ReasoningSummaryFormat::Experimental,
+            base_instructions: GPT_5_2_CODEX_INSTRUCTIONS.to_string(),
+            apply_patch_tool_type: Some(ApplyPatchToolType::Freeform),
+            shell_type: ConfigShellToolType::ShellCommand,
+            supports_parallel_tool_calls: true,
+            support_verbosity: false,
+            truncation_policy: TruncationPolicy::Tokens(10_000),
+            context_window: Some(CONTEXT_WINDOW_272K),
+        )
+    } else if slug.starts_with("bengalfox") {
+        model_family!(
+            slug, slug,
+            supports_reasoning_summaries: true,
+            reasoning_summary_format: ReasoningSummaryFormat::Experimental,
+            base_instructions: GPT_5_2_CODEX_INSTRUCTIONS.to_string(),
+            apply_patch_tool_type: Some(ApplyPatchToolType::Freeform),
+            shell_type: ConfigShellToolType::ShellCommand,
+            supports_parallel_tool_calls: true,
+            support_verbosity: false,
+            truncation_policy: TruncationPolicy::Tokens(10_000),
+            context_window: Some(CONTEXT_WINDOW_272K),
+        )
     } else if slug.starts_with("gpt-5.1-codex-max") {
         model_family!(
             slug, slug,
@@ -337,6 +365,20 @@ pub(super) fn find_family_for_model(slug: &str) -> ModelFamily {
             supports_parallel_tool_calls: true,
             context_window: Some(CONTEXT_WINDOW_272K),
         )
+    } else if slug.starts_with("boomslang") {
+        model_family!(
+            slug, slug,
+            supports_reasoning_summaries: true,
+            apply_patch_tool_type: Some(ApplyPatchToolType::Freeform),
+            support_verbosity: true,
+            default_verbosity: Some(Verbosity::Low),
+            base_instructions: GPT_5_2_INSTRUCTIONS.to_string(),
+            default_reasoning_effort: Some(ReasoningEffort::Medium),
+            truncation_policy: TruncationPolicy::Bytes(10_000),
+            shell_type: ConfigShellToolType::ShellCommand,
+            supports_parallel_tool_calls: true,
+            context_window: Some(CONTEXT_WINDOW_272K),
+        )
     } else if slug.starts_with("gpt-5.1") {
         model_family!(
             slug, "gpt-5.1",

codex-rs/core/src/openai_models/model_presets.rs

@@ -12,10 +12,10 @@ pub const HIDE_GPT_5_1_CODEX_MAX_MIGRATION_PROMPT_CONFIG: &str =
 static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
     vec![
         ModelPreset {
-            id: "gpt-5.1-codex-max".to_string(),
-            model: "gpt-5.1-codex-max".to_string(),
-            display_name: "gpt-5.1-codex-max".to_string(),
-            description: "Latest Codex-optimized flagship for deep and fast reasoning.".to_string(),
+            id: "gpt-5.2-codex".to_string(),
+            model: "gpt-5.2-codex".to_string(),
+            display_name: "gpt-5.2-codex".to_string(),
+            description: "Latest frontier agentic coding model.".to_string(),
             default_reasoning_effort: ReasoningEffort::Medium,
             supported_reasoning_efforts: vec![
                 ReasoningEffortPreset {
@@ -38,35 +38,36 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
             is_default: true,
             upgrade: None,
             show_in_picker: true,
+            supported_in_api: false,
         },
         ModelPreset {
-            id: "gpt-5.1-codex".to_string(),
-            model: "gpt-5.1-codex".to_string(),
-            display_name: "gpt-5.1-codex".to_string(),
-            description: "Optimized for codex.".to_string(),
+            id: "gpt-5.1-codex-max".to_string(),
+            model: "gpt-5.1-codex-max".to_string(),
+            display_name: "gpt-5.1-codex-max".to_string(),
+            description: "Codex-optimized flagship for deep and fast reasoning.".to_string(),
             default_reasoning_effort: ReasoningEffort::Medium,
             supported_reasoning_efforts: vec![
                 ReasoningEffortPreset {
                     effort: ReasoningEffort::Low,
-                    description: "Fastest responses with limited reasoning".to_string(),
+                    description: "Fast responses with lighter reasoning".to_string(),
                 },
                 ReasoningEffortPreset {
                     effort: ReasoningEffort::Medium,
-                    description: "Dynamically adjusts reasoning based on the task".to_string(),
+                    description: "Balances speed and reasoning depth for everyday tasks".to_string(),
                 },
                 ReasoningEffortPreset {
                     effort: ReasoningEffort::High,
-                    description: "Maximizes reasoning depth for complex or ambiguous problems"
-                        .to_string(),
+                    description: "Greater reasoning depth for complex problems".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::XHigh,
+                    description: "Extra high reasoning depth for complex problems".to_string(),
                 },
             ],
             is_default: false,
-            upgrade: Some(ModelUpgrade {
-                id: "gpt-5.1-codex-max".to_string(),
-                reasoning_effort_mapping: None,
-                migration_config_key: HIDE_GPT_5_1_CODEX_MAX_MIGRATION_PROMPT_CONFIG.to_string(),
-            }),
+            upgrade: Some(gpt_52_codex_upgrade()),
             show_in_picker: true,
+            supported_in_api: true,
         },
         ModelPreset {
             id: "gpt-5.1-codex-mini".to_string(),
@@ -86,12 +87,9 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
                 },
             ],
             is_default: false,
-            upgrade: Some(ModelUpgrade {
-                id: "gpt-5.1-codex-max".to_string(),
-                reasoning_effort_mapping: None,
-                migration_config_key: HIDE_GPT_5_1_CODEX_MAX_MIGRATION_PROMPT_CONFIG.to_string(),
-            }),
+            upgrade: Some(gpt_52_codex_upgrade()),
             show_in_picker: true,
+            supported_in_api: true,
         },
         ModelPreset {
             id: "gpt-5.2".to_string(),
@@ -110,7 +108,7 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
                 },
                 ReasoningEffortPreset {
                     effort: ReasoningEffort::High,
-                    description: "Greater reasoning depth for complex or ambiguous problems".to_string(),
+                    description: "Maximizes reasoning depth for complex or ambiguous problems".to_string(),
                 },
                 ReasoningEffortPreset {
                     effort: ReasoningEffort::XHigh,
@@ -118,14 +116,44 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
                 },
             ],
             is_default: false,
-            upgrade: None,
+            upgrade: Some(gpt_52_codex_upgrade()),
             show_in_picker: true,
+            supported_in_api: true,
         },
         ModelPreset {
-            id: "gpt-5.1".to_string(),
-            model: "gpt-5.1".to_string(),
-            display_name: "gpt-5.1".to_string(),
-            description: "Broad world knowledge with strong general reasoning.".to_string(),
+            id: "bengalfox".to_string(),
+            model: "bengalfox".to_string(),
+            display_name: "bengalfox".to_string(),
+            description: "bengalfox".to_string(),
+            default_reasoning_effort: ReasoningEffort::Medium,
+            supported_reasoning_efforts: vec![
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::Low,
+                    description: "Fast responses with lighter reasoning".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::Medium,
+                    description: "Balances speed and reasoning depth for everyday tasks".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::High,
+                    description: "Greater reasoning depth for complex problems".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::XHigh,
+                    description: "Extra high reasoning depth for complex problems".to_string(),
+                },
+            ],
+            is_default: false,
+            upgrade: None,
+            show_in_picker: false,
+            supported_in_api: true,
+        },
+        ModelPreset {
+            id: "boomslang".to_string(),
+            model: "boomslang".to_string(),
+            display_name: "boomslang".to_string(),
+            description: "boomslang".to_string(),
             default_reasoning_effort: ReasoningEffort::Medium,
             supported_reasoning_efforts: vec![
                 ReasoningEffortPreset {
@@ -140,14 +168,15 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
                     effort: ReasoningEffort::High,
                     description: "Maximizes reasoning depth for complex or ambiguous problems".to_string(),
                 },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::XHigh,
+                    description: "Extra high reasoning for complex problems".to_string(),
+                },
             ],
             is_default: false,
-            upgrade: Some(ModelUpgrade {
-                id: "gpt-5.1-codex-max".to_string(),
-                reasoning_effort_mapping: None,
-                migration_config_key: HIDE_GPT_5_1_CODEX_MAX_MIGRATION_PROMPT_CONFIG.to_string(),
-            }),
-            show_in_picker: true,
+            upgrade: None,
+            show_in_picker: false,
+            supported_in_api: true,
         },
         // Deprecated models.
         ModelPreset {
@@ -171,12 +200,9 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
                 },
             ],
             is_default: false,
-            upgrade: Some(ModelUpgrade {
-                id: "gpt-5.1-codex-max".to_string(),
-                reasoning_effort_mapping: None,
-                migration_config_key: HIDE_GPT_5_1_CODEX_MAX_MIGRATION_PROMPT_CONFIG.to_string(),
-            }),
+            upgrade: Some(gpt_52_codex_upgrade()),
             show_in_picker: false,
+            supported_in_api: true,
         },
         ModelPreset {
             id: "gpt-5-codex-mini".to_string(),
@@ -195,12 +221,35 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
                 },
             ],
             is_default: false,
-            upgrade: Some(ModelUpgrade {
-                id: "gpt-5.1-codex-mini".to_string(),
-                reasoning_effort_mapping: None,
-                migration_config_key: HIDE_GPT5_1_MIGRATION_PROMPT_CONFIG.to_string(),
-            }),
+            upgrade: Some(gpt_52_codex_upgrade()),
             show_in_picker: false,
+            supported_in_api: true,
+        },
+        ModelPreset {
+            id: "gpt-5.1-codex".to_string(),
+            model: "gpt-5.1-codex".to_string(),
+            display_name: "gpt-5.1-codex".to_string(),
+            description: "Optimized for codex.".to_string(),
+            default_reasoning_effort: ReasoningEffort::Medium,
+            supported_reasoning_efforts: vec![
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::Low,
+                    description: "Fastest responses with limited reasoning".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::Medium,
+                    description: "Dynamically adjusts reasoning based on the task".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::High,
+                    description: "Maximizes reasoning depth for complex or ambiguous problems"
+                        .to_string(),
+                },
+            ],
+            is_default: false,
+            upgrade: Some(gpt_52_codex_upgrade()),
+            show_in_picker: false,
+            supported_in_api: true,
         },
         ModelPreset {
             id: "gpt-5".to_string(),
@@ -227,16 +276,51 @@ static PRESETS: Lazy<Vec<ModelPreset>> = Lazy::new(|| {
                 },
             ],
             is_default: false,
-            upgrade: Some(ModelUpgrade {
-                id: "gpt-5.1-codex-max".to_string(),
-                reasoning_effort_mapping: None,
-                migration_config_key: HIDE_GPT_5_1_CODEX_MAX_MIGRATION_PROMPT_CONFIG.to_string(),
-            }),
+            upgrade: Some(gpt_52_codex_upgrade()),
             show_in_picker: false,
+            supported_in_api: true,
+        },
+        ModelPreset {
+            id: "gpt-5.1".to_string(),
+            model: "gpt-5.1".to_string(),
+            display_name: "gpt-5.1".to_string(),
+            description: "Broad world knowledge with strong general reasoning.".to_string(),
+            default_reasoning_effort: ReasoningEffort::Medium,
+            supported_reasoning_efforts: vec![
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::Low,
+                    description: "Balances speed with some reasoning; useful for straightforward queries and short explanations".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::Medium,
+                    description: "Provides a solid balance of reasoning depth and latency for general-purpose tasks".to_string(),
+                },
+                ReasoningEffortPreset {
+                    effort: ReasoningEffort::High,
+                    description: "Maximizes reasoning depth for complex or ambiguous problems".to_string(),
+                },
+            ],
+            is_default: false,
+            upgrade: Some(gpt_52_codex_upgrade()),
+            show_in_picker: false,
+            supported_in_api: true,
         },
     ]
 });
 
+fn gpt_52_codex_upgrade() -> ModelUpgrade {
+    ModelUpgrade {
+        id: "gpt-5.2-codex".to_string(),
+        reasoning_effort_mapping: None,
+        migration_config_key: "gpt-5.2-codex".to_string(),
+        model_link: Some("https://openai.com/index/introducing-gpt-5-2-codex".to_string()),
+        upgrade_copy: Some(
+            "Codex is now powered by gpt-5.2-codex, our latest frontier agentic coding model. It is smarter and faster than its predecessors and capable of long-running project-scale work."
+                .to_string(),
+        ),
+    }
+}
+
 pub(super) fn builtin_model_presets(_auth_mode: Option<AuthMode>) -> Vec<ModelPreset> {
     PRESETS
         .iter()

codex-rs/core/src/openai_models/models_manager.rs

@@ -29,7 +29,8 @@ use crate::openai_models::model_presets::builtin_model_presets;
 
 const MODEL_CACHE_FILE: &str = "models_cache.json";
 const DEFAULT_MODEL_CACHE_TTL: Duration = Duration::from_secs(300);
-const OPENAI_DEFAULT_MODEL: &str = "gpt-5.1-codex-max";
+const OPENAI_DEFAULT_API_MODEL: &str = "gpt-5.1-codex-max";
+const OPENAI_DEFAULT_CHATGPT_MODEL: &str = "gpt-5.2-codex";
 const CODEX_AUTO_BALANCED_MODEL: &str = "codex-auto-balanced";
 
 /// Coordinates remote model discovery plus cached metadata on disk.
@@ -51,7 +52,7 @@ impl ModelsManager {
         let codex_home = auth_manager.codex_home().to_path_buf();
         Self {
             local_models: builtin_model_presets(auth_manager.get_auth_mode()),
-            remote_models: RwLock::new(Vec::new()),
+            remote_models: RwLock::new(Self::load_remote_models_from_file().unwrap_or_default()),
             auth_manager,
             etag: RwLock::new(None),
             codex_home,
@@ -66,7 +67,7 @@ impl ModelsManager {
         let codex_home = auth_manager.codex_home().to_path_buf();
         Self {
             local_models: builtin_model_presets(auth_manager.get_auth_mode()),
-            remote_models: RwLock::new(Vec::new()),
+            remote_models: RwLock::new(Self::load_remote_models_from_file().unwrap_or_default()),
             auth_manager,
             etag: RwLock::new(None),
             codex_home,
@@ -76,14 +77,24 @@ impl ModelsManager {
     }
 
     /// Fetch the latest remote models, using the on-disk cache when still fresh.
-    pub async fn refresh_available_models(&self, config: &Config) -> CoreResult<()> {
-        if !config.features.enabled(Feature::RemoteModels) {
+    pub async fn try_refresh_available_models(&self, config: &Config) -> CoreResult<()> {
+        if !config.features.enabled(Feature::RemoteModels)
+            || self.auth_manager.get_auth_mode() == Some(AuthMode::ApiKey)
+        {
             return Ok(());
         }
         if self.try_load_cache().await {
             return Ok(());
         }
+        self.refresh_available_models(config).await
+    }
 
+    pub async fn refresh_available_models(&self, config: &Config) -> CoreResult<()> {
+        if !config.features.enabled(Feature::RemoteModels)
+            || self.auth_manager.get_auth_mode() == Some(AuthMode::ApiKey)
+        {
+            return Ok(());
+        }
         let auth = self.auth_manager.auth();
         let api_provider = self.provider.to_api_provider(Some(AuthMode::ChatGPT))?;
         let api_auth = auth_provider_from_auth(auth.clone(), &self.provider).await?;
@@ -91,12 +102,12 @@ impl ModelsManager {
         let client = ModelsClient::new(transport, api_provider, api_auth);
 
         let client_version = format_client_version_to_whole();
-        let ModelsResponse { models, etag } = client
+        let (models, etag) = client
             .list_models(&client_version, HeaderMap::new())
             .await
             .map_err(map_api_error)?;
 
-        let etag = (!etag.is_empty()).then_some(etag);
+        let etag = etag.filter(|value| !value.is_empty());
 
         self.apply_remote_models(models.clone()).await;
         *self.etag.write().await = etag.clone();
@@ -105,15 +116,15 @@ impl ModelsManager {
     }
 
     pub async fn list_models(&self, config: &Config) -> Vec<ModelPreset> {
-        if let Err(err) = self.refresh_available_models(config).await {
+        if let Err(err) = self.try_refresh_available_models(config).await {
             error!("failed to refresh available models: {err}");
         }
-        let remote_models = self.remote_models.read().await.clone();
+        let remote_models = self.remote_models(config).await;
         self.build_available_models(remote_models)
     }
 
-    pub fn try_list_models(&self) -> Result<Vec<ModelPreset>, TryLockError> {
-        let remote_models = self.remote_models.try_read()?.clone();
+    pub fn try_list_models(&self, config: &Config) -> Result<Vec<ModelPreset>, TryLockError> {
+        let remote_models = self.try_get_remote_models(config)?;
         Ok(self.build_available_models(remote_models))
     }
 
@@ -124,20 +135,24 @@ impl ModelsManager {
     /// Look up the requested model family while applying remote metadata overrides.
     pub async fn construct_model_family(&self, model: &str, config: &Config) -> ModelFamily {
         Self::find_family_for_model(model)
-            .with_remote_overrides(self.remote_models.read().await.clone())
+            .with_remote_overrides(self.remote_models(config).await)
             .with_config_overrides(config)
     }
 
+    pub async fn get_models_etag(&self) -> Option<String> {
+        self.etag.read().await.clone()
+    }
+
     pub async fn get_model(&self, model: &Option<String>, config: &Config) -> String {
         if let Some(model) = model.as_ref() {
             return model.to_string();
         }
-        if let Err(err) = self.refresh_available_models(config).await {
+        if let Err(err) = self.try_refresh_available_models(config).await {
             error!("failed to refresh available models: {err}");
         }
         // if codex-auto-balanced exists & signed in with chatgpt mode, return it, otherwise return the default model
         let auth_mode = self.auth_manager.get_auth_mode();
-        let remote_models = self.remote_models.read().await.clone();
+        let remote_models = self.remote_models(config).await;
         if auth_mode == Some(AuthMode::ChatGPT)
             && self
                 .build_available_models(remote_models)
@@ -145,13 +160,15 @@ impl ModelsManager {
                 .any(|m| m.model == CODEX_AUTO_BALANCED_MODEL)
         {
             return CODEX_AUTO_BALANCED_MODEL.to_string();
+        } else if auth_mode == Some(AuthMode::ChatGPT) {
+            return OPENAI_DEFAULT_CHATGPT_MODEL.to_string();
         }
-        OPENAI_DEFAULT_MODEL.to_string()
+        OPENAI_DEFAULT_API_MODEL.to_string()
     }
 
     #[cfg(any(test, feature = "test-support"))]
     pub fn get_model_offline(model: Option<&str>) -> String {
-        model.unwrap_or(OPENAI_DEFAULT_MODEL).to_string()
+        model.unwrap_or(OPENAI_DEFAULT_CHATGPT_MODEL).to_string()
     }
 
     #[cfg(any(test, feature = "test-support"))]
@@ -165,6 +182,12 @@ impl ModelsManager {
         *self.remote_models.write().await = models;
     }
 
+    fn load_remote_models_from_file() -> Result<Vec<ModelInfo>, std::io::Error> {
+        let file_contents = include_str!("../../models.json");
+        let response: ModelsResponse = serde_json::from_str(file_contents)?;
+        Ok(response.models)
+    }
+
     /// Attempt to satisfy the refresh from the cache when it matches the provider and TTL.
     async fn try_load_cache(&self) -> bool {
         // todo(aibrahim): think if we should store fetched_at in ModelsManager so we don't always need to read the disk
@@ -209,7 +232,7 @@ impl ModelsManager {
         let remote_presets: Vec<ModelPreset> = remote_models.into_iter().map(Into::into).collect();
         let existing_presets = self.local_models.clone();
         let mut merged_presets = Self::merge_presets(remote_presets, existing_presets);
-        merged_presets = Self::filter_visible_models(merged_presets);
+        merged_presets = self.filter_visible_models(merged_presets);
 
         let has_default = merged_presets.iter().any(|preset| preset.is_default);
         if let Some(default) = merged_presets.first_mut()
@@ -221,10 +244,11 @@ impl ModelsManager {
         merged_presets
     }
 
-    fn filter_visible_models(models: Vec<ModelPreset>) -> Vec<ModelPreset> {
+    fn filter_visible_models(&self, models: Vec<ModelPreset>) -> Vec<ModelPreset> {
+        let chatgpt_mode = self.auth_manager.get_auth_mode() == Some(AuthMode::ChatGPT);
         models
             .into_iter()
-            .filter(|model| model.show_in_picker)
+            .filter(|model| model.show_in_picker && (chatgpt_mode || model.supported_in_api))
             .collect()
     }
 
@@ -253,6 +277,22 @@ impl ModelsManager {
         merged_presets
     }
 
+    async fn remote_models(&self, config: &Config) -> Vec<ModelInfo> {
+        if config.features.enabled(Feature::RemoteModels) {
+            self.remote_models.read().await.clone()
+        } else {
+            Vec::new()
+        }
+    }
+
+    fn try_get_remote_models(&self, config: &Config) -> Result<Vec<ModelInfo>, TryLockError> {
+        if config.features.enabled(Feature::RemoteModels) {
+            Ok(self.remote_models.try_read()?.clone())
+        } else {
+            Ok(Vec::new())
+        }
+    }
+
     fn cache_path(&self) -> PathBuf {
         self.codex_home.join(MODEL_CACHE_FILE)
     }
@@ -286,9 +326,7 @@ mod tests {
     use super::*;
     use crate::CodexAuth;
     use crate::auth::AuthCredentialsStoreMode;
-    use crate::config::Config;
-    use crate::config::ConfigOverrides;
-    use crate::config::ConfigToml;
+    use crate::config::ConfigBuilder;
     use crate::features::Feature;
     use crate::model_provider_info::WireApi;
     use codex_protocol::openai_models::ModelsResponse;
@@ -363,29 +401,27 @@ mod tests {
             &server,
             ModelsResponse {
                 models: remote_models.clone(),
-                etag: String::new(),
             },
         )
         .await;
 
         let codex_home = tempdir().expect("temp dir");
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("load default test config");
         config.features.enable(Feature::RemoteModels);
         let auth_manager =
-            AuthManager::from_auth_for_testing(CodexAuth::from_api_key("Test API Key"));
+            AuthManager::from_auth_for_testing(CodexAuth::create_dummy_chatgpt_auth_for_testing());
         let provider = provider_for(server.uri());
         let manager = ModelsManager::with_provider(auth_manager, provider);
 
         manager
-            .refresh_available_models(&config)
+            .try_refresh_available_models(&config)
             .await
             .expect("refresh succeeds");
-        let cached_remote = manager.remote_models.read().await.clone();
+        let cached_remote = manager.remote_models(&config).await;
         assert_eq!(cached_remote, remote_models);
 
         let available = manager.list_models(&config).await;
@@ -421,18 +457,16 @@ mod tests {
             &server,
             ModelsResponse {
                 models: remote_models.clone(),
-                etag: String::new(),
             },
         )
         .await;
 
         let codex_home = tempdir().expect("temp dir");
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("load default test config");
         config.features.enable(Feature::RemoteModels);
         let auth_manager = Arc::new(AuthManager::new(
             codex_home.path().to_path_buf(),
@@ -443,22 +477,22 @@ mod tests {
         let manager = ModelsManager::with_provider(auth_manager, provider);
 
         manager
-            .refresh_available_models(&config)
+            .try_refresh_available_models(&config)
             .await
             .expect("first refresh succeeds");
         assert_eq!(
-            *manager.remote_models.read().await,
+            manager.remote_models(&config).await,
             remote_models,
             "remote cache should store fetched models"
         );
 
         // Second call should read from cache and avoid the network.
         manager
-            .refresh_available_models(&config)
+            .try_refresh_available_models(&config)
             .await
             .expect("cached refresh succeeds");
         assert_eq!(
-            *manager.remote_models.read().await,
+            manager.remote_models(&config).await,
             remote_models,
             "cache path should not mutate stored models"
         );
@@ -477,18 +511,16 @@ mod tests {
             &server,
             ModelsResponse {
                 models: initial_models.clone(),
-                etag: String::new(),
             },
         )
         .await;
 
         let codex_home = tempdir().expect("temp dir");
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("load default test config");
         config.features.enable(Feature::RemoteModels);
         let auth_manager = Arc::new(AuthManager::new(
             codex_home.path().to_path_buf(),
@@ -499,7 +531,7 @@ mod tests {
         let manager = ModelsManager::with_provider(auth_manager, provider);
 
         manager
-            .refresh_available_models(&config)
+            .try_refresh_available_models(&config)
             .await
             .expect("initial refresh succeeds");
 
@@ -519,17 +551,16 @@ mod tests {
             &server,
             ModelsResponse {
                 models: updated_models.clone(),
-                etag: String::new(),
             },
         )
         .await;
 
         manager
-            .refresh_available_models(&config)
+            .try_refresh_available_models(&config)
             .await
             .expect("second refresh succeeds");
         assert_eq!(
-            *manager.remote_models.read().await,
+            manager.remote_models(&config).await,
             updated_models,
             "stale cache should trigger refetch"
         );
@@ -553,27 +584,25 @@ mod tests {
             &server,
             ModelsResponse {
                 models: initial_models,
-                etag: String::new(),
             },
         )
         .await;
 
         let codex_home = tempdir().expect("temp dir");
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("load default test config");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("load default test config");
         config.features.enable(Feature::RemoteModels);
         let auth_manager =
-            AuthManager::from_auth_for_testing(CodexAuth::from_api_key("Test API Key"));
+            AuthManager::from_auth_for_testing(CodexAuth::create_dummy_chatgpt_auth_for_testing());
         let provider = provider_for(server.uri());
         let mut manager = ModelsManager::with_provider(auth_manager, provider);
         manager.cache_ttl = Duration::ZERO;
 
         manager
-            .refresh_available_models(&config)
+            .try_refresh_available_models(&config)
             .await
             .expect("initial refresh succeeds");
 
@@ -583,18 +612,17 @@ mod tests {
             &server,
             ModelsResponse {
                 models: refreshed_models,
-                etag: String::new(),
             },
         )
         .await;
 
         manager
-            .refresh_available_models(&config)
+            .try_refresh_available_models(&config)
             .await
             .expect("second refresh succeeds");
 
         let available = manager
-            .try_list_models()
+            .try_list_models(&config)
             .expect("models should be available");
         assert!(
             available.iter().any(|preset| preset.model == "remote-new"),
@@ -634,4 +662,25 @@ mod tests {
 
         assert_eq!(available, vec![expected]);
     }
+
+    #[test]
+    fn bundled_models_json_roundtrips() {
+        let file_contents = include_str!("../../models.json");
+        let response: ModelsResponse =
+            serde_json::from_str(file_contents).expect("bundled models.json should deserialize");
+
+        let serialized =
+            serde_json::to_string(&response).expect("bundled models.json should serialize");
+        let roundtripped: ModelsResponse =
+            serde_json::from_str(&serialized).expect("serialized models.json should deserialize");
+
+        assert_eq!(
+            response, roundtripped,
+            "bundled models.json should round trip through serde"
+        );
+        assert!(
+            !response.models.is_empty(),
+            "bundled models.json should contain at least one model"
+        );
+    }
 }

codex-rs/core/src/path_utils.rs

@@ -3,8 +3,8 @@ use std::path::PathBuf;
 
 use crate::env;
 
-pub fn normalize_for_path_comparison(path: &Path) -> std::io::Result<PathBuf> {
-    let canonical = path.canonicalize()?;
+pub fn normalize_for_path_comparison(path: impl AsRef<Path>) -> std::io::Result<PathBuf> {
+    let canonical = path.as_ref().canonicalize()?;
     Ok(normalize_for_wsl(canonical))
 }
 

codex-rs/core/src/project_doc.rs

@@ -14,7 +14,6 @@
 //! 3.  We do **not** walk past the Git root.
 
 use crate::config::Config;
-use crate::features::Feature;
 use crate::skills::SkillMetadata;
 use crate::skills::render_skills_section;
 use dunce::canonicalize as normalize_path;
@@ -37,11 +36,7 @@ pub(crate) async fn get_user_instructions(
     config: &Config,
     skills: Option<&[SkillMetadata]>,
 ) -> Option<String> {
-    let skills_section = if config.features.enabled(Feature::Skills) {
-        skills.and_then(render_skills_section)
-    } else {
-        None
-    };
+    let skills_section = skills.and_then(render_skills_section);
 
     let project_docs = match read_project_docs(config).await {
         Ok(docs) => docs,
@@ -237,8 +232,7 @@ fn merge_project_docs_with_skills(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::config::ConfigOverrides;
-    use crate::config::ConfigToml;
+    use crate::config::ConfigBuilder;
     use crate::skills::load_skills;
     use std::fs;
     use std::path::PathBuf;
@@ -249,30 +243,28 @@ mod tests {
     /// optionally specify a custom `instructions` string – when `None` the
     /// value is cleared to mimic a scenario where no system instructions have
     /// been configured.
-    fn make_config(root: &TempDir, limit: usize, instructions: Option<&str>) -> Config {
+    async fn make_config(root: &TempDir, limit: usize, instructions: Option<&str>) -> Config {
         let codex_home = TempDir::new().unwrap();
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("defaults for test should always succeed");
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("defaults for test should always succeed");
 
         config.cwd = root.path().to_path_buf();
         config.project_doc_max_bytes = limit;
-        config.features.enable(Feature::Skills);
 
         config.user_instructions = instructions.map(ToOwned::to_owned);
         config
     }
 
-    fn make_config_with_fallback(
+    async fn make_config_with_fallback(
         root: &TempDir,
         limit: usize,
         instructions: Option<&str>,
         fallbacks: &[&str],
     ) -> Config {
-        let mut config = make_config(root, limit, instructions);
+        let mut config = make_config(root, limit, instructions).await;
         config.project_doc_fallback_filenames = fallbacks
             .iter()
             .map(std::string::ToString::to_string)
@@ -285,7 +277,7 @@ mod tests {
     async fn no_doc_file_returns_none() {
         let tmp = tempfile::tempdir().expect("tempdir");
 
-        let res = get_user_instructions(&make_config(&tmp, 4096, None), None).await;
+        let res = get_user_instructions(&make_config(&tmp, 4096, None).await, None).await;
         assert!(
             res.is_none(),
             "Expected None when AGENTS.md is absent and no system instructions provided"
@@ -299,7 +291,7 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         fs::write(tmp.path().join("AGENTS.md"), "hello world").unwrap();
 
-        let res = get_user_instructions(&make_config(&tmp, 4096, None), None)
+        let res = get_user_instructions(&make_config(&tmp, 4096, None).await, None)
             .await
             .expect("doc expected");
 
@@ -318,7 +310,7 @@ mod tests {
         let huge = "A".repeat(LIMIT * 2); // 2 KiB
         fs::write(tmp.path().join("AGENTS.md"), &huge).unwrap();
 
-        let res = get_user_instructions(&make_config(&tmp, LIMIT, None), None)
+        let res = get_user_instructions(&make_config(&tmp, LIMIT, None).await, None)
             .await
             .expect("doc expected");
 
@@ -347,7 +339,7 @@ mod tests {
         std::fs::create_dir_all(&nested).unwrap();
 
         // Build config pointing at the nested dir.
-        let mut cfg = make_config(&repo, 4096, None);
+        let mut cfg = make_config(&repo, 4096, None).await;
         cfg.cwd = nested;
 
         let res = get_user_instructions(&cfg, None)
@@ -362,7 +354,7 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         fs::write(tmp.path().join("AGENTS.md"), "something").unwrap();
 
-        let res = get_user_instructions(&make_config(&tmp, 0, None), None).await;
+        let res = get_user_instructions(&make_config(&tmp, 0, None).await, None).await;
         assert!(
             res.is_none(),
             "With limit 0 the function should return None"
@@ -378,7 +370,7 @@ mod tests {
 
         const INSTRUCTIONS: &str = "base instructions";
 
-        let res = get_user_instructions(&make_config(&tmp, 4096, Some(INSTRUCTIONS)), None)
+        let res = get_user_instructions(&make_config(&tmp, 4096, Some(INSTRUCTIONS)).await, None)
             .await
             .expect("should produce a combined instruction string");
 
@@ -395,7 +387,8 @@ mod tests {
 
         const INSTRUCTIONS: &str = "some instructions";
 
-        let res = get_user_instructions(&make_config(&tmp, 4096, Some(INSTRUCTIONS)), None).await;
+        let res =
+            get_user_instructions(&make_config(&tmp, 4096, Some(INSTRUCTIONS)).await, None).await;
 
         assert_eq!(res, Some(INSTRUCTIONS.to_string()));
     }
@@ -421,7 +414,7 @@ mod tests {
         std::fs::create_dir_all(&nested).unwrap();
         fs::write(nested.join("AGENTS.md"), "crate doc").unwrap();
 
-        let mut cfg = make_config(&repo, 4096, None);
+        let mut cfg = make_config(&repo, 4096, None).await;
         cfg.cwd = nested;
 
         let res = get_user_instructions(&cfg, None)
@@ -437,7 +430,7 @@ mod tests {
         fs::write(tmp.path().join(DEFAULT_PROJECT_DOC_FILENAME), "versioned").unwrap();
         fs::write(tmp.path().join(LOCAL_PROJECT_DOC_FILENAME), "local").unwrap();
 
-        let cfg = make_config(&tmp, 4096, None);
+        let cfg = make_config(&tmp, 4096, None).await;
 
         let res = get_user_instructions(&cfg, None)
             .await
@@ -459,7 +452,7 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         fs::write(tmp.path().join("EXAMPLE.md"), "example instructions").unwrap();
 
-        let cfg = make_config_with_fallback(&tmp, 4096, None, &["EXAMPLE.md"]);
+        let cfg = make_config_with_fallback(&tmp, 4096, None, &["EXAMPLE.md"]).await;
 
         let res = get_user_instructions(&cfg, None)
             .await
@@ -475,7 +468,7 @@ mod tests {
         fs::write(tmp.path().join("AGENTS.md"), "primary").unwrap();
         fs::write(tmp.path().join("EXAMPLE.md"), "secondary").unwrap();
 
-        let cfg = make_config_with_fallback(&tmp, 4096, None, &["EXAMPLE.md", ".example.md"]);
+        let cfg = make_config_with_fallback(&tmp, 4096, None, &["EXAMPLE.md", ".example.md"]).await;
 
         let res = get_user_instructions(&cfg, None)
             .await
@@ -499,7 +492,7 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         fs::write(tmp.path().join("AGENTS.md"), "base doc").unwrap();
 
-        let cfg = make_config(&tmp, 4096, None);
+        let cfg = make_config(&tmp, 4096, None).await;
         create_skill(
             cfg.codex_home.clone(),
             "pdf-processing",
@@ -522,7 +515,7 @@ mod tests {
         let expected_path_str = expected_path.to_string_lossy().replace('\\', "/");
         let usage_rules = "- Discovery: Available skills are listed in project docs and may also appear in a runtime \"## Skills\" section (name + description + file path). These are the sources of truth; skill bodies live on disk at the listed paths.\n- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.\n- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.\n- How to use a skill (progressive disclosure):\n  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.\n  2) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.\n  3) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.\n  4) If `assets/` or templates exist, reuse them instead of recreating from scratch.\n- Description as trigger: The YAML `description` in `SKILL.md` is the primary trigger signal; rely on it to decide applicability. If unsure, ask a brief clarification before proceeding.\n- Coordination and sequencing:\n  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.\n  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.\n- Context hygiene:\n  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.\n  - Avoid deeply nested references; prefer one-hop files explicitly linked from `SKILL.md`.\n  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.\n- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.";
         let expected = format!(
-            "base doc\n\n## Skills\nThese skills are discovered at startup from ~/.codex/skills; each entry shows name, description, and file path so you can open the source for full instructions. Content is not inlined to keep context lean.\n- pdf-processing: extract from pdfs (file: {expected_path_str})\n{usage_rules}"
+            "base doc\n\n## Skills\nThese skills are discovered at startup from multiple local sources. Each entry includes a name, description, and file path so you can open the source for full instructions.\n- pdf-processing: extract from pdfs (file: {expected_path_str})\n{usage_rules}"
         );
         assert_eq!(res, expected);
     }
@@ -530,7 +523,7 @@ mod tests {
     #[tokio::test]
     async fn skills_render_without_project_doc() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let cfg = make_config(&tmp, 4096, None);
+        let cfg = make_config(&tmp, 4096, None).await;
         create_skill(cfg.codex_home.clone(), "linting", "run clippy");
 
         let skills = load_skills(&cfg);
@@ -546,7 +539,7 @@ mod tests {
         let expected_path_str = expected_path.to_string_lossy().replace('\\', "/");
         let usage_rules = "- Discovery: Available skills are listed in project docs and may also appear in a runtime \"## Skills\" section (name + description + file path). These are the sources of truth; skill bodies live on disk at the listed paths.\n- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.\n- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.\n- How to use a skill (progressive disclosure):\n  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.\n  2) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.\n  3) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.\n  4) If `assets/` or templates exist, reuse them instead of recreating from scratch.\n- Description as trigger: The YAML `description` in `SKILL.md` is the primary trigger signal; rely on it to decide applicability. If unsure, ask a brief clarification before proceeding.\n- Coordination and sequencing:\n  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.\n  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.\n- Context hygiene:\n  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.\n  - Avoid deeply nested references; prefer one-hop files explicitly linked from `SKILL.md`.\n  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.\n- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.";
         let expected = format!(
-            "## Skills\nThese skills are discovered at startup from ~/.codex/skills; each entry shows name, description, and file path so you can open the source for full instructions. Content is not inlined to keep context lean.\n- linting: run clippy (file: {expected_path_str})\n{usage_rules}"
+            "## Skills\nThese skills are discovered at startup from multiple local sources. Each entry includes a name, description, and file path so you can open the source for full instructions.\n- linting: run clippy (file: {expected_path_str})\n{usage_rules}"
         );
         assert_eq!(res, expected);
     }

codex-rs/core/src/rollout/policy.rs

@@ -88,6 +88,7 @@ pub(crate) fn should_persist_event_msg(ev: &EventMsg) -> bool {
         | EventMsg::ItemCompleted(_)
         | EventMsg::AgentMessageContentDelta(_)
         | EventMsg::ReasoningContentDelta(_)
-        | EventMsg::ReasoningRawContentDelta(_) => false,
+        | EventMsg::ReasoningRawContentDelta(_)
+        | EventMsg::SkillsUpdateAvailable => false,
     }
 }

codex-rs/core/src/safety.rs

@@ -91,7 +91,10 @@ pub fn assess_patch_safety(
     if is_write_patch_constrained_to_writable_paths(action, sandbox_policy, cwd)
         || policy == AskForApproval::OnFailure
     {
-        if matches!(sandbox_policy, SandboxPolicy::DangerFullAccess) {
+        if matches!(
+            sandbox_policy,
+            SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. }
+        ) {
             // DangerFullAccess is intended to bypass sandboxing entirely.
             SafetyCheck::AutoApprove {
                 sandbox_type: SandboxType::None,
@@ -147,7 +150,7 @@ fn is_write_patch_constrained_to_writable_paths(
         SandboxPolicy::ReadOnly => {
             return false;
         }
-        SandboxPolicy::DangerFullAccess => {
+        SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. } => {
             return true;
         }
         SandboxPolicy::WorkspaceWrite { .. } => sandbox_policy.get_writable_roots_with_cwd(cwd),
@@ -262,4 +265,23 @@ mod tests {
             &cwd,
         ));
     }
+
+    #[test]
+    fn external_sandbox_auto_approves_in_on_request() {
+        let tmp = TempDir::new().unwrap();
+        let cwd = tmp.path().to_path_buf();
+        let add_inside = ApplyPatchAction::new_add_for_test(&cwd.join("inner.txt"), "".to_string());
+
+        let policy = SandboxPolicy::ExternalSandbox {
+            network_access: codex_protocol::protocol::NetworkAccess::Enabled,
+        };
+
+        assert_eq!(
+            assess_patch_safety(&add_inside, AskForApproval::OnRequest, &policy, &cwd,),
+            SafetyCheck::AutoApprove {
+                sandbox_type: SandboxType::None,
+                user_explicitly_approved: false,
+            }
+        );
+    }
 }

codex-rs/core/src/sandboxing/mod.rs

@@ -85,7 +85,9 @@ impl SandboxManager {
                 crate::safety::get_platform_sandbox().unwrap_or(SandboxType::None)
             }
             SandboxablePreference::Auto => match policy {
-                SandboxPolicy::DangerFullAccess => SandboxType::None,
+                SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. } => {
+                    SandboxType::None
+                }
                 _ => crate::safety::get_platform_sandbox().unwrap_or(SandboxType::None),
             },
         }

codex-rs/core/src/skills/assets/samples/plan/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: plan
+description: Generate a plan for how an agent should accomplish a complex coding task. Use when a user asks for a plan, and optionally when they want to save, find, read, update, or delete plan files in $CODEX_HOME/plans (default ~/.codex/plans).
+metadata:
+  short-description: Generate a plan for a complex task
+---
+
+# Plan
+
+## Overview
+
+Draft structured plans that clarify intent, scope, requirements, action items, testing/validation, and risks.
+
+Optionally, save plans to disk as markdown files with YAML frontmatter and free-form content. When drafting in chat, output only the plan body without frontmatter; add frontmatter only when saving to disk. Only write to the plans folder; do not modify the repository codebase.
+
+This skill can also be used to draft codebase or system overviews.
+
+## Core rules
+
+- Resolve the plans directory as `$CODEX_HOME/plans` or `~/.codex/plans` when `CODEX_HOME` is not set.
+- Create the plans directory if it does not exist.
+- Never write to the repo; only read files to understand context.
+- Require frontmatter with **only** `name` and `description` (single-line values) for on-disk plans.
+- When presenting a draft plan in chat, omit frontmatter and start at `# Plan`.
+- Enforce naming rules: short, lower-case, hyphen-delimited; filename must equal `<name>.md`.
+- If a plan is not found, state it clearly and offer to create one.
+- Allow overview-style plans that document flows, architecture, or context without a work checklist.
+
+## Decide the task
+
+1. **Find/list**: discover plans by frontmatter summary; confirm if multiple matches exist.
+2. **Read/use**: validate frontmatter; present summary and full contents.
+3. **Create**: inspect repo read-only; choose plan style (implementation vs overview); draft plan; write to plans directory only.
+4. **Update**: load plan; revise content and/or description; preserve frontmatter keys; overwrite the plan file.
+5. **Delete**: confirm intent, then remove the plan file if asked.
+
+## Plan discovery
+
+- Prefer `scripts/list_plans.py` for quick summaries.
+- Use `scripts/read_plan_frontmatter.py` to validate a specific plan.
+- If name mismatches filename or frontmatter is missing fields, call it out and ask whether to fix.
+
+## Plan creation workflow
+
+1. Scan context quickly: read README.md and obvious docs (docs/, CONTRIBUTING.md, ARCHITECTURE.md); skim likely touched files; identify constraints (language, frameworks, CI/test commands, deployment).
+2. Ask follow-ups only if blocked: at most 1-2 questions, prefer multiple-choice. If unsure but not blocked, state assumptions and proceed.
+3. Identify scope, constraints, and data model/API implications (or capture existing behavior for an overview).
+4. Draft either an ordered implementation plan or a structured overview plan with diagrams/notes as needed.
+5. Immediately output the plan body only (no frontmatter), then ask the user if they want to 1. Make changes, 2. Implement it, 3. Save it as per plan.
+6. If the user wants to save it, prepend frontmatter and save the plan under the computed plans directory using `scripts/create_plan.py`.
+
+
+## Plan update workflow
+
+- Re-read the plan and related code/docs before updating.
+- Keep the plan name stable unless the user explicitly wants a rename.
+- If renaming, update both frontmatter `name` and filename together.
+
+## Scripts (low-freedom helpers)
+
+Create a plan file (body only; frontmatter is written for you). Run from the plan skill directory:
+
+```bash
+python ./scripts/create_plan.py \
+  --name codex-rate-limit-overview \
+  --description "Scope and update plan for Codex rate limiting" \
+  --body-file /tmp/plan-body.md
+```
+
+Read frontmatter summary for a plan (run from the plan skill directory):
+
+```bash
+python ./scripts/read_plan_frontmatter.py ~/.codex/plans/codex-rate-limit-overview.md
+```
+
+List plan summaries (optional filter; run from the plan skill directory):
+
+```bash
+python ./scripts/list_plans.py --query "rate limit"
+```
+
+## Plan file format
+
+Use one of the structures below for the plan body. When drafting, output only the body (no frontmatter). When saving, prepend this frontmatter:
+
+```markdown
+---
+name: <plan-name>
+description: <1-line summary>
+---
+```
+
+### Implementation plan body template
+
+```markdown
+# Plan
+
+<1-3 sentences: intent, scope, and approach.>
+
+## Requirements
+- <Requirement 1>
+- <Requirement 2>
+
+## Scope
+- In:
+- Out:
+
+## Files and entry points
+- <File/module/entry point 1>
+- <File/module/entry point 2>
+
+## Data model / API changes
+- <If applicable, describe schema or contract changes>
+
+## Action items
+[ ] <Step 1>
+[ ] <Step 2>
+[ ] <Step 3>
+[ ] <Step 4>
+[ ] <Step 5>
+[ ] <Step 6>
+
+## Testing and validation
+- <Tests, commands, or validation steps>
+
+## Risks and edge cases
+- <Risk 1>
+- <Risk 2>
+
+## Open questions
+- <Question 1>
+- <Question 2>
+```
+
+### Overview plan body template
+
+```markdown
+# Plan
+
+<1-3 sentences: intent and scope of the overview.>
+
+## Overview
+<Describe the system, flow, or architecture at a high level.>
+
+## Diagrams
+<Include text or Mermaid diagrams if helpful.>
+
+## Key file references
+- <File/module/entry point 1>
+- <File/module/entry point 2>
+
+## Auth / routing / behavior notes
+- <Capture relevant differences (e.g., auth modes, routing paths).>
+
+## Current status
+- <What is live today vs pending work, if known.>
+
+## Action items
+- None (overview only).
+
+## Testing and validation
+- None (overview only).
+
+## Risks and edge cases
+- None (overview only).
+
+## Open questions
+- None.
+```
+
+## Writing guidance
+
+- Start with 1 short paragraph describing intent and approach.
+- Keep action items ordered and atomic (discovery -> changes -> tests -> rollout); use verb-first phrasing.
+- Scale action item count to complexity (simple: 1-2; complex: up to about 10).
+- Include file/entry-point hints and concrete validation steps where useful.
+- Always include testing/validation and risks/edge cases in implementation plans; include safe rollout/rollback when relevant.
+- Use open questions only when necessary (max 3).
+- Avoid vague steps, micro-steps, and code snippets; keep the plan implementation-agnostic.
+- For overview plans, keep action items minimal and set non-applicable sections to "None."

codex-rs/core/src/skills/assets/samples/plan/scripts/create_plan.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Create or overwrite a plan markdown file in $CODEX_HOME/plans."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from plan_utils import get_plans_dir, validate_plan_name
+
+DEFAULT_TEMPLATE = """# Plan
+
+<1-3 sentences: intent, scope, and approach.>
+
+## Requirements
+- <Requirement 1>
+- <Requirement 2>
+
+## Scope
+- In:
+- Out:
+
+## Files and entry points
+- <File/module/entry point 1>
+- <File/module/entry point 2>
+
+## Data model / API changes
+- <If applicable, describe schema or contract changes>
+
+## Action items
+[ ] <Step 1>
+[ ] <Step 2>
+[ ] <Step 3>
+[ ] <Step 4>
+[ ] <Step 5>
+[ ] <Step 6>
+
+## Testing and validation
+- <Tests, commands, or validation steps>
+
+## Risks and edge cases
+- <Risk 1>
+- <Risk 2>
+
+## Open questions
+- <Question 1>
+- <Question 2>
+"""
+
+
+def read_body(args: argparse.Namespace) -> str | None:
+    if args.template:
+        return DEFAULT_TEMPLATE
+    if args.body_file:
+        return Path(args.body_file).read_text(encoding="utf-8")
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Create a plan file under $CODEX_HOME/plans or ~/.codex/plans."
+    )
+    parser.add_argument("--name", required=True, help="Plan name (lower-case, hyphen-delimited).")
+    parser.add_argument("--description", required=True, help="Short plan description.")
+    parser.add_argument(
+        "--body-file",
+        help="Path to markdown body (without frontmatter). If omitted, read from stdin.",
+    )
+    parser.add_argument(
+        "--template",
+        action="store_true",
+        help="Write a template body instead of reading from stdin or --body-file.",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite the plan file if it already exists.",
+    )
+    args = parser.parse_args()
+
+    name = args.name.strip()
+    description = args.description.strip()
+    validate_plan_name(name)
+    if not description or "\n" in description:
+        raise SystemExit("Description must be a single line.")
+
+    body = read_body(args)
+    if body is None:
+        raise SystemExit("Provide --body-file, stdin, or --template to supply plan content.")
+
+    body = body.strip()
+    if not body:
+        raise SystemExit("Plan body cannot be empty.")
+    if body.lstrip().startswith("---"):
+        raise SystemExit("Plan body should not include frontmatter.")
+
+    plans_dir = get_plans_dir()
+    plans_dir.mkdir(parents=True, exist_ok=True)
+    plan_path = plans_dir / f"{name}.md"
+
+    if plan_path.exists() and not args.overwrite:
+        raise SystemExit(f"Plan already exists: {plan_path}. Use --overwrite to replace.")
+
+    content = f"---\nname: {name}\ndescription: {description}\n---\n\n{body}\n"
+    plan_path.write_text(content, encoding="utf-8")
+    print(str(plan_path))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex-rs/core/src/skills/assets/samples/plan/scripts/list_plans.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""List plan summaries by reading frontmatter only."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from plan_utils import get_plans_dir, parse_frontmatter
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="List plan summaries from $CODEX_HOME/plans.")
+    parser.add_argument("--query", help="Case-insensitive substring to filter name/description.")
+    parser.add_argument("--json", action="store_true", help="Emit JSON output.")
+    args = parser.parse_args()
+
+    plans_dir = get_plans_dir()
+    if not plans_dir.exists():
+        raise SystemExit(f"Plans directory not found: {plans_dir}")
+
+    query = args.query.lower() if args.query else None
+    items = []
+    for path in sorted(plans_dir.glob("*.md")):
+        try:
+            data = parse_frontmatter(path)
+        except ValueError:
+            continue
+        name = data.get("name")
+        description = data.get("description")
+        if not name or not description:
+            continue
+        if query:
+            haystack = f"{name} {description}".lower()
+            if query not in haystack:
+                continue
+        items.append({"name": name, "description": description, "path": str(path)})
+
+    if args.json:
+        print(json.dumps(items))
+    else:
+        for item in items:
+            print(f"{item['name']}\t{item['description']}\t{item['path']}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex-rs/core/src/skills/assets/samples/plan/scripts/plan_utils.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Shared helpers for plan scripts."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def get_codex_home() -> Path:
+    """Return CODEX_HOME if set, else ~/.codex."""
+    return Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+
+
+def get_plans_dir() -> Path:
+    return get_codex_home() / "plans"
+
+
+def validate_plan_name(name: str) -> None:
+    if not name or not _NAME_RE.match(name):
+        raise ValueError(
+            "Invalid plan name. Use short, lower-case, hyphen-delimited names "
+            "(e.g., codex-rate-limit-overview)."
+        )
+
+
+def parse_frontmatter(path: Path) -> dict:
+    """Parse YAML frontmatter from a markdown file without reading the body."""
+    with path.open("r", encoding="utf-8") as handle:
+        first = handle.readline()
+        if first.strip() != "---":
+            raise ValueError("Frontmatter must start with '---'.")
+
+        data: dict[str, str] = {}
+        for line in handle:
+            stripped = line.strip()
+            if stripped == "---":
+                return data
+            if not stripped or stripped.startswith("#"):
+                continue
+            if ":" not in line:
+                raise ValueError(f"Invalid frontmatter line: {line.rstrip()}")
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+            if value and len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                value = value[1:-1]
+            data[key] = value
+
+    raise ValueError("Frontmatter must end with '---'.")

codex-rs/core/src/skills/assets/samples/plan/scripts/read_plan_frontmatter.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Read plan frontmatter without loading the full markdown body."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from plan_utils import parse_frontmatter
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Read name/description from plan frontmatter.")
+    parser.add_argument("plan_path", help="Path to the plan markdown file.")
+    parser.add_argument("--json", action="store_true", help="Emit JSON output.")
+    args = parser.parse_args()
+
+    path = Path(args.plan_path).expanduser()
+    if not path.exists():
+        raise SystemExit(f"Plan not found: {path}")
+
+    data = parse_frontmatter(path)
+    name = data.get("name")
+    description = data.get("description")
+    if not name or not description:
+        raise SystemExit("Frontmatter must include name and description.")
+
+    payload = {"name": name, "description": description, "path": str(path)}
+    if args.json:
+        print(json.dumps(payload))
+    else:
+        print(f"name: {name}")
+        print(f"description: {description}")
+        print(f"path: {path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex-rs/core/src/skills/assets/samples/skill-creator/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
+metadata:
+  short-description: Create or update a skill
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Codex's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Codex from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: Codex is already very smart.** Only add context Codex doesn't already have. Challenge each piece of information: "Does Codex really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Codex reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Codex for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform Codex's process and thinking.
+
+- **When to include**: For documentation that Codex should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Codex determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output Codex produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Codex to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Codex (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+Codex loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, Codex only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+    ├── aws.md (AWS deployment patterns)
+    ├── gcp.md (GCP deployment patterns)
+    └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, Codex only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+Codex reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Codex can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
+- When generating names, generate a name under 30 characters (letters, digits, hyphens).
+- Prefer short, verb-led phrases that describe the action.
+- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
+- Name the skill folder exactly after the skill name.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
+```
+
+Examples:
+
+```bash
+scripts/init_skill.py my-skill --path skills/public
+scripts/init_skill.py my-skill --path skills/public --resources scripts,references
+scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Optionally creates resource directories based on `--resources`
+- Optionally adds example files when `--examples` is set
+
+After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Codex to use. Include information that would be beneficial and non-obvious to Codex. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Codex instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.
+  - Include both what the Skill does and specific triggers/contexts for when to use it.
+  - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Codex.
+  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again

codex-rs/core/src/skills/assets/samples/skill-creator/license.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

codex-rs/core/src/skills/assets/samples/skill-creator/scripts/init_skill.py

@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples]
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-new-skill --path skills/public --resources scripts,references
+    init_skill.py my-api-helper --path skills/private --resources scripts --examples
+    init_skill.py custom-skill --path /custom/location
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+MAX_SKILL_NAME_LENGTH = 30
+ALLOWED_RESOURCES = {"scripts", "references", "assets"}
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources (optional)
+
+Create only the resource directories this skill actually needs. Delete this section if no resources are required.
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Codex for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Codex's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Codex should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Codex produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Not every skill requires all three types of resources.**
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Codex produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def normalize_skill_name(skill_name):
+    """Normalize a skill name to lowercase hyphen-case."""
+    normalized = skill_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return " ".join(word.capitalize() for word in skill_name.split("-"))
+
+
+def parse_resources(raw_resources):
+    if not raw_resources:
+        return []
+    resources = [item.strip() for item in raw_resources.split(",") if item.strip()]
+    invalid = sorted({item for item in resources if item not in ALLOWED_RESOURCES})
+    if invalid:
+        allowed = ", ".join(sorted(ALLOWED_RESOURCES))
+        print(f"❌ Error: Unknown resource type(s): {', '.join(invalid)}")
+        print(f"   Allowed: {allowed}")
+        sys.exit(1)
+    deduped = []
+    seen = set()
+    for resource in resources:
+        if resource not in seen:
+            deduped.append(resource)
+            seen.add(resource)
+    return deduped
+
+
+def create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples):
+    for resource in resources:
+        resource_dir = skill_dir / resource
+        resource_dir.mkdir(exist_ok=True)
+        if resource == "scripts":
+            if include_examples:
+                example_script = resource_dir / "example.py"
+                example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+                example_script.chmod(0o755)
+                print("✅ Created scripts/example.py")
+            else:
+                print("✅ Created scripts/")
+        elif resource == "references":
+            if include_examples:
+                example_reference = resource_dir / "api_reference.md"
+                example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+                print("✅ Created references/api_reference.md")
+            else:
+                print("✅ Created references/")
+        elif resource == "assets":
+            if include_examples:
+                example_asset = resource_dir / "example_asset.txt"
+                example_asset.write_text(EXAMPLE_ASSET)
+                print("✅ Created assets/example_asset.txt")
+            else:
+                print("✅ Created assets/")
+
+
+def init_skill(skill_name, path, resources, include_examples):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+        resources: Resource directories to create
+        include_examples: Whether to create example files in resource directories
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"❌ Error: Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+        print(f"✅ Created skill directory: {skill_dir}")
+    except Exception as e:
+        print(f"❌ Error creating directory: {e}")
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
+
+    skill_md_path = skill_dir / "SKILL.md"
+    try:
+        skill_md_path.write_text(skill_content)
+        print("✅ Created SKILL.md")
+    except Exception as e:
+        print(f"❌ Error creating SKILL.md: {e}")
+        return None
+
+    # Create resource directories if requested
+    if resources:
+        try:
+            create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples)
+        except Exception as e:
+            print(f"❌ Error creating resource directories: {e}")
+            return None
+
+    # Print next steps
+    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    if resources:
+        if include_examples:
+            print("2. Customize or delete the example files in scripts/, references/, and assets/")
+        else:
+            print("2. Add resources to scripts/, references/, and assets/ as needed")
+    else:
+        print("2. Create resource directories only if needed (scripts/, references/, assets/)")
+    print("3. Run the validator when ready to check the skill structure")
+
+    return skill_dir
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create a new skill directory with a SKILL.md template.",
+    )
+    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
+    parser.add_argument("--path", required=True, help="Output directory for the skill")
+    parser.add_argument(
+        "--resources",
+        default="",
+        help="Comma-separated list: scripts,references,assets",
+    )
+    parser.add_argument(
+        "--examples",
+        action="store_true",
+        help="Create example files inside the selected resource directories",
+    )
+    args = parser.parse_args()
+
+    raw_skill_name = args.skill_name
+    skill_name = normalize_skill_name(raw_skill_name)
+    if not skill_name:
+        print("❌ Error: Skill name must include at least one letter or digit.")
+        sys.exit(1)
+    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
+        print(
+            f"❌ Error: Skill name '{skill_name}' is too long ({len(skill_name)} characters). "
+            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters."
+        )
+        sys.exit(1)
+    if skill_name != raw_skill_name:
+        print(f"Note: Normalized skill name from '{raw_skill_name}' to '{skill_name}'.")
+
+    resources = parse_resources(args.resources)
+    if args.examples and not resources:
+        print("❌ Error: --examples requires --resources to be set.")
+        sys.exit(1)
+
+    path = args.path
+
+    print(f"🚀 Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    if resources:
+        print(f"   Resources: {', '.join(resources)}")
+        if args.examples:
+            print("   Examples: enabled")
+    else:
+        print("   Resources: none (create as needed)")
+    print()
+
+    result = init_skill(skill_name, path, resources, args.examples)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

codex-rs/core/src/skills/assets/samples/skill-creator/scripts/package_skill.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"❌ Error: Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"❌ Error: Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"❌ Error: SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("🔍 Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"❌ Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"✅ {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    # Create the .skill file (zip format)
+    try:
+        with zipfile.ZipFile(skill_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
+            # Walk through the skill directory
+            for file_path in skill_path.rglob("*"):
+                if file_path.is_file():
+                    # Calculate the relative path within the zip
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+                    print(f"  Added: {arcname}")
+
+        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        print(f"❌ Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python utils/package_skill.py skills/public/my-skill")
+        print("  python utils/package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"📦 Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

codex-rs/core/src/skills/assets/samples/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+MAX_SKILL_NAME_LENGTH = 30
+
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    content = skill_md.read_text()
+    if not content.startswith("---"):
+        return False, "No YAML frontmatter found"
+
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+
+    frontmatter_text = match.group(1)
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            return False, "Frontmatter must be a YAML dictionary"
+    except yaml.YAMLError as e:
+        return False, f"Invalid YAML in frontmatter: {e}"
+
+    allowed_properties = {"name", "description", "license", "allowed-tools", "metadata"}
+
+    unexpected_keys = set(frontmatter.keys()) - allowed_properties
+    if unexpected_keys:
+        allowed = ", ".join(sorted(allowed_properties))
+        unexpected = ", ".join(sorted(unexpected_keys))
+        return (
+            False,
+            f"Unexpected key(s) in SKILL.md frontmatter: {unexpected}. Allowed properties are: {allowed}",
+        )
+
+    if "name" not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if "description" not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    name = frontmatter.get("name", "")
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if name:
+        if not re.match(r"^[a-z0-9-]+$", name):
+            return (
+                False,
+                f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)",
+            )
+        if name.startswith("-") or name.endswith("-") or "--" in name:
+            return (
+                False,
+                f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens",
+            )
+        if len(name) > MAX_SKILL_NAME_LENGTH:
+            return (
+                False,
+                f"Name is too long ({len(name)} characters). "
+                f"Maximum is {MAX_SKILL_NAME_LENGTH} characters.",
+            )
+
+    description = frontmatter.get("description", "")
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if description:
+        if "<" in description or ">" in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+        if len(description) > 1024:
+            return (
+                False,
+                f"Description is too long ({len(description)} characters). Maximum is 1024 characters.",
+            )
+
+    return True, "Skill is valid!"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)

codex-rs/core/src/skills/loader.rs

@@ -3,9 +3,11 @@ use crate::git_info::resolve_root_git_project_for_trust;
 use crate::skills::model::SkillError;
 use crate::skills::model::SkillLoadOutcome;
 use crate::skills::model::SkillMetadata;
+use crate::skills::system::system_cache_root_dir;
 use codex_protocol::protocol::SkillScope;
 use dunce::canonicalize as normalize_path;
 use serde::Deserialize;
+use std::collections::HashSet;
 use std::collections::VecDeque;
 use std::error::Error;
 use std::fmt;
@@ -18,13 +20,23 @@ use tracing::error;
 struct SkillFrontmatter {
     name: String,
     description: String,
+    #[serde(default)]
+    metadata: SkillFrontmatterMetadata,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct SkillFrontmatterMetadata {
+    #[serde(default, rename = "short-description")]
+    short_description: Option<String>,
 }
 
 const SKILLS_FILENAME: &str = "SKILL.md";
 const SKILLS_DIR_NAME: &str = "skills";
 const REPO_ROOT_CONFIG_DIR_NAME: &str = ".codex";
+const ADMIN_SKILLS_ROOT: &str = "/etc/codex/skills";
 const MAX_NAME_LEN: usize = 64;
 const MAX_DESCRIPTION_LEN: usize = 1024;
+const MAX_SHORT_DESCRIPTION_LEN: usize = MAX_DESCRIPTION_LEN;
 
 #[derive(Debug)]
 enum SkillParseError {
@@ -71,6 +83,11 @@ where
         discover_skills_under_root(&root.path, root.scope, &mut outcome);
     }
 
+    let mut seen: HashSet<String> = HashSet::new();
+    outcome
+        .skills
+        .retain(|skill| seen.insert(skill.name.clone()));
+
     outcome
         .skills
         .sort_by(|a, b| a.name.cmp(&b.name).then_with(|| a.path.cmp(&b.path)));
@@ -85,25 +102,74 @@ pub(crate) fn user_skills_root(codex_home: &Path) -> SkillRoot {
     }
 }
 
+pub(crate) fn system_skills_root(codex_home: &Path) -> SkillRoot {
+    SkillRoot {
+        path: system_cache_root_dir(codex_home),
+        scope: SkillScope::System,
+    }
+}
+
+pub(crate) fn admin_skills_root() -> SkillRoot {
+    SkillRoot {
+        path: PathBuf::from(ADMIN_SKILLS_ROOT),
+        scope: SkillScope::Admin,
+    }
+}
+
 pub(crate) fn repo_skills_root(cwd: &Path) -> Option<SkillRoot> {
-    resolve_root_git_project_for_trust(cwd).map(|repo_root| SkillRoot {
-        path: repo_root
-            .join(REPO_ROOT_CONFIG_DIR_NAME)
-            .join(SKILLS_DIR_NAME),
-        scope: SkillScope::Repo,
+    let base = if cwd.is_dir() { cwd } else { cwd.parent()? };
+    let base = normalize_path(base).unwrap_or_else(|_| base.to_path_buf());
+
+    let repo_root =
+        resolve_root_git_project_for_trust(&base).map(|root| normalize_path(&root).unwrap_or(root));
+
+    let scope = SkillScope::Repo;
+    if let Some(repo_root) = repo_root.as_deref() {
+        for dir in base.ancestors() {
+            let skills_root = dir.join(REPO_ROOT_CONFIG_DIR_NAME).join(SKILLS_DIR_NAME);
+            if skills_root.is_dir() {
+                return Some(SkillRoot {
+                    path: skills_root,
+                    scope,
+                });
+            }
+
+            if dir == repo_root {
+                break;
+            }
+        }
+        return None;
+    }
+
+    let skills_root = base.join(REPO_ROOT_CONFIG_DIR_NAME).join(SKILLS_DIR_NAME);
+    skills_root.is_dir().then_some(SkillRoot {
+        path: skills_root,
+        scope,
     })
 }
 
-fn skill_roots(config: &Config) -> Vec<SkillRoot> {
-    let mut roots = vec![user_skills_root(&config.codex_home)];
+pub(crate) fn skill_roots_for_cwd(codex_home: &Path, cwd: &Path) -> Vec<SkillRoot> {
+    let mut roots = Vec::new();
 
-    if let Some(repo_root) = repo_skills_root(&config.cwd) {
+    if let Some(repo_root) = repo_skills_root(cwd) {
         roots.push(repo_root);
     }
 
+    // Load order matters: we dedupe by name, keeping the first occurrence.
+    // Priority order: repo, user, system, then admin.
+    roots.push(user_skills_root(codex_home));
+    roots.push(system_skills_root(codex_home));
+    if cfg!(unix) {
+        roots.push(admin_skills_root());
+    }
+
     roots
 }
 
+fn skill_roots(config: &Config) -> Vec<SkillRoot> {
+    skill_roots_for_cwd(&config.codex_home, &config.cwd)
+}
+
 fn discover_skills_under_root(root: &Path, scope: SkillScope, outcome: &mut SkillLoadOutcome) {
     let Ok(root) = normalize_path(root) else {
         return;
@@ -149,11 +215,17 @@ fn discover_skills_under_root(root: &Path, scope: SkillScope, outcome: &mut Skil
 
             if file_type.is_file() && file_name == SKILLS_FILENAME {
                 match parse_skill_file(&path, scope) {
-                    Ok(skill) => outcome.skills.push(skill),
-                    Err(err) => outcome.errors.push(SkillError {
-                        path,
-                        message: err.to_string(),
-                    }),
+                    Ok(skill) => {
+                        outcome.skills.push(skill);
+                    }
+                    Err(err) => {
+                        if scope != SkillScope::System {
+                            outcome.errors.push(SkillError {
+                                path,
+                                message: err.to_string(),
+                            });
+                        }
+                    }
                 }
             }
         }
@@ -170,15 +242,29 @@ fn parse_skill_file(path: &Path, scope: SkillScope) -> Result<SkillMetadata, Ski
 
     let name = sanitize_single_line(&parsed.name);
     let description = sanitize_single_line(&parsed.description);
+    let short_description = parsed
+        .metadata
+        .short_description
+        .as_deref()
+        .map(sanitize_single_line)
+        .filter(|value| !value.is_empty());
 
     validate_field(&name, MAX_NAME_LEN, "name")?;
     validate_field(&description, MAX_DESCRIPTION_LEN, "description")?;
+    if let Some(short_description) = short_description.as_deref() {
+        validate_field(
+            short_description,
+            MAX_SHORT_DESCRIPTION_LEN,
+            "metadata.short-description",
+        )?;
+    }
 
     let resolved_path = normalize_path(path).unwrap_or_else(|_| path.to_path_buf());
 
     Ok(SkillMetadata {
         name,
         description,
+        short_description,
         path: resolved_path,
         scope,
     })
@@ -231,31 +317,44 @@ fn extract_frontmatter(contents: &str) -> Option<String> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::config::ConfigOverrides;
-    use crate::config::ConfigToml;
+    use crate::config::ConfigBuilder;
+    use codex_protocol::protocol::SkillScope;
     use pretty_assertions::assert_eq;
     use std::path::Path;
     use std::process::Command;
     use tempfile::TempDir;
 
-    fn make_config(codex_home: &TempDir) -> Config {
-        let mut config = Config::load_from_base_config_with_overrides(
-            ConfigToml::default(),
-            ConfigOverrides::default(),
-            codex_home.path().to_path_buf(),
-        )
-        .expect("defaults for test should always succeed");
+    async fn make_config(codex_home: &TempDir) -> Config {
+        let mut config = ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .build()
+            .await
+            .expect("defaults for test should always succeed");
 
         config.cwd = codex_home.path().to_path_buf();
         config
     }
 
     fn write_skill(codex_home: &TempDir, dir: &str, name: &str, description: &str) -> PathBuf {
-        write_skill_at(codex_home.path(), dir, name, description)
+        write_skill_at(&codex_home.path().join("skills"), dir, name, description)
+    }
+
+    fn write_system_skill(
+        codex_home: &TempDir,
+        dir: &str,
+        name: &str,
+        description: &str,
+    ) -> PathBuf {
+        write_skill_at(
+            &codex_home.path().join("skills/.system"),
+            dir,
+            name,
+            description,
+        )
     }
 
     fn write_skill_at(root: &Path, dir: &str, name: &str, description: &str) -> PathBuf {
-        let skill_dir = root.join(format!("skills/{dir}"));
+        let skill_dir = root.join(dir);
         fs::create_dir_all(&skill_dir).unwrap();
         let indented_description = description.replace('\n', "\n  ");
         let content = format!(
@@ -266,11 +365,11 @@ mod tests {
         path
     }
 
-    #[test]
-    fn loads_valid_skill() {
+    #[tokio::test]
+    async fn loads_valid_skill() {
         let codex_home = tempfile::tempdir().expect("tempdir");
         write_skill(&codex_home, "demo", "demo-skill", "does things\ncarefully");
-        let cfg = make_config(&codex_home);
+        let cfg = make_config(&codex_home).await;
 
         let outcome = load_skills(&cfg);
         assert!(
@@ -282,6 +381,7 @@ mod tests {
         let skill = &outcome.skills[0];
         assert_eq!(skill.name, "demo-skill");
         assert_eq!(skill.description, "does things carefully");
+        assert_eq!(skill.short_description, None);
         let path_str = skill.path.to_string_lossy().replace('\\', "/");
         assert!(
             path_str.ends_with("skills/demo/SKILL.md"),
@@ -289,8 +389,54 @@ mod tests {
         );
     }
 
-    #[test]
-    fn skips_hidden_and_invalid() {
+    #[tokio::test]
+    async fn loads_short_description_from_metadata() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let skill_dir = codex_home.path().join("skills/demo");
+        fs::create_dir_all(&skill_dir).unwrap();
+        let contents = "---\nname: demo-skill\ndescription: long description\nmetadata:\n  short-description: short summary\n---\n\n# Body\n";
+        fs::write(skill_dir.join(SKILLS_FILENAME), contents).unwrap();
+
+        let cfg = make_config(&codex_home).await;
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(
+            outcome.skills[0].short_description,
+            Some("short summary".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn enforces_short_description_length_limits() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let skill_dir = codex_home.path().join("skills/demo");
+        fs::create_dir_all(&skill_dir).unwrap();
+        let too_long = "x".repeat(MAX_SHORT_DESCRIPTION_LEN + 1);
+        let contents = format!(
+            "---\nname: demo-skill\ndescription: long description\nmetadata:\n  short-description: {too_long}\n---\n\n# Body\n"
+        );
+        fs::write(skill_dir.join(SKILLS_FILENAME), contents).unwrap();
+
+        let cfg = make_config(&codex_home).await;
+        let outcome = load_skills(&cfg);
+        assert_eq!(outcome.skills.len(), 0);
+        assert_eq!(outcome.errors.len(), 1);
+        assert!(
+            outcome.errors[0]
+                .message
+                .contains("invalid metadata.short-description"),
+            "expected length error, got: {:?}",
+            outcome.errors
+        );
+    }
+
+    #[tokio::test]
+    async fn skips_hidden_and_invalid() {
         let codex_home = tempfile::tempdir().expect("tempdir");
         let hidden_dir = codex_home.path().join("skills/.hidden");
         fs::create_dir_all(&hidden_dir).unwrap();
@@ -305,7 +451,7 @@ mod tests {
         fs::create_dir_all(&invalid_dir).unwrap();
         fs::write(invalid_dir.join(SKILLS_FILENAME), "---\nname: bad").unwrap();
 
-        let cfg = make_config(&codex_home);
+        let cfg = make_config(&codex_home).await;
         let outcome = load_skills(&cfg);
         assert_eq!(outcome.skills.len(), 0);
         assert_eq!(outcome.errors.len(), 1);
@@ -317,12 +463,12 @@ mod tests {
         );
     }
 
-    #[test]
-    fn enforces_length_limits() {
+    #[tokio::test]
+    async fn enforces_length_limits() {
         let codex_home = tempfile::tempdir().expect("tempdir");
         let max_desc = "\u{1F4A1}".repeat(MAX_DESCRIPTION_LEN);
         write_skill(&codex_home, "max-len", "max-len", &max_desc);
-        let cfg = make_config(&codex_home);
+        let cfg = make_config(&codex_home).await;
 
         let outcome = load_skills(&cfg);
         assert!(
@@ -343,8 +489,8 @@ mod tests {
         );
     }
 
-    #[test]
-    fn loads_skills_from_repo_root() {
+    #[tokio::test]
+    async fn loads_skills_from_repo_root() {
         let codex_home = tempfile::tempdir().expect("tempdir");
         let repo_dir = tempfile::tempdir().expect("tempdir");
 
@@ -360,7 +506,7 @@ mod tests {
             .join(REPO_ROOT_CONFIG_DIR_NAME)
             .join(SKILLS_DIR_NAME);
         write_skill_at(&skills_root, "repo", "repo-skill", "from repo");
-        let mut cfg = make_config(&codex_home);
+        let mut cfg = make_config(&codex_home).await;
         cfg.cwd = repo_dir.path().to_path_buf();
         let repo_root = normalize_path(&skills_root).unwrap_or_else(|_| skills_root.clone());
 
@@ -375,4 +521,365 @@ mod tests {
         assert_eq!(skill.name, "repo-skill");
         assert!(skill.path.starts_with(&repo_root));
     }
+
+    #[tokio::test]
+    async fn loads_skills_from_nearest_codex_dir_under_repo_root() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let repo_dir = tempfile::tempdir().expect("tempdir");
+
+        let status = Command::new("git")
+            .arg("init")
+            .current_dir(repo_dir.path())
+            .status()
+            .expect("git init");
+        assert!(status.success(), "git init failed");
+
+        let nested_dir = repo_dir.path().join("nested/inner");
+        fs::create_dir_all(&nested_dir).unwrap();
+
+        write_skill_at(
+            &repo_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "root",
+            "root-skill",
+            "from root",
+        );
+        write_skill_at(
+            &repo_dir
+                .path()
+                .join("nested")
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "nested",
+            "nested-skill",
+            "from nested",
+        );
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = nested_dir;
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "nested-skill");
+    }
+
+    #[tokio::test]
+    async fn loads_skills_from_codex_dir_when_not_git_repo() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let work_dir = tempfile::tempdir().expect("tempdir");
+
+        write_skill_at(
+            &work_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "local",
+            "local-skill",
+            "from cwd",
+        );
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = work_dir.path().to_path_buf();
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "local-skill");
+        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+    }
+
+    #[tokio::test]
+    async fn deduplicates_by_name_preferring_repo_over_user() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let repo_dir = tempfile::tempdir().expect("tempdir");
+
+        let status = Command::new("git")
+            .arg("init")
+            .current_dir(repo_dir.path())
+            .status()
+            .expect("git init");
+        assert!(status.success(), "git init failed");
+
+        write_skill(&codex_home, "user", "dupe-skill", "from user");
+        write_skill_at(
+            &repo_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "repo",
+            "dupe-skill",
+            "from repo",
+        );
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = repo_dir.path().to_path_buf();
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "dupe-skill");
+        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+    }
+
+    #[tokio::test]
+    async fn loads_system_skills_when_present() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+
+        write_system_skill(&codex_home, "system", "dupe-skill", "from system");
+        write_skill(&codex_home, "user", "dupe-skill", "from user");
+
+        let cfg = make_config(&codex_home).await;
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].description, "from user");
+        assert_eq!(outcome.skills[0].scope, SkillScope::User);
+    }
+
+    #[tokio::test]
+    async fn repo_skills_search_does_not_escape_repo_root() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let outer_dir = tempfile::tempdir().expect("tempdir");
+        let repo_dir = outer_dir.path().join("repo");
+        fs::create_dir_all(&repo_dir).unwrap();
+
+        write_skill_at(
+            &outer_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "outer",
+            "outer-skill",
+            "from outer",
+        );
+
+        let status = Command::new("git")
+            .arg("init")
+            .current_dir(&repo_dir)
+            .status()
+            .expect("git init");
+        assert!(status.success(), "git init failed");
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = repo_dir;
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 0);
+    }
+
+    #[tokio::test]
+    async fn loads_skills_when_cwd_is_file_in_repo() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let repo_dir = tempfile::tempdir().expect("tempdir");
+
+        let status = Command::new("git")
+            .arg("init")
+            .current_dir(repo_dir.path())
+            .status()
+            .expect("git init");
+        assert!(status.success(), "git init failed");
+
+        write_skill_at(
+            &repo_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "repo",
+            "repo-skill",
+            "from repo",
+        );
+        let file_path = repo_dir.path().join("some-file.txt");
+        fs::write(&file_path, "contents").unwrap();
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = file_path;
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "repo-skill");
+        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+    }
+
+    #[tokio::test]
+    async fn non_git_repo_skills_search_does_not_walk_parents() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let outer_dir = tempfile::tempdir().expect("tempdir");
+        let nested_dir = outer_dir.path().join("nested/inner");
+        fs::create_dir_all(&nested_dir).unwrap();
+
+        write_skill_at(
+            &outer_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "outer",
+            "outer-skill",
+            "from outer",
+        );
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = nested_dir;
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 0);
+    }
+
+    #[tokio::test]
+    async fn loads_skills_from_system_cache_when_present() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let work_dir = tempfile::tempdir().expect("tempdir");
+
+        write_system_skill(&codex_home, "system", "system-skill", "from system");
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = work_dir.path().to_path_buf();
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "system-skill");
+        assert_eq!(outcome.skills[0].scope, SkillScope::System);
+    }
+
+    #[tokio::test]
+    async fn skill_roots_include_admin_with_lowest_priority_on_unix() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let cfg = make_config(&codex_home).await;
+
+        let scopes: Vec<SkillScope> = skill_roots(&cfg)
+            .into_iter()
+            .map(|root| root.scope)
+            .collect();
+        let mut expected = vec![SkillScope::User, SkillScope::System];
+        if cfg!(unix) {
+            expected.push(SkillScope::Admin);
+        }
+        assert_eq!(scopes, expected);
+    }
+
+    #[tokio::test]
+    async fn deduplicates_by_name_preferring_system_over_admin() {
+        let system_dir = tempfile::tempdir().expect("tempdir");
+        let admin_dir = tempfile::tempdir().expect("tempdir");
+
+        write_skill_at(system_dir.path(), "system", "dupe-skill", "from system");
+        write_skill_at(admin_dir.path(), "admin", "dupe-skill", "from admin");
+
+        let outcome = load_skills_from_roots([
+            SkillRoot {
+                path: system_dir.path().to_path_buf(),
+                scope: SkillScope::System,
+            },
+            SkillRoot {
+                path: admin_dir.path().to_path_buf(),
+                scope: SkillScope::Admin,
+            },
+        ]);
+
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "dupe-skill");
+        assert_eq!(outcome.skills[0].scope, SkillScope::System);
+    }
+
+    #[tokio::test]
+    async fn deduplicates_by_name_preferring_user_over_system() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let work_dir = tempfile::tempdir().expect("tempdir");
+
+        write_skill(&codex_home, "user", "dupe-skill", "from user");
+        write_system_skill(&codex_home, "system", "dupe-skill", "from system");
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = work_dir.path().to_path_buf();
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "dupe-skill");
+        assert_eq!(outcome.skills[0].scope, SkillScope::User);
+    }
+
+    #[tokio::test]
+    async fn deduplicates_by_name_preferring_repo_over_system() {
+        let codex_home = tempfile::tempdir().expect("tempdir");
+        let repo_dir = tempfile::tempdir().expect("tempdir");
+
+        let status = Command::new("git")
+            .arg("init")
+            .current_dir(repo_dir.path())
+            .status()
+            .expect("git init");
+        assert!(status.success(), "git init failed");
+
+        write_skill_at(
+            &repo_dir
+                .path()
+                .join(REPO_ROOT_CONFIG_DIR_NAME)
+                .join(SKILLS_DIR_NAME),
+            "repo",
+            "dupe-skill",
+            "from repo",
+        );
+        write_system_skill(&codex_home, "system", "dupe-skill", "from system");
+
+        let mut cfg = make_config(&codex_home).await;
+        cfg.cwd = repo_dir.path().to_path_buf();
+
+        let outcome = load_skills(&cfg);
+        assert!(
+            outcome.errors.is_empty(),
+            "unexpected errors: {:?}",
+            outcome.errors
+        );
+        assert_eq!(outcome.skills.len(), 1);
+        assert_eq!(outcome.skills[0].name, "dupe-skill");
+        assert_eq!(outcome.skills[0].scope, SkillScope::Repo);
+    }
 }

codex-rs/core/src/skills/manager.rs

@@ -5,9 +5,8 @@ use std::sync::RwLock;
 
 use crate::skills::SkillLoadOutcome;
 use crate::skills::loader::load_skills_from_roots;
-use crate::skills::loader::repo_skills_root;
-use crate::skills::loader::user_skills_root;
-
+use crate::skills::loader::skill_roots_for_cwd;
+use crate::skills::system::install_system_skills;
 pub struct SkillsManager {
     codex_home: PathBuf,
     cache_by_cwd: RwLock<HashMap<PathBuf, SkillLoadOutcome>>,
@@ -15,6 +14,10 @@ pub struct SkillsManager {
 
 impl SkillsManager {
     pub fn new(codex_home: PathBuf) -> Self {
+        if let Err(err) = install_system_skills(&codex_home) {
+            tracing::error!("failed to install system skills: {err}");
+        }
+
         Self {
             codex_home,
             cache_by_cwd: RwLock::new(HashMap::new()),
@@ -22,18 +25,19 @@ impl SkillsManager {
     }
 
     pub fn skills_for_cwd(&self, cwd: &Path) -> SkillLoadOutcome {
+        self.skills_for_cwd_with_options(cwd, false)
+    }
+
+    pub fn skills_for_cwd_with_options(&self, cwd: &Path, force_reload: bool) -> SkillLoadOutcome {
         let cached = match self.cache_by_cwd.read() {
             Ok(cache) => cache.get(cwd).cloned(),
             Err(err) => err.into_inner().get(cwd).cloned(),
         };
-        if let Some(outcome) = cached {
+        if !force_reload && let Some(outcome) = cached {
             return outcome;
         }
 
-        let mut roots = vec![user_skills_root(&self.codex_home)];
-        if let Some(repo_root) = repo_skills_root(cwd) {
-            roots.push(repo_root);
-        }
+        let roots = skill_roots_for_cwd(&self.codex_home, cwd);
         let outcome = load_skills_from_roots(roots);
         match self.cache_by_cwd.write() {
             Ok(mut cache) => {

codex-rs/core/src/skills/mod.rs

@@ -3,6 +3,7 @@ pub mod loader;
 pub mod manager;
 pub mod model;
 pub mod render;
+pub mod system;
 
 pub(crate) use injection::SkillInjections;
 pub(crate) use injection::build_skill_injections;

codex-rs/core/src/skills/model.rs

@@ -6,6 +6,7 @@ use codex_protocol::protocol::SkillScope;
 pub struct SkillMetadata {
     pub name: String,
     pub description: String,
+    pub short_description: Option<String>,
     pub path: PathBuf,
     pub scope: SkillScope,
 }

codex-rs/core/src/skills/render.rs

@@ -7,14 +7,13 @@ pub fn render_skills_section(skills: &[SkillMetadata]) -> Option<String> {
 
     let mut lines: Vec<String> = Vec::new();
     lines.push("## Skills".to_string());
-    lines.push("These skills are discovered at startup from ~/.codex/skills; each entry shows name, description, and file path so you can open the source for full instructions. Content is not inlined to keep context lean.".to_string());
+    lines.push("These skills are discovered at startup from multiple local sources. Each entry includes a name, description, and file path so you can open the source for full instructions.".to_string());
 
     for skill in skills {
         let path_str = skill.path.to_string_lossy().replace('\\', "/");
-        lines.push(format!(
-            "- {}: {} (file: {})",
-            skill.name, skill.description, path_str
-        ));
+        let name = skill.name.as_str();
+        let description = skill.description.as_str();
+        lines.push(format!("- {name}: {description} (file: {path_str})"));
     }
 
     lines.push(

codex-rs/core/src/skills/system.rs

@@ -0,0 +1,165 @@
+use codex_utils_absolute_path::AbsolutePathBuf;
+use include_dir::Dir;
+use std::collections::hash_map::DefaultHasher;
+use std::fs;
+use std::hash::Hash;
+use std::hash::Hasher;
+use std::path::Path;
+use std::path::PathBuf;
+
+use thiserror::Error;
+
+const SYSTEM_SKILLS_DIR: Dir =
+    include_dir::include_dir!("$CARGO_MANIFEST_DIR/src/skills/assets/samples");
+
+const SYSTEM_SKILLS_DIR_NAME: &str = ".system";
+const SKILLS_DIR_NAME: &str = "skills";
+const SYSTEM_SKILLS_MARKER_FILENAME: &str = ".codex-system-skills.marker";
+const SYSTEM_SKILLS_MARKER_SALT: &str = "v1";
+
+/// Returns the on-disk cache location for embedded system skills.
+///
+/// This is typically located at `CODEX_HOME/skills/.system`.
+pub(crate) fn system_cache_root_dir(codex_home: &Path) -> PathBuf {
+    AbsolutePathBuf::try_from(codex_home)
+        .and_then(|codex_home| system_cache_root_dir_abs(&codex_home))
+        .map(AbsolutePathBuf::into_path_buf)
+        .unwrap_or_else(|_| {
+            codex_home
+                .join(SKILLS_DIR_NAME)
+                .join(SYSTEM_SKILLS_DIR_NAME)
+        })
+}
+
+fn system_cache_root_dir_abs(codex_home: &AbsolutePathBuf) -> std::io::Result<AbsolutePathBuf> {
+    codex_home
+        .join(SKILLS_DIR_NAME)?
+        .join(SYSTEM_SKILLS_DIR_NAME)
+}
+
+/// Installs embedded system skills into `CODEX_HOME/skills/.system`.
+///
+/// Clears any existing system skills directory first and then writes the embedded
+/// skills directory into place.
+///
+/// To avoid doing unnecessary work on every startup, a marker file is written
+/// with a fingerprint of the embedded directory. When the marker matches, the
+/// install is skipped.
+pub(crate) fn install_system_skills(codex_home: &Path) -> Result<(), SystemSkillsError> {
+    let codex_home = AbsolutePathBuf::try_from(codex_home)
+        .map_err(|source| SystemSkillsError::io("normalize codex home dir", source))?;
+    let skills_root_dir = codex_home
+        .join(SKILLS_DIR_NAME)
+        .map_err(|source| SystemSkillsError::io("resolve skills root dir", source))?;
+    fs::create_dir_all(skills_root_dir.as_path())
+        .map_err(|source| SystemSkillsError::io("create skills root dir", source))?;
+
+    let dest_system = system_cache_root_dir_abs(&codex_home)
+        .map_err(|source| SystemSkillsError::io("resolve system skills cache root dir", source))?;
+
+    let marker_path = dest_system
+        .join(SYSTEM_SKILLS_MARKER_FILENAME)
+        .map_err(|source| SystemSkillsError::io("resolve system skills marker path", source))?;
+    let expected_fingerprint = embedded_system_skills_fingerprint();
+    if dest_system.as_path().is_dir()
+        && read_marker(&marker_path).is_ok_and(|marker| marker == expected_fingerprint)
+    {
+        return Ok(());
+    }
+
+    if dest_system.as_path().exists() {
+        fs::remove_dir_all(dest_system.as_path())
+            .map_err(|source| SystemSkillsError::io("remove existing system skills dir", source))?;
+    }
+
+    write_embedded_dir(&SYSTEM_SKILLS_DIR, &dest_system)?;
+    fs::write(marker_path.as_path(), format!("{expected_fingerprint}\n"))
+        .map_err(|source| SystemSkillsError::io("write system skills marker", source))?;
+    Ok(())
+}
+
+fn read_marker(path: &AbsolutePathBuf) -> Result<String, SystemSkillsError> {
+    Ok(fs::read_to_string(path.as_path())
+        .map_err(|source| SystemSkillsError::io("read system skills marker", source))?
+        .trim()
+        .to_string())
+}
+
+fn embedded_system_skills_fingerprint() -> String {
+    let mut items: Vec<(String, Option<u64>)> = SYSTEM_SKILLS_DIR
+        .entries()
+        .iter()
+        .map(|entry| match entry {
+            include_dir::DirEntry::Dir(dir) => (dir.path().to_string_lossy().to_string(), None),
+            include_dir::DirEntry::File(file) => {
+                let mut file_hasher = DefaultHasher::new();
+                file.contents().hash(&mut file_hasher);
+                (
+                    file.path().to_string_lossy().to_string(),
+                    Some(file_hasher.finish()),
+                )
+            }
+        })
+        .collect();
+    items.sort_unstable_by(|(a, _), (b, _)| a.cmp(b));
+
+    let mut hasher = DefaultHasher::new();
+    SYSTEM_SKILLS_MARKER_SALT.hash(&mut hasher);
+    for (path, contents_hash) in items {
+        path.hash(&mut hasher);
+        contents_hash.hash(&mut hasher);
+    }
+    format!("{:x}", hasher.finish())
+}
+
+/// Writes the embedded `include_dir::Dir` to disk under `dest`.
+///
+/// Preserves the embedded directory structure.
+fn write_embedded_dir(dir: &Dir<'_>, dest: &AbsolutePathBuf) -> Result<(), SystemSkillsError> {
+    fs::create_dir_all(dest.as_path())
+        .map_err(|source| SystemSkillsError::io("create system skills dir", source))?;
+
+    for entry in dir.entries() {
+        match entry {
+            include_dir::DirEntry::Dir(subdir) => {
+                let subdir_dest = dest.join(subdir.path()).map_err(|source| {
+                    SystemSkillsError::io("resolve system skills subdir", source)
+                })?;
+                fs::create_dir_all(subdir_dest.as_path()).map_err(|source| {
+                    SystemSkillsError::io("create system skills subdir", source)
+                })?;
+                write_embedded_dir(subdir, dest)?;
+            }
+            include_dir::DirEntry::File(file) => {
+                let path = dest.join(file.path()).map_err(|source| {
+                    SystemSkillsError::io("resolve system skills file", source)
+                })?;
+                if let Some(parent) = path.as_path().parent() {
+                    fs::create_dir_all(parent).map_err(|source| {
+                        SystemSkillsError::io("create system skills file parent", source)
+                    })?;
+                }
+                fs::write(path.as_path(), file.contents())
+                    .map_err(|source| SystemSkillsError::io("write system skill file", source))?;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[derive(Debug, Error)]
+pub(crate) enum SystemSkillsError {
+    #[error("io error while {action}: {source}")]
+    Io {
+        action: &'static str,
+        #[source]
+        source: std::io::Error,
+    },
+}
+
+impl SystemSkillsError {
+    fn io(action: &'static str, source: std::io::Error) -> Self {
+        Self::Io { action, source }
+    }
+}

codex-rs/core/src/tasks/ghost_snapshot.rs

@@ -41,31 +41,36 @@ impl SessionTask for GhostSnapshotTask {
     ) -> Option<String> {
         tokio::task::spawn(async move {
             let token = self.token;
+            let warnings_enabled = !ctx.ghost_snapshot.disable_warnings;
             // Channel used to signal when the snapshot work has finished so the
             // timeout warning task can exit early without sending a warning.
             let (snapshot_done_tx, snapshot_done_rx) = oneshot::channel::<()>();
-            let ctx_for_warning = ctx.clone();
-            let cancellation_token_for_warning = cancellation_token.clone();
-            let session_for_warning = session.clone();
-            // Fire a generic warning if the snapshot is still running after
-            // three minutes; this helps users discover large untracked files
-            // that might need to be added to .gitignore.
-            tokio::task::spawn(async move {
-                tokio::select! {
-                    _ = tokio::time::sleep(SNAPSHOT_WARNING_THRESHOLD) => {
-                        session_for_warning.session
-                            .send_event(
-                                &ctx_for_warning,
-                                EventMsg::Warning(WarningEvent {
-                                    message: "Repository snapshot is taking longer than expected. Large untracked or ignored files can slow snapshots; consider adding large files or directories to .gitignore or disabling `undo` in your config.".to_string()
-                                }),
-                            )
-                            .await;
+            if warnings_enabled {
+                let ctx_for_warning = ctx.clone();
+                let cancellation_token_for_warning = cancellation_token.clone();
+                let session_for_warning = session.clone();
+                // Fire a generic warning if the snapshot is still running after
+                // three minutes; this helps users discover large untracked files
+                // that might need to be added to .gitignore.
+                tokio::task::spawn(async move {
+                    tokio::select! {
+                        _ = tokio::time::sleep(SNAPSHOT_WARNING_THRESHOLD) => {
+                            session_for_warning.session
+                                .send_event(
+                                    &ctx_for_warning,
+                                    EventMsg::Warning(WarningEvent {
+                                        message: "Repository snapshot is taking longer than expected. Large untracked or ignored files can slow snapshots; consider adding large files or directories to .gitignore or disabling `undo` in your config.".to_string()
+                                    }),
+                                )
+                                .await;
+                        }
+                        _ = snapshot_done_rx => {}
+                        _ = cancellation_token_for_warning.cancelled() => {}
                     }
-                    _ = snapshot_done_rx => {}
-                    _ = cancellation_token_for_warning.cancelled() => {}
-                }
-            });
+                });
+            } else {
+                drop(snapshot_done_rx);
+            }
 
             let ctx_for_task = ctx.clone();
             let cancelled = tokio::select! {
@@ -84,18 +89,20 @@ impl SessionTask for GhostSnapshotTask {
                     {
                         Ok(Ok((ghost_commit, report))) => {
                             info!("ghost snapshot blocking task finished");
-                            for message in format_snapshot_warnings(
-                                ghost_snapshot.ignore_large_untracked_files,
-                                ghost_snapshot.ignore_large_untracked_dirs,
-                                &report,
-                            ) {
-                                session
-                                    .session
-                                    .send_event(
-                                        &ctx_for_task,
-                                        EventMsg::Warning(WarningEvent { message }),
-                                    )
-                                    .await;
+                            if warnings_enabled {
+                                for message in format_snapshot_warnings(
+                                    ghost_snapshot.ignore_large_untracked_files,
+                                    ghost_snapshot.ignore_large_untracked_dirs,
+                                    &report,
+                                ) {
+                                    session
+                                        .session
+                                        .send_event(
+                                            &ctx_for_task,
+                                            EventMsg::Warning(WarningEvent { message }),
+                                        )
+                                        .await;
+                                }
                             }
                             session
                                 .session

codex-rs/core/src/tasks/user_shell.rs

@@ -59,7 +59,7 @@ impl SessionTask for UserShellCommandTask {
         cancellation_token: CancellationToken,
     ) -> Option<String> {
         let event = EventMsg::TaskStarted(TaskStartedEvent {
-            model_context_window: turn_context.client.get_model_context_window(),
+            model_context_window: turn_context.client.get_model_context_window().await,
         });
         let session = session.clone_session();
         session.send_event(turn_context.as_ref(), event).await;