Add files using upload-large-folder tool

codex-rs/config/examples/generate-proto.rs

@@ -0,0 +1,19 @@
+use std::path::PathBuf;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let Some(proto_dir_arg) = std::env::args().nth(1) else {
+        eprintln!("Usage: generate-proto <proto-dir>");
+        std::process::exit(1);
+    };
+
+    let proto_dir = PathBuf::from(proto_dir_arg);
+    let proto_file = proto_dir.join("codex.thread_config.v1.proto");
+
+    tonic_prost_build::configure()
+        .build_client(true)
+        .build_server(true)
+        .out_dir(&proto_dir)
+        .compile_protos(&[proto_file], &[proto_dir])?;
+
+    Ok(())
+}

codex-rs/config/scripts/generate-proto.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$script_dir/../../.." && pwd)"
+proto_dir="$repo_root/codex-rs/config/src/thread_config/proto"
+generated="$proto_dir/codex.thread_config.v1.rs"
+tmpdir="$(mktemp -d)"
+
+cleanup() {
+    rm -rf "$tmpdir"
+}
+trap cleanup EXIT
+
+(
+    cd "$repo_root/codex-rs"
+    CARGO_TARGET_DIR="$tmpdir/target" cargo run \
+        -p codex-config \
+        --example generate-proto \
+        -- "$proto_dir"
+)
+
+if ! sed -n '2p' "$generated" | grep -q 'clippy::trivially_copy_pass_by_ref'; then
+    {
+        sed -n '1p' "$generated"
+        printf '#![allow(clippy::trivially_copy_pass_by_ref)]\n'
+        sed '1d' "$generated"
+    } > "$tmpdir/generated.rs"
+    mv "$tmpdir/generated.rs" "$generated"
+fi
+
+rustfmt --edition 2024 "$generated"
+
+awk '
+    NR == 3 && previous ~ /clippy::trivially_copy_pass_by_ref/ && $0 != "" { print "" }
+    { print; previous = $0 }
+' "$generated" > "$tmpdir/formatted.rs"
+mv "$tmpdir/formatted.rs" "$generated"

codex-rs/config/src/application_requirements_tests.rs

@@ -0,0 +1,251 @@
+//! Application requirements use managed precedence and deny unlisted destinations.
+
+use super::*;
+use crate::ConfigRequirements;
+use crate::ConfigRequirementsToml;
+use crate::ConfigRequirementsWithSources;
+use crate::RequirementSource;
+use crate::RequirementsLayerEntry;
+use crate::Sourced;
+use crate::compose_requirements_for_hostname;
+use pretty_assertions::assert_eq;
+
+const INSTALLATION: &str = r#"
+[application.network.domains]
+"shared.example.com" = "allow"
+"installed.example.com" = "allow"
+"blocked.example.com" = "deny"
+"#;
+const WORKSPACE: &str = r#"
+[application.network.domains]
+"shared.example.com" = "allow"
+"workspace.example.com" = "allow"
+"blocked.example.com" = "allow"
+"#;
+const MERGED: &str = r#"
+[application.network.domains]
+"shared.example.com" = "allow"
+"installed.example.com" = "allow"
+"workspace.example.com" = "allow"
+"blocked.example.com" = "allow"
+"#;
+
+fn parse(contents: &str) -> ConfigRequirementsToml {
+    toml::from_str(contents).expect("valid application requirements")
+}
+
+fn cloud_source() -> RequirementSource {
+    RequirementSource::EnterpriseManaged {
+        id: "workspace".to_string(),
+        name: "Workspace policy".to_string(),
+    }
+}
+
+fn managed_source() -> RequirementSource {
+    RequirementSource::MdmManagedPreferences {
+        domain: "com.openai.codex".to_string(),
+        key: "requirements".to_string(),
+    }
+}
+
+#[test]
+fn application_network_defaults_to_enabled_and_denies_unlisted_domains() {
+    assert!(parse("[application]").is_empty());
+    let requirements = parse("[application.network]");
+    assert!(!requirements.is_empty());
+    assert_eq!(
+        requirements.application,
+        Some(ApplicationRequirementsToml {
+            network: Some(ApplicationNetworkRequirementsToml {
+                enabled: true,
+                domains: BTreeMap::new(),
+            }),
+        }),
+    );
+    assert_eq!(
+        parse("[application.network.domains]\n\"EXAMPLE.com.\" = \"deny\""),
+        parse("[application.network.domains]\n\"example.com\" = \"deny\""),
+    );
+}
+
+#[test]
+fn application_network_is_preserved_from_each_managed_source() {
+    for source in [
+        RequirementSource::SystemRequirementsToml {
+            file: crate::AbsolutePathBuf::try_from(std::env::temp_dir().join("requirements.toml"))
+                .expect("absolute requirements path"),
+        },
+        managed_source(),
+        cloud_source(),
+    ] {
+        let requirements = compose_requirements_for_hostname(
+            [RequirementsLayerEntry::from_toml(
+                source.clone(),
+                INSTALLATION,
+            )],
+            /*hostname*/ None,
+        )
+        .expect("compose application requirements")
+        .expect("application requirements are not empty");
+        assert_eq!(
+            requirements,
+            ConfigRequirementsWithSources {
+                application: Some(Sourced::new(
+                    parse(INSTALLATION).application.expect("application"),
+                    source,
+                )),
+                ..Default::default()
+            },
+        );
+        let normalized: ConfigRequirements =
+            requirements.clone().try_into().expect("runtime policy");
+        assert_eq!(normalized.application, requirements.application);
+    }
+}
+
+#[test]
+fn application_network_uses_regular_toml_precedence() {
+    let installed_wins = MERGED.replace(
+        "\"blocked.example.com\" = \"allow\"",
+        "\"blocked.example.com\" = \"deny\"",
+    );
+    let disabled_installation = format!("[application.network]\nenabled = false\n{INSTALLATION}");
+    for (low, high, expected) in [
+        (INSTALLATION, WORKSPACE, MERGED),
+        (WORKSPACE, INSTALLATION, installed_wins.as_str()),
+        (
+            INSTALLATION,
+            "[application.network]\nenabled = false",
+            disabled_installation.as_str(),
+        ),
+        (
+            disabled_installation.as_str(),
+            "[application.network]\nenabled = true",
+            INSTALLATION,
+        ),
+        (
+            "[application.network]\nenabled = false",
+            INSTALLATION,
+            disabled_installation.as_str(),
+        ),
+        (INSTALLATION, "[application.network]", INSTALLATION),
+        (INSTALLATION, "", INSTALLATION),
+        ("[application]", INSTALLATION, INSTALLATION),
+        ("[application.network]", WORKSPACE, WORKSPACE),
+        (
+            "[application.network.domains]\n'example.com' = 'allow'",
+            "[application.network.domains]\n'EXAMPLE.COM.' = 'deny'",
+            "[application.network.domains]\n'example.com' = 'deny'",
+        ),
+        (
+            "[application.network.domains]\n'EXAMPLE.COM.' = 'deny'",
+            "[application.network.domains]\n'example.com' = 'allow'",
+            "[application.network.domains]\n'example.com' = 'allow'",
+        ),
+    ] {
+        let composed = compose_requirements_for_hostname(
+            [
+                RequirementsLayerEntry::from_toml(managed_source(), low),
+                RequirementsLayerEntry::from_toml(cloud_source(), high),
+            ],
+            /*hostname*/ None,
+        )
+        .expect("compose application requirements")
+        .expect("configured requirements");
+        assert_eq!(
+            composed.into_toml(),
+            parse(expected),
+            "low: {low}, high: {high}"
+        );
+    }
+}
+
+#[test]
+fn legacy_application_merge_uses_whole_table_precedence() {
+    for (high, low) in [
+        (INSTALLATION, WORKSPACE),
+        (WORKSPACE, INSTALLATION),
+        ("[application.network]\nenabled = false", INSTALLATION),
+        ("[application]", INSTALLATION),
+    ] {
+        let mut composed = ConfigRequirementsWithSources::default();
+        composed.merge_unset_fields(managed_source(), parse(high));
+        composed.merge_unset_fields(cloud_source(), parse(low));
+        assert_eq!(
+            composed,
+            ConfigRequirementsWithSources {
+                application: Some(Sourced::new(
+                    parse(high).application.expect("application"),
+                    managed_source(),
+                )),
+                ..Default::default()
+            },
+        );
+    }
+    let mut composed = ConfigRequirementsWithSources::default();
+    composed.merge_unset_fields(managed_source(), parse(""));
+    composed.merge_unset_fields(cloud_source(), parse(INSTALLATION));
+    assert_eq!(composed.into_toml(), parse(INSTALLATION));
+}
+
+#[test]
+fn invalid_application_policy_is_rejected_before_layer_overrides() {
+    for invalid in [
+        "[application.network]\nenabled = 'true'",
+        "[application.network]\nallowed_domains = ['example.com']",
+        "[application.network.domains]\n'example.com' = 'prompt'",
+        "[application.network.domains]\n'*.example.com' = 'allow'",
+        "[application.network.domains]\n'https://example.com' = 'allow'",
+        "[application.network.domains]\n'example.com:443' = 'allow'",
+        "[application.network.domains]\n'example..com' = 'allow'",
+        "[application.network.domains]\n' example.com' = 'allow'",
+        "[application.network.domains]\n'EXAMPLE.com' = 'allow'\n'example.com.' = 'deny'",
+    ] {
+        assert!(
+            toml::from_str::<ConfigRequirementsToml>(invalid).is_err(),
+            "{invalid}"
+        );
+        assert!(
+            compose_requirements_for_hostname(
+                [
+                    RequirementsLayerEntry::from_toml(cloud_source(), invalid),
+                    RequirementsLayerEntry::from_toml(managed_source(), INSTALLATION),
+                ],
+                /*hostname*/ None,
+            )
+            .is_err(),
+            "{invalid}"
+        );
+    }
+}
+
+#[test]
+fn cloud_bundle_application_network_uses_managed_precedence() {
+    let base_dir =
+        crate::AbsolutePathBuf::try_from(std::env::temp_dir()).expect("absolute base directory");
+    let bundle = crate::CloudConfigBundle {
+        requirements_toml: crate::CloudRequirementsTomlBundle {
+            enterprise_managed: vec![crate::CloudRequirementsFragment {
+                id: "workspace".to_string(),
+                name: "Workspace".to_string(),
+                contents: WORKSPACE.to_string(),
+            }],
+        },
+        ..Default::default()
+    };
+    let mut layers = crate::CloudConfigBundleLayers::from_bundle(bundle, &base_dir)
+        .expect("load cloud bundle")
+        .enterprise_managed_requirements;
+    layers.push(RequirementsLayerEntry::from_toml(
+        managed_source(),
+        INSTALLATION,
+    ));
+    let composed = compose_requirements_for_hostname(layers, /*hostname*/ None)
+        .expect("compose cloud and installation requirements")
+        .expect("requirements");
+    let expected = MERGED.replace(
+        "\"blocked.example.com\" = \"allow\"",
+        "\"blocked.example.com\" = \"deny\"",
+    );
+    assert_eq!(composed.into_toml(), parse(&expected));
+}

codex-rs/config/src/auth_policy.rs

@@ -0,0 +1,61 @@
+use codex_protocol::config_types::ForcedLoginMethod;
+
+/// Authentication restrictions supplied by locally managed requirements.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ManagedAuthPolicy {
+    pub allowed_login_methods: Option<Vec<ForcedLoginMethod>>,
+    pub allowed_chatgpt_workspaces: Option<Vec<String>>,
+}
+
+impl ManagedAuthPolicy {
+    pub fn allows_login_method(
+        &self,
+        method: ForcedLoginMethod,
+        forced_login_method: Option<ForcedLoginMethod>,
+        forced_workspaces: Option<&[String]>,
+    ) -> bool {
+        forced_login_method.is_none_or(|forced| forced == method)
+            && self
+                .allowed_login_methods
+                .as_ref()
+                .is_none_or(|allowed| allowed.contains(&method))
+            && (method != ForcedLoginMethod::Chatgpt
+                || self
+                    .effective_chatgpt_workspaces(forced_workspaces)
+                    .is_none_or(|workspaces| !workspaces.is_empty()))
+    }
+
+    pub fn allowed_login_methods(
+        &self,
+        forced_login_method: Option<ForcedLoginMethod>,
+        forced_workspaces: Option<&[String]>,
+    ) -> Vec<ForcedLoginMethod> {
+        [ForcedLoginMethod::Api, ForcedLoginMethod::Chatgpt]
+            .into_iter()
+            .filter(|method| {
+                self.allows_login_method(*method, forced_login_method, forced_workspaces)
+            })
+            .collect()
+    }
+
+    pub fn effective_chatgpt_workspaces(
+        &self,
+        forced_workspaces: Option<&[String]>,
+    ) -> Option<Vec<String>> {
+        match (
+            forced_workspaces,
+            self.allowed_chatgpt_workspaces.as_deref(),
+        ) {
+            (Some(forced), Some(allowed)) => Some(
+                forced
+                    .iter()
+                    .filter(|workspace| allowed.contains(workspace))
+                    .cloned()
+                    .collect(),
+            ),
+            (Some(forced), None) => Some(forced.to_vec()),
+            (None, Some(allowed)) => Some(allowed.to_vec()),
+            (None, None) => None,
+        }
+    }
+}

codex-rs/config/src/browser_computer_use_requirements.rs

@@ -0,0 +1,116 @@
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::BTreeMap;
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum AllowDenyRequirementToml {
+    Allow,
+    Deny,
+}
+
+#[derive(Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+pub struct BrowserUseOriginPolicyToml {
+    pub access: Option<AllowDenyRequirementToml>,
+    pub downloads: Option<AllowDenyRequirementToml>,
+    pub uploads: Option<AllowDenyRequirementToml>,
+    pub full_cdp_access: Option<AllowDenyRequirementToml>,
+    pub auto_review: Option<AllowDenyRequirementToml>,
+    pub persistent_approval: Option<bool>,
+    pub access_approval_lifetime: Option<BrowserUseAccessApprovalLifetimeToml>,
+}
+
+impl BrowserUseOriginPolicyToml {
+    fn is_empty(&self) -> bool {
+        self.access.is_none()
+            && self.downloads.is_none()
+            && self.uploads.is_none()
+            && self.full_cdp_access.is_none()
+            && self.auto_review.is_none()
+            && self.persistent_approval.is_none()
+            && self.access_approval_lifetime.is_none()
+    }
+}
+
+#[derive(Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum BrowserUseAccessApprovalLifetimeToml {
+    Turn,
+    Thread,
+}
+
+#[derive(Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+pub struct BrowserUseRequirementsToml {
+    pub allow_webmcp: Option<bool>,
+    pub allow_history_access: Option<bool>,
+    pub disable_auto_review: Option<bool>,
+    pub allow_global_persistent_approval: Option<bool>,
+    pub default_origin_policy: Option<BrowserUseOriginPolicyToml>,
+    pub origins: Option<BTreeMap<String, BrowserUseOriginPolicyToml>>,
+}
+
+impl BrowserUseRequirementsToml {
+    pub fn is_empty(&self) -> bool {
+        self.allow_webmcp.is_none()
+            && self.allow_history_access.is_none()
+            && self.disable_auto_review.is_none()
+            && self.allow_global_persistent_approval.is_none()
+            && self
+                .default_origin_policy
+                .as_ref()
+                .is_none_or(BrowserUseOriginPolicyToml::is_empty)
+            && self
+                .origins
+                .as_ref()
+                .is_none_or(|origins| origins.values().all(BrowserUseOriginPolicyToml::is_empty))
+    }
+}
+
+#[derive(Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+pub struct ComputerUseMacosRequirementsToml {
+    pub bundle_ids: Option<BTreeMap<String, AllowDenyRequirementToml>>,
+}
+
+#[derive(Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+pub struct ComputerUseWindowsRequirementsToml {
+    pub aumids: Option<BTreeMap<String, AllowDenyRequirementToml>>,
+    pub exes: Option<Vec<ComputerUseWindowsExeRequirementToml>>,
+}
+
+#[derive(Deserialize, Debug, Clone, PartialEq, Eq)]
+pub struct ComputerUseWindowsExeRequirementToml {
+    pub publisher_name: String,
+    pub product_name: String,
+    pub binary_name: Option<String>,
+    pub access: AllowDenyRequirementToml,
+}
+
+#[derive(Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+pub struct ComputerUseRequirementsToml {
+    pub allow_locked_computer_use: Option<bool>,
+    pub allow_persistent_approval: Option<bool>,
+    pub default_app_access: Option<AllowDenyRequirementToml>,
+    pub macos: Option<ComputerUseMacosRequirementsToml>,
+    pub windows: Option<ComputerUseWindowsRequirementsToml>,
+}
+
+impl ComputerUseRequirementsToml {
+    pub fn is_empty(&self) -> bool {
+        self.allow_locked_computer_use.is_none()
+            && self.allow_persistent_approval.is_none()
+            && self.default_app_access.is_none()
+            && self
+                .macos
+                .as_ref()
+                .is_none_or(|macos| macos.bundle_ids.as_ref().is_none_or(BTreeMap::is_empty))
+            && self.windows.as_ref().is_none_or(|windows| {
+                windows.aumids.as_ref().is_none_or(BTreeMap::is_empty)
+                    && windows.exes.as_ref().is_none_or(Vec::is_empty)
+            })
+    }
+}
+
+#[cfg(test)]
+#[path = "browser_computer_use_requirements_tests.rs"]
+mod tests;

codex-rs/config/src/browser_use_tests.rs

@@ -0,0 +1,52 @@
+use super::*;
+use crate::AllowDenyRequirementToml;
+use crate::config_toml::ConfigToml;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn browser_use_origin_policies_round_trip() {
+    let config: ConfigToml = toml::from_str(
+        r#"
+[browser_use]
+allow_history_access = true
+
+[browser_use.default_origin_policy]
+access = "deny"
+downloads = "allow"
+uploads = "deny"
+full_cdp_access = "allow"
+
+[browser_use.origins."https://example.com"]
+access = "allow"
+downloads = "deny"
+uploads = "allow"
+full_cdp_access = "deny"
+"#,
+    )
+    .expect("browser use config should deserialize");
+
+    let expected = BrowserUseConfigToml {
+        allow_history_access: Some(true),
+        default_origin_policy: Some(BrowserUseOriginPolicyConfigToml {
+            access: Some(AllowDenyRequirementToml::Deny),
+            downloads: Some(AllowDenyRequirementToml::Allow),
+            uploads: Some(AllowDenyRequirementToml::Deny),
+            full_cdp_access: Some(AllowDenyRequirementToml::Allow),
+        }),
+        origins: Some(BTreeMap::from([(
+            "https://example.com".to_string(),
+            BrowserUseOriginPolicyConfigToml {
+                access: Some(AllowDenyRequirementToml::Allow),
+                downloads: Some(AllowDenyRequirementToml::Deny),
+                uploads: Some(AllowDenyRequirementToml::Allow),
+                full_cdp_access: Some(AllowDenyRequirementToml::Deny),
+            },
+        )])),
+    };
+    assert_eq!(config.browser_use, Some(expected.clone()));
+
+    let serialized = toml::to_string(&config).expect("browser use config should serialize");
+    let reparsed: ConfigToml =
+        toml::from_str(&serialized).expect("serialized browser use config should deserialize");
+    assert_eq!(reparsed.browser_use, Some(expected));
+}

codex-rs/config/src/cloud_config_bundle_tests.rs

@@ -0,0 +1,259 @@
+use super::*;
+use crate::AbsolutePathBufGuard;
+use crate::ConfigLayerSource;
+use crate::ConfigRequirementsToml;
+use crate::FilesystemDenyReadPattern;
+use crate::SandboxModeRequirement;
+use crate::compose_requirements;
+use crate::compose_requirements_for_hostname;
+use crate::config_requirements::FilesystemRequirementsToml;
+use crate::config_requirements::PermissionsRequirementsToml;
+use crate::config_toml::ConfigToml;
+use crate::types::SandboxWorkspaceWrite;
+use codex_protocol::protocol::AskForApproval;
+use pretty_assertions::assert_eq;
+use std::sync::Arc;
+use std::sync::RwLock;
+use std::sync::atomic::AtomicUsize;
+use std::sync::atomic::Ordering;
+use tempfile::tempdir;
+
+#[tokio::test]
+async fn shared_future_runs_once() {
+    let counter = Arc::new(AtomicUsize::new(0));
+    let counter_clone = Arc::clone(&counter);
+    let loader = CloudConfigBundleLoader::new(async move {
+        counter_clone.fetch_add(1, Ordering::SeqCst);
+        Ok(Some(CloudConfigBundle::default()))
+    });
+    let cloned_loader = loader.clone();
+
+    let (first, second) = tokio::join!(loader.get(), cloned_loader.get());
+    assert_eq!(first, second);
+    assert_eq!(loader.get().await, first);
+    assert_eq!(counter.load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn getter_returns_latest_result_across_clones() {
+    let initial_error = CloudConfigBundleLoadError::new(
+        CloudConfigBundleLoadErrorCode::RequestFailed,
+        /*status_code*/ None,
+        "initial load failed",
+    );
+    let latest = Arc::new(RwLock::new(Err(initial_error.clone())));
+    let getter_latest = Arc::clone(&latest);
+    let loader = CloudConfigBundleLoader::from_getter(move || {
+        let latest = Arc::clone(&getter_latest);
+        async move { latest.read().expect("bundle state lock").clone() }
+    });
+    let cloned_loader = loader.clone();
+
+    assert_eq!(loader.get().await, Err(initial_error));
+
+    let bundle = CloudConfigBundle {
+        config_toml: CloudConfigTomlBundle {
+            enterprise_managed: vec![CloudConfigFragment {
+                id: "managed".to_string(),
+                name: "Managed".to_string(),
+                contents: "model = \"managed\"".to_string(),
+            }],
+        },
+        ..Default::default()
+    };
+    *latest.write().expect("bundle state lock") = Ok(Some(bundle.clone()));
+
+    assert_eq!(cloned_loader.get().await, Ok(Some(bundle)));
+    assert_eq!(CloudConfigBundleLoader::default().get().await, Ok(None));
+
+    *latest.write().expect("bundle state lock") = Ok(None);
+
+    assert_eq!(loader.get().await, Ok(None));
+}
+
+#[test]
+fn bundle_layers_preserve_enterprise_managed_bucket_order() {
+    let tempdir = tempdir().expect("tempdir");
+    let base_dir = AbsolutePathBuf::from_absolute_path(tempdir.path()).expect("absolute path");
+    let layers = CloudConfigBundleLayers::from_bundle(
+        CloudConfigBundle {
+            config_toml: CloudConfigTomlBundle {
+                enterprise_managed: vec![
+                    CloudConfigFragment {
+                        id: "cfg_high".to_string(),
+                        name: "High config".to_string(),
+                        contents: "model = \"high\"".to_string(),
+                    },
+                    CloudConfigFragment {
+                        id: "cfg_low".to_string(),
+                        name: "Low config".to_string(),
+                        contents: "model = \"low\"".to_string(),
+                    },
+                ],
+            },
+            requirements_toml: CloudRequirementsTomlBundle {
+                enterprise_managed: vec![
+                    CloudRequirementsFragment {
+                        id: "req_high".to_string(),
+                        name: "High requirements".to_string(),
+                        contents: "allowed_approval_policies = [\"on-request\"]".to_string(),
+                    },
+                    CloudRequirementsFragment {
+                        id: "req_low".to_string(),
+                        name: "Low requirements".to_string(),
+                        contents: "allowed_approval_policies = [\"never\"]".to_string(),
+                    },
+                ],
+            },
+        },
+        &base_dir,
+    )
+    .expect("bundle should be converted into layers");
+
+    assert_eq!(
+        layers
+            .enterprise_managed_config
+            .iter()
+            .map(|layer| layer.name.clone())
+            .collect::<Vec<_>>(),
+        vec![
+            ConfigLayerSource::EnterpriseManaged {
+                id: "cfg_low".to_string(),
+                name: "Low config".to_string(),
+            },
+            ConfigLayerSource::EnterpriseManaged {
+                id: "cfg_high".to_string(),
+                name: "High config".to_string(),
+            },
+        ]
+    );
+    assert_eq!(
+        compose_requirements(layers.enterprise_managed_requirements)
+            .expect("requirements should compose")
+            .expect("requirements should be present")
+            .into_toml(),
+        ConfigRequirementsToml {
+            allowed_approval_policies: Some(vec![AskForApproval::OnRequest]),
+            ..Default::default()
+        }
+    );
+}
+
+#[test]
+fn bundle_layers_can_strict_validate_enterprise_managed_config() {
+    let tempdir = tempdir().expect("tempdir");
+    let base_dir = AbsolutePathBuf::from_absolute_path(tempdir.path()).expect("absolute path");
+    let err = CloudConfigBundleLayers::from_bundle_strict_config(
+        CloudConfigBundle {
+            config_toml: CloudConfigTomlBundle {
+                enterprise_managed: vec![CloudConfigFragment {
+                    id: "cfg".to_string(),
+                    name: "Cloud config".to_string(),
+                    contents: "unknown_key = true".to_string(),
+                }],
+            },
+            requirements_toml: CloudRequirementsTomlBundle {
+                enterprise_managed: Vec::new(),
+            },
+        },
+        &base_dir,
+    )
+    .expect_err("strict config should reject unknown fields");
+
+    assert_eq!(
+        err,
+        CloudConfigLayerError::Invalid {
+            fragment: crate::CloudConfigFragmentSource {
+                id: "cfg".to_string(),
+                name: "Cloud config".to_string(),
+            },
+            message: "unknown configuration field `unknown_key`".to_string(),
+        }
+    );
+}
+
+#[test]
+fn bundle_layers_resolve_paths_and_requirements_for_the_execution_host() {
+    let temp_dir = tempdir().expect("temporary directories");
+    let executor_home = temp_dir.path().join("executor-home");
+    let executor_codex_home = AbsolutePathBuf::from_absolute_path(executor_home.join(".codex"))
+        .expect("absolute executor Codex home");
+    let bundle = CloudConfigBundle {
+        config_toml: CloudConfigTomlBundle {
+            enterprise_managed: vec![CloudConfigFragment {
+                id: "config".to_string(),
+                name: "Executor config".to_string(),
+                contents: r#"
+[sandbox_workspace_write]
+writable_roots = ["~/cloud-root", "./relative-root"]
+"#
+                .to_string(),
+            }],
+        },
+        requirements_toml: CloudRequirementsTomlBundle {
+            enterprise_managed: vec![CloudRequirementsFragment {
+                id: "requirements".to_string(),
+                name: "Executor requirements".to_string(),
+                contents: r#"
+[permissions.filesystem]
+deny_read = ["~/private"]
+
+[[remote_sandbox_config]]
+hostname_patterns = ["executor-*"]
+allowed_sandbox_modes = ["read-only"]
+"#
+                .to_string(),
+            }],
+        },
+    };
+
+    let (config, requirements) = AbsolutePathBufGuard::with_home_directory(&executor_home, || {
+        let layers =
+            CloudConfigBundleLayers::from_bundle_strict_config(bundle, &executor_codex_home)
+                .expect("executor bundle should convert into layers");
+        let config: ConfigToml = layers.enterprise_managed_config[0]
+            .config
+            .clone()
+            .try_into()
+            .expect("deserialize executor config");
+        let requirements = compose_requirements_for_hostname(
+            layers.enterprise_managed_requirements,
+            Some("executor-01"),
+        )
+        .expect("compose executor requirements")
+        .expect("executor requirements should be present")
+        .into_toml();
+        (config, requirements)
+    });
+
+    assert_eq!(
+        config.sandbox_workspace_write,
+        Some(SandboxWorkspaceWrite {
+            writable_roots: vec![
+                AbsolutePathBuf::from_absolute_path(executor_home.join("cloud-root"))
+                    .expect("absolute cloud root"),
+                AbsolutePathBuf::from_absolute_path(
+                    executor_codex_home.as_path().join("relative-root"),
+                )
+                .expect("absolute relative root"),
+            ],
+            ..Default::default()
+        })
+    );
+    assert_eq!(
+        requirements,
+        ConfigRequirementsToml {
+            allowed_sandbox_modes: Some(vec![SandboxModeRequirement::ReadOnly]),
+            permissions: Some(PermissionsRequirementsToml {
+                filesystem: Some(FilesystemRequirementsToml {
+                    deny_read: Some(vec![FilesystemDenyReadPattern::from(
+                        AbsolutePathBuf::from_absolute_path(executor_home.join("private"))
+                            .expect("absolute private root"),
+                    )]),
+                }),
+                ..Default::default()
+            }),
+            ..Default::default()
+        }
+    );
+}

codex-rs/config/src/cloud_config_layers.rs

@@ -0,0 +1,151 @@
+//! Conversion from cloud-delivered config TOML fragments into config stack layers.
+//!
+//! Backend fragments arrive in backend priority order. This module parses each
+//! fragment, resolves relative path fields against the cloud config base
+//! directory, and returns layers in `ConfigLayerStack` order.
+
+use crate::ConfigLayerEntry;
+use crate::ConfigLayerSource;
+use crate::TomlValue;
+use crate::config_toml::ConfigToml;
+use crate::loader::resolve_relative_paths_in_config_toml;
+use crate::strict_config::config_error_from_ignored_toml_value_fields_for_source_name;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::AbsolutePathBufGuard;
+use serde::Deserialize;
+use serde::Serialize;
+use std::fmt;
+use std::io;
+use thiserror::Error;
+
+/// Config fragment delivered by the cloud config bundle.
+///
+/// The bundle orders fragments from highest precedence to lowest precedence.
+/// This module returns config layers in stack order, so callers can append the
+/// result between system and user config without re-sorting.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct CloudConfigFragment {
+    pub id: String,
+    pub name: String,
+    pub contents: String,
+}
+
+impl CloudConfigFragment {
+    fn source_ref(&self) -> CloudConfigFragmentSource {
+        CloudConfigFragmentSource {
+            id: self.id.clone(),
+            name: self.name.clone(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CloudConfigFragmentSource {
+    pub id: String,
+    pub name: String,
+}
+
+impl fmt::Display for CloudConfigFragmentSource {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} ({})", self.name, self.id)
+    }
+}
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum CloudConfigLayerError {
+    #[error("failed to parse cloud config fragment {fragment}: {message}")]
+    Parse {
+        fragment: CloudConfigFragmentSource,
+        message: String,
+    },
+    #[error("invalid cloud config fragment {fragment}: {message}")]
+    Invalid {
+        fragment: CloudConfigFragmentSource,
+        message: String,
+    },
+}
+
+pub fn cloud_config_layers_from_fragments(
+    fragments: impl IntoIterator<Item = CloudConfigFragment>,
+    base_dir: &AbsolutePathBuf,
+) -> Result<Vec<ConfigLayerEntry>, CloudConfigLayerError> {
+    cloud_config_layers_from_fragments_impl(fragments, base_dir, /*strict_config*/ false)
+}
+
+pub(crate) fn cloud_config_layers_from_fragments_strict(
+    fragments: impl IntoIterator<Item = CloudConfigFragment>,
+    base_dir: &AbsolutePathBuf,
+) -> Result<Vec<ConfigLayerEntry>, CloudConfigLayerError> {
+    cloud_config_layers_from_fragments_impl(fragments, base_dir, /*strict_config*/ true)
+}
+
+fn cloud_config_layers_from_fragments_impl(
+    fragments: impl IntoIterator<Item = CloudConfigFragment>,
+    base_dir: &AbsolutePathBuf,
+    strict_config: bool,
+) -> Result<Vec<ConfigLayerEntry>, CloudConfigLayerError> {
+    let mut layers = Vec::new();
+    for fragment in fragments {
+        let source_ref = fragment.source_ref();
+        let raw_toml = fragment.contents;
+        let value: TomlValue =
+            toml::from_str(&raw_toml).map_err(|err| CloudConfigLayerError::Parse {
+                fragment: source_ref.clone(),
+                message: err.to_string(),
+            })?;
+        if strict_config {
+            validate_fragment_strictly(&source_ref, &raw_toml, &value, base_dir)?;
+        }
+        let resolved =
+            resolve_relative_paths_in_config_toml(value, base_dir.as_path()).map_err(|err| {
+                CloudConfigLayerError::Invalid {
+                    fragment: source_ref.clone(),
+                    message: err.to_string(),
+                }
+            })?;
+        layers.push(ConfigLayerEntry::new_with_raw_toml(
+            ConfigLayerSource::EnterpriseManaged {
+                id: fragment.id,
+                name: fragment.name,
+            },
+            resolved,
+            raw_toml,
+            base_dir.clone(),
+        ));
+    }
+
+    // Bundle fragments arrive highest-priority first, while ConfigLayerStack
+    // folds lowest-priority to highest-priority.
+    layers.reverse();
+    Ok(layers)
+}
+
+fn validate_fragment_strictly(
+    source_ref: &CloudConfigFragmentSource,
+    raw_toml: &str,
+    value: &TomlValue,
+    base_dir: &AbsolutePathBuf,
+) -> Result<(), CloudConfigLayerError> {
+    let _guard = AbsolutePathBufGuard::new(base_dir.as_path());
+    if let Some(config_error) = config_error_from_ignored_toml_value_fields_for_source_name::<
+        ConfigToml,
+    >(&source_ref.to_string(), raw_toml, value.clone())
+    {
+        return Err(CloudConfigLayerError::Invalid {
+            fragment: source_ref.clone(),
+            message: config_error.message,
+        });
+    }
+
+    Ok(())
+}
+
+impl From<CloudConfigLayerError> for io::Error {
+    fn from(error: CloudConfigLayerError) -> Self {
+        io::Error::new(io::ErrorKind::InvalidData, error)
+    }
+}
+
+#[cfg(test)]
+#[path = "cloud_config_layers_tests.rs"]
+mod tests;

codex-rs/config/src/codex_home_symlink.rs

@@ -0,0 +1,28 @@
+//! Resolves the host's symlink opt-out from its already-loaded user config.
+
+use crate::ConfigLayerSource;
+use crate::ConfigLayerStack;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+/// Returns the opted-in home without consulting project config or rereading config files.
+pub fn allowed_symlinked_codex_home(
+    config_layer_stack: &ConfigLayerStack,
+    codex_home: &AbsolutePathBuf,
+) -> Option<AbsolutePathBuf> {
+    let enabled = config_layer_stack
+        .layers_low_to_high()
+        .find(|layer| matches!(layer.name, ConfigLayerSource::User { profile: None, .. }))?
+        .config
+        .get("allow_symlinked_codex_home")?
+        .as_bool()?;
+    if !enabled {
+        return None;
+    }
+
+    // Preserve a configured alias only when lexical normalization did not change its target.
+    let alias = std::env::var_os("CODEX_HOME")
+        .filter(|path| !path.is_empty())
+        .and_then(|path| AbsolutePathBuf::from_absolute_path(path).ok())
+        .filter(|path| path.canonicalize().ok().as_ref() == Some(codex_home));
+    Some(alias.unwrap_or_else(|| codex_home.clone()))
+}

codex-rs/config/src/computer_use.rs

@@ -0,0 +1,39 @@
+use crate::AllowDenyRequirementToml;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::BTreeMap;
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ComputerUseConfigToml {
+    pub default_app_access: Option<AllowDenyRequirementToml>,
+    pub macos: Option<ComputerUseMacosConfigToml>,
+    pub windows: Option<ComputerUseWindowsConfigToml>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ComputerUseMacosConfigToml {
+    pub bundle_ids: Option<BTreeMap<String, AllowDenyRequirementToml>>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ComputerUseWindowsConfigToml {
+    pub aumids: Option<BTreeMap<String, AllowDenyRequirementToml>>,
+    pub exes: Option<Vec<ComputerUseWindowsExeConfigToml>>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ComputerUseWindowsExeConfigToml {
+    pub publisher_name: String,
+    pub product_name: String,
+    pub binary_name: Option<String>,
+    pub access: AllowDenyRequirementToml,
+}
+
+#[cfg(test)]
+#[path = "computer_use_tests.rs"]
+mod tests;

codex-rs/config/src/computer_use_tests.rs

@@ -0,0 +1,54 @@
+use super::*;
+use crate::config_toml::ConfigToml;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn computer_use_config_round_trips() {
+    let config: ConfigToml = toml::from_str(
+        r#"
+[computer_use]
+default_app_access = "deny"
+
+[computer_use.macos.bundle_ids]
+"com.apple.Safari" = "allow"
+
+[computer_use.windows.aumids]
+"Microsoft.Paint_8wekyb3d8bbwe!App" = "deny"
+
+[[computer_use.windows.exes]]
+publisher_name = "CN=Google LLC"
+product_name = "Google Chrome"
+binary_name = "chrome.exe"
+access = "allow"
+"#,
+    )
+    .expect("computer use config should deserialize");
+
+    let expected = ComputerUseConfigToml {
+        default_app_access: Some(AllowDenyRequirementToml::Deny),
+        macos: Some(ComputerUseMacosConfigToml {
+            bundle_ids: Some(BTreeMap::from([(
+                "com.apple.Safari".to_string(),
+                AllowDenyRequirementToml::Allow,
+            )])),
+        }),
+        windows: Some(ComputerUseWindowsConfigToml {
+            aumids: Some(BTreeMap::from([(
+                "Microsoft.Paint_8wekyb3d8bbwe!App".to_string(),
+                AllowDenyRequirementToml::Deny,
+            )])),
+            exes: Some(vec![ComputerUseWindowsExeConfigToml {
+                publisher_name: "CN=Google LLC".to_string(),
+                product_name: "Google Chrome".to_string(),
+                binary_name: Some("chrome.exe".to_string()),
+                access: AllowDenyRequirementToml::Allow,
+            }]),
+        }),
+    };
+    assert_eq!(config.computer_use, Some(expected.clone()));
+
+    let serialized = toml::to_string(&config).expect("computer use config should serialize");
+    let reparsed: ConfigToml =
+        toml::from_str(&serialized).expect("serialized computer use config should deserialize");
+    assert_eq!(reparsed.computer_use, Some(expected));
+}

codex-rs/config/src/config_toml.rs

@@ -0,0 +1,1073 @@
+//! Schema-heavy configuration TOML types used by Codex.
+
+use std::collections::BTreeMap;
+use std::collections::HashMap;
+use std::num::NonZeroU64;
+use std::path::Path;
+
+use crate::HooksToml;
+use crate::browser_use::BrowserUseConfigToml;
+use crate::computer_use::ComputerUseConfigToml;
+use crate::permissions_toml::PermissionsToml;
+use crate::profile_toml::ConfigProfile;
+use crate::types::AnalyticsConfigToml;
+use crate::types::ApprovalsReviewer;
+use crate::types::AppsConfigToml;
+use crate::types::AuthCredentialsStoreMode;
+use crate::types::FeedbackConfigToml;
+use crate::types::History;
+use crate::types::MarketplaceConfig;
+use crate::types::McpEnterpriseManagedAuthConfig;
+use crate::types::McpServerConfig;
+use crate::types::MemoriesToml;
+use crate::types::Notice;
+use crate::types::OAuthCredentialsStoreMode;
+use crate::types::OtelConfigToml;
+use crate::types::PluginConfig;
+use crate::types::SandboxWorkspaceWrite;
+use crate::types::ShellEnvironmentPolicyToml;
+use crate::types::SkillsConfig;
+use crate::types::ToolSuggestConfig;
+use crate::types::Tui;
+use crate::types::UriBasedFileOpener;
+use crate::types::WindowsToml;
+use codex_features::FeaturesToml;
+use codex_model_provider_info::AMAZON_BEDROCK_PROVIDER_ID;
+use codex_model_provider_info::AMAZON_BEDROCK_RUNTIME_PROVIDER_ID;
+use codex_model_provider_info::LEGACY_OLLAMA_CHAT_PROVIDER_ID;
+use codex_model_provider_info::LMSTUDIO_OSS_PROVIDER_ID;
+use codex_model_provider_info::ModelProviderInfo;
+use codex_model_provider_info::OLLAMA_CHAT_PROVIDER_REMOVED_ERROR;
+use codex_model_provider_info::OLLAMA_OSS_PROVIDER_ID;
+use codex_model_provider_info::OPENAI_PROVIDER_ID;
+use codex_protocol::config_types::AutoCompactTokenLimitScope;
+use codex_protocol::config_types::ForcedLoginMethod;
+use codex_protocol::config_types::Personality;
+use codex_protocol::config_types::ReasoningSummary;
+use codex_protocol::config_types::SandboxMode;
+use codex_protocol::config_types::TrustLevel;
+use codex_protocol::config_types::Verbosity;
+use codex_protocol::config_types::WebSearchMode;
+use codex_protocol::config_types::WebSearchToolConfig;
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::openai_models::ReasoningEffort;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_protocol::protocol::AskForApproval;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_path::normalize_for_path_comparison;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Deserializer;
+use serde::Serialize;
+use serde::de::Error as SerdeError;
+use serde_json::Value as JsonValue;
+
+const RESERVED_MODEL_PROVIDER_IDS: [&str; 5] = [
+    AMAZON_BEDROCK_PROVIDER_ID,
+    AMAZON_BEDROCK_RUNTIME_PROVIDER_ID,
+    OPENAI_PROVIDER_ID,
+    OLLAMA_OSS_PROVIDER_ID,
+    LMSTUDIO_OSS_PROVIDER_ID,
+];
+
+pub const DEFAULT_PROJECT_DOC_MAX_BYTES: usize = 32 * 1024;
+
+fn default_history() -> Option<History> {
+    Some(History::default())
+}
+
+const fn default_project_doc_max_bytes() -> Option<usize> {
+    Some(DEFAULT_PROJECT_DOC_MAX_BYTES)
+}
+
+fn default_project_doc_fallback_filenames() -> Option<Vec<String>> {
+    Some(Vec::new())
+}
+
+const fn default_hide_agent_reasoning() -> Option<bool> {
+    Some(false)
+}
+
+const fn default_true() -> bool {
+    true
+}
+
+/// Backward-compatible shape for ChatGPT workspace login restrictions in config.toml.
+#[derive(Serialize, Debug, Clone, PartialEq, JsonSchema)]
+#[serde(untagged)]
+pub enum ForcedChatgptWorkspaceIds {
+    Single(String),
+    Multiple(Vec<String>),
+}
+
+impl ForcedChatgptWorkspaceIds {
+    pub fn into_vec(self) -> Vec<String> {
+        match self {
+            Self::Single(value) => vec![value],
+            Self::Multiple(values) => values,
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for ForcedChatgptWorkspaceIds {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        #[serde(untagged)]
+        enum Repr {
+            Single(String),
+            Multiple(Vec<String>),
+        }
+
+        match Repr::deserialize(deserializer)? {
+            Repr::Single(value) if value.contains(',') => Err(D::Error::custom(
+                "forced_chatgpt_workspace_id must be a single workspace ID string or a TOML list \
+of strings; comma-separated strings are not supported. Use \
+`forced_chatgpt_workspace_id = [\"123e4567-e89b-42d3-a456-426614174000\", \
+\"123e4567-e89b-42d3-a456-426614174001\"]` instead.",
+            )),
+            Repr::Single(value) => Ok(Self::Single(value)),
+            Repr::Multiple(values) => Ok(Self::Multiple(values)),
+        }
+    }
+}
+
+/// Orchestrator-owned feature settings.
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct OrchestratorToml {
+    pub skills: Option<OrchestratorFeatureToml>,
+    pub mcp: Option<OrchestratorFeatureToml>,
+}
+
+/// Settings for a feature owned by the orchestrator.
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct OrchestratorFeatureToml {
+    pub enabled: Option<bool>,
+}
+
+/// Base config deserialized from ~/.codex/config.toml.
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ConfigToml {
+    /// Optional override of model selection.
+    pub model: Option<String>,
+    /// Review model override used by the `/review` feature.
+    pub review_model: Option<String>,
+
+    /// Provider to use from the model_providers map.
+    pub model_provider: Option<String>,
+
+    /// Size of the context window for the model, in tokens.
+    pub model_context_window: Option<i64>,
+
+    /// Token usage threshold triggering auto-compaction of conversation history.
+    pub model_auto_compact_token_limit: Option<i64>,
+
+    /// Controls whether the auto-compaction limit applies to the full context or
+    /// only to tokens after the carried prefix in the current compaction window.
+    pub model_auto_compact_token_limit_scope: Option<AutoCompactTokenLimitScope>,
+
+    /// Default approval policy for executing commands.
+    #[schemars(with = "Option<crate::schema::ConfigAskForApproval>")]
+    pub approval_policy: Option<AskForApproval>,
+
+    /// Configures who approval requests are routed to for review once they have
+    /// been escalated. This does not disable separate safety checks such as
+    /// ARC.
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
+
+    /// Optional policy instructions for the guardian auto-reviewer.
+    #[serde(default)]
+    pub auto_review: Option<AutoReviewToml>,
+
+    pub browser_use: Option<BrowserUseConfigToml>,
+
+    pub computer_use: Option<ComputerUseConfigToml>,
+
+    #[serde(default)]
+    pub shell_environment_policy: ShellEnvironmentPolicyToml,
+
+    /// Whether the model may request a login shell for shell-based tools.
+    /// Default to `true`
+    ///
+    /// If `true`, the model may request a login shell (`login = true`), and
+    /// omitting `login` defaults to using a login shell.
+    /// If `false`, the model can never use a login shell: `login = true`
+    /// requests are rejected, and omitting `login` defaults to a non-login
+    /// shell.
+    pub allow_login_shell: Option<bool>,
+
+    /// Sandbox mode to use.
+    pub sandbox_mode: Option<SandboxMode>,
+
+    /// Allow macOS sandbox writable roots at or beneath CODEX_HOME to traverse
+    /// symlinks. Read only from the host's user config at startup; defaults to false.
+    /// This grants no write access by itself, but trusts symlink targets even if
+    /// they change between commands or lie outside CODEX_HOME.
+    /// This setting has no effect on Linux or Windows.
+    pub allow_symlinked_codex_home: Option<bool>,
+
+    /// Sandbox configuration to apply if `sandbox` is `WorkspaceWrite`.
+    pub sandbox_workspace_write: Option<SandboxWorkspaceWrite>,
+
+    /// Default permissions profile to apply. Names starting with `:` refer to
+    /// built-in profiles; other names are resolved from the `[permissions]`
+    /// table.
+    pub default_permissions: Option<String>,
+
+    /// Named permissions profiles.
+    #[serde(default)]
+    pub permissions: Option<PermissionsToml>,
+
+    /// Optional external command to spawn for end-user notifications.
+    #[serde(default)]
+    pub notify: Option<Vec<String>>,
+
+    /// System instructions.
+    pub instructions: Option<String>,
+
+    /// Developer instructions inserted as a `developer` role message.
+    #[serde(default)]
+    pub developer_instructions: Option<String>,
+
+    /// Whether to inject the `<permissions instructions>` developer block.
+    pub include_permissions_instructions: Option<bool>,
+
+    /// Whether to inject the `<apps_instructions>` developer block.
+    pub include_apps_instructions: Option<bool>,
+
+    /// Whether to inject the `<collaboration_mode>` developer block.
+    pub include_collaboration_mode_instructions: Option<bool>,
+
+    /// Whether to inject the `<environment_context>` user block.
+    pub include_environment_context: Option<bool>,
+
+    /// Optional path to a file containing model instructions that will override
+    /// the built-in instructions for the selected model. Users are STRONGLY
+    /// DISCOURAGED from using this field, as deviating from the instructions
+    /// sanctioned by Codex will likely degrade model performance.
+    pub model_instructions_file: Option<AbsolutePathBuf>,
+
+    /// Compact prompt used for history compaction.
+    pub compact_prompt: Option<String>,
+
+    /// When set, restricts ChatGPT login to one or more workspace identifiers.
+    #[serde(default)]
+    pub forced_chatgpt_workspace_id: Option<ForcedChatgptWorkspaceIds>,
+
+    /// When set, restricts the login mechanism users may use.
+    #[serde(default)]
+    pub forced_login_method: Option<ForcedLoginMethod>,
+
+    /// Preferred backend for storing CLI auth credentials.
+    /// file (default): Use a file in the Codex home directory.
+    /// keyring: Use an OS-specific keyring service.
+    /// auto: Use the keyring if available, otherwise use a file.
+    #[serde(default)]
+    pub cli_auth_credentials_store: Option<AuthCredentialsStoreMode>,
+
+    /// Definition for MCP servers that Codex can reach out to for tool calls.
+    #[serde(default)]
+    // Uses the raw MCP input shape (custom deserialization) rather than `McpServerConfig`.
+    #[schemars(schema_with = "crate::schema::mcp_servers_schema")]
+    pub mcp_servers: HashMap<String, McpServerConfig>,
+
+    /// Trusted enterprise IdP shared by EMA-enabled MCP servers and plugins.
+    #[serde(default)]
+    pub mcp_enterprise_managed_auth: Option<McpEnterpriseManagedAuthConfig>,
+
+    /// Preferred backend for storing MCP OAuth credentials.
+    /// keyring: Use an OS-specific keyring service.
+    ///          https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/oauth.rs#L2
+    /// file: Use a file in the Codex home directory.
+    /// auto (default): Use the OS-specific keyring service if available, otherwise use a file.
+    #[serde(default)]
+    pub mcp_oauth_credentials_store: Option<OAuthCredentialsStoreMode>,
+
+    /// Optional fixed port for the local HTTP callback server used during MCP OAuth login.
+    /// When unset, Codex will bind to an ephemeral port chosen by the OS.
+    pub mcp_oauth_callback_port: Option<u16>,
+
+    /// Optional redirect URI to use during MCP OAuth login.
+    /// When set, this URI is used in the OAuth authorization request instead
+    /// of the local listener address. The local callback listener still binds
+    /// to 127.0.0.1 (using `mcp_oauth_callback_port` when provided).
+    pub mcp_oauth_callback_url: Option<String>,
+
+    /// Milliseconds to wait for optional MCP servers while building the initial tool catalog.
+    ///
+    /// Defaults to 1000. Set to 0 to disable the shared grace and wait for each
+    /// server's configured `startup_timeout_sec` instead.
+    pub mcp_optional_startup_grace_ms: Option<u64>,
+
+    /// User-defined provider entries that extend the built-in list. Built-in
+    /// IDs cannot be overridden.
+    #[serde(default, deserialize_with = "deserialize_model_providers")]
+    pub model_providers: HashMap<String, ModelProviderInfo>,
+
+    /// Maximum total bytes of project instruction content across all selected environments.
+    #[serde(default = "default_project_doc_max_bytes")]
+    pub project_doc_max_bytes: Option<usize>,
+
+    /// Ordered list of fallback filenames to look for when AGENTS.md is missing.
+    #[serde(default = "default_project_doc_fallback_filenames")]
+    pub project_doc_fallback_filenames: Option<Vec<String>>,
+
+    /// Token budget applied when storing tool/function outputs in the context manager.
+    pub tool_output_token_limit: Option<usize>,
+
+    /// Maximum poll window for background terminal output (`write_stdin`), in milliseconds.
+    /// Default: `300000` (5 minutes).
+    pub background_terminal_max_timeout: Option<u64>,
+
+    /// Seconds a thread must have no subscribers and no activity before app-server
+    /// unloads it. Defaults to 60; zero unloads immediately. Changes require a server restart.
+    pub thread_unload_delay_secs: Option<u64>,
+
+    /// Deprecated: ignored.
+    #[schemars(skip)]
+    pub js_repl_node_path: Option<AbsolutePathBuf>,
+
+    /// Deprecated: ignored.
+    #[schemars(skip)]
+    pub js_repl_node_module_dirs: Option<Vec<AbsolutePathBuf>>,
+
+    /// Profile to use from the `profiles` map.
+    pub profile: Option<String>,
+
+    /// Named profiles to facilitate switching between different configurations.
+    #[serde(default)]
+    pub profiles: HashMap<String, ConfigProfile>,
+
+    /// Settings that govern if and what will be written to `~/.codex/history.jsonl`.
+    #[serde(default = "default_history")]
+    pub history: Option<History>,
+
+    /// Directory where Codex stores the SQLite state DB.
+    /// Defaults to `$CODEX_SQLITE_HOME` when set. Otherwise uses `$CODEX_HOME`.
+    pub sqlite_home: Option<AbsolutePathBuf>,
+
+    /// Directory where Codex writes log files. Setting this value explicitly
+    /// also enables the TUI text log in this directory.
+    /// Defaults to `$CODEX_HOME/log`.
+    pub log_dir: Option<AbsolutePathBuf>,
+
+    /// Optional URI-based file opener. If set, citations to files in the model
+    /// output will be hyperlinked using the specified URI scheme.
+    pub file_opener: Option<UriBasedFileOpener>,
+
+    /// Collection of settings that are specific to the TUI.
+    pub tui: Option<Tui>,
+
+    /// When set to `true`, `AgentReasoning` events will be hidden from the
+    /// UI/output. Defaults to `false`.
+    #[serde(default = "default_hide_agent_reasoning")]
+    pub hide_agent_reasoning: Option<bool>,
+
+    /// When set to `true`, `AgentReasoningRawContentEvent` events will be shown in the UI/output.
+    /// Defaults to `false`.
+    pub show_raw_agent_reasoning: Option<bool>,
+
+    pub model_reasoning_effort: Option<ReasoningEffort>,
+    pub plan_mode_reasoning_effort: Option<ReasoningEffort>,
+    pub model_reasoning_summary: Option<ReasoningSummary>,
+    /// Optional verbosity control for GPT-5 models (Responses API `text.verbosity`).
+    pub model_verbosity: Option<Verbosity>,
+
+    /// Optional path to a JSON model catalog (applied on startup only).
+    /// Per-thread `config` overrides are accepted but do not reapply this (no-ops).
+    pub model_catalog_json: Option<AbsolutePathBuf>,
+
+    /// Deprecated: `friendly` and `pragmatic` no longer select a style.
+    pub personality: Option<Personality>,
+
+    /// Optional explicit service tier request id for new turns (for example
+    /// `default`, `priority`, or `flex`; legacy `fast` also works).
+    pub service_tier: Option<String>,
+
+    /// Base URL for requests to ChatGPT (as opposed to the OpenAI API).
+    pub chatgpt_base_url: Option<String>,
+
+    /// Optional product SKU forwarded on host-owned Codex Apps MCP requests.
+    pub apps_mcp_product_sku: Option<String>,
+
+    /// Bounded, product-owned metadata attached to every Responses API request.
+    pub responses_api_metadata: Option<BTreeMap<String, String>>,
+
+    /// Orchestrator-owned feature settings.
+    pub orchestrator: Option<OrchestratorToml>,
+
+    /// Base URL override for the built-in `openai` model provider.
+    pub openai_base_url: Option<String>,
+
+    /// Machine-local realtime audio device preferences used by realtime voice.
+    #[serde(default)]
+    pub audio: Option<RealtimeAudioToml>,
+
+    /// Experimental / do not use. Overrides only the realtime conversation
+    /// websocket transport base URL (the `Op::RealtimeConversation`
+    /// `/v1/realtime`
+    /// connection) without changing normal provider HTTP requests.
+    pub experimental_realtime_ws_base_url: Option<String>,
+    /// Experimental / do not use. Overrides only the WebRTC realtime call
+    /// creation base URL. This is separate from `experimental_realtime_ws_base_url`
+    /// because WebRTC call creation is HTTP, while sideband control is websocket.
+    pub experimental_realtime_webrtc_call_base_url: Option<String>,
+    /// Experimental / do not use. Selects the realtime websocket model/snapshot
+    /// used for the `Op::RealtimeConversation` connection.
+    pub experimental_realtime_ws_model: Option<String>,
+    /// Experimental / do not use. Realtime websocket session selection.
+    /// `version` controls v1/v2 and `type` controls conversational/transcription.
+    #[serde(default)]
+    pub realtime: Option<RealtimeToml>,
+    /// Experimental / do not use. Overrides only the realtime conversation
+    /// websocket transport instructions (the `Op::RealtimeConversation`
+    /// `/ws` session.update instructions) without changing normal prompts.
+    pub experimental_realtime_ws_backend_prompt: Option<String>,
+    /// Experimental / do not use. Replaces the synthesized realtime startup
+    /// context appended to websocket session instructions. An empty string
+    /// disables startup context injection entirely.
+    pub experimental_realtime_ws_startup_context: Option<String>,
+    /// Experimental / do not use. Replaces the built-in realtime start
+    /// instructions inserted into developer messages when realtime becomes
+    /// active.
+    pub experimental_realtime_start_instructions: Option<String>,
+
+    /// Removed. Former remote thread-store endpoint setting kept only so we can
+    /// fail fast instead of silently falling back to local persistence.
+    #[schemars(skip)]
+    pub experimental_thread_store_endpoint: Option<String>,
+
+    /// Experimental / do not use. Selects the thread store implementation.
+    pub experimental_thread_store: Option<ThreadStoreToml>,
+    pub projects: Option<HashMap<String, ProjectConfig>>,
+
+    /// Controls the web search tool mode: disabled, cached, indexed, or live.
+    pub web_search: Option<WebSearchMode>,
+
+    /// Nested tools section for feature toggles
+    pub tools: Option<ToolsToml>,
+
+    /// Additional discoverable tools that can be suggested for installation.
+    pub tool_suggest: Option<ToolSuggestConfig>,
+
+    /// Agent-related settings (thread limits, etc.).
+    pub agents: Option<AgentsToml>,
+
+    /// Goal-related settings.
+    pub goals: Option<GoalsToml>,
+
+    /// Memories subsystem settings.
+    pub memories: Option<MemoriesToml>,
+
+    /// User-level skill config entries keyed by SKILL.md path.
+    pub skills: Option<SkillsConfig>,
+
+    /// Lifecycle hooks configured inline in TOML plus user-level overrides.
+    pub hooks: Option<HooksToml>,
+
+    /// User-level plugin config entries keyed by plugin name.
+    #[serde(default)]
+    pub plugins: HashMap<String, PluginConfig>,
+
+    /// User-level marketplace entries keyed by marketplace name.
+    #[serde(default)]
+    pub marketplaces: HashMap<String, MarketplaceConfig>,
+
+    /// Centralized feature flags (new). Prefer this over individual toggles.
+    #[serde(default)]
+    // Injects known feature keys into the schema and forbids unknown keys.
+    #[schemars(schema_with = "crate::schema::features_schema")]
+    pub features: Option<FeaturesToml>,
+
+    /// Suppress warnings about unstable (under development) features.
+    pub suppress_unstable_features_warning: Option<bool>,
+
+    /// Compatibility-only settings retained so legacy `ghost_snapshot`
+    /// config still loads.
+    #[serde(default)]
+    pub ghost_snapshot: Option<GhostSnapshotToml>,
+
+    /// Markers used to detect the project root when searching parent
+    /// directories for `.codex` folders. Defaults to [".git"] when unset.
+    #[serde(default)]
+    pub project_root_markers: Option<Vec<String>>,
+
+    /// When `true`, checks for Codex updates on startup and surfaces update prompts.
+    /// Set to `false` only if your Codex updates are centrally managed.
+    /// Defaults to `true`.
+    pub check_for_update_on_startup: Option<bool>,
+
+    /// Legacy fallback for `tui.disable_paste_burst`. Prefer the setting under `[tui]`.
+    pub disable_paste_burst: Option<bool>,
+
+    /// When `false`, disables analytics across Codex product surfaces in this machine.
+    /// Defaults to `true`.
+    pub analytics: Option<AnalyticsConfigToml>,
+
+    /// When `false`, disables feedback collection across Codex product surfaces.
+    /// Defaults to `true`.
+    pub feedback: Option<FeedbackConfigToml>,
+
+    /// Settings for app-specific controls.
+    #[serde(default)]
+    pub apps: Option<AppsConfigToml>,
+
+    /// Opaque desktop settings stored alongside the rest of config.toml.
+    #[serde(default)]
+    pub desktop: Option<HashMap<String, JsonValue>>,
+
+    /// OTEL configuration.
+    pub otel: Option<OtelConfigToml>,
+
+    /// Windows-specific configuration.
+    #[serde(default)]
+    pub windows: Option<WindowsToml>,
+
+    /// Collection of in-product notices (different from notifications)
+    /// See [`crate::types::Notice`] for more details
+    pub notice: Option<Notice>,
+
+    pub experimental_compact_prompt_file: Option<AbsolutePathBuf>,
+    pub experimental_use_unified_exec_tool: Option<bool>,
+    /// Preferred OSS provider for local models, e.g. "lmstudio" or "ollama".
+    pub oss_provider: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ThreadStoreToml {
+    Local {},
+    #[schemars(skip)]
+    InMemory {
+        id: String,
+    },
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+pub struct AutoReviewToml {
+    /// Additional policy instructions inserted into the guardian prompt.
+    pub policy: Option<String>,
+    /// Experimental full Guardian prompt template containing the tenant policy placeholder.
+    pub experimental_policy_template: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ProjectConfig {
+    pub trust_level: Option<TrustLevel>,
+}
+
+impl ProjectConfig {
+    pub fn is_trusted(&self) -> bool {
+        matches!(self.trust_level, Some(TrustLevel::Trusted))
+    }
+
+    pub fn is_untrusted(&self) -> bool {
+        matches!(self.trust_level, Some(TrustLevel::Untrusted))
+    }
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct RealtimeAudioConfig {
+    pub microphone: Option<String>,
+    pub speaker: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, Default, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum RealtimeWsMode {
+    #[default]
+    Conversational,
+    Transcription,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, Default, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum RealtimeTransport {
+    #[default]
+    #[serde(rename = "webrtc")]
+    WebRtc,
+    Websocket,
+}
+
+pub use codex_protocol::protocol::RealtimeConversationVersion as RealtimeWsVersion;
+pub use codex_protocol::protocol::RealtimeVoice;
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct RealtimeConfig {
+    pub version: RealtimeWsVersion,
+    #[serde(rename = "type")]
+    pub session_type: RealtimeWsMode,
+    pub transport: RealtimeTransport,
+    pub voice: Option<RealtimeVoice>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct RealtimeToml {
+    pub version: Option<RealtimeWsVersion>,
+    #[serde(rename = "type")]
+    pub session_type: Option<RealtimeWsMode>,
+    pub transport: Option<RealtimeTransport>,
+    pub voice: Option<RealtimeVoice>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct RealtimeAudioToml {
+    pub microphone: Option<String>,
+    pub speaker: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ToolsToml {
+    #[serde(
+        default,
+        deserialize_with = "deserialize_optional_web_search_tool_config"
+    )]
+    pub web_search: Option<WebSearchToolConfig>,
+    pub experimental_request_user_input: Option<ExperimentalRequestUserInput>,
+    pub update_plan: Option<UpdatePlanToolConfig>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ExperimentalRequestUserInput {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct UpdatePlanToolConfig {
+    #[serde(default)]
+    pub enabled: bool,
+}
+
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum WebSearchToolConfigInput {
+    Enabled(bool),
+    Config(WebSearchToolConfig),
+}
+
+fn deserialize_optional_web_search_tool_config<'de, D>(
+    deserializer: D,
+) -> Result<Option<WebSearchToolConfig>, D::Error>
+where
+    D: Deserializer<'de>,
+{
+    let value = Option::<WebSearchToolConfigInput>::deserialize(deserializer)?;
+
+    Ok(match value {
+        None => None,
+        Some(WebSearchToolConfigInput::Enabled(enabled)) => {
+            let _ = enabled;
+            None
+        }
+        Some(WebSearchToolConfigInput::Config(config)) => Some(config),
+    })
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct GoalsToml {
+    /// Maximum token budget allowed for a goal and default budget for new goals.
+    pub max_goal_token_budget: Option<NonZeroU64>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AgentsToml {
+    /// Whether multi-agent tools are enabled. Defaults to true.
+    /// An enabled `features.multi_agent_v2` setting takes precedence.
+    pub enabled: Option<bool>,
+    /// Maximum number of spawned agent threads that can be open concurrently per session.
+    /// When unset, the selected multi-agent backend uses its default.
+    #[serde(alias = "max_threads")]
+    #[schemars(range(min = 1))]
+    pub max_concurrent_threads_per_session: Option<usize>,
+    /// Maximum nesting depth for V1 agent threads. Ignored by V2.
+    pub max_depth: Option<i32>,
+    /// Default model for spawned subagents when the spawn call does not select one.
+    pub default_subagent_model: Option<String>,
+    /// Default reasoning effort for spawned subagents when the spawn call does not select one.
+    pub default_subagent_reasoning_effort: Option<ReasoningEffort>,
+    /// Removed agent-job setting retained as a no-op for compatibility.
+    #[schemars(skip)]
+    pub job_max_runtime_seconds: Option<u64>,
+    /// Whether to record a model-visible message when an agent turn is interrupted.
+    /// Defaults to true.
+    pub interrupt_message: Option<bool>,
+
+    /// User-defined role declarations keyed by role name.
+    ///
+    /// Example:
+    /// ```toml
+    /// [agents.researcher]
+    /// description = "Research-focused role."
+    /// config_file = "./agents/researcher.toml"
+    /// nickname_candidates = ["Herodotus", "Ibn Battuta"]
+    /// ```
+    #[serde(default, flatten)]
+    pub roles: BTreeMap<String, AgentRoleToml>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AgentRoleToml {
+    /// Human-facing role documentation used in spawn tool guidance.
+    /// Required unless supplied by the referenced agent role file.
+    pub description: Option<String>,
+
+    /// Path to a role-specific config layer.
+    /// Relative paths are resolved relative to the `config.toml` that defines them.
+    pub config_file: Option<AbsolutePathBuf>,
+
+    /// Candidate nicknames for agents spawned with this role.
+    pub nickname_candidates: Option<Vec<String>>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct GhostSnapshotToml {
+    /// Legacy no-op setting retained for compatibility.
+    #[serde(alias = "ignore_untracked_files_over_bytes")]
+    pub ignore_large_untracked_files: Option<i64>,
+    /// Legacy no-op setting retained for compatibility.
+    #[serde(alias = "large_untracked_dir_warning_threshold")]
+    pub ignore_large_untracked_dirs: Option<i64>,
+    /// Legacy no-op setting retained for compatibility.
+    pub disable_warnings: Option<bool>,
+}
+
+impl ConfigToml {
+    /// Derive the effective permission profile from legacy sandbox config.
+    ///
+    /// Call this only after ruling out `default_permissions`: named
+    /// `[permissions]` profiles must be compiled through the permissions
+    /// profile pipeline, not reconstructed from `sandbox_mode`.
+    pub async fn derive_permission_profile(
+        &self,
+        sandbox_mode_override: Option<SandboxMode>,
+        windows_sandbox_level: WindowsSandboxLevel,
+        active_project: Option<&ProjectConfig>,
+        permission_profile_constraint: Option<&crate::Constrained<PermissionProfile>>,
+    ) -> PermissionProfile {
+        let configured_sandbox_mode = sandbox_mode_override.or(self.sandbox_mode);
+        let resolved_sandbox_mode = configured_sandbox_mode
+            .or_else(|| {
+                // If no sandbox_mode is set but this directory has a trust decision,
+                // default to workspace-write except on unsandboxed Windows where we
+                // default to read-only.
+                active_project
+                    .filter(|project| project.is_trusted() || project.is_untrusted())
+                    .map(|_| {
+                        if cfg!(target_os = "windows")
+                            && windows_sandbox_level == WindowsSandboxLevel::Disabled
+                        {
+                            SandboxMode::ReadOnly
+                        } else {
+                            SandboxMode::WorkspaceWrite
+                        }
+                    })
+            })
+            .unwrap_or_default();
+        let effective_sandbox_mode = if cfg!(target_os = "windows")
+            // If the experimental Windows sandbox is enabled, do not force a downgrade.
+            && windows_sandbox_level == WindowsSandboxLevel::Disabled
+            && matches!(resolved_sandbox_mode, SandboxMode::WorkspaceWrite)
+        {
+            SandboxMode::ReadOnly
+        } else {
+            resolved_sandbox_mode
+        };
+
+        let permission_profile = match effective_sandbox_mode {
+            SandboxMode::ReadOnly => PermissionProfile::read_only(),
+            SandboxMode::WorkspaceWrite => match self.sandbox_workspace_write.as_ref() {
+                Some(SandboxWorkspaceWrite {
+                    writable_roots,
+                    network_access,
+                    exclude_tmpdir_env_var,
+                    exclude_slash_tmp,
+                }) => {
+                    let network_policy = if *network_access {
+                        NetworkSandboxPolicy::Enabled
+                    } else {
+                        NetworkSandboxPolicy::Restricted
+                    };
+                    PermissionProfile::workspace_write_with(
+                        writable_roots,
+                        network_policy,
+                        *exclude_tmpdir_env_var,
+                        *exclude_slash_tmp,
+                    )
+                }
+                None => PermissionProfile::workspace_write(),
+            },
+            SandboxMode::DangerFullAccess => PermissionProfile::Disabled,
+        };
+        if configured_sandbox_mode.is_none()
+            && let Some(constraint) = permission_profile_constraint
+            && let Err(err) = constraint.can_set(&permission_profile)
+        {
+            tracing::warn!(
+                error = %err,
+                "default sandbox policy is disallowed by requirements; falling back to required default"
+            );
+            PermissionProfile::read_only()
+        } else {
+            permission_profile
+        }
+    }
+
+    /// Resolves the cwd to an existing project, or returns None if ConfigToml
+    /// does not contain a project corresponding to cwd or the resolved git repo
+    /// root for cwd.
+    pub fn get_active_project(
+        &self,
+        resolved_cwd: &Path,
+        repo_root: Option<&Path>,
+    ) -> Option<ProjectConfig> {
+        let projects = self.projects.as_ref()?;
+
+        for normalized_cwd in normalized_project_lookup_keys(resolved_cwd) {
+            if let Some(project_config) = project_config_for_lookup_key(projects, &normalized_cwd) {
+                return Some(project_config);
+            }
+        }
+
+        if let Some(repo_root) = repo_root {
+            for normalized_repo_root in normalized_project_lookup_keys(repo_root) {
+                if let Some(project_config_for_root) =
+                    project_config_for_lookup_key(projects, &normalized_repo_root)
+                {
+                    return Some(project_config_for_root);
+                }
+            }
+        }
+
+        None
+    }
+}
+
+/// Canonicalize the path and convert it to a string to be used as a key in the
+/// projects trust map. On Windows, strips UNC, when possible, to try to ensure
+/// that different paths that point to the same location have the same key.
+fn normalized_project_lookup_keys(path: &Path) -> Vec<String> {
+    let normalized_path = normalize_project_lookup_key(path.to_string_lossy().to_string());
+    let normalized_canonical_path = normalize_project_lookup_key(
+        normalize_for_path_comparison(path)
+            .unwrap_or_else(|_| path.to_path_buf())
+            .to_string_lossy()
+            .to_string(),
+    );
+    if normalized_path == normalized_canonical_path {
+        vec![normalized_canonical_path]
+    } else {
+        vec![normalized_canonical_path, normalized_path]
+    }
+}
+
+fn normalize_project_lookup_key(key: String) -> String {
+    if cfg!(windows) {
+        key.to_ascii_lowercase()
+    } else {
+        key
+    }
+}
+
+fn project_config_for_lookup_key(
+    projects: &HashMap<String, ProjectConfig>,
+    lookup_key: &str,
+) -> Option<ProjectConfig> {
+    if let Some(project_config) = projects.get(lookup_key) {
+        return Some(project_config.clone());
+    }
+
+    let mut normalized_matches: Vec<_> = projects
+        .iter()
+        .filter(|(key, _)| normalize_project_lookup_key((*key).clone()) == lookup_key)
+        .collect();
+    normalized_matches.sort_by_key(|(key, _)| *key);
+    normalized_matches
+        .first()
+        .map(|(_, project_config)| (**project_config).clone())
+}
+
+pub fn validate_reserved_model_provider_ids(
+    model_providers: &HashMap<String, ModelProviderInfo>,
+) -> Result<(), String> {
+    let mut conflicts = model_providers
+        .keys()
+        .filter(|key| {
+            !matches!(
+                key.as_str(),
+                AMAZON_BEDROCK_PROVIDER_ID | AMAZON_BEDROCK_RUNTIME_PROVIDER_ID
+            ) && RESERVED_MODEL_PROVIDER_IDS.contains(&key.as_str())
+        })
+        .map(|key| format!("`{key}`"))
+        .collect::<Vec<_>>();
+    conflicts.sort_unstable();
+    if conflicts.is_empty() {
+        Ok(())
+    } else {
+        Err(format!(
+            "model_providers contains reserved built-in provider IDs: {}. \
+Built-in providers cannot be overridden. Rename your custom provider (for example, `openai-custom`).",
+            conflicts.join(", ")
+        ))
+    }
+}
+
+pub fn validate_model_providers(
+    model_providers: &HashMap<String, ModelProviderInfo>,
+) -> Result<(), String> {
+    validate_reserved_model_provider_ids(model_providers)?;
+    for (key, provider) in model_providers {
+        if matches!(
+            key.as_str(),
+            AMAZON_BEDROCK_PROVIDER_ID | AMAZON_BEDROCK_RUNTIME_PROVIDER_ID
+        ) {
+            provider
+                .validate_bedrock_override()
+                .map_err(|message| format!("model_providers.{key} {message}"))?;
+        } else {
+            if provider.aws.is_some() {
+                return Err(format!(
+                    "model_providers.{key}: provider aws is only supported for \
+`{AMAZON_BEDROCK_PROVIDER_ID}` or `{AMAZON_BEDROCK_RUNTIME_PROVIDER_ID}`"
+                ));
+            }
+            if provider.name.trim().is_empty() {
+                return Err(format!(
+                    "model_providers.{key}: provider name must not be empty"
+                ));
+            }
+        }
+        provider
+            .validate()
+            .map_err(|message| format!("model_providers.{key}: {message}"))?;
+    }
+    Ok(())
+}
+
+fn deserialize_model_providers<'de, D>(
+    deserializer: D,
+) -> Result<HashMap<String, ModelProviderInfo>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    let model_providers = HashMap::<String, ModelProviderInfo>::deserialize(deserializer)?;
+    validate_model_providers(&model_providers).map_err(serde::de::Error::custom)?;
+    Ok(model_providers)
+}
+
+#[cfg(test)]
+#[path = "bedrock_runtime_tests.rs"]
+mod bedrock_runtime_tests;
+
+pub fn validate_oss_provider(provider: &str) -> std::io::Result<()> {
+    match provider {
+        LMSTUDIO_OSS_PROVIDER_ID | OLLAMA_OSS_PROVIDER_ID => Ok(()),
+        LEGACY_OLLAMA_CHAT_PROVIDER_ID => Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidInput,
+            OLLAMA_CHAT_PROVIDER_REMOVED_ERROR,
+        )),
+        _ => Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidInput,
+            format!(
+                "Invalid OSS provider '{provider}'. Must be one of: {LMSTUDIO_OSS_PROVIDER_ID}, {OLLAMA_OSS_PROVIDER_ID}"
+            ),
+        )),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    const WORKSPACE_ID_A: &str = "123e4567-e89b-42d3-a456-426614174000";
+    const WORKSPACE_ID_B: &str = "123e4567-e89b-42d3-a456-426614174001";
+
+    #[test]
+    fn thread_unload_delay_requires_nonnegative_seconds() {
+        for value in ["-1", "1.5", "\"60\""] {
+            let error =
+                toml::from_str::<ConfigToml>(&format!("thread_unload_delay_secs = {value}"))
+                    .expect_err("idle timeout must be a nonnegative integer");
+            assert!(error.to_string().contains("thread_unload_delay_secs"));
+        }
+    }
+
+    #[test]
+    fn forced_chatgpt_workspace_id_accepts_single_string() {
+        let config: ConfigToml = toml::from_str(&format!(
+            r#"forced_chatgpt_workspace_id = "{WORKSPACE_ID_A}""#
+        ))
+        .expect("single workspace id should deserialize");
+
+        assert_eq!(
+            config
+                .forced_chatgpt_workspace_id
+                .expect("workspace id should be set")
+                .into_vec(),
+            vec![WORKSPACE_ID_A.to_string()]
+        );
+    }
+
+    #[test]
+    fn forced_chatgpt_workspace_id_accepts_string_list() {
+        let config: ConfigToml = toml::from_str(&format!(
+            r#"forced_chatgpt_workspace_id = ["{WORKSPACE_ID_A}", "{WORKSPACE_ID_B}"]"#
+        ))
+        .expect("workspace id list should deserialize");
+
+        assert_eq!(
+            config
+                .forced_chatgpt_workspace_id
+                .expect("workspace ids should be set")
+                .into_vec(),
+            vec![WORKSPACE_ID_A.to_string(), WORKSPACE_ID_B.to_string()]
+        );
+    }
+
+    #[test]
+    fn forced_chatgpt_workspace_id_rejects_comma_separated_string() {
+        let err = toml::from_str::<ConfigToml>(&format!(
+            r#"forced_chatgpt_workspace_id = "{WORKSPACE_ID_A},{WORKSPACE_ID_B}""#
+        ))
+        .expect_err("comma-separated string should be rejected");
+
+        let message = err.to_string();
+        assert!(message.contains("TOML list of strings"));
+        assert!(message.contains("comma-separated strings are not supported"));
+    }
+
+    #[test]
+    fn amazon_bedrock_auth_command_must_not_be_empty() {
+        let err = toml::from_str::<ConfigToml>(
+            r#"
+[model_providers.amazon-bedrock.auth]
+command = "   "
+"#,
+        )
+        .expect_err("empty Amazon Bedrock auth command should be rejected");
+
+        assert!(
+            err.to_string().contains(
+                "model_providers.amazon-bedrock: provider auth.command must not be empty"
+            )
+        );
+    }
+}

codex-rs/config/src/constraint.rs

@@ -0,0 +1,344 @@
+use std::fmt;
+use std::sync::Arc;
+
+use crate::config_requirements::RequirementSource;
+use thiserror::Error;
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum ConstraintError {
+    #[error(
+        "invalid value for `{field_name}`: `{candidate}` is not in the allowed set {allowed} (set by {requirement_source})"
+    )]
+    InvalidValue {
+        field_name: &'static str,
+        candidate: String,
+        allowed: String,
+        requirement_source: RequirementSource,
+    },
+
+    #[error("To use model `{model}`, you need to use auto review.")]
+    AutoReviewRequired { model: String },
+
+    #[error("field `{field_name}` cannot be empty")]
+    EmptyField { field_name: String },
+
+    #[error("invalid rules in requirements (set by {requirement_source}): {reason}")]
+    ExecPolicyParse {
+        requirement_source: RequirementSource,
+        reason: String,
+    },
+
+    #[error(
+        "invalid requirement for MCP server `{server_name}` (set by {requirement_source}): {reason}"
+    )]
+    McpServerRequirementParse {
+        server_name: String,
+        requirement_source: RequirementSource,
+        reason: String,
+    },
+}
+
+impl ConstraintError {
+    pub fn empty_field(field_name: impl Into<String>) -> Self {
+        Self::EmptyField {
+            field_name: 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;
+/// A ConstraintNormalizer is a function which transforms a value into another of the same type.
+/// `Constrained` uses normalizers to transform values to satisfy constraints or enforce values.
+type ConstraintNormalizer<T> = dyn Fn(T) -> T + Send + Sync;
+
+#[derive(Clone)]
+pub struct Constrained<T> {
+    value: T,
+    validator: Arc<ConstraintValidator<T>>,
+    normalizer: Option<Arc<ConstraintNormalizer<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,
+            normalizer: None,
+        })
+    }
+
+    /// normalized creates a `Constrained` value with a normalizer function and a validator that allows any value.
+    pub fn normalized(
+        initial_value: T,
+        normalizer: impl Fn(T) -> T + Send + Sync + 'static,
+    ) -> ConstraintResult<Self> {
+        let validator: Arc<ConstraintValidator<T>> = Arc::new(|_| Ok(()));
+        let normalizer: Arc<ConstraintNormalizer<T>> = Arc::new(normalizer);
+        let normalized = normalizer(initial_value);
+        validator(&normalized)?;
+        Ok(Self {
+            value: normalized,
+            validator,
+            normalizer: Some(normalizer),
+        })
+    }
+
+    pub fn allow_any(initial_value: T) -> Self {
+        Self {
+            value: initial_value,
+            validator: Arc::new(|_| Ok(())),
+            normalizer: None,
+        }
+    }
+
+    pub fn allow_only(only_value: T) -> Self
+    where
+        T: Clone + fmt::Debug + PartialEq + 'static,
+    {
+        let allowed_value = only_value.clone();
+        Self {
+            value: only_value,
+            validator: Arc::new(move |candidate| {
+                if candidate == &allowed_value {
+                    Ok(())
+                } else {
+                    Err(ConstraintError::InvalidValue {
+                        field_name: "<unknown>",
+                        candidate: format!("{candidate:?}"),
+                        allowed: format!("[{allowed_value:?}]"),
+                        requirement_source: RequirementSource::Unknown,
+                    })
+                }
+            }),
+            normalizer: None,
+        }
+    }
+
+    /// 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 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)
+    }
+
+    /// Composes an additional validator onto the current constraint.
+    ///
+    /// The existing value must satisfy the combined validator before it is installed.
+    pub fn add_validator(
+        &mut self,
+        validator: impl Fn(&T) -> ConstraintResult<()> + Send + Sync + 'static,
+    ) -> ConstraintResult<()>
+    where
+        T: 'static,
+    {
+        let existing_validator = self.validator.clone();
+        let combined_validator: Arc<ConstraintValidator<T>> = Arc::new(move |candidate| {
+            existing_validator(candidate)?;
+            validator(candidate)
+        });
+
+        combined_validator(&self.value)?;
+        self.validator = combined_validator;
+        Ok(())
+    }
+
+    pub fn set(&mut self, value: T) -> ConstraintResult<()> {
+        let value = if let Some(normalizer) = &self.normalizer {
+            normalizer(value)
+        } else {
+            value
+        };
+        (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;
+
+    fn invalid_value(candidate: impl Into<String>, allowed: impl Into<String>) -> ConstraintError {
+        ConstraintError::InvalidValue {
+            field_name: "<unknown>",
+            candidate: candidate.into(),
+            allowed: allowed.into(),
+            requirement_source: RequirementSource::Unknown,
+        }
+    }
+
+    #[test]
+    fn constrained_allow_any_accepts_any_value() {
+        let mut constrained = Constrained::allow_any(/*initial_value*/ 5);
+        constrained
+            .set(/*value*/ -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_allow_only_rejects_different_values() {
+        let mut constrained = Constrained::allow_only(/*only_value*/ 5);
+        constrained
+            .set(/*value*/ 5)
+            .expect("allowed value should be accepted");
+
+        let err = constrained
+            .set(/*value*/ 6)
+            .expect_err("different value should be rejected");
+        assert_eq!(err, invalid_value("6", "[5]"));
+        assert_eq!(constrained.value(), 5);
+    }
+
+    #[test]
+    fn constrained_normalizer_applies_on_init_and_set() -> anyhow::Result<()> {
+        let mut constrained =
+            Constrained::normalized(/*initial_value*/ -1, |value| value.max(0))?;
+        assert_eq!(constrained.value(), 0);
+        constrained.set(/*value*/ -5)?;
+        assert_eq!(constrained.value(), 0);
+        constrained.set(/*value*/ 10)?;
+        assert_eq!(constrained.value(), 10);
+        Ok(())
+    }
+
+    #[test]
+    fn constrained_add_validator_composes_with_existing_validator() -> anyhow::Result<()> {
+        let mut constrained = Constrained::new(/*initial_value*/ 5, |value: &i32| {
+            if *value >= 0 {
+                Ok(())
+            } else {
+                Err(ConstraintError::empty_field("value"))
+            }
+        })?;
+        constrained.add_validator(|value| {
+            if *value <= 10 {
+                Ok(())
+            } else {
+                Err(ConstraintError::empty_field("value"))
+            }
+        })?;
+
+        assert_eq!(constrained.can_set(&7), Ok(()));
+        assert_eq!(
+            constrained.can_set(&11),
+            Err(ConstraintError::empty_field("value"))
+        );
+        assert_eq!(
+            constrained.can_set(&-1),
+            Err(ConstraintError::empty_field("value"))
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn constrained_new_rejects_invalid_initial_value() {
+        let result = Constrained::new(/*initial_value*/ 0, |value| {
+            if *value > 0 {
+                Ok(())
+            } else {
+                Err(invalid_value(value.to_string(), "positive values"))
+            }
+        });
+
+        assert_eq!(result, Err(invalid_value("0", "positive values")));
+    }
+
+    #[test]
+    fn constrained_set_rejects_invalid_value_and_leaves_previous() {
+        let mut constrained = Constrained::new(/*initial_value*/ 1, |value| {
+            if *value > 0 {
+                Ok(())
+            } else {
+                Err(invalid_value(value.to_string(), "positive values"))
+            }
+        })
+        .expect("initial value should be accepted");
+
+        let err = constrained
+            .set(/*value*/ -5)
+            .expect_err("negative values should be rejected");
+        assert_eq!(err, invalid_value("-5", "positive values"));
+        assert_eq!(constrained.value(), 1);
+    }
+
+    #[test]
+    fn constrained_can_set_allows_probe_without_setting() {
+        let constrained = Constrained::new(/*initial_value*/ 1, |value| {
+            if *value > 0 {
+                Ok(())
+            } else {
+                Err(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, invalid_value("-1", "positive values"));
+        assert_eq!(constrained.value(), 1);
+    }
+}

codex-rs/config/src/diagnostics.rs

@@ -0,0 +1,495 @@
+//! Helpers for mapping config parse/validation failures to file locations and
+//! rendering them in a user-friendly way.
+
+use crate::ConfigLayerEntry;
+use crate::ConfigLayerSource;
+use crate::ConfigLayerStack;
+use crate::format_config_layer_source;
+use codex_utils_absolute_path::AbsolutePathBufGuard;
+use serde::de::DeserializeOwned;
+use serde_path_to_error::Path as SerdePath;
+use serde_path_to_error::Segment as SerdeSegment;
+use std::fmt;
+use std::fmt::Write;
+use std::io;
+use std::path::Path;
+use std::path::PathBuf;
+use toml_edit::Document;
+use toml_edit::Item;
+use toml_edit::Table;
+use toml_edit::Value;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TextPosition {
+    pub line: usize,
+    pub column: usize,
+}
+
+/// Text range in 1-based line/column coordinates.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TextRange {
+    pub start: TextPosition,
+    pub end: TextPosition,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ConfigError {
+    pub path: PathBuf,
+    pub range: TextRange,
+    pub message: String,
+}
+
+impl ConfigError {
+    pub fn new(path: PathBuf, range: TextRange, message: impl Into<String>) -> Self {
+        Self {
+            path,
+            range,
+            message: message.into(),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct ConfigLoadError {
+    error: ConfigError,
+    source: Option<toml::de::Error>,
+}
+
+impl ConfigLoadError {
+    pub fn new(error: ConfigError, source: Option<toml::de::Error>) -> Self {
+        Self { error, source }
+    }
+
+    pub fn config_error(&self) -> &ConfigError {
+        &self.error
+    }
+}
+
+impl fmt::Display for ConfigLoadError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "{}:{}:{}: {}",
+            self.error.path.display(),
+            self.error.range.start.line,
+            self.error.range.start.column,
+            self.error.message
+        )
+    }
+}
+
+impl std::error::Error for ConfigLoadError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        self.source
+            .as_ref()
+            .map(|err| err as &dyn std::error::Error)
+    }
+}
+
+#[derive(Clone, Copy)]
+pub(crate) enum ConfigDiagnosticSource<'a> {
+    Path(&'a Path),
+    DisplayName(&'a str),
+}
+
+impl ConfigDiagnosticSource<'_> {
+    pub(crate) fn to_path_buf(self) -> PathBuf {
+        match self {
+            ConfigDiagnosticSource::Path(path) => path.to_path_buf(),
+            ConfigDiagnosticSource::DisplayName(name) => PathBuf::from(name),
+        }
+    }
+}
+
+pub fn io_error_from_config_error(
+    kind: io::ErrorKind,
+    error: ConfigError,
+    source: Option<toml::de::Error>,
+) -> io::Error {
+    io::Error::new(kind, ConfigLoadError::new(error, source))
+}
+
+pub fn config_error_from_toml(
+    path: impl AsRef<Path>,
+    contents: &str,
+    err: toml::de::Error,
+) -> ConfigError {
+    config_error_from_toml_for_source(ConfigDiagnosticSource::Path(path.as_ref()), contents, err)
+}
+
+pub(crate) fn config_error_from_toml_for_source(
+    source: ConfigDiagnosticSource<'_>,
+    contents: &str,
+    err: toml::de::Error,
+) -> ConfigError {
+    let range = err
+        .span()
+        .map(|span| text_range_from_span(contents, span))
+        .unwrap_or_else(default_range);
+    ConfigError::new(source.to_path_buf(), range, err.message())
+}
+
+pub fn config_error_from_typed_toml<T: DeserializeOwned>(
+    path: impl AsRef<Path>,
+    contents: &str,
+) -> Option<ConfigError> {
+    config_error_from_typed_toml_for_source::<T>(
+        ConfigDiagnosticSource::Path(path.as_ref()),
+        contents,
+    )
+}
+
+fn config_error_from_typed_toml_for_source<T: DeserializeOwned>(
+    source: ConfigDiagnosticSource<'_>,
+    contents: &str,
+) -> Option<ConfigError> {
+    let deserializer = match toml::de::Deserializer::parse(contents) {
+        Ok(deserializer) => deserializer,
+        Err(err) => return Some(config_error_from_toml_for_source(source, contents, err)),
+    };
+
+    let result: Result<T, _> = serde_path_to_error::deserialize(deserializer);
+    match result {
+        Ok(_) => None,
+        Err(err) => {
+            let path_hint = err.path().clone();
+            let toml_err: toml::de::Error = err.into_inner();
+            let range = span_for_config_path(contents, &path_hint)
+                .or_else(|| toml_err.span())
+                .map(|span| text_range_from_span(contents, span))
+                .unwrap_or_else(default_range);
+            Some(ConfigError::new(
+                source.to_path_buf(),
+                range,
+                toml_err.message(),
+            ))
+        }
+    }
+}
+
+pub async fn first_layer_config_error<T: DeserializeOwned>(
+    layers: &ConfigLayerStack,
+    config_toml_file: &str,
+) -> Option<ConfigError> {
+    // When the merged config fails schema validation, we surface the first concrete
+    // per-file error to point users at a specific file and range rather than an
+    // opaque merged-layer failure.
+    first_layer_config_error_for_entries::<T, _>(layers.layers_low_to_high(), config_toml_file)
+        .await
+}
+
+pub async fn first_layer_config_error_from_entries<T: DeserializeOwned>(
+    layers: &[ConfigLayerEntry],
+    config_toml_file: &str,
+) -> Option<ConfigError> {
+    first_layer_config_error_for_entries::<T, _>(layers.iter(), config_toml_file).await
+}
+
+async fn first_layer_config_error_for_entries<'a, T: DeserializeOwned, I>(
+    layers: I,
+    config_toml_file: &str,
+) -> Option<ConfigError>
+where
+    I: IntoIterator<Item = &'a ConfigLayerEntry>,
+{
+    for layer in layers {
+        if layer.is_disabled() {
+            continue;
+        }
+        if let Some(contents) = layer.raw_toml() {
+            let source_name = format_config_layer_source(&layer.name, config_toml_file);
+            let Some(base_dir) = layer.raw_toml_base_dir() else {
+                tracing::debug!(
+                    "Skipping raw TOML diagnostics for {source_name} because it has no base directory"
+                );
+                continue;
+            };
+            // Match the base directory used when the raw non-file layer was
+            // parsed into the runtime layer so diagnostics resolve relative
+            // path fields with the same semantics.
+            let _absolute_path_base = AbsolutePathBufGuard::new(base_dir.as_path());
+            if let Some(error) = config_error_from_typed_toml_for_source::<T>(
+                ConfigDiagnosticSource::DisplayName(&source_name),
+                contents,
+            ) {
+                return Some(error);
+            }
+            continue;
+        }
+
+        let Some(path) = config_path_for_layer(layer, config_toml_file) else {
+            continue;
+        };
+        let contents = match tokio::fs::read_to_string(&path).await {
+            Ok(contents) => contents,
+            Err(err) if err.kind() == io::ErrorKind::NotFound => continue,
+            Err(err) => {
+                tracing::debug!("Failed to read config file {}: {err}", path.display());
+                continue;
+            }
+        };
+
+        let Some(parent) = path.parent() else {
+            tracing::debug!("Config file {} has no parent directory", path.display());
+            continue;
+        };
+        let _guard = AbsolutePathBufGuard::new(parent);
+        if let Some(error) = config_error_from_typed_toml::<T>(&path, &contents) {
+            return Some(error);
+        }
+    }
+
+    None
+}
+
+fn config_path_for_layer(layer: &ConfigLayerEntry, config_toml_file: &str) -> Option<PathBuf> {
+    match &layer.name {
+        ConfigLayerSource::PackagedDefaults { file } => Some(file.to_path_buf()),
+        ConfigLayerSource::System { file } => Some(file.to_path_buf()),
+        ConfigLayerSource::User { file, .. } => Some(file.to_path_buf()),
+        ConfigLayerSource::Project { dot_codex_folder } => {
+            Some(dot_codex_folder.as_path().join(config_toml_file))
+        }
+        ConfigLayerSource::LegacyManagedConfigTomlFromFile { file } => Some(file.to_path_buf()),
+        ConfigLayerSource::Mdm { .. }
+        | ConfigLayerSource::EnterpriseManaged { .. }
+        | ConfigLayerSource::SessionFlags
+        | ConfigLayerSource::LegacyManagedConfigTomlFromMdm => None,
+    }
+}
+
+pub(crate) fn text_range_from_span(contents: &str, span: std::ops::Range<usize>) -> TextRange {
+    let start = position_for_offset(contents, span.start);
+    let end_index = if span.end > span.start {
+        span.end - 1
+    } else {
+        span.end
+    };
+    let end = position_for_offset(contents, end_index);
+    TextRange { start, end }
+}
+
+pub fn format_config_error(error: &ConfigError, contents: &str) -> String {
+    let mut output = String::new();
+    let start = error.range.start;
+    let _ = writeln!(
+        output,
+        "{}:{}:{}: {}",
+        error.path.display(),
+        start.line,
+        start.column,
+        error.message
+    );
+
+    let line_index = start.line.saturating_sub(1);
+    let line = match contents.lines().nth(line_index) {
+        Some(line) => line.trim_end_matches('\r'),
+        None => return output.trim_end().to_string(),
+    };
+
+    let line_number = start.line;
+    let gutter = line_number.to_string().len();
+    let _ = writeln!(output, "{:width$} |", "", width = gutter);
+    let _ = writeln!(output, "{line_number:>gutter$} | {line}");
+
+    let highlight_len = if error.range.end.line == error.range.start.line
+        && error.range.end.column >= error.range.start.column
+    {
+        error.range.end.column - error.range.start.column + 1
+    } else {
+        1
+    };
+    let spaces = " ".repeat(start.column.saturating_sub(1));
+    let carets = "^".repeat(highlight_len.max(1));
+    let _ = writeln!(output, "{:width$} | {spaces}{carets}", "", width = gutter);
+    output.trim_end().to_string()
+}
+
+pub fn format_config_error_with_source(error: &ConfigError) -> String {
+    match std::fs::read_to_string(&error.path) {
+        Ok(contents) => format_config_error(error, &contents),
+        Err(_) => format_config_error(error, ""),
+    }
+}
+
+fn position_for_offset(contents: &str, index: usize) -> TextPosition {
+    let bytes = contents.as_bytes();
+    if bytes.is_empty() {
+        return TextPosition { line: 1, column: 1 };
+    }
+
+    let safe_index = index.min(bytes.len().saturating_sub(1));
+    let column_offset = index.saturating_sub(safe_index);
+    let index = safe_index;
+
+    let line_start = bytes[..index]
+        .iter()
+        .rposition(|byte| *byte == b'\n')
+        .map(|pos| pos + 1)
+        .unwrap_or(0);
+    let line = bytes[..line_start]
+        .iter()
+        .filter(|byte| **byte == b'\n')
+        .count();
+
+    let column = std::str::from_utf8(&bytes[line_start..=index])
+        .map(|slice| slice.chars().count().saturating_sub(1))
+        .unwrap_or_else(|_| index - line_start);
+    let column = column + column_offset;
+
+    TextPosition {
+        line: line + 1,
+        column: column + 1,
+    }
+}
+
+pub(crate) fn default_range() -> TextRange {
+    let position = TextPosition { line: 1, column: 1 };
+    TextRange {
+        start: position,
+        end: position,
+    }
+}
+
+enum TomlNode<'a> {
+    Item(&'a Item),
+    Table(&'a Table),
+    Value(&'a Value),
+}
+
+fn span_for_path(contents: &str, path: &SerdePath) -> Option<std::ops::Range<usize>> {
+    let doc = contents.parse::<Document<String>>().ok()?;
+    let node = node_for_path(doc.as_item(), path)?;
+    match node {
+        TomlNode::Item(item) => item.span(),
+        TomlNode::Table(table) => table.span(),
+        TomlNode::Value(value) => value.span(),
+    }
+}
+
+pub(crate) fn span_for_config_path(
+    contents: &str,
+    path: &SerdePath,
+) -> Option<std::ops::Range<usize>> {
+    if is_features_table_path(path)
+        && let Some(span) = span_for_features_value(contents)
+    {
+        return Some(span);
+    }
+    span_for_path(contents, path)
+}
+
+pub(crate) fn span_for_toml_key_path(
+    contents: &str,
+    path: &[String],
+) -> Option<std::ops::Range<usize>> {
+    let doc = contents.parse::<Document<String>>().ok()?;
+    let mut node = TomlNode::Item(doc.as_item());
+    for (index, segment) in path.iter().enumerate() {
+        if index + 1 == path.len() {
+            let key_span = match &node {
+                TomlNode::Item(item) => item
+                    .as_table_like()
+                    .and_then(|table| table.get_key_value(segment))
+                    .and_then(|(key, _)| key.span()),
+                TomlNode::Table(table) => {
+                    table.get_key_value(segment).and_then(|(key, _)| key.span())
+                }
+                TomlNode::Value(Value::InlineTable(table)) => {
+                    table.get_key_value(segment).and_then(|(key, _)| key.span())
+                }
+                _ => None,
+            };
+            if key_span.is_some() {
+                return key_span;
+            }
+        }
+
+        if let Some(next) = map_child(&node, segment) {
+            node = next;
+            continue;
+        }
+
+        let index = segment.parse::<usize>().ok()?;
+        node = seq_child(&node, index)?;
+    }
+
+    match node {
+        TomlNode::Item(item) => item.span(),
+        TomlNode::Table(table) => table.span(),
+        TomlNode::Value(value) => value.span(),
+    }
+}
+
+fn is_features_table_path(path: &SerdePath) -> bool {
+    let mut segments = path.iter();
+    matches!(segments.next(), Some(SerdeSegment::Map { key }) if key == "features")
+        && segments.next().is_none()
+}
+
+fn span_for_features_value(contents: &str) -> Option<std::ops::Range<usize>> {
+    let doc = contents.parse::<Document<String>>().ok()?;
+    let root = doc.as_item().as_table_like()?;
+    let features_item = root.get("features")?;
+    let features_table = features_item.as_table_like()?;
+    for (_, item) in features_table.iter() {
+        match item {
+            Item::Value(Value::Boolean(_)) => continue,
+            Item::Value(value) => return value.span(),
+            Item::Table(table) => return table.span(),
+            Item::ArrayOfTables(array) => return array.span(),
+            Item::None => continue,
+        }
+    }
+    None
+}
+
+fn node_for_path<'a>(item: &'a Item, path: &SerdePath) -> Option<TomlNode<'a>> {
+    let segments: Vec<_> = path.iter().cloned().collect();
+    let mut node = TomlNode::Item(item);
+    let mut index = 0;
+    while index < segments.len() {
+        match &segments[index] {
+            SerdeSegment::Map { key } | SerdeSegment::Enum { variant: key } => {
+                if let Some(next) = map_child(&node, key) {
+                    node = next;
+                    index += 1;
+                    continue;
+                }
+
+                if index + 1 < segments.len() {
+                    index += 1;
+                    continue;
+                }
+                return None;
+            }
+            SerdeSegment::Seq { index: seq_index } => {
+                node = seq_child(&node, *seq_index)?;
+                index += 1;
+            }
+            SerdeSegment::Unknown => return None,
+        }
+    }
+    Some(node)
+}
+
+fn map_child<'a>(node: &TomlNode<'a>, key: &str) -> Option<TomlNode<'a>> {
+    match node {
+        TomlNode::Item(item) => {
+            let table = item.as_table_like()?;
+            table.get(key).map(TomlNode::Item)
+        }
+        TomlNode::Table(table) => table.get(key).map(TomlNode::Item),
+        TomlNode::Value(Value::InlineTable(table)) => table.get(key).map(TomlNode::Value),
+        _ => None,
+    }
+}
+
+fn seq_child<'a>(node: &TomlNode<'a>, index: usize) -> Option<TomlNode<'a>> {
+    match node {
+        TomlNode::Item(Item::Value(Value::Array(array))) => array.get(index).map(TomlNode::Value),
+        TomlNode::Item(Item::ArrayOfTables(array)) => array.get(index).map(TomlNode::Table),
+        TomlNode::Value(Value::Array(array)) => array.get(index).map(TomlNode::Value),
+        _ => None,
+    }
+}

codex-rs/config/src/filesystem_constraints.rs

@@ -0,0 +1,62 @@
+//! Convert resolved filesystem denials into portable policy entries.
+
+use crate::FilesystemConstraints;
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_utils_path_uri::LegacyAppPathString;
+use codex_utils_path_uri::LegacyAppPathStringError;
+use codex_utils_path_uri::PathConvention;
+use codex_utils_path_uri::PathUri;
+use std::io;
+
+impl FilesystemConstraints {
+    /// Adds denials without changing existing entries or other policy settings.
+    /// `convention` must match the executor facts used to resolve these requirements.
+    /// Literal paths become URIs; glob spellings and entry order are preserved.
+    /// Invalid denials return an error before the policy is changed.
+    pub fn apply_to_policy(
+        &self,
+        policy: &mut FileSystemSandboxPolicy,
+        convention: PathConvention,
+    ) -> io::Result<()> {
+        let entries = self
+            .deny_read
+            .iter()
+            .map(|deny_read| {
+                PathUri::validate_config_path_text(deny_read.as_str(), convention)?;
+                let path = if deny_read.contains_glob() {
+                    FileSystemPath::GlobPattern {
+                        pattern: deny_read.as_str().to_string(),
+                    }
+                } else {
+                    let mut path = LegacyAppPathString::from_string(deny_read.as_str())
+                        .to_path_uri(convention)?;
+                    path.validate_config_path(convention)?;
+                    // Match Core's existing URI spelling for UNC share roots.
+                    if path.to_url().host_str().is_some() {
+                        path = path.join(".")?;
+                    }
+                    path.into()
+                };
+                Ok(FileSystemSandboxEntry::new(
+                    path,
+                    FileSystemAccessMode::Deny,
+                ))
+            })
+            .collect::<Result<Vec<_>, LegacyAppPathStringError>>()
+            .map_err(|error| {
+                io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("invalid permissions.filesystem.deny_read path: {error}"),
+                )
+            })?;
+        for entry in entries {
+            if !policy.entries.contains(&entry) {
+                policy.entries.push(entry);
+            }
+        }
+        Ok(())
+    }
+}

codex-rs/config/src/fingerprint.rs

@@ -0,0 +1,84 @@
+use crate::ConfigLayerMetadata;
+use crate::merge::is_structured_feature_path;
+use serde_json::Value as JsonValue;
+use sha2::Digest;
+use sha2::Sha256;
+use std::collections::HashMap;
+use toml::Value as TomlValue;
+
+pub(super) fn record_origins(
+    value: &TomlValue,
+    meta: &ConfigLayerMetadata,
+    path: &mut Vec<String>,
+    origins: &mut HashMap<String, ConfigLayerMetadata>,
+    include: &impl Fn(&[String]) -> bool,
+) {
+    match value {
+        TomlValue::Table(table) => {
+            for (key, val) in table {
+                path.push(key.clone());
+                record_origins(val, meta, path, origins, include);
+                path.pop();
+            }
+        }
+        TomlValue::Array(items) => {
+            for (idx, item) in (0_i32..).zip(items.iter()) {
+                path.push(idx.to_string());
+                record_origins(item, meta, path, origins, include);
+                path.pop();
+            }
+        }
+        _ => {
+            if !path.is_empty() {
+                if !include(path) {
+                    return;
+                }
+                if matches!(value, TomlValue::Boolean(_)) && is_structured_feature_path(path) {
+                    if path
+                        .last()
+                        .is_some_and(|feature| feature == "network_proxy")
+                    {
+                        origins.insert(path.join("."), meta.clone());
+                    }
+                    path.push("enabled".to_string());
+                    origins.insert(path.join("."), meta.clone());
+                    path.pop();
+                    return;
+                }
+                origins.insert(path.join("."), meta.clone());
+            }
+        }
+    }
+}
+
+pub fn version_for_toml(value: &TomlValue) -> String {
+    let json = serde_json::to_value(value).unwrap_or(JsonValue::Null);
+    let canonical = canonical_json(&json);
+    let serialized = serde_json::to_vec(&canonical).unwrap_or_default();
+    let mut hasher = Sha256::new();
+    hasher.update(serialized);
+    let hash = hasher.finalize();
+    let hex = hash
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect::<String>();
+    format!("sha256:{hex}")
+}
+
+fn canonical_json(value: &JsonValue) -> JsonValue {
+    match value {
+        JsonValue::Object(map) => {
+            let mut sorted = serde_json::Map::new();
+            let mut keys = map.keys().cloned().collect::<Vec<_>>();
+            keys.sort();
+            for key in keys {
+                if let Some(val) = map.get(&key) {
+                    sorted.insert(key, canonical_json(val));
+                }
+            }
+            JsonValue::Object(sorted)
+        }
+        JsonValue::Array(items) => JsonValue::Array(items.iter().map(canonical_json).collect()),
+        other => other.clone(),
+    }
+}

codex-rs/config/src/hook_config.rs

@@ -0,0 +1,256 @@
+use std::collections::BTreeMap;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_protocol::protocol::HookEventName;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct HooksFile {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub hooks: HookEventsToml,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+pub struct HooksToml {
+    #[serde(flatten)]
+    pub events: HookEventsToml,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub state: BTreeMap<String, HookStateToml>,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+pub struct HookStateToml {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enabled: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub trusted_hash: Option<String>,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+pub struct HookEventsToml {
+    #[serde(rename = "PreToolUse", default)]
+    pub pre_tool_use: Vec<MatcherGroup>,
+    #[serde(rename = "PermissionRequest", default)]
+    pub permission_request: Vec<MatcherGroup>,
+    #[serde(rename = "PostToolUse", default)]
+    pub post_tool_use: Vec<MatcherGroup>,
+    #[serde(rename = "PreCompact", default)]
+    pub pre_compact: Vec<MatcherGroup>,
+    #[serde(rename = "PostCompact", default)]
+    pub post_compact: Vec<MatcherGroup>,
+    #[serde(rename = "SessionStart", default)]
+    pub session_start: Vec<MatcherGroup>,
+    #[serde(rename = "SessionEnd", default)]
+    pub session_end: Vec<MatcherGroup>,
+    #[serde(rename = "UserPromptSubmit", default)]
+    pub user_prompt_submit: Vec<MatcherGroup>,
+    #[serde(rename = "SubagentStart", default)]
+    pub subagent_start: Vec<MatcherGroup>,
+    #[serde(rename = "SubagentStop", default)]
+    pub subagent_stop: Vec<MatcherGroup>,
+    #[serde(rename = "Stop", default)]
+    pub stop: Vec<MatcherGroup>,
+    #[serde(rename = "Interrupt", default)]
+    pub interrupt: Vec<MatcherGroup>,
+}
+
+impl HookEventsToml {
+    pub fn is_empty(&self) -> bool {
+        let Self {
+            pre_tool_use,
+            permission_request,
+            post_tool_use,
+            pre_compact,
+            post_compact,
+            session_start,
+            session_end,
+            user_prompt_submit,
+            subagent_start,
+            subagent_stop,
+            stop,
+            interrupt,
+        } = self;
+        pre_tool_use.is_empty()
+            && permission_request.is_empty()
+            && post_tool_use.is_empty()
+            && pre_compact.is_empty()
+            && post_compact.is_empty()
+            && session_start.is_empty()
+            && session_end.is_empty()
+            && user_prompt_submit.is_empty()
+            && subagent_start.is_empty()
+            && subagent_stop.is_empty()
+            && stop.is_empty()
+            && interrupt.is_empty()
+    }
+
+    pub fn handler_count(&self) -> usize {
+        let Self {
+            pre_tool_use,
+            permission_request,
+            post_tool_use,
+            pre_compact,
+            post_compact,
+            session_start,
+            session_end,
+            user_prompt_submit,
+            subagent_start,
+            subagent_stop,
+            stop,
+            interrupt,
+        } = self;
+        [
+            pre_tool_use,
+            permission_request,
+            post_tool_use,
+            pre_compact,
+            post_compact,
+            session_start,
+            session_end,
+            user_prompt_submit,
+            subagent_start,
+            subagent_stop,
+            stop,
+            interrupt,
+        ]
+        .into_iter()
+        .flatten()
+        .map(|group| group.hooks.len())
+        .sum()
+    }
+
+    pub fn into_matcher_groups(mut self) -> [(HookEventName, Vec<MatcherGroup>); 12] {
+        self.matcher_groups_mut()
+            .map(|(event, groups)| (event, std::mem::take(groups)))
+    }
+
+    pub fn matcher_groups_mut(&mut self) -> [(HookEventName, &mut Vec<MatcherGroup>); 12] {
+        use HookEventName as Event;
+
+        [
+            (Event::PreToolUse, &mut self.pre_tool_use),
+            (Event::PermissionRequest, &mut self.permission_request),
+            (Event::PostToolUse, &mut self.post_tool_use),
+            (Event::PreCompact, &mut self.pre_compact),
+            (Event::PostCompact, &mut self.post_compact),
+            (Event::SessionStart, &mut self.session_start),
+            (Event::SessionEnd, &mut self.session_end),
+            (Event::UserPromptSubmit, &mut self.user_prompt_submit),
+            (Event::SubagentStart, &mut self.subagent_start),
+            (Event::SubagentStop, &mut self.subagent_stop),
+            (Event::Stop, &mut self.stop),
+            (Event::Interrupt, &mut self.interrupt),
+        ]
+    }
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+pub struct MatcherGroup {
+    #[serde(default)]
+    pub matcher: Option<String>,
+    #[serde(default)]
+    pub hooks: Vec<HookHandlerConfig>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(tag = "type")]
+pub enum HookHandlerConfig {
+    #[serde(rename = "command")]
+    Command {
+        command: String,
+        #[serde(default, rename = "commandWindows", alias = "command_windows")]
+        command_windows: Option<String>,
+        #[serde(default, rename = "timeout")]
+        timeout_sec: Option<u64>,
+        #[serde(default)]
+        r#async: bool,
+        #[serde(default, rename = "statusMessage")]
+        status_message: Option<String>,
+        /// Approximate token threshold for spilling this hook's `additionalContext` to disk.
+        /// Unset uses 2,500 tokens; `0` disables spilling for this hook. The threshold is
+        /// evaluated against the original context; a spilled preview also includes recovery
+        /// metadata.
+        #[serde(
+            default,
+            rename = "additionalContextLimit",
+            skip_serializing_if = "Option::is_none"
+        )]
+        additional_context_limit: Option<usize>,
+    },
+    #[serde(rename = "mcp_tool")]
+    McpTool {
+        server: String,
+        tool: String,
+        #[serde(default, deserialize_with = "deserialize_mcp_tool_input")]
+        input: serde_json::Map<String, serde_json::Value>,
+        #[serde(default, rename = "timeout")]
+        timeout_sec: Option<u64>,
+        #[serde(default, rename = "statusMessage")]
+        status_message: Option<String>,
+    },
+    #[serde(rename = "prompt")]
+    Prompt {},
+    #[serde(rename = "agent")]
+    Agent {},
+}
+
+// Reject values such as null that cannot be represented in TOML for trust hashing.
+fn deserialize_mcp_tool_input<'de, D>(
+    deserializer: D,
+) -> Result<serde_json::Map<String, serde_json::Value>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    let input = serde_json::Map::deserialize(deserializer)?;
+    toml::Value::try_from(&input).map_err(|error| {
+        serde::de::Error::custom(format!(
+            "MCP hook input must be representable as TOML: {error}"
+        ))
+    })?;
+    Ok(input)
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ManagedHooksRequirementsToml {
+    pub managed_dir: Option<PathBuf>,
+    pub windows_managed_dir: Option<PathBuf>,
+    #[serde(flatten)]
+    pub hooks: HookEventsToml,
+}
+
+impl ManagedHooksRequirementsToml {
+    pub fn is_empty(&self) -> bool {
+        let Self {
+            managed_dir,
+            windows_managed_dir,
+            hooks,
+        } = self;
+        managed_dir.is_none() && windows_managed_dir.is_none() && hooks.is_empty()
+    }
+
+    pub fn handler_count(&self) -> usize {
+        self.hooks.handler_count()
+    }
+
+    pub fn managed_dir_for_current_platform(&self) -> Option<&Path> {
+        #[cfg(windows)]
+        {
+            self.windows_managed_dir.as_deref()
+        }
+
+        #[cfg(not(windows))]
+        {
+            self.managed_dir.as_deref()
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "hooks_tests.rs"]
+mod tests;

codex-rs/config/src/in_app_browser_requirements.rs

@@ -0,0 +1,14 @@
+use serde::Deserialize;
+
+/// Managed requirements for the interactive in-app browser, not agent Browser Use.
+#[derive(Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+pub struct InAppBrowserRequirementsToml {
+    /// Whether external browser settings may be imported. Only `Some(false)`
+    /// denies import; omission is effectively `true`. Keep omission unset while
+    /// composing managed layers so it cannot replace an explicit requirement.
+    pub allow_external_browser_settings_import: Option<bool>,
+}
+
+#[cfg(test)]
+#[path = "in_app_browser_requirements_tests.rs"]
+mod tests;

codex-rs/config/src/key_aliases.rs

@@ -0,0 +1,59 @@
+use toml::Value as TomlValue;
+use toml::map::Map as TomlMap;
+
+#[derive(Debug, Clone, Copy)]
+struct ConfigKeyAlias {
+    table_path: &'static [&'static str],
+    legacy_key: &'static str,
+    canonical_key: &'static str,
+}
+
+const CONFIG_KEY_ALIASES: &[ConfigKeyAlias] = &[
+    ConfigKeyAlias {
+        table_path: &["memories"],
+        legacy_key: "no_memories_if_mcp_or_web_search",
+        canonical_key: "disable_on_external_context",
+    },
+    ConfigKeyAlias {
+        table_path: &["agents"],
+        legacy_key: "max_threads",
+        canonical_key: "max_concurrent_threads_per_session",
+    },
+];
+
+pub(crate) fn normalize_key_aliases(path: &[String], table: &mut TomlMap<String, TomlValue>) {
+    for alias in CONFIG_KEY_ALIASES {
+        if path
+            .iter()
+            .map(String::as_str)
+            .eq(alias.table_path.iter().copied())
+            && let Some(value) = table.remove(alias.legacy_key)
+        {
+            table
+                .entry(alias.canonical_key.to_string())
+                .or_insert(value);
+        }
+    }
+}
+
+pub(crate) fn normalized_with_key_aliases(value: &TomlValue, path: &[String]) -> TomlValue {
+    match value {
+        TomlValue::Table(table) => {
+            let mut normalized = TomlMap::new();
+            for (key, child) in table {
+                let mut child_path = path.to_vec();
+                child_path.push(key.clone());
+                normalized.insert(key.clone(), normalized_with_key_aliases(child, &child_path));
+            }
+            normalize_key_aliases(path, &mut normalized);
+            TomlValue::Table(normalized)
+        }
+        TomlValue::Array(items) => TomlValue::Array(
+            items
+                .iter()
+                .map(|item| normalized_with_key_aliases(item, path))
+                .collect(),
+        ),
+        _ => value.clone(),
+    }
+}

codex-rs/config/src/lib.rs

@@ -0,0 +1,218 @@
+mod application_requirements;
+mod auth_policy;
+mod browser_computer_use_requirements;
+mod browser_use;
+mod cloud_config_bundle;
+mod cloud_config_layers;
+#[cfg(target_os = "macos")]
+mod codex_home_symlink;
+mod computer_use;
+mod config_layer_source;
+mod config_requirements;
+pub mod config_toml;
+mod constraint;
+mod diagnostics;
+mod filesystem_constraints;
+mod fingerprint;
+mod hook_config;
+mod host_name;
+mod in_app_browser_requirements;
+mod key_aliases;
+pub mod loader;
+mod marketplace_edit;
+mod mcp_edit;
+mod mcp_ema;
+mod mcp_requirements;
+mod mcp_types;
+mod merge;
+mod model_provider_requirements;
+mod overrides;
+mod path_context;
+pub mod permissions_toml;
+mod plugin_edit;
+pub mod profile_toml;
+mod project_root_markers;
+mod requirements_exec_policy;
+mod requirements_layers;
+pub mod schema;
+mod shell_environment_policy;
+mod skills_config;
+mod state;
+mod strict_config;
+pub mod test_support;
+mod thread_config;
+mod tui_keymap;
+pub mod types;
+
+pub const CONFIG_TOML_FILE: &str = "config.toml";
+
+pub use application_requirements::ApplicationNetworkRequirementsToml;
+pub use application_requirements::ApplicationRequirementsToml;
+pub use auth_policy::ManagedAuthPolicy;
+pub use browser_computer_use_requirements::AllowDenyRequirementToml;
+pub use browser_computer_use_requirements::BrowserUseAccessApprovalLifetimeToml;
+pub use browser_computer_use_requirements::BrowserUseOriginPolicyToml;
+pub use browser_computer_use_requirements::BrowserUseRequirementsToml;
+pub use browser_computer_use_requirements::ComputerUseMacosRequirementsToml;
+pub use browser_computer_use_requirements::ComputerUseRequirementsToml;
+pub use browser_computer_use_requirements::ComputerUseWindowsExeRequirementToml;
+pub use browser_computer_use_requirements::ComputerUseWindowsRequirementsToml;
+pub use browser_use::BrowserUseConfigToml;
+pub use browser_use::BrowserUseOriginPolicyConfigToml;
+pub use cloud_config_bundle::CloudConfigBundle;
+pub use cloud_config_bundle::CloudConfigBundleLayers;
+pub use cloud_config_bundle::CloudConfigBundleLoadError;
+pub use cloud_config_bundle::CloudConfigBundleLoadErrorCode;
+pub use cloud_config_bundle::CloudConfigBundleLoader;
+pub use cloud_config_bundle::CloudConfigTomlBundle;
+pub use cloud_config_bundle::CloudRequirementsFragment;
+pub use cloud_config_bundle::CloudRequirementsTomlBundle;
+pub use cloud_config_layers::CloudConfigFragment;
+pub use cloud_config_layers::CloudConfigFragmentSource;
+pub use cloud_config_layers::CloudConfigLayerError;
+pub use cloud_config_layers::cloud_config_layers_from_fragments;
+pub use codex_execpolicy::RequirementsExecPolicy;
+#[cfg(target_os = "macos")]
+pub use codex_home_symlink::allowed_symlinked_codex_home;
+pub use codex_protocol::config_types::ProfileV2Name;
+pub use codex_protocol::config_types::ProfileV2NameParseError;
+pub use codex_protocol::config_types::ToolExposureSurface;
+pub use codex_protocol::mcp_policy::McpServerCommandMatcher;
+pub use codex_protocol::mcp_policy::McpServerIdentity;
+pub use codex_protocol::mcp_policy::McpServerRequirement;
+pub use codex_protocol::mcp_policy::McpServerValueMatcher;
+pub use codex_protocol::mcp_policy::PluginMcpRequirements as PluginRequirementsToml;
+pub use codex_utils_absolute_path::AbsolutePathBuf;
+pub use codex_utils_absolute_path::AbsolutePathBufGuard;
+pub use computer_use::ComputerUseConfigToml;
+pub use computer_use::ComputerUseMacosConfigToml;
+pub use computer_use::ComputerUseWindowsConfigToml;
+pub use computer_use::ComputerUseWindowsExeConfigToml;
+pub use config_layer_source::ConfigLayer;
+pub use config_layer_source::ConfigLayerMetadata;
+pub use config_layer_source::ConfigLayerSource;
+pub use config_layer_source::format_config_layer_source;
+pub use config_requirements::AppRequirementToml;
+pub use config_requirements::AppToolRequirementToml;
+pub use config_requirements::AppToolResultSourceFormat;
+pub use config_requirements::AppToolResultSourceRequirementToml;
+pub use config_requirements::AppToolsRequirementsToml;
+pub use config_requirements::AppsRequirementsToml;
+pub use config_requirements::AutoReviewRequirementsToml;
+pub use config_requirements::ConfigRequirements;
+pub use config_requirements::ConfigRequirementsToml;
+pub use config_requirements::ConfigRequirementsWithSources;
+pub use config_requirements::ConstrainedWithSource;
+pub use config_requirements::FeatureRequirementsToml;
+pub use config_requirements::FilesystemConstraints;
+pub use config_requirements::FilesystemDenyReadPattern;
+pub use config_requirements::MarketplaceAllowedSourceKind;
+pub use config_requirements::MarketplaceAllowedSourceToml;
+pub use config_requirements::MarketplaceRequirementsToml;
+pub use config_requirements::ModelsRequirementsToml;
+pub use config_requirements::NetworkConstraints;
+pub use config_requirements::NetworkDomainPermissionToml;
+pub use config_requirements::NetworkDomainPermissionsToml;
+pub use config_requirements::NetworkHeaderInjectionToml;
+pub use config_requirements::NetworkRequirementsToml;
+pub use config_requirements::NetworkUnixSocketPermissionToml;
+pub use config_requirements::NetworkUnixSocketPermissionsToml;
+pub use config_requirements::NewThreadModelDefaultsToml;
+pub use config_requirements::RemoteSandboxConfigToml;
+pub use config_requirements::RequirementSource;
+pub use config_requirements::ResidencyRequirement;
+pub use config_requirements::SandboxModeRequirement;
+pub use config_requirements::Sourced;
+pub use config_requirements::WebSearchModeRequirement;
+pub use config_requirements::WindowsRequirementsToml;
+pub use config_requirements::sandbox_mode_requirement_for_permission_profile;
+pub use constraint::Constrained;
+pub use constraint::ConstraintError;
+pub use constraint::ConstraintResult;
+pub use diagnostics::ConfigError;
+pub use diagnostics::ConfigLoadError;
+pub use diagnostics::TextPosition;
+pub use diagnostics::TextRange;
+pub use diagnostics::config_error_from_toml;
+pub use diagnostics::config_error_from_typed_toml;
+pub use diagnostics::first_layer_config_error;
+pub use diagnostics::first_layer_config_error_from_entries;
+pub use diagnostics::format_config_error;
+pub use diagnostics::format_config_error_with_source;
+pub use diagnostics::io_error_from_config_error;
+pub use fingerprint::version_for_toml;
+pub use hook_config::HookEventsToml;
+pub use hook_config::HookHandlerConfig;
+pub use hook_config::HookStateToml;
+pub use hook_config::HooksFile;
+pub use hook_config::HooksToml;
+pub use hook_config::ManagedHooksRequirementsToml;
+pub use hook_config::MatcherGroup;
+pub use host_name::host_name;
+pub use host_name::os_host_name;
+pub use in_app_browser_requirements::InAppBrowserRequirementsToml;
+pub use marketplace_edit::MarketplaceConfigUpdate;
+pub use marketplace_edit::RemoveMarketplaceConfigOutcome;
+pub use marketplace_edit::record_user_marketplace;
+pub use marketplace_edit::remove_user_marketplace;
+pub use marketplace_edit::remove_user_marketplace_config;
+pub use mcp_edit::load_global_mcp_servers;
+pub use mcp_ema::McpEmaRegistration;
+pub use mcp_ema::McpEnterpriseManagedAuthConfig;
+pub use mcp_ema::McpServerIdpOAuthConfig;
+pub use mcp_types::AppToolApproval;
+pub use mcp_types::DEFAULT_MCP_SERVER_ENVIRONMENT_ID;
+pub use mcp_types::McpServerAuth;
+pub use mcp_types::McpServerConfig;
+pub use mcp_types::McpServerDisabledReason;
+pub use mcp_types::McpServerEnvVar;
+pub use mcp_types::McpServerOAuthConfig;
+pub use mcp_types::McpServerToolConfig;
+pub use mcp_types::McpServerTransportConfig;
+pub use mcp_types::RawMcpServerConfig;
+pub use merge::ShellEnvironmentPolicyFilterRepresentation;
+pub use merge::is_structured_feature_path;
+pub use merge::merge_toml_values;
+pub use merge::shell_environment_filter_entry;
+pub use overrides::build_cli_overrides_layer;
+pub use path_context::ConfigPathContext;
+pub use plugin_edit::PluginConfigEdit;
+pub use plugin_edit::apply_user_plugin_config_edits;
+pub use plugin_edit::clear_user_plugin;
+pub use plugin_edit::set_user_plugin_enabled;
+pub use project_root_markers::default_project_root_markers;
+pub use project_root_markers::project_root_markers_from_config;
+pub use requirements_exec_policy::RequirementsExecPolicyDecisionToml;
+pub use requirements_exec_policy::RequirementsExecPolicyParseError;
+pub use requirements_exec_policy::RequirementsExecPolicyPatternTokenToml;
+pub use requirements_exec_policy::RequirementsExecPolicyPrefixRuleToml;
+pub use requirements_exec_policy::RequirementsExecPolicyToml;
+pub use requirements_layers::RequirementsLayerEntry;
+pub use requirements_layers::compose_requirements;
+pub use requirements_layers::compose_requirements_for_hostname;
+pub use shell_environment_policy::validate_shell_environment_policy_filter_config;
+pub use skills_config::BundledSkillsConfig;
+pub use skills_config::SkillConfig;
+pub use skills_config::SkillConfigRule;
+pub use skills_config::SkillConfigRuleSelector;
+pub use skills_config::SkillConfigRules;
+pub use skills_config::SkillsConfig;
+pub use skills_config::bundled_skills_enabled_from_stack;
+pub use skills_config::skill_config_rules_from_stack;
+pub use state::ConfigLayerEntry;
+pub use state::ConfigLayerStack;
+pub use state::ConfigLoadOptions;
+pub use state::LoaderOverrides;
+pub use strict_config::config_error_from_ignored_toml_fields;
+pub use thread_config::NoopThreadConfigLoader;
+pub use thread_config::RemoteThreadConfigLoader;
+pub use thread_config::SessionThreadConfig;
+pub use thread_config::StaticThreadConfigLoader;
+pub use thread_config::ThreadConfigContext;
+pub use thread_config::ThreadConfigLoadError;
+pub use thread_config::ThreadConfigLoadErrorCode;
+pub use thread_config::ThreadConfigLoader;
+pub use thread_config::ThreadConfigLoaderFuture;
+pub use thread_config::ThreadConfigSource;
+pub use thread_config::UserThreadConfig;
+pub use toml::Value as TomlValue;

codex-rs/config/src/mcp_edit.rs

@@ -0,0 +1,50 @@
+use std::collections::BTreeMap;
+use std::io::ErrorKind;
+use std::path::Path;
+
+use toml::Value as TomlValue;
+
+use crate::CONFIG_TOML_FILE;
+use crate::McpServerConfig;
+
+pub async fn load_global_mcp_servers(
+    codex_home: &Path,
+) -> std::io::Result<BTreeMap<String, McpServerConfig>> {
+    let config_path = codex_home.join(CONFIG_TOML_FILE);
+    let raw = match tokio::fs::read_to_string(&config_path).await {
+        Ok(raw) => raw,
+        Err(err) if err.kind() == ErrorKind::NotFound => return Ok(BTreeMap::new()),
+        Err(err) => return Err(err),
+    };
+    let parsed = toml::from_str::<TomlValue>(&raw)
+        .map_err(|err| std::io::Error::new(ErrorKind::InvalidData, err))?;
+    let Some(servers_value) = parsed.get("mcp_servers") else {
+        return Ok(BTreeMap::new());
+    };
+
+    ensure_no_inline_bearer_tokens(servers_value)?;
+
+    servers_value
+        .clone()
+        .try_into()
+        .map_err(|err| std::io::Error::new(ErrorKind::InvalidData, err))
+}
+
+fn ensure_no_inline_bearer_tokens(value: &TomlValue) -> std::io::Result<()> {
+    let Some(servers_table) = value.as_table() else {
+        return Ok(());
+    };
+
+    for (server_name, server_value) in servers_table {
+        if let Some(server_table) = server_value.as_table()
+            && server_table.contains_key("bearer_token")
+        {
+            let message = format!(
+                "mcp_servers.{server_name} uses unsupported `bearer_token`; set `bearer_token_env_var`."
+            );
+            return Err(std::io::Error::new(ErrorKind::InvalidData, message));
+        }
+    }
+
+    Ok(())
+}

codex-rs/config/src/mcp_ema_tests.rs

@@ -0,0 +1,309 @@
+//! Enterprise registration provenance checks.
+
+use super::*;
+use crate::AbsolutePathBuf;
+use crate::ConfigLayerEntry;
+use crate::ConfigRequirements;
+use crate::ConfigRequirementsToml;
+use pretty_assertions::assert_eq;
+
+fn stack(layers: Vec<(ConfigLayerSource, &str)>) -> ConfigLayerStack {
+    ConfigLayerStack::new(
+        layers
+            .into_iter()
+            .map(|(source, value)| ConfigLayerEntry::new(source, toml::from_str(value).unwrap()))
+            .collect(),
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .unwrap()
+}
+
+fn local_sources(name: &str) -> (ConfigLayerSource, ConfigLayerSource, ConfigLayerSource) {
+    let path = AbsolutePathBuf::from_absolute_path(std::env::temp_dir().join(name)).unwrap();
+    (
+        ConfigLayerSource::System { file: path.clone() },
+        ConfigLayerSource::User {
+            file: path.clone(),
+            profile: None,
+        },
+        ConfigLayerSource::Project {
+            dot_codex_folder: path,
+        },
+    )
+}
+
+fn validate_effective_ema(stack: &ConfigLayerStack) -> std::io::Result<()> {
+    let servers = stack
+        .effective_config()
+        .get("mcp_servers")
+        .cloned()
+        .unwrap_or_else(|| toml::Value::Table(Default::default()))
+        .try_into::<std::collections::HashMap<String, McpServerConfig>>()
+        .map_err(|error| std::io::Error::new(std::io::ErrorKind::InvalidInput, error))?;
+    validate_ema_auth_sources(stack, &servers)
+}
+
+fn valid_ema_layers(layers: Vec<(ConfigLayerSource, &str)>) -> bool {
+    validate_effective_ema(&stack(layers)).is_ok()
+}
+
+#[test]
+fn ema_profiles_and_auth_modes_preserve_non_project_authority() {
+    let (system, user, project) = local_sources("ema-config");
+    let trusted = "[mcp_enterprise_managed_auth.idp]\nissuer = 'https://idp.example'\nclient_id = 'enterprise'";
+    let replacement =
+        "[mcp_enterprise_managed_auth.idp]\nissuer = 'https://other.example'\nclient_id = 'other'";
+    let expected = McpEnterpriseManagedAuthConfig {
+        idp: McpServerIdpOAuthConfig {
+            issuer: "https://idp.example".into(),
+            client_id: "enterprise".into(),
+        },
+    };
+    for (layers, selected) in [
+        (
+            vec![
+                (system.clone(), trusted),
+                (user.clone(), replacement),
+                (project.clone(), replacement),
+            ],
+            Some(expected.clone()),
+        ),
+        (
+            vec![(user.clone(), trusted), (project.clone(), replacement)],
+            Some(expected.clone()),
+        ),
+        (vec![(project, trusted)], None),
+        (
+            vec![
+                (system, trusted),
+                (
+                    user,
+                    "[mcp_enterprise_managed_auth.idp]\nclient_id = 'partial'",
+                ),
+            ],
+            Some(expected),
+        ),
+    ] {
+        assert_eq!(
+            McpEnterpriseManagedAuthConfig::from_config_layers(
+                &stack(layers),
+                /*fallback*/ None
+            )
+            .unwrap(),
+            selected
+        );
+    }
+    let incomplete = stack(vec![(
+        ConfigLayerSource::SessionFlags,
+        "[mcp_enterprise_managed_auth.idp]\nclient_id = 'partial'",
+    )]);
+    assert!(
+        McpEnterpriseManagedAuthConfig::from_config_layers(&incomplete, /*fallback*/ None).is_err()
+    );
+
+    let server: McpServerConfig = toml::from_str("url='https://resource.example'\nauth='ema_auth'\n[oauth.idp]\nissuer='https://other.example'\nclient_id='other'").unwrap();
+    assert_eq!(server.oauth_idp(), None);
+}
+
+#[test]
+fn ema_registrations_require_one_atomic_non_project_source() {
+    let (system, user, project) = local_sources("ema-registration-sources");
+    for (section, authorization, protected_changes) in [
+        (
+            "mcp_servers.enterprise",
+            r#"
+            auth='ema_auth'
+            oauth_resource='https://resource.example'
+            oauth.client_id='resource-client'
+            oauth.authorization_server_issuer='https://as.example'
+        "#,
+            &[
+                "oauth_resource='https://other.example'",
+                "oauth.client_id='other-client'",
+                "oauth.authorization_server_issuer='https://other-as.example'",
+            ] as &[&str],
+        ),
+        (
+            "plugins.\"sample@test\".mcp_servers.enterprise.ema_auth",
+            r#"
+            resource='https://resource.example'
+            client_id='resource-client'
+            authorization_server_issuer='https://as.example'
+        "#,
+            &[
+                "resource='https://other.example'",
+                "client_id='other-client'",
+                "authorization_server_issuer='https://other-as.example'",
+            ],
+        ),
+    ] {
+        let registration = format!(
+            "[{section}]\nurl='https://resource.example/mcp'\nscopes=['tools']\n{authorization}"
+        );
+        for (source, allowed) in [
+            (system.clone(), true),
+            (user.clone(), true),
+            (project.clone(), false),
+        ] {
+            assert_eq!(
+                valid_ema_layers(vec![(source, registration.as_str())]),
+                allowed,
+                "{section}"
+            );
+        }
+        for change in protected_changes.iter().copied().chain([
+            "url='https://other.example/mcp'",
+            "url='https://resource.example/mcp/other'",
+            "scopes=['admin']",
+        ]) {
+            let overlay = format!("[{section}]\n{change}");
+            assert!(
+                !valid_ema_layers(vec![
+                    (system.clone(), &registration),
+                    (project.clone(), &overlay)
+                ]),
+                "{section}: {change}"
+            );
+        }
+        let higher = registration.replace("tools", "managed-tools");
+        assert!(
+            !valid_ema_layers(vec![
+                (system.clone(), &registration),
+                (user.clone(), &higher),
+                (project.clone(), &registration)
+            ]),
+            "project rollback: {section}"
+        );
+        let policy_section = section.strip_suffix(".ema_auth").unwrap_or(section);
+        let policy = format!(
+            "[{policy_section}]\nenabled=false\n[{policy_section}.tools.read]\napproval_mode='prompt'"
+        );
+        assert!(valid_ema_layers(vec![
+            (system.clone(), &registration),
+            (project.clone(), &policy)
+        ]));
+        if section.ends_with(".ema_auth") {
+            for required in [
+                "url='https://resource.example/mcp'\n",
+                "resource='https://resource.example'\n",
+            ] {
+                assert!(
+                    !valid_ema_layers(vec![(system.clone(), &registration.replace(required, ""))]),
+                    "missing {required}"
+                );
+            }
+        } else {
+            assert!(valid_ema_layers(vec![
+                (system.clone(), &registration),
+                (project.clone(), "[mcp_servers.enterprise]\nauth='ema_auth'")
+            ]));
+        }
+    }
+}
+
+#[test]
+fn project_cannot_reenable_trusted_disabled_ema_registration() {
+    let (system, user, project) = local_sources("ema-disabled-source");
+    let trusted = "[mcp_servers.enterprise]\nurl='https://resource.example/mcp'\nauth='ema_auth'\nenabled=false";
+    let project_enable = "[mcp_servers.enterprise]\nenabled=true";
+    assert!(!valid_ema_layers(vec![
+        (system.clone(), trusted),
+        (project.clone(), project_enable)
+    ]));
+    assert!(valid_ema_layers(vec![
+        (system.clone(), trusted),
+        (user, project_enable)
+    ]));
+    let enabled = trusted.replace("enabled=false", "enabled=true");
+    assert!(valid_ema_layers(vec![
+        (system, &enabled),
+        (project, "[mcp_servers.enterprise]\nenabled=false")
+    ]));
+}
+
+#[test]
+fn project_cannot_reenable_trusted_disabled_ema_plugin() {
+    let (system, _, project) = local_sources("ema-disabled-plugin");
+    let trusted = r#"
+        [plugins."sample@test".mcp_servers.enterprise]
+        enabled=false
+        [plugins."sample@test".mcp_servers.enterprise.ema_auth]
+        url='https://resource.example/mcp'
+        client_id='resource-client'
+        authorization_server_issuer='https://as.example'
+        resource='https://resource.example'
+    "#;
+    let project_enable = "[plugins.\"sample@test\".mcp_servers.enterprise]\nenabled=true";
+    assert!(!valid_ema_layers(vec![
+        (system.clone(), trusted),
+        (project.clone(), project_enable)
+    ]));
+    assert!(valid_ema_layers(vec![
+        (system, trusted),
+        (
+            project,
+            "[plugins.\"sample@test\".mcp_servers.enterprise]\nenabled=false"
+        )
+    ]));
+}
+
+#[test]
+fn non_project_auth_changes_and_ordinary_oauth_remain_allowed() {
+    let (system, user, project) = local_sources("ema-auth-downgrade");
+    for (base_auth, source) in [("ema_auth", user), ("oauth", project)] {
+        let base = format!(
+            "[mcp_servers.enterprise]\nurl='https://resource.example/mcp'\nauth='{base_auth}'"
+        );
+        assert!(
+            validate_effective_ema(&stack(vec![
+                (system.clone(), &base),
+                (
+                    source,
+                    "[mcp_servers.enterprise]\nauth='oauth'\nenabled=false"
+                ),
+            ]))
+            .is_ok()
+        );
+    }
+}
+
+#[test]
+fn xaa_opt_in_requires_a_non_project_source() {
+    let (_, user, project) = local_sources("xaa-sources");
+    let session = ConfigLayerSource::SessionFlags;
+    let enabled = "[features]\nuse_xaa=true";
+
+    for (source, allowed) in [(user, true), (session, true), (project.clone(), false)] {
+        assert_eq!(
+            validate_xaa_opt_in_source(&stack(vec![(source, enabled)]), /*xaa_enabled*/ true,)
+                .is_ok(),
+            allowed
+        );
+    }
+    assert!(
+        validate_xaa_opt_in_source(&stack(vec![(project, enabled)]), /*xaa_enabled*/ false,)
+            .is_ok()
+    );
+}
+
+#[test]
+fn ema_rejects_alternate_credentials_and_executor_custody() {
+    for extra in [
+        "bearer_token_env_var='TOKEN'",
+        "http_headers.Authorization='secret'",
+        "http_headers.Accept='application/json'",
+        "env_http_headers.X-Key='TOKEN'",
+        "http_headers_helper='get-headers'",
+        "environment_id='remote'",
+    ] {
+        let server: McpServerConfig = toml::from_str(&format!(
+            "url='https://resource.example'\nauth='ema_auth'\n{extra}"
+        ))
+        .unwrap();
+        assert!(server.validate_ema_auth_transport().is_err(), "{extra}");
+    }
+    let server: McpServerConfig =
+        toml::from_str("url='https://resource.example'\nauth='ema_auth'\nhttp_headers={}").unwrap();
+    assert_eq!(server.validate_ema_auth_transport(), Ok(()));
+}

codex-rs/config/src/mcp_requirements_tests.rs

@@ -0,0 +1,225 @@
+use super::*;
+use crate::McpServerCommandMatcher;
+use crate::mcp_types::McpServerConfig;
+use pretty_assertions::assert_eq;
+use std::collections::HashMap;
+
+fn stdio_server(command: &str, args: &[&str]) -> McpServerConfig {
+    McpServerConfig {
+        auth: Default::default(),
+        transport: McpServerTransportConfig::Stdio {
+            command: command.to_string(),
+            args: args.iter().map(ToString::to_string).collect(),
+            env: None,
+            env_vars: Vec::new(),
+            cwd: None,
+        },
+        environment_id: crate::DEFAULT_MCP_SERVER_ENVIRONMENT_ID.to_string(),
+        enabled: true,
+        required: false,
+        supports_parallel_tool_calls: false,
+        omit_tools_from: None,
+        disabled_reason: None,
+        startup_timeout_sec: None,
+        tool_timeout_sec: None,
+        default_tools_approval_mode: None,
+        enabled_tools: None,
+        disabled_tools: None,
+        scopes: None,
+        oauth: None,
+        oauth_resource: None,
+        tools: HashMap::new(),
+    }
+}
+
+#[test]
+fn command_matcher_matches_exact_positional_arguments() {
+    let requirement = McpServerRequirement::Command(McpServerCommandMatcher {
+        executable: "company-cli".to_string(),
+        args: vec![
+            McpServerValueMatcher::Exact {
+                value: "mcp".to_string(),
+            },
+            McpServerValueMatcher::Regex {
+                expression: r"https://[a-z]+\.example\.com".to_string(),
+            },
+        ],
+    });
+
+    assert!(
+        stdio_server("company-cli", &["mcp", "https://pricing.example.com"])
+            .matches_requirement(&requirement)
+    );
+    assert!(
+        !stdio_server("company-cli", &["https://pricing.example.com", "mcp"])
+            .matches_requirement(&requirement)
+    );
+    assert!(
+        !stdio_server(
+            "company-cli",
+            &["mcp", "https://pricing.example.com", "--verbose"]
+        )
+        .matches_requirement(&requirement)
+    );
+    assert!(
+        !stdio_server(
+            "/usr/local/bin/company-cli",
+            &["mcp", "https://pricing.example.com"]
+        )
+        .matches_requirement(&requirement)
+    );
+}
+
+#[test]
+fn regex_matcher_requires_a_full_value_match() {
+    let matcher = McpServerValueMatcher::Regex {
+        expression: "mcp".to_string(),
+    };
+
+    assert!(matches_value(&matcher, "mcp"));
+    assert!(!matches_value(&matcher, "mcp-proxy"));
+    assert!(!matches_value(&matcher, "prefix-mcp"));
+}
+
+#[test]
+fn regex_matcher_allows_a_later_alternative_to_match_the_full_value() {
+    let matcher = McpServerValueMatcher::Regex {
+        expression: r"https://api\.example\.com|https://api\.example\.com/mcp".to_string(),
+    };
+
+    assert!(matches_value(&matcher, "https://api.example.com/mcp"));
+}
+
+#[test]
+fn regex_matcher_validation_rejects_expression_that_cannot_be_wrapped() {
+    let matcher = McpServerValueMatcher::Regex {
+        expression: "(?x)mcp # trailing comment".to_string(),
+    };
+
+    let err = validate_value_matcher(&matcher)
+        .expect_err("expression should not be valid for full-value matching");
+    assert!(
+        err.contains("cannot be used for full-value matching"),
+        "{err}"
+    );
+}
+
+#[test]
+fn legacy_command_identity_keeps_ignoring_arguments() {
+    let requirement: McpServerRequirement = toml::from_str(
+        r#"
+[identity]
+command = "company-cli"
+"#,
+    )
+    .expect("legacy command identity");
+
+    assert!(
+        stdio_server("company-cli", &["any", "arguments", "remain", "allowed"])
+            .matches_requirement(&requirement)
+    );
+    assert!(!stdio_server("different-cli", &[]).matches_requirement(&requirement));
+}
+
+#[test]
+fn requirement_deserializes_command_and_url_matcher_shapes() {
+    let command: McpServerRequirement = toml::from_str(
+        r#"
+[identity]
+command = { executable = "company-cli", args = [
+    { match = "exact", value = "mcp" },
+    { match = "regex", expression = '^https://[a-z]+\.example\.com$' },
+] }
+"#,
+    )
+    .expect("command matcher");
+    let url: McpServerRequirement = toml::from_str(
+        r#"
+[identity]
+url = { match = "prefix", value = "https://mcp.example.com/" }
+"#,
+    )
+    .expect("URL matcher");
+
+    assert_eq!(
+        command,
+        McpServerRequirement::Command(McpServerCommandMatcher {
+            executable: "company-cli".to_string(),
+            args: vec![
+                McpServerValueMatcher::Exact {
+                    value: "mcp".to_string(),
+                },
+                McpServerValueMatcher::Regex {
+                    expression: r"^https://[a-z]+\.example\.com$".to_string(),
+                },
+            ],
+        })
+    );
+    assert_eq!(
+        url,
+        McpServerRequirement::Url(McpServerValueMatcher::Prefix {
+            value: "https://mcp.example.com/".to_string(),
+        })
+    );
+}
+
+#[test]
+fn requirement_rejects_matchers_outside_identity() {
+    for contents in [
+        r#"
+command = "company-cli"
+"#,
+        r#"
+command = { executable = "company-cli", args = [] }
+"#,
+        r#"
+url = { match = "prefix", value = "https://mcp.example.com/" }
+"#,
+    ] {
+        let err = toml::from_str::<McpServerRequirement>(contents)
+            .expect_err("MCP server requirements should use the identity key");
+        assert!(
+            err.to_string().contains("missing field `identity`"),
+            "{err}"
+        );
+    }
+}
+
+#[test]
+fn matcher_identity_rejects_unknown_fields() {
+    for contents in [
+        r#"
+[identity]
+unknown = "value"
+command = { executable = "company-cli", args = [] }
+"#,
+        r#"
+[identity]
+command = { executable = "company-cli", args = [], unknown = "value" }
+"#,
+    ] {
+        toml::from_str::<McpServerRequirement>(contents)
+            .expect_err("matcher identities should reject unknown fields");
+    }
+}
+
+#[test]
+fn identity_requirement_keeps_ignoring_unrelated_sibling_fields() {
+    let requirement: McpServerRequirement = toml::from_str(
+        r#"
+unrelated = "ignored"
+[identity]
+command = "company-cli"
+"#,
+    )
+    .expect("legacy identity with unrelated sibling field");
+
+    assert_eq!(
+        requirement,
+        McpServerRequirement::Identity {
+            identity: McpServerIdentity::Command {
+                command: "company-cli".to_string(),
+            },
+        }
+    );
+}

codex-rs/config/src/mcp_types.rs

@@ -0,0 +1,626 @@
+//! MCP server configuration types.
+
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::fmt;
+use std::num::NonZeroUsize;
+use std::time::Duration;
+
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use codex_protocol::config_types::ToolExposureSurface;
+use codex_utils_path_uri::LegacyAppPathString;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Deserializer;
+use serde::Serialize;
+use serde::de::Error as SerdeError;
+
+use crate::McpEmaRegistration;
+use crate::RequirementSource;
+
+/// Effective MCP environment id when config omits `environment_id`.
+pub const DEFAULT_MCP_SERVER_ENVIRONMENT_ID: &str = "local";
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Default, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum AppToolApproval {
+    #[default]
+    Auto,
+    Prompt,
+    Writes,
+    Approve,
+}
+
+impl AppToolApproval {
+    /// Requires approval whenever either policy could require it.
+    ///
+    /// `Auto` and `Writes` are incomparable: each can require approval for a
+    /// tool the other would approve. Their conservative intersection is `Prompt`.
+    pub fn restrict_to(self, requested: Self) -> Self {
+        match (self, requested) {
+            (Self::Prompt, _) | (_, Self::Prompt) => Self::Prompt,
+            (Self::Approve, mode) | (mode, Self::Approve) => mode,
+            (Self::Auto, Self::Auto) => Self::Auto,
+            (Self::Writes, Self::Writes) => Self::Writes,
+            (Self::Auto, Self::Writes) | (Self::Writes, Self::Auto) => Self::Prompt,
+        }
+    }
+}
+
+/// Human-readable reason a configured MCP server was disabled after requirements
+/// were applied.
+///
+/// `Display` is intentionally implemented for CLI/TUI status output; avoid
+/// relying on `Debug` because enum variant syntax is not part of the user-facing
+/// message contract.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum McpServerDisabledReason {
+    /// The server is disabled, but there is no more specific user-facing reason.
+    Unknown,
+    /// The server was disabled by config requirements from the given source.
+    Requirements { source: RequirementSource },
+    /// Enterprise authorization was rejected for this registration, not its name.
+    EmaRegistration,
+}
+
+impl fmt::Display for McpServerDisabledReason {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            McpServerDisabledReason::Unknown => write!(f, "unknown"),
+            McpServerDisabledReason::Requirements { source } => {
+                write!(f, "requirements ({source})")
+            }
+            McpServerDisabledReason::EmaRegistration => {
+                write!(f, "invalid enterprise registration")
+            }
+        }
+    }
+}
+
+/// Per-tool settings for a single MCP server tool.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct McpServerToolConfig {
+    /// Approval mode for this tool.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub approval_mode: Option<AppToolApproval>,
+
+    /// Token budget for this tool's output, before the standard 20% serialization allowance.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_token_limit: Option<NonZeroUsize>,
+}
+
+impl McpServerToolConfig {
+    /// Applies the stricter explicit output budget without changing approval policy.
+    pub fn restrict_output_token_limit(&mut self, limit: Option<NonZeroUsize>) {
+        self.output_token_limit = self.output_token_limit.into_iter().chain(limit).min();
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[serde(untagged, deny_unknown_fields)]
+pub enum McpServerEnvVar {
+    Name(String),
+    Config {
+        name: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        source: Option<String>,
+    },
+}
+
+impl McpServerEnvVar {
+    pub fn name(&self) -> &str {
+        match self {
+            McpServerEnvVar::Name(name) => name,
+            McpServerEnvVar::Config { name, .. } => name,
+        }
+    }
+
+    pub fn source(&self) -> Option<&str> {
+        match self {
+            McpServerEnvVar::Name(_) => None,
+            McpServerEnvVar::Config { source, .. } => source.as_deref(),
+        }
+    }
+
+    pub fn is_remote_source(&self) -> bool {
+        self.source() == Some("remote")
+    }
+
+    pub fn validate_source(&self) -> Result<(), String> {
+        match self.source() {
+            None | Some("local") | Some("remote") => Ok(()),
+            Some(source) => Err(format!(
+                "unsupported env_vars source `{source}`; expected `local` or `remote`"
+            )),
+        }
+    }
+}
+
+impl From<String> for McpServerEnvVar {
+    fn from(value: String) -> Self {
+        Self::Name(value)
+    }
+}
+
+impl From<&str> for McpServerEnvVar {
+    fn from(value: &str) -> Self {
+        Self::Name(value.to_string())
+    }
+}
+
+impl AsRef<str> for McpServerEnvVar {
+    fn as_ref(&self) -> &str {
+        self.name()
+    }
+}
+
+/// Client settings for MCP OAuth login or enterprise token exchange.
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct McpServerOAuthConfig {
+    /// Explicit OAuth client identifier to present during authorization and token exchange.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub client_id: Option<String>,
+
+    /// Registered callback URL associated with this OAuth client.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub callback_url: Option<String>,
+
+    /// Fixed callback port that takes precedence over Codex's global OAuth callback port.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub callback_port: Option<u16>,
+
+    /// Expected resource authorization server issuer for EMA token exchange.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub authorization_server_issuer: Option<String>,
+
+    /// Host-resolved authorization; never accepted from a server or plugin declaration.
+    #[serde(skip)]
+    #[schemars(skip)]
+    pub ema_registration: Option<McpEmaRegistration>,
+
+    /// Host-policy rejection retained until catalog finalization; never deserialized.
+    #[serde(skip)]
+    #[schemars(skip)]
+    pub ema_registration_error: Option<&'static str>,
+}
+
+/// Authentication flow for an HTTP MCP server. Explicit credentials take
+/// precedence for OAuth and ChatGPT; EMA rejects alternate credentials and fallback.
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum McpServerAuth {
+    /// Use stored MCP OAuth credentials when available. Starting an OAuth login
+    /// is a separate operation.
+    #[default]
+    #[serde(rename = "oauth")]
+    OAuth,
+    /// Use the current ChatGPT session for servers on the trusted first-party
+    /// ChatGPT origin. If no ChatGPT session provider is available, startup can
+    /// still fall back to stored OAuth credentials.
+    #[serde(rename = "chatgpt")]
+    ChatGpt,
+    /// Exchange an enterprise IdP refresh token for resource-specific authorization.
+    /// Alternate credentials and ordinary OAuth fallback are not permitted.
+    #[serde(rename = "ema_auth")]
+    EmaAuth,
+}
+
+impl McpServerAuth {
+    fn is_default(&self) -> bool {
+        self == &Self::default()
+    }
+}
+
+#[derive(Serialize, Debug, Clone, PartialEq)]
+pub struct McpServerConfig {
+    #[serde(flatten)]
+    pub transport: McpServerTransportConfig,
+
+    /// Authentication flow, including an explicit no-fallback EMA mode.
+    #[serde(default, skip_serializing_if = "McpServerAuth::is_default")]
+    pub auth: McpServerAuth,
+
+    /// Effective environment id for where Codex should start this MCP server.
+    pub environment_id: String,
+
+    /// When `false`, Codex skips initializing this MCP server.
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+
+    /// When `true`, `codex exec` exits with an error if this MCP server fails to initialize.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub required: bool,
+
+    /// When `true`, every tool from this server is advertised as safe for parallel tool calls.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub supports_parallel_tool_calls: bool,
+
+    /// Model-facing surfaces from which this server's tools must be omitted.
+    /// `None` leaves lower-priority configuration unchanged; an empty list clears it.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub omit_tools_from: Option<Vec<ToolExposureSurface>>,
+
+    /// Reason this server was disabled after applying requirements.
+    #[serde(skip)]
+    pub disabled_reason: Option<McpServerDisabledReason>,
+
+    /// Startup timeout in seconds for initializing MCP server & initially listing tools.
+    #[serde(
+        default,
+        with = "option_duration_secs",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub startup_timeout_sec: Option<Duration>,
+
+    /// Default timeout for MCP tool calls initiated via this server.
+    #[serde(default, with = "option_duration_secs")]
+    pub tool_timeout_sec: Option<Duration>,
+
+    /// Approval mode for tools in this server unless a tool override exists.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default_tools_approval_mode: Option<AppToolApproval>,
+
+    /// Explicit allow-list of tools exposed from this server. When set, only these tools will be registered.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enabled_tools: Option<Vec<String>>,
+
+    /// Explicit deny-list of tools. These tools will be removed after applying `enabled_tools`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub disabled_tools: Option<Vec<String>>,
+
+    /// Optional scopes requested during MCP login or EMA token exchange.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub scopes: Option<Vec<String>>,
+
+    /// Optional client settings for MCP login or EMA token exchange.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub oauth: Option<McpServerOAuthConfig>,
+
+    /// Optional resource parameter for MCP login or EMA token exchange (RFC 8707).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub oauth_resource: Option<String>,
+
+    /// Per-tool settings keyed by tool name.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub tools: HashMap<String, McpServerToolConfig>,
+}
+
+impl McpServerConfig {
+    pub fn is_local_environment(&self) -> bool {
+        self.environment_id == DEFAULT_MCP_SERVER_ENVIRONMENT_ID
+    }
+
+    /// Keeps local OAuth credentials compatible while reserving managed credential namespaces.
+    pub fn oauth_credential_name<'a>(&self, server_name: &'a str) -> Cow<'a, str> {
+        if self.is_local_environment() {
+            if server_name.starts_with("executor:")
+                || server_name.starts_with("local:")
+                || server_name.starts_with("ema-idp:")
+            {
+                Cow::Owned(format!("local:{server_name}"))
+            } else {
+                Cow::Borrowed(server_name)
+            }
+        } else {
+            let environment = URL_SAFE_NO_PAD.encode(self.environment_id.as_bytes());
+            let server = URL_SAFE_NO_PAD.encode(server_name.as_bytes());
+            Cow::Owned(format!("executor:{environment}:{server}"))
+        }
+    }
+
+    pub fn oauth_client_id(&self) -> Option<&str> {
+        self.oauth
+            .as_ref()
+            .and_then(|oauth| oauth.client_id.as_deref())
+    }
+
+    pub fn oauth_callback_port(&self, global_callback_port: Option<u16>) -> Option<u16> {
+        let callback_port = self.oauth.as_ref().and_then(|oauth| oauth.callback_port);
+        if let Some(callback_port) = callback_port {
+            tracing::info!(
+                callback_port,
+                ?global_callback_port,
+                "using plugin-specific MCP OAuth callback port instead of the global callback port"
+            );
+        }
+        callback_port.or(global_callback_port)
+    }
+}
+
+/// Raw MCP config shape used for deserialization and supported-field JSON
+/// Schema generation.
+///
+/// Fields that are accepted only to produce targeted validation errors should
+/// be skipped in the generated schema.
+///
+/// Keep `TryFrom<RawMcpServerConfig> for McpServerConfig` exhaustively
+/// destructuring this struct so new TOML fields cannot be added here without
+/// updating the validation/mapping logic that produces [`McpServerConfig`].
+#[derive(Deserialize, Clone, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct RawMcpServerConfig {
+    // stdio
+    pub command: Option<String>,
+    #[serde(default)]
+    pub args: Option<Vec<String>>,
+    #[serde(default)]
+    pub env: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub env_vars: Option<Vec<McpServerEnvVar>>,
+    #[serde(default)]
+    pub cwd: Option<LegacyAppPathString>,
+    pub http_headers: Option<HashMap<String, String>>,
+    #[serde(default)]
+    pub env_http_headers: Option<HashMap<String, String>>,
+
+    // streamable_http
+    pub url: Option<String>,
+    #[schemars(skip)]
+    pub bearer_token: Option<String>,
+    pub bearer_token_env_var: Option<String>,
+    pub http_headers_helper: Option<String>,
+
+    // shared
+    #[serde(default)]
+    pub environment_id: Option<String>,
+    #[serde(default)]
+    pub auth: Option<McpServerAuth>,
+    #[serde(default)]
+    pub startup_timeout_sec: Option<f64>,
+    #[serde(default)]
+    pub startup_timeout_ms: Option<u64>,
+    #[serde(default, with = "option_duration_secs")]
+    #[schemars(with = "Option<f64>")]
+    pub tool_timeout_sec: Option<Duration>,
+    #[serde(default)]
+    pub enabled: Option<bool>,
+    #[serde(default)]
+    pub required: Option<bool>,
+    #[serde(default)]
+    pub supports_parallel_tool_calls: Option<bool>,
+    #[serde(default)]
+    pub omit_tools_from: Option<Vec<ToolExposureSurface>>,
+    #[serde(default)]
+    pub default_tools_approval_mode: Option<AppToolApproval>,
+    #[serde(default)]
+    pub enabled_tools: Option<Vec<String>>,
+    #[serde(default)]
+    pub disabled_tools: Option<Vec<String>>,
+    #[serde(default)]
+    pub scopes: Option<Vec<String>>,
+    #[serde(default)]
+    pub oauth: Option<McpServerOAuthConfig>,
+    #[serde(default)]
+    pub oauth_resource: Option<String>,
+    /// Legacy display-name field accepted for backward compatibility.
+    #[serde(default, rename = "name")]
+    pub _name: Option<String>,
+    #[serde(default)]
+    pub tools: Option<HashMap<String, McpServerToolConfig>>,
+}
+
+impl TryFrom<RawMcpServerConfig> for McpServerConfig {
+    type Error = String;
+
+    fn try_from(raw: RawMcpServerConfig) -> Result<Self, Self::Error> {
+        let RawMcpServerConfig {
+            command,
+            args,
+            env,
+            env_vars,
+            cwd,
+            http_headers,
+            env_http_headers,
+            url,
+            bearer_token,
+            bearer_token_env_var,
+            http_headers_helper,
+            environment_id,
+            auth,
+            startup_timeout_sec,
+            startup_timeout_ms,
+            tool_timeout_sec,
+            enabled,
+            required,
+            supports_parallel_tool_calls,
+            omit_tools_from,
+            default_tools_approval_mode,
+            enabled_tools,
+            disabled_tools,
+            scopes,
+            oauth,
+            oauth_resource,
+            _name: _,
+            tools,
+        } = raw;
+
+        let startup_timeout_sec = match (startup_timeout_sec, startup_timeout_ms) {
+            (Some(sec), _) => {
+                Some(Duration::try_from_secs_f64(sec).map_err(|err| err.to_string())?)
+            }
+            (None, Some(ms)) => Some(Duration::from_millis(ms)),
+            (None, None) => None,
+        };
+
+        fn throw_if_set<T>(transport: &str, field: &str, value: Option<&T>) -> Result<(), String> {
+            if value.is_none() {
+                return Ok(());
+            }
+            Err(format!("{field} is not supported for {transport}"))
+        }
+
+        let transport = if let Some(command) = command {
+            throw_if_set("stdio", "url", url.as_ref())?;
+            throw_if_set(
+                "stdio",
+                "bearer_token_env_var",
+                bearer_token_env_var.as_ref(),
+            )?;
+            throw_if_set("stdio", "bearer_token", bearer_token.as_ref())?;
+            throw_if_set("stdio", "http_headers_helper", http_headers_helper.as_ref())?;
+            throw_if_set("stdio", "http_headers", http_headers.as_ref())?;
+            throw_if_set("stdio", "env_http_headers", env_http_headers.as_ref())?;
+            throw_if_set("stdio", "oauth", oauth.as_ref())?;
+            throw_if_set("stdio", "oauth_resource", oauth_resource.as_ref())?;
+            throw_if_set("stdio", "auth", auth.as_ref())?;
+            let env_vars = env_vars.unwrap_or_default();
+            for env_var in &env_vars {
+                env_var.validate_source()?;
+            }
+            McpServerTransportConfig::Stdio {
+                command,
+                args: args.unwrap_or_default(),
+                env,
+                env_vars,
+                cwd,
+            }
+        } else if let Some(url) = url {
+            throw_if_set("streamable_http", "args", args.as_ref())?;
+            throw_if_set("streamable_http", "env", env.as_ref())?;
+            throw_if_set("streamable_http", "env_vars", env_vars.as_ref())?;
+            throw_if_set("streamable_http", "cwd", cwd.as_ref())?;
+            throw_if_set("streamable_http", "bearer_token", bearer_token.as_ref())?;
+            if http_headers_helper
+                .as_deref()
+                .is_some_and(|command| command.trim().is_empty())
+            {
+                return Err("http_headers_helper must not be empty".to_string());
+            }
+            if environment_id
+                .as_deref()
+                .is_some_and(|environment_id| environment_id != DEFAULT_MCP_SERVER_ENVIRONMENT_ID)
+                && http_headers_helper.is_some()
+            {
+                return Err(
+                    "http_headers_helper is only supported for local MCP servers".to_string(),
+                );
+            }
+            McpServerTransportConfig::StreamableHttp {
+                url,
+                bearer_token_env_var,
+                http_headers,
+                env_http_headers,
+                http_headers_helper,
+            }
+        } else {
+            return Err("invalid transport".to_string());
+        };
+
+        let environment_id =
+            environment_id.unwrap_or_else(|| DEFAULT_MCP_SERVER_ENVIRONMENT_ID.to_string());
+        let auth = auth.unwrap_or_default();
+        if !matches!(auth, McpServerAuth::EmaAuth)
+            && oauth
+                .as_ref()
+                .is_some_and(|oauth| oauth.authorization_server_issuer.is_some())
+        {
+            return Err(
+                "oauth.authorization_server_issuer requires auth = \"ema_auth\"".to_string(),
+            );
+        }
+
+        Ok(Self {
+            transport,
+            auth,
+            environment_id,
+            startup_timeout_sec,
+            tool_timeout_sec,
+            enabled: enabled.unwrap_or_else(default_enabled),
+            required: required.unwrap_or_default(),
+            supports_parallel_tool_calls: supports_parallel_tool_calls.unwrap_or_default(),
+            omit_tools_from,
+            disabled_reason: None,
+            default_tools_approval_mode,
+            enabled_tools,
+            disabled_tools,
+            scopes,
+            oauth,
+            oauth_resource,
+            tools: tools.unwrap_or_default(),
+        })
+    }
+}
+
+impl<'de> Deserialize<'de> for McpServerConfig {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        RawMcpServerConfig::deserialize(deserializer)?
+            .try_into()
+            .map_err(SerdeError::custom)
+    }
+}
+
+const fn default_enabled() -> bool {
+    true
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
+#[serde(untagged, deny_unknown_fields, rename_all = "snake_case")]
+pub enum McpServerTransportConfig {
+    /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
+    Stdio {
+        command: String,
+        #[serde(default)]
+        args: Vec<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        env: Option<HashMap<String, String>>,
+        #[serde(default, skip_serializing_if = "Vec::is_empty")]
+        env_vars: Vec<McpServerEnvVar>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        cwd: Option<LegacyAppPathString>,
+    },
+    /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
+    StreamableHttp {
+        url: String,
+        /// Name of the environment variable to read for an HTTP bearer token.
+        /// When set, requests will include the token via `Authorization: Bearer <token>`.
+        /// The actual secret value must be provided via the environment.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        bearer_token_env_var: Option<String>,
+        /// Additional HTTP headers to include in requests to this server.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        http_headers: Option<HashMap<String, String>>,
+        /// HTTP headers where the value is sourced from an environment variable.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        env_http_headers: Option<HashMap<String, String>>,
+        /// Local-only shell command that prints a JSON object of dynamic HTTP headers.
+        /// The command may be visible to local process inspection; do not embed credentials.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        http_headers_helper: Option<String>,
+    },
+}
+
+mod option_duration_secs {
+    use serde::Deserialize;
+    use serde::Deserializer;
+    use serde::Serializer;
+    use std::time::Duration;
+
+    pub fn serialize<S>(value: &Option<Duration>, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        match value {
+            Some(duration) => serializer.serialize_some(&duration.as_secs_f64()),
+            None => serializer.serialize_none(),
+        }
+    }
+
+    pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<Duration>, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let secs = Option::<f64>::deserialize(deserializer)?;
+        secs.map(|secs| Duration::try_from_secs_f64(secs).map_err(serde::de::Error::custom))
+            .transpose()
+    }
+}
+
+#[cfg(test)]
+#[path = "mcp_types_tests.rs"]
+mod tests;

codex-rs/config/src/mcp_types_tests.rs

@@ -0,0 +1,663 @@
+use super::*;
+use codex_utils_path_uri::LegacyAppPathString;
+use pretty_assertions::assert_eq;
+use std::collections::HashMap;
+use std::path::Path;
+
+#[test]
+fn app_tool_approval_restrictions_never_weaken_either_policy() {
+    use AppToolApproval::Approve;
+    use AppToolApproval::Auto;
+    use AppToolApproval::Prompt;
+    use AppToolApproval::Writes;
+
+    let modes = [Approve, Auto, Writes, Prompt];
+    let expected = [
+        [Approve, Auto, Writes, Prompt],
+        [Auto, Auto, Prompt, Prompt],
+        [Writes, Prompt, Writes, Prompt],
+        [Prompt, Prompt, Prompt, Prompt],
+    ];
+
+    for (parent_index, parent) in modes.into_iter().enumerate() {
+        for (requested_index, requested) in modes.into_iter().enumerate() {
+            assert_eq!(
+                parent.restrict_to(requested),
+                expected[parent_index][requested_index],
+                "parent: {parent:?}, requested: {requested:?}",
+            );
+        }
+    }
+}
+
+#[test]
+fn deserialize_stdio_command_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+        "#,
+    )
+    .expect("should deserialize command config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: Vec::new(),
+            cwd: None,
+        }
+    );
+    assert!(cfg.enabled);
+    assert!(!cfg.required);
+    assert_eq!(cfg.omit_tools_from, None);
+    assert!(cfg.enabled_tools.is_none());
+    assert!(cfg.disabled_tools.is_none());
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_args() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            args = ["hello", "world"]
+        "#,
+    )
+    .expect("should deserialize command config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec!["hello".to_string(), "world".to_string()],
+            env: None,
+            env_vars: Vec::new(),
+            cwd: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_remote_stdio_server_accepts_foreign_absolute_cwd() {
+    #[cfg(not(windows))]
+    let cwd = r"C:\Users\openai\share";
+    #[cfg(windows)]
+    let cwd = "/home/openai/share";
+    let expected_cwd = LegacyAppPathString::from_path(Path::new(cwd));
+    let cfg: McpServerConfig = match toml::from_str(&format!(
+        r#"
+            command = "echo"
+            environment_id = "remote"
+            cwd = {cwd:?}
+        "#
+    )) {
+        Ok(cfg) => cfg,
+        Err(error) => panic!("remote stdio MCP should accept absolute cwd: {error}"),
+    };
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: Vec::new(),
+            cwd: Some(expected_cwd),
+        }
+    );
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_arg_with_args_and_env() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            args = ["hello", "world"]
+            env = { "FOO" = "BAR" }
+        "#,
+    )
+    .expect("should deserialize command config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec!["hello".to_string(), "world".to_string()],
+            env: Some(HashMap::from([("FOO".to_string(), "BAR".to_string())])),
+            env_vars: Vec::new(),
+            cwd: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_env_vars() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            env_vars = ["FOO", "BAR"]
+        "#,
+    )
+    .expect("should deserialize command config with env_vars");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: vec!["FOO".into(), "BAR".into()],
+            cwd: None,
+        }
+    );
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_env_var_sources() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            env_vars = [
+                "LEGACY_TOKEN",
+                { name = "LOCAL_TOKEN", source = "local" },
+                { name = "REMOTE_TOKEN", source = "remote" },
+            ]
+        "#,
+    )
+    .expect("should deserialize command config with sourced env_vars");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: vec![
+                McpServerEnvVar::Name("LEGACY_TOKEN".to_string()),
+                McpServerEnvVar::Config {
+                    name: "LOCAL_TOKEN".to_string(),
+                    source: Some("local".to_string()),
+                },
+                McpServerEnvVar::Config {
+                    name: "REMOTE_TOKEN".to_string(),
+                    source: Some("remote".to_string()),
+                },
+            ],
+            cwd: None,
+        }
+    );
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_rejects_unknown_env_var_source() {
+    let err = toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            env_vars = [{ name = "TOKEN", source = "elsewhere" }]
+        "#,
+    )
+    .expect_err("unsupported env var source should be rejected");
+
+    assert!(
+        err.to_string()
+            .contains("unsupported env_vars source `elsewhere`"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn deserialize_stdio_command_server_config_with_cwd() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            cwd = "/tmp"
+        "#,
+    )
+    .expect("should deserialize command config with cwd");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec![],
+            env: None,
+            env_vars: Vec::new(),
+            cwd: Some(LegacyAppPathString::from_path(Path::new("/tmp"))),
+        }
+    );
+}
+
+#[test]
+fn deserialize_disabled_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            enabled = false
+        "#,
+    )
+    .expect("should deserialize disabled server config");
+
+    assert!(!cfg.enabled);
+    assert!(!cfg.required);
+}
+
+#[test]
+fn deserialize_required_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            required = true
+        "#,
+    )
+    .expect("should deserialize required server config");
+
+    assert!(cfg.required);
+}
+
+#[test]
+fn deserialize_streamable_http_server_config() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+        "#,
+    )
+    .expect("should deserialize http config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::StreamableHttp {
+            url: "https://example.com/mcp".to_string(),
+            bearer_token_env_var: None,
+            http_headers: None,
+            env_http_headers: None,
+            http_headers_helper: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_streamable_http_server_config_with_env_var() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+            bearer_token_env_var = "GITHUB_TOKEN"
+        "#,
+    )
+    .expect("should deserialize http config");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::StreamableHttp {
+            url: "https://example.com/mcp".to_string(),
+            bearer_token_env_var: Some("GITHUB_TOKEN".to_string()),
+            http_headers: None,
+            env_http_headers: None,
+            http_headers_helper: None,
+        }
+    );
+    assert!(cfg.enabled);
+}
+
+#[test]
+fn deserialize_streamable_http_server_config_with_headers() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+            http_headers = { "X-Foo" = "bar" }
+            env_http_headers = { "X-Token" = "TOKEN_ENV" }
+            http_headers_helper = "auth-cli headers"
+        "#,
+    )
+    .expect("should deserialize http config with headers");
+
+    assert_eq!(
+        cfg.transport,
+        McpServerTransportConfig::StreamableHttp {
+            url: "https://example.com/mcp".to_string(),
+            bearer_token_env_var: None,
+            http_headers: Some(HashMap::from([("X-Foo".to_string(), "bar".to_string())])),
+            env_http_headers: Some(HashMap::from([(
+                "X-Token".to_string(),
+                "TOKEN_ENV".to_string()
+            )])),
+            http_headers_helper: Some("auth-cli headers".to_string()),
+        }
+    );
+}
+
+#[test]
+fn rejects_http_headers_helper_outside_local_http_servers() {
+    for contents in [
+        "command = \"server\"\nhttp_headers_helper = \"auth-cli headers\"",
+        "url = \"https://example.com/mcp\"\nhttp_headers_helper = \"  \"",
+        "url = \"https://example.com/mcp\"\nenvironment_id = \"remote\"\nhttp_headers_helper = \"auth-cli headers\"",
+    ] {
+        toml::from_str::<McpServerConfig>(contents).expect_err("invalid helper placement");
+    }
+}
+
+#[test]
+fn deserialize_streamable_http_server_config_with_oauth_resource() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+            oauth_resource = "https://api.example.com"
+        "#,
+    )
+    .expect("should deserialize http config with oauth_resource");
+
+    assert_eq!(
+        cfg.oauth_resource,
+        Some("https://api.example.com".to_string())
+    );
+}
+
+#[test]
+fn deserialize_streamable_http_server_config_with_oauth_client_id() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+
+            [oauth]
+            client_id = "eci-prd-pub-codex-123"
+            callback_url = "http://127.0.0.1/callback/registered"
+            callback_port = 9876
+        "#,
+    )
+    .expect("should deserialize http config with oauth client id");
+
+    assert_eq!(
+        cfg.oauth,
+        Some(McpServerOAuthConfig {
+            client_id: Some("eci-prd-pub-codex-123".to_string()),
+            callback_url: Some("http://127.0.0.1/callback/registered".to_string()),
+            callback_port: Some(9876),
+            ..Default::default()
+        })
+    );
+}
+
+#[test]
+fn oauth_callback_port_prefers_server_port_over_global_port() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+
+            [oauth]
+            callback_port = 9876
+        "#,
+    )
+    .expect("should deserialize http config with oauth callback port");
+
+    assert_eq!(cfg.oauth_callback_port(Some(4321)), Some(9876));
+}
+
+#[test]
+fn oauth_callback_port_falls_back_to_global_port() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            url = "https://example.com/mcp"
+        "#,
+    )
+    .expect("should deserialize http config without oauth callback port");
+
+    assert_eq!(cfg.oauth_callback_port(Some(4321)), Some(4321));
+    assert_eq!(cfg.oauth_callback_port(/*global_callback_port*/ None), None);
+}
+
+#[test]
+fn deserialize_server_config_with_tool_filters() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            enabled_tools = ["allowed"]
+            disabled_tools = ["blocked"]
+        "#,
+    )
+    .expect("should deserialize tool filters");
+
+    assert_eq!(cfg.enabled_tools, Some(vec!["allowed".to_string()]));
+    assert_eq!(cfg.disabled_tools, Some(vec!["blocked".to_string()]));
+}
+
+#[test]
+fn deserialize_server_config_with_parallel_tool_calls() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            supports_parallel_tool_calls = true
+        "#,
+    )
+    .expect("should deserialize supports_parallel_tool_calls");
+
+    assert!(cfg.supports_parallel_tool_calls);
+}
+
+#[test]
+fn serialize_round_trips_server_config_with_omitted_tool_exposure_surfaces() {
+    for omitted_surfaces in [
+        vec![],
+        vec![ToolExposureSurface::CodeMode],
+        vec![ToolExposureSurface::Deferred],
+        vec![ToolExposureSurface::Direct],
+        vec![ToolExposureSurface::CodeMode, ToolExposureSurface::Deferred],
+        vec![ToolExposureSurface::CodeMode, ToolExposureSurface::Direct],
+        vec![ToolExposureSurface::Deferred, ToolExposureSurface::Direct],
+        vec![
+            ToolExposureSurface::CodeMode,
+            ToolExposureSurface::Deferred,
+            ToolExposureSurface::Direct,
+        ],
+    ] {
+        let serialized_surfaces = omitted_surfaces
+            .iter()
+            .map(|surface| format!("\"{surface}\""))
+            .collect::<Vec<_>>()
+            .join(", ");
+        let config = format!("command = \"echo\"\nomit_tools_from = [{serialized_surfaces}]\n");
+        let cfg: McpServerConfig =
+            toml::from_str(&config).expect("should deserialize omitted MCP exposure surfaces");
+        assert_eq!(cfg.omit_tools_from, Some(omitted_surfaces.clone()));
+
+        let serialized = toml::to_string(&cfg).expect("should serialize MCP config");
+        assert!(serialized.contains(&format!("omit_tools_from = [{serialized_surfaces}]")));
+
+        let round_tripped: McpServerConfig =
+            toml::from_str(&serialized).expect("should deserialize serialized MCP config");
+        assert_eq!(round_tripped, cfg);
+    }
+}
+
+#[test]
+fn deserialize_server_config_with_default_tool_approval_mode() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            default_tools_approval_mode = "approve"
+
+            [tools.search]
+            approval_mode = "prompt"
+            output_token_limit = 30000
+        "#,
+    )
+    .expect("should deserialize default tool approval mode");
+
+    assert_eq!(
+        cfg.default_tools_approval_mode,
+        Some(AppToolApproval::Approve)
+    );
+    assert_eq!(
+        cfg.tools.get("search"),
+        Some(&McpServerToolConfig {
+            approval_mode: Some(AppToolApproval::Prompt),
+            output_token_limit: std::num::NonZeroUsize::new(30_000),
+        })
+    );
+
+    let serialized = toml::to_string(&cfg).expect("should serialize MCP config");
+    assert!(serialized.contains("default_tools_approval_mode = \"approve\""));
+    assert!(serialized.contains("output_token_limit = 30000"));
+
+    let round_tripped: McpServerConfig =
+        toml::from_str(&serialized).expect("should deserialize serialized MCP config");
+    assert_eq!(round_tripped, cfg);
+}
+
+#[test]
+fn deserialize_rejects_nonpositive_mcp_tool_output_limits() {
+    for output_token_limit in [0, -1] {
+        let config = format!(
+            "command = \"echo\"\n[tools.search]\noutput_token_limit = {output_token_limit}\n"
+        );
+        let error = toml::from_str::<McpServerConfig>(&config)
+            .expect_err("MCP tool output limit must be positive");
+        assert!(error.to_string().contains("output_token_limit"));
+    }
+}
+
+#[test]
+fn serialize_round_trips_server_config_with_parallel_tool_calls() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            supports_parallel_tool_calls = true
+            tool_timeout_sec = 2.0
+        "#,
+    )
+    .expect("should deserialize supports_parallel_tool_calls");
+
+    let serialized = toml::to_string(&cfg).expect("should serialize MCP config");
+    assert!(serialized.contains("supports_parallel_tool_calls = true"));
+
+    let round_tripped: McpServerConfig =
+        toml::from_str(&serialized).expect("should deserialize serialized MCP config");
+    assert_eq!(round_tripped, cfg);
+}
+
+#[test]
+fn deserialize_ignores_unknown_server_fields() {
+    let cfg: McpServerConfig = toml::from_str(
+        r#"
+            command = "echo"
+            trust_level = "trusted"
+        "#,
+    )
+    .expect("should ignore unknown server fields");
+
+    assert_eq!(
+        cfg,
+        McpServerConfig {
+            auth: Default::default(),
+            transport: McpServerTransportConfig::Stdio {
+                command: "echo".to_string(),
+                args: vec![],
+                env: None,
+                env_vars: Vec::new(),
+                cwd: None,
+            },
+            environment_id: crate::DEFAULT_MCP_SERVER_ENVIRONMENT_ID.to_string(),
+            enabled: true,
+            required: false,
+            supports_parallel_tool_calls: false,
+            omit_tools_from: None,
+            disabled_reason: None,
+            startup_timeout_sec: None,
+            tool_timeout_sec: None,
+            default_tools_approval_mode: None,
+            enabled_tools: None,
+            disabled_tools: None,
+            scopes: None,
+            oauth: None,
+            oauth_resource: None,
+            tools: HashMap::new(),
+        }
+    );
+}
+
+#[test]
+fn deserialize_rejects_command_and_url() {
+    toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            url = "https://example.com"
+        "#,
+    )
+    .expect_err("should reject command+url");
+}
+
+#[test]
+fn deserialize_rejects_env_for_http_transport() {
+    toml::from_str::<McpServerConfig>(
+        r#"
+            url = "https://example.com"
+            env = { "FOO" = "BAR" }
+        "#,
+    )
+    .expect_err("should reject env for http transport");
+}
+
+#[test]
+fn deserialize_rejects_headers_for_stdio() {
+    toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            http_headers = { "X-Foo" = "bar" }
+        "#,
+    )
+    .expect_err("should reject http_headers for stdio transport");
+
+    toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            env_http_headers = { "X-Foo" = "BAR_ENV" }
+        "#,
+    )
+    .expect_err("should reject env_http_headers for stdio transport");
+
+    let err = toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            oauth = { client_id = "eci-prd-pub-codex-123" }
+        "#,
+    )
+    .expect_err("should reject oauth for stdio transport");
+
+    assert!(
+        err.to_string().contains("oauth is not supported for stdio"),
+        "unexpected error: {err}"
+    );
+
+    let err = toml::from_str::<McpServerConfig>(
+        r#"
+            command = "echo"
+            oauth_resource = "https://api.example.com"
+        "#,
+    )
+    .expect_err("should reject oauth_resource for stdio transport");
+
+    assert!(
+        err.to_string()
+            .contains("oauth_resource is not supported for stdio"),
+        "unexpected error: {err}"
+    );
+}
+
+#[test]
+fn deserialize_rejects_inline_bearer_token_field() {
+    let err = toml::from_str::<McpServerConfig>(
+        r#"
+            url = "https://example.com"
+            bearer_token = "secret"
+        "#,
+    )
+    .expect_err("should reject bearer_token field");
+
+    assert!(
+        err.to_string().contains("bearer_token is not supported"),
+        "unexpected error: {err}"
+    );
+}

codex-rs/config/src/merge.rs

@@ -0,0 +1,236 @@
+use crate::key_aliases::normalize_key_aliases;
+use crate::key_aliases::normalized_with_key_aliases;
+use codex_network_proxy::normalize_host;
+use toml::Value as TomlValue;
+
+/// The mutually exclusive shell-environment filter representations.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ShellEnvironmentPolicyFilterRepresentation {
+    Filters,
+    Legacy,
+}
+
+impl ShellEnvironmentPolicyFilterRepresentation {
+    /// Returns the representation selected by a policy table, including empty fields.
+    pub fn from_policy(policy: &TomlValue) -> Option<Self> {
+        let policy = policy.as_table()?;
+        if policy.contains_key("filters") {
+            Some(Self::Filters)
+        } else if policy.contains_key("exclude") || policy.contains_key("include_only") {
+            Some(Self::Legacy)
+        } else {
+            None
+        }
+    }
+
+    /// Returns the representation addressed by a dotted config path.
+    pub fn from_path(path: &[String]) -> Option<Self> {
+        match path {
+            [policy, field, ..] if policy == "shell_environment_policy" => match field.as_str() {
+                "filters" => Some(Self::Filters),
+                "exclude" | "include_only" => Some(Self::Legacy),
+                _ => None,
+            },
+            _ => None,
+        }
+    }
+
+    /// Returns the representation selected by an edit at `path`.
+    pub fn from_edit(path: &[String], value: &TomlValue) -> Option<Self> {
+        if matches!(path, [policy] if policy == "shell_environment_policy") {
+            Self::from_policy(value)
+        } else {
+            Self::from_path(path)
+        }
+    }
+
+    /// Returns the policy fields that must be removed when this representation is selected.
+    pub fn displaced_fields(self) -> &'static [&'static str] {
+        match self {
+            Self::Filters => &["exclude", "include_only"],
+            Self::Legacy => &["filters"],
+        }
+    }
+}
+
+/// Merge config `overlay` into `base`, giving `overlay` precedence.
+pub fn merge_toml_values(base: &mut TomlValue, overlay: &TomlValue) {
+    merge_toml_values_at_path(base, overlay, &mut Vec::new());
+}
+
+pub fn is_structured_feature_path<S: AsRef<str>>(path: &[S]) -> bool {
+    let (features, feature) = match path {
+        [profiles, _, features, feature] if profiles.as_ref() == "profiles" => (features, feature),
+        [features, feature] => (features, feature),
+        _ => return false,
+    };
+
+    features.as_ref() == "features"
+        && matches!(
+            feature.as_ref(),
+            "multi_agent_v2" | "network_proxy" | "sleep_tool"
+        )
+}
+
+fn merge_toml_values_at_path(base: &mut TomlValue, overlay: &TomlValue, path: &mut Vec<String>) {
+    replace_shell_environment_policy_filter_representation(base, overlay, path);
+
+    if is_structured_feature_path(path) {
+        if let TomlValue::Boolean(enabled) = base
+            && overlay.is_table()
+        {
+            *base = TomlValue::Table(toml::map::Map::from_iter([(
+                "enabled".to_string(),
+                TomlValue::Boolean(*enabled),
+            )]));
+        } else if let TomlValue::Table(table) = base
+            && let TomlValue::Boolean(enabled) = overlay
+        {
+            table.insert("enabled".to_string(), TomlValue::Boolean(*enabled));
+            return;
+        }
+    }
+
+    if let TomlValue::Table(overlay_table) = overlay
+        && let TomlValue::Table(base_table) = base
+    {
+        normalize_key_aliases(path, base_table);
+        let mut overlay_table = overlay_table.clone();
+        normalize_key_aliases(path, &mut overlay_table);
+        if is_network_domains_path(path) {
+            normalize_network_domain_keys(base_table);
+            normalize_network_domain_keys(&mut overlay_table);
+        }
+        if is_shell_environment_filters_path(path) {
+            normalize_case_insensitive_keys(base_table);
+            normalize_case_insensitive_keys(&mut overlay_table);
+        }
+        if path.split_last().is_some_and(|(field, feature_path)| {
+            field == "credentials" && is_structured_feature_path(feature_path)
+        }) {
+            for (provider_id, provider) in &overlay_table {
+                let Some(overlay_sources) = provider.get("env").and_then(TomlValue::as_array)
+                else {
+                    continue;
+                };
+                base_table.retain(|existing_id, existing| {
+                    existing_id == provider_id
+                        || !overlay_table
+                            .get(existing_id)
+                            .and_then(|provider| provider.get("env"))
+                            .or_else(|| existing.get("env"))
+                            .and_then(TomlValue::as_array)
+                            .is_some_and(|existing_sources| {
+                                existing_sources.iter().filter_map(TomlValue::as_str).any(
+                                    |existing_source| {
+                                        overlay_sources.iter().filter_map(TomlValue::as_str).any(
+                                            |overlay_source| {
+                                                existing_source == overlay_source
+                                                    || cfg!(windows)
+                                                        && existing_source
+                                                            .eq_ignore_ascii_case(overlay_source)
+                                            },
+                                        )
+                                    },
+                                )
+                            })
+                });
+            }
+        }
+        for (key, value) in overlay_table {
+            path.push(key.clone());
+            if let Some(existing) = base_table.get_mut(&key) {
+                merge_toml_values_at_path(existing, &value, path);
+            } else {
+                base_table.insert(key, normalized_with_key_aliases(&value, path));
+            }
+            path.pop();
+        }
+    } else {
+        *base = normalized_with_key_aliases(overlay, path);
+    }
+}
+
+fn is_shell_environment_filters_path(path: &[String]) -> bool {
+    matches!(
+        path,
+        [policy, filters]
+            if policy == "shell_environment_policy" && filters == "filters"
+    )
+}
+
+/// Switching between legacy arrays and keyed filters replaces lower filter
+/// fields instead of attempting to reconcile the two representations. Legacy
+/// arrays already replace wholesale, so reconciling them would add merge
+/// semantics that the legacy representation never supported.
+fn replace_shell_environment_policy_filter_representation(
+    base: &mut TomlValue,
+    overlay: &TomlValue,
+    path: &[String],
+) {
+    if !matches!(path, [policy] if policy == "shell_environment_policy") {
+        return;
+    }
+    let Some(overlay_representation) =
+        ShellEnvironmentPolicyFilterRepresentation::from_policy(overlay)
+    else {
+        return;
+    };
+    let TomlValue::Table(base) = base else {
+        return;
+    };
+
+    for field in overlay_representation.displaced_fields() {
+        base.remove(*field);
+    }
+}
+
+/// Looks up a shell-environment filter pattern while ignoring case.
+pub fn shell_environment_filter_entry<'a>(
+    root: &'a TomlValue,
+    path: &[String],
+) -> Option<(&'a String, &'a TomlValue)> {
+    let [policy, filters, pattern] = path else {
+        return None;
+    };
+    if policy != "shell_environment_policy" || filters != "filters" {
+        return None;
+    }
+
+    let pattern = pattern.to_lowercase();
+    root.get(policy)?
+        .get(filters)?
+        .as_table()?
+        .iter()
+        .find(|(candidate, _)| candidate.to_lowercase() == pattern)
+}
+
+fn is_network_domains_path(path: &[String]) -> bool {
+    matches!(
+        path,
+        [permissions, _, network, domains]
+            if permissions == "permissions" && network == "network" && domains == "domains"
+    ) || matches!(
+        path,
+        [application, network, domains]
+            if application == "application" && network == "network" && domains == "domains"
+    )
+}
+
+fn normalize_network_domain_keys(table: &mut toml::map::Map<String, TomlValue>) {
+    let entries = std::mem::take(table);
+    for (pattern, value) in entries {
+        table.insert(normalize_host(&pattern), value);
+    }
+}
+
+fn normalize_case_insensitive_keys(table: &mut toml::map::Map<String, TomlValue>) {
+    let entries = std::mem::take(table);
+    for (key, value) in entries {
+        table.insert(key.to_lowercase(), value);
+    }
+}
+
+#[cfg(test)]
+#[path = "merge_tests.rs"]
+mod tests;

codex-rs/config/src/merge_tests.rs

@@ -0,0 +1,692 @@
+use super::*;
+use crate::config_toml::AgentsToml;
+use crate::config_toml::ConfigToml;
+use crate::types::MemoriesToml;
+use pretty_assertions::assert_eq;
+
+fn parse_toml(value: &str) -> TomlValue {
+    toml::from_str(value).expect("TOML should parse")
+}
+
+#[test]
+fn merge_toml_values_normalizes_legacy_key_from_base_layer() {
+    let mut base = parse_toml(
+        r#"
+[memories]
+no_memories_if_mcp_or_web_search = false
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[memories]
+disable_on_external_context = true
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    let expected = parse_toml(
+        r#"
+[memories]
+disable_on_external_context = true
+"#,
+    );
+    assert_eq!(base, expected);
+
+    let config: ConfigToml = base.try_into().expect("merged config should deserialize");
+    assert_eq!(
+        config.memories,
+        Some(MemoriesToml {
+            disable_on_external_context: Some(true),
+            ..Default::default()
+        })
+    );
+}
+
+#[test]
+fn merge_toml_values_normalizes_legacy_key_from_overlay_layer() {
+    let mut base = parse_toml(
+        r#"
+[memories]
+disable_on_external_context = false
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[memories]
+no_memories_if_mcp_or_web_search = true
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    let expected = parse_toml(
+        r#"
+[memories]
+disable_on_external_context = true
+"#,
+    );
+    assert_eq!(base, expected);
+
+    let config: ConfigToml = base.try_into().expect("merged config should deserialize");
+    assert_eq!(
+        config.memories,
+        Some(MemoriesToml {
+            disable_on_external_context: Some(true),
+            ..Default::default()
+        })
+    );
+}
+
+#[test]
+fn merge_toml_values_prefers_canonical_key_when_one_layer_has_both_names() {
+    let mut base = TomlValue::Table(toml::map::Map::new());
+    let overlay = parse_toml(
+        r#"
+[memories]
+disable_on_external_context = true
+no_memories_if_mcp_or_web_search = false
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    let expected = parse_toml(
+        r#"
+[memories]
+disable_on_external_context = true
+"#,
+    );
+    assert_eq!(base, expected);
+}
+
+#[test]
+fn merge_toml_values_normalizes_legacy_agents_key_across_layers() {
+    let mut base = parse_toml(
+        r#"
+[agents]
+max_threads = 4
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[agents]
+max_concurrent_threads_per_session = 7
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    let expected = parse_toml(
+        r#"
+[agents]
+max_concurrent_threads_per_session = 7
+"#,
+    );
+    assert_eq!(base, expected);
+
+    let config: ConfigToml = base.try_into().expect("merged config should deserialize");
+    assert_eq!(
+        config.agents,
+        Some(AgentsToml {
+            max_concurrent_threads_per_session: Some(7),
+            ..Default::default()
+        })
+    );
+}
+
+#[test]
+fn merge_toml_values_normalizes_legacy_agents_key_from_overlay() {
+    let mut base = parse_toml(
+        r#"
+[agents]
+max_concurrent_threads_per_session = 4
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[agents]
+max_threads = 7
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    let expected = parse_toml(
+        r#"
+[agents]
+max_concurrent_threads_per_session = 7
+"#,
+    );
+    assert_eq!(base, expected);
+}
+
+/// Feature tables added above legacy toggles retain the lower layer's enabled state.
+#[test]
+fn merge_multi_agent_v2_table_preserves_legacy_boolean_toggle() {
+    for feature_path in ["features", "profiles.work.features"] {
+        let mut base = parse_toml(&format!("[{feature_path}]\nmulti_agent_v2 = true\n"));
+        let overlay = parse_toml(&format!(
+            "[{feature_path}.multi_agent_v2]\nsubagent_usage_hint_text = \"Delegate carefully.\"\n",
+        ));
+
+        merge_toml_values(&mut base, &overlay);
+
+        assert_eq!(
+            base,
+            parse_toml(&format!(
+                "[{feature_path}.multi_agent_v2]\nenabled = true\nsubagent_usage_hint_text = \"Delegate carefully.\"\n",
+            ))
+        );
+    }
+}
+
+/// Legacy feature toggles update enabled state without discarding nested configuration.
+#[test]
+fn merge_multi_agent_v2_boolean_preserves_existing_feature_table() {
+    for feature_path in ["features", "profiles.work.features"] {
+        let mut base = parse_toml(&format!(
+            "[{feature_path}.multi_agent_v2]\nenabled = true\nsubagent_usage_hint_text = \"Delegate carefully.\"\n",
+        ));
+        let overlay = parse_toml(&format!("[{feature_path}]\nmulti_agent_v2 = false\n"));
+
+        merge_toml_values(&mut base, &overlay);
+
+        assert_eq!(
+            base,
+            parse_toml(&format!(
+                "[{feature_path}.multi_agent_v2]\nenabled = false\nsubagent_usage_hint_text = \"Delegate carefully.\"\n",
+            ))
+        );
+    }
+}
+
+/// Opaque desktop settings retain ordinary scalar/table replacement semantics.
+#[test]
+fn merge_multi_agent_v2_compatibility_excludes_opaque_desktop_paths() {
+    let cases = [
+        (
+            "[desktop.features.multi_agent_v2]\nenabled = true\n",
+            "[desktop.features]\nmulti_agent_v2 = false\n",
+            "[desktop.features]\nmulti_agent_v2 = false\n",
+        ),
+        (
+            "[desktop.features]\nmulti_agent_v2 = true\n",
+            "[desktop.features.multi_agent_v2]\ncustom = true\n",
+            "[desktop.features.multi_agent_v2]\ncustom = true\n",
+        ),
+    ];
+
+    for (base, overlay, expected) in cases {
+        let mut base = parse_toml(base);
+        merge_toml_values(&mut base, &parse_toml(overlay));
+        assert_eq!(base, parse_toml(expected));
+    }
+}
+
+/// CLI overrides preserve the multi-agent toggle and nested options in either ordering.
+#[test]
+fn multi_agent_v2_cli_overrides_preserve_boolean_and_nested_configuration() {
+    for feature_path in ["features", "profiles.work.features"] {
+        let instructions = (
+            format!("{feature_path}.multi_agent_v2.subagent_usage_hint_text"),
+            TomlValue::String("Delegate carefully.".to_string()),
+        );
+        let enabled = (
+            format!("{feature_path}.multi_agent_v2"),
+            TomlValue::Boolean(true),
+        );
+        let feature_table = (
+            format!("{feature_path}.multi_agent_v2"),
+            parse_toml("subagent_usage_hint_text = \"Delegate carefully.\"\n"),
+        );
+        let expected = parse_toml(&format!(
+            "[{feature_path}.multi_agent_v2]\nenabled = true\nsubagent_usage_hint_text = \"Delegate carefully.\"\n",
+        ));
+
+        for overrides in [
+            vec![enabled.clone(), instructions.clone()],
+            vec![instructions, enabled.clone()],
+            vec![enabled.clone(), feature_table.clone()],
+            vec![feature_table, enabled],
+        ] {
+            assert_eq!(crate::build_cli_overrides_layer(&overrides), expected);
+        }
+    }
+}
+
+#[test]
+fn sleep_tool_overrides_preserve_disabled_state_and_mode() {
+    for feature_path in ["features", "profiles.work.features"] {
+        let disabled = (
+            format!("{feature_path}.sleep_tool"),
+            TomlValue::Boolean(false),
+        );
+        let mode = (
+            format!("{feature_path}.sleep_tool.mode"),
+            TomlValue::String("always_on".to_string()),
+        );
+        let expected = parse_toml(&format!(
+            "[{feature_path}.sleep_tool]\nenabled = false\nmode = \"always_on\"\n",
+        ));
+        for overrides in [vec![disabled.clone(), mode.clone()], vec![mode, disabled]] {
+            assert_eq!(crate::build_cli_overrides_layer(&overrides), expected);
+        }
+
+        let boolean_layer = parse_toml(&format!("[{feature_path}]\nsleep_tool = false\n"));
+        let table_layer = parse_toml(&format!(
+            "[{feature_path}.sleep_tool]\nmode = \"always_on\"\n",
+        ));
+        for (mut base, overlay) in [
+            (boolean_layer.clone(), table_layer.clone()),
+            (table_layer, boolean_layer),
+        ] {
+            merge_toml_values(&mut base, &overlay);
+            assert_eq!(base, expected);
+        }
+    }
+}
+
+#[test]
+fn network_proxy_feature_overrides_preserve_credential_broker_configuration() {
+    let enabled = (
+        "features.network_proxy".to_string(),
+        TomlValue::Boolean(true),
+    );
+    let broker = (
+        "features.network_proxy.credential_broker".to_string(),
+        TomlValue::Boolean(true),
+    );
+    let expected =
+        parse_toml("[features.network_proxy]\nenabled = true\ncredential_broker = true\n");
+
+    for overrides in [vec![enabled.clone(), broker.clone()], vec![broker, enabled]] {
+        assert_eq!(crate::build_cli_overrides_layer(&overrides), expected);
+    }
+
+    let mut base = parse_toml("[features]\nnetwork_proxy = true\n");
+    merge_toml_values(
+        &mut base,
+        &parse_toml("[features.network_proxy]\ncredential_broker = true\n"),
+    );
+    assert_eq!(base, expected);
+}
+
+#[test]
+fn higher_priority_credential_provider_replaces_overlapping_sources() {
+    for (feature_path, base_source, overlay_source, keep_default) in [
+        ("features", "VENDOR_TOKEN", "VENDOR_TOKEN", false),
+        (
+            "profiles.work.features",
+            "VENDOR_TOKEN",
+            "VENDOR_TOKEN",
+            false,
+        ),
+        ("features", "vendor_token", "VENDOR_TOKEN", !cfg!(windows)),
+    ] {
+        let default_provider = format!(
+            "[{feature_path}.network_proxy.credentials.default]\n\
+             env = ['{base_source}']\n\
+             url_prefixes = ['https://default.example']\n"
+        );
+        let shared_provider = format!(
+            "[{feature_path}.network_proxy.credentials.shared]\n\
+             env = ['SHARED_TOKEN']\n\
+             patterns = ['shared_[a-z]+']\n"
+        );
+        let mut base = parse_toml(&format!("{default_provider}\n{shared_provider}"));
+        let overlay = parse_toml(&format!(
+            "[{feature_path}.network_proxy.credentials.override]\n\
+             env = ['{overlay_source}']\n\
+             url_prefixes = ['https://override.example']\n\
+             [{feature_path}.network_proxy.credentials.shared]\n\
+             url_prefixes = ['https://shared.example']\n"
+        ));
+
+        merge_toml_values(&mut base, &overlay);
+
+        let retained_default = if keep_default { &default_provider } else { "" };
+        let expected = parse_toml(&format!(
+            "{retained_default}\n\
+             [{feature_path}.network_proxy.credentials.override]\n\
+             env = ['{overlay_source}']\n\
+             url_prefixes = ['https://override.example']\n\
+             [{feature_path}.network_proxy.credentials.shared]\n\
+             env = ['SHARED_TOKEN']\n\
+             patterns = ['shared_[a-z]+']\n\
+             url_prefixes = ['https://shared.example']\n"
+        ));
+        assert_eq!(base, expected, "feature path: {feature_path}");
+    }
+}
+
+#[test]
+fn credential_provider_remapping_preserves_inherited_settings() {
+    let base = parse_toml(
+        r#"
+[features.network_proxy.credentials.a]
+env = ["OLD_AUTH"]
+patterns = ["acme_[a-z]{24}"]
+url_prefixes = ["https://a.example"]
+auth = ["token"]
+[features.network_proxy.credentials.b]
+env = ["OTHER_AUTH"]
+patterns = ["other_[a-z]{24}"]
+url_prefixes = ["https://b.example"]
+auth = ["bearer"]
+"#,
+    );
+
+    for new_a in ["NEW_AUTH", "OTHER_AUTH"] {
+        let mut merged = base.clone();
+        let mut expected = base.clone();
+        let providers = &mut expected["features"]["network_proxy"]["credentials"];
+        providers["a"]["env"] = TomlValue::Array(vec![new_a.into()]);
+        providers["b"]["env"] = TomlValue::Array(vec!["OLD_AUTH".into()]);
+        let overlay = parse_toml(&format!(
+            "[features.network_proxy.credentials.a]\n\
+             env = ['{new_a}']\n\
+             [features.network_proxy.credentials.b]\n\
+             env = ['OLD_AUTH']\n"
+        ));
+
+        merge_toml_values(&mut merged, &overlay);
+
+        assert_eq!(merged, expected);
+    }
+}
+
+/// Repeated opaque desktop overrides continue to replace their previous value.
+#[test]
+fn multi_agent_v2_cli_compatibility_excludes_opaque_desktop_paths() {
+    let path = "desktop.features.multi_agent_v2".to_string();
+    let enabled = (path.clone(), TomlValue::Boolean(true));
+    let feature_table = (path, parse_toml("custom = true\n"));
+
+    assert_eq!(
+        crate::build_cli_overrides_layer(&[enabled.clone(), feature_table.clone()]),
+        parse_toml("[desktop.features.multi_agent_v2]\ncustom = true\n")
+    );
+    assert_eq!(
+        crate::build_cli_overrides_layer(&[feature_table, enabled]),
+        parse_toml("[desktop.features]\nmulti_agent_v2 = true\n")
+    );
+}
+
+#[test]
+fn merge_toml_values_normalizes_permission_network_domains_before_overlaying() {
+    let mut base = parse_toml(
+        r#"
+[permissions.dev.network.domains]
+"example.com" = "deny"
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[permissions.dev.network.domains]
+"EXAMPLE.COM" = "allow"
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    let expected = parse_toml(
+        r#"
+[permissions.dev.network.domains]
+"example.com" = "allow"
+"#,
+    );
+    assert_eq!(base, expected);
+}
+
+#[test]
+fn shell_environment_policy_legacy_array_overlay_replaces_legacy_array() {
+    let mut base = parse_toml(
+        r#"
+[shell_environment_policy]
+exclude = ["LOW_*", "SHARED_*"]
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[shell_environment_policy]
+exclude = ["HIGH_*"]
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    assert_eq!(base, overlay);
+}
+
+#[test]
+fn shell_environment_policy_set_overlay_preserves_case_distinct_keys() {
+    let mut base = parse_toml(
+        r#"
+[features.network_proxy.credentials.stripe]
+env = ["STRIPE_API_KEY"]
+patterns = ["stripe_[a-z]+"]
+url_prefix_from_env = "STRIPE_HOST"
+
+[shell_environment_policy.set]
+stripe_api_key = "stale"
+stripe_host = "stale.example"
+foo = "lowercase"
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[shell_environment_policy.set]
+STRIPE_API_KEY = "trusted"
+STRIPE_HOST = "trusted.example"
+FOO = "uppercase"
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    let values = base["shell_environment_policy"]["set"]
+        .as_table()
+        .expect("shell environment overrides");
+    assert_eq!(
+        values.get("foo").and_then(TomlValue::as_str),
+        Some("lowercase")
+    );
+    assert_eq!(
+        values.get("FOO").and_then(TomlValue::as_str),
+        Some("uppercase")
+    );
+    assert_eq!(values.len(), 6);
+}
+
+#[test]
+fn later_credential_provider_preserves_case_distinct_environment_overrides() {
+    let mut base = parse_toml(
+        "[shell_environment_policy.set]\n\
+         stripe_api_key = 'stale'\n\
+         stripe_host = 'stale.example'",
+    );
+    let override_layer = parse_toml(
+        "[shell_environment_policy.set]\n\
+         STRIPE_API_KEY = 'previous'\n\
+         STRIPE_HOST = 'previous.example'",
+    );
+    let final_override_layer = parse_toml(
+        "[shell_environment_policy.set]\n\
+         stripe_api_key = 'trusted'\n\
+         stripe_host = 'current.example'",
+    );
+    let provider_layer = parse_toml(
+        "[features.network_proxy.credentials.stripe]\n\
+         env = ['STRIPE_API_KEY']\n\
+         url_prefix_from_env = 'STRIPE_HOST'",
+    );
+
+    merge_toml_values(&mut base, &override_layer);
+    merge_toml_values(&mut base, &final_override_layer);
+    merge_toml_values(&mut base, &provider_layer);
+
+    assert_eq!(
+        base["shell_environment_policy"]["set"],
+        parse_toml(
+            "stripe_api_key = 'trusted'\n\
+             stripe_host = 'current.example'\n\
+             STRIPE_API_KEY = 'previous'\n\
+             STRIPE_HOST = 'previous.example'",
+        )
+    );
+}
+
+#[test]
+fn shell_environment_policy_filters_overlay_merges_by_key_case_insensitively() {
+    let mut base = parse_toml(
+        r#"
+[shell_environment_policy.filters]
+"FLIP_*" = "exclude"
+"KEEP_*" = "include"
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[shell_environment_policy.filters]
+"ADD_*" = "exclude"
+"flip_*" = "include"
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    assert_eq!(
+        base,
+        parse_toml(
+            r#"
+[shell_environment_policy.filters]
+"add_*" = "exclude"
+"flip_*" = "include"
+"keep_*" = "include"
+"#,
+        )
+    );
+}
+
+#[test]
+fn shell_environment_policy_filters_overlay_merges_unicode_keys_case_insensitively() {
+    let mut base = parse_toml(
+        r#"
+[shell_environment_policy.filters]
+"СЕКРЕТ_*" = "exclude"
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[shell_environment_policy.filters]
+"секрет_*" = "include"
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    assert_eq!(base, overlay);
+}
+
+#[test]
+fn shell_environment_policy_filters_replace_lower_legacy_filter_fields() {
+    let mut base = parse_toml(
+        r#"
+[shell_environment_policy]
+inherit = "core"
+exclude = ["FLIP_TO_INCLUDE", "KEEP_EXCLUDED"]
+include_only = ["FLIP_TO_EXCLUDE", "KEEP_INCLUDED"]
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[shell_environment_policy.filters]
+"ADD_INCLUDED" = "include"
+"FLIP_TO_EXCLUDE" = "exclude"
+"FLIP_TO_INCLUDE" = "include"
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    assert_eq!(
+        base,
+        parse_toml(
+            r#"
+[shell_environment_policy]
+inherit = "core"
+
+[shell_environment_policy.filters]
+"ADD_INCLUDED" = "include"
+"FLIP_TO_EXCLUDE" = "exclude"
+"FLIP_TO_INCLUDE" = "include"
+"#,
+        )
+    );
+}
+
+#[test]
+fn shell_environment_policy_legacy_arrays_replace_lower_filters() {
+    let mut base = parse_toml(
+        r#"
+[shell_environment_policy]
+inherit = "core"
+
+[shell_environment_policy.filters]
+"FLIP_TO_EXCLUDE" = "include"
+"LOW_EXCLUDED" = "exclude"
+"KEEP_INCLUDED" = "include"
+"#,
+    );
+    let overlay = parse_toml(
+        r#"
+[shell_environment_policy]
+exclude = ["FLIP_TO_EXCLUDE", "HIGH_EXCLUDED"]
+"#,
+    );
+
+    merge_toml_values(&mut base, &overlay);
+
+    assert_eq!(
+        base,
+        parse_toml(
+            r#"
+[shell_environment_policy]
+inherit = "core"
+exclude = ["FLIP_TO_EXCLUDE", "HIGH_EXCLUDED"]
+"#,
+        )
+    );
+}
+
+#[test]
+fn empty_shell_environment_filter_representations_replace_the_other_form() {
+    let cases = [
+        (
+            r#"[shell_environment_policy]
+exclude = ["AWS_*"]
+include_only = ["PATH"]
+"#,
+            r#"[shell_environment_policy.filters]
+"#,
+        ),
+        (
+            r#"[shell_environment_policy.filters]
+"AWS_*" = "include"
+"#,
+            r#"[shell_environment_policy]
+exclude = []
+"#,
+        ),
+    ];
+
+    for (base, overlay) in cases {
+        let mut base = parse_toml(base);
+        let overlay = parse_toml(overlay);
+
+        merge_toml_values(&mut base, &overlay);
+
+        assert_eq!(base, overlay);
+    }
+}

codex-rs/config/src/model_provider_requirements_tests.rs

@@ -0,0 +1,99 @@
+//! Tests exact provider requirements across layers and config projections.
+
+use crate::ConfigLayerEntry;
+use crate::ConfigLayerSource;
+use crate::ConfigLayerStack;
+use crate::ConfigRequirements;
+use crate::ConfigRequirementsToml;
+use crate::RequirementSource;
+use crate::RequirementsLayerEntry;
+use crate::compose_requirements;
+use pretty_assertions::assert_eq;
+
+const REQUIRED: &str = r#"
+model_provider = "gateway"
+[model_providers.gateway]
+name = "Managed gateway"
+base_url = "https://gateway.example.test/v1"
+requires_openai_auth = true
+[model_providers.gateway.http_headers]
+X-Managed = "yes"
+"#;
+
+#[test]
+fn higher_requirements_merge_provider_fields_and_nested_tables() -> anyhow::Result<()> {
+    let cloud_source = RequirementSource::EnterpriseManaged {
+        id: "req_1".into(),
+        name: "Gateway".into(),
+    };
+    let requirements = compose_requirements([
+        RequirementsLayerEntry::from_toml(
+            RequirementSource::Unknown,
+            r#"
+model_provider = "other"
+[model_providers.gateway]
+name = "System gateway"
+base_url = "https://old.example.test"
+env_key = "OLD_KEY"
+supports_websockets = true
+[model_providers.gateway.http_headers]
+X-Old = "no"
+X-Managed = "old"
+[model_providers.other]
+name = "Other provider"
+"#,
+        ),
+        RequirementsLayerEntry::from_toml(cloud_source.clone(), REQUIRED),
+    ])?
+    .expect("provider requirements must not be discarded");
+    let normalized = ConfigRequirements::try_from(requirements.clone())?;
+    assert_eq!(
+        normalized
+            .model_provider
+            .as_ref()
+            .map(|requirement| &requirement.source),
+        Some(&cloud_source)
+    );
+    let requirements = requirements.into_toml();
+    let expected: ConfigRequirementsToml = toml::from_str(
+        r#"
+model_provider = "gateway"
+[model_providers.gateway]
+name = "Managed gateway"
+base_url = "https://gateway.example.test/v1"
+requires_openai_auth = true
+env_key = "OLD_KEY"
+supports_websockets = true
+[model_providers.gateway.http_headers]
+X-Managed = "yes"
+X-Old = "no"
+[model_providers.other]
+name = "Other provider"
+"#,
+    )?;
+    assert_eq!(requirements, expected);
+    assert_eq!(
+        normalized
+            .model_providers
+            .map(|requirement| requirement.value),
+        requirements.model_providers
+    );
+    Ok(())
+}
+
+#[test]
+fn required_provider_definitions_are_validated_without_local_defaults() -> anyhow::Result<()> {
+    for invalid in [
+        "[model_providers.gateway]\nbase_url = 'https://example.test'",
+        "[model_providers.openai]\nname = 'Reserved'",
+        "[model_providers.gateway]\nname = 'Gateway'\n[model_providers.gateway.aws]\nregion = 'us-east-1'",
+    ] {
+        let requirements = toml::from_str(invalid)?;
+        let local =
+            ConfigLayerEntry::new(ConfigLayerSource::SessionFlags, toml::from_str(REQUIRED)?);
+        let error = ConfigLayerStack::new(vec![local], ConfigRequirements::default(), requirements)
+            .expect_err("local config cannot repair an invalid required provider");
+        assert_eq!(error.kind(), std::io::ErrorKind::InvalidData);
+    }
+    Ok(())
+}

codex-rs/config/src/overrides.rs

@@ -0,0 +1,99 @@
+use crate::merge::is_structured_feature_path;
+use crate::merge::merge_toml_values;
+use toml::Value as TomlValue;
+
+pub(crate) fn default_empty_table() -> TomlValue {
+    TomlValue::Table(Default::default())
+}
+
+pub fn build_cli_overrides_layer(cli_overrides: &[(String, TomlValue)]) -> TomlValue {
+    let mut root = default_empty_table();
+    for (path, value) in cli_overrides {
+        apply_toml_override(&mut root, path, value.clone());
+    }
+    root
+}
+
+/// Apply a single dotted-path override onto a TOML value.
+fn apply_toml_override(root: &mut TomlValue, path: &str, value: TomlValue) {
+    use toml::value::Table;
+
+    let mut current = root;
+    let mut segments_iter = path.split('.').peekable();
+    let mut traversed_segments = Vec::new();
+
+    while let Some(segment) = segments_iter.next() {
+        traversed_segments.push(segment);
+        let is_last = segments_iter.peek().is_none();
+
+        if is_last {
+            match current {
+                TomlValue::Table(table) => {
+                    if is_structured_feature_path(&traversed_segments)
+                        && let Some(existing) = table.get_mut(segment)
+                    {
+                        match (&mut *existing, &value) {
+                            (TomlValue::Table(feature), TomlValue::Boolean(enabled)) => {
+                                feature.insert("enabled".to_string(), TomlValue::Boolean(*enabled));
+                                return;
+                            }
+                            (TomlValue::Boolean(enabled), TomlValue::Table(_)) => {
+                                *existing = TomlValue::Table(Table::from_iter([(
+                                    "enabled".to_string(),
+                                    TomlValue::Boolean(*enabled),
+                                )]));
+                                merge_toml_values(existing, &value);
+                                return;
+                            }
+                            (TomlValue::Table(_), TomlValue::Table(_)) => {
+                                merge_toml_values(existing, &value);
+                                return;
+                            }
+                            (
+                                TomlValue::String(_)
+                                | TomlValue::Integer(_)
+                                | TomlValue::Float(_)
+                                | TomlValue::Boolean(_)
+                                | TomlValue::Datetime(_)
+                                | TomlValue::Array(_)
+                                | TomlValue::Table(_),
+                                _,
+                            ) => {}
+                        }
+                    }
+                    table.insert(segment.to_string(), value);
+                }
+                _ => {
+                    let mut table = Table::new();
+                    table.insert(segment.to_string(), value);
+                    *current = TomlValue::Table(table);
+                }
+            }
+            return;
+        }
+
+        match current {
+            TomlValue::Table(table) => {
+                current = table
+                    .entry(segment.to_string())
+                    .or_insert_with(|| TomlValue::Table(Table::new()));
+                if is_structured_feature_path(&traversed_segments)
+                    && let TomlValue::Boolean(enabled) = current
+                {
+                    *current = TomlValue::Table(Table::from_iter([(
+                        "enabled".to_string(),
+                        TomlValue::Boolean(*enabled),
+                    )]));
+                }
+            }
+            _ => {
+                *current = TomlValue::Table(Table::new());
+                if let TomlValue::Table(tbl) = current {
+                    current = tbl
+                        .entry(segment.to_string())
+                        .or_insert_with(|| TomlValue::Table(Table::new()));
+                }
+            }
+        }
+    }
+}

codex-rs/config/src/path_context.rs

@@ -0,0 +1,115 @@
+//! Path facts for configuration parsing. Native callers and callers resolving
+//! another platform use the same resolver after fact capture.
+
+use codex_utils_absolute_path::AbsolutePathBufGuard;
+use codex_utils_path_uri::LegacyAppPathStringError;
+use codex_utils_path_uri::PathConvention;
+use codex_utils_path_uri::PathUri;
+use std::cell::RefCell;
+
+/// The owning environment's path convention, base directory, and home for configuration.
+#[derive(Clone, Debug)]
+pub struct ConfigPathContext {
+    convention: PathConvention,
+    base_dir: Option<PathUri>,
+    user_home_dir: Option<PathUri>,
+}
+
+impl ConfigPathContext {
+    /// Supplies the grammar and directories of the environment owning the layer.
+    /// Relative paths require a base; home-relative paths require a home directory.
+    pub fn new(
+        convention: PathConvention,
+        base_dir: Option<PathUri>,
+        user_home_dir: Option<PathUri>,
+    ) -> Self {
+        Self {
+            convention,
+            base_dir,
+            user_home_dir,
+        }
+    }
+
+    /// Returns the path grammar supplied by the owning environment.
+    pub fn convention(&self) -> PathConvention {
+        self.convention
+    }
+
+    /// Resolves configuration text to a URI using the supplied directory and home facts.
+    pub fn resolve_path(&self, input: &str) -> Result<PathUri, LegacyAppPathStringError> {
+        PathUri::resolve_config_path_uri(
+            input,
+            self.convention,
+            self.base_dir.as_ref(),
+            self.user_home_dir.as_ref(),
+        )
+    }
+
+    /// Resolves against a supplied base using this context's grammar and home.
+    pub fn resolve_against(
+        &self,
+        input: &str,
+        base: &PathUri,
+    ) -> Result<PathUri, LegacyAppPathStringError> {
+        PathUri::resolve_config_path_uri(
+            input,
+            self.convention,
+            Some(base),
+            self.user_home_dir.as_ref(),
+        )
+    }
+
+    pub(crate) fn enter(&self) -> PathContextGuard {
+        PathContextGuard(PATH_CONTEXT.with(|current| current.replace(Some(self.clone()))))
+    }
+}
+
+thread_local! {
+    static PATH_CONTEXT: RefCell<Option<ConfigPathContext>> = const { RefCell::new(None) };
+}
+
+pub(crate) struct PathContextGuard(Option<ConfigPathContext>);
+
+impl Drop for PathContextGuard {
+    fn drop(&mut self) {
+        PATH_CONTEXT.with(|current| *current.borrow_mut() = self.0.take());
+    }
+}
+
+pub(crate) fn convention() -> PathConvention {
+    PATH_CONTEXT.with(|current| {
+        current
+            .borrow()
+            .as_ref()
+            .map_or_else(PathConvention::native, |context| context.convention)
+    })
+}
+
+pub(crate) fn resolve(input: &str) -> Result<String, String> {
+    let context = match PATH_CONTEXT.with(|current| current.borrow().clone()) {
+        Some(context) => context,
+        None => {
+            let convention = PathConvention::native();
+            let base = AbsolutePathBufGuard::deserialization_base(std::path::Path::new(input))
+                .map_err(str::to_owned)?
+                .map(PathUri::from_host_native_path)
+                .transpose()
+                .map_err(|error| error.to_string())?;
+            let home = convention
+                .home_relative_suffix(input)
+                .and_then(|_| AbsolutePathBufGuard::home_directory())
+                .map(PathUri::from_host_native_path)
+                .transpose()
+                .map_err(|error| error.to_string())?;
+            ConfigPathContext::new(convention, base, home)
+        }
+    };
+    context
+        .resolve_path(input)
+        .and_then(|path| path.to_config_path_string(context.convention()))
+        .map_err(|error| error.to_string())
+}
+
+#[cfg(test)]
+#[path = "path_context_tests.rs"]
+mod tests;

codex-rs/config/src/path_context_tests.rs

@@ -0,0 +1,255 @@
+//! Contracts for layer-owned denial facts, parser scoping, and policy conversion.
+
+use super::ConfigPathContext;
+use crate::FilesystemConstraints;
+use crate::FilesystemDenyReadPattern;
+use crate::RequirementSource;
+use crate::RequirementsLayerEntry;
+use crate::compose_requirements_for_hostname;
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxKind;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_utils_absolute_path::AbsolutePathBufGuard;
+use codex_utils_path_uri::PathConvention;
+use codex_utils_path_uri::PathUri;
+use pretty_assertions::assert_eq;
+use tempfile::tempdir;
+
+#[test]
+fn composition_applies_each_layers_base_and_home_to_policy() {
+    let native_home = tempdir().expect("native home");
+    let first = RequirementsLayerEntry::from_toml(
+        RequirementSource::Unknown,
+        "[permissions.filesystem]\ndeny_read = ['private', '~/secret', 'private', 'C:\\', '\\\\server\\share\\', 'private/*.key']",
+    )
+    .with_path_context(ConfigPathContext::new(
+        PathConvention::Windows,
+        Some(PathUri::parse("file:///C:/first").expect("first base")),
+        Some(PathUri::parse("file:///C:/Users/first").expect("first home")),
+    ));
+    let second = RequirementsLayerEntry::from_toml_value(
+        RequirementSource::Unknown,
+        toml::toml! { [permissions.filesystem] deny_read = ["private", "~/secret"] }.into(),
+    )
+    .with_path_context(ConfigPathContext::new(
+        PathConvention::Windows,
+        Some(PathUri::parse("file:///D:/second").expect("second base")),
+        Some(PathUri::parse("file:///D:/Users/second").expect("second home")),
+    ));
+    let composed = AbsolutePathBufGuard::with_home_directory(native_home.path(), || {
+        compose_requirements_for_hostname([first, second], /*hostname*/ None)
+            .expect("compose layers")
+            .expect("requirements present")
+    });
+    let constraints = FilesystemConstraints::from(composed.permissions.expect("permissions").value);
+    let mut expected = FileSystemSandboxPolicy {
+        kind: FileSystemSandboxKind::Restricted,
+        glob_scan_max_depth: Some(7),
+        entries: vec![FileSystemSandboxEntry::new(
+            PathUri::parse("file:///C:/allowed")
+                .expect("existing path")
+                .into(),
+            FileSystemAccessMode::Write,
+        )],
+    };
+    let mut policy = expected.clone();
+    expected.entries.extend(
+        [
+            "file:///D:/second/private",
+            "file:///D:/Users/second/secret",
+            "file:///C:/first/private",
+            "file:///C:/Users/first/secret",
+            "file:///C:/",
+            "file://server/share",
+        ]
+        .map(|path| {
+            FileSystemSandboxEntry::new(
+                PathUri::parse(path).expect("expected denial").into(),
+                FileSystemAccessMode::Deny,
+            )
+        }),
+    );
+    expected.entries.push(FileSystemSandboxEntry::new(
+        FileSystemPath::GlobPattern {
+            pattern: r"C:\first\private/*.key".to_string(),
+        },
+        FileSystemAccessMode::Deny,
+    ));
+    constraints
+        .apply_to_policy(&mut policy, PathConvention::Windows)
+        .expect("apply denials");
+    constraints
+        .apply_to_policy(&mut policy, PathConvention::Windows)
+        .expect("deduplicate existing denials");
+    assert_eq!(policy, expected);
+    assert!(
+        constraints
+            .apply_to_policy(&mut policy, PathConvention::Posix)
+            .is_err(),
+        "a foreign denial cannot be reinterpreted using the host convention",
+    );
+    assert_eq!(policy, expected);
+}
+
+#[test]
+fn common_parser_uses_supplied_windows_drive_and_glob_separators() {
+    let context = ConfigPathContext::new(
+        PathConvention::Windows,
+        Some(PathUri::parse("file:///C:/base/cwd").expect("base")),
+        /*user_home_dir*/ None,
+    );
+    let _guard = context.enter();
+    for (input, expected) in [
+        (r"C:private\*.key", r"C:\base\cwd\private/*.key"),
+        (r"D:\*.key", r"D:\/*.key"),
+        (r"\private\*.key", r"C:\private/*.key"),
+    ] {
+        assert_eq!(
+            FilesystemDenyReadPattern::from_input(input)
+                .expect("resolve pattern")
+                .as_str(),
+            expected,
+        );
+    }
+}
+
+#[test]
+fn windows_denial_globs_reject_ambiguous_roots_and_streams() {
+    let context = ConfigPathContext::new(
+        PathConvention::Windows,
+        Some(PathUri::parse("file://server/share/base").expect("UNC base")),
+        /*user_home_dir*/ None,
+    );
+    let _guard = context.enter();
+    for input in [
+        r"\\?\C:\private",
+        r"\\*\share\private",
+        r"D:*.key",
+        r"private\*\file:stream",
+    ] {
+        assert!(
+            FilesystemDenyReadPattern::from_input(input).is_err(),
+            "{input}"
+        );
+    }
+}
+
+#[test]
+fn failed_nested_composition_restores_outer_context_and_then_native_resolution() {
+    let base = tempdir().expect("native base");
+    let _native_guard = AbsolutePathBufGuard::new(base.path());
+    let native = FilesystemDenyReadPattern::from_input("private");
+    {
+        let outer = ConfigPathContext::new(
+            PathConvention::Posix,
+            Some(PathUri::parse("file:///outer").expect("outer base")),
+            /*user_home_dir*/ None,
+        );
+        let _outer_guard = outer.enter();
+        let inner = RequirementsLayerEntry::from_toml(
+            RequirementSource::Unknown,
+            "[permissions.filesystem]\ndeny_read = ['relative']",
+        )
+        .with_path_context(ConfigPathContext::new(
+            PathConvention::Windows,
+            /*base_dir*/ None,
+            /*user_home_dir*/ None,
+        ));
+        assert!(compose_requirements_for_hostname([inner], /*hostname*/ None).is_err());
+        assert_eq!(
+            FilesystemDenyReadPattern::from_input("private")
+                .expect("outer context restored")
+                .as_str(),
+            "/outer/private",
+        );
+    }
+    assert_eq!(FilesystemDenyReadPattern::from_input("private"), native);
+}
+
+#[test]
+fn native_guard_and_supplied_native_facts_use_the_same_parser() {
+    let base = tempdir().expect("base");
+    let home = tempdir().expect("home");
+    let _base_guard = AbsolutePathBufGuard::new(base.path());
+    AbsolutePathBufGuard::with_home_directory(home.path(), || {
+        let inputs = ["./private", "~/secret/*.txt"];
+        let native = inputs.map(FilesystemDenyReadPattern::from_input);
+        let context = ConfigPathContext::new(
+            PathConvention::native(),
+            Some(PathUri::from_host_native_path(base.path()).expect("native base URI")),
+            Some(PathUri::from_host_native_path(home.path()).expect("native home URI")),
+        );
+        let _context_guard = context.enter();
+        assert_eq!(inputs.map(FilesystemDenyReadPattern::from_input), native);
+    });
+}
+
+#[test]
+fn missing_supplied_home_does_not_fall_back_to_native_home() {
+    let home = tempdir().expect("native home");
+    let layer = RequirementsLayerEntry::from_toml(
+        RequirementSource::Unknown,
+        "[permissions.filesystem]\ndeny_read = ['~/secret']",
+    )
+    .with_path_context(ConfigPathContext::new(
+        PathConvention::Windows,
+        Some(PathUri::parse("file:///C:/base").expect("base")),
+        /*user_home_dir*/ None,
+    ));
+    AbsolutePathBufGuard::with_home_directory(home.path(), || {
+        assert!(compose_requirements_for_hostname([layer], /*hostname*/ None).is_err());
+    });
+}
+
+#[test]
+fn denial_resolution_rejects_glob_syntax_in_supplied_facts() {
+    for directory in ["file:///home/sam[1]", "file:///C:/Users/sam[1]"] {
+        let directory = PathUri::parse(directory).unwrap();
+        let context = ConfigPathContext::new(
+            directory.infer_path_convention().unwrap(),
+            Some(directory.clone()),
+            Some(directory),
+        );
+        // Literal denials also reject metacharacters introduced by path facts.
+        for input in [
+            "private/*.key",
+            "~/private/*.key",
+            "private/key",
+            "~/private/key",
+        ] {
+            let layer = RequirementsLayerEntry::from_toml(
+                RequirementSource::Unknown,
+                format!("[permissions.filesystem]\ndeny_read = ['{input}']"),
+            )
+            .with_path_context(context.clone());
+            assert!(compose_requirements_for_hostname([layer], /*hostname*/ None).is_err());
+        }
+    }
+}
+
+#[test]
+fn native_and_supplied_denials_reject_the_same_unsafe_facts() {
+    let parent = tempdir().unwrap();
+    let directory = parent.path().join("sam[1]");
+    let _base_guard = AbsolutePathBufGuard::new(&directory);
+    AbsolutePathBufGuard::with_home_directory(&directory, || {
+        let inputs = [
+            "private/*.key",
+            "~/private/*.key",
+            "private/key",
+            "~/private/key",
+        ];
+        let native = inputs.map(FilesystemDenyReadPattern::from_input);
+        assert!(native.iter().all(Result::is_err));
+        let directory = PathUri::from_host_native_path(&directory).unwrap();
+        let context = ConfigPathContext::new(
+            PathConvention::native(),
+            Some(directory.clone()),
+            Some(directory),
+        );
+        let _context_guard = context.enter();
+        assert_eq!(inputs.map(FilesystemDenyReadPattern::from_input), native);
+    });
+}

codex-rs/config/src/permissions_toml.rs

@@ -0,0 +1,600 @@
+use std::collections::BTreeMap;
+
+use crate::merge::merge_toml_values;
+use codex_network_proxy::InjectedHeaderConfig;
+use codex_network_proxy::MitmHookActionsConfig;
+use codex_network_proxy::MitmHookBodyConfig;
+use codex_network_proxy::MitmHookConfig;
+use codex_network_proxy::MitmHookMatchConfig;
+use codex_network_proxy::NetworkDomainPermission as ProxyNetworkDomainPermission;
+use codex_network_proxy::NetworkMode;
+use codex_network_proxy::NetworkProxyConfig;
+use codex_network_proxy::NetworkUnixSocketPermission as ProxyNetworkUnixSocketPermission;
+use codex_network_proxy::normalize_host;
+use codex_protocol::permissions::FileSystemAccessMode;
+use indexmap::IndexMap;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use thiserror::Error;
+use toml::Value as TomlValue;
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+pub struct PermissionsToml {
+    #[serde(flatten)]
+    pub entries: BTreeMap<String, PermissionProfileToml>,
+}
+
+impl PermissionsToml {
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// Resolve `profile_name` and all of its `extends` ancestors into one TOML
+    /// profile.
+    ///
+    /// Parent profiles are merged before their children, so child keys override
+    /// matching parent keys before callers compile the profile into runtime
+    /// permissions. The returned profile keeps the selected profile's
+    /// declaration metadata, such as `description` and `extends`.
+    pub fn resolve_profile<F>(
+        &self,
+        profile_name: &str,
+        mut parent_profile: F,
+    ) -> Result<PermissionProfileToml, PermissionProfileResolutionError>
+    where
+        F: FnMut(&str) -> Option<PermissionProfileToml>,
+    {
+        let mut profile_names = Vec::new();
+        let mut profiles = Vec::new();
+        let mut next_profile_name = profile_name.to_string();
+        let mut referenced_by: Option<String> = None;
+
+        loop {
+            if let Some(cycle_start) = profile_names
+                .iter()
+                .position(|name| name == &next_profile_name)
+            {
+                let cycle = profile_names[cycle_start..]
+                    .iter()
+                    .cloned()
+                    .chain(std::iter::once(next_profile_name))
+                    .collect::<Vec<_>>();
+                return Err(PermissionProfileResolutionError::Cycle { cycle });
+            }
+
+            let profile = self
+                .entries
+                .get(&next_profile_name)
+                .cloned()
+                .or_else(|| parent_profile(&next_profile_name))
+                .ok_or_else(|| {
+                    referenced_by.as_deref().map_or_else(
+                        || PermissionProfileResolutionError::UndefinedProfile {
+                            profile_name: next_profile_name.clone(),
+                        },
+                        |referenced_by| {
+                            if next_profile_name.starts_with(':') {
+                                PermissionProfileResolutionError::UnsupportedBuiltInParent {
+                                    profile_name: referenced_by.to_string(),
+                                    parent_profile_name: next_profile_name.clone(),
+                                }
+                            } else {
+                                PermissionProfileResolutionError::UndefinedParent {
+                                    profile_name: referenced_by.to_string(),
+                                    parent_profile_name: next_profile_name.clone(),
+                                }
+                            }
+                        },
+                    )
+                })?;
+            let parent_profile_name = profile.extends.clone();
+
+            profile_names.push(next_profile_name.clone());
+
+            if let Some(parent_profile_name) = parent_profile_name {
+                profiles.push(profile);
+                referenced_by = Some(next_profile_name);
+                next_profile_name = parent_profile_name;
+                continue;
+            }
+
+            let profile = profiles
+                .into_iter()
+                .rev()
+                .try_fold(profile, merge_permission_profiles)?;
+            return Ok(profile);
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct PermissionProfileToml {
+    pub description: Option<String>,
+    pub extends: Option<String>,
+    pub workspace_roots: Option<WorkspaceRootsToml>,
+    pub filesystem: Option<FilesystemPermissionsToml>,
+    pub network: Option<NetworkToml>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Error)]
+pub enum PermissionProfileResolutionError {
+    #[error("default_permissions refers to undefined profile `{profile_name}`")]
+    UndefinedProfile { profile_name: String },
+    #[error(
+        "permissions profile `{profile_name}` extends undefined profile `{parent_profile_name}`"
+    )]
+    UndefinedParent {
+        profile_name: String,
+        parent_profile_name: String,
+    },
+    #[error(
+        "permissions profile `{profile_name}` cannot extend unsupported built-in profile `{parent_profile_name}`"
+    )]
+    UnsupportedBuiltInParent {
+        profile_name: String,
+        parent_profile_name: String,
+    },
+    #[error(
+        "permissions profile inheritance cycle detected: {}",
+        cycle.join(" -> ")
+    )]
+    Cycle { cycle: Vec<String> },
+    #[error("failed to serialize permissions profile while resolving inheritance: {source}")]
+    SerializeProfileToml {
+        #[source]
+        source: toml::ser::Error,
+    },
+    #[error(
+        "failed to deserialize merged permissions profile while resolving inheritance: {source}"
+    )]
+    DeserializeProfileToml {
+        #[source]
+        source: toml::de::Error,
+    },
+}
+
+fn merge_permission_profiles(
+    mut parent: PermissionProfileToml,
+    mut child: PermissionProfileToml,
+) -> Result<PermissionProfileToml, PermissionProfileResolutionError> {
+    let merges_network_domains = parent
+        .network
+        .as_ref()
+        .and_then(|network| network.domains.as_ref())
+        .is_some()
+        && child
+            .network
+            .as_ref()
+            .and_then(|network| network.domains.as_ref())
+            .is_some();
+
+    // Description and inheritance metadata belong to the selected profile
+    // declaration, so an inherited profile must not fill those gaps.
+    parent.description = None;
+    parent.extends = None;
+
+    if merges_network_domains {
+        normalize_profile_network_domains(&mut parent);
+        normalize_profile_network_domains(&mut child);
+    }
+
+    let mut merged = TomlValue::try_from(parent)
+        .map_err(|source| PermissionProfileResolutionError::SerializeProfileToml { source })?;
+    let child = TomlValue::try_from(child)
+        .map_err(|source| PermissionProfileResolutionError::SerializeProfileToml { source })?;
+    merge_toml_values(&mut merged, &child);
+    merged
+        .try_into()
+        .map_err(|source| PermissionProfileResolutionError::DeserializeProfileToml { source })
+}
+
+fn normalize_profile_network_domains(profile: &mut PermissionProfileToml) {
+    let Some(domains) = profile
+        .network
+        .as_mut()
+        .and_then(|network| network.domains.as_mut())
+    else {
+        return;
+    };
+
+    let entries = std::mem::take(&mut domains.entries);
+    domains.entries = entries
+        .into_iter()
+        .map(|(pattern, permission)| (normalize_host(&pattern), permission))
+        .collect();
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+pub struct WorkspaceRootsToml {
+    #[serde(flatten)]
+    pub entries: BTreeMap<String, bool>,
+}
+
+impl WorkspaceRootsToml {
+    pub fn enabled_roots(&self) -> impl Iterator<Item = &String> {
+        self.entries
+            .iter()
+            .filter_map(|(path, enabled)| (*enabled).then_some(path))
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+pub struct FilesystemPermissionsToml {
+    /// Optional maximum depth for expanding unreadable glob patterns on
+    /// platforms that snapshot glob matches before sandbox startup.
+    #[schemars(range(min = 1))]
+    pub glob_scan_max_depth: Option<usize>,
+    #[serde(flatten)]
+    pub entries: BTreeMap<String, FilesystemPermissionToml>,
+}
+
+impl FilesystemPermissionsToml {
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[serde(untagged)]
+pub enum FilesystemPermissionToml {
+    Access(FileSystemAccessMode),
+    Scoped(BTreeMap<String, FileSystemAccessMode>),
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+pub struct NetworkDomainPermissionsToml {
+    #[serde(flatten)]
+    pub entries: BTreeMap<String, NetworkDomainPermissionToml>,
+}
+
+impl NetworkDomainPermissionsToml {
+    pub fn allowed_domains(&self) -> Option<Vec<String>> {
+        let allowed_domains: Vec<String> = self
+            .entries
+            .iter()
+            .filter(|(_, permission)| matches!(permission, NetworkDomainPermissionToml::Allow))
+            .map(|(pattern, _)| pattern.clone())
+            .collect();
+        (!allowed_domains.is_empty()).then_some(allowed_domains)
+    }
+
+    pub fn denied_domains(&self) -> Option<Vec<String>> {
+        let denied_domains: Vec<String> = self
+            .entries
+            .iter()
+            .filter(|(_, permission)| matches!(permission, NetworkDomainPermissionToml::Deny))
+            .map(|(pattern, _)| pattern.clone())
+            .collect();
+        (!denied_domains.is_empty()).then_some(denied_domains)
+    }
+}
+
+#[derive(
+    Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, JsonSchema,
+)]
+#[serde(rename_all = "lowercase")]
+pub enum NetworkDomainPermissionToml {
+    Allow,
+    Deny,
+}
+
+impl std::fmt::Display for NetworkDomainPermissionToml {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let permission = match self {
+            Self::Allow => "allow",
+            Self::Deny => "deny",
+        };
+        f.write_str(permission)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+pub struct NetworkUnixSocketPermissionsToml {
+    #[serde(flatten)]
+    pub entries: BTreeMap<String, NetworkUnixSocketPermissionToml>,
+}
+
+impl NetworkUnixSocketPermissionsToml {
+    pub fn allow_unix_sockets(&self) -> Vec<String> {
+        self.entries
+            .iter()
+            .filter(|(_, permission)| matches!(permission, NetworkUnixSocketPermissionToml::Allow))
+            .map(|(path, _)| path.clone())
+            .collect()
+    }
+}
+
+#[derive(
+    Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, JsonSchema,
+)]
+#[serde(rename_all = "lowercase")]
+pub enum NetworkUnixSocketPermissionToml {
+    Allow,
+    Deny,
+}
+
+impl std::fmt::Display for NetworkUnixSocketPermissionToml {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let permission = match self {
+            Self::Allow => "allow",
+            Self::Deny => "deny",
+        };
+        f.write_str(permission)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct NetworkToml {
+    pub enabled: Option<bool>,
+    pub proxy_url: Option<String>,
+    pub enable_socks5: Option<bool>,
+    pub socks_url: Option<String>,
+    pub enable_socks5_udp: Option<bool>,
+    pub allow_upstream_proxy: Option<bool>,
+    pub dangerously_allow_non_loopback_proxy: Option<bool>,
+    pub dangerously_allow_all_unix_sockets: Option<bool>,
+    #[schemars(with = "Option<NetworkModeSchema>")]
+    pub mode: Option<NetworkMode>,
+    pub domains: Option<NetworkDomainPermissionsToml>,
+    pub unix_sockets: Option<NetworkUnixSocketPermissionsToml>,
+    pub allow_local_binding: Option<bool>,
+    pub mitm: Option<NetworkMitmToml>,
+}
+
+#[derive(Serialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct NetworkMitmToml {
+    #[schemars(with = "Option<BTreeMap<String, NetworkMitmHookToml>>")]
+    pub hooks: Option<IndexMap<String, NetworkMitmHookToml>>,
+    #[schemars(with = "Option<BTreeMap<String, NetworkMitmActionToml>>")]
+    pub actions: Option<IndexMap<String, NetworkMitmActionToml>>,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct NetworkMitmTomlUnchecked {
+    pub hooks: Option<IndexMap<String, NetworkMitmHookToml>>,
+    pub actions: Option<IndexMap<String, NetworkMitmActionToml>>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct NetworkMitmHookToml {
+    pub host: String,
+    pub methods: Vec<String>,
+    pub path_prefixes: Vec<String>,
+    #[serde(default)]
+    pub query: BTreeMap<String, Vec<String>>,
+    #[serde(default)]
+    pub headers: BTreeMap<String, Vec<String>>,
+    #[schemars(with = "Option<MitmHookBodyConfigSchema>")]
+    pub body: Option<MitmHookBodyConfig>,
+    pub action: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+enum NetworkModeSchema {
+    Limited,
+    Full,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[serde(default)]
+pub struct NetworkMitmActionToml {
+    pub strip_request_headers: Vec<String>,
+    pub inject_request_headers: Vec<NetworkMitmInjectedHeaderToml>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[serde(default)]
+pub struct NetworkMitmInjectedHeaderToml {
+    pub name: String,
+    pub secret_env_var: Option<String>,
+    pub secret_file: Option<String>,
+    pub prefix: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[serde(transparent)]
+struct MitmHookBodyConfigSchema(pub serde_json::Value);
+
+impl<'de> Deserialize<'de> for NetworkMitmToml {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let unchecked = NetworkMitmTomlUnchecked::deserialize(deserializer)?;
+        let mitm = Self {
+            hooks: unchecked.hooks,
+            actions: unchecked.actions,
+        };
+        mitm.validate_action_definitions()
+            .map_err(serde::de::Error::custom)?;
+        Ok(mitm)
+    }
+}
+
+impl NetworkMitmToml {
+    pub fn validate_action_definitions(&self) -> Result<(), String> {
+        if let Some(actions) = self.actions.as_ref() {
+            for (action_name, action) in actions {
+                if action.is_empty() {
+                    return Err(format!(
+                        "network.mitm.actions.{action_name} must define at least one operation"
+                    ));
+                }
+            }
+        }
+
+        let Some(hooks) = self.hooks.as_ref() else {
+            return Ok(());
+        };
+
+        for (hook_name, hook) in hooks {
+            if hook.action.is_empty() {
+                return Err(format!(
+                    "network.mitm.hooks.{hook_name}.action must not be empty"
+                ));
+            }
+        }
+
+        Ok(())
+    }
+
+    pub fn to_runtime_hooks(
+        &self,
+        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
+    ) -> Vec<MitmHookConfig> {
+        self.hooks
+            .as_ref()
+            .map(|hooks| {
+                hooks
+                    .values()
+                    .map(|hook| hook.to_runtime(actions_by_name))
+                    .collect()
+            })
+            .unwrap_or_default()
+    }
+}
+
+impl NetworkMitmActionToml {
+    pub fn is_empty(&self) -> bool {
+        self.strip_request_headers.is_empty() && self.inject_request_headers.is_empty()
+    }
+}
+
+impl NetworkToml {
+    pub fn apply_to_network_proxy_config(&self, config: &mut NetworkProxyConfig) {
+        if let Some(enabled) = self.enabled {
+            config.enabled = enabled;
+        }
+        if let Some(proxy_url) = self.proxy_url.as_ref() {
+            config.proxy_url = proxy_url.clone();
+        }
+        if let Some(enable_socks5) = self.enable_socks5 {
+            config.enable_socks5 = enable_socks5;
+        }
+        if let Some(socks_url) = self.socks_url.as_ref() {
+            config.socks_url = socks_url.clone();
+        }
+        if let Some(enable_socks5_udp) = self.enable_socks5_udp {
+            config.enable_socks5_udp = enable_socks5_udp;
+        }
+        if let Some(allow_upstream_proxy) = self.allow_upstream_proxy {
+            config.allow_upstream_proxy = allow_upstream_proxy;
+        }
+        if let Some(dangerously_allow_non_loopback_proxy) =
+            self.dangerously_allow_non_loopback_proxy
+        {
+            config.dangerously_allow_non_loopback_proxy = dangerously_allow_non_loopback_proxy;
+        }
+        if let Some(dangerously_allow_all_unix_sockets) = self.dangerously_allow_all_unix_sockets {
+            config.dangerously_allow_all_unix_sockets = dangerously_allow_all_unix_sockets;
+        }
+        if let Some(mode) = self.mode {
+            config.mode = mode;
+        }
+        if let Some(domains) = self.domains.as_ref() {
+            overlay_network_domain_permissions(config, domains);
+        }
+        if let Some(unix_sockets) = self.unix_sockets.as_ref() {
+            let mut proxy_unix_sockets = config.unix_sockets.take().unwrap_or_default();
+            for (path, permission) in &unix_sockets.entries {
+                let permission = match permission {
+                    NetworkUnixSocketPermissionToml::Allow => {
+                        ProxyNetworkUnixSocketPermission::Allow
+                    }
+                    NetworkUnixSocketPermissionToml::Deny => ProxyNetworkUnixSocketPermission::Deny,
+                };
+                proxy_unix_sockets.entries.insert(path.clone(), permission);
+            }
+            config.unix_sockets =
+                (!proxy_unix_sockets.entries.is_empty()).then_some(proxy_unix_sockets);
+        }
+        if let Some(allow_local_binding) = self.allow_local_binding {
+            config.allow_local_binding = allow_local_binding;
+        }
+        if let Some(mitm) = self.mitm.as_ref() {
+            config.mitm_hooks = mitm.to_runtime_hooks(mitm.actions.as_ref());
+        }
+        config.mitm = config.mode == NetworkMode::Limited || !config.mitm_hooks.is_empty();
+    }
+
+    pub fn to_network_proxy_config(&self) -> NetworkProxyConfig {
+        let mut config = NetworkProxyConfig::default();
+        self.apply_to_network_proxy_config(&mut config);
+        config
+    }
+}
+
+impl NetworkMitmHookToml {
+    fn to_runtime(
+        &self,
+        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
+    ) -> MitmHookConfig {
+        MitmHookConfig {
+            host: self.host.clone(),
+            matcher: MitmHookMatchConfig {
+                methods: self.methods.clone(),
+                path_prefixes: self.path_prefixes.clone(),
+                query: self.query.clone(),
+                headers: self.headers.clone(),
+                body: self.body.clone(),
+            },
+            actions: self.selected_actions(actions_by_name),
+        }
+    }
+
+    fn selected_actions(
+        &self,
+        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
+    ) -> MitmHookActionsConfig {
+        let Some(actions_by_name) = actions_by_name else {
+            return MitmHookActionsConfig::default();
+        };
+
+        let mut selected = MitmHookActionsConfig::default();
+        for action_name in &self.action {
+            if let Some(action) = actions_by_name.get(action_name) {
+                selected
+                    .strip_request_headers
+                    .extend(action.strip_request_headers.clone());
+                selected.inject_request_headers.extend(
+                    action
+                        .inject_request_headers
+                        .iter()
+                        .map(NetworkMitmInjectedHeaderToml::to_runtime),
+                );
+            }
+        }
+        selected
+    }
+}
+
+impl NetworkMitmInjectedHeaderToml {
+    fn to_runtime(&self) -> InjectedHeaderConfig {
+        InjectedHeaderConfig {
+            name: self.name.clone(),
+            secret_env_var: self.secret_env_var.clone(),
+            secret_file: self.secret_file.clone(),
+            prefix: self.prefix.clone(),
+        }
+    }
+}
+
+pub fn overlay_network_domain_permissions(
+    config: &mut NetworkProxyConfig,
+    domains: &NetworkDomainPermissionsToml,
+) {
+    for (pattern, permission) in &domains.entries {
+        let permission = match permission {
+            NetworkDomainPermissionToml::Allow => ProxyNetworkDomainPermission::Allow,
+            NetworkDomainPermissionToml::Deny => ProxyNetworkDomainPermission::Deny,
+        };
+        config.upsert_domain_permission(pattern.clone(), permission, normalize_host);
+    }
+}

codex-rs/config/src/project_root_markers.rs

@@ -0,0 +1,50 @@
+use std::io;
+
+use toml::Value as TomlValue;
+
+const DEFAULT_PROJECT_ROOT_MARKERS: &[&str] = &[".git"];
+
+/// Reads `project_root_markers` from a merged `config.toml` [toml::Value].
+///
+/// Invariants:
+/// - If `project_root_markers` is not specified, returns `Ok(None)`.
+/// - If `project_root_markers` is specified, returns `Ok(Some(markers))` where
+///   `markers` is a `Vec<String>` (including `Ok(Some(Vec::new()))` for an
+///   empty array, which indicates that root detection should be disabled).
+/// - Returns an error if `project_root_markers` is specified but is not an
+///   array of strings.
+pub fn project_root_markers_from_config(config: &TomlValue) -> io::Result<Option<Vec<String>>> {
+    let Some(table) = config.as_table() else {
+        return Ok(None);
+    };
+    let Some(markers_value) = table.get("project_root_markers") else {
+        return Ok(None);
+    };
+    let TomlValue::Array(entries) = markers_value else {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            "project_root_markers must be an array of strings",
+        ));
+    };
+    if entries.is_empty() {
+        return Ok(Some(Vec::new()));
+    }
+    let mut markers = Vec::new();
+    for entry in entries {
+        let Some(marker) = entry.as_str() else {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidData,
+                "project_root_markers must be an array of strings",
+            ));
+        };
+        markers.push(marker.to_string());
+    }
+    Ok(Some(markers))
+}
+
+pub fn default_project_root_markers() -> Vec<String> {
+    DEFAULT_PROJECT_ROOT_MARKERS
+        .iter()
+        .map(ToString::to_string)
+        .collect()
+}

codex-rs/config/src/requirements_exec_policy.rs

@@ -0,0 +1,201 @@
+use codex_execpolicy::Decision;
+use codex_execpolicy::Policy;
+use codex_execpolicy::RequirementsExecPolicy;
+use codex_execpolicy::RuleRef;
+use codex_execpolicy::rule::PatternToken;
+use codex_execpolicy::rule::PrefixPattern;
+use codex_execpolicy::rule::PrefixRule;
+use multimap::MultiMap;
+use serde::Deserialize;
+use std::sync::Arc;
+use thiserror::Error;
+
+/// TOML representation of `[rules]` within `requirements.toml`.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct RequirementsExecPolicyToml {
+    pub prefix_rules: Vec<RequirementsExecPolicyPrefixRuleToml>,
+}
+
+/// A TOML representation of the `prefix_rule(...)` Starlark builtin.
+///
+/// This mirrors the builtin defined in `execpolicy/src/parser.rs`.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct RequirementsExecPolicyPrefixRuleToml {
+    pub pattern: Vec<RequirementsExecPolicyPatternTokenToml>,
+    pub decision: Option<RequirementsExecPolicyDecisionToml>,
+    pub justification: Option<String>,
+}
+
+/// TOML-friendly representation of a pattern token.
+///
+/// Starlark supports either a string token or a list of alternative tokens at
+/// each position, but TOML arrays cannot mix strings and arrays. Using an
+/// array of tables sidesteps that restriction.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct RequirementsExecPolicyPatternTokenToml {
+    pub token: Option<String>,
+    pub any_of: Option<Vec<String>>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum RequirementsExecPolicyDecisionToml {
+    Allow,
+    Prompt,
+    Forbidden,
+}
+
+impl RequirementsExecPolicyDecisionToml {
+    fn as_decision(self) -> Decision {
+        match self {
+            Self::Allow => Decision::Allow,
+            Self::Prompt => Decision::Prompt,
+            Self::Forbidden => Decision::Forbidden,
+        }
+    }
+}
+
+#[derive(Debug, Error)]
+pub enum RequirementsExecPolicyParseError {
+    #[error("rules prefix_rules cannot be empty")]
+    EmptyPrefixRules,
+
+    #[error("rules prefix_rule at index {rule_index} has an empty pattern")]
+    EmptyPattern { rule_index: usize },
+
+    #[error(
+        "rules prefix_rule at index {rule_index} has an invalid pattern token at index {token_index}: {reason}"
+    )]
+    InvalidPatternToken {
+        rule_index: usize,
+        token_index: usize,
+        reason: String,
+    },
+
+    #[error("rules prefix_rule at index {rule_index} has an empty justification")]
+    EmptyJustification { rule_index: usize },
+
+    #[error("rules prefix_rule at index {rule_index} is missing a decision")]
+    MissingDecision { rule_index: usize },
+
+    #[error(
+        "rules prefix_rule at index {rule_index} has decision 'allow', which is not permitted in requirements.toml: Codex merges these rules with other config and uses the most restrictive result (use 'prompt' or 'forbidden')"
+    )]
+    AllowDecisionNotAllowed { rule_index: usize },
+}
+
+impl RequirementsExecPolicyToml {
+    /// Convert requirements TOML rules into the internal `.rules`
+    /// representation used by `codex-execpolicy`.
+    pub fn to_policy(&self) -> Result<Policy, RequirementsExecPolicyParseError> {
+        if self.prefix_rules.is_empty() {
+            return Err(RequirementsExecPolicyParseError::EmptyPrefixRules);
+        }
+
+        let mut rules_by_program: MultiMap<String, RuleRef> = MultiMap::new();
+
+        for (rule_index, rule) in self.prefix_rules.iter().enumerate() {
+            if let Some(justification) = &rule.justification
+                && justification.trim().is_empty()
+            {
+                return Err(RequirementsExecPolicyParseError::EmptyJustification { rule_index });
+            }
+
+            if rule.pattern.is_empty() {
+                return Err(RequirementsExecPolicyParseError::EmptyPattern { rule_index });
+            }
+
+            let pattern_tokens = rule
+                .pattern
+                .iter()
+                .enumerate()
+                .map(|(token_index, token)| parse_pattern_token(token, rule_index, token_index))
+                .collect::<Result<Vec<_>, _>>()?;
+
+            let decision = match rule.decision {
+                Some(RequirementsExecPolicyDecisionToml::Allow) => {
+                    return Err(RequirementsExecPolicyParseError::AllowDecisionNotAllowed {
+                        rule_index,
+                    });
+                }
+                Some(decision) => decision.as_decision(),
+                None => {
+                    return Err(RequirementsExecPolicyParseError::MissingDecision { rule_index });
+                }
+            };
+            let justification = rule.justification.clone();
+
+            let (first_token, remaining_tokens) = pattern_tokens
+                .split_first()
+                .ok_or(RequirementsExecPolicyParseError::EmptyPattern { rule_index })?;
+
+            let rest: Arc<[PatternToken]> = remaining_tokens.to_vec().into();
+
+            for head in first_token.alternatives() {
+                let rule: RuleRef = Arc::new(PrefixRule {
+                    pattern: PrefixPattern {
+                        first: Arc::from(head.as_str()),
+                        rest: rest.clone(),
+                    },
+                    decision,
+                    justification: justification.clone(),
+                });
+                rules_by_program.insert(head.clone(), rule);
+            }
+        }
+
+        Ok(Policy::new(rules_by_program))
+    }
+
+    pub(crate) fn to_requirements_policy(
+        &self,
+    ) -> Result<RequirementsExecPolicy, RequirementsExecPolicyParseError> {
+        self.to_policy().map(RequirementsExecPolicy::new)
+    }
+}
+
+fn parse_pattern_token(
+    token: &RequirementsExecPolicyPatternTokenToml,
+    rule_index: usize,
+    token_index: usize,
+) -> Result<PatternToken, RequirementsExecPolicyParseError> {
+    match (&token.token, &token.any_of) {
+        (Some(single), None) => {
+            if single.trim().is_empty() {
+                return Err(RequirementsExecPolicyParseError::InvalidPatternToken {
+                    rule_index,
+                    token_index,
+                    reason: "token cannot be empty".to_string(),
+                });
+            }
+            Ok(PatternToken::Single(single.clone()))
+        }
+        (None, Some(alternatives)) => {
+            if alternatives.is_empty() {
+                return Err(RequirementsExecPolicyParseError::InvalidPatternToken {
+                    rule_index,
+                    token_index,
+                    reason: "any_of cannot be empty".to_string(),
+                });
+            }
+            if alternatives.iter().any(|alt| alt.trim().is_empty()) {
+                return Err(RequirementsExecPolicyParseError::InvalidPatternToken {
+                    rule_index,
+                    token_index,
+                    reason: "any_of cannot include empty tokens".to_string(),
+                });
+            }
+            Ok(PatternToken::Alts(alternatives.clone()))
+        }
+        (Some(_), Some(_)) => Err(RequirementsExecPolicyParseError::InvalidPatternToken {
+            rule_index,
+            token_index,
+            reason: "set either token or any_of, not both".to_string(),
+        }),
+        (None, None) => Err(RequirementsExecPolicyParseError::InvalidPatternToken {
+            rule_index,
+            token_index,
+            reason: "set either token or any_of".to_string(),
+        }),
+    }
+}

codex-rs/config/src/schema.rs

@@ -0,0 +1,292 @@
+use crate::config_toml::ConfigToml;
+use crate::types::RawMcpServerConfig;
+use codex_features::FEATURES;
+use codex_features::legacy_feature_keys;
+use codex_protocol::protocol::GranularApprovalConfig;
+use schemars::JsonSchema;
+use schemars::r#gen::SchemaGenerator;
+use schemars::r#gen::SchemaSettings;
+use schemars::schema::InstanceType;
+use schemars::schema::ObjectValidation;
+use schemars::schema::RootSchema;
+use schemars::schema::Schema;
+use schemars::schema::SchemaObject;
+use schemars::schema::SubschemaValidation;
+use serde_json::Map;
+use serde_json::Value;
+use std::path::Path;
+
+/// Determines the conditions under which the user is consulted to approve
+/// running the command proposed by Codex.
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[schemars(rename = "AskForApproval")]
+#[serde(rename_all = "kebab-case")]
+pub(crate) enum ConfigAskForApproval {
+    /// The model decides when to ask the user for approval.
+    OnRequest,
+
+    /// Fine-grained controls for individual approval flows.
+    ///
+    /// When a field is `true`, commands in that category are allowed. When it
+    /// is `false`, those requests are automatically rejected instead of shown
+    /// to the user.
+    Granular(GranularApprovalConfig),
+
+    /// Never ask the user to approve commands. Failures are immediately returned
+    /// to the model, and never escalated to the user for approval.
+    Never,
+}
+
+/// Schema for the `[features]` map with known + legacy keys only.
+pub fn features_schema(schema_gen: &mut SchemaGenerator) -> Schema {
+    let mut object = SchemaObject {
+        instance_type: Some(InstanceType::Object.into()),
+        ..Default::default()
+    };
+
+    let mut validation = ObjectValidation::default();
+    for feature in FEATURES {
+        if feature.id == codex_features::Feature::Artifact {
+            continue;
+        }
+        if feature.id == codex_features::Feature::CodeMode {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::CodeModeConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::CodeModeHost {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::CodeModeHostConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::NonPrefixedMcpToolNames {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::NonPrefixedMcpToolNamesConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::GuardianThreadContext {
+            // This setting is already part of the guardianv2 feature table.
+            continue;
+        }
+        if feature.id == codex_features::Feature::GuardianV2 {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::GuardianV2ConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::MultiAgentV2 {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::MultiAgentV2ConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::TokenBudget {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::TokenBudgetConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::ContextManagement {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::ContextManagementConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::RolloutBudget {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::RolloutBudgetConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::CurrentTimeReminder {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::CurrentTimeReminderConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::SleepTool {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::SleepToolConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::AppsMcpPathOverride {
+            validation.properties.insert(
+                feature.key.to_string(),
+                removed_apps_mcp_path_override_schema(schema_gen),
+            );
+            continue;
+        }
+        if feature.id == codex_features::Feature::NetworkProxy {
+            validation.properties.insert(
+                feature.key.to_string(),
+                schema_gen.subschema_for::<codex_features::FeatureToml<
+                    codex_features::NetworkProxyConfigToml,
+                >>(),
+            );
+            continue;
+        }
+        validation
+            .properties
+            .insert(feature.key.to_string(), schema_gen.subschema_for::<bool>());
+    }
+    for legacy_key in legacy_feature_keys() {
+        validation
+            .properties
+            .insert(legacy_key.to_string(), schema_gen.subschema_for::<bool>());
+    }
+    validation.properties.insert(
+        "tool_registry".to_string(),
+        schema_gen.subschema_for::<codex_features::ToolRegistryConfigToml>(),
+    );
+    validation.additional_properties = Some(Box::new(Schema::Bool(false)));
+    object.object = Some(Box::new(validation));
+
+    Schema::Object(object)
+}
+
+fn removed_apps_mcp_path_override_schema(schema_gen: &mut SchemaGenerator) -> Schema {
+    let mut config_validation = ObjectValidation::default();
+    config_validation
+        .properties
+        .insert("enabled".to_string(), schema_gen.subschema_for::<bool>());
+    config_validation
+        .properties
+        .insert("path".to_string(), schema_gen.subschema_for::<String>());
+    config_validation.additional_properties = Some(Box::new(Schema::Bool(false)));
+
+    let config = Schema::Object(SchemaObject {
+        instance_type: Some(InstanceType::Object.into()),
+        object: Some(Box::new(config_validation)),
+        ..Default::default()
+    });
+    Schema::Object(SchemaObject {
+        subschemas: Some(Box::new(SubschemaValidation {
+            any_of: Some(vec![schema_gen.subschema_for::<bool>(), config]),
+            ..Default::default()
+        })),
+        ..Default::default()
+    })
+}
+
+/// Schema for the `[mcp_servers]` map using the raw input shape.
+pub fn mcp_servers_schema(schema_gen: &mut SchemaGenerator) -> Schema {
+    let mut object = SchemaObject {
+        instance_type: Some(InstanceType::Object.into()),
+        ..Default::default()
+    };
+
+    let validation = ObjectValidation {
+        additional_properties: Some(Box::new(schema_gen.subschema_for::<RawMcpServerConfig>())),
+        ..Default::default()
+    };
+    object.object = Some(Box::new(validation));
+
+    Schema::Object(object)
+}
+
+/// Build the config schema for `config.toml`.
+pub fn config_schema() -> RootSchema {
+    let mut schema = SchemaSettings::draft07()
+        .with(|settings| {
+            settings.option_add_null_type = false;
+        })
+        .into_generator()
+        .into_root_schema_for::<ConfigToml>();
+    add_shell_environment_policy_constraints(&mut schema);
+    schema
+}
+
+fn add_shell_environment_policy_constraints(schema: &mut RootSchema) {
+    let Some(Schema::Object(policy)) = schema.definitions.get_mut("ShellEnvironmentPolicyToml")
+    else {
+        return;
+    };
+    let all_of = policy
+        .subschemas
+        .get_or_insert_default()
+        .all_of
+        .get_or_insert_default();
+    for fields in [["exclude", "filters"], ["filters", "include_only"]] {
+        all_of.push(Schema::Object(SchemaObject {
+            subschemas: Some(Box::new(SubschemaValidation {
+                not: Some(Box::new(Schema::Object(SchemaObject {
+                    object: Some(Box::new(ObjectValidation {
+                        required: fields.into_iter().map(str::to_string).collect(),
+                        ..Default::default()
+                    })),
+                    ..Default::default()
+                }))),
+                ..Default::default()
+            })),
+            ..Default::default()
+        }));
+    }
+}
+
+/// Canonicalize a JSON value by sorting its keys.
+pub fn canonicalize(value: &Value) -> Value {
+    match value {
+        Value::Array(items) => Value::Array(items.iter().map(canonicalize).collect()),
+        Value::Object(map) => {
+            let mut entries: Vec<_> = map.iter().collect();
+            entries.sort_by_key(|(key, _)| *key);
+            let mut sorted = Map::with_capacity(map.len());
+            for (key, child) in entries {
+                sorted.insert(key.clone(), canonicalize(child));
+            }
+            Value::Object(sorted)
+        }
+        _ => value.clone(),
+    }
+}
+
+/// Render the config schema as pretty-printed JSON.
+pub fn config_schema_json() -> anyhow::Result<Vec<u8>> {
+    let schema = config_schema();
+    let value = serde_json::to_value(schema)?;
+    let value = canonicalize(&value);
+    let json = serde_json::to_vec_pretty(&value)?;
+    Ok(json)
+}
+
+/// Write the config schema fixture to disk.
+pub fn write_config_schema(out_path: &Path) -> anyhow::Result<()> {
+    let json = config_schema_json()?;
+    std::fs::write(out_path, json)?;
+    Ok(())
+}

codex-rs/config/src/skills_config.rs

@@ -0,0 +1,215 @@
+//! Skill-related configuration types shared across crates.
+
+use std::collections::HashSet;
+use std::num::NonZeroUsize;
+
+use crate::ConfigLayerSource;
+use crate::ConfigLayerStack;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use tracing::warn;
+
+const fn default_enabled() -> bool {
+    true
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct SkillConfig {
+    /// Path-based selector.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub path: Option<AbsolutePathBuf>,
+    /// Name-based selector.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    pub enabled: bool,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct SkillsConfig {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bundled: Option<BundledSkillsConfig>,
+
+    /// Whether turns receive the automatic skills instructions block.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub include_instructions: Option<bool>,
+
+    /// Maximum tokens used by the available-skills catalog. Defaults to 2% of
+    /// the model context window and is capped at 10,000 tokens when set.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_context_tokens: Option<NonZeroUsize>,
+
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub config: Vec<SkillConfig>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct BundledSkillsConfig {
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+}
+
+impl Default for BundledSkillsConfig {
+    fn default() -> Self {
+        Self { enabled: true }
+    }
+}
+
+impl TryFrom<toml::Value> for SkillsConfig {
+    type Error = toml::de::Error;
+
+    fn try_from(value: toml::Value) -> Result<Self, Self::Error> {
+        SkillsConfig::deserialize(value)
+    }
+}
+
+/// Selects configured skills by their name or canonical document path.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub enum SkillConfigRuleSelector {
+    Name(String),
+    Path(AbsolutePathBuf),
+}
+
+/// Enables or disables every skill matched by its selector.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct SkillConfigRule {
+    pub selector: SkillConfigRuleSelector,
+    pub enabled: bool,
+}
+
+/// Ordered effective skill enablement rules from configuration layers.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)]
+pub struct SkillConfigRules {
+    pub entries: Vec<SkillConfigRule>,
+}
+
+impl SkillConfigRules {
+    /// Applies rules in order; later rules override earlier rules for matching skills.
+    ///
+    /// Explicit path selectors remain effective even when no current skill matches.
+    pub fn resolve_disabled_paths<'a>(
+        &self,
+        skills: impl IntoIterator<Item = (&'a str, &'a AbsolutePathBuf)> + Clone,
+    ) -> HashSet<AbsolutePathBuf> {
+        let mut disabled_paths = HashSet::new();
+
+        for entry in &self.entries {
+            match &entry.selector {
+                SkillConfigRuleSelector::Path(path) => {
+                    if entry.enabled {
+                        disabled_paths.remove(path);
+                    } else {
+                        disabled_paths.insert(path.clone());
+                    }
+                }
+                SkillConfigRuleSelector::Name(name) => {
+                    for (skill_name, path) in skills.clone() {
+                        if skill_name != name {
+                            continue;
+                        }
+                        if entry.enabled {
+                            disabled_paths.remove(path);
+                        } else {
+                            disabled_paths.insert(path.clone());
+                        }
+                    }
+                }
+            }
+        }
+
+        disabled_paths
+    }
+}
+
+/// Returns whether bundled skills are enabled by the effective configuration.
+pub fn bundled_skills_enabled_from_stack(config_layer_stack: &ConfigLayerStack) -> bool {
+    let effective_config = config_layer_stack.effective_config();
+    let Some(skills_value) = effective_config
+        .as_table()
+        .and_then(|table| table.get("skills"))
+    else {
+        return true;
+    };
+
+    let skills: SkillsConfig = match skills_value.clone().try_into() {
+        Ok(skills) => skills,
+        Err(err) => {
+            warn!("invalid skills config: {err}");
+            return true;
+        }
+    };
+
+    skills.bundled.unwrap_or_default().enabled
+}
+
+/// Resolves skill enablement rules from user and session configuration layers.
+pub fn skill_config_rules_from_stack(config_layer_stack: &ConfigLayerStack) -> SkillConfigRules {
+    let mut entries = Vec::new();
+    for layer in config_layer_stack.all_layers_low_to_high() {
+        if !matches!(
+            layer.name,
+            ConfigLayerSource::User { .. } | ConfigLayerSource::SessionFlags
+        ) {
+            continue;
+        }
+
+        let Some(skills_value) = layer.config.get("skills") else {
+            continue;
+        };
+        let skills: SkillsConfig = match skills_value.clone().try_into() {
+            Ok(skills) => skills,
+            Err(err) => {
+                warn!("invalid skills config: {err}");
+                continue;
+            }
+        };
+
+        for entry in skills.config {
+            let Some(selector) = skill_config_rule_selector(&entry) else {
+                continue;
+            };
+            // Preserve layer order so a later name selector can override an earlier path selector
+            // for the same loaded skill.
+            entries.retain(|entry: &SkillConfigRule| entry.selector != selector);
+            entries.push(SkillConfigRule {
+                selector,
+                enabled: entry.enabled,
+            });
+        }
+    }
+
+    SkillConfigRules { entries }
+}
+
+fn skill_config_rule_selector(entry: &SkillConfig) -> Option<SkillConfigRuleSelector> {
+    match (entry.path.as_ref(), entry.name.as_deref()) {
+        (Some(path), None) => Some(SkillConfigRuleSelector::Path(
+            path.canonicalize().unwrap_or_else(|_| path.clone()),
+        )),
+        (None, Some(name)) => {
+            let name = name.trim();
+            if name.is_empty() {
+                warn!("ignoring empty skills.config name override");
+                None
+            } else {
+                Some(SkillConfigRuleSelector::Name(name.to_string()))
+            }
+        }
+        (Some(_), Some(_)) => {
+            warn!("ignoring skills.config entry with both path and name selectors");
+            None
+        }
+        (None, None) => {
+            warn!("ignoring skills.config entry without a path or name selector");
+            None
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "skills_config_tests.rs"]
+mod tests;

codex-rs/config/src/skills_config_tests.rs

@@ -0,0 +1,242 @@
+use crate::CONFIG_TOML_FILE;
+use crate::ConfigLayerEntry;
+use crate::ConfigLayerSource;
+use crate::ConfigLayerStack;
+use crate::ConfigRequirementsToml;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::SkillConfigRule;
+use super::SkillConfigRuleSelector;
+use super::SkillConfigRules;
+use super::bundled_skills_enabled_from_stack;
+use super::skill_config_rules_from_stack;
+
+fn user_layer(codex_home: &TempDir, config: &str) -> ConfigLayerEntry {
+    let config_path = AbsolutePathBuf::try_from(codex_home.path().join(CONFIG_TOML_FILE))
+        .expect("absolute config path");
+    ConfigLayerEntry::new(
+        ConfigLayerSource::User {
+            file: config_path,
+            profile: None,
+        },
+        toml::from_str(config).expect("valid user config"),
+    )
+}
+
+fn stack(codex_home: &TempDir, user: &str, session: &str) -> ConfigLayerStack {
+    ConfigLayerStack::new(
+        vec![
+            user_layer(codex_home, user),
+            ConfigLayerEntry::new(
+                ConfigLayerSource::SessionFlags,
+                toml::from_str(session).expect("valid session config"),
+            ),
+        ],
+        Default::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("valid config stack")
+}
+
+fn path_toggle_config(path: &std::path::Path, enabled: bool) -> String {
+    let path = toml::Value::String(path.display().to_string());
+    format!(
+        r#"[[skills.config]]
+path = {path}
+enabled = {enabled}
+"#
+    )
+}
+
+#[test]
+fn bundled_skills_follow_effective_configuration() {
+    let codex_home = TempDir::new().expect("temp dir");
+
+    assert!(bundled_skills_enabled_from_stack(&stack(
+        &codex_home,
+        "",
+        ""
+    )));
+    assert!(!bundled_skills_enabled_from_stack(&stack(
+        &codex_home,
+        "[skills.bundled]\nenabled = false\n",
+        ""
+    )));
+    assert!(bundled_skills_enabled_from_stack(&stack(
+        &codex_home,
+        "[skills.bundled]\nenabled = false\n",
+        "[skills.bundled]\nenabled = true\n"
+    )));
+}
+
+#[test]
+fn malformed_bundled_skills_config_defaults_to_enabled() {
+    let codex_home = TempDir::new().expect("temp dir");
+
+    assert!(bundled_skills_enabled_from_stack(&stack(
+        &codex_home,
+        "[skills]\nbundled = 'invalid'\n",
+        ""
+    )));
+}
+
+#[test]
+fn session_flags_can_reenable_user_disabled_path() {
+    let codex_home = TempDir::new().expect("temp dir");
+    let skill_path = codex_home.path().join("skills/demo/SKILL.md");
+
+    assert_eq!(
+        skill_config_rules_from_stack(&stack(
+            &codex_home,
+            &path_toggle_config(&skill_path, /*enabled*/ false),
+            &path_toggle_config(&skill_path, /*enabled*/ true),
+        )),
+        SkillConfigRules {
+            entries: vec![SkillConfigRule {
+                selector: SkillConfigRuleSelector::Path(skill_path.abs()),
+                enabled: true,
+            }],
+        }
+    );
+}
+
+#[test]
+fn session_flags_can_disable_user_enabled_path() {
+    let codex_home = TempDir::new().expect("temp dir");
+    let skill_path = codex_home.path().join("skills/demo/SKILL.md");
+
+    assert_eq!(
+        skill_config_rules_from_stack(&stack(
+            &codex_home,
+            &path_toggle_config(&skill_path, /*enabled*/ true),
+            &path_toggle_config(&skill_path, /*enabled*/ false),
+        )),
+        SkillConfigRules {
+            entries: vec![SkillConfigRule {
+                selector: SkillConfigRuleSelector::Path(skill_path.abs()),
+                enabled: false,
+            }],
+        }
+    );
+}
+
+#[test]
+fn preserves_name_selectors() {
+    let codex_home = TempDir::new().expect("temp dir");
+
+    assert_eq!(
+        skill_config_rules_from_stack(&stack(
+            &codex_home,
+            r#"
+[[skills.config]]
+name = "github:yeet"
+enabled = false
+"#,
+            "",
+        )),
+        SkillConfigRules {
+            entries: vec![SkillConfigRule {
+                selector: SkillConfigRuleSelector::Name("github:yeet".to_string()),
+                enabled: false,
+            }],
+        }
+    );
+}
+
+#[test]
+fn preserves_order_across_path_and_name_selectors() {
+    let codex_home = TempDir::new().expect("temp dir");
+    let skill_path = codex_home.path().join("skills/demo/SKILL.md");
+
+    assert_eq!(
+        skill_config_rules_from_stack(&stack(
+            &codex_home,
+            &path_toggle_config(&skill_path, /*enabled*/ false),
+            r#"
+[[skills.config]]
+name = "github:yeet"
+enabled = true
+"#,
+        )),
+        SkillConfigRules {
+            entries: vec![
+                SkillConfigRule {
+                    selector: SkillConfigRuleSelector::Path(skill_path.abs()),
+                    enabled: false,
+                },
+                SkillConfigRule {
+                    selector: SkillConfigRuleSelector::Name("github:yeet".to_string()),
+                    enabled: true,
+                },
+            ],
+        }
+    );
+}
+
+#[test]
+fn path_rule_disables_selected_path() {
+    let codex_home = TempDir::new().expect("temp dir");
+    let path = codex_home.path().join("disable-by-path/SKILL.md").abs();
+    let rules = SkillConfigRules {
+        entries: vec![SkillConfigRule {
+            selector: SkillConfigRuleSelector::Path(path.clone()),
+            enabled: false,
+        }],
+    };
+
+    assert_eq!(
+        rules.resolve_disabled_paths(std::iter::empty()),
+        [path].into_iter().collect()
+    );
+}
+
+#[test]
+fn later_name_rule_reenables_path_disabled_skill() {
+    let codex_home = TempDir::new().expect("temp dir");
+    let path = codex_home.path().join("reenable-by-name/SKILL.md").abs();
+    let rules = SkillConfigRules {
+        entries: vec![
+            SkillConfigRule {
+                selector: SkillConfigRuleSelector::Path(path.clone()),
+                enabled: false,
+            },
+            SkillConfigRule {
+                selector: SkillConfigRuleSelector::Name("demo".to_string()),
+                enabled: true,
+            },
+        ],
+    };
+
+    assert_eq!(
+        rules.resolve_disabled_paths([("demo", &path)]),
+        Default::default()
+    );
+}
+
+#[test]
+fn later_path_rule_reenables_one_skill_disabled_by_name() {
+    let codex_home = TempDir::new().expect("temp dir");
+    let root = codex_home.path().join("reenable-by-path");
+    let first_path = root.join("first/SKILL.md").abs();
+    let second_path = root.join("second/SKILL.md").abs();
+    let rules = SkillConfigRules {
+        entries: vec![
+            SkillConfigRule {
+                selector: SkillConfigRuleSelector::Name("demo".to_string()),
+                enabled: false,
+            },
+            SkillConfigRule {
+                selector: SkillConfigRuleSelector::Path(first_path.clone()),
+                enabled: true,
+            },
+        ],
+    };
+
+    assert_eq!(
+        rules.resolve_disabled_paths([("demo", &first_path), ("demo", &second_path)]),
+        [second_path].into_iter().collect()
+    );
+}

codex-rs/config/src/state.rs

@@ -0,0 +1,630 @@
+use crate::CONFIG_TOML_FILE;
+use crate::config_requirements::ConfigRequirements;
+use crate::config_requirements::ConfigRequirementsToml;
+use crate::format_config_layer_source;
+
+use super::fingerprint::record_origins;
+use super::fingerprint::version_for_toml;
+use super::key_aliases::normalized_with_key_aliases;
+use super::merge::merge_toml_values;
+use crate::CloudConfigBundleLoader;
+use crate::ConfigLayer;
+use crate::ConfigLayerMetadata;
+use crate::ConfigLayerSource;
+use crate::ProfileV2Name;
+use crate::shell_environment_policy::validate_shell_environment_policy_filter_config;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde_json::Value as JsonValue;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+use toml::Value as TomlValue;
+
+/// User-facing config loading behavior that is not part of the config document.
+#[derive(Debug, Default, Clone)]
+pub struct ConfigLoadOptions {
+    pub loader_overrides: LoaderOverrides,
+    pub strict_config: bool,
+    pub cloud_config_bundle: CloudConfigBundleLoader,
+}
+
+impl From<LoaderOverrides> for ConfigLoadOptions {
+    fn from(loader_overrides: LoaderOverrides) -> Self {
+        Self {
+            loader_overrides,
+            strict_config: false,
+            cloud_config_bundle: CloudConfigBundleLoader::default(),
+        }
+    }
+}
+
+/// LoaderOverrides overrides managed configuration inputs (primarily for tests).
+#[derive(Debug, Default, Clone)]
+pub struct LoaderOverrides {
+    /// Optional configuration file supplied with the installed Codex package.
+    pub packaged_defaults_path: Option<AbsolutePathBuf>,
+    pub user_config_path: Option<AbsolutePathBuf>,
+    pub user_config_profile: Option<ProfileV2Name>,
+    pub managed_config_path: Option<PathBuf>,
+    pub system_config_path: Option<PathBuf>,
+    pub system_requirements_path: Option<PathBuf>,
+    pub ignore_managed_requirements: bool,
+    /// Remote app servers own their authentication policy independently.
+    pub ignore_login_requirements: bool,
+    pub ignore_user_config: bool,
+    /// Skip project-root discovery and all project configuration layers.
+    pub ignore_project_config: bool,
+    pub ignore_user_and_project_exec_policy_rules: bool,
+    //TODO(gt): Add a macos_ prefix to this field and remove the target_os check.
+    #[cfg(target_os = "macos")]
+    pub managed_preferences_base64: Option<String>,
+    pub macos_managed_config_requirements_base64: Option<String>,
+}
+
+impl LoaderOverrides {
+    /// Returns overrides that ignore host-managed configuration.
+    ///
+    /// This is intended for tests that should load only repo-controlled config fixtures.
+    pub fn without_managed_config_for_tests() -> Self {
+        let base = std::env::temp_dir().join("codex-config-tests");
+        Self {
+            packaged_defaults_path: None,
+            user_config_path: None,
+            user_config_profile: None,
+            managed_config_path: Some(base.join("managed_config.toml")),
+            system_config_path: Some(base.join("config.toml")),
+            system_requirements_path: Some(base.join("requirements.toml")),
+            ignore_managed_requirements: false,
+            ignore_login_requirements: false,
+            ignore_user_config: false,
+            ignore_project_config: false,
+            ignore_user_and_project_exec_policy_rules: false,
+            #[cfg(target_os = "macos")]
+            managed_preferences_base64: Some(String::new()),
+            macos_managed_config_requirements_base64: Some(String::new()),
+        }
+    }
+
+    /// Returns overrides with host MDM disabled and managed config loaded from
+    /// `managed_config_path`. System requirements are loaded from a sibling
+    /// `requirements.toml` fixture.
+    ///
+    /// This is intended for tests that supply an explicit managed config fixture.
+    pub fn with_managed_config_path_for_tests(managed_config_path: PathBuf) -> Self {
+        let system_requirements_path = managed_config_path.with_file_name("requirements.toml");
+        Self {
+            user_config_path: None,
+            user_config_profile: None,
+            managed_config_path: Some(managed_config_path),
+            system_requirements_path: Some(system_requirements_path),
+            ..Self::without_managed_config_for_tests()
+        }
+    }
+
+    pub fn user_config_path(&self, codex_home: &Path) -> std::io::Result<AbsolutePathBuf> {
+        match self.user_config_path.as_ref() {
+            Some(path) => Ok(path.clone()),
+            None => Ok(AbsolutePathBuf::resolve_path_against_base(
+                crate::CONFIG_TOML_FILE,
+                codex_home,
+            )),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct ConfigLayerEntry {
+    pub name: ConfigLayerSource,
+    pub config: TomlValue,
+    pub version: String,
+    pub disabled_reason: Option<String>,
+    raw_toml: Option<RawTomlLayer>,
+    hooks_config_folder_override: Option<AbsolutePathBuf>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct RawTomlLayer {
+    contents: String,
+    base_dir: AbsolutePathBuf,
+}
+
+impl ConfigLayerEntry {
+    pub fn new(name: ConfigLayerSource, config: TomlValue) -> Self {
+        let version = version_for_toml(&config);
+        Self {
+            name,
+            config,
+            version,
+            disabled_reason: None,
+            raw_toml: None,
+            hooks_config_folder_override: None,
+        }
+    }
+
+    pub fn new_with_raw_toml(
+        name: ConfigLayerSource,
+        config: TomlValue,
+        raw_toml: String,
+        raw_toml_base_dir: AbsolutePathBuf,
+    ) -> Self {
+        let version = version_for_toml(&config);
+        Self {
+            name,
+            config,
+            version,
+            disabled_reason: None,
+            raw_toml: Some(RawTomlLayer {
+                contents: raw_toml,
+                base_dir: raw_toml_base_dir,
+            }),
+            hooks_config_folder_override: None,
+        }
+    }
+
+    pub fn new_disabled(
+        name: ConfigLayerSource,
+        config: TomlValue,
+        disabled_reason: impl Into<String>,
+    ) -> Self {
+        let version = version_for_toml(&config);
+        Self {
+            name,
+            config,
+            version,
+            disabled_reason: Some(disabled_reason.into()),
+            raw_toml: None,
+            hooks_config_folder_override: None,
+        }
+    }
+
+    pub fn is_disabled(&self) -> bool {
+        self.disabled_reason.is_some()
+    }
+
+    pub fn raw_toml(&self) -> Option<&str> {
+        self.raw_toml
+            .as_ref()
+            .map(|raw_toml| raw_toml.contents.as_str())
+    }
+
+    pub fn raw_toml_base_dir(&self) -> Option<&AbsolutePathBuf> {
+        self.raw_toml.as_ref().map(|raw_toml| &raw_toml.base_dir)
+    }
+
+    pub(crate) fn with_hooks_config_folder_override(
+        mut self,
+        hooks_config_folder_override: Option<AbsolutePathBuf>,
+    ) -> Self {
+        self.hooks_config_folder_override = hooks_config_folder_override;
+        self
+    }
+
+    pub fn metadata(&self) -> ConfigLayerMetadata {
+        ConfigLayerMetadata {
+            name: self.name.clone(),
+            version: self.version.clone(),
+        }
+    }
+
+    pub fn as_layer(&self) -> ConfigLayer {
+        ConfigLayer {
+            name: self.name.clone(),
+            version: self.version.clone(),
+            config: serde_json::to_value(&self.config).unwrap_or(JsonValue::Null),
+            disabled_reason: self.disabled_reason.clone(),
+        }
+    }
+
+    // Get the `.codex/` folder associated with this config layer, if any.
+    pub fn config_folder(&self) -> Option<AbsolutePathBuf> {
+        match &self.name {
+            ConfigLayerSource::PackagedDefaults { .. } => None,
+            ConfigLayerSource::Mdm { .. } => None,
+            ConfigLayerSource::System { file } => file.parent(),
+            ConfigLayerSource::EnterpriseManaged { .. } => None,
+            ConfigLayerSource::User { file, .. } => file.parent(),
+            ConfigLayerSource::Project { dot_codex_folder } => Some(dot_codex_folder.clone()),
+            ConfigLayerSource::SessionFlags => None,
+            ConfigLayerSource::LegacyManagedConfigTomlFromFile { .. } => None,
+            ConfigLayerSource::LegacyManagedConfigTomlFromMdm => None,
+        }
+    }
+
+    /// Returns the `.codex/` folder that should be used for hook declarations.
+    ///
+    /// Project layers normally use their own config folder. Linked Git worktrees
+    /// can instead point hook discovery at the matching folder from the root
+    /// checkout while the rest of the project config still comes from the
+    /// worktree.
+    pub fn hooks_config_folder(&self) -> Option<AbsolutePathBuf> {
+        self.hooks_config_folder_override
+            .clone()
+            .or_else(|| self.config_folder())
+    }
+}
+
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ConfigLayerStack {
+    /// Cached TOML projection derived only from `requirements_toml`.
+    /// Construction validates provider definitions and reports serialization errors,
+    /// so `effective_config()` can replace complete entries without a fallible conversion.
+    model_provider_requirements: Option<TomlValue>,
+    /// Layers are listed from lowest precedence (base) to highest (top), so
+    /// later entries in the Vec override earlier ones.
+    layers: Vec<ConfigLayerEntry>,
+
+    /// Constraints that must be enforced when deriving a [Config] from the
+    /// layers.
+    requirements: ConfigRequirements,
+
+    /// Raw requirements data as loaded from requirements.toml/MDM/legacy
+    /// sources. This preserves the original allow-lists so they can be
+    /// surfaced via APIs.
+    requirements_toml: ConfigRequirementsToml,
+
+    /// Whether execpolicy should skip `.rules` files from user and project config-layer folders.
+    ignore_user_and_project_exec_policy_rules: bool,
+
+    /// Startup warnings discovered while building this stack.
+    ///
+    /// `None` means the loader did not check for stack-level warnings, while
+    /// `Some(vec![])` means it checked and found nothing to report.
+    startup_warnings: Option<Vec<String>>,
+}
+
+impl ConfigLayerStack {
+    pub fn new(
+        layers: Vec<ConfigLayerEntry>,
+        requirements: ConfigRequirements,
+        requirements_toml: ConfigRequirementsToml,
+    ) -> std::io::Result<Self> {
+        validate_enabled_config_layers(&layers)?;
+        verify_layer_ordering(&layers)?;
+        let model_provider_requirements = Some(crate::model_provider_requirements::to_config(
+            &requirements_toml,
+        )?);
+        Ok(Self {
+            model_provider_requirements,
+            layers,
+            requirements,
+            requirements_toml,
+            ignore_user_and_project_exec_policy_rules: false,
+            startup_warnings: None,
+        })
+    }
+
+    pub fn with_user_and_project_exec_policy_rules_ignored(
+        mut self,
+        ignore_user_and_project_exec_policy_rules: bool,
+    ) -> Self {
+        self.ignore_user_and_project_exec_policy_rules = ignore_user_and_project_exec_policy_rules;
+        self
+    }
+
+    pub fn ignore_user_and_project_exec_policy_rules(&self) -> bool {
+        self.ignore_user_and_project_exec_policy_rules
+    }
+
+    pub(crate) fn with_startup_warnings(mut self, startup_warnings: Vec<String>) -> Self {
+        self.startup_warnings = Some(startup_warnings);
+        self
+    }
+
+    pub fn startup_warnings(&self) -> Option<&[String]> {
+        self.startup_warnings.as_deref()
+    }
+
+    /// Returns the active raw user config layer, if any.
+    ///
+    /// This does not merge other config layers or apply any requirements. When
+    /// a profile-v2 layer is active, this returns that profile layer rather than
+    /// the base `$CODEX_HOME/config.toml` layer because the active layer is the
+    /// writable target for profile-aware edits.
+    pub fn get_active_user_layer(&self) -> Option<&ConfigLayerEntry> {
+        self.layers
+            .iter()
+            .rev()
+            .find(|layer| matches!(layer.name, ConfigLayerSource::User { .. }))
+    }
+
+    pub fn get_user_config_file(&self) -> Option<&AbsolutePathBuf> {
+        let layer = self.get_active_user_layer()?;
+        let ConfigLayerSource::User { file, .. } = &layer.name else {
+            return None;
+        };
+        Some(file)
+    }
+
+    /// Returns the merged config from enabled user layers only.
+    ///
+    /// When profile config is active, this includes the base user config followed
+    /// by the profile override config.
+    pub fn effective_user_config(&self) -> Option<TomlValue> {
+        let mut user_layers = self
+            .layers_low_to_high()
+            .filter(|layer| matches!(layer.name, ConfigLayerSource::User { .. }))
+            .peekable();
+        user_layers.peek()?;
+
+        let mut merged = TomlValue::Table(toml::map::Map::new());
+        for layer in user_layers {
+            merge_toml_values(&mut merged, &layer.config);
+        }
+        Some(merged)
+    }
+
+    pub fn requirements(&self) -> &ConfigRequirements {
+        &self.requirements
+    }
+
+    pub fn requirements_toml(&self) -> &ConfigRequirementsToml {
+        &self.requirements_toml
+    }
+
+    /// Creates a new [ConfigLayerStack] using the specified values to inject one
+    /// 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. When the stack has both base and profile-v2
+    /// user layers, this updates only the layer whose file matches
+    /// `config_toml`.
+    pub fn with_user_config(
+        &self,
+        config_toml: &AbsolutePathBuf,
+        user_config: TomlValue,
+    ) -> std::io::Result<Self> {
+        let profile = self.layers.iter().find_map(|layer| match &layer.name {
+            ConfigLayerSource::User { file, profile } if file == config_toml => profile
+                .as_deref()
+                .and_then(|profile| profile.parse::<ProfileV2Name>().ok()),
+            _ => None,
+        });
+        self.with_user_config_profile(config_toml, profile.as_ref(), user_config)
+    }
+
+    pub fn with_user_config_profile(
+        &self,
+        config_toml: &AbsolutePathBuf,
+        profile: Option<&ProfileV2Name>,
+        user_config: TomlValue,
+    ) -> std::io::Result<Self> {
+        let user_layer = ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_toml.clone(),
+                profile: profile.map(ToString::to_string),
+            },
+            user_config,
+        );
+        validate_enabled_config_layers(std::slice::from_ref(&user_layer))?;
+
+        let mut layers = self.layers.clone();
+        if let Some(index) = layers.iter().position(|layer| {
+            matches!(
+                &layer.name,
+                ConfigLayerSource::User { file, .. } if file == config_toml
+            )
+        }) {
+            layers.remove(index);
+        }
+        match layers
+            .iter()
+            .position(|layer| layer.name.precedence() > user_layer.name.precedence())
+        {
+            Some(index) => layers.insert(index, user_layer),
+            None => layers.push(user_layer),
+        }
+        Ok(Self {
+            layers,
+            model_provider_requirements: self.model_provider_requirements.clone(),
+            requirements: self.requirements.clone(),
+            requirements_toml: self.requirements_toml.clone(),
+            ignore_user_and_project_exec_policy_rules: self
+                .ignore_user_and_project_exec_policy_rules,
+            startup_warnings: self.startup_warnings.clone(),
+        })
+    }
+
+    /// Returns a new stack with the user layer copied from `other`, preserving
+    /// every non-user layer already present in this stack.
+    pub fn with_user_layer_from(&self, other: &Self) -> Self {
+        let user_layers = other
+            .layers
+            .iter()
+            .filter(|layer| matches!(layer.name, ConfigLayerSource::User { .. }))
+            .cloned()
+            .collect::<Vec<_>>();
+        let mut layers = self
+            .layers
+            .iter()
+            .filter(|layer| !matches!(layer.name, ConfigLayerSource::User { .. }))
+            .cloned()
+            .collect::<Vec<_>>();
+        for user_layer in user_layers {
+            match layers
+                .iter()
+                .position(|layer| layer.name.precedence() > user_layer.name.precedence())
+            {
+                Some(index) => layers.insert(index, user_layer),
+                None => layers.push(user_layer),
+            }
+        }
+        Self {
+            layers,
+            model_provider_requirements: self.model_provider_requirements.clone(),
+            requirements: self.requirements.clone(),
+            requirements_toml: self.requirements_toml.clone(),
+            ignore_user_and_project_exec_policy_rules: self
+                .ignore_user_and_project_exec_policy_rules,
+            startup_warnings: self.startup_warnings.clone(),
+        }
+    }
+
+    /// Returns the merged config-layer view.
+    ///
+    /// Required provider definitions replace local entries before deserialization.
+    /// Selection and other requirements are applied when constructing the final config.
+    pub fn effective_config(&self) -> TomlValue {
+        let mut merged = TomlValue::Table(toml::map::Map::new());
+        for layer in self.layers_low_to_high() {
+            merge_toml_values(&mut merged, &layer.config);
+        }
+        if let Some(requirements) = &self.model_provider_requirements {
+            crate::model_provider_requirements::apply(&mut merged, requirements);
+        }
+        merged
+    }
+
+    /// Required provider selection used when building the effective configuration.
+    pub fn required_model_provider(&self) -> Option<&str> {
+        self.requirements_toml.model_provider.as_deref()
+    }
+
+    /// Returns field origins for the merged config-layer view.
+    ///
+    /// Requirement sources are tracked separately and are not included here.
+    pub fn origins(&self) -> HashMap<String, ConfigLayerMetadata> {
+        self.origins_with_path_filter(|_| true)
+    }
+
+    /// Filters origins using their original TOML key segments before formatting
+    /// them for the public API, where dots in quoted keys are ambiguous.
+    pub fn origins_with_path_filter(
+        &self,
+        include: impl Fn(&[String]) -> bool,
+    ) -> HashMap<String, ConfigLayerMetadata> {
+        let mut origins = HashMap::new();
+        let mut path = Vec::new();
+        let mut provider_paths = vec!["features.network_proxy.credentials.".to_string()];
+
+        for layer in self.layers_low_to_high() {
+            let config = normalized_with_key_aliases(&layer.config, &[]);
+            if let Some(profiles) = config.get("profiles").and_then(TomlValue::as_table) {
+                provider_paths.extend(
+                    profiles
+                        .keys()
+                        .map(|name| format!("profiles.{name}.features.network_proxy.credentials.")),
+                );
+            }
+            record_origins(
+                &config,
+                &layer.metadata(),
+                &mut path,
+                &mut origins,
+                &include,
+            );
+        }
+
+        if let Some(layer) = self.layers_low_to_high().next_back() {
+            let effective = self.effective_config();
+            let mut effective_origins = HashMap::new();
+            record_origins(
+                &effective,
+                &layer.metadata(),
+                &mut path,
+                &mut effective_origins,
+                &include,
+            );
+            origins.retain(|path, _| {
+                !provider_paths.iter().any(|prefix| path.starts_with(prefix))
+                    || effective_origins.contains_key(path)
+            });
+        }
+
+        origins
+    }
+
+    /// Returns enabled config layers from lowest precedence to highest.
+    ///
+    /// Requirement sources are tracked separately and are not included here.
+    pub fn layers_low_to_high(&self) -> impl DoubleEndedIterator<Item = &ConfigLayerEntry> {
+        self.all_layers_low_to_high()
+            .filter(|layer| !layer.is_disabled())
+    }
+
+    /// Returns enabled config layers from highest precedence to lowest.
+    ///
+    /// Requirement sources are tracked separately and are not included here.
+    pub fn layers_high_to_low(&self) -> impl DoubleEndedIterator<Item = &ConfigLayerEntry> {
+        self.layers_low_to_high().rev()
+    }
+
+    /// Returns all config layers, including disabled layers, from lowest
+    /// precedence to highest.
+    ///
+    /// Requirement sources are tracked separately and are not included here.
+    pub fn all_layers_low_to_high(&self) -> impl DoubleEndedIterator<Item = &ConfigLayerEntry> {
+        self.layers.iter()
+    }
+
+    /// Returns all config layers, including disabled layers, from highest
+    /// precedence to lowest.
+    ///
+    /// Requirement sources are tracked separately and are not included here.
+    pub fn all_layers_high_to_low(&self) -> impl DoubleEndedIterator<Item = &ConfigLayerEntry> {
+        self.all_layers_low_to_high().rev()
+    }
+}
+
+/// Validates before merging so mixed forms and malformed filter entries cannot be normalized away.
+pub(crate) fn validate_enabled_config_layers(layers: &[ConfigLayerEntry]) -> std::io::Result<()> {
+    for layer in layers.iter().filter(|layer| !layer.is_disabled()) {
+        validate_shell_environment_policy_filter_config(&layer.config).map_err(|error| {
+            std::io::Error::new(
+                std::io::ErrorKind::InvalidData,
+                format!(
+                    "invalid shell environment policy in {}: {error}",
+                    format_config_layer_source(&layer.name, CONFIG_TOML_FILE)
+                ),
+            )
+        })?;
+    }
+    Ok(())
+}
+
+/// Ensures precedence ordering of config layers is correct.
+fn verify_layer_ordering(layers: &[ConfigLayerEntry]) -> std::io::Result<()> {
+    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",
+        ));
+    }
+
+    // The previous check ensured `layers` is sorted by precedence, so now we
+    // further verify that project layers are ordered from root to cwd. Multiple
+    // user layers are allowed so a profile override can layer on top of the base
+    // user config.
+    let mut previous_project_dot_codex_folder: Option<&AbsolutePathBuf> = None;
+    for layer in layers {
+        if let ConfigLayerSource::Project {
+            dot_codex_folder: current_project_dot_codex_folder,
+        } = &layer.name
+        {
+            if let Some(previous) = previous_project_dot_codex_folder {
+                let Some(parent) = previous.as_path().parent() else {
+                    return Err(std::io::Error::new(
+                        std::io::ErrorKind::InvalidData,
+                        "project layer has no parent directory",
+                    ));
+                };
+                if previous == current_project_dot_codex_folder
+                    || !current_project_dot_codex_folder
+                        .as_path()
+                        .ancestors()
+                        .any(|ancestor| ancestor == parent)
+                {
+                    return Err(std::io::Error::new(
+                        std::io::ErrorKind::InvalidData,
+                        "project layers are not ordered from root to cwd",
+                    ));
+                }
+            }
+            previous_project_dot_codex_folder = Some(current_project_dot_codex_folder);
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "state_tests.rs"]
+mod tests;

codex-rs/config/src/state_tests.rs

@@ -0,0 +1,398 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+fn test_user_config_path(temp_dir: &TempDir, file_name: &str) -> AbsolutePathBuf {
+    AbsolutePathBuf::from_absolute_path(temp_dir.path().join(file_name))
+        .expect("test user config path should be absolute")
+}
+
+#[test]
+fn origins_use_canonical_key_aliases() {
+    let layer = ConfigLayerEntry::new(
+        ConfigLayerSource::SessionFlags,
+        toml::from_str(
+            r#"
+[memories]
+no_memories_if_mcp_or_web_search = true
+"#,
+        )
+        .expect("config TOML should parse"),
+    );
+    let metadata = layer.metadata();
+    let stack = ConfigLayerStack::new(
+        vec![layer],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("single layer stack should be valid");
+
+    let origins = stack.origins();
+
+    assert_eq!(
+        origins.get("memories.disable_on_external_context"),
+        Some(&metadata)
+    );
+    assert!(
+        !origins.contains_key("memories.no_memories_if_mcp_or_web_search"),
+        "legacy key should be canonicalized before origin recording"
+    );
+}
+
+/// Legacy feature toggles own the semantic enabled leaf after layered merging.
+#[test]
+fn origins_attribute_multi_agent_v2_enabled_to_overriding_boolean_layer() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let user_layer = ConfigLayerEntry::new(
+        ConfigLayerSource::User {
+            file: test_user_config_path(&temp_dir, "config.toml"),
+            profile: None,
+        },
+        toml::from_str(
+            "[features.multi_agent_v2]\nenabled = true\nsubagent_usage_hint_text = \"keep\"\n",
+        )
+        .expect("user config"),
+    );
+    let user_metadata = user_layer.metadata();
+    let session_layer = ConfigLayerEntry::new(
+        ConfigLayerSource::SessionFlags,
+        toml::from_str("[features]\nmulti_agent_v2 = false\n").expect("session config"),
+    );
+    let session_metadata = session_layer.metadata();
+    let stack = ConfigLayerStack::new(
+        vec![user_layer, session_layer],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("layer stack should be valid");
+
+    let origins = stack.origins();
+
+    assert_eq!(
+        origins.get("features.multi_agent_v2.enabled"),
+        Some(&session_metadata)
+    );
+    assert_eq!(
+        origins.get("features.multi_agent_v2.subagent_usage_hint_text"),
+        Some(&user_metadata)
+    );
+}
+
+#[test]
+fn origins_omit_displaced_credential_providers() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    for scope in ["", "profiles.work."] {
+        let user = ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: test_user_config_path(&temp_dir, "config.toml"),
+                profile: None,
+            },
+            toml::from_str(&format!(
+                "[{scope}features.network_proxy.credentials.user_provider]\nenv = ['VENDOR_TOKEN']\n",
+            ))
+            .expect("user config"),
+        );
+        let session = ConfigLayerEntry::new(
+            ConfigLayerSource::SessionFlags,
+            toml::from_str(&format!(
+                "[{scope}features.network_proxy.credentials.session_provider]\nenv = ['VENDOR_TOKEN']\n",
+            ))
+            .expect("session config"),
+        );
+        let metadata = session.metadata();
+        let stack = ConfigLayerStack::new(
+            vec![user, session],
+            ConfigRequirements::default(),
+            ConfigRequirementsToml::default(),
+        )
+        .expect("valid layers");
+        assert_eq!(
+            stack.origins(),
+            HashMap::from([(
+                format!("{scope}features.network_proxy.credentials.session_provider.env.0"),
+                metadata
+            )])
+        );
+    }
+}
+
+#[test]
+fn enabled_layers_validate_shell_environment_policy() {
+    let layer = ConfigLayerEntry::new(
+        ConfigLayerSource::SessionFlags,
+        toml::from_str(
+            r#"
+[shell_environment_policy]
+exclude = ["LEGACY_*"]
+
+[shell_environment_policy.filters]
+"CANONICAL_*" = "include"
+"#,
+        )
+        .expect("session config"),
+    );
+
+    let error = ConfigLayerStack::new(
+        vec![layer],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect_err("enabled layers should be validated");
+
+    assert_eq!(error.kind(), std::io::ErrorKind::InvalidData);
+    assert!(
+        error
+            .to_string()
+            .contains("cannot mix `filters` with legacy `exclude` or `include_only`")
+    );
+}
+
+#[test]
+fn disabled_layers_do_not_validate_shell_environment_policy() {
+    let layer = ConfigLayerEntry::new_disabled(
+        ConfigLayerSource::Project {
+            dot_codex_folder: AbsolutePathBuf::from_absolute_path("/untrusted/.codex")
+                .expect("project path should be absolute"),
+        },
+        toml::from_str(
+            r#"
+[shell_environment_policy]
+exclude = ["LEGACY_*"]
+
+[shell_environment_policy.filters]
+"CANONICAL_*" = "include"
+"#,
+        )
+        .expect("project config"),
+        "project is untrusted",
+    );
+
+    ConfigLayerStack::new(
+        vec![layer],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("disabled layers should not be validated");
+}
+
+#[test]
+fn enabled_layers_only_validate_representation_sensitive_shell_policy_fields() {
+    let cases = [
+        r#"shell_environment_policy = 17"#,
+        r#"
+[shell_environment_policy]
+inherit = "invalid"
+set = ["invalid"]
+"#,
+    ];
+
+    for contents in cases {
+        let layer = ConfigLayerEntry::new(
+            ConfigLayerSource::SessionFlags,
+            toml::from_str(contents).expect("session config"),
+        );
+
+        ConfigLayerStack::new(
+            vec![layer],
+            ConfigRequirements::default(),
+            ConfigRequirementsToml::default(),
+        )
+        .expect("unrelated shell policy fields should retain normal overlay semantics");
+    }
+}
+
+#[test]
+fn with_user_config_rejects_malformed_shell_policy_filter_fields() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let config_file = test_user_config_path(&temp_dir, "config.toml");
+    let cases = [
+        r#"
+[shell_environment_policy]
+exclude = ["SECRET_*", 17]
+"#,
+        r#"
+[shell_environment_policy.filters]
+"SECRET_*" = "keep"
+"#,
+        r#"
+[shell_environment_policy]
+exclude = ["SECRET_*"]
+
+[shell_environment_policy.filters]
+"PATH" = "include"
+"#,
+        r#"
+[shell_environment_policy.filters]
+"SECRET_*" = "exclude"
+"secret_*" = "include"
+"#,
+    ];
+
+    for contents in cases {
+        let error = ConfigLayerStack::default()
+            .with_user_config(&config_file, toml::from_str(contents).expect("user config"))
+            .expect_err("malformed shell policy filter fields should be rejected");
+
+        assert_eq!(error.kind(), std::io::ErrorKind::InvalidData);
+    }
+}
+
+#[test]
+fn active_user_layer_is_highest_precedence_user_layer() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let base_file = test_user_config_path(&temp_dir, "config.toml");
+    let profile_file = test_user_config_path(&temp_dir, "work.config.toml");
+    let base_layer = ConfigLayerEntry::new(
+        ConfigLayerSource::User {
+            file: base_file,
+            profile: None,
+        },
+        toml::from_str(
+            r#"
+model = "base"
+approval_policy = "on-request"
+"#,
+        )
+        .expect("base config"),
+    );
+    let profile_layer = ConfigLayerEntry::new(
+        ConfigLayerSource::User {
+            file: profile_file.clone(),
+            profile: Some("work".to_string()),
+        },
+        toml::from_str(r#"model = "profile""#).expect("profile config"),
+    );
+    let stack = ConfigLayerStack::new(
+        vec![base_layer, profile_layer],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("multiple user layers should be valid");
+
+    assert_eq!(stack.get_user_config_file(), Some(&profile_file));
+    assert_eq!(
+        stack
+            .effective_user_config()
+            .expect("merged user config")
+            .get("model")
+            .and_then(toml::Value::as_str),
+        Some("profile")
+    );
+    assert_eq!(
+        stack
+            .effective_user_config()
+            .expect("merged user config")
+            .get("approval_policy")
+            .and_then(toml::Value::as_str),
+        Some("on-request")
+    );
+}
+
+#[test]
+fn layer_iterators_preserve_precedence_and_disabled_layers() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let user_source = ConfigLayerSource::User {
+        file: test_user_config_path(&temp_dir, "config.toml"),
+        profile: None,
+    };
+    let project_source = ConfigLayerSource::Project {
+        dot_codex_folder: test_user_config_path(&temp_dir, ".codex"),
+    };
+    let session_source = ConfigLayerSource::SessionFlags;
+    let empty_config = TomlValue::Table(toml::map::Map::new());
+    let stack = ConfigLayerStack::new(
+        vec![
+            ConfigLayerEntry::new(user_source.clone(), empty_config.clone()),
+            ConfigLayerEntry::new_disabled(
+                project_source.clone(),
+                empty_config.clone(),
+                "project is untrusted",
+            ),
+            ConfigLayerEntry::new(session_source.clone(), empty_config),
+        ],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("layer stack should be valid");
+
+    assert_eq!(
+        stack
+            .layers_low_to_high()
+            .map(|layer| &layer.name)
+            .collect::<Vec<_>>(),
+        vec![&user_source, &session_source]
+    );
+    assert_eq!(
+        stack
+            .layers_high_to_low()
+            .map(|layer| &layer.name)
+            .collect::<Vec<_>>(),
+        vec![&session_source, &user_source]
+    );
+    assert_eq!(
+        stack
+            .all_layers_low_to_high()
+            .map(|layer| &layer.name)
+            .collect::<Vec<_>>(),
+        vec![&user_source, &project_source, &session_source]
+    );
+    assert_eq!(
+        stack
+            .all_layers_high_to_low()
+            .map(|layer| &layer.name)
+            .collect::<Vec<_>>(),
+        vec![&session_source, &project_source, &user_source]
+    );
+}
+
+#[test]
+fn with_user_config_updates_matching_user_layer_without_replacing_active_profile() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let base_file = test_user_config_path(&temp_dir, "config.toml");
+    let profile_file = test_user_config_path(&temp_dir, "work.config.toml");
+    let base_layer = ConfigLayerEntry::new(
+        ConfigLayerSource::User {
+            file: base_file.clone(),
+            profile: None,
+        },
+        toml::from_str(r#"model = "base""#).expect("base config"),
+    );
+    let profile_layer = ConfigLayerEntry::new(
+        ConfigLayerSource::User {
+            file: profile_file.clone(),
+            profile: Some("work".to_string()),
+        },
+        toml::from_str(r#"approval_policy = "on-request""#).expect("profile config"),
+    );
+    let stack = ConfigLayerStack::new(
+        vec![base_layer, profile_layer],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("multiple user layers should be valid");
+
+    let updated = stack
+        .with_user_config(
+            &base_file,
+            toml::from_str(r#"model = "updated-base""#).expect("updated base config"),
+        )
+        .expect("updated user layer should be valid");
+
+    assert_eq!(updated.get_user_config_file(), Some(&profile_file));
+    assert_eq!(
+        updated
+            .effective_user_config()
+            .expect("merged user config")
+            .get("model")
+            .and_then(toml::Value::as_str),
+        Some("updated-base")
+    );
+    assert_eq!(
+        updated
+            .effective_user_config()
+            .expect("merged user config")
+            .get("approval_policy")
+            .and_then(toml::Value::as_str),
+        Some("on-request")
+    );
+}

codex-rs/config/src/strict_config_tests.rs

@@ -0,0 +1,203 @@
+use super::*;
+use crate::ConfigLayerEntry;
+use crate::ConfigLayerSource;
+use crate::ConfigRequirements;
+use crate::config_toml::ConfigToml;
+use crate::diagnostics::TextPosition;
+use crate::diagnostics::TextRange;
+use pretty_assertions::assert_eq;
+use std::path::PathBuf;
+
+#[test]
+fn ignored_toml_field_errors_accept_non_file_source_names() {
+    let source_name = "com.openai.codex:config_toml_base64";
+    let contents = r#"
+model = "gpt-5"
+unknown_key = true"#;
+
+    let value = toml::from_str::<TomlValue>(contents).expect("valid TOML");
+    let error = config_error_from_ignored_toml_value_fields_for_source_name::<ConfigToml>(
+        source_name,
+        contents,
+        value,
+    )
+    .expect("unknown field error");
+
+    assert_eq!(
+        error,
+        ConfigError::new(
+            PathBuf::from(source_name),
+            TextRange {
+                start: TextPosition { line: 3, column: 1 },
+                end: TextPosition {
+                    line: 3,
+                    column: 11,
+                },
+            },
+            "unknown configuration field `unknown_key`",
+        )
+    );
+}
+
+#[test]
+fn type_errors_take_precedence_over_ignored_fields() {
+    let path = Path::new("/tmp/config.toml");
+    let contents = r#"
+model_context_window = "wide"
+unknown_key = true"#;
+
+    let error =
+        config_error_from_ignored_toml_fields::<ConfigToml>(path, contents).expect("type error");
+
+    assert_eq!(
+        error,
+        ConfigError::new(
+            path.to_path_buf(),
+            TextRange {
+                start: TextPosition {
+                    line: 2,
+                    column: 24,
+                },
+                end: TextPosition {
+                    line: 2,
+                    column: 29,
+                },
+            },
+            "invalid type: string \"wide\", expected i64",
+        )
+    );
+}
+
+#[test]
+fn strict_config_rejects_unknown_feature_key() {
+    let path = Path::new("/tmp/config.toml");
+    let contents = r#"
+[features]
+foo = true"#;
+
+    let error = config_error_from_ignored_toml_fields::<ConfigToml>(path, contents)
+        .expect("unknown feature error");
+
+    assert_eq!(
+        error,
+        ConfigError::new(
+            path.to_path_buf(),
+            TextRange {
+                start: TextPosition { line: 3, column: 1 },
+                end: TextPosition { line: 3, column: 3 },
+            },
+            "unknown configuration field `features.foo`",
+        )
+    );
+}
+
+#[test]
+fn strict_config_accepts_tool_registry_config() {
+    let path = Path::new("/tmp/config.toml");
+
+    for contents in [
+        "[features.tool_registry]\nerror_on_tool_collisions = true\n",
+        "[profiles.work.features.tool_registry]\nerror_on_tool_collisions = true\n",
+        "[features.tool_registry]\nturn_metadata_includes_tool_info = true\n",
+        "[profiles.work.features.tool_registry]\nturn_metadata_includes_tool_info = true\n",
+    ] {
+        assert_eq!(
+            config_error_from_ignored_toml_fields::<ConfigToml>(path, contents),
+            None
+        );
+    }
+
+    assert!(
+        config_error_from_ignored_toml_fields::<ConfigToml>(
+            path,
+            "[features.tool_registry]\nunknown = true\n",
+        )
+        .is_some()
+    );
+}
+
+#[test]
+fn strict_config_rejects_unknown_profile_feature_key() {
+    let path = Path::new("/tmp/config.toml");
+    let contents = r#"
+[profiles.work.features]
+foo = true"#;
+
+    let error = config_error_from_ignored_toml_fields::<ConfigToml>(path, contents)
+        .expect("unknown feature error");
+
+    assert_eq!(
+        error,
+        ConfigError::new(
+            path.to_path_buf(),
+            TextRange {
+                start: TextPosition { line: 3, column: 1 },
+                end: TextPosition { line: 3, column: 3 },
+            },
+            "unknown configuration field `profiles.work.features.foo`",
+        )
+    );
+}
+
+#[test]
+fn strict_config_accepts_opaque_desktop_keys() {
+    let path = Path::new("/tmp/config.toml");
+    let contents = r#"
+[desktop]
+appearanceTheme = "dark"
+
+[desktop.workspace]
+collapsed = true"#;
+
+    let error = config_error_from_ignored_toml_fields::<ConfigToml>(path, contents);
+
+    assert_eq!(error, None);
+}
+
+fn layer(source: ConfigLayerSource, contents: &str) -> ConfigLayerEntry {
+    ConfigLayerEntry::new(source, toml::from_str(contents).unwrap())
+}
+
+#[test]
+fn checks_merged_config_and_ignores_disabled_layers() {
+    let layers = vec![
+        layer(
+            ConfigLayerSource::EnterpriseManaged {
+                id: "cfg".into(),
+                name: "Defaults".into(),
+            },
+            r#"
+[model_providers.custom]
+name = "Custom"
+wire_api = "responses"
+unknown_timeout = 1
+[model_providers.custom.http_headers]
+custom_header = "accepted"
+"#,
+        ),
+        ConfigLayerEntry::new_disabled(
+            ConfigLayerSource::SessionFlags,
+            toml::from_str("disabled_unknown = true").unwrap(),
+            "not trusted",
+        ),
+        layer(
+            ConfigLayerSource::SessionFlags,
+            r#"
+[model_providers.custom]
+unknown_timeout = 42
+[profiles.work.features]
+include_view_image_tool = false
+"#,
+        ),
+    ];
+    let config = ConfigLayerStack::new(
+        layers,
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .unwrap();
+    assert_eq!(
+        ignored_config_warning(&config, &[]).unwrap(),
+        "Codex is ignoring 3 unrecognized configuration settings. Check for typos or deprecated settings.\n  enterprise-managed (Defaults, cfg): `model_providers.custom.unknown_timeout` is ignored.\n  session-flags: `model_providers.custom.unknown_timeout` is ignored.\n  session-flags: `profiles.work.features.include_view_image_tool` is ignored. Use [features].view_image to configure the image tool."
+    );
+}

codex-rs/config/src/test_support.rs

@@ -0,0 +1,80 @@
+//! Test-only helpers exposed for cross-crate integration tests.
+//!
+//! Production code should not depend on this module.
+
+use crate::CloudConfigBundle;
+use crate::CloudConfigBundleLoader;
+use crate::CloudConfigFragment;
+use crate::CloudRequirementsFragment;
+
+#[derive(Debug, Clone, Default)]
+pub struct CloudConfigBundleFixture {
+    bundle: CloudConfigBundle,
+}
+
+impl CloudConfigBundleFixture {
+    pub fn enterprise_requirement(contents: impl Into<String>) -> Self {
+        Self::default().add_enterprise_requirement(contents)
+    }
+
+    pub fn enterprise_config(contents: impl Into<String>) -> Self {
+        Self::default().add_enterprise_config(contents)
+    }
+
+    pub fn loader_with_enterprise_requirement(
+        contents: impl Into<String>,
+    ) -> CloudConfigBundleLoader {
+        Self::enterprise_requirement(contents).into_loader()
+    }
+
+    pub fn loader_with_enterprise_config(contents: impl Into<String>) -> CloudConfigBundleLoader {
+        Self::enterprise_config(contents).into_loader()
+    }
+
+    pub fn add_enterprise_requirement(mut self, contents: impl Into<String>) -> Self {
+        let index = self.bundle.requirements_toml.enterprise_managed.len() + 1;
+        self.bundle
+            .requirements_toml
+            .enterprise_managed
+            .push(CloudRequirementsFragment {
+                id: format!("req_{index}"),
+                name: if index == 1 {
+                    "Base requirements".to_string()
+                } else {
+                    format!("Requirements {index}")
+                },
+                contents: contents.into(),
+            });
+        self
+    }
+
+    pub fn add_enterprise_config(mut self, contents: impl Into<String>) -> Self {
+        let index = self.bundle.config_toml.enterprise_managed.len() + 1;
+        self.bundle
+            .config_toml
+            .enterprise_managed
+            .push(CloudConfigFragment {
+                id: format!("cfg_{index}"),
+                name: if index == 1 {
+                    "Base config".to_string()
+                } else {
+                    format!("Config {index}")
+                },
+                contents: contents.into(),
+            });
+        self
+    }
+
+    pub fn into_bundle(self) -> CloudConfigBundle {
+        self.bundle
+    }
+
+    pub fn into_loader(self) -> CloudConfigBundleLoader {
+        let bundle = self.into_bundle();
+        CloudConfigBundleLoader::new(async move { Ok(Some(bundle)) })
+    }
+}
+
+#[cfg(test)]
+#[path = "test_support_tests.rs"]
+mod tests;

codex-rs/config/src/thread_config.rs

@@ -0,0 +1,319 @@
+use std::collections::BTreeMap;
+use std::collections::HashMap;
+use std::future::Future;
+use std::pin::Pin;
+
+use crate::ConfigLayerSource;
+use codex_model_provider_info::ModelProviderInfo;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use thiserror::Error;
+use toml::Value as TomlValue;
+
+use crate::ConfigLayerEntry;
+
+mod remote;
+
+pub use remote::RemoteThreadConfigLoader;
+
+/// Context available to implementations when loading thread-scoped config.
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct ThreadConfigContext {
+    pub thread_id: Option<String>,
+    pub cwd: Option<AbsolutePathBuf>,
+}
+
+/// Config values owned by the service that starts or manages the session.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct SessionThreadConfig {
+    pub model_provider: Option<String>,
+    pub model_providers: HashMap<String, ModelProviderInfo>,
+    pub features: BTreeMap<String, bool>,
+}
+
+/// Config values owned by the authenticated user.
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct UserThreadConfig {}
+
+/// A typed config payload paired with the authority that produced it.
+#[derive(Clone, Debug, PartialEq)]
+pub enum ThreadConfigSource {
+    Session(SessionThreadConfig),
+    User(UserThreadConfig),
+}
+
+/// Stable category for failures returned while loading thread config.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ThreadConfigLoadErrorCode {
+    Auth,
+    Timeout,
+    Parse,
+    RequestFailed,
+    Internal,
+}
+
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+#[error("{message}")]
+pub struct ThreadConfigLoadError {
+    code: ThreadConfigLoadErrorCode,
+    message: String,
+    status_code: Option<u16>,
+}
+
+impl ThreadConfigLoadError {
+    pub fn new(
+        code: ThreadConfigLoadErrorCode,
+        status_code: Option<u16>,
+        message: impl Into<String>,
+    ) -> Self {
+        Self {
+            code,
+            message: message.into(),
+            status_code,
+        }
+    }
+
+    pub fn code(&self) -> ThreadConfigLoadErrorCode {
+        self.code
+    }
+}
+
+/// Loads typed config sources for a new thread.
+///
+/// Implementations should fetch only the source-specific config they own and
+/// return typed payloads without applying precedence or merge rules. Callers
+/// are responsible for resolving the returned sources into the effective
+/// runtime config.
+pub trait ThreadConfigLoader: Send + Sync {
+    /// Load source-specific typed config.
+    ///
+    /// Implementations should keep this method focused on fetching and parsing
+    /// their owned sources. Most callers should use [`Self::load_config_layers`]
+    /// so precedence and merging continue through the ordinary config layer
+    /// stack.
+    fn load(
+        &self,
+        context: ThreadConfigContext,
+    ) -> ThreadConfigLoaderFuture<'_, Vec<ThreadConfigSource>>;
+
+    fn load_config_layers(
+        &self,
+        context: ThreadConfigContext,
+    ) -> ThreadConfigLoaderFuture<'_, Vec<ConfigLayerEntry>> {
+        Box::pin(async move {
+            let sources = self.load(context).await?;
+            sources
+                .into_iter()
+                .map(thread_config_source_to_layer)
+                .collect::<Result<Vec<_>, _>>()
+                .map(|layers| layers.into_iter().flatten().collect())
+        })
+    }
+}
+
+pub type ThreadConfigLoaderFuture<'a, T> =
+    Pin<Box<dyn Future<Output = Result<T, ThreadConfigLoadError>> + Send + 'a>>;
+
+/// Loader backed by a static set of typed thread config sources.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct StaticThreadConfigLoader {
+    sources: Vec<ThreadConfigSource>,
+}
+
+impl StaticThreadConfigLoader {
+    pub fn new(sources: Vec<ThreadConfigSource>) -> Self {
+        Self { sources }
+    }
+}
+
+impl ThreadConfigLoader for StaticThreadConfigLoader {
+    fn load(
+        &self,
+        _context: ThreadConfigContext,
+    ) -> ThreadConfigLoaderFuture<'_, Vec<ThreadConfigSource>> {
+        Box::pin(async { Ok(self.sources.clone()) })
+    }
+}
+
+/// Loader used when no external thread config source is configured.
+#[derive(Clone, Debug, Default)]
+pub struct NoopThreadConfigLoader;
+
+impl ThreadConfigLoader for NoopThreadConfigLoader {
+    fn load(
+        &self,
+        _context: ThreadConfigContext,
+    ) -> ThreadConfigLoaderFuture<'_, Vec<ThreadConfigSource>> {
+        Box::pin(async { Ok(Vec::new()) })
+    }
+}
+
+fn thread_config_source_to_layer(
+    source: ThreadConfigSource,
+) -> Result<Option<ConfigLayerEntry>, ThreadConfigLoadError> {
+    match source {
+        ThreadConfigSource::Session(config) => {
+            let config = session_thread_config_to_toml(config)?;
+            if is_empty_table(&config) {
+                Ok(None)
+            } else {
+                Ok(Some(ConfigLayerEntry::new(
+                    ConfigLayerSource::SessionFlags,
+                    config,
+                )))
+            }
+        }
+        // UserThreadConfig has no TOML-backed fields yet. When it grows one,
+        // fold it into the existing user layer instead of adding another
+        // ConfigLayerSource variant.
+        ThreadConfigSource::User(_config) => Ok(None),
+    }
+}
+
+fn is_empty_table(config: &TomlValue) -> bool {
+    config.as_table().is_some_and(toml::map::Map::is_empty)
+}
+
+fn session_thread_config_to_toml(
+    config: SessionThreadConfig,
+) -> Result<TomlValue, ThreadConfigLoadError> {
+    let mut table = toml::map::Map::new();
+
+    if let Some(model_provider) = config.model_provider {
+        table.insert(
+            "model_provider".to_string(),
+            TomlValue::String(model_provider),
+        );
+    }
+
+    if !config.model_providers.is_empty() {
+        let model_providers = TomlValue::try_from(config.model_providers).map_err(|err| {
+            ThreadConfigLoadError::new(
+                ThreadConfigLoadErrorCode::Parse,
+                /*status_code*/ None,
+                format!("failed to convert session model providers to config TOML: {err}"),
+            )
+        })?;
+        table.insert("model_providers".to_string(), model_providers);
+    }
+
+    if !config.features.is_empty() {
+        let features = config
+            .features
+            .into_iter()
+            .map(|(feature, enabled)| (feature, TomlValue::Boolean(enabled)))
+            .collect();
+        table.insert("features".to_string(), TomlValue::Table(features));
+    }
+
+    Ok(TomlValue::Table(table))
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_model_provider_info::ModelProviderInfo;
+    use codex_model_provider_info::WireApi;
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[tokio::test]
+    async fn loader_returns_session_and_user_sources() {
+        let loader = StaticThreadConfigLoader::new(vec![
+            ThreadConfigSource::Session(SessionThreadConfig {
+                model_provider: Some("local".to_string()),
+                model_providers: HashMap::from([("local".to_string(), test_provider("local"))]),
+                features: BTreeMap::from([("plugins".to_string(), false)]),
+            }),
+            ThreadConfigSource::User(UserThreadConfig::default()),
+        ]);
+
+        let sources = loader
+            .load(ThreadConfigContext {
+                thread_id: Some("thread-1".to_string()),
+                ..Default::default()
+            })
+            .await
+            .expect("thread config loads");
+
+        assert_eq!(
+            sources,
+            vec![
+                ThreadConfigSource::Session(SessionThreadConfig {
+                    model_provider: Some("local".to_string()),
+                    model_providers: HashMap::from([("local".to_string(), test_provider("local"))]),
+                    features: BTreeMap::from([("plugins".to_string(), false)]),
+                }),
+                ThreadConfigSource::User(UserThreadConfig::default()),
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn loader_translates_sources_to_config_layers() {
+        let loader = StaticThreadConfigLoader::new(vec![
+            ThreadConfigSource::User(UserThreadConfig::default()),
+            ThreadConfigSource::Session(SessionThreadConfig {
+                model_provider: Some("local".to_string()),
+                model_providers: HashMap::from([("local".to_string(), test_provider("local"))]),
+                features: BTreeMap::from([("plugins".to_string(), false)]),
+            }),
+        ]);
+        let layers = loader
+            .load_config_layers(ThreadConfigContext {
+                cwd: Some(
+                    AbsolutePathBuf::from_absolute_path_checked(
+                        std::env::temp_dir().join("project"),
+                    )
+                    .expect("absolute cwd"),
+                ),
+                ..Default::default()
+            })
+            .await
+            .expect("thread config layers load");
+
+        assert_eq!(
+            layers,
+            vec![ConfigLayerEntry::new(
+                ConfigLayerSource::SessionFlags,
+                toml::toml! {
+                    model_provider = "local"
+
+                    [model_providers.local]
+                    name = "local"
+                    base_url = "http://127.0.0.1:8061/api/codex"
+                    wire_api = "responses"
+                    requires_openai_auth = false
+                    supports_websockets = true
+                    supports_standalone_web_search = true
+
+                    [features]
+                    plugins = false
+                }
+                .into()
+            )]
+        );
+    }
+
+    fn test_provider(name: &str) -> ModelProviderInfo {
+        ModelProviderInfo {
+            name: name.to_string(),
+            base_url: Some("http://127.0.0.1:8061/api/codex".to_string()),
+            env_key: None,
+            env_key_instructions: None,
+            experimental_bearer_token: None,
+            auth: None,
+            aws: None,
+            wire_api: WireApi::Responses,
+            query_params: None,
+            http_headers: None,
+            env_http_headers: None,
+            request_max_retries: None,
+            stream_max_retries: None,
+            stream_idle_timeout_ms: None,
+            websocket_connect_timeout_ms: None,
+            requires_openai_auth: false,
+            supports_websockets: true,
+            supports_standalone_web_search: true,
+        }
+    }
+}

codex-rs/config/src/types.rs

@@ -0,0 +1,1057 @@
+//! Types used to define loaded and effective Codex configuration values.
+
+// Note this file should generally be restricted to simple struct/enum
+// definitions that do not contain business logic.
+
+pub use crate::mcp_ema::McpEnterpriseManagedAuthConfig;
+pub use crate::mcp_ema::McpServerIdpOAuthConfig;
+pub use crate::mcp_types::AppToolApproval;
+pub use crate::mcp_types::McpServerAuth;
+pub use crate::mcp_types::McpServerConfig;
+pub use crate::mcp_types::McpServerDisabledReason;
+pub use crate::mcp_types::McpServerEnvVar;
+pub use crate::mcp_types::McpServerOAuthConfig;
+pub use crate::mcp_types::McpServerToolConfig;
+pub use crate::mcp_types::McpServerTransportConfig;
+pub use crate::mcp_types::RawMcpServerConfig;
+pub use crate::shell_environment_policy::ShellEnvironmentPolicyToml;
+pub use codex_protocol::config_types::AltScreenMode;
+pub use codex_protocol::config_types::ApprovalsReviewer;
+pub use codex_protocol::config_types::ModeKind;
+pub use codex_protocol::config_types::Personality;
+pub use codex_protocol::config_types::ServiceTier;
+pub use codex_protocol::config_types::WebSearchMode;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::collections::BTreeMap;
+use std::collections::HashMap;
+use std::fmt;
+
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+
+pub use crate::tui_keymap::KeybindingSpec;
+pub use crate::tui_keymap::KeybindingsSpec;
+pub use crate::tui_keymap::MAX_FUNCTION_KEY;
+pub use crate::tui_keymap::TuiAgentsKeymap;
+pub use crate::tui_keymap::TuiApprovalKeymap;
+pub use crate::tui_keymap::TuiChatKeymap;
+pub use crate::tui_keymap::TuiComposerKeymap;
+pub use crate::tui_keymap::TuiEditorKeymap;
+pub use crate::tui_keymap::TuiGlobalKeymap;
+pub use crate::tui_keymap::TuiKeymap;
+pub use crate::tui_keymap::TuiListKeymap;
+pub use crate::tui_keymap::TuiPagerKeymap;
+pub use crate::tui_keymap::TuiVimNormalKeymap;
+pub use crate::tui_keymap::TuiVimOperatorKeymap;
+pub use crate::tui_keymap::TuiVimSearchKeymap;
+
+pub const DEFAULT_OTEL_ENVIRONMENT: &str = "dev";
+pub const DEFAULT_MEMORIES_MAX_ROLLOUTS_PER_STARTUP: usize = 2;
+pub const DEFAULT_MEMORIES_MAX_ROLLOUT_AGE_DAYS: i64 = 10;
+pub const DEFAULT_MEMORIES_MIN_ROLLOUT_IDLE_HOURS: i64 = 6;
+pub const DEFAULT_MEMORIES_MIN_RATE_LIMIT_REMAINING_PERCENT: i64 = 25;
+pub const DEFAULT_MEMORIES_MAX_RAW_MEMORIES_FOR_CONSOLIDATION: usize = 256;
+pub const DEFAULT_MEMORIES_MAX_UNUSED_DAYS: i64 = 30;
+const MIN_MEMORIES_MAX_RAW_MEMORIES_FOR_CONSOLIDATION: usize = 1;
+const MAX_MEMORIES_MAX_RAW_MEMORIES_FOR_CONSOLIDATION: usize = 4096;
+const MIN_MEMORIES_MAX_ROLLOUTS_PER_STARTUP: usize = 1;
+const MAX_MEMORIES_MAX_ROLLOUTS_PER_STARTUP: usize = 128;
+
+const fn default_enabled() -> bool {
+    true
+}
+
+/// Preferred layout for the resume/fork session picker.
+#[derive(Serialize, Deserialize, Debug, Default, Copy, Clone, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "kebab-case")]
+pub enum SessionPickerViewMode {
+    Comfortable,
+    #[default]
+    Dense,
+}
+
+impl SessionPickerViewMode {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Comfortable => "comfortable",
+            Self::Dense => "dense",
+        }
+    }
+}
+
+impl fmt::Display for SessionPickerViewMode {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
+/// Working directory to use when resuming or forking a session.
+#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "kebab-case")]
+pub enum ResumeCwdMode {
+    /// Use the directory where Codex was launched.
+    Current,
+    /// Use the latest working directory recorded in the selected session.
+    Session,
+}
+
+impl ResumeCwdMode {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Current => "current",
+            Self::Session => "session",
+        }
+    }
+}
+
+/// Determine where Codex should store CLI auth credentials.
+#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum AuthCredentialsStoreMode {
+    #[default]
+    /// Persist credentials in CODEX_HOME/auth.json.
+    File,
+    /// Persist credentials in the keyring. Fail if unavailable.
+    Keyring,
+    /// Use keyring when available; otherwise, fall back to a file in CODEX_HOME.
+    Auto,
+    /// Store credentials in memory only for the current process.
+    Ephemeral,
+}
+
+/// Determine where Codex should store and read MCP credentials.
+#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum OAuthCredentialsStoreMode {
+    /// Prefer `Keyring` and use `File` when keyring storage is unavailable.
+    /// Once an MCP client loads credentials from one store, that client keeps the resolved store
+    /// for its lifetime so refreshes cannot switch to a possibly stale credential source.
+    /// Credentials stored in the keyring will only be readable by Codex unless the user explicitly grants access via OS-level keyring access.
+    #[default]
+    Auto,
+    /// CODEX_HOME/.credentials.json
+    /// This file will be readable to Codex and other applications running as the same user.
+    File,
+    /// Keyring when available, otherwise fail.
+    Keyring,
+}
+
+/// Determine how auth credentials should use keyring-backed storage.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum AuthKeyringBackendKind {
+    /// Store the serialized auth payload directly in the OS keyring.
+    Direct,
+    /// Store auth payloads in the local encrypted secrets file, with the file key in the OS keyring.
+    Secrets,
+}
+
+impl Default for AuthKeyringBackendKind {
+    fn default() -> Self {
+        if cfg!(windows) {
+            Self::Secrets
+        } else {
+            Self::Direct
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "kebab-case")]
+pub enum WindowsSandboxModeToml {
+    Elevated,
+    Unelevated,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct WindowsToml {
+    pub sandbox: Option<WindowsSandboxModeToml>,
+    /// Defaults to `true`. Set to `false` to launch the final sandboxed child
+    /// process on `Winsta0\\Default` instead of a private desktop.
+    pub sandbox_private_desktop: Option<bool>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, JsonSchema)]
+pub enum UriBasedFileOpener {
+    #[serde(rename = "vscode")]
+    VsCode,
+
+    #[serde(rename = "vscode-insiders")]
+    VsCodeInsiders,
+
+    #[serde(rename = "windsurf")]
+    Windsurf,
+
+    #[serde(rename = "cursor")]
+    Cursor,
+
+    /// Option to disable the URI-based file opener.
+    #[serde(rename = "none")]
+    None,
+}
+
+/// Settings that govern if and what will be written to `~/.codex/history.jsonl`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[serde(default)]
+#[schemars(deny_unknown_fields)]
+pub struct History {
+    /// If true, history entries will not be written to disk.
+    pub persistence: HistoryPersistence,
+
+    /// If set, the maximum size of the history file in bytes. The oldest entries
+    /// are dropped once the file exceeds this limit.
+    pub max_bytes: Option<usize>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Default, JsonSchema)]
+#[serde(rename_all = "kebab-case")]
+pub enum HistoryPersistence {
+    /// Save all history entries to disk.
+    #[default]
+    SaveAll,
+    /// Do not write history to disk.
+    None,
+}
+
+// ===== Analytics configuration =====
+
+/// Analytics settings loaded from config.toml. Fields are optional so we can apply defaults.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AnalyticsConfigToml {
+    /// When `false`, disables analytics across Codex product surfaces in this profile.
+    pub enabled: Option<bool>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct FeedbackConfigToml {
+    /// When `false`, disables the feedback flow across Codex product surfaces.
+    pub enabled: Option<bool>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Hash, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum ToolSuggestDiscoverableType {
+    Connector,
+    Plugin,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Hash, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ToolSuggestDiscoverable {
+    #[serde(rename = "type")]
+    pub kind: ToolSuggestDiscoverableType,
+    pub id: String,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Hash, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ToolSuggestDisabledTool {
+    #[serde(rename = "type")]
+    pub kind: ToolSuggestDiscoverableType,
+    pub id: String,
+}
+
+impl ToolSuggestDisabledTool {
+    pub fn plugin(id: impl Into<String>) -> Self {
+        Self {
+            kind: ToolSuggestDiscoverableType::Plugin,
+            id: id.into(),
+        }
+    }
+
+    pub fn connector(id: impl Into<String>) -> Self {
+        Self {
+            kind: ToolSuggestDiscoverableType::Connector,
+            id: id.into(),
+        }
+    }
+
+    pub fn normalized(&self) -> Option<Self> {
+        let id = self.id.trim();
+        (!id.is_empty()).then(|| Self {
+            kind: self.kind,
+            id: id.to_string(),
+        })
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ToolSuggestConfig {
+    #[serde(default)]
+    pub discoverables: Vec<ToolSuggestDiscoverable>,
+    #[serde(default)]
+    pub disabled_tools: Vec<ToolSuggestDisabledTool>,
+}
+
+pub use codex_protocol::MemoryVersion;
+
+/// Memories settings loaded from config.toml.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct MemoriesToml {
+    /// Selects the memory pipeline; v1 remains the default.
+    pub version: Option<MemoryVersion>,
+    /// Generate both versions while the selected version supplies context.
+    pub dual_write: Option<bool>,
+    /// When `true`, external context sources mark the thread `memory_mode` as `"polluted"`.
+    #[serde(alias = "no_memories_if_mcp_or_web_search")]
+    pub disable_on_external_context: Option<bool>,
+    /// When `false`, newly created threads are stored with `memory_mode = "disabled"` in the state DB.
+    pub generate_memories: Option<bool>,
+    /// When `false`, skip injecting memory usage instructions into developer prompts.
+    pub use_memories: Option<bool>,
+    /// When `true`, expose dedicated memory tools through the extension tool surface.
+    pub dedicated_tools: Option<bool>,
+    /// Maximum number of recent raw memories retained for global consolidation.
+    #[schemars(range(min = 1, max = 4096))]
+    pub max_raw_memories_for_consolidation: Option<usize>,
+    /// Maximum number of days since a memory was last used before it becomes ineligible for phase 2 selection.
+    pub max_unused_days: Option<i64>,
+    /// Maximum age of the threads used for memories.
+    pub max_rollout_age_days: Option<i64>,
+    /// Maximum number of rollout candidates processed per pass.
+    #[schemars(range(min = 1, max = 128))]
+    pub max_rollouts_per_startup: Option<usize>,
+    /// Minimum idle time between last thread activity and memory creation (hours). > 12h recommended.
+    pub min_rollout_idle_hours: Option<i64>,
+    /// Minimum remaining percentage required in Codex rate-limit windows before memory startup runs.
+    #[schemars(range(min = 0, max = 100))]
+    pub min_rate_limit_remaining_percent: Option<i64>,
+    /// Model used for thread summarisation.
+    pub extract_model: Option<String>,
+    /// Model used for memory consolidation.
+    pub consolidation_model: Option<String>,
+}
+
+/// Effective memories settings after defaults are applied.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct MemoriesConfig {
+    pub version: MemoryVersion,
+    pub dual_write: bool,
+    pub disable_on_external_context: bool,
+    pub generate_memories: bool,
+    pub use_memories: bool,
+    pub dedicated_tools: bool,
+    pub max_raw_memories_for_consolidation: usize,
+    pub max_unused_days: i64,
+    pub max_rollout_age_days: i64,
+    pub max_rollouts_per_startup: usize,
+    pub min_rollout_idle_hours: i64,
+    pub min_rate_limit_remaining_percent: i64,
+    pub extract_model: Option<String>,
+    pub consolidation_model: Option<String>,
+}
+
+impl Default for MemoriesConfig {
+    fn default() -> Self {
+        Self {
+            version: MemoryVersion::V1,
+            dual_write: false,
+            disable_on_external_context: false,
+            generate_memories: true,
+            use_memories: true,
+            dedicated_tools: false,
+            max_raw_memories_for_consolidation: DEFAULT_MEMORIES_MAX_RAW_MEMORIES_FOR_CONSOLIDATION,
+            max_unused_days: DEFAULT_MEMORIES_MAX_UNUSED_DAYS,
+            max_rollout_age_days: DEFAULT_MEMORIES_MAX_ROLLOUT_AGE_DAYS,
+            max_rollouts_per_startup: DEFAULT_MEMORIES_MAX_ROLLOUTS_PER_STARTUP,
+            min_rollout_idle_hours: DEFAULT_MEMORIES_MIN_ROLLOUT_IDLE_HOURS,
+            min_rate_limit_remaining_percent: DEFAULT_MEMORIES_MIN_RATE_LIMIT_REMAINING_PERCENT,
+            extract_model: None,
+            consolidation_model: None,
+        }
+    }
+}
+
+impl From<MemoriesToml> for MemoriesConfig {
+    fn from(toml: MemoriesToml) -> Self {
+        let defaults = Self::default();
+        Self {
+            version: toml.version.unwrap_or(defaults.version),
+            dual_write: toml.dual_write.unwrap_or(defaults.dual_write),
+            disable_on_external_context: toml
+                .disable_on_external_context
+                .unwrap_or(defaults.disable_on_external_context),
+            generate_memories: toml.generate_memories.unwrap_or(defaults.generate_memories),
+            use_memories: toml.use_memories.unwrap_or(defaults.use_memories),
+            dedicated_tools: toml.dedicated_tools.unwrap_or(defaults.dedicated_tools),
+            max_raw_memories_for_consolidation: toml
+                .max_raw_memories_for_consolidation
+                .unwrap_or(defaults.max_raw_memories_for_consolidation)
+                .clamp(
+                    MIN_MEMORIES_MAX_RAW_MEMORIES_FOR_CONSOLIDATION,
+                    MAX_MEMORIES_MAX_RAW_MEMORIES_FOR_CONSOLIDATION,
+                ),
+            max_unused_days: toml
+                .max_unused_days
+                .unwrap_or(defaults.max_unused_days)
+                .clamp(0, 365),
+            max_rollout_age_days: toml
+                .max_rollout_age_days
+                .unwrap_or(defaults.max_rollout_age_days)
+                .clamp(0, 90),
+            max_rollouts_per_startup: toml
+                .max_rollouts_per_startup
+                .unwrap_or(defaults.max_rollouts_per_startup)
+                .clamp(
+                    MIN_MEMORIES_MAX_ROLLOUTS_PER_STARTUP,
+                    MAX_MEMORIES_MAX_ROLLOUTS_PER_STARTUP,
+                ),
+            min_rollout_idle_hours: toml
+                .min_rollout_idle_hours
+                .unwrap_or(defaults.min_rollout_idle_hours)
+                .clamp(1, 48),
+            min_rate_limit_remaining_percent: toml
+                .min_rate_limit_remaining_percent
+                .unwrap_or(defaults.min_rate_limit_remaining_percent)
+                .clamp(0, 100),
+            extract_model: toml.extract_model,
+            consolidation_model: toml.consolidation_model,
+        }
+    }
+}
+
+/// Default settings that apply to all apps.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppsDefaultConfig {
+    /// When `false`, apps are disabled unless overridden by per-app settings.
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+
+    /// Reviewer for approval prompts unless overridden by per-app settings.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
+
+    /// Whether tools with `destructive_hint = true` are allowed by default.
+    #[serde(
+        default = "default_enabled",
+        skip_serializing_if = "std::clone::Clone::clone"
+    )]
+    pub destructive_enabled: bool,
+
+    /// Whether tools with `open_world_hint = true` are allowed by default.
+    #[serde(
+        default = "default_enabled",
+        skip_serializing_if = "std::clone::Clone::clone"
+    )]
+    pub open_world_enabled: bool,
+
+    /// Approval mode for tools unless overridden by per-app or per-tool settings.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default_tools_approval_mode: Option<AppToolApproval>,
+}
+
+/// Per-tool settings for a single app tool.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppToolConfig {
+    /// Whether this tool is enabled. `Some(true)` explicitly allows this tool.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enabled: Option<bool>,
+
+    /// Approval mode for this tool.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub approval_mode: Option<AppToolApproval>,
+}
+
+/// Tool settings for a single app.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppToolsConfig {
+    /// Per-tool overrides keyed by tool name (for example `repos/list`).
+    #[serde(default, flatten)]
+    pub tools: HashMap<String, AppToolConfig>,
+}
+
+/// Approval settings for a connected account within an app.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppLinkConfig {
+    /// Reviewer for approval prompts from this account, overriding the app default.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
+
+    /// Approval mode for this account unless a tool override exists.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default_tools_approval_mode: Option<AppToolApproval>,
+}
+
+/// Account settings for a single app.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppLinksConfig {
+    /// Per-account approval settings keyed by link ID.
+    #[serde(default, flatten)]
+    pub links: HashMap<String, AppLinkConfig>,
+}
+
+/// Config values for a single app/connector.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppConfig {
+    /// When `false`, Codex does not surface this app.
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+
+    /// Reviewer for approval prompts from this app, overriding the thread default.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub approvals_reviewer: Option<ApprovalsReviewer>,
+
+    /// Whether tools with `destructive_hint = true` are allowed for this app.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub destructive_enabled: Option<bool>,
+
+    /// Whether tools with `open_world_hint = true` are allowed for this app.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub open_world_enabled: Option<bool>,
+
+    /// Approval mode for tools in this app unless a tool override exists.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default_tools_approval_mode: Option<AppToolApproval>,
+
+    /// Whether tools are enabled by default for this app.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default_tools_enabled: Option<bool>,
+
+    /// Per-tool settings for this app.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tools: Option<AppToolsConfig>,
+
+    /// Per-account approval settings keyed by link ID.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub links: Option<AppLinksConfig>,
+}
+
+/// App/connector settings loaded from `config.toml`.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AppsConfigToml {
+    /// Default settings for all apps.
+    #[serde(default, rename = "_default", skip_serializing_if = "Option::is_none")]
+    pub default: Option<AppsDefaultConfig>,
+
+    /// Per-app settings keyed by app ID (for example `[apps.google_drive]`).
+    #[serde(default, flatten)]
+    pub apps: HashMap<String, AppConfig>,
+}
+
+// ===== OTEL configuration =====
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
+#[serde(rename_all = "kebab-case")]
+pub enum OtelHttpProtocol {
+    /// Binary payload
+    Binary,
+    /// JSON payload
+    Json,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+#[serde(rename_all = "kebab-case")]
+pub struct OtelTlsConfig {
+    pub ca_certificate: Option<AbsolutePathBuf>,
+    pub client_certificate: Option<AbsolutePathBuf>,
+    pub client_private_key: Option<AbsolutePathBuf>,
+}
+
+/// Which OTEL exporter to use.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+#[serde(rename_all = "kebab-case")]
+pub enum OtelExporterKind {
+    None,
+    Statsig,
+    OtlpHttp {
+        endpoint: String,
+        #[serde(default)]
+        headers: HashMap<String, String>,
+        protocol: OtelHttpProtocol,
+        #[serde(default)]
+        tls: Option<OtelTlsConfig>,
+    },
+    OtlpGrpc {
+        endpoint: String,
+        #[serde(default)]
+        headers: HashMap<String, String>,
+        #[serde(default)]
+        tls: Option<OtelTlsConfig>,
+    },
+}
+
+/// OTEL settings loaded from config.toml. Fields are optional so we can apply defaults.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct OtelConfigToml {
+    /// Byte limit for tool-result log output; independent of model-visible output.
+    #[serde(default)]
+    pub tool_result: codex_protocol::config_types::ToolResultLogConfig,
+    /// Log user prompt in traces
+    pub log_user_prompt: Option<bool>,
+
+    /// Mark traces with environment (dev, staging, prod, test). Defaults to dev.
+    pub environment: Option<String>,
+
+    /// Optional log exporter
+    pub exporter: Option<OtelExporterKind>,
+
+    /// Optional trace exporter
+    pub trace_exporter: Option<OtelExporterKind>,
+
+    /// Optional metrics exporter
+    pub metrics_exporter: Option<OtelExporterKind>,
+
+    /// Attributes to add to every exported trace span.
+    pub span_attributes: Option<BTreeMap<String, String>>,
+
+    /// Semicolon-separated `key:value` fields to upsert into W3C tracestate members.
+    pub tracestate: Option<BTreeMap<String, BTreeMap<String, String>>>,
+}
+
+/// Effective OTEL settings after defaults are applied.
+#[derive(Debug, Clone, PartialEq)]
+pub struct OtelConfig {
+    pub tool_result: codex_protocol::config_types::ToolResultLogConfig,
+    pub log_user_prompt: bool,
+    pub environment: String,
+    pub exporter: OtelExporterKind,
+    pub trace_exporter: OtelExporterKind,
+    pub metrics_exporter: OtelExporterKind,
+    pub span_attributes: BTreeMap<String, String>,
+    pub tracestate: BTreeMap<String, BTreeMap<String, String>>,
+}
+
+impl Default for OtelConfig {
+    fn default() -> Self {
+        OtelConfig {
+            tool_result: Default::default(),
+            log_user_prompt: false,
+            environment: DEFAULT_OTEL_ENVIRONMENT.to_owned(),
+            exporter: OtelExporterKind::None,
+            trace_exporter: OtelExporterKind::None,
+            metrics_exporter: OtelExporterKind::Statsig,
+            span_attributes: BTreeMap::new(),
+            tracestate: BTreeMap::new(),
+        }
+    }
+}
+
+#[derive(Serialize, Debug, Clone, PartialEq, Eq, Deserialize, JsonSchema)]
+#[serde(untagged)]
+pub enum Notifications {
+    Enabled(bool),
+    Custom(Vec<String>),
+}
+
+impl Default for Notifications {
+    fn default() -> Self {
+        Self::Enabled(true)
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum NotificationMethod {
+    #[default]
+    Auto,
+    Osc9,
+    Bel,
+}
+
+impl fmt::Display for NotificationMethod {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            NotificationMethod::Auto => write!(f, "auto"),
+            NotificationMethod::Osc9 => write!(f, "osc9"),
+            NotificationMethod::Bel => write!(f, "bel"),
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum NotificationCondition {
+    /// Emit TUI notifications only while the terminal is unfocused.
+    #[default]
+    Unfocused,
+    /// Emit TUI notifications regardless of terminal focus.
+    Always,
+}
+
+impl fmt::Display for NotificationCondition {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            NotificationCondition::Unfocused => write!(f, "unfocused"),
+            NotificationCondition::Always => write!(f, "always"),
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, Default)]
+#[serde(rename_all = "kebab-case")]
+pub enum TuiPetAnchor {
+    /// Anchor the pet to the bottom of the current TUI composer viewport.
+    #[default]
+    Composer,
+    /// Anchor the pet to the physical bottom of the terminal screen.
+    ScreenBottom,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct TuiNotificationSettings {
+    /// Enable desktop notifications from the TUI.
+    /// Defaults to `true`.
+    #[serde(default, rename = "notifications")]
+    pub notifications: Notifications,
+
+    /// Notification method to use for terminal notifications.
+    /// Defaults to `auto`.
+    #[serde(default, rename = "notification_method")]
+    pub method: NotificationMethod,
+
+    /// Controls whether TUI notifications are delivered only when the terminal is unfocused or
+    /// regardless of focus. Defaults to `unfocused`.
+    #[serde(default, rename = "notification_condition")]
+    pub condition: NotificationCondition,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ModelAvailabilityNuxConfig {
+    /// Number of times a startup availability NUX has been shown per model slug.
+    #[serde(default, flatten)]
+    pub shown_count: HashMap<String, u32>,
+}
+
+/// Fallback resize-reflow row cap when Codex cannot identify a terminal-specific scrollback size.
+pub const DEFAULT_TERMINAL_RESIZE_REFLOW_FALLBACK_MAX_ROWS: usize = 1_000;
+
+/// Collection of settings that are specific to the TUI.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct Tui {
+    #[serde(default, flatten)]
+    pub notification_settings: TuiNotificationSettings,
+
+    /// Enable animations (welcome screen, shimmer effects, spinners).
+    /// Defaults to `true`.
+    #[serde(default = "default_true")]
+    pub animations: bool,
+
+    /// Enable decorative effects such as Astra composer stars. Also requires animations.
+    /// Defaults to `true`.
+    #[serde(default = "default_true")]
+    pub whimsy: bool,
+
+    /// Show startup tooltips in the TUI welcome screen.
+    /// Defaults to `true`.
+    #[serde(default = "default_true")]
+    pub show_tooltips: bool,
+
+    /// Show an informational notice when the connected app server is an older stable release.
+    /// Defaults to `true`; this does not control compatibility errors or version status.
+    #[serde(default = "default_true")]
+    pub show_server_version_notice: bool,
+
+    /// Generate automatic conversation recaps when the terminal is unfocused.
+    /// Defaults to `true`. Disabling this leaves `/recap` available on demand.
+    #[serde(default = "default_true")]
+    pub auto_recap: bool,
+
+    /// When true, disables burst-paste detection for typed input entirely.
+    /// All characters are inserted as they are received, and no buffering
+    /// or placeholder replacement will occur for fast keypress bursts.
+    /// Overrides the legacy top-level `disable_paste_burst` setting. Defaults to `false`.
+    pub disable_paste_burst: Option<bool>,
+
+    /// Start the composer in Vim mode (`Normal`) by default.
+    /// Defaults to `false`.
+    #[serde(default)]
+    pub vim_mode_default: bool,
+
+    /// Escape returns from async questions to the composer, preserving the answer draft.
+    #[serde(default = "default_true")]
+    pub question_esc_back: bool,
+
+    /// Start the TUI in raw scrollback mode for copy-friendly transcript output.
+    /// Defaults to `false`.
+    #[serde(default)]
+    pub raw_output_mode: bool,
+
+    /// Controls whether the TUI uses the terminal's alternate screen buffer.
+    ///
+    /// - `auto` (default): Use alternate screen.
+    /// - `always`: Always use alternate screen.
+    /// - `never`: Never use alternate screen (inline mode only, preserves scrollback).
+    #[serde(default)]
+    pub alternate_screen: AltScreenMode,
+
+    /// Ordered list of status line item identifiers.
+    ///
+    /// When set, the TUI renders the selected items as the status line.
+    /// When unset, the TUI defaults to: `model-with-reasoning`, `current-dir`, and `thread-name`.
+    #[serde(default)]
+    pub status_line: Option<Vec<String>>,
+
+    /// Color status line items with colors derived from the active syntax theme.
+    /// Defaults to `true`.
+    #[serde(default = "default_true")]
+    pub status_line_use_colors: bool,
+
+    /// Ordered list of terminal title item identifiers.
+    ///
+    /// When set, the TUI renders the selected items into the terminal window/tab title.
+    /// When unset, the TUI defaults to: `activity`, `thread-name`, and `project-name`.
+    /// The `activity` item spins while working and shows an action-required
+    /// message when blocked on the user.
+    #[serde(default)]
+    pub terminal_title: Option<Vec<String>>,
+
+    /// Syntax highlighting theme name (kebab-case).
+    ///
+    /// When set, overrides automatic light/dark theme detection.
+    /// Use `/theme` in the TUI or see `$CODEX_HOME/themes` for custom themes.
+    #[serde(default)]
+    pub theme: Option<String>,
+
+    /// Pet id to preselect in the terminal pet picker.
+    ///
+    /// Custom pet ids resolve against CODEX_HOME/pets/<pet-id>/pet.json.
+    #[serde(default)]
+    pub pet: Option<String>,
+
+    /// Where the terminal pet should anchor vertically.
+    ///
+    /// Defaults to `composer`, which follows the current TUI composer viewport.
+    #[serde(default)]
+    pub pet_anchor: TuiPetAnchor,
+
+    /// Preferred layout for resume/fork session picker results.
+    #[serde(default)]
+    pub session_picker_view: Option<SessionPickerViewMode>,
+
+    /// Working directory to use when resuming or forking a session.
+    /// When unset, prompt if the current and session directories differ.
+    #[serde(default)]
+    pub resume_cwd: Option<ResumeCwdMode>,
+
+    /// Keybinding overrides for the TUI.
+    ///
+    /// This supports rebinding selected actions globally and by context.
+    /// Context bindings take precedence over `global` bindings.
+    #[serde(default)]
+    pub keymap: TuiKeymap,
+
+    /// Startup tooltip availability NUX state persisted by the TUI.
+    #[serde(default)]
+    pub model_availability_nux: ModelAvailabilityNuxConfig,
+
+    /// Trim terminal resize-reflow replay to the most recent rendered terminal rows when the
+    /// transcript exceeds this cap. Omit to use Codex's terminal-specific default. Set to `0` to
+    /// keep all rendered rows.
+    #[serde(default)]
+    #[schemars(range(min = 0))]
+    pub terminal_resize_reflow_max_rows: Option<usize>,
+}
+
+const fn default_true() -> bool {
+    true
+}
+
+/// Settings for notices we display to users via the tui and app-server clients
+/// (primarily the Codex IDE extension). NOTE: these are different from
+/// notifications - notices are warnings, NUX screens, acknowledgements, etc.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ExternalConfigMigrationPrompts {
+    /// Tracks whether home-level external config migration prompts are hidden.
+    pub home: Option<bool>,
+    /// Tracks the last time the home-level external config migration prompt was shown.
+    pub home_last_prompted_at: Option<i64>,
+    /// Tracks which project paths have opted out of external config migration prompts.
+    #[serde(default)]
+    pub projects: BTreeMap<String, bool>,
+    /// Tracks the last time a project-level external config migration prompt was shown.
+    #[serde(default)]
+    pub project_last_prompted_at: BTreeMap<String, i64>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct Notice {
+    /// Tracks whether the user has acknowledged the full access warning prompt.
+    pub hide_full_access_warning: Option<bool>,
+    /// Tracks whether the user has acknowledged the Windows world-writable directories warning.
+    pub hide_world_writable_warning: Option<bool>,
+    /// Tracks whether the user opted out of Codex-managed fast defaults.
+    pub fast_default_opt_out: Option<bool>,
+    /// Tracks whether the user opted out of the rate limit model switch reminder.
+    pub hide_rate_limit_model_nudge: Option<bool>,
+    /// Tracks whether the user has seen the model migration prompt
+    pub hide_gpt5_1_migration_prompt: Option<bool>,
+    /// Tracks whether the user has seen the gpt-5.1-codex-max migration prompt
+    #[serde(rename = "hide_gpt-5.1-codex-max_migration_prompt")]
+    pub hide_gpt_5_1_codex_max_migration_prompt: Option<bool>,
+    /// Tracks acknowledged model migrations as old->new model slug mappings.
+    #[serde(default)]
+    pub model_migrations: BTreeMap<String, String>,
+    /// Tracks scopes where external config migration prompts should be suppressed.
+    #[serde(default)]
+    pub external_config_migration_prompts: ExternalConfigMigrationPrompts,
+}
+
+pub use crate::skills_config::BundledSkillsConfig;
+pub use crate::skills_config::SkillConfig;
+pub use crate::skills_config::SkillsConfig;
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct PluginConfig {
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+
+    /// Per-MCP-server policy overlays for MCP servers contributed by this plugin.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub mcp_servers: HashMap<String, PluginMcpServerConfig>,
+}
+
+/// Policy settings for a plugin-provided MCP server.
+///
+/// This intentionally excludes transport settings: plugin manifests own how the
+/// MCP server is launched, while host config owns enablement, auth, and tool policy.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct PluginMcpServerConfig {
+    /// When `false`, Codex skips initializing this plugin MCP server.
+    #[serde(default = "default_enabled")]
+    pub enabled: bool,
+
+    /// Host-configured EMA registration; the plugin still owns its endpoint.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ema_auth: Option<PluginMcpServerEmaAuthConfig>,
+
+    /// Approval mode for tools in this server unless a tool override exists.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default_tools_approval_mode: Option<AppToolApproval>,
+
+    /// Explicit allow-list of tools exposed from this server.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enabled_tools: Option<Vec<String>>,
+
+    /// Explicit deny-list of tools. These tools are removed after applying `enabled_tools`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub disabled_tools: Option<Vec<String>>,
+
+    /// Per-tool policy settings keyed by tool name.
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub tools: HashMap<String, McpServerToolConfig>,
+}
+
+impl Default for PluginMcpServerConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            ema_auth: None,
+            default_tools_approval_mode: None,
+            enabled_tools: None,
+            disabled_tools: None,
+            tools: HashMap::new(),
+        }
+    }
+}
+
+/// Resource registration applied through an existing per-plugin policy overlay.
+/// The enterprise IdP is selected separately by trusted host configuration.
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct PluginMcpServerEmaAuthConfig {
+    /// Exact plugin endpoint approved by the host; never overrides the declaration.
+    pub url: String,
+    pub client_id: String,
+    pub authorization_server_issuer: String,
+    #[serde(default)]
+    pub scopes: Vec<String>,
+    pub resource: String,
+}
+
+impl PluginMcpServerEmaAuthConfig {
+    pub fn apply(&self, server: &mut McpServerConfig) {
+        let registration_error = if self.resource.trim().is_empty() {
+            Some("plugin EMA registration requires a resource")
+        } else if !server.matches_requirement(&crate::McpServerRequirement::Identity {
+            identity: crate::McpServerIdentity::Url {
+                url: self.url.clone(),
+            },
+        }) {
+            Some("plugin endpoint does not match its EMA registration")
+        } else {
+            None
+        };
+        if registration_error.is_some() && server.enabled {
+            server.enabled = false;
+            server.disabled_reason = Some(crate::McpServerDisabledReason::EmaRegistration);
+        }
+        server.auth = McpServerAuth::EmaAuth;
+        let oauth = server.oauth.get_or_insert_default();
+        oauth.client_id = Some(self.client_id.clone());
+        oauth.authorization_server_issuer = Some(self.authorization_server_issuer.clone());
+        server.scopes = Some(self.scopes.clone());
+        oauth.ema_registration = None;
+        oauth.ema_registration_error = registration_error;
+        server.oauth_resource = Some(self.resource.clone());
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct MarketplaceConfig {
+    /// Last time Codex successfully added or refreshed this marketplace.
+    #[serde(default)]
+    pub last_updated: Option<String>,
+    /// Git revision Codex last successfully activated for this marketplace.
+    #[serde(default)]
+    pub last_revision: Option<String>,
+    /// Source kind used to install this marketplace.
+    #[serde(default)]
+    pub source_type: Option<MarketplaceSourceType>,
+    /// Source location used when the marketplace was added.
+    #[serde(default)]
+    pub source: Option<String>,
+    /// Git ref to check out when `source_type` is `git`.
+    #[serde(default, rename = "ref")]
+    pub ref_name: Option<String>,
+    /// Sparse checkout paths used when `source_type` is `git`.
+    #[serde(default)]
+    pub sparse_paths: Option<Vec<String>>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum MarketplaceSourceType {
+    Git,
+    Local,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct SandboxWorkspaceWrite {
+    #[serde(default)]
+    pub writable_roots: Vec<AbsolutePathBuf>,
+    #[serde(default)]
+    pub network_access: bool,
+    #[serde(default)]
+    pub exclude_tmpdir_env_var: bool,
+    #[serde(default)]
+    pub exclude_slash_tmp: bool,
+}
+
+#[cfg(test)]
+#[path = "types_tests.rs"]
+mod tests;

codex-rs/config/src/types_tests.rs

@@ -0,0 +1,106 @@
+use super::*;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn deserialize_skill_config_with_name_selector() {
+    let cfg: SkillConfig = toml::from_str(
+        r#"
+            name = "github:yeet"
+            enabled = false
+        "#,
+    )
+    .expect("should deserialize skill config with name selector");
+
+    assert_eq!(cfg.name.as_deref(), Some("github:yeet"));
+    assert_eq!(cfg.path, None);
+    assert!(!cfg.enabled);
+}
+
+#[test]
+fn deserialize_skill_config_with_path_selector() {
+    let tempdir = tempfile::tempdir().expect("tempdir");
+    let skill_path = tempdir.path().join("skills").join("demo").join("SKILL.md");
+    let cfg: SkillConfig = toml::from_str(&format!(
+        r#"
+            path = {path:?}
+            enabled = false
+        "#,
+        path = skill_path.display().to_string(),
+    ))
+    .expect("should deserialize skill config with path selector");
+
+    assert_eq!(
+        cfg,
+        SkillConfig {
+            path: Some(
+                AbsolutePathBuf::from_absolute_path(&skill_path)
+                    .expect("skill path should be absolute"),
+            ),
+            name: None,
+            enabled: false,
+        }
+    );
+}
+
+#[test]
+fn memories_config_clamps_count_limits_to_nonzero_values() {
+    let config = MemoriesConfig::from(MemoriesToml {
+        max_raw_memories_for_consolidation: Some(0),
+        max_rollouts_per_startup: Some(0),
+        ..Default::default()
+    });
+
+    assert_eq!(
+        config,
+        MemoriesConfig {
+            max_raw_memories_for_consolidation: 1,
+            max_rollouts_per_startup: 1,
+            ..MemoriesConfig::default()
+        }
+    );
+}
+
+#[test]
+fn memories_config_clamps_rate_limit_remaining_threshold() {
+    let config = MemoriesConfig::from(MemoriesToml {
+        min_rate_limit_remaining_percent: Some(101),
+        ..Default::default()
+    });
+    assert_eq!(
+        config,
+        MemoriesConfig {
+            min_rate_limit_remaining_percent: 100,
+            ..MemoriesConfig::default()
+        }
+    );
+
+    let config = MemoriesConfig::from(MemoriesToml {
+        min_rate_limit_remaining_percent: Some(-1),
+        ..Default::default()
+    });
+    assert_eq!(
+        config,
+        MemoriesConfig {
+            min_rate_limit_remaining_percent: 0,
+            ..MemoriesConfig::default()
+        }
+    );
+}
+
+#[test]
+fn memories_version_selects_pipeline_without_changing_other_defaults() {
+    for (source, version) in [
+        ("", MemoryVersion::V1),
+        ("version = \"v2\"", MemoryVersion::V2),
+    ] {
+        let parsed: MemoriesToml = toml::from_str(source).expect("parse memories config");
+        assert_eq!(
+            MemoriesConfig::from(parsed),
+            MemoriesConfig {
+                version,
+                ..Default::default()
+            }
+        );
+    }
+    assert!(toml::from_str::<MemoriesToml>("version = \"v3\"").is_err());
+}

codex-rs/install-context/src/bundle_tests.rs

@@ -0,0 +1,76 @@
+//! Ensure a provisioned CLI still discovers its outer package and install method.
+
+use super::*;
+use pretty_assertions::assert_eq;
+use std::fs;
+
+#[test]
+fn bundle_executable_preserves_package_layout_and_install_method() -> std::io::Result<()> {
+    let home = tempfile::tempdir()?;
+    let package = home.path().join("packages/standalone/releases/test");
+    let executable = package.join("CodexCLI.app/Contents/MacOS/codex");
+    fs::create_dir_all(executable.parent().unwrap())?;
+    fs::write(&executable, "")?;
+    for directory in [BIN_DIRNAME, RESOURCES_DIRNAME, PATH_DIRNAME] {
+        fs::create_dir_all(package.join(directory))?;
+    }
+    fs::write(
+        package.join(PACKAGE_METADATA_FILENAME),
+        r#"{"version":"1.2.3"}"#,
+    )?;
+    let package = canonical_absolute_path(&package).unwrap();
+    let bin_dir = package.join(BIN_DIRNAME);
+    let resources_dir = package.join(RESOURCES_DIRNAME);
+    let path_dir = package.join(PATH_DIRNAME);
+    let context = InstallContext::from_exe_with_codex_home(
+        /*is_macos*/ true,
+        /*current_exe*/ Some(&executable),
+        /*method_override*/ None,
+        /*codex_home*/ Some(home.path()),
+    );
+    assert_eq!(
+        context,
+        InstallContext {
+            method: InstallMethod::Standalone {
+                release_dir: package.clone(),
+                resources_dir: Some(resources_dir.clone()),
+                platform: standalone_platform(),
+            },
+            package_layout: Some(CodexPackageLayout {
+                package_dir: package,
+                bin_dir,
+                resources_dir: Some(resources_dir),
+                path_dir: Some(path_dir),
+            }),
+        }
+    );
+    Ok(())
+}
+
+#[cfg(windows)]
+#[test]
+fn winget_root_requires_metadata_for_the_actual_executable() -> std::io::Result<()> {
+    let temp = tempfile::tempdir()?;
+    let package = canonical_absolute_path(temp.path()).unwrap();
+    let name = "codex-x86_64-pc-windows-msvc.exe";
+    let executable = package.join(name);
+    fs::write(&executable, "signed CLI")?;
+    for directory in [RESOURCES_DIRNAME, PATH_DIRNAME] {
+        fs::create_dir_all(package.join(directory))?;
+    }
+    assert_eq!(CodexPackageLayout::from_exe(executable.as_path()), None);
+    for entrypoint in ["other.exe", "bin/codex.exe", name] {
+        fs::write(
+            package.join(PACKAGE_METADATA_FILENAME),
+            serde_json::json!({"layoutVersion": 1, "entrypoint": entrypoint}).to_string(),
+        )?;
+        let expected = (entrypoint == name).then(|| CodexPackageLayout {
+            package_dir: package.clone(),
+            bin_dir: package.clone(),
+            resources_dir: Some(package.join(RESOURCES_DIRNAME)),
+            path_dir: Some(package.join(PATH_DIRNAME)),
+        });
+        assert_eq!(CodexPackageLayout::from_exe(executable.as_path()), expected);
+    }
+    Ok(())
+}

codex-rs/install-context/src/lib.rs

@@ -0,0 +1,915 @@
+use std::ffi::OsStr;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::OnceLock;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+use semver::Version;
+use serde::Deserialize;
+
+const BIN_DIRNAME: &str = "bin";
+const CODE_MODE_HOST_EXECUTABLE_NAME: &str = if cfg!(windows) {
+    "codex-code-mode-host.exe"
+} else {
+    "codex-code-mode-host"
+};
+const PACKAGE_METADATA_FILENAME: &str = "codex-package.json";
+const PATH_DIRNAME: &str = "codex-path";
+const RELEASES_DIRNAME: &str = "releases";
+const RESOURCES_DIRNAME: &str = "codex-resources";
+const STANDALONE_PACKAGES_DIRNAME: &str = "standalone";
+const ZSH_DIRNAME: &str = "zsh";
+static INSTALL_CONTEXT: OnceLock<InstallContext> = OnceLock::new();
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum StandalonePlatform {
+    Unix,
+    Windows,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CodexPackageLayout {
+    /// The package root that contains the metadata file and layout directories.
+    pub package_dir: AbsolutePathBuf,
+    /// Directory containing the Codex entrypoint executable.
+    pub bin_dir: AbsolutePathBuf,
+    /// Directory containing managed helper binaries and data files, when present.
+    pub resources_dir: Option<AbsolutePathBuf>,
+    /// Folder that should be prepended to the PATH, when present.
+    pub path_dir: Option<AbsolutePathBuf>,
+}
+
+/// Version metadata recorded in a bundled Codex runtime package.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
+pub struct CodexPackageManifest {
+    pub version: Version,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct InstallContext {
+    pub method: InstallMethod,
+    pub package_layout: Option<CodexPackageLayout>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum InstallMethod {
+    Standalone {
+        /// The managed standalone release directory. Legacy installs use paths
+        /// such as
+        /// `~/.codex/packages/standalone/releases/0.111.0-x86_64-unknown-linux-musl`.
+        /// Package-layout installs use the package root that contains `bin/`,
+        /// `codex-resources/`, and `codex-path/`.
+        release_dir: AbsolutePathBuf,
+        /// The bundled resource directory for managed dependencies.
+        resources_dir: Option<AbsolutePathBuf>,
+        /// The platform of the standalone release, either `Unix` or `Windows`.
+        platform: StandalonePlatform,
+    },
+    /// A Codex binary launched through the npm-managed `codex.js` shim.
+    Npm,
+    /// A Codex binary launched through the bun-managed `codex.js` shim.
+    Bun,
+    /// A Codex binary launched through the pnpm-managed `codex.js` shim.
+    Pnpm,
+    /// A Codex binary launched through the Vite+-managed `codex.js` shim.
+    VitePlus,
+    /// A Codex binary that appears to come from a Homebrew install prefix.
+    Brew,
+    /// Any other execution environment.
+    ///
+    /// This commonly covers `cargo run`, app-bundled Codex binaries, custom
+    /// internal launchers, and tests that execute Codex from an arbitrary path.
+    Other,
+}
+
+impl InstallContext {
+    pub fn from_exe(
+        is_macos: bool,
+        current_exe: Option<&Path>,
+        method_override: Option<InstallMethod>,
+    ) -> Self {
+        let codex_home = codex_utils_home_dir::find_codex_home().ok();
+        Self::from_exe_with_codex_home(
+            is_macos,
+            current_exe,
+            method_override,
+            codex_home.as_deref(),
+        )
+    }
+
+    fn from_exe_with_codex_home(
+        is_macos: bool,
+        current_exe: Option<&Path>,
+        method_override: Option<InstallMethod>,
+        codex_home: Option<&Path>,
+    ) -> Self {
+        let package_layout = current_exe.and_then(CodexPackageLayout::from_exe);
+        let method = if let Some(method) = method_override {
+            method
+        } else if let Some(exe_path) = current_exe {
+            install_method_from_exe(exe_path, codex_home, package_layout.as_ref(), is_macos)
+        } else {
+            InstallMethod::Other
+        };
+
+        Self {
+            method,
+            package_layout,
+        }
+    }
+
+    pub fn current() -> &'static Self {
+        INSTALL_CONTEXT.get_or_init(|| {
+            let current_exe = std::env::current_exe().ok();
+            let method_override = if std::env::var_os("CODEX_MANAGED_BY_VITE_PLUS").is_some() {
+                Some(InstallMethod::VitePlus)
+            } else if std::env::var_os("CODEX_MANAGED_BY_PNPM").is_some() {
+                Some(InstallMethod::Pnpm)
+            } else if std::env::var_os("CODEX_MANAGED_BY_NPM").is_some() {
+                Some(InstallMethod::Npm)
+            } else if std::env::var_os("CODEX_MANAGED_BY_BUN").is_some() {
+                Some(InstallMethod::Bun)
+            } else {
+                None
+            };
+            Self::from_exe(
+                cfg!(target_os = "macos"),
+                current_exe.as_deref(),
+                method_override,
+            )
+        })
+    }
+
+    /// Read the manifest for the package that contains the current executable.
+    pub fn package_manifest(&self) -> Option<CodexPackageManifest> {
+        let package_layout = self.package_layout.as_ref()?;
+        let manifest =
+            std::fs::read_to_string(package_layout.package_dir.join(PACKAGE_METADATA_FILENAME))
+                .ok()?;
+        serde_json::from_str(&manifest).ok()
+    }
+
+    pub fn rg_command(&self) -> PathBuf {
+        if let Some(package_layout) = &self.package_layout
+            && let Some(path_dir) = &package_layout.path_dir
+        {
+            let bundled_rg = path_dir.join(default_rg_command());
+            if bundled_rg.is_file() {
+                return bundled_rg.into_path_buf();
+            }
+        }
+
+        if let InstallMethod::Standalone {
+            resources_dir: Some(resources_dir),
+            ..
+        } = &self.method
+        {
+            let bundled_rg = resources_dir.join(default_rg_command());
+            if bundled_rg.is_file() {
+                return bundled_rg.into_path_buf();
+            }
+        }
+
+        default_rg_command()
+    }
+
+    pub fn code_mode_host_program(&self) -> PathBuf {
+        // prefer the one packed under codex-resources
+        self.bundled_resource(CODE_MODE_HOST_EXECUTABLE_NAME)
+            .map_or_else(
+                || self.code_mode_host_program_from_exe(std::env::current_exe().ok().as_deref()),
+                AbsolutePathBuf::into_path_buf,
+            )
+    }
+
+    fn code_mode_host_program_from_exe(&self, current_exe: Option<&Path>) -> PathBuf {
+        let executable_dir = if let Some(package_layout) = &self.package_layout {
+            Some(package_layout.bin_dir.clone())
+        } else if let InstallMethod::Standalone { release_dir, .. } = &self.method {
+            Some(release_dir.clone())
+        } else {
+            current_exe
+                .and_then(Path::parent)
+                .and_then(canonical_absolute_path)
+        };
+        if let Some(executable_dir) = executable_dir {
+            let executable = executable_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME);
+            if executable.is_file() {
+                return executable.into_path_buf();
+            }
+        }
+
+        current_exe
+            .and_then(Path::parent)
+            .map(|parent| parent.join(CODE_MODE_HOST_EXECUTABLE_NAME))
+            .unwrap_or_else(|| PathBuf::from(CODE_MODE_HOST_EXECUTABLE_NAME))
+    }
+
+    pub fn bundled_resource(&self, file_name: impl AsRef<Path>) -> Option<AbsolutePathBuf> {
+        if let Some(package_layout) = &self.package_layout
+            && let Some(resources_dir) = &package_layout.resources_dir
+        {
+            let resource = resources_dir.join(file_name.as_ref());
+            if resource.is_file() {
+                return Some(resource);
+            }
+        }
+
+        if let InstallMethod::Standalone {
+            resources_dir: Some(resources_dir),
+            ..
+        } = &self.method
+        {
+            let resource = resources_dir.join(file_name);
+            if resource.is_file() {
+                return Some(resource);
+            }
+        }
+
+        None
+    }
+
+    pub fn bundled_zsh_path(&self) -> Option<AbsolutePathBuf> {
+        if cfg!(windows) {
+            None
+        } else {
+            self.bundled_resource(zsh_resource_path())
+        }
+    }
+
+    pub fn bundled_zsh_bin_dir(&self) -> Option<AbsolutePathBuf> {
+        self.bundled_zsh_path()?.parent()
+    }
+}
+
+impl CodexPackageLayout {
+    fn from_exe(exe_path: &Path) -> Option<Self> {
+        let canonical_exe = canonical_absolute_path(exe_path)?;
+        let exe_dir = canonical_exe.parent()?;
+        // WinGet preserves a target-qualified executable at the package root.
+        // Only recognize that layout when metadata names this exact executable.
+        #[cfg(windows)]
+        if let Ok(contents) = std::fs::read(exe_dir.join(PACKAGE_METADATA_FILENAME))
+            && let Ok(metadata) = serde_json::from_slice::<serde_json::Value>(&contents)
+            && metadata["layoutVersion"] == 1
+            && metadata["entrypoint"].as_str().map(OsStr::new) == canonical_exe.file_name()
+        {
+            return Some(Self {
+                resources_dir: existing_dir(exe_dir.join(RESOURCES_DIRNAME)),
+                path_dir: existing_dir(exe_dir.join(PATH_DIRNAME)),
+                package_dir: exe_dir.clone(),
+                bin_dir: exe_dir,
+            });
+        }
+        match exe_dir.file_name() {
+            Some(name) if name == OsStr::new(BIN_DIRNAME) => Self::from_package_bin_dir(exe_dir),
+            Some(name) if name == OsStr::new(RESOURCES_DIRNAME) => {
+                let package_dir = exe_dir.parent()?;
+                Self::from_package_bin_dir(package_dir.join(BIN_DIRNAME))
+            }
+            Some(name) if name == OsStr::new("MacOS") => {
+                // A provisioned CLI keeps helpers and metadata in the outer
+                // package. current_exe points inside the bundle, not at bin/codex.
+                let contents = exe_dir.parent()?;
+                let bundle = contents.parent()?;
+                if contents.file_name()? != OsStr::new("Contents")
+                    || bundle.file_name()? != OsStr::new("CodexCLI.app")
+                {
+                    return None;
+                }
+                Self::from_package_bin_dir(bundle.parent()?.join(BIN_DIRNAME))
+            }
+            Some(_) | None => None,
+        }
+    }
+
+    fn from_package_bin_dir(bin_dir: AbsolutePathBuf) -> Option<Self> {
+        if !bin_dir.is_dir() {
+            return None;
+        }
+        let package_dir = bin_dir.parent()?;
+        if !package_dir.join(PACKAGE_METADATA_FILENAME).is_file() {
+            return None;
+        }
+
+        Some(Self {
+            resources_dir: existing_dir(package_dir.join(RESOURCES_DIRNAME)),
+            path_dir: existing_dir(package_dir.join(PATH_DIRNAME)),
+            package_dir,
+            bin_dir,
+        })
+    }
+}
+
+fn install_method_from_exe(
+    exe_path: &Path,
+    codex_home: Option<&Path>,
+    package_layout: Option<&CodexPackageLayout>,
+    is_macos: bool,
+) -> InstallMethod {
+    if let Some(standalone_method) = standalone_install_method(exe_path, codex_home, package_layout)
+    {
+        return standalone_method;
+    }
+
+    if is_macos && (exe_path.starts_with("/opt/homebrew") || exe_path.starts_with("/usr/local")) {
+        InstallMethod::Brew
+    } else {
+        InstallMethod::Other
+    }
+}
+
+fn standalone_install_method(
+    exe_path: &Path,
+    codex_home: Option<&Path>,
+    package_layout: Option<&CodexPackageLayout>,
+) -> Option<InstallMethod> {
+    let canonical_codex_home = canonical_absolute_path(codex_home?)?;
+    let release_dir = if let Some(package_layout) = package_layout {
+        package_layout.package_dir.clone()
+    } else {
+        canonical_absolute_path(exe_path)?.parent()?
+    };
+    let releases_root = canonical_codex_home
+        .join("packages")
+        .join(STANDALONE_PACKAGES_DIRNAME)
+        .join(RELEASES_DIRNAME);
+    if !release_dir.starts_with(releases_root.as_path()) {
+        return None;
+    }
+
+    let resources_dir = release_dir.join(RESOURCES_DIRNAME);
+    Some(InstallMethod::Standalone {
+        release_dir,
+        resources_dir: resources_dir.is_dir().then_some(resources_dir),
+        platform: standalone_platform(),
+    })
+}
+
+fn canonical_absolute_path(path: &Path) -> Option<AbsolutePathBuf> {
+    let canonical_path = std::fs::canonicalize(path).ok()?;
+    AbsolutePathBuf::from_absolute_path(canonical_path).ok()
+}
+
+fn standalone_platform() -> StandalonePlatform {
+    if cfg!(windows) {
+        StandalonePlatform::Windows
+    } else {
+        StandalonePlatform::Unix
+    }
+}
+
+fn existing_dir(path: AbsolutePathBuf) -> Option<AbsolutePathBuf> {
+    path.is_dir().then_some(path)
+}
+
+fn default_rg_command() -> PathBuf {
+    if cfg!(windows) {
+        PathBuf::from("rg.exe")
+    } else {
+        PathBuf::from("rg")
+    }
+}
+
+fn zsh_resource_path() -> PathBuf {
+    PathBuf::from(ZSH_DIRNAME).join(BIN_DIRNAME).join("zsh")
+}
+
+#[cfg(test)]
+#[path = "bundle_tests.rs"]
+mod bundle_tests;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+
+    const TEST_RESOURCE_NAME: &str = "codex-test-helper";
+
+    #[test]
+    fn code_mode_host_program_prefers_package_resource_over_legacy_binary() -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        let resources_dir = package_dir.path().join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(&resources_dir)?;
+        fs::write(package_dir.path().join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        let resource_host = resources_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME);
+        fs::write(&exe_path, "")?;
+        fs::write(bin_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME), "legacy host")?;
+        fs::write(&resource_host, "managed host")?;
+
+        let context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+        );
+
+        assert_eq!(
+            context.code_mode_host_program(),
+            AbsolutePathBuf::from_absolute_path(resource_host.canonicalize()?)?.into_path_buf()
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn code_mode_host_program_uses_package_resource_without_legacy_binary() -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        let resources_dir = package_dir.path().join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(&resources_dir)?;
+        fs::write(package_dir.path().join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        let resource_host = resources_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME);
+        fs::write(&exe_path, "")?;
+        fs::write(&resource_host, "managed host")?;
+
+        let context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+        );
+
+        assert_eq!(
+            context.code_mode_host_program(),
+            AbsolutePathBuf::from_absolute_path(resource_host.canonicalize()?)?.into_path_buf()
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn code_mode_host_program_ignores_resource_directory_and_uses_legacy_binary()
+    -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        let resources_dir = package_dir.path().join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(resources_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME))?;
+        fs::write(package_dir.path().join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        let legacy_host = bin_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME);
+        fs::write(&exe_path, "")?;
+        fs::write(&legacy_host, "legacy host")?;
+
+        let context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+        );
+
+        assert_eq!(
+            context.code_mode_host_program(),
+            AbsolutePathBuf::from_absolute_path(legacy_host.canonicalize()?)?.into_path_buf()
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn detects_standalone_install_from_release_layout() -> std::io::Result<()> {
+        let codex_home = tempfile::tempdir()?;
+        let release_dir = codex_home
+            .path()
+            .join("packages/standalone/releases/1.2.3-x86_64-unknown-linux-musl");
+        let resources_dir = release_dir.join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&resources_dir)?;
+        let exe_path = release_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        fs::write(&exe_path, "")?;
+        fs::write(release_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME), "")?;
+        fs::write(
+            resources_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME),
+            "managed host",
+        )?;
+        fs::write(resources_dir.join(default_rg_command()), "")?;
+        fs::write(resources_dir.join(TEST_RESOURCE_NAME), "")?;
+        let canonical_release_dir =
+            AbsolutePathBuf::from_absolute_path(release_dir.canonicalize()?)?;
+        let canonical_resources_dir =
+            AbsolutePathBuf::from_absolute_path(resources_dir.canonicalize()?)?;
+
+        let context = InstallContext::from_exe_with_codex_home(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+            /*codex_home*/ Some(codex_home.path()),
+        );
+        assert_eq!(
+            context,
+            InstallContext {
+                method: InstallMethod::Standalone {
+                    release_dir: canonical_release_dir.clone(),
+                    resources_dir: Some(canonical_resources_dir.clone()),
+                    platform: standalone_platform(),
+                },
+                package_layout: None,
+            }
+        );
+        assert_eq!(
+            context.code_mode_host_program_from_exe(Some(&exe_path)),
+            canonical_release_dir
+                .join(CODE_MODE_HOST_EXECUTABLE_NAME)
+                .into_path_buf()
+        );
+        assert_eq!(
+            context.code_mode_host_program(),
+            canonical_resources_dir
+                .join(CODE_MODE_HOST_EXECUTABLE_NAME)
+                .into_path_buf()
+        );
+        assert_eq!(
+            context.bundled_resource(TEST_RESOURCE_NAME),
+            Some(canonical_resources_dir.join(TEST_RESOURCE_NAME))
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn standalone_rg_falls_back_when_resources_are_missing() -> std::io::Result<()> {
+        let codex_home = tempfile::tempdir()?;
+        let release_dir = codex_home
+            .path()
+            .join("packages/standalone/releases/1.2.3-x86_64-unknown-linux-musl");
+        fs::create_dir_all(&release_dir)?;
+        let exe_path = release_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        fs::write(&exe_path, "")?;
+
+        let context = InstallContext::from_exe_with_codex_home(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+            /*codex_home*/ Some(codex_home.path()),
+        );
+        assert_eq!(context.rg_command(), default_rg_command());
+        Ok(())
+    }
+
+    #[test]
+    fn detects_package_layout_independently_from_install_method() -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        let resources_dir = package_dir.path().join(RESOURCES_DIRNAME);
+        let path_dir = package_dir.path().join(PATH_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(&resources_dir)?;
+        fs::create_dir_all(&path_dir)?;
+        fs::write(
+            package_dir.path().join(PACKAGE_METADATA_FILENAME),
+            r#"{
+  "layoutVersion": 1,
+  "version": "1.2.3",
+  "target": "x86_64-unknown-linux-musl",
+  "variant": "codex",
+  "entrypoint": "bin/codex",
+  "resourcesDir": "codex-resources",
+  "pathDir": "codex-path"
+}
+"#,
+        )?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        fs::write(&exe_path, "")?;
+        fs::write(bin_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME), "")?;
+        fs::write(resources_dir.join(TEST_RESOURCE_NAME), "")?;
+        fs::write(path_dir.join(default_rg_command()), "")?;
+        if !cfg!(windows) {
+            let zsh_path = resources_dir.join(zsh_resource_path());
+            fs::create_dir_all(zsh_path.parent().expect("zsh path should have parent"))?;
+            fs::write(&zsh_path, "")?;
+        }
+        let canonical_package_dir =
+            AbsolutePathBuf::from_absolute_path(package_dir.path().canonicalize()?)?;
+        let canonical_bin_dir = AbsolutePathBuf::from_absolute_path(bin_dir.canonicalize()?)?;
+        let canonical_resources_dir =
+            AbsolutePathBuf::from_absolute_path(resources_dir.canonicalize()?)?;
+        let canonical_path_dir = AbsolutePathBuf::from_absolute_path(path_dir.canonicalize()?)?;
+        let package_layout = CodexPackageLayout {
+            package_dir: canonical_package_dir,
+            bin_dir: canonical_bin_dir.clone(),
+            resources_dir: Some(canonical_resources_dir.clone()),
+            path_dir: Some(canonical_path_dir.clone()),
+        };
+
+        let context = InstallContext::from_exe_with_codex_home(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+            /*codex_home*/ None,
+        );
+        assert_eq!(
+            context,
+            InstallContext {
+                method: InstallMethod::Other,
+                package_layout: Some(package_layout),
+            }
+        );
+        assert_eq!(
+            context.package_manifest(),
+            Some(CodexPackageManifest {
+                version: Version::new(1, 2, 3),
+            })
+        );
+        assert_eq!(
+            context.code_mode_host_program_from_exe(Some(&exe_path)),
+            canonical_bin_dir
+                .join(CODE_MODE_HOST_EXECUTABLE_NAME)
+                .into_path_buf()
+        );
+        assert_eq!(
+            context.code_mode_host_program(),
+            canonical_bin_dir
+                .join(CODE_MODE_HOST_EXECUTABLE_NAME)
+                .into_path_buf()
+        );
+        assert_eq!(
+            context.rg_command(),
+            canonical_path_dir
+                .join(default_rg_command())
+                .into_path_buf()
+        );
+        assert_eq!(
+            context.bundled_resource(TEST_RESOURCE_NAME),
+            Some(canonical_resources_dir.join(TEST_RESOURCE_NAME))
+        );
+        if cfg!(windows) {
+            assert_eq!(context.bundled_zsh_path(), None);
+            assert_eq!(context.bundled_zsh_bin_dir(), None);
+        } else {
+            assert_eq!(
+                context.bundled_zsh_path(),
+                Some(canonical_resources_dir.join(zsh_resource_path()))
+            );
+            assert_eq!(
+                context.bundled_zsh_bin_dir(),
+                Some(canonical_resources_dir.join(ZSH_DIRNAME).join(BIN_DIRNAME))
+            );
+        }
+        Ok(())
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn code_mode_host_program_accepts_symlinks_to_files() -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::write(package_dir.path().join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join("codex");
+        let executable_target = package_dir.path().join("host-target");
+        let executable_path = bin_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME);
+        fs::write(&exe_path, "")?;
+        fs::write(&executable_target, "")?;
+        std::os::unix::fs::symlink(&executable_target, &executable_path)?;
+        let canonical_bin_dir = AbsolutePathBuf::from_absolute_path(bin_dir.canonicalize()?)?;
+
+        let context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+        );
+
+        assert_eq!(
+            context.code_mode_host_program_from_exe(Some(&exe_path)),
+            canonical_bin_dir
+                .join(CODE_MODE_HOST_EXECUTABLE_NAME)
+                .into_path_buf()
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn standalone_package_layout_keeps_standalone_install_method() -> std::io::Result<()> {
+        let codex_home = tempfile::tempdir()?;
+        let package_dir = codex_home
+            .path()
+            .join("packages/standalone/releases/1.2.3-x86_64-unknown-linux-musl");
+        let bin_dir = package_dir.join(BIN_DIRNAME);
+        let resources_dir = package_dir.join(RESOURCES_DIRNAME);
+        let path_dir = package_dir.join(PATH_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(&resources_dir)?;
+        fs::create_dir_all(&path_dir)?;
+        fs::write(package_dir.join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        fs::write(&exe_path, "")?;
+        fs::write(resources_dir.join(TEST_RESOURCE_NAME), "")?;
+        fs::write(path_dir.join(default_rg_command()), "")?;
+        let canonical_package_dir =
+            AbsolutePathBuf::from_absolute_path(package_dir.canonicalize()?)?;
+        let canonical_bin_dir = AbsolutePathBuf::from_absolute_path(bin_dir.canonicalize()?)?;
+        let canonical_resources_dir =
+            AbsolutePathBuf::from_absolute_path(resources_dir.canonicalize()?)?;
+        let canonical_path_dir = AbsolutePathBuf::from_absolute_path(path_dir.canonicalize()?)?;
+
+        let context = InstallContext::from_exe_with_codex_home(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+            /*codex_home*/ Some(codex_home.path()),
+        );
+        assert_eq!(
+            context,
+            InstallContext {
+                method: InstallMethod::Standalone {
+                    release_dir: canonical_package_dir.clone(),
+                    resources_dir: Some(canonical_resources_dir.clone()),
+                    platform: standalone_platform(),
+                },
+                package_layout: Some(CodexPackageLayout {
+                    package_dir: canonical_package_dir,
+                    bin_dir: canonical_bin_dir,
+                    resources_dir: Some(canonical_resources_dir.clone()),
+                    path_dir: Some(canonical_path_dir.clone()),
+                }),
+            }
+        );
+        assert_eq!(
+            context.rg_command(),
+            canonical_path_dir
+                .join(default_rg_command())
+                .into_path_buf()
+        );
+        assert_eq!(
+            context.bundled_resource(TEST_RESOURCE_NAME),
+            Some(canonical_resources_dir.join(TEST_RESOURCE_NAME))
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn npm_managed_package_keeps_package_layout() -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        let path_dir = package_dir.path().join(PATH_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(&path_dir)?;
+        fs::write(package_dir.path().join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        fs::write(&exe_path, "")?;
+        fs::write(path_dir.join(default_rg_command()), "")?;
+        let canonical_path_dir = AbsolutePathBuf::from_absolute_path(path_dir.canonicalize()?)?;
+
+        let context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ Some(InstallMethod::Npm),
+        );
+        assert_eq!(context.method, InstallMethod::Npm);
+        assert!(context.package_layout.is_some());
+        assert_eq!(
+            context.rg_command(),
+            canonical_path_dir
+                .join(default_rg_command())
+                .into_path_buf()
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn standalone_package_rg_falls_back_when_codex_path_is_missing() -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::write(package_dir.path().join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        fs::write(&exe_path, "")?;
+
+        let context = InstallContext::from_exe_with_codex_home(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+            /*codex_home*/ None,
+        );
+        assert_eq!(context.rg_command(), default_rg_command());
+        Ok(())
+    }
+
+    #[test]
+    fn bundled_file_lookups_ignore_directories() -> std::io::Result<()> {
+        let package_dir = tempfile::tempdir()?;
+        let bin_dir = package_dir.path().join(BIN_DIRNAME);
+        let resources_dir = package_dir.path().join(RESOURCES_DIRNAME);
+        let path_dir = package_dir.path().join(PATH_DIRNAME);
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(bin_dir.join(CODE_MODE_HOST_EXECUTABLE_NAME))?;
+        fs::create_dir_all(resources_dir.join(TEST_RESOURCE_NAME))?;
+        fs::create_dir_all(path_dir.join(default_rg_command()))?;
+        fs::write(package_dir.path().join(PACKAGE_METADATA_FILENAME), "{}")?;
+        let exe_path = bin_dir.join(if cfg!(windows) { "codex.exe" } else { "codex" });
+        fs::write(&exe_path, "")?;
+        let fallback_exe_path = package_dir.path().join("fallback-codex");
+        fs::write(&fallback_exe_path, "")?;
+
+        let context = InstallContext::from_exe_with_codex_home(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(&exe_path),
+            /*method_override*/ None,
+            /*codex_home*/ None,
+        );
+        assert_eq!(
+            context.code_mode_host_program_from_exe(Some(&fallback_exe_path)),
+            package_dir.path().join(CODE_MODE_HOST_EXECUTABLE_NAME)
+        );
+        assert_eq!(context.rg_command(), default_rg_command());
+        assert_eq!(context.bundled_resource(TEST_RESOURCE_NAME), None);
+        Ok(())
+    }
+
+    #[test]
+    fn code_mode_host_program_is_next_to_the_executable_even_when_missing() {
+        let context = InstallContext {
+            method: InstallMethod::Other,
+            package_layout: None,
+        };
+
+        assert_eq!(
+            context.code_mode_host_program_from_exe(Some(Path::new("/opt/codex/bin/codex"))),
+            PathBuf::from("/opt/codex/bin").join(CODE_MODE_HOST_EXECUTABLE_NAME)
+        );
+    }
+
+    #[test]
+    fn code_mode_host_program_falls_back_to_its_name_when_executable_is_unknown() {
+        let context = InstallContext {
+            method: InstallMethod::Other,
+            package_layout: None,
+        };
+
+        assert_eq!(
+            context.code_mode_host_program_from_exe(/*current_exe*/ None),
+            PathBuf::from(CODE_MODE_HOST_EXECUTABLE_NAME)
+        );
+    }
+
+    #[test]
+    fn package_manager_method_overrides_take_precedence() {
+        let vite_plus_context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(Path::new("/tmp/codex")),
+            /*method_override*/ Some(InstallMethod::VitePlus),
+        );
+        assert_eq!(
+            vite_plus_context,
+            InstallContext {
+                method: InstallMethod::VitePlus,
+                package_layout: None,
+            }
+        );
+
+        let pnpm_context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(Path::new("/tmp/codex")),
+            /*method_override*/ Some(InstallMethod::Pnpm),
+        );
+        assert_eq!(
+            pnpm_context,
+            InstallContext {
+                method: InstallMethod::Pnpm,
+                package_layout: None,
+            }
+        );
+
+        let npm_context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(Path::new("/tmp/codex")),
+            /*method_override*/ Some(InstallMethod::Npm),
+        );
+        assert_eq!(
+            npm_context,
+            InstallContext {
+                method: InstallMethod::Npm,
+                package_layout: None,
+            }
+        );
+
+        let bun_context = InstallContext::from_exe(
+            /*is_macos*/ false,
+            /*current_exe*/ Some(Path::new("/tmp/codex")),
+            /*method_override*/ Some(InstallMethod::Bun),
+        );
+        assert_eq!(
+            bun_context,
+            InstallContext {
+                method: InstallMethod::Bun,
+                package_layout: None,
+            }
+        );
+    }
+
+    #[test]
+    fn brew_is_detected_on_macos_prefixes() {
+        let context = InstallContext::from_exe_with_codex_home(
+            /*is_macos*/ true,
+            /*current_exe*/ Some(Path::new("/opt/homebrew/bin/codex")),
+            /*method_override*/ None,
+            /*codex_home*/ None,
+        );
+        assert_eq!(
+            context,
+            InstallContext {
+                method: InstallMethod::Brew,
+                package_layout: None,
+            }
+        );
+    }
+}

codex-rs/tui/assets/inline_visualization/visualize.css

@@ -0,0 +1,867 @@
+:root {
+  color-scheme: light dark;
+  background-color: var(
+    --background,
+    var(--color-background-primary, light-dark(rgb(255 255 255), rgb(24 24 24)))
+  ) !important;
+
+  /* Agent-facing contract; keep in sync with SKILL.md. */
+  --background: var(
+    --color-background-primary,
+    light-dark(rgb(255 255 255), rgb(24 24 24))
+  );
+  --foreground: var(
+    --color-text-primary,
+    light-dark(rgb(26 28 31), rgb(255 255 255))
+  );
+  --card: color-mix(in oklab, var(--foreground) 5%, var(--background));
+  --card-foreground: var(
+    --color-text-primary,
+    light-dark(rgb(26 28 31), rgb(255 255 255))
+  );
+  --popover: var(
+    --color-background-secondary,
+    light-dark(rgb(255 255 255), rgb(45 45 45))
+  );
+  --popover-foreground: var(
+    --color-text-primary,
+    light-dark(rgb(26 28 31), rgb(255 255 255))
+  );
+  --primary: var(
+    --color-text-info,
+    light-dark(rgb(51 156 255), rgb(131 195 255))
+  );
+  --primary-foreground: var(
+    --color-text-inverse,
+    light-dark(rgb(255 255 255), rgb(13 13 13))
+  );
+  --secondary: var(
+    --color-background-secondary,
+    light-dark(rgb(255 255 255 / 96%), rgb(54 54 54 / 96%))
+  );
+  --secondary-foreground: var(
+    --color-text-primary,
+    light-dark(rgb(26 28 31), rgb(255 255 255))
+  );
+  --muted: color-mix(in srgb, var(--foreground) 10%, transparent);
+  --muted-foreground: var(
+    --color-text-secondary,
+    light-dark(rgb(26 28 31 / 49.4%), rgb(255 255 255 / 49.8%))
+  );
+  --accent: var(
+    --color-background-info,
+    light-dark(rgb(229 242 255), rgb(13 39 63))
+  );
+  --accent-foreground: var(
+    --color-text-info,
+    light-dark(rgb(51 156 255), rgb(131 195 255))
+  );
+  --destructive: var(
+    --color-text-warning,
+    light-dark(rgb(226 85 7), rgb(255 133 73))
+  );
+  --border: var(
+    --color-border-secondary,
+    light-dark(rgb(26 28 31 / 8%), rgb(255 255 255 / 8.2%))
+  );
+  --input: var(
+    --color-border-primary,
+    light-dark(
+      rgb(26 28 31 / 11.8%),
+      color-mix(in oklab, rgb(0 0 0) 10%, transparent)
+    )
+  );
+  --ring: var(
+    --color-ring-primary,
+    light-dark(rgb(51 156 255), rgb(131 195 255 / 76%))
+  );
+  --font-size-base: var(--font-text-md-size, 14px);
+  --blue: light-dark(rgb(51 156 255), rgb(51 156 255));
+  --orange: light-dark(rgb(226 85 7), rgb(251 106 34));
+  --green: light-dark(rgb(0 162 64), rgb(64 201 119));
+  --red: light-dark(rgb(224 46 42), rgb(255 103 100));
+  --purple: light-dark(rgb(146 79 247), rgb(173 123 249));
+  --yellow: light-dark(rgb(255 195 0), rgb(255 210 64));
+  --viz-series-1: var(--primary);
+  --viz-series-2: light-dark(rgb(243 136 59), rgb(245 154 86));
+  --viz-series-3: light-dark(rgb(93 201 119), rgb(116 213 139));
+  --viz-series-4: light-dark(rgb(235 119 177), rgb(240 143 192));
+  --viz-series-5: light-dark(rgb(155 121 236), rgb(170 145 239));
+  --viz-series-6: light-dark(rgb(58 185 177), rgb(90 203 194));
+
+  /* Internal implementation variables; not part of the agent contract. */
+  --font-sans: -apple-system, system-ui, "Segoe UI", sans-serif;
+  --font-mono:
+    ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+    monospace;
+  --font-size-normal: max(11px, var(--font-size-base));
+  --font-size-tooltip: calc(var(--font-size-base) - 1px);
+  --font-size-small: max(11px, calc(var(--font-size-base) - 2px));
+  --font-size-h1: calc(var(--font-size-normal) * 1.7142857143);
+  --font-size-h2: calc(var(--font-size-normal) * 1.4285714286);
+  --font-size-h3: calc(var(--font-size-normal) * 1.2857142857);
+  --font-weight-normal: 430;
+  --font-weight-medium: 500;
+  --line-height-normal: calc(var(--font-size-normal) * 1.5);
+  --line-height-tooltip: calc(var(--font-size-tooltip) * 1.4285714286);
+  --line-height-small: calc(var(--font-size-small) + 4px);
+  --radius: var(--border-radius-lg, 12.5px);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-2xl: calc(var(--radius) * 1.6);
+  --radius-full: 9999px;
+  --shadow-sm: 0 1px 2px -1px rgb(0 0 0 / 8%);
+  --checkmark-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 17 17'%3E%3Cpath d='M12.8961 3.64101C13.1297 3.41418 13.4984 3.37523 13.7779 3.56581C14.0571 3.75635 14.1554 4.11331 14.0299 4.41347L13.9615 4.53847L7.71151 13.7045C7.59411 13.8767 7.4063 13.9877 7.19881 14.0072C6.99136 14.0267 6.78564 13.9533 6.63826 13.806L2.88826 10.056L2.79842 9.9457C2.6192 9.67407 2.64927 9.30496 2.88826 9.06581C3.12738 8.82669 3.49647 8.79676 3.76815 8.97597L3.8785 9.06581L7.03084 12.2182L12.8053 3.74941L12.8961 3.64101Z'/%3E%3C/svg%3E");
+
+  /* Legacy aliases; not part of the current agent contract. */
+  --viz-bg: transparent;
+  --viz-panel: var(--card);
+  --viz-border: var(--border);
+  --viz-text: var(--foreground);
+  --viz-muted: var(--muted-foreground);
+  --viz-accent: var(--primary);
+  --viz-accent-text: var(--primary-foreground);
+  --viz-accent-bg: var(--accent);
+  --viz-font-size: var(--font-size-base);
+  --viz-warning: var(--destructive);
+}
+
+:root[data-theme="light"] {
+  color-scheme: light;
+}
+
+:root[data-theme="dark"] {
+  color-scheme: dark;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html > body {
+  /* Preserve MCP aliases for older inline renderers without creating :root cycles. */
+  --color-background-primary: var(
+    --background,
+    light-dark(rgb(255 255 255), rgb(24 24 24))
+  );
+  --color-text-primary: var(
+    --foreground,
+    light-dark(rgb(26 28 31), rgb(255 255 255))
+  );
+  --color-border-secondary: var(
+    --border,
+    light-dark(rgb(26 28 31 / 8%), rgb(255 255 255 / 8.2%))
+  );
+
+  margin: 0;
+  padding: 5px;
+  color: var(--foreground);
+  background: transparent !important;
+  font-family: var(--font-sans);
+  font-size: var(--font-size-normal);
+  font-weight: var(--font-weight-normal);
+  line-height: var(--line-height-normal);
+}
+
+a {
+  color: color-mix(in srgb, var(--viz-accent) 80%, var(--viz-text) 20%);
+  cursor: pointer;
+  font-weight: var(--font-weight-medium, 500);
+  text-decoration: none;
+  text-underline-offset: 2px;
+}
+
+a:is(:hover, :focus-visible) {
+  text-decoration-line: underline;
+  text-decoration-style: dashed;
+  text-decoration-thickness: 0.5px;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+p {
+  margin-block: 0;
+}
+
+h1 {
+  font-size: var(--font-size-h1);
+  font-weight: var(--font-weight-medium);
+  line-height: 1.25;
+}
+
+h2 {
+  font-size: var(--font-size-h2);
+  font-weight: var(--font-weight-medium);
+  line-height: 1.25;
+}
+
+h3,
+h4,
+h5,
+h6 {
+  font-size: var(--font-size-h3);
+  font-weight: var(--font-weight-medium);
+  line-height: 1.3;
+}
+
+b,
+strong,
+th {
+  font-weight: var(--font-weight-medium);
+}
+
+code:not(pre code) {
+  display: inline;
+  padding: 1px 6px;
+  border-radius: var(--radius-sm);
+  corner-shape: superellipse(1.5);
+  background: var(--muted);
+  font-family: var(--font-mono);
+  font-size: 0.92em;
+  overflow-wrap: anywhere;
+  -webkit-box-decoration-break: clone;
+  box-decoration-break: clone;
+  word-break: break-word;
+}
+
+.table-responsive {
+  width: 100%;
+  overflow-x: auto;
+  scrollbar-width: thin;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  color: var(--foreground);
+  font: inherit;
+  text-align: start;
+}
+
+.table :is(th, td) {
+  padding-block: 10px;
+  padding-inline: 0 24px;
+  overflow-wrap: anywhere;
+  border-bottom: 1px solid var(--border);
+  text-align: start;
+  vertical-align: top;
+}
+
+.table-responsive > .table :is(th, td) {
+  overflow-wrap: break-word;
+}
+
+.table :is(th, td):last-child {
+  padding-inline-end: 0;
+}
+
+.table :is(caption, thead th) {
+  font-weight: 600;
+}
+
+.table thead th {
+  padding-block: 8px;
+  border-bottom-color: color-mix(in srgb, var(--foreground) 16%, transparent);
+}
+
+.table tbody tr:last-child :is(th, td) {
+  border-bottom: 0;
+}
+
+.table.table-sm :is(th, td) {
+  padding-block: 6px;
+}
+
+.table.table-sm :is(th, td):not(:last-child) {
+  padding-inline-end: 16px;
+}
+
+.table :is(.text-end, [align="right"]) {
+  text-align: end;
+  font-variant-numeric: tabular-nums;
+}
+
+.table :is(.text-center, [align="center"]) {
+  text-align: center;
+}
+
+.table .text-nowrap {
+  white-space: nowrap;
+}
+
+#widget {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  width: 100%;
+  padding: 0;
+  background: transparent !important;
+}
+
+.card {
+  min-width: 0;
+  padding: 12px;
+  overflow: hidden;
+  overflow-wrap: break-word;
+  border-radius: var(--radius-2xl);
+  corner-shape: superellipse(1.5);
+  color: var(--card-foreground);
+  background: var(--card);
+}
+
+#widget > :not(.card) {
+  width: 100% !important;
+  max-width: none !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  border-radius: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+}
+
+.tooltip {
+  position: fixed;
+  z-index: 50;
+  top: 0;
+  left: 0;
+  width: max-content;
+  max-width: min(
+    20rem,
+    var(--tooltip-available-width, calc(100vw - 10px)),
+    calc(100vw - 10px)
+  );
+  max-height: min(
+    var(--tooltip-available-height, calc(100vh - 10px)),
+    calc(100vh - 10px)
+  );
+  padding: 4px 8px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  corner-shape: superellipse(1.5);
+  color: var(--popover-foreground);
+  background: var(--popover);
+  box-shadow: none;
+  font-size: var(--font-size-tooltip);
+  line-height: var(--line-height-tooltip);
+  overflow-wrap: break-word;
+  white-space: normal;
+  pointer-events: none;
+  user-select: none;
+}
+
+.viz-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(max(180px, 24%), 1fr));
+  gap: 10px;
+}
+
+.viz-stat {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.viz-stat-value {
+  font-size: var(--font-size-h2);
+  font-weight: var(--font-weight-medium);
+  line-height: 1.25;
+}
+
+.viz-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+}
+
+.viz-badge {
+  padding: 3px 8px;
+  border-radius: var(--radius-full);
+  color: var(--accent-foreground);
+  background: var(--accent);
+  font-weight: var(--font-weight-medium);
+}
+
+small,
+.text-small,
+.viz-badge {
+  font-size: var(--font-size-small);
+  line-height: var(--line-height-small);
+}
+
+.text-muted {
+  color: var(--muted-foreground);
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.viz-controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+
+.viz-controls > .form-label {
+  display: grid;
+  min-width: min(100%, 260px);
+  flex: 1 1 280px;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: baseline;
+  gap: 2px 12px;
+  margin-bottom: 0;
+}
+
+.viz-controls > .form-label > :is(.form-control, .form-range, .form-select) {
+  grid-column: 1 / -1;
+}
+
+.btn,
+.form-check-input,
+.form-control,
+.form-range,
+.form-select {
+  font: inherit;
+}
+
+.btn {
+  appearance: button;
+  display: inline-flex;
+  inline-size: fit-content;
+  max-inline-size: 100%;
+  min-height: 28px;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  margin: 0;
+  padding: 0 8px;
+  -webkit-app-region: no-drag;
+  border: 1px solid var(--input);
+  border-radius: var(--radius-lg);
+  corner-shape: superellipse(1.5);
+  color: var(--secondary-foreground);
+  background: var(--secondary);
+  cursor: var(--cursor-interaction, pointer);
+  text-align: center;
+  text-decoration: none;
+  white-space: nowrap;
+  user-select: none;
+  -webkit-font-smoothing: antialiased;
+}
+
+.btn:is(.btn-block, .viz-tile) {
+  inline-size: 100%;
+}
+
+.btn.viz-tile {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  white-space: normal;
+}
+
+a.btn {
+  cursor: pointer;
+  text-decoration: none;
+}
+
+.btn:not(:disabled):hover {
+  background: color-mix(in srgb, var(--foreground) 6%, var(--secondary));
+}
+
+.btn-primary {
+  border-color: transparent;
+  color: var(--primary-foreground);
+  background: var(--foreground);
+  background-clip: padding-box;
+}
+
+.btn-primary .text-muted {
+  color: color-mix(in srgb, var(--primary-foreground) 50%, transparent);
+}
+
+.btn-primary:not(:disabled):hover {
+  background: color-mix(in srgb, var(--foreground) 80%, transparent);
+  background-clip: padding-box;
+}
+
+.btn-ghost {
+  border-color: transparent;
+  color: var(--muted-foreground);
+  background: transparent;
+}
+
+.btn-ghost:not(:disabled):hover {
+  color: var(--foreground);
+  background: color-mix(in srgb, var(--foreground) 6%, var(--secondary));
+}
+
+.btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+[data-lucide] {
+  stroke-width: 1.6;
+}
+
+.form-label {
+  display: block;
+  margin-bottom: 6px;
+  color: var(--foreground);
+}
+
+.form-control {
+  display: block;
+  width: 100%;
+  min-height: 28px;
+  padding: 0 8px;
+  outline: none;
+  border: 1px solid var(--input);
+  border-radius: var(--radius-lg);
+  corner-shape: superellipse(1.5);
+  color: var(--foreground);
+  background: var(--secondary);
+}
+
+.form-control::placeholder {
+  color: var(--muted-foreground);
+}
+
+.form-control[type="file"] {
+  padding: 0;
+  overflow: hidden;
+  cursor: var(--cursor-interaction, pointer);
+}
+
+.form-control[type="file"]::file-selector-button {
+  min-height: 26px;
+  margin-right: 8px;
+  padding: 0 8px;
+  border: 0;
+  border-right: 1px solid var(--input);
+  color: var(--secondary-foreground);
+  background: var(--secondary);
+  cursor: inherit;
+  font: inherit;
+}
+
+.form-control[type="file"]:not(:disabled):hover::file-selector-button {
+  background: color-mix(in srgb, var(--foreground) 6%, var(--secondary));
+}
+
+.form-control-color[type="color"] {
+  width: 40px;
+  height: 28px;
+  padding: 3px;
+  cursor: var(--cursor-interaction, pointer);
+}
+
+.form-control-color[type="color"]::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+.form-control-color[type="color"]::-webkit-color-swatch {
+  border: 0;
+  border-radius: calc(var(--radius-lg) - 4px);
+  corner-shape: superellipse(1.5);
+}
+
+textarea.form-control {
+  height: auto;
+  min-height: 72px;
+  padding: 8px 10px;
+  resize: vertical;
+}
+
+.form-control:focus-visible {
+  border-color: var(--ring);
+  box-shadow: inset 0 0 0 1px var(--ring);
+}
+
+.form-control:disabled,
+.form-select:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+.form-select {
+  appearance: none;
+  display: block;
+  width: 100%;
+  min-height: 28px;
+  margin: 0;
+  padding: 0 32px 0 8px;
+  outline: none;
+  border: 1px solid var(--input);
+  border-radius: var(--radius-lg);
+  corner-shape: superellipse(1.5);
+  color: var(--foreground);
+  background-color: var(--secondary);
+  background-image:
+    linear-gradient(45deg, transparent 50%, var(--muted-foreground) 50%),
+    linear-gradient(135deg, var(--muted-foreground) 50%, transparent 50%);
+  background-position:
+    calc(100% - 14px) 50%,
+    calc(100% - 10px) 50%;
+  background-repeat: no-repeat;
+  background-size: 4px 4px;
+  cursor: var(--cursor-interaction, default);
+}
+
+.form-select:not(:disabled):hover {
+  background-color: color-mix(in srgb, var(--foreground) 6%, var(--secondary));
+}
+
+.form-select:focus-visible {
+  border-color: var(--ring);
+  box-shadow: inset 0 0 0 1px var(--ring);
+}
+
+.form-check {
+  display: flex;
+  min-height: 20px;
+  align-items: center;
+  gap: 6px;
+}
+
+.form-check-input {
+  appearance: none;
+  width: 14px;
+  height: 14px;
+  flex: 0 0 auto;
+  margin: 0;
+  border: 1px solid var(--input);
+  color: var(--primary-foreground);
+  background-color: transparent;
+  cursor: var(--cursor-interaction, default);
+  transition:
+    background-color 150ms,
+    border-color 150ms,
+    box-shadow 150ms;
+}
+
+.form-check:not(.form-switch) .form-check-input[type="checkbox"] {
+  border-color: var(--input);
+  border-radius: var(--radius-sm);
+  corner-shape: superellipse(1.5);
+  background-color: var(--secondary);
+  box-shadow: var(--shadow-sm);
+}
+
+.form-check:not(.form-switch)
+  .form-check-input:not(:disabled):not(:checked):hover {
+  background-color: var(--card);
+}
+
+.form-check:not(.form-switch) .form-check-input[type="checkbox"]:checked {
+  border-color: var(--primary);
+  background-color: var(--primary);
+}
+
+.form-check:not(.form-switch)
+  .form-check-input[type="checkbox"]:checked::before {
+  display: block;
+  width: 100%;
+  height: 100%;
+  background: var(--primary-foreground);
+  content: "";
+  mask: var(--checkmark-image) center / 12px 12px no-repeat;
+}
+
+.form-check-input[type="radio"] {
+  width: 14px;
+  height: 14px;
+  border-radius: var(--radius-full);
+}
+
+.form-check-input[type="radio"]:checked {
+  border: 2px solid var(--primary);
+  background:
+    radial-gradient(circle, var(--primary-foreground) 0 2.5px, transparent 3px),
+    var(--primary);
+}
+
+.form-check:not(.form-switch) .form-check-input:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+.form-check:not(.form-switch) .form-check-input:disabled {
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+.form-check:not(.form-switch) .form-check-input:disabled + .form-check-label {
+  cursor: not-allowed;
+}
+
+.form-switch .form-check-input:disabled,
+.form-switch .form-check-input:disabled + .form-check-label {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.form-check-label {
+  color: var(--foreground);
+  cursor: var(--cursor-interaction, default);
+}
+
+.form-switch .form-check-input {
+  position: relative;
+  width: 32px;
+  height: 20px;
+  border: 0;
+  border-radius: var(--radius-full);
+  background: var(--muted);
+  box-shadow: none;
+  transition: background-color 200ms cubic-bezier(0, 0, 0.2, 1);
+}
+
+.form-switch .form-check-input::before {
+  position: absolute;
+  top: 50%;
+  left: 0;
+  width: 16px;
+  height: 16px;
+  box-sizing: border-box;
+  border: 1px solid light-dark(var(--primary-foreground), var(--foreground));
+  border-radius: var(--radius-full);
+  background: light-dark(var(--primary-foreground), var(--foreground));
+  box-shadow: var(--shadow-sm);
+  content: "";
+  transform: translate(2px, -50%);
+  transition: transform 200ms cubic-bezier(0, 0, 0.2, 1);
+}
+
+.form-switch .form-check-input:checked {
+  background: var(--primary);
+}
+
+.form-switch .form-check-input:checked::before {
+  transform: translate(14px, -50%);
+}
+
+.form-switch .form-check-input:focus-visible {
+  box-shadow: 0 0 0 2px var(--ring);
+}
+
+.form-range {
+  appearance: none;
+  display: block;
+  width: 100%;
+  height: 28px;
+  flex: 1;
+  margin: 0;
+  padding: 0;
+  outline: none;
+  border: 0;
+  accent-color: var(--primary);
+  background: linear-gradient(
+      color-mix(in srgb, var(--foreground) 7%, transparent),
+      color-mix(in srgb, var(--foreground) 7%, transparent)
+    )
+    center / 100% 2px no-repeat;
+}
+
+.form-range::-webkit-slider-runnable-track {
+  height: 28px;
+  background: transparent;
+}
+
+.form-range::-webkit-slider-thumb {
+  appearance: none;
+  width: 20px;
+  height: 20px;
+  margin-top: 4px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-full);
+  background: light-dark(var(--primary-foreground), var(--foreground));
+}
+
+.form-range:focus-visible::-webkit-slider-thumb {
+  border-color: var(--ring);
+  box-shadow: inset 0 0 0 1px var(--ring);
+}
+
+.form-range::-moz-range-track {
+  height: 28px;
+  background: transparent;
+}
+
+.form-range::-moz-range-thumb {
+  width: 20px;
+  height: 20px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-full);
+  background: light-dark(var(--primary-foreground), var(--foreground));
+}
+
+.form-range:focus-visible::-moz-range-thumb {
+  border-color: var(--ring);
+  box-shadow: inset 0 0 0 1px var(--ring);
+}
+
+.form-range:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+.btn:not(.btn-primary, .viz-tile):is(
+    [aria-pressed="true"],
+    [aria-selected="true"],
+    .is-selected
+  ) {
+  border-color: var(--primary);
+  color: var(--primary-foreground);
+  background: var(--primary);
+}
+
+.btn.viz-tile:is([aria-pressed="true"], [aria-selected="true"], .is-selected) {
+  border-color: var(--primary);
+  box-shadow: inset 0 0 0 1px var(--primary);
+}
+
+.btn:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+#widget > svg {
+  width: 100%;
+}
+
+/* Model-authored chart rules can otherwise stretch icons after these styles load. */
+svg.lucide {
+  display: block;
+  width: 16px !important;
+  height: 16px !important;
+  flex: none;
+  margin: 0 !important;
+  stroke-width: 1.6;
+}
+
+.text-warning,
+.text-destructive {
+  color: var(--destructive);
+}

codex-rs/tui/assets/inline_visualization/visualize.html

@@ -0,0 +1,239 @@
+<!--__INLINE_VISUALIZATION_FRAGMENT__-->
+<script src="https://unpkg.com/@floating-ui/core@1.7.3/dist/floating-ui.core.umd.min.js"></script>
+<script src="https://unpkg.com/@floating-ui/dom@1.7.4/dist/floating-ui.dom.umd.min.js"></script>
+<script>
+(() => {
+  if (window.FloatingUIDOM == null) {
+    return;
+  }
+  const { autoUpdate, computePosition, flip, offset, shift, size } =
+    window.FloatingUIDOM;
+  const tooltipPlacements = new Set(["top", "right", "bottom", "left"]);
+  const tooltipId = `codex-visualization-tooltip-${
+    window.crypto?.randomUUID?.() ?? Date.now().toString(36)
+  }`;
+  const tooltipGap = 5;
+  const hoverDelay = 700;
+  const skipDelay = 300;
+  let activeTrigger = null;
+  let pendingTrigger = null;
+  let tooltip = null;
+  let openTimeout = null;
+  let autoUpdateCleanup = null;
+  let positionRequest = 0;
+  let skipDelayUntil = 0;
+
+  const getTrigger = (target) =>
+    target?.nodeType === Node.ELEMENT_NODE
+      ? target.closest("[data-tooltip]")
+      : null;
+  const containsTarget = (trigger, target) =>
+    target?.nodeType != null && trigger.contains(target);
+  const getContent = (trigger) =>
+    trigger.getAttribute("data-tooltip")?.trim() ?? "";
+  const getPlacement = (trigger) => {
+    const placement = trigger.getAttribute("data-tooltip-placement");
+    return tooltipPlacements.has(placement) ? placement : "top";
+  };
+  const getTooltip = () => {
+    if (tooltip == null) {
+      tooltip = document.createElement("div");
+      tooltip.id = tooltipId;
+      tooltip.className = "tooltip";
+      tooltip.setAttribute("role", "tooltip");
+    }
+    return tooltip;
+  };
+  const setDescribedBy = (trigger, described) => {
+    const ids = new Set(
+      (trigger.getAttribute("aria-describedby") ?? "")
+        .split(/\s+/)
+        .filter(Boolean),
+    );
+    if (described) {
+      ids.add(tooltipId);
+    } else {
+      ids.delete(tooltipId);
+    }
+    if (ids.size === 0) {
+      trigger.removeAttribute("aria-describedby");
+    } else {
+      trigger.setAttribute("aria-describedby", [...ids].join(" "));
+    }
+  };
+  const clearOpenTimeout = () => {
+    if (openTimeout != null) {
+      window.clearTimeout(openTimeout);
+      openTimeout = null;
+    }
+    pendingTrigger = null;
+  };
+  const closeTooltip = (activateSkipDelay = true) => {
+    clearOpenTimeout();
+    positionRequest += 1;
+    autoUpdateCleanup?.();
+    autoUpdateCleanup = null;
+    if (activeTrigger == null) {
+      return;
+    }
+    setDescribedBy(activeTrigger, false);
+    activeTrigger = null;
+    tooltip?.remove();
+    if (activateSkipDelay) {
+      skipDelayUntil = Date.now() + skipDelay;
+    }
+  };
+  const updatePosition = (trigger, floating) => {
+    const request = ++positionRequest;
+    void computePosition(trigger, floating, {
+      middleware: [
+        offset(tooltipGap),
+        flip({ padding: tooltipGap }),
+        shift({ padding: tooltipGap }),
+        size({
+          padding: tooltipGap,
+          apply({ availableHeight, availableWidth, elements }) {
+            elements.floating.style.setProperty(
+              "--tooltip-available-width",
+              `${Math.max(0, availableWidth)}px`,
+            );
+            elements.floating.style.setProperty(
+              "--tooltip-available-height",
+              `${Math.max(0, availableHeight)}px`,
+            );
+          },
+        }),
+      ],
+      placement: getPlacement(trigger),
+      strategy: "fixed",
+    })
+      .then(({ x, y }) => {
+        if (activeTrigger !== trigger || request !== positionRequest) {
+          return;
+        }
+        const scale = window.devicePixelRatio || 1;
+        floating.style.transform = `translate(${Math.round(x * scale) / scale}px, ${Math.round(y * scale) / scale}px)`;
+        floating.style.visibility = "visible";
+      })
+      .catch(() => {
+        if (activeTrigger === trigger && request === positionRequest) {
+          closeTooltip(false);
+        }
+      });
+  };
+  const openTooltip = (trigger) => {
+    const content = getContent(trigger);
+    if (!trigger.isConnected || content.length === 0) {
+      return;
+    }
+    clearOpenTimeout();
+    if (activeTrigger === trigger) {
+      return;
+    }
+    closeTooltip();
+    const floating = getTooltip();
+    floating.textContent = content;
+    floating.style.visibility = "hidden";
+    floating.style.transform = "translate(0, 0)";
+    document.body.appendChild(floating);
+    activeTrigger = trigger;
+    setDescribedBy(trigger, true);
+    autoUpdateCleanup = autoUpdate(trigger, floating, () => {
+      updatePosition(trigger, floating);
+    });
+  };
+  const requestOpen = (trigger, immediate = false) => {
+    if (
+      getContent(trigger).length === 0 ||
+      activeTrigger === trigger ||
+      pendingTrigger === trigger
+    ) {
+      return;
+    }
+    clearOpenTimeout();
+    pendingTrigger = trigger;
+    const delay =
+      immediate || activeTrigger != null || Date.now() < skipDelayUntil
+        ? 0
+        : hoverDelay;
+    if (delay === 0) {
+      openTooltip(trigger);
+      return;
+    }
+    openTimeout = window.setTimeout(() => {
+      openTimeout = null;
+      pendingTrigger = null;
+      openTooltip(trigger);
+    }, delay);
+  };
+  const handlePointerOpen = (event) => {
+    if (event.pointerType === "touch") {
+      return;
+    }
+    const trigger = getTrigger(event.target);
+    if (trigger == null || containsTarget(trigger, event.relatedTarget)) {
+      return;
+    }
+    requestOpen(trigger);
+  };
+  const handleLeave = (event) => {
+    const trigger = getTrigger(event.target);
+    if (trigger == null || containsTarget(trigger, event.relatedTarget)) {
+      return;
+    }
+    if (activeTrigger === trigger || pendingTrigger === trigger) {
+      closeTooltip();
+    }
+  };
+  const handleFocusIn = (event) => {
+    const trigger = getTrigger(event.target);
+    if (trigger?.matches(":focus-visible")) {
+      requestOpen(trigger, true);
+    }
+  };
+  const handleKeyDown = (event) => {
+    if (event.key === "Escape") {
+      closeTooltip();
+    }
+  };
+  const handleContextMenu = (event) => {
+    const trigger = getTrigger(event.target);
+    if (activeTrigger === trigger || pendingTrigger === trigger) {
+      closeTooltip();
+    }
+  };
+  const destroy = () => {
+    closeTooltip(false);
+    document.removeEventListener("pointerover", handlePointerOpen);
+    document.removeEventListener("pointerout", handleLeave);
+    document.removeEventListener("focusin", handleFocusIn);
+    document.removeEventListener("focusout", handleLeave);
+    document.removeEventListener("keydown", handleKeyDown);
+    document.removeEventListener("contextmenu", handleContextMenu);
+    tooltip = null;
+  };
+
+  document.addEventListener("pointerover", handlePointerOpen);
+  document.addEventListener("pointerout", handleLeave);
+  document.addEventListener("focusin", handleFocusIn);
+  document.addEventListener("focusout", handleLeave);
+  document.addEventListener("keydown", handleKeyDown);
+  document.addEventListener("contextmenu", handleContextMenu);
+  window.addEventListener("pagehide", destroy, { once: true });
+})();
+</script>
+<script id="codex-visualization-lucide" async src="https://unpkg.com/lucide@1.17.0/dist/umd/lucide.js"></script>
+<script>
+(() => {
+  const initialize = () => {
+    globalThis.lucide?.createIcons({ attrs: { width: 16, height: 16 } });
+  };
+  if (globalThis.lucide != null) {
+    initialize();
+    return;
+  }
+  document
+    .getElementById("codex-visualization-lucide")
+    ?.addEventListener("load", initialize, { once: true });
+})();
+</script>

codex-rs/tui/frames/blocks/frame_1.txt

@@ -0,0 +1,17 @@
+                                      
+             ▒▓▒▓▒██▒▒██▒             
+         ▒▒█▓█▒█▓█▒▒░░▒▒ ▒ █▒         
+       █░█░███ ▒░   ░ █░ ░▒░░░█       
+      ▓█▒▒████▒            ▓█░▓░█     
+     ▒▒▓▓█▒░▒░▒▒             ▓░▒▒█    
+    ░█ █░  ░█▓▓░░█           █▓▒░░█   
+   █▒ ▓█    █▒░█▓ ░▒            ░▓░   
+   ░░▒░░     █▓▓░▓░█             ░░   
+   ░▒░█░    ▓░░▒▒░ ▓░██████▒██ ▒  ░   
+    ▒░▓█  ▒▓█░ ▓█ ░ ░▒▒▒▓▓███░▓█▓█░   
+    ▒▒▒ ▒ ▒▒█▓▓░   ░▒████ ▒█ ▓█▓▒▓    
+     █▒█  █ ░              ██▓█▒░     
+       ▒▒█░▒█▒          ▒▒▒█░▒█       
+         ▒██▒▒ ██▓▓▒▓▓▓▒██▒█░█        
+           ░█ █░░░▒▒▒█▒▓██            
+