Configuration, feature resolution, and startup policy assembly

fn inherit_exec_root_options(&mut self, root: &Self)

Purpose: This function fills in missing options on one command from a root, or top-level, command. It is used when a more specific command should inherit defaults from the command that wrapped it, while still keeping anything the specific command already chose.

Data flow: It starts with two sets of command-line options: self, which may be incomplete, and root, which represents the outer command's choices. For each setting, it copies the root value only when self has not already chosen a value. List-like settings, such as images and extra writable directories, are combined with the root values first. The result is that self is updated in place with inherited defaults and merged lists.

Call relations: This method is part of the setup path that combines shared command-line options before Codex acts on them. It does not hand work to another project-specific function in this file; its job is to apply the inheritance rules directly so later code can read one completed SharedCliOptions value.

fn apply_subcommand_overrides(&mut self, subcommand: Self)

Purpose: This function applies a subcommand's options on top of an existing set of options. It lets the more specific command override the broader command where the user clearly supplied a value.

Data flow: It takes the current options in self and a separate subcommand options value. If the subcommand contains a model, provider, profile, working directory, sandbox choice, or safety bypass choice, those values replace or update the current ones. Images from the subcommand replace the current images when present, while extra writable directories are added to the existing list. The result is an updated self that reflects the subcommand's more specific choices.

Call relations: This method is used after options have been parsed and a subcommand's settings need to be layered onto the main command's settings. Like the inheritance method, it keeps the merging logic local so the rest of the CLI can use the final options without re-deciding precedence rules.

fn new(
        codex_home: PathBuf,
        cli_overrides: Vec<(String, TomlValue)>,
        loader_overrides: LoaderOverrides,
        strict_config: bool,
        cloud_config_bundle: CloudConfigBu

Purpose: Creates a new shared configuration manager from the startup inputs. It stores fixed choices, such as the Codex home directory, and wraps changeable pieces in safe shared containers so the server can update them later.

Data flow: The caller gives paths, command-line overrides, loader options, strictness, cloud and thread loaders, and executable-path information. The function packages those values into a ConfigManager, putting mutable values behind shared read-write locks. The result is a manager that other server components can clone and use.

Call relations: This is used during server and test setup, including startup flows such as start_uninitialized and run_main_with_transport_options. Later functions on the manager rely on the stored pieces when they load or refresh configuration.

Call graph: called by 5 (start_uninitialized, refresh_test_state, build_test_processor, derive_config_from_params_uses_session_thread_config_model_provider, run_main_with_transport_options); 3 external calls (new, new, new).

fn codex_home(&self) -> &Path

Purpose: Returns the Codex home directory known by this manager. Other code uses this as the base place for finding config files and related state.

Data flow: It reads the stored home path and returns it as a path reference. Nothing is changed.

Call relations: This is a small helper used by user_config_path, load_default_config, and plugin-related code that needs to know where Codex lives on disk.

Call graph: called by 3 (load_default_config, user_config_path, emit_plugin_toggle_events); 1 external calls (as_path).

fn user_config_path(&self) -> std::io::Result<AbsolutePathBuf>

Purpose: Computes the path to the selected user configuration file. This respects any loader override that says to use a non-default config file.

Data flow: It reads the manager's Codex home path and loader override settings. It asks the loader override logic to resolve the user config path. The result is either an absolute path or an input/output error.

Call relations: This builds on ConfigManager::codex_home. It is used when code needs to know exactly which user config file is active, especially during default config loading or config editing.

Call graph: calls 2 internal fn (codex_home, user_config_path).

fn current_cli_overrides(&self) -> Vec<(String, TomlValue)>

Purpose: Returns the current command-line override settings. These are settings originally supplied outside the config file, and they should keep taking precedence when config is reloaded.

Data flow: It reads the shared override list through a read lock and clones it. If the lock cannot be read, it safely returns an empty list rather than crashing.

Call relations: Most config-loading paths call this before building config, including load_latest_config, load_with_overrides, load_for_cwd, load_default_config, load_config_layers, and thread startup.

Call graph: called by 6 (load_config_layers, load_default_config, load_for_cwd, load_latest_config, load_with_overrides, thread_start_task).

fn current_cloud_config_bundle(&self) -> CloudConfigBundleLoader

Purpose: Returns the current cloud-managed configuration loader. This lets config loading include settings supplied by a remote service when such settings are available.

Data flow: It reads the shared cloud config loader through a read lock and clones it. If the lock cannot be read, it falls back to the default empty loader.

Call relations: This is pulled into full config construction by load_with_cli_overrides and into layer inspection by load_config_layers.

Call graph: called by 2 (load_config_layers, load_with_cli_overrides).

fn extend_runtime_feature_enablement(&self, enablement: I) -> Result<(), ()>

Purpose: Adds or updates live feature switches while the server is running. This is used for experimental feature enablement without rewriting config files.

Data flow: It receives feature-name to enabled-or-disabled pairs. It takes a write lock on the runtime feature map and extends the stored map. It returns success, or a simple error if the lock cannot be acquired.

Call relations: The experimental feature setting flow calls this through set_experimental_feature_enablement. Later config loads apply these stored choices unless the features are protected by config policy.

Call graph: called by 1 (set_experimental_feature_enablement).

fn replace_cloud_config_bundle_loader(
        &self,
        auth_manager: Arc<AuthManager>,
        chatgpt_base_url: String,
    )

Purpose: Swaps in a new cloud config loader after ChatGPT authentication or cloud context changes. This lets future config loads see the latest cloud-managed settings.

Data flow: It receives an authentication manager and base URL, builds a fresh cloud config loader using the Codex home directory, and writes it into the shared slot. If the write lock fails, it logs a warning and leaves the old loader in place.

Call relations: Login completion paths call this after authentication state changes. Subsequent calls to current_cloud_config_bundle, load_with_cli_overrides, or load_config_layers will then use the updated loader.

Call graph: called by 2 (login_chatgpt_auth_tokens_response, send_chatgpt_login_completion_notifications); 3 external calls (clone, cloud_config_bundle_loader, warn!).

fn replace_thread_config_loader(
        &self,
        thread_config_loader: Arc<dyn ThreadConfigLoader>,
    )

Purpose: Replaces the component that knows how to load per-thread configuration. A thread here means a conversation or session whose settings may differ from the global defaults.

Data flow: It receives a new thread config loader and tries to store it behind the shared write lock. If the lock cannot be acquired, it logs a warning and keeps the previous loader.

Call relations: This prepares future config loads. current_thread_config_loader is the reader side that later hands the active loader to full config loading and config layer inspection.

Call graph: 1 external calls (warn!).

fn current_thread_config_loader(&self) -> Arc<dyn ThreadConfigLoader>

Purpose: Returns the currently active per-thread config loader. If the stored loader cannot be read, it uses a no-op loader, meaning a loader that intentionally adds nothing.

Data flow: It reads the shared loader, clones the shared pointer, and returns it. On lock failure, it creates and returns a no-op replacement.

Call relations: Both load_with_cli_overrides and load_config_layers call this so thread-specific settings can be included in the config view.

Call graph: called by 2 (load_config_layers, load_with_cli_overrides).

async fn sync_default_client_residency_requirement(&self)

Purpose: Updates the default network client with the latest data residency requirement from config. Data residency means a policy about where data is allowed to be processed or stored.

Data flow: It loads the latest config. If loading succeeds, it reads the enforce_residency setting and sends that value to the default client setup. If loading fails, it logs a warning.

Call relations: Authentication refresh and login completion code call this after credentials change. It depends on load_latest_config so the client policy follows the same config rules as the rest of the server.

Call graph: calls 2 internal fn (load_latest_config, set_default_client_residency_requirement); called by 2 (login_chatgpt_auth_tokens_response, send_chatgpt_login_completion_notifications); 1 external calls (warn!).

async fn load_latest_config(
        &self,
        fallback_cwd: Option<PathBuf>,
    ) -> std::io::Result<Config>

Purpose: Loads the freshest normal configuration using the manager's current command-line overrides. This is the common path for code that simply wants the current effective config.

Data flow: It gathers current command-line overrides, supplies no request-specific overrides, uses default typed overrides, and optionally supplies a fallback current working directory. It delegates the actual build to load_with_cli_overrides and returns the resulting Config or an error.

Call relations: Many refresh and inspection paths call this, including sync_default_client_residency_requirement, load_latest_config_for_thread, plugin cache refresh, and strict refresh work. It is a convenience wrapper around the more general loader.

Call graph: calls 2 internal fn (current_cli_overrides, load_with_cli_overrides); called by 10 (load_latest_config_for_thread, sync_default_client_residency_requirement, queue_strict_refresh, maybe_refresh_plugin_caches_for_current_config, load_latest_config, load_latest_config, load_latest_config, load_latest_config, load_latest_config, load_latest_config); 1 external calls (default).

async fn load_latest_config_for_thread(
        &self,
        thread_config: &Config,
    ) -> std::io::Result<Config>

Purpose: Refreshes configuration for an existing conversation or session while preserving that session's own config layers. This keeps a running thread consistent but still picks up newer global settings.

Data flow: It takes an existing thread config, reloads the latest config using that thread's current working directory as a fallback, then asks the old thread config to rebuild itself while preserving session-specific layers. Finally it applies runtime feature switches and executable paths, and returns the refreshed config.

Call relations: Thread-aware flows such as refresh config building, experimental feature listing, and MCP server status listing call this. It builds on load_latest_config and then finishes with the same final adjustments used by other load paths.

Call graph: calls 3 internal fn (apply_arg0_paths, apply_runtime_feature_enablement, load_latest_config); called by 3 (build_refresh_config, experimental_feature_list_response, list_mcp_server_status); 1 external calls (rebuild_preserving_session_layers).

async fn load_default_config(&self) -> std::io::Result<Config>

Purpose: Loads a default Codex configuration for the manager's home directory and command-line overrides. It is useful when the server needs a baseline config outside a specific request.

Data flow: It asks the core config system to load defaults using the Codex home and current command-line overrides. If user config path or profile overrides are set, it updates the config layer stack so the selected user config path and profile are preserved. It then applies runtime feature switches and executable paths before returning the config.

Call relations: This is a higher-level default-loading path. It uses helpers such as codex_home, current_cli_overrides, user_config_path, apply_runtime_feature_enablement, and apply_arg0_paths.

Call graph: calls 5 internal fn (apply_arg0_paths, apply_runtime_feature_enablement, codex_home, current_cli_overrides, user_config_path); 4 external calls (clone, Table, load_default_with_cli_overrides_for_codex_home, new).

async fn load_with_overrides(
        &self,
        request_overrides: Option<HashMap<String, serde_json::Value>>,
        typesafe_overrides: ConfigOverrides,
    ) -> std::io::Result<Config>

Purpose: Loads config with temporary request-level overrides plus typed override values. This is for operations that need a one-off setting change without changing stored config.

Data flow: It reads current command-line overrides, receives optional JSON-style request overrides and structured ConfigOverrides, then forwards all of that to load_with_cli_overrides with no fallback working directory. The output is a fully built Config or an error.

Call relations: Session persistence and thread startup use this when they need to mix normal config with request-specific choices. The real merging and building happens in load_with_cli_overrides.

Call graph: calls 2 internal fn (current_cli_overrides, load_with_cli_overrides); called by 2 (persist_session, thread_start_task).

async fn load_for_cwd(
        &self,
        request_overrides: Option<HashMap<String, serde_json::Value>>,
        typesafe_overrides: ConfigOverrides,
        cwd: Option<PathBuf>,
    ) -> std::io

Purpose: Loads config as it should apply to a specific current working directory. This matters because project-local settings may depend on where the command or thread is running.

Data flow: It receives optional request overrides, typed overrides, and an optional directory. It combines them with the current command-line overrides and delegates to load_with_cli_overrides. The result reflects the chosen directory when config loading needs one.

Call relations: Command execution, hook listing, thread fork and resume, thread setting construction, and Windows sandbox setup call this when the current directory matters.

Call graph: calls 2 internal fn (current_cli_overrides, load_with_cli_overrides); called by 6 (hooks_list_response, exec_one_off_command_inner, thread_fork_inner, thread_resume_inner, build_thread_settings_overrides, windows_sandbox_setup_start_inner).

async fn load_with_cli_overrides(
        &self,
        cli_overrides: &[(String, TomlValue)],
        request_overrides: Option<HashMap<String, serde_json::Value>>,
        mut typesafe_overrides: C

Purpose: Builds the full effective config from all active sources. This is the central assembly line for configuration in this file.

Data flow: It starts with command-line overrides and optional request overrides. A special request override, bypass_hook_trust, is checked to make sure it is a boolean and then moved into typed overrides. Other request override values are converted from JSON to TOML and merged with command-line overrides. The function then configures the core ConfigBuilder with home path, overrides, strict mode, fallback directory, cloud config, and thread loader. After the builder returns a config, it applies runtime feature switches and executable paths.

Call relations: load_latest_config, load_with_overrides, load_for_cwd, and thread startup all funnel into this function. It calls the helper readers for cloud and thread loaders, then uses apply_runtime_feature_enablement and apply_arg0_paths as final polishing steps.

Call graph: calls 4 internal fn (apply_arg0_paths, apply_runtime_feature_enablement, current_cloud_config_bundle, current_thread_config_loader); called by 4 (load_for_cwd, load_latest_config, load_with_overrides, thread_start_task); 3 external calls (clone, clone, default).

async fn load_config_layers_for_cwd(
        &self,
        cwd: AbsolutePathBuf,
    ) -> std::io::Result<ConfigLayerStack>

Purpose: Loads the raw configuration layer stack for a particular directory. A layer stack is the ordered set of config sources, such as defaults, user settings, project settings, and managed settings.

Data flow: It receives an absolute current working directory and passes it to load_config_layers as the directory to consider. It returns the resulting ConfigLayerStack or an error.

Call relations: resolve_cwd_config calls this when it needs to inspect config layers for a directory. This is a thin convenience wrapper around load_config_layers.

Call graph: calls 1 internal fn (load_config_layers); called by 1 (resolve_cwd_config).

async fn load_config_layers(
        &self,
        cwd: Option<AbsolutePathBuf>,
    ) -> std::io::Result<ConfigLayerStack>

Purpose: Loads the config layers without necessarily building the final Config object. This is useful for tools that need to see where settings came from, not just the final answer.

Data flow: It reads the current thread loader, command-line overrides, cloud config loader, loader override settings, and strict mode. It passes these plus the filesystem, Codex home, and optional directory into the lower-level layer loader. The output is a ConfigLayerStack describing the effective layered state.

Call relations: load_config_layers_for_cwd and permission-profile listing call this. It mirrors the same ingredients used by full config loading so layer inspection matches normal behavior.

Call graph: calls 4 internal fn (current_cli_overrides, current_cloud_config_bundle, current_thread_config_loader, load_config_layers_state); called by 2 (load_config_layers_for_cwd, permission_profile_list_response); 1 external calls (clone).

fn apply_runtime_feature_enablement(&self, config: &mut Config)

Purpose: Applies the manager's stored live feature switches to a config. It is the object-method wrapper around the standalone feature-application function.

Data flow: It reads the current runtime feature map from the manager, then passes the mutable config and that map to the standalone apply_runtime_feature_enablement. The config may have feature flags changed as a result.

Call relations: Full loading paths call this after config creation, including load_default_config, load_latest_config_for_thread, and load_with_cli_overrides. It bridges stored manager state to the pure helper function.

Call graph: calls 2 internal fn (current_runtime_feature_enablement, apply_runtime_feature_enablement); called by 3 (load_default_config, load_latest_config_for_thread, load_with_cli_overrides).

fn current_runtime_feature_enablement(&self) -> BTreeMap<String, bool>

Purpose: Returns the current live feature switch map. These are runtime choices stored by feature-name and true-or-false value.

Data flow: It reads the shared runtime feature map and clones it. If the read lock fails, it returns an empty map so config loading can continue safely.

Call relations: Only ConfigManager::apply_runtime_feature_enablement calls this. It keeps the lock-reading detail separate from the feature-application logic.

Call graph: called by 1 (apply_runtime_feature_enablement).

fn apply_arg0_paths(&self, config: &mut Config)

Purpose: Copies executable paths discovered at process startup into the config. These paths tell Codex where to find its own executable and related sandbox or wrapper executables.

Data flow: It reads the stored arg0_paths from the manager and writes those path values into the mutable config. It returns nothing; the config is changed in place.

Call relations: Config-loading paths call this at the end of loading, including load_default_config, load_latest_config_for_thread, and load_with_cli_overrides. This makes sure the built config knows the actual executable paths used by this server process.

Call graph: called by 3 (load_default_config, load_latest_config_for_thread, load_with_cli_overrides).

fn new_for_tests(
        codex_home: PathBuf,
        cli_overrides: Vec<(String, TomlValue)>,
        loader_overrides: LoaderOverrides,
        cloud_config_bundle: CloudConfigBundleLoader,
    ) -

Purpose: Creates a ConfigManager with simple defaults for tests. It avoids requiring production-only pieces such as strict config, real process dispatch paths, or a real thread config loader.

Data flow: Test code supplies a Codex home, command-line overrides, loader overrides, and a cloud config loader. The function fills in test-friendly defaults and calls the normal constructor. The result is a usable manager for unit and integration tests.

Call relations: Many config tests call this when they need a controlled manager. It keeps test setup short while still exercising the same main constructor as production code.

Call graph: called by 9 (invalid_user_value_rejected_even_if_overridden_by_managed, load_default_config_preserves_selected_user_config_path_after_load_error, read_includes_origins_and_layers, read_reports_managed_overrides_user_and_session_flags, write_value_defaults_to_selected_user_config_path, write_value_rejects_feature_requirement_conflict, write_value_reports_managed_override, write_value_reports_override, write_value_succeeds_when_managed_preferences_expand_home_directory_paths); 3 external calls (new, new, default).

fn without_managed_config_for_tests(codex_home: PathBuf) -> Self

Purpose: Creates a test ConfigManager that deliberately ignores managed configuration. Managed configuration means centrally supplied settings that can override local user choices.

Data flow: It receives a Codex home, creates empty command-line overrides, uses loader overrides that disable managed config for tests, and uses the default cloud config loader. It returns a test manager through new_for_tests.

Call relations: Config editing and validation tests call this when they need a clean local-only setup. It builds on new_for_tests, which then builds on the normal manager constructor.

Call graph: calls 2 internal fn (default, without_managed_config_for_tests); called by 12 (batch_write_rejects_legacy_profile_selector, clear_missing_nested_config_is_noop, reserved_builtin_provider_override_rejected, upsert_merges_tables_replace_overwrites, version_conflict_rejected, write_value_defaults_to_user_config_path, write_value_preserves_comments_and_order, write_value_rejects_legacy_profile_selector, write_value_rejects_legacy_profile_table, write_value_supports_custom_mcp_server_default_tool_approval_mode (+2 more)); 2 external calls (new_for_tests, new).

fn protected_feature_keys(config_layer_stack: &ConfigLayerStack) -> BTreeSet<String>

Purpose: Finds feature flags that runtime switches are not allowed to change. A feature is protected if it is already set in the effective config or appears in feature requirements.

Data flow: It reads the effective config layer stack and collects keys under the features table. It also reads feature requirements and adds any required feature names. The output is a sorted set of protected feature keys.

Call relations: The standalone apply_runtime_feature_enablement function calls this before applying live feature changes. This provides the guardrail that prevents runtime toggles from overriding config-controlled or requirement-controlled features.

Call graph: calls 2 internal fn (effective_config, requirements_toml); called by 1 (apply_runtime_feature_enablement).

fn apply_runtime_feature_enablement(
    config: &mut Config,
    runtime_feature_enablement: &BTreeMap<String, bool>,
)

Purpose: Applies live feature toggles to a config, but only when doing so is allowed. It skips protected features and ignores unknown feature names.

Data flow: It receives a mutable config and a map of feature names to enabled-or-disabled values. It first computes protected feature names from the config layer stack. For each runtime entry, it skips protected names, looks up known feature definitions, and sets the feature state in the config. If setting a feature fails, it logs a warning and continues.

Call relations: The method ConfigManager::apply_runtime_feature_enablement calls this after loading config. This function contains the actual policy: runtime choices can adjust known, unprotected features but cannot override stronger config sources.

Call graph: calls 1 internal fn (protected_feature_keys); called by 1 (apply_runtime_feature_enablement); 2 external calls (feature_for_key, warn!).

fn project_root_markers_from_config(config: &TomlValue) -> io::Result<Option<Vec<String>>>

Purpose: This function reads the project_root_markers entry from an already-merged TOML configuration value. It returns either no custom setting, a list of marker names, an explicit empty list meaning “turn this feature off,” or an error if the setting is written incorrectly.

Data flow: It receives a TOML value, which is the parsed configuration data. First it checks whether that value is a table, then looks for project_root_markers. If the entry is missing, it returns None. If the entry is present, it must be an array; each item in that array must be a string. Valid strings are copied into a new list and returned as Some(list). If the shape is wrong, it returns an invalid-data error explaining that the setting must be an array of strings.

Call relations: During configuration loading, load_config_layers_state calls this function after the configuration layers have been combined. This function does the focused checking and extraction for this one setting, then hands back either the markers or a clear error so the larger loader can continue or stop safely.

Call graph: called by 1 (load_config_layers_state); 3 external calls (as_table, new, new).

fn default_project_root_markers() -> Vec<String>

Purpose: This function provides the built-in project root markers used when the user has not chosen their own. Currently it returns .git, so Git repositories are recognized as project roots by default.

Data flow: It reads the file’s constant default marker list, converts each borrowed text value into an owned string, and returns those strings in a vector. It does not read files, inspect the current directory, or change any state.

Call relations: This function is the fallback source for root markers when configuration does not provide project_root_markers. It keeps the default choice in one place, separate from the code that reads user-provided settings.

fn default() -> Self

Purpose: Provides safe legacy defaults for the old ghost_snapshot settings. The snapshot feature no longer produces snapshots, but old config files can still mention these keys without breaking startup.

Data flow: No input is needed. It creates a GhostSnapshotConfig with default thresholds for large untracked files and directories, and warnings enabled. The result is used as a compatibility value.

Call relations: During full config construction, the loader starts from this default and then applies any old ghost_snapshot values it finds. Tests and default config construction also rely on it so legacy settings remain harmless.

Call graph: called by 2 (load_config_with_layer_stack, new_config).

fn default_multi_agent_v2_usage_hint_text(usage_hint_text: &str, max_concurrency: usize) -> String

Purpose: Builds the default instruction text shown to agents when multi-agent v2 is enabled. It explains how agents should collaborate and how many concurrent agent slots are available.

Data flow: It receives a role-specific hint and a maximum concurrency number. It combines them with shared collaboration guidance and returns one final instruction string.

Call relations: The multi-agent default builder calls this when it creates root-agent and sub-agent guidance. That keeps the repeated collaboration rules in one place.

Call graph: called by 1 (defaults_for_max_concurrency); 1 external calls (format!).

fn resolve_sqlite_home_env(resolved_cwd: &Path) -> Option<PathBuf>

Purpose: Interprets the environment variable that can move Codex's SQLite state directory. SQLite is the local database storage used for some state.

Data flow: It reads the environment variable, trims whitespace, ignores it if empty, and turns it into a path. Relative paths are resolved against the current working directory; absolute paths are used as-is.

Call relations: The main config loader uses this as one possible source for sqlite_home, after explicit config and before falling back to the Codex home directory.

Call graph: 3 external calls (join, from, var).

fn resolve_cli_auth_credentials_store_mode(
    configured: AuthCredentialsStoreMode,
    package_version: &str,
) -> AuthCredentialsStoreMode

Purpose: Chooses where CLI login credentials should be stored, with a special fallback for local development builds. Local dev builds avoid keyring storage when the setting is auto or keyring.

Data flow: It receives the configured credential storage mode and package version. If this is the local development version and the mode would use a keyring, it returns file storage; otherwise it returns the configured mode.

Call relations: The main config loader calls this before placing the auth storage choice into Config, so auth code later receives the resolved behavior rather than raw user input.

Call graph: called by 1 (load_config_with_layer_stack).

fn resolve_mcp_oauth_credentials_store_mode(
    configured: OAuthCredentialsStoreMode,
    package_version: &str,
) -> OAuthCredentialsStoreMode

Purpose: Chooses where MCP OAuth credentials should be stored, with the same local-development safety fallback as CLI credentials.

Data flow: It receives the configured MCP OAuth storage mode and package version. For local development builds, keyring-like choices become file storage; all other cases keep the original mode.

Call relations: The main config loader calls this while building the MCP-related fields of Config, and later MCP setup uses the resolved choice.

Call graph: called by 1 (load_config_with_layer_stack).

async fn test_config() -> Config

Purpose: Creates a default Config in a temporary Codex home for tests. It gives tests a clean, isolated configuration without using the real user's files.

Data flow: It creates a temporary directory, loads default TOML with default overrides, and returns a ready Config. If setup fails, the test fails immediately.

Call relations: Many tests call this when they need a realistic but isolated configuration. Internally it uses the same lower-level loading path as production, minus managed requirements enforcement for convenience.

Call graph: calls 1 internal fn (from_absolute_path); called by 32 (interrupted_v2_agent_is_lost_after_residency_eviction, residency_slot_reservation_unloads_oldest_idle_v2_agent, guardian_review_session_compact_scope_change_invalidates_cached_session, guardian_review_session_config_change_invalidates_cached_session, guardian_review_session_config_disables_hooks, guardian_review_session_config_disables_skill_instructions, guardian_review_session_config_allows_pinned_disabled_feature, guardian_review_session_config_clears_legacy_notify, guardian_review_session_config_clears_parent_developer_instructions, guardian_review_session_config_disables_mcp_apps_plugins_and_memories (+15 more)); 4 external calls (load_from_base_config_with_overrides, default, default, tempdir).

fn from_approval_and_profile(
        approval_policy: Constrained<AskForApproval>,
        permission_profile: Constrained<PermissionProfile>,
    ) -> ConstraintResult<Self>

Purpose: Builds a minimal Permissions object from an approval policy and permission profile. This is useful when code needs permissions without loading a full config file.

Data flow: It takes constrained approval and permission values, converts the permission profile into internal state, and fills the remaining permission fields with safe defaults. It returns either a complete Permissions value or a constraint error.

Call relations: Tests and helper config constructors use this to create permission settings directly. It delegates profile-state creation to the resolved permission-profile module.

Call graph: calls 2 internal fn (from_constrained_legacy, default); called by 3 (permission_snapshot_setter_preserves_permission_constraints, new_config, debug_config_output_filters_sandbox_modes_blocked_by_deny_read_requirements); 1 external calls (new).

fn permission_profile_state(&self) -> &PermissionProfileState

Purpose: Gives internal code read-only access to the stored permission profile state. The state includes both the profile and metadata about how it was selected.

Data flow: It reads the Permissions object and returns a reference to its internal profile state. Nothing is changed.

Call relations: This is a small accessor used by nearby modules that need the richer state, not just the simplified permission profile.

fn set_permission_profile_state(
        &mut self,
        permission_profile_state: PermissionProfileState,
    )

Purpose: Replaces the internal permission profile state. This is used when another part of the system has already resolved and validated a new state.

Data flow: It receives a new PermissionProfileState and stores it inside Permissions. It does not return a value.

Call relations: Permission update code calls this after resolving a profile elsewhere, so the Permissions object stays in sync with the chosen profile.

Call graph: called by 1 (apply_permission_profile_to_permissions).

fn set_permission_profile_from_session_snapshot(
        &mut self,
        snapshot: PermissionProfileSnapshot,
    ) -> ConstraintResult<()>

Purpose: Applies a permission snapshot that came from an existing session. A snapshot is a trusted record of the permissions that core session state already chose.

Data flow: It receives a snapshot, asks the internal state to accept it, and returns success or a constraint error. The permission state may be updated.

Call relations: Clients that mirror session state use this bridge instead of resolving named profiles themselves. It hands the actual validation to PermissionProfileState.

Call graph: calls 1 internal fn (set_permission_profile_snapshot).

fn replace_permission_profile_from_session_snapshot(
        &mut self,
        snapshot: PermissionProfileSnapshot,
    ) -> ConstraintResult<()>

Purpose: Forcefully replaces local permission constraints with a trusted session snapshot. This is for clients that must mirror core state even if their local config would reject it.

Data flow: It receives a session snapshot, wraps its profile as the only allowed value, converts the snapshot into resolved profile data, and replaces the internal state. It returns success or a constraint error.

Call relations: This is a stronger version of the snapshot setter. It is used when preserving session truth matters more than local config constraints.

Call graph: calls 4 internal fn (allow_only, into_resolved_permission_profile, permission_profile, from_constrained_resolved).

fn permission_profile(&self) -> &PermissionProfile

Purpose: Returns the canonical permission profile before runtime workspace roots are expanded. The canonical profile is the source version stored by config.

Data flow: It reads the internal profile state and returns a reference to the current profile. It does not modify anything.

Call relations: Several permission projections call this before deriving file-system, network, or materialized runtime views.

Call graph: calls 1 internal fn (permission_profile); called by 2 (materialized_permission_profile, network_sandbox_policy).

fn can_set_permission_profile(
        &self,
        permission_profile: &PermissionProfile,
    ) -> ConstraintResult<()>

Purpose: Checks whether a proposed permission profile is allowed by the current constraints. It answers the question before actually changing permissions.

Data flow: It receives a profile candidate, compares it against the internal constraints, and returns success or a constraint error. No state changes.

Call relations: Callers that let users or sessions change sandbox behavior use this as a guard before applying the profile.

Call graph: calls 1 internal fn (can_set_legacy_permission_profile); called by 1 (sandbox_mode_is_allowed_by_permissions).

fn set_workspace_roots(&mut self, workspace_roots: Vec<AbsolutePathBuf>)

Purpose: Sets the runtime workspace roots used by permission profiles. Workspace roots are the directories treated as the active working area for the session.

Data flow: It receives a list of absolute paths and stores it. Future permission calculations will use these roots.

Call relations: Runtime setup or session updates can call this when the active workspace changes.

fn workspace_roots(&self) -> &[AbsolutePathBuf]

Purpose: Returns the runtime workspace roots currently stored in permissions.

Data flow: It reads the list of roots and returns it as a slice. Nothing is changed.

Call relations: The higher-level Config::set_legacy_sandbox_policy uses this after updating permissions so the top-level config mirrors the permission state.

Call graph: called by 1 (set_legacy_sandbox_policy).

fn user_visible_workspace_roots(&self) -> &[AbsolutePathBuf]

Purpose: Returns workspace roots that came from user-facing config or runtime selection. It intentionally excludes internal Codex-only helper paths.

Data flow: It reads the stored workspace roots and returns them directly. No data is transformed.

Call relations: UI or reporting code can use this when it should show only roots meaningful to the user.

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

Purpose: Returns workspace roots that are defined by the active permission profile itself. These are separate from runtime roots such as the current directory.

Data flow: It asks the internal permission profile state for its profile-level roots and returns them. Nothing is changed.

Call relations: Top-level config combines these with runtime roots when computing the full effective workspace root list.

Call graph: calls 1 internal fn (profile_workspace_roots); called by 1 (effective_workspace_roots).

fn materialized_permission_profile(&self) -> PermissionProfile

Purpose: Creates the actual runtime permission profile by replacing symbolic workspace-root markers with concrete directories.

Data flow: It clones the stored canonical profile, applies the current workspace root list, and returns a concrete profile. The stored profile is not changed.

Call relations: Permission projections for file-system sandboxing and legacy sandbox compatibility use this because tools need real paths, not symbols.

Call graph: calls 1 internal fn (permission_profile); called by 3 (effective_permission_profile, file_system_sandbox_policy, legacy_sandbox_policy).

fn effective_permission_profile(&self) -> PermissionProfile

Purpose: Returns the permission profile that should be enforced at runtime. It includes runtime workspace-root expansion.

Data flow: It reads the stored profile and workspace roots, materializes them, and returns the resulting profile.

Call relations: Runtime tool execution can use this when it needs the complete current permission picture.

Call graph: calls 1 internal fn (materialized_permission_profile).

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

Purpose: Reports the named permission profile currently selected, if there is one. Some permissions may come from an anonymous or legacy profile, so this can be absent.

Data flow: It asks the profile state for active profile metadata and returns it as an optional value. Nothing changes.

Call relations: Session configuration and UI code use this to show or preserve the selected named profile.

Call graph: calls 1 internal fn (active_permission_profile).

fn file_system_sandbox_policy(&self) -> FileSystemSandboxPolicy

Purpose: Derives the file access rules that spawned tools should follow. A sandbox policy is the rule set that limits reads and writes.

Data flow: It materializes the permission profile and converts it into a file-system sandbox policy. The result describes allowed and denied paths.

Call relations: Tool execution and sandbox setup use this projection because they need concrete file rules.

Call graph: calls 1 internal fn (materialized_permission_profile).

fn network_sandbox_policy(&self) -> NetworkSandboxPolicy

Purpose: Derives the network access rules from the current permission profile. This says whether network access is enabled, disabled, or controlled.

Data flow: It reads the canonical profile and returns its network policy. Workspace roots are not relevant here.

Call relations: Network proxy setup and runtime permission checks use this when deciding how external traffic should be treated.

Call graph: calls 1 internal fn (permission_profile).

fn legacy_sandbox_policy(&self, cwd: &Path) -> SandboxPolicy

Purpose: Converts modern permission profiles into the older SandboxPolicy shape. This keeps older code paths working while newer profile logic remains the source of truth.

Data flow: It materializes the permission profile using the current roots, then converts it into a legacy sandbox policy for a given current directory.

Call relations: The top-level Config::legacy_sandbox_policy calls this for consumers that still expect legacy sandbox settings.

Call graph: calls 1 internal fn (materialized_permission_profile); called by 1 (legacy_sandbox_policy); 1 external calls (compatibility_sandbox_policy_for_permission_profile).

fn can_set_legacy_sandbox_policy(
        &self,
        sandbox_policy: &SandboxPolicy,
        cwd: &Path,
    ) -> ConstraintResult<()>

Purpose: Checks whether an old-style sandbox policy can be accepted under the current permission constraints.

Data flow: It receives a legacy sandbox policy and current directory, converts that policy into the modern permission profile form, and checks constraints. It returns success or a constraint error without changing state.

Call relations: The setter for legacy sandbox policies calls this first, so invalid changes are rejected before any permission fields are updated.

Call graph: calls 5 internal fn (can_set_legacy_permission_profile, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from); called by 1 (set_legacy_sandbox_policy).

fn set_legacy_sandbox_policy(
        &mut self,
        sandbox_policy: SandboxPolicy,
        cwd: &Path,
    ) -> ConstraintResult<()>

Purpose: Applies an old-style sandbox policy while keeping the modern permission profile state consistent.

Data flow: It validates the legacy policy, converts it into file, network, and modern permission profile forms, updates workspace roots based on the policy, and stores the profile. It returns success or a constraint error.

Call relations: Top-level config calls this when legacy sandbox settings are changed, and this method performs the actual permission-state update.

Call graph: calls 6 internal fn (can_set_legacy_sandbox_policy, set_legacy_permission_profile, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from); called by 1 (set_legacy_sandbox_policy); 1 external calls (vec!).

fn set_permission_profile(
        &mut self,
        permission_profile: PermissionProfile,
    ) -> ConstraintResult<()>

Purpose: Sets the current permission profile directly using the modern profile format.

Data flow: It receives a permission profile and asks the internal state to store it if constraints allow. It returns success or a constraint error.

Call relations: Code that already works with modern profiles can call this without going through legacy sandbox conversion.

Call graph: calls 1 internal fn (set_legacy_permission_profile).

fn profile_allows_configured_network_proxy(permission_profile: &PermissionProfile) -> bool

Purpose: Decides whether a permission profile is allowed to inherit configured network proxy behavior. Disabled permissions mean Codex is not controlling the network sandbox, so adding a managed proxy would unexpectedly narrow access.

Data flow: It receives a permission profile and returns true only for managed or external profiles whose network policy is enabled. Disabled profiles return false.

Call relations: The main config loader and active-profile network proxy recalculation use this before applying proxy allowlists.

Call graph: called by 2 (load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile).

fn build_network_proxy_spec(
    configured_network_proxy_config: NetworkProxyConfig,
    network_requirements: Option<Sourced<codex_config::NetworkConstraints>>,
    permission_profile: &PermissionPr

Purpose: Builds the final managed network proxy plan from user config, managed requirements, and the active permission profile.

Data flow: It receives proxy config, optional network requirements, and a permission profile. It combines them into a NetworkProxySpec, wraps errors with requirement-source context when useful, and returns either no proxy or a proxy spec.

Call relations: Full config loading and runtime profile switching call this after deciding which network settings are eligible.

Call graph: calls 1 internal fn (from_config_and_constraints); called by 2 (load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile).

fn defaults_for_max_concurrency(max_concurrent_threads_per_session: usize) -> Self

Purpose: Creates default settings for multi-agent v2 based on how many agents may run at once.

Data flow: It receives a concurrency limit and fills timeout values, instruction text, namespace behavior, and display flags. It returns a complete multi-agent v2 config.

Call relations: The resolver for multi-agent v2 config uses this as the base before applying user-specified overrides.

Call graph: calls 1 internal fn (default_multi_agent_v2_usage_hint_text); called by 1 (resolve_multi_agent_v2_config).

fn default() -> Self

Purpose: Provides the standard multi-agent v2 defaults. It uses the built-in concurrency limit.

Data flow: It has no input. It calls the concurrency-aware default builder and returns the resulting config.

Call relations: Default config construction uses this when no custom multi-agent v2 settings are supplied.

Call graph: called by 1 (new_config); 1 external calls (defaults_for_max_concurrency).

fn codex_home(&self) -> PathBuf

Purpose: Returns the Codex home directory for authentication code. Codex home is where user-level Codex state and config live.

Data flow: It reads self.codex_home, clones it into a normal path buffer, and returns it.

Call relations: This is part of the AuthManagerConfig interface, letting login code use Config without knowing all of its fields.

Call graph: calls 1 internal fn (to_path_buf).

fn cli_auth_credentials_store_mode(&self) -> AuthCredentialsStoreMode

Purpose: Returns the resolved storage mode for CLI authentication credentials.

Data flow: It reads the config field and returns the enum value. Nothing is changed.

Call relations: Auth management code calls this through the AuthManagerConfig interface when deciding whether to use a file, keyring, or automatic choice.

fn auth_keyring_backend_kind(&self) -> AuthKeyringBackendKind

Purpose: Returns which operating-system keyring backend should be used for credentials. A keyring is the OS secure credential store.

Data flow: It delegates to the config's keyring resolution helper and returns the backend kind.

Call relations: MCP config creation calls this so OAuth setup can use the same keyring decision as the rest of auth.

Call graph: called by 1 (to_mcp_config_with_plugin_registrations); 1 external calls (auth_keyring_backend_kind).

fn forced_chatgpt_workspace_id(&self) -> Option<Vec<String>>

Purpose: Returns any configured restriction on which ChatGPT workspaces may be used.

Data flow: It clones the optional workspace ID list from config and returns it.

Call relations: Authentication code reads this through the AuthManagerConfig interface to enforce login restrictions.

fn chatgpt_base_url(&self) -> String

Purpose: Returns the base URL used for ChatGPT backend requests.

Data flow: It clones the configured URL string and returns it.

Call relations: Auth and MCP-related code call this through shared configuration interfaces.

fn codex_home(mut self, codex_home: PathBuf) -> Self

Purpose: Sets the Codex home directory on a config builder.

Data flow: It receives a path, stores it in the builder, and returns the builder so calls can be chained.

Call relations: Callers use this before build when they want to load config from a specific home directory instead of the default.

fn cli_overrides(mut self, cli_overrides: Vec<(String, TomlValue)>) -> Self

Purpose: Sets command-line override values on a config builder.

Data flow: It receives key-value override pairs, stores them, and returns the builder for chaining.

Call relations: Startup paths use this so flags can override values from config files.

fn harness_overrides(mut self, harness_overrides: ConfigOverrides) -> Self

Purpose: Sets runtime-only overrides that do not come from normal TOML config. Examples include current directory and executable paths.

Data flow: It receives a ConfigOverrides value, stores it, and returns the builder.

Call relations: CLI subcommands and tests use this to force behavior for a particular run.

fn loader_overrides(mut self, loader_overrides: LoaderOverrides) -> Self

Purpose: Sets overrides for the lower-level config layer loader.

Data flow: It receives loader options, stores them, and returns the builder.

Call relations: Tests and profile-loading paths use this when they need to skip or alter managed config loading.

fn strict_config(mut self, strict_config: bool) -> Self

Purpose: Controls whether config loading should be strict about errors and unknowns.

Data flow: It receives a boolean, stores it, and returns the builder.

Call relations: Startup can enable this when it wants invalid config to fail early rather than be tolerated.

fn cloud_config_bundle(mut self, cloud_config_bundle: CloudConfigBundleLoader) -> Self

Purpose: Supplies cloud-managed config data to the builder.

Data flow: It receives a cloud bundle loader, stores it, and returns the builder.

Call relations: Managed or enterprise-style configuration flows use this before building the final config.

fn thread_config_loader(
        mut self,
        thread_config_loader: Arc<dyn ThreadConfigLoader>,
    ) -> Self

Purpose: Supplies a loader for thread-scoped configuration. Thread-scoped config is config tied to a specific conversation or session thread.

Data flow: It receives a shared loader object, stores it, and returns the builder.

Call relations: App-server or session-aware startup code can use this so thread settings participate in the same layer merge.

fn fallback_cwd(mut self, fallback_cwd: Option<PathBuf>) -> Self

Purpose: Sets a fallback current working directory for config loading.

Data flow: It receives an optional path, stores it, and returns the builder.

Call relations: Builder startup uses this if harness overrides did not already provide a current directory.

async fn build(self) -> std::io::Result<Config>

Purpose: Starts building the final Config. It boxes the work so the large async load process does not use too much stack space.

Data flow: It consumes the builder, runs the inner build future, and returns either a complete config or an I/O error.

Call relations: Runtime startup helpers call this after setting builder options. It hands all real work to build_inner.

Call graph: calls 1 internal fn (build_inner); called by 1 (build_config_on_runtime_worker); 1 external calls (pin).

async fn build_inner(self) -> std::io::Result<Config>

Purpose: Performs the full builder-based config loading flow. It finds paths, loads config layers, handles config lock replay, and constructs the final Config.

Data flow: It consumes builder fields, resolves Codex home and current directory, loads and merges config layers, deserializes the merged TOML, optionally replaces it with a config lock, and returns a final config.

Call relations: build calls this. It delegates raw layer loading to codex_config, then delegates final interpretation to Config::load_config_with_layer_stack.

Call graph: calls 9 internal fn (load_config_layers_state, new, find_codex_home, config_without_lock_controls, lock_layer_from_config, read_config_lock_from_path, current_dir, from_absolute_path, relative_to_current_dir); called by 1 (build); 5 external calls (new, load_config_with_layer_stack, new, io_error_from_config_error, vec!).

fn without_managed_config_for_tests() -> Self

Purpose: Creates a builder preset that skips managed configuration for tests.

Data flow: It starts with a default builder, applies test loader overrides, and returns the builder.

Call relations: Tests call this when they need predictable local config behavior without cloud or managed requirements.

Call graph: calls 1 internal fn (without_managed_config_for_tests); called by 58 (test_config_with_cli_overrides, inline_instructions_set_base_instructions, active_profile_is_cleared_when_requirements_force_fallback, agent_role_file_metadata_overrides_config_toml_metadata, agent_role_file_name_takes_precedence_over_config_key, agent_role_file_without_developer_instructions_is_dropped_with_warning, agent_role_relative_config_file_resolves_against_config_toml, agent_role_without_description_after_merge_is_dropped_with_warning, approvals_reviewer_can_be_set_in_config_without_guardian_approval, approvals_reviewer_defaults_to_manual_only_without_guardian_feature (+15 more)); 1 external calls (default).

fn multi_agent_version_from_features(&self) -> MultiAgentVersion

Purpose: Decides which multi-agent system version is active based on feature flags.

Data flow: It reads enabled features and returns v2, v1, or disabled. V2 takes priority over the older collaboration feature.

Call relations: Session and agent orchestration code can use this after config load to choose the correct agent tool surface.

Call graph: 1 external calls (enabled).

fn validate_multi_agent_v2_config(&self) -> std::io::Result<()>

Purpose: Rejects an incompatible setting combination for multi-agent v2. The older agents.max_threads setting cannot be used with v2.

Data flow: It reads feature flags and agent_max_threads. If v2 is enabled and the old setting is present, it returns an invalid-input error; otherwise it succeeds.

Call relations: Runtime setup can call this after loading config to catch conflicting agent settings before work begins.

Call graph: 2 external calls (new, enabled).

fn effective_agent_max_threads(
        &self,
        multi_agent_version: MultiAgentVersion,
    ) -> Option<usize>

Purpose: Calculates how many child agent threads may be used for the active multi-agent mode.

Data flow: It receives the selected multi-agent version. For v2 it uses the v2 concurrency limit minus the root agent; for older or disabled modes it uses the old agent limit or default.

Call relations: Agent orchestration uses this to enforce thread limits consistently across old and new multi-agent modes.

fn legacy_sandbox_policy(&self) -> SandboxPolicy

Purpose: Returns the current permissions in the old sandbox-policy format.

Data flow: It reads the config current directory and delegates to Permissions::legacy_sandbox_policy. The output is a legacy sandbox policy.

Call relations: Older callers that still speak SandboxPolicy use this instead of reading modern permission profiles directly.

Call graph: calls 2 internal fn (legacy_sandbox_policy, as_path).

fn set_legacy_sandbox_policy(
        &mut self,
        sandbox_policy: SandboxPolicy,
    ) -> ConstraintResult<()>

Purpose: Applies an old-style sandbox policy to the whole config and keeps workspace root fields synchronized.

Data flow: It receives a legacy policy, marks whether workspace roots were explicitly set, asks Permissions to apply it, then copies the updated roots back to the top-level config.

Call relations: Legacy sandbox-changing code calls this higher-level wrapper so both Config and Permissions stay aligned.

Call graph: calls 3 internal fn (set_legacy_sandbox_policy, workspace_roots, as_path); 1 external calls (matches!).

fn effective_workspace_roots(&self) -> Vec<AbsolutePathBuf>

Purpose: Returns the full set of workspace roots that should matter at runtime.

Data flow: It starts with top-level runtime roots, appends roots supplied by the active permission profile, removes duplicates, and returns the combined list.

Call relations: Runtime and UI code use this when they need the complete workspace view rather than just one source of roots.

Call graph: calls 2 internal fn (profile_workspace_roots, dedupe_absolute_paths).

fn to_models_manager_config(&self) -> ModelsManagerConfig

Purpose: Extracts the part of Config needed by the model manager. The model manager controls model catalog and context-window behavior.

Data flow: It reads model-related limits, instructions, personality feature state, and catalog overrides, then returns a smaller ModelsManagerConfig.

Call relations: Model-management code calls this instead of depending on the entire large Config type.

Call graph: 1 external calls (enabled).

fn plugins_config_input(&self) -> PluginsConfigInput

Purpose: Builds the input object used to decide which plugins are available.

Data flow: It reads the config layer stack, plugin feature flags, remote-plugin feature flag, and ChatGPT base URL. It returns a PluginsConfigInput.

Call relations: MCP config construction calls this before asking the plugin manager for active plugins.

Call graph: calls 1 internal fn (new); called by 1 (to_mcp_config_with_plugin_registrations); 2 external calls (clone, enabled).

fn apply_plugin_mcp_server_requirements(
        &self,
        plugin_id: &str,
        mcp_servers: &mut HashMap<String, McpServerConfig>,
    )

Purpose: Applies managed allowlists to MCP servers supplied by a plugin. MCP servers provide external tools using the Model Context Protocol.

Data flow: It receives a plugin ID and mutable server map. It disables plugin servers that do not match plugin requirements and also handles the special case of an empty global MCP allowlist.

Call relations: When building MCP config, each active plugin's servers pass through this filter before registration.

Call graph: calls 3 internal fn (requirements, filter_mcp_servers_by_requirements, filter_plugin_mcp_servers_by_requirements); called by 1 (to_mcp_config_with_plugin_registrations).

async fn to_mcp_config(
        &self,
        plugins_manager: &codex_core_plugins::PluginsManager,
    ) -> McpConfig

Purpose: Builds the MCP runtime config using the normal plugin registrations.

Data flow: It receives a plugin manager, calls the more general MCP builder with no extra registrations, and returns an McpConfig.

Call relations: MCP startup code calls this common path. It delegates the detailed catalog construction to to_mcp_config_with_plugin_registrations.

Call graph: calls 1 internal fn (to_mcp_config_with_plugin_registrations).

async fn to_mcp_config_with_plugin_registrations(
        &self,
        plugins_manager: &codex_core_plugins::PluginsManager,
        additional_plugin_registrations: impl IntoIterator<Item = McpServ

Purpose: Builds the full MCP configuration, including plugin-provided servers, extra registrations, configured servers, auth settings, sandbox settings, and capabilities.

Data flow: It asks the plugin manager for plugins allowed by config, filters their MCP servers, registers plugin and extra servers, then registers user-configured servers. It returns an McpConfig with all connection and capability details.

Call relations: to_mcp_config calls this for the standard path. Tests or advanced flows can pass extra server registrations through this lower-level method.

Call graph: calls 11 internal fn (new, from_config, from_plugin, builder, get, plugins_for_config, apply_plugin_mcp_server_requirements, auth_keyring_backend_kind, plugins_config_input, prefix_mcp_tool_names (+1 more)); called by 1 (to_mcp_config); 5 external calls (default, default, default, enabled, use_legacy_landlock).

fn prefix_mcp_tool_names(&self) -> bool

Purpose: Decides whether MCP tool names should be prefixed to avoid name collisions.

Data flow: It reads the NonPrefixedMcpToolNames feature flag and returns false only when that feature is enabled.

Call relations: MCP config construction uses this to choose how tool names are exposed to the model.

Call graph: called by 1 (to_mcp_config_with_plugin_registrations); 1 external calls (enabled).

async fn rebuild_preserving_session_layers(
        &self,
        refreshed_config: &Config,
    ) -> std::io::Result<Self>

Purpose: Rebuilds config from refreshed files while keeping session-specific layers from the existing config. This is useful for runtime reloads that should not forget flags set for the current session.

Data flow: It combines non-session layers from the refreshed config with session layers from the current config, sorts them by precedence, rebuilds the layer stack, deserializes it, and loads a new Config using the current cwd.

Call relations: Runtime reload code can call this after user or project config changes. It delegates final interpretation to load_config_with_layer_stack.

Call graph: calls 3 internal fn (get_layers, new, to_path_buf); 2 external calls (default, load_config_with_layer_stack).

async fn load_with_cli_overrides(
        cli_overrides: Vec<(String, TomlValue)>,
    ) -> std::io::Result<Self>

Purpose: Loads a normal full configuration with command-line overrides.

Data flow: It creates a default builder, attaches CLI override key-value pairs, builds the config, and returns the result.

Call relations: This is the preferred public entry for startup paths that only need CLI overrides.

Call graph: 1 external calls (default).

async fn load_default_with_cli_overrides(
        cli_overrides: Vec<(String, TomlValue)>,
    ) -> std::io::Result<Self>

Purpose: Loads default config plus CLI overrides when user config files should not be read or are invalid.

Data flow: It finds the Codex home directory, then delegates to the Codex-home-specific default loader. It returns a complete fallback config.

Call relations: Recovery startup paths use this when normal config loading fails but the application still needs a safe baseline.

Call graph: calls 1 internal fn (find_codex_home); 1 external calls (load_default_with_cli_overrides_for_codex_home).

async fn load_default_with_cli_overrides_for_codex_home(
        codex_home: PathBuf,
        cli_overrides: Vec<(String, TomlValue)>,
    ) -> std::io::Result<Self>

Purpose: Loads default config for a specific Codex home without reading user, project, or system config layers.

Data flow: It serializes default TOML, merges CLI overrides into it, deserializes with the Codex home as the path base, and builds a final config from an empty layer stack.

Call relations: The broader default loader calls this after finding Codex home. It still uses the main final config constructor so defaults are interpreted consistently.

Call graph: calls 2 internal fn (deserialize_config_toml_with_base, from_absolute_path_checked); 7 external calls (load_config_with_layer_stack, build_cli_overrides_layer, merge_toml_values, default, default, default, try_from).

async fn load_with_cli_overrides_and_harness_overrides(
        cli_overrides: Vec<(String, TomlValue)>,
        harness_overrides: ConfigOverrides,
    ) -> std::io::Result<Self>

Purpose: Loads full config with both CLI overrides and runtime-only harness overrides.

Data flow: It creates a default builder, attaches both override sets, builds the config, and returns the result.

Call relations: Subcommands such as noninteractive execution use this when they must force settings that are not representable in config.toml.

Call graph: 1 external calls (default).

fn resolve_profile_v2_config_path(
    codex_home: &Path,
    profile_name: &ProfileV2Name,
) -> AbsolutePathBuf

Purpose: Builds the file path for a named v2 config profile. Profiles are stored as separate TOML files under the Codex home directory.

Data flow: It receives Codex home and a profile name, appends the profile suffix, resolves it against Codex home, and returns an absolute path.

Call relations: CLI profile loading and app-server archive startup call this to locate profile-specific config files.

Call graph: calls 1 internal fn (resolve_path_against_base); called by 3 (loader_overrides_for_profile, run_main, start_app_server_for_archive_command); 1 external calls (format!).

async fn load_config_as_toml_with_cli_overrides(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    loader_overrides: LoaderOverrides,
) -> std:

Purpose: Loads merged config as raw ConfigToml with CLI overrides. It is deprecated because it does not produce fully enforced runtime Config.

Data flow: It forwards Codex home, current directory, CLI overrides, and loader overrides to the next helper and returns the raw TOML config.

Call relations: Older callers use this compatibility path. It delegates immediately to the more general loader-overrides helper.

Call graph: calls 1 internal fn (load_config_as_toml_with_cli_and_loader_overrides).

async fn load_config_as_toml_with_cli_and_loader_overrides(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    loader_overrides: LoaderOverrides

Purpose: Loads merged config as raw ConfigToml with CLI and loader overrides. It is also deprecated for most callers.

Data flow: It passes its arguments to the load-options version and returns the resulting raw config.

Call relations: It exists as a compatibility step between the older helper name and the newer load-options helper.

Call graph: calls 1 internal fn (load_config_as_toml_with_cli_and_load_options); called by 1 (load_config_as_toml_with_cli_overrides).

async fn load_config_as_toml_with_cli_and_load_options(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    options: impl Into<ConfigLoadOptions>

Purpose: Loads only the deserialized TOML part of the config using general load options.

Data flow: It calls the layer-stack loader, then extracts and returns only the config_toml field from the result.

Call relations: Deprecated raw-config callers use this when they need merged TOML but not the final Config object.

Call graph: calls 1 internal fn (load_config_toml_with_layer_stack); called by 1 (load_config_as_toml_with_cli_and_loader_overrides).

async fn load_config_toml_with_layer_stack(
    codex_home: &Path,
    cwd: Option<&AbsolutePathBuf>,
    cli_overrides: Vec<(String, TomlValue)>,
    options: impl Into<ConfigLoadOptions>,
) -> std::

Purpose: Loads merged TOML together with the layer stack that produced it. This is for startup paths that need to inspect raw config before full construction.

Data flow: It loads config layers, gets their effective merged TOML, deserializes it with a base directory for relative paths, and returns both the TOML and stack.

Call relations: Bootstrap and archive-server paths use this when they need both raw config and managed requirements context.

Call graph: calls 2 internal fn (load_config_layers_state, deserialize_config_toml_with_base); called by 4 (load_config_as_toml_with_cli_and_load_options, load_bootstrap_config_or_exit, load_bootstrap_config_or_exit, start_app_server_for_archive_command).

fn deserialize_config_toml_with_base(
    root_value: TomlValue,
    config_base_dir: &Path,
) -> std::io::Result<ConfigToml>

Purpose: Turns a generic TOML value into ConfigToml while resolving relative paths against a chosen base directory.

Data flow: It installs a temporary path-resolution guard, deserializes the TOML value, and returns either ConfigToml or an invalid-data error.

Call relations: Config loaders and config editing code use this so relative paths mean the same thing wherever deserialization happens.

Call graph: calls 1 internal fn (new); called by 5 (apply_edits, load_role_layer_toml, deserialize_effective_config, load_default_with_cli_overrides_for_codex_home, load_config_toml_with_layer_stack); 1 external calls (try_into).

fn validate_feature_requirements_for_config_toml(
    cfg: &ConfigToml,
    feature_requirements: Option<&Sourced<FeatureRequirementsToml>>,
) -> std::io::Result<()>

Purpose: Checks feature settings in raw config against managed feature requirements.

Data flow: It receives parsed config and optional feature requirements, validates explicit feature choices, then validates required feature states. It returns success or an I/O error.

Call relations: Config editing calls this before saving changes that might violate managed feature policy.

Call graph: calls 2 internal fn (validate_explicit_feature_settings_in_config_toml, validate_feature_requirements_in_config_toml); called by 1 (apply_edits).

fn load_catalog_json(path: &AbsolutePathBuf) -> std::io::Result<ModelsResponse>

Purpose: Reads and validates a custom model catalog JSON file. A model catalog lists available models and their metadata.

Data flow: It receives a path, reads the file, parses it as JSON into a model response, checks that at least one model exists, and returns the catalog or an error.

Call relations: The model catalog resolver calls this when config points to a custom catalog file.

Call graph: 3 external calls (new, format!, read_to_string).

fn load_model_catalog(
    model_catalog_json: Option<AbsolutePathBuf>,
) -> std::io::Result<Option<ModelsResponse>>

Purpose: Optionally loads a custom model catalog from a configured path.

Data flow: It receives an optional path. If present, it loads and validates the JSON file; if absent, it returns None.

Call relations: The main config loader calls this while filling the model-catalog field.

Call graph: called by 1 (load_config_with_layer_stack).

fn filter_mcp_servers_by_requirements(
    mcp_servers: &mut HashMap<String, McpServerConfig>,
    mcp_requirements: Option<&Sourced<BTreeMap<String, McpServerRequirement>>>,
)

Purpose: Disables configured MCP servers that are not allowed by managed requirements.

Data flow: It receives a mutable server map and an optional allowlist. If an allowlist exists, each server is checked by name and identity; disallowed servers are marked disabled with a reason.

Call relations: Plugin filtering and MCP constraint construction use this to enforce server allowlists.

Call graph: called by 1 (apply_plugin_mcp_server_requirements).

fn filter_plugin_mcp_servers_by_requirements(
    plugin_config_name: &str,
    mcp_servers: &mut HashMap<String, McpServerConfig>,
    plugin_requirements: Option<&Sourced<BTreeMap<String, PluginRequ

Purpose: Disables MCP servers from one plugin unless managed plugin requirements allow them.

Data flow: It receives a plugin name, mutable server map, and optional plugin requirements. It finds requirements for that plugin, checks each server, and marks disallowed ones disabled.

Call relations: Config::apply_plugin_mcp_server_requirements calls this before plugin MCP servers are registered.

Call graph: called by 1 (apply_plugin_mcp_server_requirements).

fn constrain_mcp_servers(
    mcp_servers: HashMap<String, McpServerConfig>,
    mcp_requirements: Option<&Sourced<BTreeMap<String, McpServerRequirement>>>,
) -> ConstraintResult<Constrained<HashMap<S

Purpose: Wraps MCP server configuration in a constraint-aware value. Constraints can normalize the map by disabling disallowed servers.

Data flow: It receives the server map and optional requirements. Without requirements it allows any map; with requirements it returns a constrained value that filters servers through the requirements.

Call relations: The main config loader calls this before storing mcp_servers in the final config.

Call graph: calls 2 internal fn (allow_any, normalized); called by 1 (load_config_with_layer_stack).

fn apply_requirement_constrained_value(
    field_name: &'static str,
    configured_value: T,
    constrained_value: &mut ConstrainedWithSource<T>,
    startup_warnings: &mut Vec<String>,
) -> std::i

Purpose: Applies a configured value to a requirement-constrained setting, falling back with a startup warning if the value is not allowed.

Data flow: It receives a field name, candidate value, constrained holder, and warning list. It tries to set the candidate; on failure it logs, warns, restores the requirement-compliant fallback, and reports whether fallback happened.

Call relations: The main config loader uses this repeatedly for approvals, permission profiles, web search, and Windows sandbox settings.

Call graph: called by 1 (load_config_with_layer_stack); 4 external calls (get, set, format!, warn!).

fn mcp_server_matches_requirement(
    requirement: &McpServerRequirement,
    server: &McpServerConfig,
) -> bool

Purpose: Checks whether an MCP server matches the identity required by a managed allowlist.

Data flow: It receives one requirement and one server config. It compares command-based servers by command and URL-based servers by URL, then returns true or false.

Call relations: Both MCP filtering helpers use this as their per-server identity test.

Call graph: 1 external calls (matches!).

async fn load_global_mcp_servers(
    codex_home: &Path,
) -> std::io::Result<BTreeMap<String, McpServerConfig>>

Purpose: Loads globally configured MCP servers without a project context. It is used by commands that edit or inspect global MCP config.

Data flow: It loads config layers for Codex home with no current directory, extracts the mcp_servers TOML table if present, rejects deprecated inline bearer tokens, deserializes the servers, and returns them.

Call relations: MCP add, remove, and list commands call this because they need raw global server definitions rather than the full runtime config.

Call graph: calls 2 internal fn (load_config_layers_state, ensure_no_inline_bearer_tokens); called by 11 (run_add, run_remove, add_and_remove_server_updates_global_config, add_cant_add_command_and_url, add_streamable_http_rejects_removed_flag, add_streamable_http_with_custom_env_var, add_streamable_http_with_oauth_options, add_streamable_http_without_manual_token, add_with_env_preserves_key_order_and_values, get_disabled_server_shows_single_line (+1 more)); 3 external calls (new, new, default).

fn ensure_no_inline_bearer_tokens(value: &TomlValue) -> std::io::Result<()>

Purpose: Rejects old MCP config that stores bearer tokens directly in config. Bearer tokens are secrets and should come from environment variables instead.

Data flow: It receives a TOML value, looks for bearer_token keys under MCP server tables, and returns an invalid-data error if one is found.

Call relations: load_global_mcp_servers calls this before deserializing servers so users get a clear message about the unsupported field.

Call graph: called by 1 (load_global_mcp_servers); 3 external calls (as_table, new, format!).

fn set_project_trust_level_inner(
    doc: &mut DocumentMut,
    project_path: &Path,
    trust_level: TrustLevel,
) -> anyhow::Result<()>

Purpose: Edits a TOML document in memory to record whether a project is trusted or untrusted. Project trust influences default approvals and sandbox behavior.

Data flow: It receives a mutable TOML document, project path, and trust level. It ensures the [projects] structure exists in a readable table form, creates or updates the project entry, and writes trust_level.

Call relations: The config editing layer calls this while applying trust edits to config.toml.

Call graph: calls 1 internal fn (project_trust_key); called by 1 (apply); 7 external calls (as_table_mut, anyhow!, to_string, Table, new, table, value).

fn set_project_trust_level(
    codex_home: &Path,
    project_path: &Path,
    trust_level: TrustLevel,
) -> anyhow::Result<()>

Purpose: Persists a project's trust level into CODEX_HOME/config.toml.

Data flow: It receives Codex home, project path, and trust level. It builds a config edit operation and applies it synchronously, returning success or an error.

Call relations: Thread startup, project-aware commands, and tests call this to mark projects trusted or untrusted.

Call graph: calls 1 internal fn (new); called by 10 (thread_start_task, config_read_includes_project_layers_for_cwd, hooks_list_uses_each_cwds_effective_feature_enablement, hooks_list_uses_root_repo_hooks_for_linked_worktrees, mcp_server_status_list_uses_thread_project_local_config, permission_profile_list_discovers_project_profiles_without_default_selection, permission_profile_list_resolves_project_profiles_and_paginates, plugin_list_uses_home_config_for_enabled_state, thread_start_respects_project_config_from_cwd, thread_start_skips_trust_write_when_project_is_already_trusted).

fn set_default_oss_provider(codex_home: &Path, provider: &str) -> std::io::Result<()>

Purpose: Saves the default open-source model provider preference to config. It validates the provider name before writing.

Data flow: It receives Codex home and provider string, validates the provider, builds a TOML edit for oss_provider, applies it, and returns success or an I/O error.

Call relations: CLI flows that set local or OSS provider preferences use this helper to update config safely.

Call graph: calls 2 internal fn (validate_oss_provider, new); 1 external calls (vec!).

fn resolve_tool_suggest_config(
    config_toml: &ConfigToml,
    config_layer_stack: &ConfigLayerStack,
) -> ToolSuggestConfig

Purpose: Computes the final tool-suggestion settings from parsed config and the layer stack.

Data flow: It reads the tool_suggest section from ConfigToml, then delegates to the shared resolver that also considers layer ordering.

Call relations: The main config loader calls this while constructing the final Config.

Call graph: calls 1 internal fn (resolve_tool_suggest_config_from_config); called by 1 (load_config_with_layer_stack).

fn resolve_tool_suggest_config_from_layer_stack(
    config_layer_stack: &ConfigLayerStack,
) -> ToolSuggestConfig

Purpose: Computes tool-suggestion settings directly from a config layer stack.

Data flow: It extracts the effective tool_suggest value from merged config if possible, then delegates to the common resolver. It returns normalized discoverable and disabled tool lists.

Call relations: Runtime config refresh paths call this when they reload config layers without rebuilding the entire Config.

Call graph: calls 2 internal fn (effective_config, resolve_tool_suggest_config_from_config); called by 2 (refresh_runtime_config, reload_user_config_layer).

fn resolve_tool_suggest_config_from_config(
    tool_suggest: Option<&ToolSuggestConfig>,
    config_layer_stack: &ConfigLayerStack,
) -> ToolSuggestConfig

Purpose: Normalizes tool-suggestion config and merges disabled-tool entries in layer order.

Data flow: It trims empty discoverable IDs, deduplicates disabled tools, and if layer data is available, collects disabled tools from each active layer from low to high precedence. It returns a clean ToolSuggestConfig.

Call relations: Both public tool-suggestion resolvers delegate here so config-load and reload behavior match.

Call graph: calls 1 internal fn (get_layers); called by 2 (resolve_tool_suggest_config, resolve_tool_suggest_config_from_layer_stack); 2 external calls (new, new).

fn thread_store_config(thread_store: Option<ThreadStoreToml>) -> ThreadStoreConfig

Purpose: Converts experimental thread-store TOML into the runtime enum. The thread store is where conversation threads are persisted.

Data flow: It receives an optional TOML setting and returns local storage, in-memory storage with an ID, or local storage by default.

Call relations: The main config loader calls this while filling the experimental thread-store field.

Call graph: called by 1 (load_config_with_layer_stack).

fn is_session_layer(source: &ConfigLayerSource) -> bool

Purpose: Identifies whether a config layer came from session flags.

Data flow: It receives a layer source and returns true if it is the session-flags source.

Call relations: Config rebuilding uses this to preserve session-specific layers while replacing refreshed user or project layers.

Call graph: 1 external calls (matches!).

fn has_profiles(&self) -> bool

Purpose: Reports whether the effective permission selection contains any named permission profiles.

Data flow: It reads the optional profile catalog and returns true only when it exists and is not empty.

Call relations: The main config loader uses this to reject a config that defines profiles but never selects one.

fn profiles_are_active(
        &self,
        default_permissions_override: Option<&str>,
        permission_config_syntax: Option<PermissionConfigSyntax>,
    ) -> bool

Purpose: Decides whether named permission profiles should be used instead of legacy sandbox settings.

Data flow: It checks managed requirements, command-line default-permission override, detected permission syntax, and absence of explicit legacy syntax. It returns true when profile mode is active.

Call relations: The main config loader calls this before compiling permissions, because profile and legacy modes are interpreted differently.

Call graph: 1 external calls (matches!).

fn resolve_permission_config_syntax(
    config_layer_stack: &ConfigLayerStack,
    cfg: &ConfigToml,
    sandbox_mode_override: Option<SandboxMode>,
) -> Option<PermissionConfigSyntax>

Purpose: Detects whether config is using old sandbox_mode syntax or newer named permission profiles.

Data flow: It checks overrides first, then session flags, then active layers in precedence order, and finally merged config fields. It returns legacy, profiles, or no explicit syntax.

Call relations: The main config loader uses this decision to choose the permission resolution path.

Call graph: calls 1 internal fn (get_layers); called by 1 (load_config_with_layer_stack).

fn apply_managed_filesystem_constraints(
    file_system_sandbox_policy: &mut FileSystemSandboxPolicy,
    filesystem_constraints: &codex_config::FilesystemConstraints,
)

Purpose: Adds managed file read-deny rules to a file-system sandbox policy.

Data flow: It receives a mutable sandbox policy and filesystem constraints. Each deny-read rule becomes either a glob-pattern deny entry or an absolute-path deny entry, and duplicate entries are skipped.

Call relations: The main config loader applies this after permission profiles are constrained, ensuring managed file restrictions are present in the final runtime policy.

Call graph: calls 1 internal fn (try_from); called by 1 (load_config_with_layer_stack).

fn dedupe_absolute_paths(paths: &mut Vec<AbsolutePathBuf>)

Purpose: Removes duplicate absolute paths while preserving the first occurrence.

Data flow: It receives a mutable vector of absolute paths, tracks paths already seen, and removes repeats in place.

Call relations: Workspace-root resolution uses this whenever roots are combined from current directory, overrides, and profile-defined roots.

Call graph: called by 2 (effective_workspace_roots, load_config_with_layer_stack); 1 external calls (new).

fn resolve_oss_provider(
    explicit_provider: Option<&str>,
    config_toml: &ConfigToml,
) -> Option<String>

Purpose: Chooses the open-source provider preference from an explicit override or global config.

Data flow: It receives an optional explicit provider and parsed config. It returns the explicit provider if present, otherwise the configured oss_provider, otherwise None.

Call relations: CLI startup and archive server setup call this when deciding which local provider option should apply.

Call graph: called by 3 (run_main, run_main, start_app_server_for_archive_command).

fn resolve_web_search_mode(config_toml: &ConfigToml, features: &Features) -> Option<WebSearchMode>

Purpose: Chooses the preferred web-search mode from config and feature flags.

Data flow: It first uses an explicit web_search config value. If absent, feature flags can select cached or live search. If nothing applies, it returns None.

Call relations: The main config loader calls this before applying managed web-search constraints.

Call graph: calls 1 internal fn (enabled); called by 1 (load_config_with_layer_stack).

fn resolve_web_search_config(config_toml: &ConfigToml) -> Option<WebSearchConfig>

Purpose: Extracts extra web-search tool parameters from config.

Data flow: It looks under the tools.web_search section, clones it if present, converts it to the runtime type, and returns it as optional config.

Call relations: The main config loader stores this alongside the constrained web-search mode.

Call graph: called by 1 (load_config_with_layer_stack).

fn resolve_experimental_request_user_input_enabled(config_toml: &ConfigToml) -> bool

Purpose: Determines whether the experimental request-user-input tool should be registered.

Data flow: It reads the optional tool config. If the setting is missing, it defaults to enabled; otherwise it returns the configured enabled flag.

Call relations: The main config loader calls this while preparing tool-surface settings.

Call graph: called by 1 (load_config_with_layer_stack).

fn resolve_code_mode_config(config_toml: &ConfigToml) -> CodeModeConfig

Purpose: Builds the runtime config for the experimental code-mode tool surface.

Data flow: It reads code-mode feature configuration, extracts excluded tool namespaces if present, and returns a CodeModeConfig with an empty list by default.

Call relations: The main config loader calls this after feature resolution.

Call graph: calls 1 internal fn (code_mode_toml_config); called by 1 (load_config_with_layer_stack).

fn resolve_multi_agent_v2_config(config_toml: &ConfigToml) -> MultiAgentV2Config

Purpose: Builds the runtime multi-agent v2 settings by combining defaults with optional feature config.

Data flow: It reads multi-agent v2 feature config, chooses a concurrency limit, creates matching defaults, applies configured timeout and prompt overrides, and returns a MultiAgentV2Config.

Call relations: The main config loader calls this before validating multi-agent limits and namespace names.

Call graph: calls 3 internal fn (defaults_for_max_concurrency, multi_agent_v2_toml_config, resolve_optional_prompt_text); called by 1 (load_config_with_layer_stack).

fn resolve_terminal_resize_reflow_config(config_toml: &ConfigToml) -> TerminalResizeReflowConfig

Purpose: Translates terminal resize reflow settings into runtime behavior. Reflow means recalculating displayed transcript rows after the terminal changes size.

Data flow: It reads TUI config. Missing settings mean automatic row limits, zero disables the cap, and positive values become an explicit row limit.

Call relations: The main config loader stores this for the terminal UI.

Call graph: called by 1 (load_config_with_layer_stack); 2 external calls (default, Limit).

fn resolve_optional_prompt_text(
    configured: Option<&Option<String>>,
    default: Option<String>,
) -> Option<String>

Purpose: Resolves optional prompt text where an empty string means disable the prompt.

Data flow: It receives an optional configured optional string and a default. A configured empty string returns None, a configured non-empty string returns that value, and missing config returns the default.

Call relations: Multi-agent v2 config resolution uses this for root-agent and sub-agent instruction prompts.

Call graph: called by 1 (resolve_multi_agent_v2_config).

fn code_mode_toml_config(features: Option<&FeaturesToml>) -> Option<&CodeModeConfigToml>

Purpose: Extracts code-mode feature configuration only when the feature uses a config object rather than a simple enabled flag.

Data flow: It receives optional feature TOML and returns the code-mode config reference if present in config form. Plain enabled form returns None.

Call relations: resolve_code_mode_config calls this to find optional detailed settings.

Call graph: called by 1 (resolve_code_mode_config).

fn multi_agent_v2_toml_config(features: Option<&FeaturesToml>) -> Option<&MultiAgentV2ConfigToml>

Purpose: Extracts multi-agent v2 feature configuration only when detailed config is present.

Data flow: It receives optional feature TOML and returns the multi-agent v2 config reference if present in config form. Plain enabled form returns None.

Call relations: resolve_multi_agent_v2_config calls this before applying detailed overrides.

Call graph: called by 1 (resolve_multi_agent_v2_config).

fn network_proxy_toml_config(features: Option<&FeaturesToml>) -> Option<&NetworkProxyConfigToml>

Purpose: Extracts network-proxy feature configuration only when detailed config is present.

Data flow: It receives optional feature TOML and returns the network-proxy config reference if present in config form. Plain enabled form returns None.

Call relations: The main config loader and active-profile network recalculation use this before applying proxy feature settings.

Call graph: called by 2 (load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile).

fn resolve_web_search_mode_for_turn(
    web_search_mode: &Constrained<WebSearchMode>,
    permission_profile: &PermissionProfile,
) -> WebSearchMode

Purpose: Chooses the actual web-search mode for one turn, taking both user preference and permission constraints into account.

Data flow: It receives a constrained web-search setting and a permission profile. If permissions are disabled, it prefers safer fallbacks. Otherwise it tries the preferred mode, then cached, live, and disabled, returning disabled if nothing is allowed.

Call relations: Turn-handling code can call this when deciding whether the web search tool should be live, cached, or unavailable for that turn.

Call graph: calls 2 internal fn (can_set, value); 1 external calls (matches!).

fn validate_multi_agent_v2_wait_timeout(label: &str, value: i64) -> std::io::Result<()>

Purpose: Checks that a multi-agent v2 wait timeout is inside hard allowed bounds.

Data flow: It receives a label and numeric timeout. Values below the hard minimum or above the hard maximum return invalid-input errors; valid values succeed.

Call relations: The main config loader calls this for minimum, maximum, and default wait timeouts before accepting multi-agent v2 config.

Call graph: called by 1 (load_config_with_layer_stack); 2 external calls (new, format!).

fn validate_multi_agent_v2_tool_namespace(namespace: Option<&str>) -> std::io::Result<()>

Purpose: Validates a custom tool namespace for multi-agent v2 tools. A namespace is the prefix used to group tool names.

Data flow: It receives an optional namespace. Missing is allowed; present values must be non-empty, trimmed, short enough, ASCII alphanumeric plus _ or -, and not reserved. It returns success or a clear error.

Call relations: The main config loader calls this before storing multi-agent v2 config.

Call graph: called by 1 (load_config_with_layer_stack); 2 external calls (new, format!).

async fn load_from_base_config_with_overrides(
        cfg: ConfigToml,
        overrides: ConfigOverrides,
        codex_home: AbsolutePathBuf,
    ) -> std::io::Result<Self>

Purpose: Test-only helper that builds a Config from a base TOML object and overrides. It skips managed requirements.

Data flow: It receives config TOML, overrides, and Codex home, creates a default layer stack, and delegates to the main config constructor.

Call relations: Test helpers call this to exercise config construction without going through real layer loading.

Call graph: 2 external calls (load_config_with_layer_stack, default).

async fn load_config_with_layer_stack(
        fs: &dyn ExecutorFileSystem,
        cfg: ConfigToml,
        overrides: ConfigOverrides,
        codex_home: AbsolutePathBuf,
        config_layer_stack

Purpose: This is the core config constructor. It turns parsed TOML, runtime overrides, Codex home, and a layer stack with requirements into the final Config used by Codex.

Data flow: It validates raw settings, resolves feature flags, permissions, project trust, workspace roots, model providers, MCP servers, auth storage, paths, prompts, UI settings, telemetry, and safety requirements. It returns a fully populated Config or a detailed error.

Call relations: Almost every public config-loading path eventually delegates here. It coordinates many helper functions in this file plus specialized modules for permissions, roles, features, network proxy, and telemetry.

Call graph: calls 47 internal fn (derive_permission_profile, get_active_project, validate_model_providers, requirements, requirements_toml, startup_warnings, default, load_agent_roles, apply_managed_filesystem_constraints, apply_requirement_constrained_value (+15 more)); 19 external calls (pin, default, try_read_non_empty_file, new, new, sandbox_mode_requirement_for_permission_profile, resolve_root_git_project_for_trust, memory_root, built_in_model_providers, merge_configured_model_providers (+9 more)).

async fn try_read_non_empty_file(
        fs: &dyn ExecutorFileSystem,
        path: Option<&AbsolutePathBuf>,
        context: &str,
    ) -> std::io::Result<Option<String>>

Purpose: Reads an optional prompt or instruction file and rejects empty files.

Data flow: It receives a filesystem interface, optional absolute path, and human-readable context. Missing path returns None; present path is read as text, trimmed, and returned if non-empty, otherwise an error is produced.

Call relations: The main config loader uses this for model instruction files and compact prompt files.

Call graph: calls 2 internal fn (read_file_text, from_abs_path); 2 external calls (new, format!).

fn set_windows_sandbox_enabled(&mut self, value: bool)

Purpose: Turns the unelevated Windows sandbox mode on or off without disturbing an elevated sandbox setting.

Data flow: It receives a boolean. True sets the Windows sandbox mode to unelevated; false clears it only if it was currently unelevated.

Call relations: Runtime controls can call this to toggle the normal Windows sandbox flag after config load.

Call graph: 1 external calls (matches!).

fn set_windows_elevated_sandbox_enabled(&mut self, value: bool)

Purpose: Turns the elevated Windows sandbox mode on or off without disturbing an unelevated sandbox setting.

Data flow: It receives a boolean. True sets the Windows sandbox mode to elevated; false clears it only if it was currently elevated.

Call relations: Runtime controls can call this to toggle elevated Windows sandbox behavior after config load.

Call graph: 1 external calls (matches!).

fn managed_network_requirements_enabled(&self) -> bool

Purpose: Reports whether managed network requirements are active for the current config.

Data flow: It checks that permissions are not fully disabled and that requirements TOML contains a network section. It returns true or false.

Call relations: Runtime or UI code can use this to explain why network behavior is being constrained.

Call graph: calls 1 internal fn (requirements_toml); 1 external calls (matches!).

fn network_proxy_spec_for_active_permission_profile(
        &self,
        active_permission_profile: &ActivePermissionProfile,
        permission_profile: &PermissionProfile,
    ) -> std::io::Resul

Purpose: Recomputes the network proxy spec for a newly selected active permission profile.

Data flow: It receives active-profile metadata and a permission profile, reloads effective config to find that profile's proxy settings when allowed, applies network-proxy feature config if enabled, then builds a final proxy spec with managed requirements.

Call relations: Permission-profile switching code uses this so network proxy behavior follows the selected profile without rebuilding the entire config.

Call graph: calls 8 internal fn (effective_config, requirements, build_network_proxy_spec, network_proxy_toml_config, apply_network_proxy_feature_config, network_proxy_config_for_profile_selection, profile_allows_configured_network_proxy, network_sandbox_policy); 2 external calls (enabled, default).

fn bundled_skills_enabled(&self) -> bool

Purpose: Reports whether bundled skills are enabled according to the config layer stack. Skills are packaged capabilities or instructions Codex can use.

Data flow: It passes the config layer stack to the manager helper and returns the boolean result.

Call relations: Skill-loading code can call this to decide whether bundled skills should be made available.

Call graph: calls 1 internal fn (bundled_skills_enabled_from_stack).

fn guardian_policy_config_from_requirements(
    requirements_toml: &ConfigRequirementsToml,
) -> Option<String>

Purpose: Extracts Guardian policy configuration from managed requirements. Guardian is the review/safety layer that can evaluate risky actions.

Data flow: It reads the requirements TOML policy text and normalizes it by trimming whitespace and dropping empty values.

Call relations: The main config loader calls this before falling back to local auto-review policy config.

Call graph: calls 1 internal fn (normalize_guardian_policy_config); called by 1 (load_config_with_layer_stack).

fn merge_managed_permission_profiles(
    configured_permissions: Option<&PermissionsToml>,
    requirements_toml: &ConfigRequirementsToml,
) -> std::io::Result<Option<PermissionsToml>>

Purpose: Combines user-defined permission profiles with profiles supplied by managed requirements.

Data flow: It receives optional configured profiles and requirements. Managed profiles are added unless they conflict with a user-defined profile of the same name; conflicts return an error.

Call relations: Effective permission selection calls this before validating and selecting a default profile.

Call graph: called by 1 (resolve_effective_permission_selection); 2 external calls (new, format!).

fn resolve_effective_permission_selection(
    configured_permissions: Option<&PermissionsToml>,
    default_permissions_override: Option<&'a str>,
    configured_default_permissions: Option<&'a str>,

Purpose: Builds the effective permission-profile catalog and selected profile ID.

Data flow: It merges managed profiles, validates user profile names, checks required profile references, resolves the selected default permission profile, and returns an EffectivePermissionSelection.

Call relations: The main config loader calls this before compiling permissions into concrete sandbox policies.

Call graph: calls 4 internal fn (merge_managed_permission_profiles, validate_user_permission_profile_names, resolve_default_permissions, validate_required_permission_profile_catalog); called by 1 (load_config_with_layer_stack).

fn resolve_default_permissions(
    default_permissions_override: Option<&'a str>,
    configured_default_permissions: Option<&'a str>,
    requirements_toml: &'a ConfigRequirementsToml,
    startup_w

Purpose: Chooses the selected permission profile while respecting managed allowlists.

Data flow: It starts from a command-line override or configured default. If requirements restrict allowed profiles, it uses the selected value only when allowed; otherwise it falls back to a required or implicit default and records a warning.

Call relations: Effective permission selection uses this after profile catalogs are merged and before profiles are compiled.

Call graph: calls 1 internal fn (is_permission_allowed); called by 1 (resolve_effective_permission_selection); 2 external calls (new, format!).

fn validate_required_permission_profile_catalog(
    requirements_toml: &ConfigRequirementsToml,
    available_permissions: Option<&PermissionsToml>,
) -> std::io::Result<()>

Purpose: Checks that managed permission-profile requirements refer to real and allowed profiles.

Data flow: It examines allowed profile names and default permissions from requirements. It verifies every allowed profile is built in or configured, ensures a default can be determined, and confirms the default is allowed.

Call relations: Effective permission selection calls this so bad managed requirements fail early with clear errors.

Call graph: calls 1 internal fn (is_permission_allowed); called by 1 (resolve_effective_permission_selection); 2 external calls (new, format!).

fn implicit_default_permissions(
    allowed_permission_profiles: &BTreeMap<String, bool>,
) -> Option<&'static str>

Purpose: Chooses an implicit managed default permission profile when requirements allow both built-in workspace and read-only profiles.

Data flow: It receives an allowlist map. If both :workspace and :read-only are allowed, it returns :workspace; otherwise it returns None.

Call relations: Default-permission resolution and requirement validation use this when requirements do not explicitly name a default.

Call graph: calls 1 internal fn (is_permission_allowed).

fn is_permission_allowed(
    allowed_permission_profiles: &BTreeMap<String, bool>,
    profile_id: &str,
) -> bool

Purpose: Checks whether a permission profile ID is allowed by a requirements allowlist.

Data flow: It receives the allowlist map and profile ID. It returns the stored boolean for that ID, or false if the ID is absent.

Call relations: Permission default resolution, implicit default selection, and requirement validation all use this small shared check.

Call graph: called by 3 (implicit_default_permissions, resolve_default_permissions, validate_required_permission_profile_catalog).

fn normalize_guardian_policy_config(value: Option<&str>) -> Option<String>

Purpose: Cleans optional Guardian policy text by trimming whitespace and dropping empty strings.

Data flow: It receives optional text. Non-empty trimmed text becomes a new string; missing or empty text becomes None.

Call relations: Managed and local Guardian policy config extraction both use this normalization.

Call graph: called by 1 (guardian_policy_config_from_requirements).

fn find_codex_home() -> std::io::Result<AbsolutePathBuf>

Purpose: Finds the Codex home directory, usually from CODEX_HOME or the default ~/.codex path.

Data flow: It delegates to the shared home-directory utility and returns an absolute path or an I/O error.

Call relations: Startup, CLI commands, profile loading, logging setup, and fallback config loading call this whenever they need the root config/state directory.

Call graph: called by 21 (from_listen_url, default_control_socket_path, run_main_with_transport_options, cli_main, disable_feature_in_config, fallback_state_check, enable_feature_in_config, loader_overrides_for_profile, run_add, run_remove (+11 more)); 1 external calls (find_codex_home).

fn log_dir(cfg: &Config) -> std::io::Result<PathBuf>

Purpose: Returns the configured log directory path.

Data flow: It receives a Config, clones its log_dir field, and returns it as an I/O result.

Call relations: Logging initialization calls this after config load to know where log files should be written.

Call graph: called by 1 (init_login_file_logging).

fn from_optional_paths(
        codex_self_exe: Option<PathBuf>,
        codex_linux_sandbox_exe: Option<PathBuf>,
    ) -> std::io::Result<Self>

Purpose: Builds the runtime path bundle when the Codex executable path may or may not have been configured yet. It requires the main Codex executable path and gives a clear error if it is missing.

Data flow: It receives two optional filesystem paths: one for the Codex executable and one for the Linux sandbox alias. It first checks that the Codex executable path is present; if not, it returns an input error saying the path is not configured. If it is present, it passes both paths on to ExecServerRuntimePaths::new, which checks that the supplied paths are absolute and returns the finished runtime path bundle.

Call relations: Higher-level startup and command-building code calls this when it is collecting settings before launching or preparing server work. This function acts as the gatekeeper for the required executable path, then hands off to ExecServerRuntimePaths::new for the actual path validation and struct creation.

Call graph: called by 8 (run_main_with_transport_options, list_accessible_connectors_from_mcp_tools_with_options_and_status, build_prompt_input, run_main, run_main, run_main, run_main, start_app_server_for_archive_command); 1 external calls (new).

fn new(
        codex_self_exe: PathBuf,
        codex_linux_sandbox_exe: Option<PathBuf>,
    ) -> std::io::Result<Self>

Purpose: Creates an ExecServerRuntimePaths value from concrete paths, while enforcing that every provided path is absolute. Use this when the caller already knows the main Codex executable path exists.

Data flow: It takes a required Codex executable path and an optional Linux sandbox alias path. It runs each supplied path through absolute_path; the optional sandbox path is checked only if it was provided. If all checks pass, it returns a struct containing the validated absolute paths. If any path is not absolute, it returns an input error instead of creating an unsafe or unreliable configuration.

Call relations: This is the central constructor used by tests, runtime setup code, exec-server command setup, and permission-related helper logic. It relies on absolute_path for the low-level check, then supplies the validated path bundle to the rest of the exec-server flow that needs to launch or reason about child processes.

Call graph: calls 1 internal fn (absolute_path); called by 27 (runtime_start_args_forward_environment_manager, run_exec_server_command, test_runtime_paths, build_with_home_and_base_url, test_runtime_paths, helper_permissions_include_helper_read_root_without_additional_permissions, helper_permissions_include_linux_sandbox_alias_parent, helper_permissions_preserve_existing_writes, sandbox_exec_request_carries_helper_env, processor_exit_reports_closed_virtual_stream (+15 more)).

fn absolute_path(path: PathBuf) -> std::io::Result<AbsolutePathBuf>

Purpose: Converts a normal filesystem path into an AbsolutePathBuf, or reports an error if the path is not absolute. This keeps the rest of the code from accidentally using paths that depend on the current directory.

Data flow: It receives a PathBuf, views it as a path, and asks AbsolutePathBuf::from_absolute_path to verify and wrap it. On success, it returns the absolute-path wrapper. On failure, it turns the validation problem into a standard input error that callers can return upward.

Call relations: ExecServerRuntimePaths::new calls this for each path it wants to store. This helper keeps the validation rule in one place, so the constructor can stay focused on building the runtime path bundle.

Call graph: calls 1 internal fn (from_absolute_path); called by 1 (new); 1 external calls (as_path).

fn request_user_input_available_modes(features: &Features) -> Vec<ModeKind>

Purpose: Builds the list of collaboration modes that may show a “request user input” option in the text user interface. It also allows the default mode to appear when a specific feature flag says that default mode should be able to request user input.

Data flow: It takes the active feature set as input. It reads the fixed list of collaboration modes visible in the interface, keeps only the modes that either already allow user input requests or qualify through the default-mode feature flag, and returns the filtered list.

Call relations: This is used when the interface or configuration layer needs to know which visible modes can support asking the user for more input. It depends on the shared mode definitions and the enabled feature flags, but it does not call other project-specific helper functions from this file.

fn shell_command_backend_for_features(features: &Features) -> ShellCommandBackendConfig

Purpose: Chooses which backend should run ordinary shell commands based on enabled features. It picks the zsh-fork backend only when both the shell tool and zsh-fork feature are enabled; otherwise it stays with the classic backend.

Data flow: It receives the feature set. It checks whether the shell tool feature is enabled and whether zsh-fork is also enabled. The output is a small enum value saying either “Classic” or “ZshFork.”

Call relations: This function is called by shell_type_for_model_and_features when that higher-level function needs to translate feature policy into the actual shell tool type. It is one smaller rule inside the larger shell-selection decision.

Call graph: calls 1 internal fn (enabled); called by 1 (shell_type_for_model_and_features).

fn unified_exec_feature_mode_for_features(features: &Features) -> UnifiedExecFeatureMode

Purpose: Decides whether feature policy allows unified exec, and if so whether it should be direct or zsh-fork based. Unified exec is a newer execution path, and this function makes sure it is not silently enabled unless the required feature flags explicitly allow it.

Data flow: It takes the active feature set. It first rejects unified exec if the shell tool itself is off or unified exec is off. If zsh-fork is enabled, it only returns the zsh-fork unified mode when the separate composition flag is also enabled. If zsh-fork is not enabled, it returns direct unified exec. The result is Disabled, Direct, or ZshFork.

Call relations: This function is called by shell_type_for_model_and_features before that function considers the model request and platform support. It supplies the policy-level answer: what unified-exec mode, if any, the configured features permit.

Call graph: calls 1 internal fn (enabled); called by 1 (shell_type_for_model_and_features).

fn shell_type_for_model_and_features(
    model_info: &ModelInfo,
    features: &Features,
) -> ConfigShellToolType

Purpose: Chooses the final shell tool type that should be exposed for a model under the current feature flags and platform support. It protects against unsupported or disabled paths by falling back to safer shell-command behavior or disabling the shell tool entirely.

Data flow: It receives model information and the active feature set. It first asks what unified-exec mode the features allow, then adjusts the model’s requested shell type if unified exec is disabled or if the model asked for a default/local shell. It also checks which classic shell-command backend is configured. Finally, if the shell tool feature is off it returns Disabled; if unified exec is allowed and the system supports the needed terminal feature, it returns UnifiedExec; otherwise it returns ShellCommand.

Call relations: This is the main shell-selection function in the file. It calls unified_exec_feature_mode_for_features for the high-level feature policy, shell_command_backend_for_features for the shell-command backend rule, and an external conpty_supported check to see whether the current platform can actually use unified exec.

Call graph: calls 3 internal fn (enabled, shell_command_backend_for_features, unified_exec_feature_mode_for_features); 2 external calls (conpty_supported, matches!).

fn for_session(
        feature_mode: UnifiedExecFeatureMode,
        user_shell_type: ToolUserShellType,
        shell_zsh_path: Option<&PathBuf>,
        main_execve_wrapper_exe: Option<&PathBuf>,

Purpose: Chooses how unified exec should run for one concrete session. It uses the policy-level mode plus real session details, such as the user’s shell and the paths to required executables, to decide whether zsh-fork can actually be used.

Data flow: It receives the requested unified-exec feature mode, the detected user shell type, and optional paths for zsh and the exec wrapper program. If the system is Unix, the feature mode asks for zsh-fork, the user shell is zsh, both paths are present, and both paths can be converted into absolute paths, it returns a ZshFork configuration containing those absolute paths. If any condition fails, it returns Direct. Invalid paths are logged as warnings before falling back.

Call relations: This function is used during session setup by callers such as spawn_review_thread and make_turn_context when they need a concrete execution mode for a running conversation or review. Tests also call it to confirm that zsh-fork is selected only when every required input matches.

Call graph: calls 1 internal fn (try_from); called by 3 (spawn_review_thread, make_turn_context, unified_exec_shell_mode_uses_zsh_fork_only_when_all_inputs_match); 3 external calls (ZshFork, cfg!, matches!).

fn from_count(count: usize) -> Self

Purpose: Turns a number of tool environments into a simple category: none, one, or many. This gives later code a clearer value to reason about than a raw number.

Data flow: It takes a count as input. A count of 0 becomes None, a count of 1 becomes Single, and any larger count becomes Multiple. It returns that category and does not change anything else.

Call relations: This is called by tool_environment_mode when some other part of the system has counted available environments and wants the standardized category used by this file’s configuration model.

Call graph: called by 1 (tool_environment_mode).

fn has_environment(self) -> bool

Purpose: Answers the yes-or-no question: does this tool environment mode include at least one environment? It is a convenience check for code that does not care whether there is one or many.

Data flow: It receives a ToolEnvironmentMode value. It checks whether that value is not None, then returns true for Single or Multiple and false for None.

Call relations: This helper is meant to be called wherever code needs a quick boolean check after a ToolEnvironmentMode has already been chosen. It does not call other project-specific functions, only a standard pattern-matching check.

Call graph: 1 external calls (matches!).

async fn validate_config_lock_if_configured(
    session_configuration: &SessionConfiguration,
) -> anyhow::Result<()>

Purpose: This function checks whether the current root session matches a previously supplied config lock. It is used to stop a replay from continuing if the effective settings have changed in a meaningful way.

Data flow: It receives a SessionConfiguration. If the session is a non-root agent, or there is no expected config lock attached to the original config, it does nothing and succeeds. Otherwise it converts the live session into a fresh lockfile, reads the version-mismatch policy from the original config, compares expected versus actual, and returns success or an error explaining that config lock replay validation failed.

Call relations: When replay validation is needed, this function asks SessionConfiguration::to_config_lockfile_toml to build the actual lock from the live session, then hands both locks to validate_config_lock_replay. It sits at the boundary between session setup and the lower-level lock comparison code.

Call graph: calls 1 internal fn (validate_config_lock_replay); 1 external calls (to_config_lockfile_toml).

async fn export_config_lock_if_configured(
    session_configuration: &SessionConfiguration,
    conversation_id: ThreadId,
) -> anyhow::Result<()>

Purpose: This function writes the session's config lock to a file when config-lock exporting has been enabled. It gives users or tooling a durable record of the exact resolved settings for a conversation.

Data flow: It receives a SessionConfiguration and a conversation ThreadId. It reads the export directory from the original config; if none is set, it exits successfully. If exporting is enabled, it builds the lockfile, converts it into pretty TOML text, creates the export directory if needed, and writes a file named after the conversation id.

Call relations: This function uses SessionConfiguration::to_config_lockfile_toml to create the lock, then relies on TOML serialization and async filesystem calls to create the directory and write the file. It is the outward-facing export path for the lock-building logic in this file.

Call graph: 5 external calls (to_config_lockfile_toml, format!, create_dir_all, write, to_string_pretty).

fn to_config_lockfile_toml(&self) -> anyhow::Result<ConfigLockfileToml>

Purpose: This method converts a live SessionConfiguration into the structured TOML object used for config lock files. It is the common entry point for both validation and export.

Data flow: It reads the SessionConfiguration, asks session_configuration_to_lock_config_toml to produce the cleaned resolved configuration, then wraps that configuration with config-lock metadata such as the lock format version. The result is a ConfigLockfileToml or an error if conversion fails.

Call relations: Both validate_config_lock_if_configured and export_config_lock_if_configured call this method before comparing or writing a lock. Internally, it delegates the detailed field selection to session_configuration_to_lock_config_toml, then hands the result to config_lockfile for final packaging.

Call graph: calls 2 internal fn (config_lockfile, session_configuration_to_lock_config_toml).

fn session_configuration_to_lock_config_toml(
    sc: &SessionConfiguration,
) -> anyhow::Result<ConfigToml>

Purpose: This function builds the actual configuration section that will go inside a config lock. It records the resolved behavior Codex ran with, while removing input-only details that should not affect replay comparison.

Data flow: It starts with the effective configuration produced by the original config's layer stack. If configured to do so, it copies session-resolved values such as model and prompts from the live SessionConfiguration. It always saves additional resolved Config fields, then drops profile, debug, file-include, sandbox, and permission inputs that are not meant to be locked. The output is a cleaned ConfigToml.

Call relations: SessionConfiguration::to_config_lockfile_toml calls this function as the main conversion step. This function coordinates three helpers: save_session_resolved_fields for values known only after session setup, save_config_resolved_fields for normalized config values, and drop_lockfile_inputs for removing non-replayable inputs.

Call graph: calls 3 internal fn (drop_lockfile_inputs, save_config_resolved_fields, save_session_resolved_fields); called by 1 (to_config_lockfile_toml).

fn save_session_resolved_fields(sc: &SessionConfiguration, lock_config: &mut ConfigToml)

Purpose: This function copies session-time choices into the lock when the lock should be fully self-contained. These are values that may not appear directly in the original TOML files but still affect how the session behaves.

Data flow: It receives the live SessionConfiguration and a mutable ConfigToml being built for the lock. It writes in the selected model, reasoning settings, service tier, base and developer instructions, compact prompt, personality, approval policy, and approval reviewer. It changes the ConfigToml in place and returns nothing.

Call relations: session_configuration_to_lock_config_toml calls this only when the config says to save fields resolved from the model catalog. It supplies the session-specific parts of the lock before save_config_resolved_fields adds broader resolved config values.

Call graph: called by 1 (session_configuration_to_lock_config_toml).

fn save_config_resolved_fields(
    config: &Config,
    lock_config: &mut ConfigToml,
) -> anyhow::Result<()>

Purpose: This function records resolved settings that live on Config after defaults, normalization, feature expansion, and other higher-level setup. Its goal is to lock what Codex actually used, not just what a user typed.

Data flow: It receives the resolved Config and a mutable ConfigToml. It writes values such as web search mode, model provider, reasoning effort, verbosity, instruction-inclusion flags, environment context, terminal timeout, feature states, multi-agent settings, memories, agent limits, and skill instruction settings. Some complex values are converted back into their TOML form through resolved_config_to_toml. The ConfigToml is updated in place, and errors are returned if conversion fails.

Call relations: session_configuration_to_lock_config_toml calls this after optionally saving session-resolved fields. This function uses resolved_config_to_toml for complex nested config objects and makes sure feature aliases become explicit feature states so replay comparison is stable.

Call graph: calls 1 internal fn (resolved_config_to_toml); called by 1 (session_configuration_to_lock_config_toml); 1 external calls (Config).

fn drop_lockfile_inputs(lock_config: &mut ConfigToml)

Purpose: This function removes settings that are inputs to configuration resolution rather than final replayable results. It keeps the lock focused on behavior, not on the path taken to produce that behavior.

Data flow: It receives a mutable ConfigToml. It clears profile data, debug config-lock controls, instruction file paths, model catalog input paths, sandbox and permission inputs, and a legacy experimental tool flag. The same ConfigToml comes out changed in place.

Call relations: session_configuration_to_lock_config_toml calls this as the final cleanup step before returning the lock configuration. It also calls clear_config_lock_debug_controls so debug-only controls do not become part of the replay contract.

Call graph: calls 1 internal fn (clear_config_lock_debug_controls); called by 1 (session_configuration_to_lock_config_toml).

fn resolved_config_to_toml(
    value: &impl serde::Serialize,
    label: &'static str,
) -> anyhow::Result<Toml>

Purpose: This helper converts an already-resolved Rust config value back into the matching TOML-shaped type. It is used when the lock needs to store complex nested settings in the same shape a config file would use.

Data flow: It receives a serializable value and a label used for error messages. It performs a TOML round trip, meaning it serializes the value and deserializes it into the requested TOML type. It returns the TOML-shaped value or an error if the conversion fails.

Call relations: save_config_resolved_fields calls this for nested settings such as multi-agent configuration and memories. The helper delegates the actual conversion to toml_round_trip and wraps any failure as an anyhow error for the caller.

Call graph: calls 1 internal fn (toml_round_trip); called by 1 (save_config_resolved_fields).

async fn lock_contains_prompts_and_materializes_features()

Purpose: This test checks that a generated config lock includes important resolved prompt and model values, and that feature settings are written explicitly. It protects against locks that look valid but omit behavior-changing details.

Data flow: It creates a test session configuration, changes the resolved base instructions, developer instructions, and compact prompt, then builds a lockfile. It inspects the lock and asserts that prompts, model fields, cleaned profile/debug inputs, memories, all feature states, and the lockfile version are present or absent as expected.

Call relations: The test calls make_session_configuration_for_tests to get a realistic session and then exercises SessionConfiguration::to_config_lockfile_toml through the public method. Its assertions cover work done by save_session_resolved_fields, save_config_resolved_fields, and drop_lockfile_inputs.

Call graph: calls 1 internal fn (make_session_configuration_for_tests); 2 external calls (assert!, assert_eq!).

async fn lock_skips_session_values_when_model_catalog_fields_are_not_saved()

Purpose: This test verifies that model-catalog-derived session values are not written into the lock when that option is disabled. It confirms the export behavior can be intentionally less self-contained.

Data flow: It creates a test session configuration, clones and modifies its original config so config_lock_save_fields_resolved_from_model_catalog is false, then fills in session-only values such as prompts and service tier. After building the lockfile, it checks that those session-derived fields remain absent.

Call relations: The test reaches the conversion path through SessionConfiguration::to_config_lockfile_toml. It specifically checks the branch in session_configuration_to_lock_config_toml that decides whether save_session_resolved_fields should run.

Call graph: calls 1 internal fn (make_session_configuration_for_tests); 2 external calls (new, assert_eq!).

async fn lock_validation_reports_config_diff()

Purpose: This test checks that validation reports a useful error when the replayed configuration differs from the expected lock. It ensures real drift is not silently accepted.

Data flow: It creates a test session, builds an expected lock, clones it into an actual lock, then changes the actual model field. It calls validate_config_lock_replay and expects an error whose message mentions that the effective config does not match and points to the model field.

Call relations: Rather than going through validate_config_lock_if_configured, this test calls validate_config_lock_replay directly to focus on comparison behavior. It uses a lock produced by SessionConfiguration::to_config_lockfile_toml as the realistic baseline.

Call graph: calls 2 internal fn (validate_config_lock_replay, make_session_configuration_for_tests); 2 external calls (assert!, default).

async fn lock_validation_ignores_removed_apps_mcp_path_override()

Purpose: This test confirms that validation tolerates an old or removed compatibility input called apps_mcp_path_override. It prevents older lockfiles from failing just because that input is no longer part of the current lock output.

Data flow: It creates a test lock, turns it into a TOML value, manually inserts the removed apps_mcp_path_override feature entry into the expected lock, converts that value back into a ConfigLockfileToml, and compares it with the current actual lock. The expected result is successful validation.

Call relations: The test uses SessionConfiguration::to_config_lockfile_toml to create the current lock and validate_config_lock_replay to check compatibility behavior. It exercises the comparison layer's ability to ignore a known removed input.

Call graph: calls 2 internal fn (validate_config_lock_replay, make_session_configuration_for_tests); 6 external calls (default, from_iter, Boolean, String, Table, try_from).

async fn lock_validation_rejects_codex_version_mismatch_by_default()

Purpose: This test checks that config-lock validation normally rejects a lock made by a different Codex version. That protects users from assuming a replay is identical when the program version itself may have changed behavior.

Data flow: It creates a test session, builds an expected lock, changes its codex_version to an older value, then builds a fresh actual lock. It calls validate_config_lock_replay with default options and expects an error that mentions the version mismatch and the debug option for allowing it.

Call relations: The test calls validate_config_lock_replay directly with default replay options. It uses SessionConfiguration::to_config_lockfile_toml to create both sides of the comparison before deliberately changing the expected version.

Call graph: calls 2 internal fn (validate_config_lock_replay, make_session_configuration_for_tests); 2 external calls (assert!, default).

async fn lock_validation_can_ignore_codex_version_mismatch()

Purpose: This test verifies the opt-in escape hatch for Codex version mismatches. It shows that version drift can be allowed when the caller explicitly chooses that policy.

Data flow: It creates a test session, builds an expected lock, changes its codex_version, and builds a fresh actual lock. It then calls validate_config_lock_replay with allow_codex_version_mismatch set to true, and expects validation to succeed.

Call relations: The test focuses on validate_config_lock_replay's option handling. It uses SessionConfiguration::to_config_lockfile_toml for realistic lock data, then confirms that the replay option overrides the default version check.

Call graph: calls 2 internal fn (validate_config_lock_replay, make_session_configuration_for_tests).

fn new_debug_config_output(
    config: &Config,
    session_network_proxy: Option<&SessionNetworkProxyRuntime>,
) -> PlainHistoryCell

Purpose: Builds the complete history cell shown for /debug-config in the terminal UI. It combines configuration-layer information with optional session network proxy details.

Data flow: It receives the current Config and, if present, the session network proxy runtime. It asks the renderer to produce the main debug lines, appends proxy environment variable lines when a proxy exists, then wraps everything in a PlainHistoryCell for display.

Call relations: This is the public entry point for this file’s production behavior. add_debug_config_output calls it when the user asks for debug configuration output; it then delegates most formatting to render_debug_config_lines and uses session_all_proxy_url for the proxy line.

Call graph: calls 3 internal fn (render_debug_config_lines, session_all_proxy_url, new); called by 1 (add_debug_config_output); 1 external calls (format!).

fn sandbox_mode_is_allowed_by_permissions(
    permissions: &Permissions,
    mode: SandboxModeRequirement,
) -> bool

Purpose: Checks whether a sandbox mode is actually allowed under the current permission rules. This prevents the debug output from claiming that a mode is available when another permission restriction blocks it.

Data flow: It receives the current permissions and one sandbox-mode requirement. It converts that mode into the matching permission profile, asks the permissions object whether that profile can be set, and returns true only if the check succeeds.

Call relations: It is used as the filtering rule passed into render_debug_config_lines from new_debug_config_output. The tests also call it to prove that blocked sandbox modes are hidden from the rendered output.

Call graph: calls 3 internal fn (can_set_permission_profile, read_only, workspace_write).

fn session_all_proxy_url(http_addr: &str, socks_addr: &str, socks_enabled: bool) -> String

Purpose: Chooses the correct URL for the ALL_PROXY environment variable. It uses SOCKS when SOCKS proxying is enabled, otherwise it falls back to HTTP.

Data flow: It receives an HTTP address, a SOCKS address, and a yes/no flag. If the flag is true it returns a socks5h://... URL; otherwise it returns an http://... URL.

Call relations: It is called by new_debug_config_output while adding session proxy details. Two focused tests check both branches so the displayed proxy instructions stay reliable.

Call graph: called by 1 (new_debug_config_output); 1 external calls (format!).

fn render_debug_config_lines(
    stack: &ConfigLayerStack,
    sandbox_mode_is_effectively_allowed: impl Fn(SandboxModeRequirement) -> bool,
) -> Vec<Line<'static>>

Purpose: Creates the main list of terminal lines for the /debug-config display. It shows configuration layers first, then the requirements that restrict allowed settings.

Data flow: It receives a configuration layer stack and a function that says whether each sandbox mode is effectively allowed. It reads the stack layers, requirement values, and requirement sources, formats each visible item into human-readable terminal lines, and returns the full list.

Call relations: This is the central formatter. new_debug_config_output calls it for real UI output, while test helpers call it to compare rendered text. It calls many smaller helpers so each kind of value, such as hooks, residency, web search, or network rules, is formatted consistently.

Call graph: calls 10 internal fn (get_layers, requirements, requirements_toml, format_managed_hooks_requirements, format_network_constraints, format_residency_requirement, join_or_empty, normalize_allowed_web_search_modes, render_non_file_layer_details, requirement_line); called by 2 (new_debug_config_output, render_stack_to_text_with_sandbox_mode_filter); 4 external calls (new, format_config_layer_source, format!, vec!).

fn render_non_file_layer_details(layer: &ConfigLayerEntry) -> Vec<Line<'static>>

Purpose: Adds extra detail for configuration layers that do not come from normal config files. This matters because session flags and managed policies would otherwise appear only as names, not as useful values.

Data flow: It receives one configuration layer. If the layer is session flags, it flattens and prints those flags. If it is enterprise or MDM managed configuration, it prints the raw managed value. For ordinary file-backed layers, it returns no extra lines.

Call relations: It is called while render_debug_config_lines is listing the stack. It hands session-flag layers to render_session_flag_details and managed layers to render_non_file_layer_value.

Call graph: calls 2 internal fn (render_non_file_layer_value, render_session_flag_details); called by 1 (render_debug_config_lines); 1 external calls (new).

fn render_session_flag_details(config: &TomlValue) -> Vec<Line<'static>>

Purpose: Turns session flag TOML into simple key-value lines. Session flags are temporary settings for the current run, so showing them plainly helps explain why this session behaves differently.

Data flow: It receives a TOML value, flattens nested tables into dotted keys, and returns one display line per key-value pair. If there are no flags, it returns a dimmed <none> line.

Call relations: It is called by render_non_file_layer_details for the SessionFlags layer. It relies on flatten_toml_key_values to walk through nested TOML data.

Call graph: calls 1 internal fn (flatten_toml_key_values); called by 1 (render_non_file_layer_details); 2 external calls (new, vec!).

fn format_managed_hooks_requirements(hooks: &ManagedHooksRequirementsToml) -> String

Purpose: Summarizes managed hook requirements in one compact string. Hooks are configured commands that can run around tool use, so the debug output shows where managed hooks live and how many handlers are required.

Data flow: It receives managed hook requirements. It collects the managed directory paths when present, counts hook handlers, joins those parts with commas, and returns the summary string.

Call relations: It is called by render_debug_config_lines when the requirements include hooks. It uses join_or_empty so even an empty summary has a clear printed value.

Call graph: calls 1 internal fn (join_or_empty); called by 1 (render_debug_config_lines); 2 external calls (new, format!).

fn render_non_file_layer_value(layer: &ConfigLayerEntry) -> Vec<Line<'static>>

Purpose: Formats the value of an enterprise-managed or MDM-managed configuration layer. This lets people see the actual managed configuration text that influenced the app.

Data flow: It receives a configuration layer, chooses a label for the source, then prefers the layer’s raw TOML text if available. It returns either a single line, an <empty> line, or several indented lines for multi-line TOML.

Call relations: It is called by render_non_file_layer_details for managed non-file layers. It uses non_file_layer_value_label to choose wording that matches the source type.

Call graph: calls 2 internal fn (raw_toml, non_file_layer_value_label); called by 1 (render_non_file_layer_details); 1 external calls (vec!).

fn non_file_layer_value_label(source: &ConfigLayerSource) -> &'static str

Purpose: Chooses the human-readable label for a non-file configuration value. For example, it distinguishes MDM values from enterprise-managed cloud values.

Data flow: It receives a configuration layer source and returns a fixed label string such as MDM value or Enterprise-managed config value.

Call relations: It is called by render_non_file_layer_value right before the managed value is printed.

Call graph: called by 1 (render_non_file_layer_value).

fn flatten_toml_key_values(
    value: &TomlValue,
    prefix: Option<&str>,
    out: &mut Vec<(String, String)>,
)

Purpose: Walks through nested TOML data and turns it into flat dotted key-value pairs. This makes deeply nested session flags easier to read in a terminal list.

Data flow: It receives a TOML value, an optional current key prefix, and an output list to fill. Tables are visited in sorted key order; non-table values are formatted and pushed into the output list.

Call relations: It is called by render_session_flag_details. It calls format_toml_value when it reaches an actual value instead of another table.

Call graph: calls 1 internal fn (format_toml_value); called by 1 (render_session_flag_details); 1 external calls (format!).

fn format_toml_value(value: &TomlValue) -> String

Purpose: Converts a TOML value into the text form shown in debug output. It keeps the display consistent with TOML’s own formatting rules.

Data flow: It receives a TOML value and returns that value’s string representation.

Call relations: It is called while flattening session flags and when rendering managed layer values without raw TOML text.

Call graph: called by 1 (flatten_toml_key_values); 1 external calls (to_string).

fn requirement_line(
    name: &str,
    value: String,
    source: Option<&RequirementSource>,
) -> Line<'static>

Purpose: Builds one standard line for a requirement. It keeps requirement output consistent by always showing the name, value, and source.

Data flow: It receives a requirement name, its already-formatted value, and an optional source. It uses the source text when available or <unspecified> otherwise, then returns a terminal line.

Call relations: It is called many times by render_debug_config_lines, once for each requirement that should be displayed.

Call graph: called by 1 (render_debug_config_lines); 1 external calls (format!).

fn join_or_empty(values: Vec<String>) -> String

Purpose: Joins a list of strings for display, while making empty lists explicit. This avoids confusing blank output when a requirement intentionally allows nothing.

Data flow: It receives a list of strings. If the list is empty it returns <empty>; otherwise it returns the strings separated by commas.

Call relations: It is used by the main debug renderer and by helper formatters such as managed hooks and network constraints.

Call graph: called by 3 (format_managed_hooks_requirements, format_network_constraints, render_debug_config_lines).

fn normalize_allowed_web_search_modes(
    modes: &[WebSearchModeRequirement],
) -> Vec<WebSearchModeRequirement>

Purpose: Normalizes the allowed web search modes before printing them. It makes sure disabled web search is represented correctly in the displayed requirement.

Data flow: It receives a slice of web search mode requirements. If the slice is empty, it returns a list containing only Disabled; otherwise it copies the modes and adds Disabled if it was missing.

Call relations: It is called by render_debug_config_lines before web search requirements are converted to text. A test covers the empty-list case.

Call graph: called by 1 (render_debug_config_lines); 3 external calls (is_empty, to_vec, vec!).

fn format_sandbox_mode_requirement(mode: SandboxModeRequirement) -> String

Purpose: Turns an internal sandbox-mode requirement into the short string users see. The sandbox is the safety boundary that limits what the app can do.

Data flow: It receives one sandbox mode and returns names such as read-only, workspace-write, danger-full-access, or external-sandbox.

Call relations: It is used by render_debug_config_lines while printing allowed sandbox modes.

fn format_residency_requirement(requirement: ResidencyRequirement) -> String

Purpose: Turns a data residency requirement into display text. Residency requirements say where data is allowed to be processed or stored.

Data flow: It receives one residency requirement and returns its short printed form, currently us for the United States requirement.

Call relations: It is called by render_debug_config_lines when an enforce_residency requirement is present.

Call graph: called by 1 (render_debug_config_lines).

fn format_network_constraints(network: &NetworkConstraints) -> String

Purpose: Summarizes network restrictions in one readable string. These restrictions explain what network behavior is allowed, such as ports, domains, Unix sockets, and proxy rules.

Data flow: It receives network constraints. For each field that is present, it adds a name=value part, formats domain and Unix socket permission maps, then joins all parts or returns <empty>.

Call relations: It is called by render_debug_config_lines when network requirements exist. It uses shared joining behavior and specialized permission formatting helpers for nested allow/deny maps.

Call graph: calls 1 internal fn (join_or_empty); called by 1 (render_debug_config_lines); 2 external calls (new, format!).

fn format_network_permission_entries(
    entries: &std::collections::BTreeMap<String, T>,
    format_value: impl Fn(T) -> &'static str,
) -> String

Purpose: Formats a map of network permission entries as {key=value, ...}. It is a small reusable helper for domain and Unix socket allow/deny lists.

Data flow: It receives a sorted map from names to permission values plus a function that converts each permission into text. It builds one key=permission part per entry and returns them inside braces.

Call relations: It supports network-constraint formatting, where both domain permissions and Unix socket permissions need the same map-shaped display.

Call graph: 1 external calls (format!).

fn format_network_domain_permission(permission: NetworkDomainPermissionToml) -> &'static str

Purpose: Converts a domain network permission into allow or deny. This is used for rules about hostnames such as example.com.

Data flow: It receives a domain permission enum and returns the matching static text.

Call relations: It is used as the value formatter when domain permission entries are displayed inside network constraints.

fn format_network_unix_socket_permission(
    permission: NetworkUnixSocketPermissionToml,
) -> &'static str

Purpose: Converts a Unix socket network permission into allow or deny. A Unix socket is a local file-like endpoint that programs can use to communicate on Unix-style systems.

Data flow: It receives a Unix socket permission enum and returns the matching static text.

Call relations: It is used as the value formatter when Unix socket permission entries are displayed inside network constraints.

fn empty_toml_table() -> TomlValue

Purpose: Creates an empty TOML table for tests. This keeps test setup short when a configuration layer needs a valid but blank TOML value.

Data flow: It takes no input, creates a new empty TOML table, and returns it as a TOML value.

Call relations: Several tests call it while constructing sample configuration layers for the debug renderer.

Call graph: 2 external calls (Table, new).

fn absolute_path(path: &str) -> AbsolutePathBuf

Purpose: Builds an absolute path object from a string during tests. This helps tests create realistic config-file paths on different operating systems.

Data flow: It receives a path string, validates it as absolute, and returns the project’s absolute-path type. If the path is not absolute, the test fails immediately.

Call relations: Tests call it when they need system, user, project, or managed-configuration paths.

Call graph: calls 1 internal fn (from_absolute_path).

fn render_to_text(lines: &[Line<'static>]) -> String

Purpose: Converts styled terminal lines into plain text for assertions. Tests do not care about colors or bold text, only the visible words.

Data flow: It receives rendered Line values, pulls out each span’s text content, joins spans into lines, then joins lines with newline characters.

Call relations: It is used by tests::render_stack_to_text_with_sandbox_mode_filter after the production renderer creates styled lines.

Call graph: 1 external calls (iter).

fn render_stack_to_text(stack: &ConfigLayerStack) -> String

Purpose: Renders a configuration stack to plain text for tests using a sandbox filter that allows every mode. It is the common shortcut for most renderer tests.

Data flow: It receives a configuration stack, passes it to the more flexible test helper with an always-true sandbox filter, and returns the plain text output.

Call relations: Many tests call this helper when they do not need to simulate sandbox modes being blocked.

Call graph: 1 external calls (render_stack_to_text_with_sandbox_mode_filter).

fn render_stack_to_text_with_sandbox_mode_filter(
        stack: &ConfigLayerStack,
        sandbox_mode_is_effectively_allowed: impl Fn(SandboxModeRequirement) -> bool,
    ) -> String

Purpose: Renders a configuration stack to plain text while letting a test control which sandbox modes are considered allowed. This makes it possible to test filtering behavior.

Data flow: It receives a stack and a sandbox-mode filter function. It calls the production render_debug_config_lines, then converts the styled lines to plain text.

Call relations: It is called by tests::render_stack_to_text and by the test that checks sandbox modes blocked by filesystem restrictions.

Call graph: calls 1 internal fn (render_debug_config_lines); 1 external calls (render_to_text).

fn debug_config_output_lists_all_layers_including_disabled()

Purpose: Checks that the debug output shows every configuration layer, including disabled ones. It also verifies that disabled layers show their reason.

Data flow: It builds a stack with one enabled system layer and one disabled project layer, renders it, and asserts that enabled, disabled, reason, and empty requirements text appear.

Call relations: This test exercises the layer-listing branch of render_debug_config_lines through the test render helper.

Call graph: calls 1 internal fn (new); 7 external calls (default, assert!, cfg!, default, absolute_path, render_stack_to_text, vec!).

fn debug_config_output_lists_requirement_sources()

Purpose: Checks that many different requirement types are printed with the correct source. This protects the main diagnostic value of /debug-config: explaining where restrictions came from.

Data flow: It builds a rich set of requirements, including approvals, sandbox modes, web search, managed features, network rules, filesystem read denial, and residency. It renders the stack and asserts that the expected text and sources appear.

Call relations: This broad test drives render_debug_config_lines through most requirement-formatting paths and indirectly covers many helper formatters.

Call graph: calls 5 internal fn (new, new, allow_any, new, read_only); 9 external calls (from, default, default, assert!, cfg!, assert_snapshot!, absolute_path, render_stack_to_text, vec!).

fn debug_config_output_filters_sandbox_modes_blocked_by_deny_read_requirements()

Purpose: Checks that sandbox modes blocked by effective permissions are not shown as available. This prevents misleading debug output when extra filesystem restrictions narrow what is really allowed.

Data flow: It creates requirements that list several sandbox modes, then creates permissions that allow only some of them. It renders with a filter based on sandbox_mode_is_allowed_by_permissions and asserts that blocked modes are absent.

Call relations: This test connects the permission-check helper with render_debug_config_lines, matching the same pattern used by new_debug_config_output.

Call graph: calls 7 internal fn (new, new, allow_any, new, new, from_approval_and_profile, read_only); 9 external calls (new, default, assert!, cfg!, default, assert_snapshot!, absolute_path, render_stack_to_text_with_sandbox_mode_filter, vec!).

fn debug_config_output_lists_approvals_reviewer_as_requirement()

Purpose: Checks that approvals reviewer requirements appear in the debug output. An approvals reviewer decides who or what reviews approval requests.

Data flow: It builds requirements containing an auto-reviewer setting, renders the stack, and asserts that the reviewer line appears and the requirements section is not empty.

Call relations: This test targets the approvals-reviewer branch inside render_debug_config_lines.

Call graph: calls 3 internal fn (new, allow_any, new); 6 external calls (new, default, assert!, default, render_stack_to_text, vec!).

fn debug_config_output_formats_unix_socket_permissions()

Purpose: Checks that Unix socket network permissions are printed clearly as allow and deny entries. This matters because socket rules are easy to miss if they are not displayed explicitly.

Data flow: It builds network constraints with one allowed and one denied socket path, renders the stack, and asserts that both entries appear in the expected order and format.

Call relations: This test exercises the network formatting path, including Unix socket permission formatting.

Call graph: calls 2 internal fn (new, new); 7 external calls (from, default, new, default, assert!, default, render_stack_to_text).

fn debug_config_output_lists_session_flag_key_value_pairs()

Purpose: Checks that session flags are shown as flattened key-value pairs. This confirms that nested temporary settings are visible in the debug output.

Data flow: It parses sample TOML session flags with both top-level and nested values, renders the stack, and asserts that dotted keys and values appear.

Call relations: This test covers render_non_file_layer_details, render_session_flag_details, and flatten_toml_key_values through the main stack renderer.

Call graph: calls 1 internal fn (new); 5 external calls (default, assert!, default, render_stack_to_text, vec!).

fn debug_config_output_shows_legacy_mdm_layer_value()

Purpose: Checks that legacy MDM-managed configuration is shown with its raw TOML content. MDM means mobile device management, a common way for organizations to enforce settings.

Data flow: It builds a managed layer with raw TOML text, renders the stack, and asserts that the MDM label and original TOML lines appear.

Call relations: This test exercises the managed non-file layer rendering path through render_non_file_layer_value.

Call graph: calls 1 internal fn (new); 7 external calls (default, assert!, cfg!, default, absolute_path, render_stack_to_text, vec!).

fn debug_config_output_shows_enterprise_managed_layer_value()

Purpose: Checks that cloud or enterprise-managed configuration is labeled separately from MDM configuration. This helps users identify which management system supplied a policy.

Data flow: It builds an enterprise-managed layer with raw TOML text, renders the stack, and asserts that the enterprise label appears, the MDM label does not, and the raw TOML is preserved.

Call relations: This test covers label selection in non_file_layer_value_label and multi-line managed value rendering.

Call graph: calls 1 internal fn (new); 7 external calls (default, assert!, cfg!, default, absolute_path, render_stack_to_text, vec!).

fn debug_config_output_normalizes_empty_web_search_mode_list()

Purpose: Checks that an empty allowed web search list is displayed as disabled. This makes an intentionally empty allowance readable instead of looking like missing output.

Data flow: It builds requirements with an empty web search mode list, renders the stack, and asserts that the output says disabled with the correct source.

Call relations: This test directly protects the behavior in normalize_allowed_web_search_modes as used by render_debug_config_lines.

Call graph: calls 3 internal fn (new, allow_any, new); 4 external calls (new, default, assert!, render_stack_to_text).

fn debug_config_output_lists_managed_hooks_requirement()

Purpose: Checks that managed hook requirements are summarized in the output. It especially verifies that hook handler counts are visible.

Data flow: It builds managed hook requirements with directories and one command handler, renders the stack, and asserts that hook text, handler count, and source appear.

Call relations: This test exercises format_managed_hooks_requirements through the main renderer.

Call graph: calls 3 internal fn (new, allow_any, new); 9 external calls (default, new, default, assert!, cfg!, default, from, render_stack_to_text, vec!).

fn session_all_proxy_url_uses_socks_when_enabled()

Purpose: Checks that SOCKS proxying wins when SOCKS support is enabled. This protects the proxy environment variable shown to users.

Data flow: It passes HTTP and SOCKS addresses with the SOCKS flag set to true, then asserts that the returned URL uses the socks5h:// scheme and SOCKS address.

Call relations: This is a focused test for the true branch of session_all_proxy_url.

Call graph: 1 external calls (assert_eq!).

fn session_all_proxy_url_uses_http_when_socks_disabled()

Purpose: Checks that HTTP proxying is used when SOCKS support is disabled. This protects the fallback proxy behavior shown in /debug-config.

Data flow: It passes HTTP and SOCKS addresses with the SOCKS flag set to false, then asserts that the returned URL uses the http:// scheme and HTTP address.

Call relations: This is a focused test for the false branch of session_all_proxy_url.

Call graph: 1 external calls (assert_eq!).

fn is_empty(&self) -> bool

Purpose: Checks whether the permissions file contains any named profiles. This is useful when code needs to know if there is anything to apply at all.

Data flow: It reads the profile map inside PermissionsToml and asks whether that map has no entries. It returns true for an empty configuration and false when at least one profile is present.

Call relations: This is a small query helper for code that has already parsed permissions. It does not call into other project logic; it simply reports whether the top-level profile collection has content.

fn resolve_profile(
        &self,
        profile_name: &str,
        mut parent_profile: F,
    ) -> Result<PermissionProfileToml, PermissionProfileResolutionError>

Purpose: Builds one complete permission profile from a named profile and all the profiles it extends. It also catches common configuration mistakes, such as missing parents or inheritance loops.

Data flow: It receives the profile name to load and a lookup function for parent profiles that may live outside this PermissionsToml. It walks from the selected profile to its parent, then that parent’s parent, collecting each one. If it finds a cycle, missing profile, or unsupported built-in parent, it returns a clear error. Otherwise it merges parents first and children after, returning the final combined profile.

Call relations: The broader config resolver calls this through resolve_permission_profile when it needs the usable version of a named profile. During the walk it may ask the supplied parent lookup for profiles not found locally, and at the end it hands each parent-child pair to merge_permission_profiles to combine them in the right order.

Call graph: called by 1 (resolve_permission_profile); 2 external calls (new, once).

fn merge_permission_profiles(
    mut parent: PermissionProfileToml,
    mut child: PermissionProfileToml,
) -> Result<PermissionProfileToml, PermissionProfileResolutionError>

Purpose: Combines a parent permission profile with a child permission profile so the child can override or add to the parent’s settings. It preserves the selected child profile’s declaration metadata instead of letting inherited descriptions leak in.

Data flow: It receives two profile objects. Before merging, it clears the parent’s description and extends fields because those belong to the chosen profile, not the inherited one. If both profiles define network domains, it normalizes their host names so equivalent names merge correctly. It then converts both profiles into generic TOML values, overlays the child onto the parent, and converts the result back into a typed profile. Serialization or deserialization failures become profile resolution errors.

Call relations: This is the merging step used by PermissionsToml::resolve_profile after the inheritance chain is known. It relies on normalize_profile_network_domains for host-name cleanup and on merge_toml_values for the actual TOML overlay behavior.

Call graph: calls 2 internal fn (merge_toml_values, normalize_profile_network_domains); 1 external calls (try_from).

fn normalize_profile_network_domains(profile: &mut PermissionProfileToml)

Purpose: Cleans up the domain names inside a profile’s network permissions before profiles are merged. This prevents the same host written in different forms from being treated as two unrelated rules.

Data flow: It receives a mutable permission profile. If the profile has network domain entries, it temporarily takes the map out, normalizes each domain pattern with normalize_host, and puts the cleaned map back. If there are no domain rules, it leaves the profile unchanged.

Call relations: It is called only by merge_permission_profiles, specifically when both parent and child contain domain rules. Its job is to prepare those maps so the later TOML merge combines matching hosts predictably.

Call graph: called by 1 (merge_permission_profiles); 1 external calls (take).

fn enabled_roots(&self) -> impl Iterator<Item = &String>

Purpose: Returns only the workspace root paths that are switched on. This lets later code ignore roots that are present in the file but explicitly disabled.

Data flow: It reads the map of root path strings to boolean enabled flags. It filters out entries set to false and yields references to the path strings whose flag is true.

Call relations: This is a convenience method for consumers of parsed workspace-root settings. It does not call other project code; it turns the raw map into the list that permission-building code usually wants.

fn is_empty(&self) -> bool

Purpose: Checks whether any filesystem permission rules were configured. This tells callers whether there are file access rules to apply.

Data flow: It reads the filesystem permission entries map and returns true if there are no path or pattern rules, otherwise false. The optional glob scan depth does not affect this answer.

Call relations: This helper is used by code that inspects parsed filesystem settings. It stands alone and does not delegate to other functions.

fn is_empty(&self) -> bool

Purpose: Checks whether any domain allow or deny rules were configured. It is a quick way to tell if network domain filtering has explicit entries.

Data flow: It looks at the domain permission map and returns true when the map is empty. If any domain pattern has an allow or deny rule, it returns false.

Call relations: This is a simple query on parsed network-domain configuration. It does not call other functions and is meant for later config application code.

fn allowed_domains(&self) -> Option<Vec<String>>

Purpose: Collects the domain patterns that are explicitly allowed. It gives callers a plain list when they only care about allow rules.

Data flow: It scans every domain entry, keeps only those whose permission is allow, clones their pattern strings, and returns them as a vector. If there are no allowed domains, it returns None instead of an empty list.

Call relations: This helper is used after TOML has been parsed, when another part of the system wants a compact allow-list. It works directly from the stored entries and does not call project-specific helpers.

fn denied_domains(&self) -> Option<Vec<String>>

Purpose: Collects the domain patterns that are explicitly denied. It gives callers a plain list when they only care about block rules.

Data flow: It scans every domain entry, keeps only those whose permission is deny, clones their pattern strings, and returns them as a vector. If there are no denied domains, it returns None instead of an empty list.

Call relations: This is the deny-list counterpart to allowed_domains. It is a read-only helper for consumers of parsed network-domain settings.

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

Purpose: Turns a domain permission value into the text allow or deny. This is used when the value needs to be displayed or included in a message.

Data flow: It receives an Allow or Deny enum value, chooses the matching lowercase word, and writes that word into the formatter. The output is formatted text, not a changed permission.

Call relations: Rust’s display formatting calls this when code prints a NetworkDomainPermissionToml. It uses the formatter’s write_str method to hand back the chosen word.

Call graph: 1 external calls (write_str).

fn is_empty(&self) -> bool

Purpose: Checks whether any Unix socket permission rules were configured. A Unix socket is a local communication path on Unix-like systems, often represented by a filesystem path.

Data flow: It reads the Unix socket permission map and returns true if no paths are listed. If any path has an allow or deny rule, it returns false.

Call relations: This is a simple inspection helper for parsed network settings. It does not call other project functions.

fn allow_unix_sockets(&self) -> Vec<String>

Purpose: Returns the Unix socket paths that are explicitly allowed. This is useful when code needs the approved local socket paths without the denied ones.

Data flow: It scans the socket permission entries, keeps only paths marked allow, clones those path strings, and returns them in a vector. Denied paths are skipped.

Call relations: This helper sits on top of the parsed socket-permission map. It does not apply the rules itself; it prepares the allowed paths for later config or policy code.

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

Purpose: Turns a Unix socket permission value into the text allow or deny. This supports clear display and error messages.

Data flow: It receives an Allow or Deny enum value, maps it to its lowercase word, and writes that word into the supplied formatter. The permission itself is not changed.

Call relations: Rust’s display formatting uses this method when a NetworkUnixSocketPermissionToml is printed. It hands the final text to the formatter through write_str.

Call graph: 1 external calls (write_str).

fn deserialize(deserializer: D) -> Result<Self, D::Error>

Purpose: Reads the MITM network section from configuration and immediately checks that its action definitions are valid. This prevents invalid hook/action setups from silently entering the runtime config.

Data flow: It receives a Serde deserializer, first reads the raw hooks and actions fields into an unchecked temporary structure, then builds the real NetworkMitmToml. Before returning it, it runs validation. If validation fails, deserialization fails with a human-readable error.

Call relations: Serde calls this automatically when parsing a NetworkMitmToml from TOML. It delegates the safety check to validate_action_definitions before handing the parsed value back to the config loader.

Call graph: 1 external calls (deserialize).

fn validate_action_definitions(&self) -> Result<(), String>

Purpose: Checks that MITM actions and hooks are not empty in ways that would make them meaningless. It catches mistakes like defining an action with no operations or a hook with no actions to run.

Data flow: It reads the optional action map and rejects any action whose operation lists are both empty. It then reads the optional hook map and rejects any hook whose action list is empty. It returns Ok if everything has enough information, or an error string naming the bad config path.

Call relations: This validation runs during NetworkMitmToml::deserialize and is also the first step inside validate_action_references. It formats clear error messages so configuration loading can tell the user exactly what is wrong.

Call graph: called by 1 (validate_action_references); 1 external calls (format!).

fn validate_action_references(
        &self,
        actions_by_name: &IndexMap<String, NetworkMitmActionToml>,
    ) -> Result<(), String>

Purpose: Checks that every MITM hook names actions that actually exist. This prevents a hook from saying “run action X” when no action X was defined.

Data flow: It receives the full action map to check against. First it reruns the basic definition checks. Then, for each hook and each action name listed by that hook, it looks for the name in the action map. If a name is missing, it returns an error string that points to the hook and missing action; otherwise it returns success.

Call relations: Callers use this when actions may come from a combined or external action map. It builds on validate_action_definitions, then uses the supplied map as the source of truth for valid action names.

Call graph: calls 1 internal fn (validate_action_definitions); 2 external calls (contains_key, format!).

fn to_runtime_hooks(
        &self,
        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
    ) -> Vec<MitmHookConfig>

Purpose: Converts parsed MITM hook configuration into the runtime hook objects used by the network proxy. This is the step where TOML-shaped data becomes proxy-shaped data.

Data flow: It reads the optional hook map. If there are hooks, it converts each hook into a MitmHookConfig, using the provided action map to expand action names into actual operations. If no hooks are configured, it returns an empty vector.

Call relations: Network settings call this while applying TOML config to NetworkProxyConfig. For each hook, it hands conversion work to NetworkMitmHookToml::to_runtime.

fn is_empty(&self) -> bool

Purpose: Reports whether an MITM action has no work to do. An action is empty if it neither strips request headers nor injects new ones.

Data flow: It reads the action’s two operation lists. If both lists are empty, it returns true; if either list has at least one operation, it returns false.

Call relations: This is used by MITM validation to reject action definitions that would do nothing. It is a small helper focused only on one action object.

fn apply_to_network_proxy_config(&self, config: &mut NetworkProxyConfig)

Purpose: Overlays the network settings from TOML onto an existing runtime network proxy configuration. It only changes fields that were explicitly present in the TOML profile.

Data flow: It receives parsed network settings and a mutable NetworkProxyConfig. For each optional setting, it checks whether the TOML provided a value; if so, it copies that value into the runtime config. Domain rules are overlaid through overlay_network_domain_permissions, Unix socket rules are translated into proxy permission values, and MITM hooks are converted into runtime hook configs. At the end, it turns on MITM behavior when limited network mode is active or when hooks are configured.

Call relations: This is the main handoff from configuration to the network proxy. It is called by to_network_proxy_config when building a fresh config and by apply_network when applying network settings into a broader existing configuration.

Call graph: calls 1 internal fn (overlay_network_domain_permissions); called by 2 (to_network_proxy_config, apply_network).

fn to_network_proxy_config(&self) -> NetworkProxyConfig

Purpose: Builds a complete runtime network proxy configuration from this TOML network section. It is a convenient one-step conversion when there is no existing config to overlay.

Data flow: It starts with the default NetworkProxyConfig, then calls apply_to_network_proxy_config to copy all explicit TOML settings into it. The finished runtime config is returned to the caller.

Call relations: This is a wrapper around apply_to_network_proxy_config. It is useful when callers want a new config object rather than modifying one they already have.

Call graph: calls 1 internal fn (apply_to_network_proxy_config); 1 external calls (default).

fn to_runtime(
        &self,
        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
    ) -> MitmHookConfig

Purpose: Converts one parsed MITM hook into the runtime hook format used by the proxy. A hook says which requests match and which actions should run for those requests.

Data flow: It reads the hook’s host, methods, path prefixes, query rules, header rules, optional body matcher, and action names. It copies the match rules into a MitmHookMatchConfig and calls selected_actions to turn action names into concrete strip/inject operations. It returns a complete MitmHookConfig.

Call relations: This is called while NetworkMitmToml::to_runtime_hooks converts all configured hooks. It delegates action expansion to NetworkMitmHookToml::selected_actions so matching logic and action selection stay separate.

Call graph: calls 1 internal fn (selected_actions).

fn selected_actions(
        &self,
        actions_by_name: Option<&IndexMap<String, NetworkMitmActionToml>>,
    ) -> MitmHookActionsConfig

Purpose: Expands the action names listed by one hook into the actual header operations the proxy should perform. It combines multiple named actions in the order the hook lists them.

Data flow: It receives an optional map of action definitions. If no map is supplied, it returns an empty action set. Otherwise it creates an empty runtime action config, looks up each action name from the hook, and appends that action’s headers-to-strip and headers-to-inject. Injected header entries are converted into runtime header configs before being added.

Call relations: This is called by NetworkMitmHookToml::to_runtime for each hook. It uses NetworkMitmInjectedHeaderToml::to_runtime for the small conversion of each injected header.

Call graph: called by 1 (to_runtime); 1 external calls (default).

fn to_runtime(&self) -> InjectedHeaderConfig

Purpose: Converts one configured injected header into the runtime format expected by the proxy. Injected headers can get their secret value from an environment variable or a file, with an optional prefix.

Data flow: It reads the header name, optional secret environment variable name, optional secret file path, and optional prefix from the TOML object. It clones those fields into a new InjectedHeaderConfig and returns it.

Call relations: This is used when NetworkMitmHookToml::selected_actions expands named actions into proxy-ready operations. It handles the final per-header translation step.

fn overlay_network_domain_permissions(
    config: &mut NetworkProxyConfig,
    domains: &NetworkDomainPermissionsToml,
)

Purpose: Applies domain allow and deny rules from parsed TOML onto an existing network proxy configuration. It updates the proxy’s domain rule set without replacing unrelated settings.

Data flow: It receives a mutable NetworkProxyConfig and parsed domain permissions. For each domain pattern, it translates the TOML permission into the proxy’s permission type, then inserts or updates that domain rule in the proxy config. Host names are normalized during insertion so equivalent domain spellings line up.

Call relations: This helper is called by NetworkToml::apply_to_network_proxy_config when network TOML includes domain rules, and also by apply_network_constraints when domain constraints are applied elsewhere. It centralizes the permission translation so both paths behave the same way.

Call graph: called by 2 (apply_to_network_proxy_config, apply_network_constraints).

fn default_builtin_permission_profile_name(
    active_project: &ProjectConfig,
    windows_sandbox_level: WindowsSandboxLevel,
) -> &'static str

Purpose: Chooses which built-in permission profile Codex should use when the user has not picked one. It prefers workspace access for projects marked trusted or untrusted, unless Windows sandboxing is disabled, and otherwise falls back to read-only.

Data flow: It receives the active project settings and the Windows sandbox level. It checks whether the project is trusted or explicitly untrusted, then considers whether the current platform is Windows with sandboxing disabled. It returns the name of the built-in profile Codex should use.

Call relations: This is an early selection helper. It relies on the project’s trust checks and feeds later profile compilation by naming the default profile.

Call graph: calls 2 internal fn (is_trusted, is_untrusted); 1 external calls (cfg!).

fn is_builtin_permission_profile_name(profile_name: &str) -> bool

Purpose: Answers whether a profile name is one of Codex’s reserved built-in names. This prevents custom and built-in profiles from being confused.

Data flow: It receives a profile name string, compares it with the three reserved built-in names, and returns true or false.

Call relations: Profile-selection code calls this before looking for custom configuration, especially when preparing workspace roots or network proxy settings.

Call graph: called by 2 (compile_permission_profile_workspace_roots, network_proxy_config_for_profile_selection); 1 external calls (matches!).

fn builtin_permission_profile(
    profile_name: &str,
    workspace_write: Option<&SandboxWorkspaceWrite>,
) -> Option<PermissionProfile>

Purpose: Builds the actual built-in permission profile for a reserved profile name. It is used when no custom TOML profile needs to be read.

Data flow: It receives a profile name and optional workspace-write settings. For read-only it creates a read-only profile; for workspace-write it may include network and temporary-directory choices; for full access it disables sandboxing. Unknown names produce no profile.

Call relations: Configuration loading and profile compilation call this first. If it returns a profile, later custom-profile resolution is skipped.

Call graph: calls 3 internal fn (read_only, workspace_write, workspace_write_with); called by 2 (load_config_with_layer_stack, compile_permission_profile_selection).

fn validate_user_permission_profile_names(
    permissions: Option<&PermissionsToml>,
) -> io::Result<()>

Purpose: Checks that user-defined permission profile names do not start with :, because that prefix is reserved for built-in names. This avoids future collisions and confusing configuration.

Data flow: It receives the optional permissions table. If no table exists, it succeeds. If a user profile name starts with :, it returns an invalid-input error; otherwise it returns success.

Call relations: The effective permission-selection flow calls this while validating configuration before Codex commits to a profile.

Call graph: called by 1 (resolve_effective_permission_selection); 2 external calls (new, format!).

fn network_proxy_config_from_profile_network(
    network: Option<&NetworkToml>,
) -> NetworkProxyConfig

Purpose: Creates network proxy settings from the network section of a permission profile, but deliberately keeps the managed proxy disabled. This lets profiles describe proxy details without turning the proxy feature on by themselves.

Data flow: It receives an optional network configuration from a profile. It converts that to a proxy configuration or starts from defaults, then forces the proxy-enabled flag to false. It returns the prepared proxy configuration.

Call relations: Network proxy selection calls this after resolving a custom profile’s network section.

Call graph: called by 1 (network_proxy_config_for_profile_selection).

fn apply_network_proxy_feature_config(
    config: &mut NetworkProxyConfig,
    feature_config: &NetworkProxyConfigToml,
)

Purpose: Applies the separate network-proxy feature configuration on top of an existing proxy configuration. This is where the feature switch and proxy-specific allow or deny lists are copied into the runtime proxy settings.

Data flow: It receives a mutable proxy configuration and feature configuration from TOML. It translates feature-specific mode, domain, and Unix socket permission values into the profile-style network format, then applies them to the existing proxy config.

Call relations: Configuration loading and active-profile proxy setup call this after base proxy settings are known, so feature-level choices can override or complete them.

Call graph: called by 2 (load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile).

fn resolve_permission_profile(
    permissions: &PermissionsToml,
    profile_name: &str,
) -> io::Result<PermissionProfileToml>

Purpose: Finds and expands a named custom permission profile. Expansion means following any extends relationship so the final profile includes inherited settings.

Data flow: It receives the permissions table and a profile name. It asks the TOML permissions object to resolve the profile, allowing certain built-in profiles as extendable parents. It returns the resolved profile or an invalid-input error.

Call relations: Filesystem compilation, workspace-root compilation, and network proxy selection call this whenever the chosen profile is not a direct built-in profile.

Call graph: calls 1 internal fn (resolve_profile); called by 3 (compile_permission_profile, compile_permission_profile_workspace_roots, network_proxy_config_for_profile_selection).

fn extensible_builtin_parent_profile(profile_name: &str) -> Option<PermissionProfileToml>

Purpose: Provides built-in profiles that custom profiles are allowed to extend. Only read-only and workspace-write are available this way.

Data flow: It receives a profile name. If the name is an extendable built-in profile, it creates the corresponding filesystem policy and converts it into TOML-shaped profile data. Otherwise it returns nothing.

Call relations: Profile resolution uses this as a callback when a custom profile says it extends a built-in profile.

Call graph: calls 3 internal fn (permission_profile_toml_from_file_system_policy, read_only, workspace_write).

fn permission_profile_toml_from_file_system_policy(
    file_system: FileSystemSandboxPolicy,
) -> PermissionProfileToml

Purpose: Converts an internal filesystem sandbox policy back into the TOML-shaped profile format. This lets built-in policies act like parent profiles for custom profiles.

Data flow: It receives a filesystem policy with entries and optional glob-scan depth. It creates a TOML filesystem table, inserts each policy entry into that table, and returns a permission profile containing that filesystem section.

Call relations: The extendable built-in parent helper calls this when turning built-in read-only or workspace-write rules into something profile resolution can merge.

Call graph: calls 1 internal fn (insert_filesystem_permission_toml); called by 1 (extensible_builtin_parent_profile); 1 external calls (new).

fn insert_filesystem_permission_toml(
    entries: &mut BTreeMap<String, FilesystemPermissionToml>,
    entry: FileSystemSandboxEntry,
)

Purpose: Adds one internal filesystem rule to a TOML-style map. It preserves whether the rule was for an exact path, a glob pattern, or a special symbolic path.

Data flow: It receives a mutable TOML entries map and one sandbox entry. It converts the entry path into a string key or delegates special paths to a helper, then stores the access mode under that key.

Call relations: The policy-to-profile conversion loop calls this for each filesystem sandbox entry.

Call graph: calls 1 internal fn (insert_special_filesystem_permission_toml); called by 1 (permission_profile_toml_from_file_system_policy); 1 external calls (Access).

fn insert_special_filesystem_permission_toml(
    entries: &mut BTreeMap<String, FilesystemPermissionToml>,
    value: FileSystemSpecialPath,
    access: FileSystemAccessMode,
)

Purpose: Converts a special filesystem path, such as workspace roots or temporary directories, into its TOML key form. Special paths are symbolic names that are resolved later.

Data flow: It receives the TOML entries map, a special path value, and an access mode. It writes keys like :root, :minimal, or :workspace_roots, using scoped nested entries when the special path includes a subpath.

Call relations: General filesystem-entry insertion calls this whenever the internal rule uses a special symbolic path.

Call graph: calls 1 internal fn (insert_scoped_filesystem_permission_toml); called by 1 (insert_filesystem_permission_toml); 1 external calls (Access).

fn insert_scoped_filesystem_permission_toml(
    entries: &mut BTreeMap<String, FilesystemPermissionToml>,
    path: String,
    subpath: PathBuf,
    access: FileSystemAccessMode,
)

Purpose: Stores a permission for a subpath beneath a larger path key. This is how TOML can say, for example, that only a folder inside the workspace roots has a particular access mode.

Data flow: It receives the entries map, the parent path key, the subpath, and the access mode. It ensures the parent key is represented as a scoped map and then records the subpath permission inside it.

Call relations: Special-path conversion calls this for special paths that carry nested subpaths.

Call graph: called by 1 (insert_special_filesystem_permission_toml); 3 external calls (from, to_string_lossy, Scoped).

fn network_proxy_config_for_profile_selection(
    permissions: Option<&PermissionsToml>,
    profile_name: &str,
) -> io::Result<NetworkProxyConfig>

Purpose: Finds the network proxy configuration associated with the selected permission profile. Built-in profiles get the default proxy configuration; custom profiles may provide proxy details.

Data flow: It receives an optional permissions table and a profile name. If the name is built-in, it returns defaults. Otherwise it rejects unknown reserved names, resolves the custom profile, converts its network section, and returns the result.

Call relations: Configuration loading and active-profile proxy setup call this when they need proxy settings tied to the selected permission profile.

Call graph: calls 4 internal fn (is_builtin_permission_profile_name, network_proxy_config_from_profile_network, reject_unknown_builtin_permission_profile, resolve_permission_profile); called by 2 (load_config_with_layer_stack, network_proxy_spec_for_active_permission_profile); 1 external calls (default).

fn compile_permission_profile(
    permissions: &PermissionsToml,
    profile_name: &str,
    policy_cwd: &Path,
    startup_warnings: &mut Vec<String>,
) -> io::Result<(FileSystemSandboxPolicy, Netwo

Purpose: Turns a resolved custom permission profile into runtime sandbox policies for files and network. This is the main compiler for user-defined permission profiles.

Data flow: It receives the permissions table, profile name, base directory for resolving paths, and a warning list. It resolves the profile, starts from restricted filesystem and network defaults, compiles each filesystem entry, validates glob settings, emits warnings for unsupported or empty rules, and returns the final filesystem and network policies.

Call relations: Profile selection calls this after it has determined the chosen profile is custom. It delegates detailed path parsing to filesystem helpers and network handling to the network policy compiler.

Call graph: calls 9 internal fn (compile_filesystem_permission, compile_network_sandbox_policy, missing_filesystem_entries_warning, push_warning, resolve_permission_profile, unbounded_unreadable_globstar_paths, unsupported_read_write_glob_paths, validate_glob_scan_max_depth, restricted); called by 1 (compile_permission_profile_selection); 3 external calls (new, cfg!, format!).

fn compile_permission_profile_selection(
    permissions: Option<&PermissionsToml>,
    profile_name: &str,
    workspace_write: Option<&SandboxWorkspaceWrite>,
    policy_cwd: &Path,
    startup_warn

Purpose: Compiles whichever permission profile the user selected, whether built-in or custom. It is the high-level entry point for turning a selected profile name into runtime permissions.

Data flow: It receives optional custom permissions, a profile name, optional workspace-write settings, a policy base directory, and warning storage. It first tries built-in profiles. If none matches, it rejects unknown reserved names, requires a permissions table, and compiles the custom profile.

Call relations: Configuration loading calls this to produce the sandbox permissions Codex will actually enforce during a session.

Call graph: calls 3 internal fn (builtin_permission_profile, compile_permission_profile, reject_unknown_builtin_permission_profile); called by 1 (load_config_with_layer_stack).

fn compile_permission_profile_workspace_roots(
    permissions: Option<&PermissionsToml>,
    profile_name: &str,
    policy_cwd: &Path,
) -> io::Result<Vec<AbsolutePathBuf>>

Purpose: Extracts any extra workspace roots declared by a custom permission profile. Built-in profiles do not add extra roots here.

Data flow: It receives optional permissions, a profile name, and the base directory for path resolution. Built-in names return an empty list. Custom names are resolved, and enabled workspace root paths are converted into absolute paths.

Call relations: Configuration loading calls this alongside permission compilation so runtime workspace-root lists match the chosen custom profile.

Call graph: calls 4 internal fn (compile_workspace_roots, is_builtin_permission_profile_name, reject_unknown_builtin_permission_profile, resolve_permission_profile); called by 1 (load_config_with_layer_stack); 1 external calls (new).

fn compile_workspace_roots(
    workspace_roots: Option<&WorkspaceRootsToml>,
    policy_cwd: &Path,
) -> Vec<AbsolutePathBuf>

Purpose: Converts enabled workspace-root entries from configuration into absolute paths. These roots can later be used by symbolic rules such as :workspace_roots.

Data flow: It receives an optional workspace-roots section and a base directory. If no section exists, it returns an empty list. Otherwise it resolves each enabled root against the base directory and returns the collected absolute paths.

Call relations: Custom-profile workspace-root compilation calls this after the profile has been resolved.

Call graph: called by 1 (compile_permission_profile_workspace_roots).

fn reject_unknown_builtin_permission_profile(profile_name: &str) -> io::Result<()>

Purpose: Rejects profile names that look like reserved built-in names but are not known by this version of Codex. This gives a clear error instead of treating a misspelled built-in as a custom profile.

Data flow: It receives a profile name. If the name starts with :, it returns an invalid-input error naming the unknown built-in profile. Otherwise it succeeds.

Call relations: Profile selection, workspace-root selection, and network proxy selection call this after known built-in names have already been checked.

Call graph: called by 3 (compile_permission_profile_selection, compile_permission_profile_workspace_roots, network_proxy_config_for_profile_selection); 2 external calls (new, format!).

fn get_readable_roots_required_for_codex_runtime(
    codex_home: &Path,
    zsh_path: Option<&PathBuf>,
    main_execve_wrapper_exe: Option<&PathBuf>,
) -> Vec<AbsolutePathBuf>

Purpose: Returns filesystem locations that Codex itself must be able to read so shell commands can start correctly. These paths are added even when user permissions are otherwise tight.

Data flow: It receives the Codex home directory, optional zsh path, and optional exec wrapper path. It converts valid absolute paths into readable roots, treating wrapper paths under Codex’s temporary arg0 area as their parent directory. It returns the roots that should be readable.

Call relations: Configuration loading calls this when building the final filesystem policy, so the sandbox does not accidentally block Codex’s own launch support files.

Call graph: calls 1 internal fn (from_absolute_path); called by 1 (load_config_with_layer_stack); 2 external calls (join, new).

fn compile_network_sandbox_policy(
    network: Option<&NetworkToml>,
    base_network_sandbox_policy: NetworkSandboxPolicy,
) -> NetworkSandboxPolicy

Purpose: Chooses the runtime network sandbox policy from a profile’s network section. If the profile does not say anything, it keeps the provided base policy.

Data flow: It receives optional network settings and a base network policy. enabled = true becomes full network access, enabled = false becomes restricted access, and no value keeps the base. It returns the resulting network policy.

Call relations: The custom profile compiler calls this after filesystem rules are compiled.

Call graph: called by 1 (compile_permission_profile).

fn compile_filesystem_permission(
    path: &str,
    permission: &FilesystemPermissionToml,
    policy_cwd: &Path,
    startup_warnings: &mut Vec<String>,
) -> io::Result<Vec<FileSystemSandboxEntry>>

Purpose: Compiles one TOML filesystem permission entry into one or more runtime sandbox entries. It understands both direct path permissions and scoped subpath permissions.

Data flow: It receives a path key, the permission value, the policy base directory, and warning storage. Direct access entries become one sandbox entry. Scoped entries are processed one by one, with deny globs becoming pattern rules when allowed and other entries becoming exact or special paths. It returns the list of compiled sandbox entries.

Call relations: The custom profile compiler calls this for every configured filesystem rule, and this function delegates the path-specific decisions to lower-level helpers.

Call graph: calls 6 internal fn (compile_filesystem_access_path, compile_read_write_glob_path, compile_scoped_filesystem_path, compile_scoped_filesystem_pattern, contains_glob_chars, parse_special_path); called by 1 (compile_permission_profile); 1 external calls (new).

fn compile_filesystem_access_path(
    path: &str,
    access: FileSystemAccessMode,
    startup_warnings: &mut Vec<String>,
) -> io::Result<FileSystemPath>

Purpose: Compiles the path part of a direct filesystem access rule. It decides whether a glob pattern is allowed or whether the path must be treated as a normal exact path.

Data flow: It receives a path string, an access mode, and warning storage. Non-glob paths are parsed normally. Deny glob paths become glob-pattern rules. Read or write paths may only use a trailing /** shortcut; otherwise an error is returned. It returns a runtime filesystem path value.

Call relations: Direct filesystem permission compilation calls this when the TOML entry is a simple access rule.

Call graph: calls 4 internal fn (compile_filesystem_path, compile_read_write_glob_path, contains_glob_chars, parse_absolute_path); called by 1 (compile_filesystem_permission).

fn compile_filesystem_path(
    path: &str,
    startup_warnings: &mut Vec<String>,
) -> io::Result<FileSystemPath>

Purpose: Parses a filesystem path string into the internal path form. It supports special symbolic paths and real absolute paths.

Data flow: It receives a path string and warning storage. If the string is a special path like :tmpdir, it returns a special-path value and may warn if the special path is unknown. Otherwise it requires and returns an absolute path.

Call relations: Both direct and scoped path compilation call this when they need a normal filesystem path result.

Call graph: calls 3 internal fn (maybe_push_unknown_special_path_warning, parse_absolute_path, parse_special_path); called by 2 (compile_filesystem_access_path, compile_scoped_filesystem_path).

fn compile_scoped_filesystem_path(
    path: &str,
    subpath: &str,
    startup_warnings: &mut Vec<String>,
) -> io::Result<FileSystemPath>

Purpose: Compiles a nested permission such as a subfolder under an absolute path or under :workspace_roots. It makes sure the subpath cannot escape upward with ...

Data flow: It receives a parent path, subpath, and warning storage. A subpath of . means the parent path itself. Special parents are allowed only if they support nesting. Absolute parent paths are combined with the safe relative subpath. It returns the compiled filesystem path.

Call relations: Scoped filesystem permission compilation calls this for literal scoped entries that are not being turned into deny glob patterns.

Call graph: calls 6 internal fn (compile_filesystem_path, maybe_push_unknown_special_path_warning, parse_absolute_path, parse_relative_subpath, parse_special_path, resolve_path_against_base); called by 1 (compile_filesystem_permission); 4 external calls (project_roots, unknown, new, format!).

fn compile_scoped_filesystem_pattern(
    path: &str,
    subpath: &str,
    access: FileSystemAccessMode,
    _policy_cwd: &Path,
) -> io::Result<String>

Purpose: Compiles a scoped deny glob into a runtime glob pattern. This is used for rules like denying certain file patterns under workspace roots.

Data flow: It receives a parent path, subpath glob, access mode, and policy base directory. It rejects anything except deny access, checks that the subpath is a safe descendant path, then returns either a symbolic workspace-roots glob pattern or an absolute joined pattern.

Call relations: Scoped filesystem permission compilation calls this only when a scoped subpath contains glob characters and the rule is a deny rule.

Call graph: calls 4 internal fn (parse_absolute_path, parse_relative_subpath, parse_special_path, project_roots_glob_pattern); called by 1 (compile_filesystem_permission); 2 external calls (new, format!).

fn compile_read_write_glob_path(path: &str, access: FileSystemAccessMode) -> io::Result<&str>

Purpose: Allows read or write rules to use only a simple trailing /** subtree shortcut, not arbitrary glob matching. This protects against pretending the sandbox can enforce glob-based write permissions that it cannot fully express.

Data flow: It receives a path and access mode. If there are no glob characters, it returns the path unchanged. If the only glob is a trailing /**, it returns the path without that suffix. Other glob use returns an invalid-input error.

Call relations: Direct and scoped filesystem compilation call this when read or write access is combined with path text that may contain glob characters.

Call graph: calls 2 internal fn (contains_glob_chars, remove_trailing_glob_suffix); called by 2 (compile_filesystem_access_path, compile_filesystem_permission); 2 external calls (new, format!).

fn unsupported_read_write_glob_paths(filesystem: &FilesystemPermissionsToml) -> Vec<String>

Purpose: Finds read or write glob rules that may not be fully supported on non-macOS sandboxes. These are warning candidates, not immediate compilation errors in this scan.

Data flow: It receives a filesystem permissions table. It walks direct and scoped entries, looking for non-deny access where glob characters remain after ignoring a trailing /**. It returns the matching path strings.

Call relations: The custom profile compiler calls this on non-macOS platforms so it can add startup warnings before compiling entries.

Call graph: calls 2 internal fn (contains_glob_chars, remove_trailing_glob_suffix); called by 1 (compile_permission_profile); 2 external calls (new, format!).

fn unbounded_unreadable_globstar_paths(filesystem: &FilesystemPermissionsToml) -> Vec<String>

Purpose: Finds deny-read glob rules that use ** without a configured scan-depth limit. On some platforms, unbounded recursive glob expansion is not natively supported.

Data flow: It receives a filesystem permissions table. If glob_scan_max_depth is set, it returns no warnings. Otherwise it scans direct and scoped deny entries for ** and returns the affected path strings.

Call relations: The custom profile compiler calls this on non-macOS platforms to warn users about deny patterns that may need a depth cap.

Call graph: called by 1 (compile_permission_profile); 2 external calls (new, format!).

fn validate_glob_scan_max_depth(max_depth: Option<usize>) -> io::Result<Option<usize>>

Purpose: Checks that a configured glob scan depth is valid. A depth of zero is rejected because it would not make sense as a maximum scan depth.

Data flow: It receives an optional depth number. If the value is Some(0), it returns an invalid-input error. Any other value, including no value, is returned unchanged.

Call relations: The custom profile compiler calls this before storing the depth on the runtime filesystem policy.

Call graph: called by 1 (compile_permission_profile); 1 external calls (new).

fn contains_glob_chars(path: &str) -> bool

Purpose: Checks whether a path string contains glob-pattern characters such as *, ?, [, or ]. It uses platform-aware behavior for Windows paths.

Data flow: It receives a path string, passes it to the platform-aware checker with the current operating-system setting, and returns true or false.

Call relations: Filesystem compilation and warning scans call this whenever they need to distinguish literal paths from pattern-like paths.

Call graph: calls 1 internal fn (contains_glob_chars_for_platform); called by 4 (compile_filesystem_access_path, compile_filesystem_permission, compile_read_write_glob_path, unsupported_read_write_glob_paths); 1 external calls (cfg!).

fn contains_glob_chars_for_platform(path: &str, is_windows: bool) -> bool

Purpose: Performs the actual glob-character check, with special normalization for Windows device paths. This avoids mistaking Windows path prefixes for ordinary text.

Data flow: It receives a path string and a flag saying whether to use Windows rules. On Windows it first normalizes device-style paths if possible, then scans the resulting string for glob characters. It returns true or false.

Call relations: The public glob check helper calls this with the current platform choice.

Call graph: calls 1 internal fn (normalize_windows_device_path); called by 1 (contains_glob_chars).

fn remove_trailing_glob_suffix(path: &str) -> &str

Purpose: Removes a trailing /** from a path if it is present. In this file, that suffix means “the whole subtree under this directory” for certain read or write rules.

Data flow: It receives a path string. If the string ends with /**, it returns the part before that suffix; otherwise it returns the original string slice.

Call relations: Read/write glob validation and warning scans use this to allow the special subtree form while still detecting other glob characters.

Call graph: called by 2 (compile_read_write_glob_path, unsupported_read_write_glob_paths).

fn parse_special_path(path: &str) -> Option<FileSystemSpecialPath>

Purpose: Recognizes symbolic filesystem paths such as :root, :minimal, and :workspace_roots. Unknown :-prefixed names are kept as unknown values instead of causing immediate failure.

Data flow: It receives a path string. Known special names become specific special-path values. Any other string beginning with : becomes an unknown special path, and ordinary paths return nothing.

Call relations: Filesystem path compilation calls this before trying to parse a real absolute path. Keeping unknown values lets older Codex versions warn rather than reject newer configuration.

Call graph: called by 4 (compile_filesystem_path, compile_filesystem_permission, compile_scoped_filesystem_path, compile_scoped_filesystem_pattern); 2 external calls (project_roots, unknown).

fn parse_absolute_path(path: &str) -> io::Result<AbsolutePathBuf>

Purpose: Parses a path string as an absolute path using rules for the current platform. It also allows user-home forms such as ~ and ~/... through the absolute-path utility.

Data flow: It receives a path string, calls the platform-aware parser using the current operating system, and returns an absolute path or an invalid-input error.

Call relations: Filesystem path and pattern compilation call this whenever a configured path is not a special symbolic path.

Call graph: calls 1 internal fn (parse_absolute_path_for_platform); called by 4 (compile_filesystem_access_path, compile_filesystem_path, compile_scoped_filesystem_path, compile_scoped_filesystem_pattern); 1 external calls (cfg!).

fn parse_absolute_path_for_platform(path: &str, is_windows: bool) -> io::Result<AbsolutePathBuf>

Purpose: Checks and converts a path string into an absolute path under a chosen platform’s rules. This is the core validation that rejects relative top-level filesystem rules.

Data flow: It receives a path string and a Windows-or-not flag. It normalizes Windows device paths when needed, checks whether the result is absolute or home-relative, and then asks the absolute-path utility to produce an absolute path. Invalid relative paths become errors.

Call relations: The current-platform absolute-path parser delegates to this function.

Call graph: calls 3 internal fn (is_absolute_path_for_platform, normalize_absolute_path_for_platform, from_absolute_path); called by 1 (parse_absolute_path); 2 external calls (new, format!).

fn is_absolute_path_for_platform(path: &str, normalized_path: &Path, is_windows: bool) -> bool

Purpose: Decides whether a path counts as absolute on a chosen platform. Windows needs extra checks because absolute paths can look like C:\... or network shares.

Data flow: It receives the original path string, a normalized path, and a Windows-or-not flag. On Windows it checks both original and normalized strings with Windows rules; on other systems it uses the standard absolute-path test. It returns true or false.

Call relations: The platform-aware absolute-path parser calls this before accepting a configured filesystem path.

Call graph: calls 1 internal fn (is_windows_absolute_path); called by 1 (parse_absolute_path_for_platform); 2 external calls (is_absolute, to_string_lossy).

fn normalize_absolute_path_for_platform(path: &str, is_windows: bool) -> Cow<'_, Path>

Purpose: Normalizes Windows device-path forms before absolute-path validation. On non-Windows platforms it leaves the path untouched.

Data flow: It receives a path string and a Windows-or-not flag. If not Windows, it returns a borrowed view of the original path. If Windows and the path has a recognized device prefix, it returns an owned normalized path; otherwise it borrows the original.

Call relations: The platform-aware absolute-path parser calls this before checking whether the path is absolute.

Call graph: calls 1 internal fn (normalize_windows_device_path); called by 1 (parse_absolute_path_for_platform); 4 external calls (Borrowed, Owned, new, from).

fn normalize_windows_device_path(path: &str) -> Option<String>

Purpose: Turns Windows device-style prefixes like \\?\ and \\.\ into more ordinary absolute path forms when possible. This helps later validation treat equivalent Windows paths consistently.

Data flow: It receives a path string. It recognizes UNC network-device forms and drive-letter device forms, rewrites them into standard-looking paths, and returns the normalized string. Unrecognized paths return nothing.

Call relations: Windows-aware glob checking and absolute-path normalization both call this before interpreting path text.

Call graph: calls 1 internal fn (is_windows_drive_absolute_path); called by 2 (contains_glob_chars_for_platform, normalize_absolute_path_for_platform); 1 external calls (format!).

fn is_windows_absolute_path(path: &str) -> bool

Purpose: Checks whether a string is an absolute Windows path. It accepts drive-letter paths and network-share style paths.

Data flow: It receives a path string. It returns true if the path looks like C:\..., C:/..., or starts with a double backslash network prefix.

Call relations: Platform-aware absolute-path checking calls this when using Windows rules.

Call graph: calls 1 internal fn (is_windows_drive_absolute_path); called by 1 (is_absolute_path_for_platform).

fn is_windows_drive_absolute_path(path: &str) -> bool

Purpose: Checks for the Windows drive-letter absolute path shape, such as C:\folder or C:/folder. This is a small helper for Windows path validation.

Data flow: It receives a path string. It inspects the first three bytes for an ASCII letter, a colon, and then a slash or backslash. It returns true or false.

Call relations: Windows absolute-path detection and Windows device-path normalization call this to recognize drive-rooted paths.

Call graph: called by 2 (is_windows_absolute_path, normalize_windows_device_path); 1 external calls (matches!).

fn parse_relative_subpath(subpath: &str) -> io::Result<PathBuf>

Purpose: Validates that a scoped subpath is a safe descendant path. It rejects empty strings, ., .., and anything with non-normal path components.

Data flow: It receives a subpath string. It inspects the path components and accepts only normal directory or file names. A valid subpath becomes a PathBuf; invalid input returns an error explaining that the subpath must stay below its parent.

Call relations: Scoped filesystem path and scoped glob-pattern compilation call this before combining a subpath with a parent path.

Call graph: called by 2 (compile_scoped_filesystem_path, compile_scoped_filesystem_pattern); 3 external calls (new, new, format!).

fn push_warning(startup_warnings: &mut Vec<String>, message: String)

Purpose: Records a startup warning and also writes it to the tracing log. This keeps user-visible warnings and diagnostic logs in sync.

Data flow: It receives the warning list and a message. It logs the message, pushes it into the list, and returns nothing.

Call relations: Profile compilation and unknown special-path handling call this whenever configuration should not fail but should be brought to the user’s attention.

Call graph: called by 2 (compile_permission_profile, maybe_push_unknown_special_path_warning); 1 external calls (warn!).

fn missing_filesystem_entries_warning(profile_name: &str) -> String

Purpose: Builds the warning text used when a permission profile has no recognized filesystem entries. This tells the user that filesystem access will remain restricted.

Data flow: It receives the profile name and formats a clear warning string mentioning that this Codex version may not recognize the intended entries. It returns that string.

Call relations: The custom profile compiler calls this before passing the message to the warning recorder.

Call graph: called by 1 (compile_permission_profile); 1 external calls (format!).

fn maybe_push_unknown_special_path_warning(
    special: &FileSystemSpecialPath,
    startup_warnings: &mut Vec<String>,
)

Purpose: Warns when a configured special filesystem path is unknown to this Codex version. Unknown special paths are ignored rather than causing configuration load to fail.

Data flow: It receives a special-path value and warning storage. If the value is not unknown, it does nothing. If it is unknown, it formats a message, including nested subpath information when present, and records the warning.

Call relations: Filesystem path compilation calls this after parsing special paths, so forward-compatible configuration problems are visible during startup.

Call graph: calls 1 internal fn (push_warning); called by 2 (compile_filesystem_path, compile_scoped_filesystem_path); 1 external calls (format!).

fn from_str(id: &str) -> Option<Self>

Purpose: This turns a text id into one of the known built-in permission profile choices. It is used to tell whether an active profile id refers to a standard profile or to a custom named one.

Data flow: It receives a string id. It compares that id with the known built-in profile names for read-only, workspace, and danger-full-access. It returns the matching built-in enum value, or nothing if the id is not one of those standard names.

Call relations: When ResolvedPermissionProfile::from_active_profile is given an active profile id, it calls this first. If this function recognizes the id, the profile is stored as built-in; otherwise the same id is treated as a named custom profile.

Call graph: called by 1 (from_active_profile).

fn as_str(self) -> &'static str

Purpose: This converts a built-in profile choice back into its public text id. It is used when the system needs to report or save which built-in profile is active.

Data flow: It receives a built-in profile enum value. It matches that value to the corresponding constant string id. It returns that static string without changing any stored state.

Call relations: ResolvedPermissionProfile::active_permission_profile uses this when rebuilding an ActivePermissionProfile for a built-in profile, so callers see the standard profile id rather than the internal enum value.

fn from_active_profile(
        permission_profile: PermissionProfile,
        active_permission_profile: Option<ActivePermissionProfile>,
        profile_workspace_roots: Vec<AbsolutePathBuf>,
    )

Purpose: This builds the richer internal record for a permission profile when the caller may also know the active profile id. It decides whether the profile is legacy, built-in, or named.

Data flow: It receives a concrete PermissionProfile, an optional ActivePermissionProfile, and any workspace roots declared by the profile. If there is no active profile id, it returns a legacy resolved profile. If there is an id, it checks whether that id is built-in; built-in ids become BuiltIn records, and all other ids become Named records. The original permission rules and workspace roots are kept with the chosen identity.

Call relations: PermissionProfileSnapshot::active_with_profile_workspace_roots and PermissionProfileState::from_constrained_active_profile call this after a profile id has already been resolved elsewhere. Inside, it calls BuiltInPermissionProfileId::from_str to classify the id, or falls back to ResolvedPermissionProfile::legacy when there is no id.

Call graph: calls 1 internal fn (from_str); called by 2 (active_with_profile_workspace_roots, from_constrained_active_profile); 3 external calls (BuiltIn, Named, legacy).

fn legacy(permission_profile: PermissionProfile) -> Self

Purpose: This creates a resolved profile for old-style or local permission settings that do not have an active profile name. It keeps the concrete permission rules but intentionally records no profile identity.

Data flow: It receives a PermissionProfile. It wraps that profile in the Legacy variant. The result can still be queried for its permissions, but it will report no active profile id and no profile-defined workspace roots.

Call relations: This is the common path for older configuration flows and direct permission overrides. Snapshot creation, constrained legacy setup, permission checks, and legacy setters all call it when they need to represent permissions without a named or built-in profile.

Call graph: called by 4 (legacy, can_set_legacy_permission_profile, from_constrained_legacy, set_legacy_permission_profile); 1 external calls (Legacy).

fn permission_profile(&self) -> &PermissionProfile

Purpose: This returns the concrete permission rules no matter how the profile was identified. Callers use it when they care about what actions are allowed, not where the rules came from.

Data flow: It reads the current resolved profile variant. Whether the variant is legacy, built-in, or named, it returns a shared reference to the stored PermissionProfile. It does not copy or change anything.

Call relations: PermissionProfileSnapshot::permission_profile and PermissionProfileState constraint checks rely on this view. It is the bridge from the richer identity-carrying wrapper back to the actual permission rules.

Call graph: called by 1 (permission_profile).

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

Purpose: This reconstructs the active profile identity, if the resolved profile has one. It lets other parts of the system report which built-in or custom profile is selected.

Data flow: It reads the resolved profile. For legacy profiles it returns nothing. For built-in profiles it converts the internal built-in id back to its standard string and includes the stored extension information. For named profiles it returns the stored custom id and extension information.

Call relations: PermissionProfileSnapshot and PermissionProfileState expose this result to callers that need session state, user interface state, or outgoing protocol data. For built-in profiles, it depends on BuiltInPermissionProfileId::as_str to produce the public id.

Call graph: called by 1 (active_permission_profile).

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

Purpose: This returns the workspace folders that were declared by the active profile itself. These roots are kept separate from temporary or turn-specific workspace roots.

Data flow: It reads the resolved profile. Legacy profiles return an empty list because they do not carry profile-defined roots. Built-in and named profiles return the stored list of absolute paths.

Call relations: PermissionProfileSnapshot and PermissionProfileState call this when higher-level permission code needs to include profile-declared workspaces in its view of allowed locations.

Call graph: called by 1 (profile_workspace_roots).

fn legacy(permission_profile: PermissionProfile) -> Self

Purpose: This creates a trusted snapshot for a permission profile that has no active profile id. It is meant for legacy data or deliberate local overrides.

Data flow: It receives a concrete PermissionProfile. It turns that into a legacy ResolvedPermissionProfile and stores it inside a snapshot. The output is a snapshot that preserves the permission rules but clears active profile metadata.

Call relations: Several configuration and session flows call this when they need to install or test permissions without associating them with a named profile. It delegates the actual legacy wrapping to ResolvedPermissionProfile::legacy.

Call graph: calls 1 internal fn (legacy); called by 4 (set_permission_profile_projection, side_fork_config_inherits_parent_thread_runtime_settings, update_feature_flags_disabling_guardian_clears_review_policy_and_restores_default, session_configured_syncs_widget_config_permissions_and_cwd).

fn active(
        permission_profile: PermissionProfile,
        active_permission_profile: ActivePermissionProfile,
    ) -> Self

Purpose: This creates a trusted snapshot for a permission profile that is known to come from an active profile id. It is the simple version used when there are no profile-declared workspace roots to carry along.

Data flow: It receives a PermissionProfile and an ActivePermissionProfile. It passes both onward with an empty workspace-root list. The result is a snapshot containing the concrete permissions and the active identity.

Call relations: Many runtime and UI flows call this after selecting or syncing a profile. It hands the work to PermissionProfileSnapshot::active_with_profile_workspace_roots so all active snapshots are built through the same path.

Call graph: called by 21 (permission_snapshot_setter_preserves_permission_constraints, apply, sync_auto_review_runtime_state_from_effective_config, try_set_builtin_active_permission_profile_on_config, handle_event, permission_settings_sync_updates_active_snapshot_without_rewriting_side_thread, profile_permissions_selection_emits_active_custom_profile, profile_permissions_selection_emits_auto_review_mode_event, profile_permissions_selection_emits_named_profile_event_only, profile_permissions_selection_popup_snapshot (+11 more)); 2 external calls (active_with_profile_workspace_roots, new).

fn active_with_profile_workspace_roots(
        permission_profile: PermissionProfile,
        active_permission_profile: ActivePermissionProfile,
        profile_workspace_roots: Vec<AbsolutePathBuf>

Purpose: This creates a trusted snapshot for an active profile and also preserves workspace folders declared by that profile. It is used when those profile roots must travel with the permission settings.

Data flow: It receives concrete permission rules, an active profile identity, and a list of absolute workspace paths. It asks ResolvedPermissionProfile::from_active_profile to classify the active id as built-in or named, then stores the resolved result inside the snapshot.

Call relations: Callers use this when applying a profile projection or when status reporting must include profile-defined workspace roots. It is the snapshot constructor that keeps identity, rules, and profile roots together.

Call graph: calls 1 internal fn (from_active_profile); called by 2 (set_permission_profile_projection, status_permissions_workspace_roots_include_profile_defined_directories).

fn from_session_snapshot(
        permission_profile: PermissionProfile,
        active_permission_profile: Option<ActivePermissionProfile>,
    ) -> Self

Purpose: This rebuilds a trusted permission snapshot from session state that already contains the concrete profile and maybe an active profile id. It avoids re-resolving the id through configuration.

Data flow: It receives a PermissionProfile and an optional ActivePermissionProfile. If an active identity is present, it creates an active snapshot. If not, it creates a legacy snapshot. It returns the reconstructed PermissionProfileSnapshot.

Call relations: Session and runtime update flows call this when applying settings captured from core session state. It chooses between PermissionProfileSnapshot::active and PermissionProfileSnapshot::legacy based on whether the session recorded an active profile.

Call graph: called by 6 (apply_permission_profile_selection, apply_runtime_policy_overrides, update_feature_flags, on_session_configured_with_display_and_fork_parent_title, apply_thread_settings, set_permission_profile_with_active_profile); 2 external calls (active, legacy).

fn permission_profile(&self) -> &PermissionProfile

Purpose: This exposes the concrete permission rules stored in a snapshot. It is useful when code needs the rules before installing or replacing the full resolved state.

Data flow: It reads the snapshot’s internal ResolvedPermissionProfile and returns a shared reference to its PermissionProfile. The snapshot itself is not changed.

Call relations: Replacement code calls this when it needs to inspect the permission profile inside a session snapshot. It delegates to ResolvedPermissionProfile::permission_profile.

Call graph: calls 1 internal fn (permission_profile); called by 1 (replace_permission_profile_from_session_snapshot).

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

Purpose: This exposes the active profile identity stored in a snapshot, if one exists. It lets callers distinguish legacy permission data from a named or built-in profile selection.

Data flow: It reads the snapshot’s resolved profile. It returns an ActivePermissionProfile for built-in or named profiles, or nothing for legacy profiles. The snapshot remains unchanged.

Call relations: This is a public-facing read method for snapshot users. It delegates to ResolvedPermissionProfile::active_permission_profile so the identity reconstruction rules stay in one place.

Call graph: calls 1 internal fn (active_permission_profile).

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

Purpose: This exposes workspace roots that were captured as part of the active profile snapshot. Callers use it when permission installation needs those roots alongside the profile rules.

Data flow: It reads the snapshot’s resolved profile and returns a shared slice of absolute paths. Legacy snapshots return an empty slice, while active built-in or named snapshots may return stored roots.

Call relations: This method is the snapshot-level doorway to ResolvedPermissionProfile::profile_workspace_roots. Higher-level permission code can use it without needing to know which resolved profile variant is inside.

Call graph: calls 1 internal fn (profile_workspace_roots).

fn into_resolved_permission_profile(self) -> ResolvedPermissionProfile

Purpose: This consumes a snapshot and extracts the resolved profile stored inside it. It is used when the snapshot is ready to be installed into mutable permission state.

Data flow: It takes ownership of the snapshot. It removes and returns the internal ResolvedPermissionProfile. After this, the original snapshot is no longer available because its contents have been moved out.

Call relations: PermissionProfileState::set_permission_profile_snapshot and replacement flows call this before setting constrained state. It is the handoff point from a portable snapshot to the live resolved-profile state.

Call graph: called by 2 (replace_permission_profile_from_session_snapshot, set_permission_profile_snapshot).

fn from_constrained_legacy(
        constrained_permission_profile: Constrained<PermissionProfile>,
    ) -> ConstraintResult<Self>

Purpose: This builds live permission-profile state from an already constrained legacy PermissionProfile. It keeps the existing safety guardrail while adding the resolved-profile wrapper.

Data flow: It receives a Constrained<PermissionProfile>, meaning a permission profile bundled with rules about what future values are allowed. It reads and clones the current profile, wraps it as legacy, and then builds constrained resolved state from it. It returns either the new PermissionProfileState or a constraint error.

Call relations: Configuration code that starts from older approval/profile settings calls this. It delegates the shared constraint setup to PermissionProfileState::from_constrained_resolved.

Call graph: calls 2 internal fn (get, legacy); called by 1 (from_approval_and_profile); 1 external calls (from_constrained_resolved).

fn from_constrained_active_profile(
        constrained_permission_profile: Constrained<PermissionProfile>,
        active_permission_profile: Option<ActivePermissionProfile>,
        profile_workspac

Purpose: This builds live permission-profile state when configuration has already resolved an active profile selection. It preserves the active profile identity and workspace roots while keeping permission constraints in force.

Data flow: It receives constrained concrete permissions, an optional active profile identity, and profile-defined workspace roots. It reads and clones the concrete profile, resolves it into legacy, built-in, or named form, and then wraps that resolved value with the same constraint rules. It returns the new state or a constraint error.

Call relations: The config loading path calls this after reading layered configuration. It uses ResolvedPermissionProfile::from_active_profile to preserve profile identity, then passes the result to PermissionProfileState::from_constrained_resolved.

Call graph: calls 2 internal fn (get, from_active_profile); called by 1 (load_config_with_layer_stack); 1 external calls (from_constrained_resolved).

fn from_constrained_resolved(
        constrained_permission_profile: Constrained<PermissionProfile>,
        resolved_permission_profile: ResolvedPermissionProfile,
    ) -> ConstraintResult<Self>

Purpose: This is the core constructor that attaches permission guardrails to a resolved profile. It ensures future replacements are checked against the original permission-profile constraint.

Data flow: It receives a constrained concrete PermissionProfile and a ResolvedPermissionProfile. It builds a new constrained wrapper around the resolved profile. The wrapper’s check looks inside any future resolved-profile candidate, pulls out its concrete PermissionProfile, and asks the original constraint whether that concrete profile is allowed. It returns PermissionProfileState if the starting value passes the check.

Call relations: Both legacy and active-profile constructors use this shared path. Replacement flows also use it when rebuilding state from a session snapshot, so all resolved profiles obey the same permission limits.

Call graph: calls 1 internal fn (new); called by 1 (replace_permission_profile_from_session_snapshot).

fn permission_profile(&self) -> &PermissionProfile

Purpose: This returns the concrete permission rules from the live constrained state. It is the normal read path for code that needs to know what permissions are currently effective.

Data flow: It reads the constrained resolved profile, then returns a shared reference to the PermissionProfile inside it. Nothing is copied or changed.

Call relations: Permission APIs and sandbox-policy code call this when they need the current permissions. It hides the legacy versus built-in versus named distinction from callers that only need the rules.

Call graph: calls 1 internal fn (get); called by 3 (permission_profile, network_sandbox_policy, permission_profile).

fn active_permission_profile(&self) -> Option<ActivePermissionProfile>

Purpose: This returns the active profile identity from live state, if there is one. It allows the rest of the system to show or send the current profile selection.

Data flow: It reads the constrained resolved profile and asks it for its active identity. The result is an ActivePermissionProfile for built-in or named profiles, or nothing for legacy state.

Call relations: Higher-level active-profile accessors call this to surface current profile metadata. It keeps those callers from needing to know the internal resolved-profile variants.

Call graph: calls 1 internal fn (get); called by 2 (active_permission_profile, active_permission_profile).

fn profile_workspace_roots(&self) -> &[AbsolutePathBuf]

Purpose: This returns workspace folders that came from the current active profile. It supports permission decisions or status views that must include those profile-declared roots.

Data flow: It reads the constrained resolved profile and returns the stored root list as a shared slice. If the live state is legacy, the returned list is empty.

Call relations: Higher-level workspace-root accessors call this when building the full set of permitted workspaces. It forwards to the resolved profile stored inside the constraint.

Call graph: calls 1 internal fn (get); called by 2 (profile_workspace_roots, profile_workspace_roots).

fn can_set_legacy_permission_profile(
        &self,
        permission_profile: &PermissionProfile,
    ) -> ConstraintResult<()>

Purpose: This checks whether a proposed legacy permission profile would be allowed by the current constraint, without actually changing anything. It is a safe “would this be accepted?” test.

Data flow: It receives a proposed PermissionProfile by reference. It clones that profile, wraps the clone as a legacy resolved profile, and asks the constrained state whether that candidate can be set. It returns success or a constraint error, and the current state remains unchanged.

Call relations: Permission-setting code calls this before applying legacy sandbox or permission profile changes. It uses ResolvedPermissionProfile::legacy so the proposed concrete profile is tested in the same shape that would later be installed.

Call graph: calls 2 internal fn (can_set, legacy); called by 2 (can_set_legacy_sandbox_policy, can_set_permission_profile); 1 external calls (clone).

fn set_legacy_permission_profile(
        &mut self,
        permission_profile: PermissionProfile,
    ) -> ConstraintResult<()>

Purpose: This replaces the live state with a new legacy permission profile, but only if the constraint allows it. It is used for old-style permission updates and tests.

Data flow: It receives a new PermissionProfile. It wraps it as a legacy resolved profile and asks the constrained wrapper to set that value. If the constraint approves, the live state changes; if not, the old state remains and an error is returned.

Call relations: Sandbox and permission setters call this when applying direct legacy-style permission changes. The constraint wrapper performs the final safety check before the new value becomes active.

Call graph: calls 2 internal fn (set, legacy); called by 3 (set_legacy_sandbox_policy, set_permission_profile, set_permission_profile_for_tests).

fn set_permission_profile_snapshot(
        &mut self,
        snapshot: PermissionProfileSnapshot,
    ) -> ConstraintResult<()>

Purpose: This replaces the live state using a trusted snapshot that may include active profile identity and profile workspace roots. It keeps the existing permission constraint active during the replacement.

Data flow: It receives a PermissionProfileSnapshot. It consumes the snapshot to extract its ResolvedPermissionProfile, then tries to set that resolved profile in the constrained state. If the concrete permissions inside the snapshot pass the constraint, the live state is updated; otherwise the update is rejected.

Call relations: Session-snapshot and projection code call this when applying a previously captured profile selection. It uses PermissionProfileSnapshot::into_resolved_permission_profile as the handoff from snapshot form into live constrained state.

Call graph: calls 2 internal fn (set, into_resolved_permission_profile); called by 2 (set_permission_profile_from_session_snapshot, set_permission_profile_projection).

fn legacy_compatible_permission_profile(
    permission_profile: &PermissionProfile,
    cwd: &Path,
) -> PermissionProfile

Purpose: This function returns a permission profile that older APIs can understand. If the given profile already fits the old format, it leaves it alone; otherwise it builds a compatible workspace-write profile that preserves writable roots and network restrictions as well as the old format allows.

Data flow: It receives a permission profile and the current working directory. First it asks the profile whether it can turn itself into the legacy sandbox policy; if yes, it simply returns a clone of the original profile. If not, it reads the file-system and network rules, gathers writable roots relative to the current directory, removes the current directory from the extra-root list, checks whether TMPDIR and /tmp are writable, and then creates a new workspace-write permission profile with those preserved settings. The output is a PermissionProfile intended to project successfully into the legacy format.

Call relations: This is called by turn_permissions_overrides when permission settings need to be prepared for compatibility. The test tests::compatibility_profile_preserves_unbridgeable_write_roots also calls it to prove that write roots not directly expressible in the original legacy conversion are still carried across. Inside, it relies on the permission model’s own helpers to inspect file-system policy, network policy, and legacy convertibility, then hands the gathered information to workspace_write_with to build the fallback profile.

Call graph: calls 5 internal fn (file_system_sandbox_policy, network_sandbox_policy, to_legacy_sandbox_policy, workspace_write_with, from_absolute_path); called by 2 (turn_permissions_overrides, compatibility_profile_preserves_unbridgeable_write_roots); 3 external calls (new, clone, var_os).

fn compatibility_profile_preserves_unbridgeable_write_roots()

Purpose: This test checks that the compatibility conversion does not throw away an extra writable directory when the original managed permission profile cannot be directly represented in the old format. It protects against a regression where older API compatibility would silently remove allowed write access.

Data flow: It builds a fake current directory, a separate writable root, and a managed permission profile that allows reading the root filesystem but writing only the extra root. It passes that profile into legacy_compatible_permission_profile, converts the result to the legacy sandbox policy, extracts the writable roots from that policy, and compares them with the expected list. The expected result contains both the extra writable root and the current working directory.

Call relations: This test exercises the fallback path in legacy_compatible_permission_profile. It sets up a permission shape that needs compatibility repair, then uses the same legacy projection method that production code depends on to confirm the repaired profile can be understood by the older policy system.

Call graph: calls 2 internal fn (legacy_compatible_permission_profile, try_from); 2 external calls (assert_eq!, vec!).

fn add_dir_warning_message(
    additional_dirs: &[PathBuf],
    permission_profile: &PermissionProfile,
    cwd: &std::path::Path,
) -> Option<String>

Purpose: Decides whether to show a warning that --add-dir folders will be ignored. It is used when startup code has already resolved the effective permission profile and needs to tell the user whether their extra writable folders can actually take effect.

Data flow: It receives a list of extra directory paths, a permission profile, and the current working directory. It first exits with no message if there are no extra directories, if permissions are disabled/full access, or if an external sandbox is responsible. Otherwise it asks the permission profile for its filesystem sandbox policy, checks whether that policy already allows broad disk writing or writing from the current workspace, and only then creates a warning string. The result is either None for “no warning needed” or Some(message) for “show this warning to the user.”

Call relations: During normal startup, run_main calls this after command-line options and permissions have been resolved. If a warning is needed, this function hands off to format_warning to build the user-facing sentence. The test tests::warns_for_read_only also calls it directly to confirm the warning behavior in a read-only sandbox.

Call graph: calls 2 internal fn (file_system_sandbox_policy, format_warning); called by 2 (warns_for_read_only, run_main); 2 external calls (is_empty, matches!).

fn format_warning(additional_dirs: &[PathBuf]) -> String

Purpose: Builds the exact warning text shown when extra directories cannot be honored. It keeps the wording in one place so the main decision function can stay focused on permission checks.

Data flow: It receives the list of directory paths. It turns each path into displayable text, joins them with commas, and inserts that list into a fixed warning sentence. The output is a single string ready to print or otherwise show to the user.

Call relations: add_dir_warning_message calls this only after it has decided that a warning is truly needed. This helper does not decide policy; it only formats the final message.

Call graph: called by 1 (add_dir_warning_message); 2 external calls (iter, format!).

fn returns_none_for_workspace_write()

Purpose: Checks that workspace-write permissions do not produce an --add-dir warning. This confirms that the normal writable-workspace mode accepts additional directories without scaring the user unnecessarily.

Data flow: The test creates a workspace-write permission profile and one example extra directory. It passes those, along with a sample current directory, into the warning check and expects the result to be None. Nothing is changed outside the test.

Call relations: This test exercises the same decision path that startup code uses through add_dir_warning_message, but in a controlled case where no warning should be returned.

Call graph: calls 1 internal fn (workspace_write); 2 external calls (assert_eq!, vec!).

fn returns_none_for_danger_full_access()

Purpose: Checks that full-access mode does not produce an --add-dir warning. In this mode the program already has broad filesystem access, so extra writable roots are not blocked by the sandbox logic.

Data flow: The test builds a Disabled permission profile, which represents the unrestricted or danger-full-access case, plus one example extra directory. It calls the warning check with a sample current directory and verifies that the answer is None.

Call relations: This test covers the branch in add_dir_warning_message that exits early for disabled permissions, matching how startup should behave when the user has chosen full access.

Call graph: 2 external calls (assert_eq!, vec!).

fn returns_none_for_external_sandbox()

Purpose: Checks that no warning is produced when an external sandbox is in charge. In that case, this code does not know enough to say whether --add-dir will work, so it stays quiet.

Data flow: The test creates an external permission profile with network sandboxing enabled and one example extra directory. It runs the warning decision and expects None, meaning no local warning text is produced.

Call relations: This test verifies the early-exit branch in add_dir_warning_message for externally managed permission setups.

Call graph: 2 external calls (assert_eq!, vec!).

fn warns_for_read_only()

Purpose: Checks that read-only permissions do produce a warning when --add-dir is supplied. This protects the user from assuming extra writable directories will work in a mode that does not allow writing.

Data flow: The test creates a read-only profile and two extra paths, one relative and one absolute. It calls add_dir_warning_message, unwraps the expected message, and compares it with the exact warning text. The output being checked is the human-readable warning string.

Call relations: This test calls add_dir_warning_message directly and verifies that, in the read-only path, the function reaches format_warning and returns the full user-facing message.

Call graph: calls 2 internal fn (read_only, add_dir_warning_message); 3 external calls (new, assert_eq!, vec!).

fn warns_when_profile_can_write_elsewhere_but_not_cwd()

Purpose: Checks a subtle case: a profile may allow writing somewhere, but not from the current workspace. The test makes sure --add-dir still gets warned about when the active workspace itself is not writable under the policy.

Data flow: The test constructs a custom managed permission profile. That profile can read the filesystem root and write to /tmp/writable, but the sample current directory is /tmp/project, which is not writable. It supplies /tmp/extra as an added directory and expects the warning message to be returned.

Call relations: This test exercises the deeper filesystem-policy checks inside add_dir_warning_message, especially the check that asks whether the policy can write using the current working directory as the workspace base.

Call graph: 2 external calls (assert_eq!, vec!).

fn returns_none_when_no_additional_dirs()

Purpose: Checks that no warning appears when the user did not provide any --add-dir entries. Even in read-only mode, there is nothing to ignore if the list is empty.

Data flow: The test creates a read-only permission profile and an empty directory list. It passes these into the warning function with a sample current directory and verifies that the result is None.

Call relations: This test covers the first early-exit branch of add_dir_warning_message, where the function returns immediately because there are no additional directories to warn about.

Call graph: calls 1 internal fn (read_only); 2 external calls (new, assert_eq!).

fn cap_sid_file(codex_home: &Path) -> PathBuf

Purpose: Builds the path to the file where capability SIDs are saved. Other code uses this single helper so everyone agrees on the same storage location.

Data flow: It receives the Codex home folder path. It appends the fixed filename cap_sid. It returns the full path where the SID data should be read from or written to.

Call relations: When sandbox setup or permission code needs saved capability IDs, it first asks this function where the storage file lives. It is used by the loading and updating functions, and also by outside permission code that needs to find the same file.

Call graph: called by 4 (apply_capability_denies_for_world_writable_for_permissions, load_or_create_cap_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path); 1 external calls (join).

fn make_random_cap_sid_string() -> String

Purpose: Creates a new random-looking Windows capability SID string. This is used when the sandbox needs a fresh permission label that is unlikely to collide with any other label.

Data flow: It starts with system-provided random seed data, generates four random numbers, and inserts them into a Windows SID-shaped string. The result is a text value like S-1-5-21-....

Call relations: The loading and lookup functions call this only when a needed SID does not already exist. After a new SID is made, those callers usually save it through persist_caps so future runs reuse the same value.

Call graph: called by 3 (load_or_create_cap_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path); 2 external calls (from_entropy, format!).

fn persist_caps(path: &Path, caps: &CapSids) -> Result<()>

Purpose: Writes the current set of capability SIDs to disk. This makes newly created permission labels survive after the program exits.

Data flow: It receives a file path and a CapSids object. It creates the parent directory if needed, turns the object into JSON text, and writes that text to the file. It returns success or an error with context about what failed.

Call relations: Whenever load_or_create_cap_sids, workspace_cap_sid_for_cwd, or writable_root_cap_sid_for_path creates or upgrades SID data, they hand the updated object to this function so the change is not lost.

Call graph: called by 3 (load_or_create_cap_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path); 4 external calls (parent, create_dir_all, write, to_string).

fn load_or_create_cap_sids(codex_home: &Path) -> Result<CapSids>

Purpose: Loads the sandbox capability SIDs from disk, or creates and saves them if they do not exist yet. It also understands an older storage format that contained only one plain SID string.

Data flow: It receives the Codex home folder, finds the cap_sid file, and checks whether it already exists. If the file contains JSON, it parses it as CapSids. If it contains an older non-empty plain string, it keeps that as the workspace SID, creates the missing newer fields, and rewrites the file as JSON. If nothing usable exists, it creates fresh workspace and read-only SIDs and saves them. It returns the complete CapSids set.

Call relations: This is the main doorway for other sandbox security setup code to get capability IDs. Workspace-specific and writable-root-specific lookup functions call it before adding more entries, and higher-level sandbox launch and permission preparation code calls it when building the security environment.

Call graph: calls 3 internal fn (cap_sid_file, make_random_cap_sid_string, persist_caps); called by 9 (apply_capability_denies_for_world_writable_for_permissions, equivalent_cwd_spellings_share_workspace_sid_key, write_roots_get_path_scoped_sids, workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path, run_windows_sandbox_capture_for_permission_profile, prepare_elevated_spawn_context_for_permissions, prepare_legacy_session_security, root_capability_sids_only_include_active_roots); 2 external calls (new, read_to_string).

fn workspace_cap_sid_for_cwd(codex_home: &Path, cwd: &Path) -> Result<String>

Purpose: Returns the capability SID for a particular workspace folder, creating it if this workspace has not been seen before. This keeps each workspace’s write permission separate from other workspaces.

Data flow: It receives the Codex home folder and the current working directory path. It loads the saved SID data, turns the directory path into a canonical key so equivalent path spellings match, and looks for an existing SID in the workspace map. If found, it returns that SID. If missing, it creates a new SID, stores it under that path key, saves the updated data, and returns the new SID.

Call relations: The root-selection helper workspace_write_cap_sid_for_root calls this when the writable root is the workspace itself. Tests call it directly to prove that differently spelled versions of the same path share one stored SID.

Call graph: calls 5 internal fn (cap_sid_file, load_or_create_cap_sids, make_random_cap_sid_string, persist_caps, canonical_path_key); called by 2 (equivalent_cwd_spellings_share_workspace_sid_key, workspace_write_cap_sid_for_root).

fn writable_root_cap_sid_for_path(codex_home: &Path, root: &Path) -> Result<String>

Purpose: Returns the capability SID for an extra writable root outside the main workspace, creating it if needed. This prevents an old extra-root permission from automatically applying to unrelated future sandbox runs.

Data flow: It receives the Codex home folder and a writable root path. It loads the saved SID data, normalizes the root path into a stable key, and checks the writable-root map. If a SID is already stored, it returns it. Otherwise it creates a new SID, inserts it for that root, saves the file, and returns the new value.

Call relations: workspace_write_cap_sid_for_root calls this whenever the allowed write root is not the workspace directory itself. The tests verify that this produces a different SID from the workspace SID and that the same extra root gets the same SID when requested again.

Call graph: calls 5 internal fn (cap_sid_file, load_or_create_cap_sids, make_random_cap_sid_string, persist_caps, canonical_path_key); called by 1 (workspace_write_cap_sid_for_root).

fn workspace_write_cap_sid_for_root(
    codex_home: &Path,
    cwd: &Path,
    root: &Path,
) -> Result<String>

Purpose: Chooses the correct capability SID for a writable root. If the root is the workspace, it uses the workspace-specific SID; if it is another allowed folder, it uses that folder’s own SID.

Data flow: It receives the Codex home folder, the workspace path, and the writable root path. It canonicalizes the workspace and root for comparison. If they refer to the same place, it returns the workspace SID. Otherwise it returns the SID scoped to the extra writable root.

Call relations: Higher-level permission-building code calls this while assembling the list of capability SIDs that should be active for a sandbox run. It delegates to workspace_cap_sid_for_cwd or writable_root_cap_sid_for_path so the right kind of isolation is used.

Call graph: calls 3 internal fn (workspace_cap_sid_for_cwd, writable_root_cap_sid_for_path, canonical_path_key); called by 4 (write_roots_get_path_scoped_sids, root_capability_sids, legacy_deny_path_includes_nested_active_root_sid, root_capability_sids_only_include_active_roots).

fn workspace_write_root_contains_path(root: &Path, path: &Path) -> bool

Purpose: Checks whether one writable root contains a given path after normalizing both paths. This helps decide whether a file or folder falls inside an allowed write area.

Data flow: It receives a root path and another path. It canonicalizes both, then checks whether the second path starts with the root path. It returns true if the path is inside that root, otherwise false.

Call relations: workspace_write_root_overlaps_path uses this helper twice, once in each direction, to decide whether two paths overlap at all.

Call graph: calls 1 internal fn (canonicalize_path); called by 1 (workspace_write_root_overlaps_path).

fn workspace_write_root_overlaps_path(root: &Path, path: &Path) -> bool

Purpose: Checks whether a writable root and another path overlap. Overlap means either the root contains the path, or the path contains the root.

Data flow: It receives two paths. It asks workspace_write_root_contains_path whether the first contains the second, then whether the second contains the first. It returns true if either check succeeds.

Call relations: This function builds on the simpler containment helper to support permission decisions where nested folders matter. For example, it can detect both “this file is under the writable root” and “this writable root is under a protected folder.”

Call graph: calls 1 internal fn (workspace_write_root_contains_path).

fn workspace_write_root_specificity(root: &Path) -> usize

Purpose: Measures how specific a writable root path is by counting how many path components it has. Deeper paths are more specific than broad parent folders.

Data flow: It receives a root path, canonicalizes it, counts the pieces of the path, and returns that count. A path like C:\work\project\src has more components than C:\work.

Call relations: This helper is intended for code that needs to compare or order writable roots by narrowness. It does not call other sandbox SID functions; it only relies on path normalization.

Call graph: calls 1 internal fn (canonicalize_path).

fn equivalent_cwd_spellings_share_workspace_sid_key()

Purpose: Tests that two different spellings of the same workspace path receive the same workspace SID. This protects against accidental duplicate permissions caused by Windows path case or slash differences.

Data flow: It creates a temporary Codex home and workspace folder. It gets the workspace’s canonical path, then creates an alternate spelling with forward slashes and uppercase letters. It asks for a workspace SID for both spellings, compares that they are equal, then reloads the saved data and checks that only one workspace entry was stored.

Call relations: This test exercises workspace_cap_sid_for_cwd and load_or_create_cap_sids. It confirms that their use of canonical path keys works as intended before higher-level sandbox code depends on those stable keys.

Call graph: calls 2 internal fn (load_or_create_cap_sids, workspace_cap_sid_for_cwd); 5 external calls (from, assert_eq!, canonicalize, create_dir_all, tempdir).

fn write_roots_get_path_scoped_sids()

Purpose: Tests that the main workspace and an extra writable root get separate capability SIDs. This ensures extra write permissions are scoped to the exact root that was allowed.

Data flow: It creates temporary Codex home, workspace, and extra-root folders. It asks workspace_write_cap_sid_for_root for the workspace SID and for the extra root SID. It checks that they are different, checks that requesting the extra-root SID directly returns the same value, and reloads the saved data to confirm one workspace entry and one extra-root entry were recorded.

Call relations: This test drives workspace_write_cap_sid_for_root, which in turn chooses between workspace and extra-root SID creation. It also calls writable_root_cap_sid_for_path and load_or_create_cap_sids to verify the saved state matches the intended split.

Call graph: calls 2 internal fn (load_or_create_cap_sids, workspace_write_cap_sid_for_root); 4 external calls (assert_eq!, assert_ne!, create_dir_all, tempdir).

fn resolve_windows_deny_read_paths(
    file_system_sandbox_policy: &FileSystemSandboxPolicy,
    cwd: &AbsolutePathBuf,
) -> Result<Vec<AbsolutePathBuf>, String>

Purpose: This is the main resolver. It takes a sandbox policy and the current working directory, then produces the concrete absolute paths that should be denied for reading on Windows.

Data flow: It starts with an empty list and a set used to avoid duplicates. Exact unreadable roots from the policy are converted into absolute paths and added immediately. Then it collects unreadable glob patterns, builds a matcher for those patterns, chooses a scan plan for each pattern, walks the existing filesystem under that plan, and returns the final list of unique absolute paths or an error message if something is invalid.

Call relations: This function is the entry point for the file’s real work. It asks the policy for exact deny-read roots and glob deny-read patterns, builds a temporary restricted policy so ReadDenyMatcher can test paths, then hands each glob scan to glob_scan_plan and collect_existing_glob_matches. The tests call it to prove that glob expansion, missing exact paths, invalid glob errors, and alias handling behave correctly.

Call graph: calls 8 internal fn (get_unreadable_globs_with_cwd, get_unreadable_roots_with_cwd, restricted, try_new, as_path, collect_existing_glob_matches, glob_scan_plan, push_absolute_path); called by 3 (aliased_glob_roots_each_preserve_their_lexical_matches, glob_patterns_expand_to_existing_matches, invalid_glob_patterns_fail_before_expansion); 2 external calls (new, new).

fn collect_existing_glob_matches(
    path: &Path,
    matcher: &ReadDenyMatcher,
    paths: &mut Vec<AbsolutePathBuf>,
    seen_paths: &mut HashSet<PathBuf>,
    seen_scan_dirs: &mut HashSet<PathBuf>

Purpose: This function walks through files and folders that already exist and adds the ones that match the deny-read glob rules. It is the filesystem scanner used after a glob pattern has been turned into a scan plan.

Data flow: It receives a starting path, a matcher, the growing output list, duplicate-tracking sets, an optional maximum depth, and the current depth. If the path does not exist, it stops. If the matcher says the path should be denied, it adds the path. If the path is a directory, it records the directory’s real location to avoid loops, checks the depth limit, reads its children, and repeats the same process for each child.

Call relations: It is called by resolve_windows_deny_read_paths for each glob pattern. When it finds a denied path, it delegates to push_absolute_path so all path cleanup and duplicate handling stays consistent. It uses ReadDenyMatcher to decide whether a visited path is actually covered by the deny-read policy.

Call graph: calls 2 internal fn (is_read_denied, push_absolute_path); called by 1 (resolve_windows_deny_read_paths); 5 external calls (exists, metadata, to_path_buf, canonicalize, read_dir).

fn push_absolute_path(
    paths: &mut Vec<AbsolutePathBuf>,
    seen: &mut HashSet<PathBuf>,
    path: PathBuf,
) -> Result<(), String>

Purpose: This helper adds one path to the result list only if it is a valid absolute path and has not already been added. It keeps the resolver’s output clean and duplicate-free.

Data flow: It receives the output list, a set of paths already seen, and a candidate path. It simplifies the path, converts it into the project’s absolute-path type, and returns an error if that conversion fails. If the absolute path is new, it appends it to the output list; otherwise it leaves the list unchanged.

Call relations: Both resolve_windows_deny_read_paths and collect_existing_glob_matches call this helper whenever they want to add a deny-read target. This means exact policy paths and glob-discovered paths go through the same validation and duplicate-removal step.

Call graph: calls 1 internal fn (from_absolute_path); called by 2 (collect_existing_glob_matches, resolve_windows_deny_read_paths); 1 external calls (simplified).

fn glob_scan_plan(pattern: &str, configured_max_depth: Option<usize>) -> GlobScanPlan

Purpose: This function decides where a glob scan should start and how deep it should go. Its job is to avoid scanning huge parts of the disk when only a smaller directory could possibly match.

Data flow: It receives a glob pattern and an optional configured depth limit. It looks for the first wildcard character, then finds the deepest literal directory before that wildcard. That directory becomes the scan root. It also passes the remaining pattern text to effective_glob_scan_max_depth to decide the depth limit, and returns both pieces as a GlobScanPlan.

Call relations: It is called by resolve_windows_deny_read_paths before each filesystem walk. It hands the resolver a practical search plan, and it relies on effective_glob_scan_max_depth for the depth calculation. The tests call it directly to check root selection and depth behavior.

Call graph: calls 1 internal fn (effective_glob_scan_max_depth); called by 1 (resolve_windows_deny_read_paths); 1 external calls (from).

fn effective_glob_scan_max_depth(
    pattern_suffix: &str,
    configured_max_depth: Option<usize>,
) -> Option<usize>

Purpose: This function calculates a safe scan depth for the part of a glob pattern that remains after the scan root. It prevents simple patterns from scanning deeper than they need to.

Data flow: It receives the pattern suffix and an optional user-configured maximum depth. It splits the suffix into path components. If the suffix contains **, meaning “match across any number of directories,” it uses the configured limit as-is. Otherwise it sets the limit to the number of remaining path components, capped by the configured maximum if one was provided.

Call relations: It is used only by glob_scan_plan. Together, they make sure the later filesystem scan searches far enough to find valid matches but not so far that a non-recursive pattern accidentally walks an entire tree.

Call graph: called by 1 (glob_scan_plan).

fn unreadable_glob_entry(pattern: String) -> FileSystemSandboxEntry

Purpose: This test helper creates a sandbox policy entry that denies reads for a glob pattern. It keeps the test setup short and clear.

Data flow: It receives a pattern string. It wraps that string as a GlobPattern, marks the access mode as deny, and returns a complete FileSystemSandboxEntry ready to put into a policy.

Call relations: The test cases call this helper when they need a deny-read glob rule. It feeds those rules into FileSystemSandboxPolicy::restricted, which is then used by the resolver or by scan-plan checks.

fn unreadable_path_entry(path: PathBuf) -> FileSystemSandboxEntry

Purpose: This test helper creates a sandbox policy entry that denies reads for one exact path. It is used to test behavior that should not depend on glob expansion.

Data flow: It receives a path buffer, converts it into the project’s absolute-path type, wraps it as an exact filesystem path, marks the access mode as deny, and returns the finished policy entry.

Call relations: The exact-missing-path test uses this helper to build a policy entry before calling the resolver. It depends on the same absolute-path validation used elsewhere in the project.

Call graph: calls 1 internal fn (from_absolute_path).

fn scan_root_uses_literal_prefix_before_glob()

Purpose: This test checks that glob scanning starts at the deepest ordinary directory before the first wildcard. That avoids unnecessarily scanning from the current directory or a whole drive.

Data flow: It supplies several glob patterns to glob_scan_plan, including Unix-style and Windows-style paths. It compares each returned root path with the expected scan root.

Call relations: The test harness runs this to protect the behavior used by resolve_windows_deny_read_paths. If this failed, glob scans could become much broader and slower than intended.

Call graph: 1 external calls (assert_eq!).

fn scan_depth_is_bounded_for_non_recursive_globs()

Purpose: This test checks that non-recursive glob patterns get a limited scan depth. A pattern like *.env should not search through every nested folder.

Data flow: It passes several patterns into glob_scan_plan and inspects the max_depth value in the returned plan. It expects shallow patterns to have small fixed limits and recursive ** patterns to be unlimited when no configured cap is present.

Call relations: This test protects the depth-planning logic that resolve_windows_deny_read_paths relies on before calling the recursive scanner.

Call graph: 1 external calls (assert_eq!).

fn configured_depth_caps_recursive_glob_scans()

Purpose: This test confirms that a configured maximum depth is respected. It matters because recursive glob scans can otherwise become expensive on large directory trees.

Data flow: It calls glob_scan_plan with patterns and a configured depth of Some(...). It then checks that recursive and non-recursive scans are capped as expected.

Call relations: The test harness uses this to verify the connection between scan planning and the policy’s glob scan depth setting. That setting is later used by resolve_windows_deny_read_paths during real resolution.

Call graph: 1 external calls (assert_eq!).

fn exact_missing_paths_are_preserved()

Purpose: This test proves that exact deny-read paths are kept even when the file does not exist yet. That is important for blocking files that may be created later.

Data flow: It creates a temporary directory, builds an absolute current working directory, chooses a missing file path, and creates a restricted policy denying that path. It calls the resolver and checks that the missing absolute path still appears in the output.

Call relations: The test calls the resolver through the same path used in production. It specifically exercises the part of resolve_windows_deny_read_paths that adds exact unreadable roots through push_absolute_path without first checking whether the file exists.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 3 external calls (new, assert_eq!, vec!).

fn glob_patterns_expand_to_existing_matches()

Purpose: This test checks that recursive glob deny rules expand to the matching files that already exist. It makes sure matching secret files are found both at the root and in nested folders.

Data flow: It creates a temporary folder, writes two .env files and one non-matching text file, builds a deny-read glob policy, and runs the resolver. It converts the result into a set and compares it with the two expected .env paths.

Call relations: This test calls resolve_windows_deny_read_paths, which then uses glob_scan_plan, ReadDenyMatcher, and collect_existing_glob_matches. It confirms that the whole glob expansion path works end to end.

Call graph: calls 3 internal fn (restricted, from_absolute_path, resolve_windows_deny_read_paths); 5 external calls (new, assert_eq!, create_dir_all, write, vec!).

fn invalid_glob_patterns_fail_before_expansion()

Purpose: This test verifies that invalid glob patterns produce a clear error instead of silently scanning or ignoring the rule. That helps catch broken sandbox policies early.

Data flow: It builds a policy containing an invalid glob range, calls the resolver, and expects an error. It checks that the error message mentions both an invalid deny-read glob pattern and the invalid range.

Call relations: This test calls resolve_windows_deny_read_paths and exercises the point where the resolver asks ReadDenyMatcher to build a matcher. If matcher construction fails, the resolver returns the error before doing filesystem expansion.

Call graph: calls 3 internal fn (restricted, from_absolute_path, resolve_windows_deny_read_paths); 3 external calls (new, assert!, vec!).

fn non_recursive_globs_do_not_expand_nested_matches()

Purpose: This test ensures that a non-recursive glob only matches files at the intended level. For example, /*.env should not also block app/.env.

Data flow: It creates one .env file at the temporary directory root and another inside a subdirectory. It builds a non-recursive deny-read glob policy, runs the resolver, and checks that only the root file is returned.

Call relations: The test protects the interaction between glob_scan_plan and collect_existing_glob_matches. If scan depth were too large, the resolver could incorrectly add nested files that the policy did not mean to deny.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 5 external calls (new, assert_eq!, create_dir_all, write, vec!).

fn aliased_glob_roots_each_preserve_their_lexical_matches()

Purpose: This Unix-only test checks that two different symbolic-link paths to the same real directory are both preserved in the output. This matters because the ACL layer may need the path form that matched the policy, not only the final real location.

Data flow: It creates a real target directory with a secret file, then creates two symbolic links pointing at that target. It builds two deny-read glob rules, one through each alias, runs the resolver, and checks that the results contain both alias-based paths.

Call relations: The test calls resolve_windows_deny_read_paths, which uses canonical directory identities only to avoid scan loops while keeping the original path spelling for matched results. This confirms that loop prevention does not erase distinct policy-facing paths.

Call graph: calls 3 internal fn (restricted, from_absolute_path, resolve_windows_deny_read_paths); 6 external calls (new, assert_eq!, create_dir_all, write, symlink, vec!).

fn token_mode_for_permission_profile(
    permission_profile: &PermissionProfile,
    workspace_roots: &[AbsolutePathBuf],
    cwd: &Path,
    env_map: &HashMap<String, String>,
) -> Result<WindowsSan

Purpose: Chooses which family of Windows restricted token is needed for a permission profile. It returns a read-only token mode when no writable roots are allowed, and a writable-roots token mode when the profile permits writing somewhere.

Data flow: It receives a permission profile, the workspace roots, the command’s current directory, and environment variables. It first resolves the profile into Windows-ready permissions, rejects full-disk write access, then checks whether any writable roots exist for the current directory. The result is either ReadOnlyCapability, WritableRootsCapability, or an error explaining why the profile cannot be enforced.

Call relations: This is the top-level decision point for token selection. It calls ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots to do the profile translation, then uses the resolved writable roots to choose the token mode. The tests call it to confirm read-only profiles, workspace-write profiles, and unsafe full-disk write profiles behave correctly.

Call graph: calls 1 internal fn (try_from_permission_profile_for_workspace_roots); called by 3 (token_mode_for_profile_with_writable_roots_uses_write_capabilities, token_mode_for_profile_without_writable_roots_uses_readonly_capability, token_mode_rejects_full_disk_write_entries); 1 external calls (bail!).

fn try_from_permission_profile(permission_profile: &PermissionProfile) -> Result<Self>

Purpose: Converts a Codex permission profile into a Windows-local permission object, but only if the profile is safe for this sandbox to enforce. It rejects disabled sandboxing and unrestricted file-system access.

Data flow: It takes a PermissionProfile. If the profile is not a managed profile, it returns an error. If the profile’s file-system policy is not restricted, it also returns an error. Otherwise, it extracts the runtime file-system and network policies and stores them in ResolvedWindowsSandboxPermissions.

Call relations: This is the basic resolver used before any Windows sandbox-specific decisions are made. It calls the protocol layer’s to_runtime_permissions method to turn the profile into concrete policies. Other code, including tests and the workspace-root-aware resolver, relies on it as the first safety gate.

Call graph: calls 1 internal fn (to_runtime_permissions); called by 3 (permission_profile_rejects_disabled_profiles, permission_profile_rejects_unrestricted_managed_filesystem, permission_profile_workspace_write_uses_windows_temp_env_vars); 2 external calls (bail!, matches!).

fn try_from_permission_profile_for_workspace_roots(
        permission_profile: &PermissionProfile,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Result<Self>

Purpose: Converts a managed permission profile into Windows-ready permissions and expands symbolic workspace-root entries into real paths. This is the version used when the sandbox knows the actual workspace folders for the current run.

Data flow: It receives a permission profile and a list of absolute workspace roots. It first calls try_from_permission_profile to validate and extract the policy. Then it replaces project-root placeholders in the file-system policy with the supplied workspace root paths. It returns the updated ResolvedWindowsSandboxPermissions or an error if the profile cannot be enforced.

Call relations: This is the main entry point used by the broader Windows sandbox setup code, including elevated setup, allow-path computation, world-writable scans, and sandbox capture. It builds on try_from_permission_profile and hands back a resolved permission object that later steps can query.

Call graph: called by 19 (run_elevated_setup, spawn_world_writable_scan, world_writable_warning_details, run_elevated_setup, compute_allow_paths, run_windows_sandbox_capture_for_permission_profile, permission_profile_workspace_root_uses_runtime_workspace_roots, permission_profile_workspace_roots_expand_all_runtime_workspace_roots, token_mode_for_permission_profile, run_setup_refresh (+9 more)); 1 external calls (try_from_permission_profile).

fn should_apply_network_block(&self) -> bool

Purpose: Answers whether the Windows sandbox should block network access. It is true when the resolved network policy says networking is not enabled.

Data flow: It reads the stored network policy from ResolvedWindowsSandboxPermissions. If that policy is disabled or restricted in a way that means network access is not enabled, it returns true; otherwise it returns false.

Call relations: This is a small query method used by sandbox setup code when deciding whether to add network-blocking rules. It delegates the meaning of “enabled” to the network policy itself.

Call graph: calls 1 internal fn (is_enabled).

fn network_policy(&self) -> NetworkSandboxPolicy

Purpose: Returns the resolved network policy stored in this Windows permission object. Callers use it when they need the exact network setting, not just a yes-or-no block decision.

Data flow: It reads the network field and returns it unchanged. Nothing else is modified.

Call relations: This method is called by from_permissions, which needs to carry the network policy forward while building another sandbox configuration object.

Call graph: called by 1 (from_permissions).

fn is_enforceable_by_windows_sandbox(&self) -> bool

Purpose: Checks whether these permissions are of the restricted file-system kind that the Windows sandbox knows how to enforce. It is a safety check before applying Windows-specific restrictions.

Data flow: It looks at the stored file-system policy kind. If it is Restricted, it returns true; otherwise it returns false.

Call relations: World-writable protection code calls this before applying capability denies. The method keeps that caller from trying to enforce a permission shape that does not fit this sandbox model.

Call graph: called by 1 (apply_capability_denies_for_world_writable_for_permissions); 1 external calls (matches!).

fn has_full_disk_read_access(&self) -> bool

Purpose: Reports whether the file-system policy allows reading the whole disk. This matters because full read access changes how the sandbox gathers readable paths.

Data flow: It asks the stored file-system policy whether full-disk read access is present. It returns that answer as a boolean and does not change any state.

Call relations: Read-root gathering code calls this while deciding whether it needs to enumerate specific readable roots or can treat the disk as broadly readable.

Call graph: calls 1 internal fn (has_full_disk_read_access); called by 1 (gather_read_roots).

fn include_platform_defaults(&self) -> bool

Purpose: Reports whether the file-system policy should include Windows platform-default readable locations. These defaults are common system paths that programs may need just to start and run normally.

Data flow: It asks the stored file-system policy whether platform defaults are included. The returned boolean tells the caller whether to add those default paths.

Call relations: Read-root gathering code calls this when assembling the final set of paths a sandboxed process can read.

Call graph: calls 1 internal fn (include_platform_defaults); called by 1 (gather_read_roots).

fn readable_roots_for_cwd(&self, cwd: &Path) -> Vec<PathBuf>

Purpose: Computes the concrete folders that should be readable for a command running from a given current directory. It turns policy entries into ordinary Windows path buffers.

Data flow: It receives the command’s current directory. It asks the file-system policy for readable roots relative to that directory, converts the project’s absolute-path wrapper into standard PathBuf values, and returns the list.

Call relations: The read-root gathering flow calls this when building the sandbox’s allow-list for read access. It relies on the lower-level file-system policy to understand current-directory-relative rules.

Call graph: calls 1 internal fn (get_readable_roots_with_cwd); called by 1 (gather_read_roots).

fn uses_write_capabilities_for_cwd(
        &self,
        cwd: &Path,
        env_map: &HashMap<String, String>,
    ) -> bool

Purpose: Answers whether a command running from this current directory needs any write capability at all. It is a convenience check used before setting up more expensive or stricter Windows write rules.

Data flow: It receives the current directory and environment variables. It calls writable_roots_for_cwd and returns true if that list is not empty, or false if there are no writable roots.

Call relations: Several sandbox setup paths call this before preparing write-capability handling, including world-writable deny logic, legacy session capability roots, and elevated spawn setup. It depends entirely on writable_roots_for_cwd for the actual path calculation.

Call graph: calls 1 internal fn (writable_roots_for_cwd); called by 3 (apply_capability_denies_for_world_writable_for_permissions, legacy_session_capability_roots, prepare_elevated_spawn_context_for_permissions).

fn writable_roots_for_cwd(
        &self,
        cwd: &Path,
        env_map: &HashMap<String, String>,
    ) -> Vec<WindowsWritableRoot>

Purpose: Computes the concrete folders the sandboxed command may write to. It also translates Codex’s temporary-directory permission into Windows TEMP and TMP paths.

Data flow: It receives the current directory and an environment map. It clones the file-system policy, removes special temporary-directory entries from the normal path calculation, asks the policy for writable roots, and converts those roots into WindowsWritableRoot values with any read-only subpaths preserved. If the original policy had a writable Tmpdir entry, it adds absolute temp paths from TEMP and TMP. The result is a list of writable Windows roots.

Call relations: This is the main write-path calculator used by allow-path computation, write-root gathering, full-read-root gathering, and uses_write_capabilities_for_cwd. It calls has_writable_tmpdir_entry to detect temp permission and windows_temp_env_roots to find the actual Windows temp directories.

Call graph: calls 2 internal fn (has_writable_tmpdir_entry, windows_temp_env_roots); called by 4 (compute_allow_paths_for_permissions, uses_write_capabilities_for_cwd, gather_full_read_roots_for_permissions, gather_write_roots_for_permissions); 1 external calls (clone).

fn has_writable_tmpdir_entry(&self) -> bool

Purpose: Checks whether the policy explicitly allows writing to the special temporary directory. This is needed because Windows temp folders come from environment variables rather than a single fixed path.

Data flow: It scans the stored file-system policy entries. If it finds a Tmpdir special path whose access mode allows writing, it returns true; otherwise it returns false.

Call relations: writable_roots_for_cwd calls this before adding TEMP and TMP paths to the writable root list. This keeps temporary-directory handling separate from ordinary path expansion.

Call graph: called by 1 (writable_roots_for_cwd).

fn windows_temp_env_roots(env_map: &HashMap<String, String>) -> Vec<PathBuf>

Purpose: Finds the actual Windows temporary directories from the TEMP and TMP environment variables. It only keeps absolute paths, because sandbox rules need complete paths rather than relative ones.

Data flow: It receives an environment-variable map. For each of TEMP and TMP, it first looks in that map, then falls back to the real process environment. It converts found values into paths, filters out relative paths, and returns the remaining absolute paths.

Call relations: writable_roots_for_cwd calls this when a profile grants writable temporary-directory access. The function provides the concrete Windows paths that stand in for Codex’s symbolic Tmpdir permission.

Call graph: called by 1 (writable_roots_for_cwd).

fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf>

Purpose: Builds a one-item workspace-root list for tests. It keeps the test setup short and makes sure the supplied path is treated as an absolute workspace root.

Data flow: It receives a path, converts it into an AbsolutePathBuf, wraps it in a vector, and returns that vector. If the path is not absolute, the test fails immediately.

Call relations: Several tests call this helper before invoking permission resolution or token-mode selection. It provides the runtime workspace roots expected by try_from_permission_profile_for_workspace_roots and token_mode_for_permission_profile.

Call graph: 1 external calls (vec!).

fn permission_profile_workspace_write_uses_windows_temp_env_vars()

Purpose: Verifies that a workspace-write profile includes the Windows temp directory from TEMP and TMP as writable roots. This protects the special Windows behavior for temporary files.

Data flow: The test creates a temporary workspace and a temporary directory, places that directory into an environment map as both TEMP and TMP, resolves a workspace-write profile, and asks for writable roots. It compares the result with the expected set: the temp directory and the canonical current workspace directory.

Call relations: This test calls ResolvedWindowsSandboxPermissions::try_from_permission_profile and then exercises writable_roots_for_cwd indirectly through the resolved permissions. It confirms the path added by windows_temp_env_roots is included.

Call graph: calls 2 internal fn (workspace_write, try_from_permission_profile); 5 external calls (new, new, assert_eq!, canonicalize, create_dir_all).

fn permission_profile_workspace_root_uses_runtime_workspace_roots()

Purpose: Verifies that a symbolic project-root permission is expanded to the actual workspace root supplied at runtime. This ensures sandbox rules follow the current session’s real workspace, not a placeholder.

Data flow: The test creates a workspace with a subdirectory as the command’s current directory. It builds a managed profile that grants write access to project roots, supplies the runtime workspace root, resolves the profile, and asks for writable roots. The result must be the canonical workspace root.

Call relations: This test calls workspace_roots_for and ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots. It focuses on the workspace-root materialization step before writable roots are calculated.

Call graph: calls 1 internal fn (try_from_permission_profile_for_workspace_roots); 6 external calls (new, new, assert_eq!, create_dir_all, vec!, workspace_roots_for).

fn permission_profile_workspace_roots_expand_all_runtime_workspace_roots()

Purpose: Verifies that project-root placeholders expand across every runtime workspace root, including subpaths and glob patterns. A glob pattern is a path-matching rule, such as “all .env files.”

Data flow: The test creates two absolute workspace roots and a profile with three entries: write each project root, deny each .git folder, and deny matching .env files. After resolving the profile with both roots, it compares the resulting file-system policy with the expected expanded entries for both roots.

Call relations: This test calls ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots. It checks that the resolver expands one symbolic policy into multiple concrete path and pattern entries.

Call graph: calls 2 internal fn (from_absolute_path, try_from_permission_profile_for_workspace_roots); 3 external calls (new, assert_eq!, vec!).

fn token_mode_for_profile_without_writable_roots_uses_readonly_capability()

Purpose: Verifies that a read-only permission profile selects the read-only Windows token mode. This confirms the sandbox does not request write powers when none are needed.

Data flow: The test creates a temporary workspace, builds a workspace-root list, and calls token_mode_for_permission_profile with a read-only profile. It expects the returned token mode to be ReadOnlyCapability.

Call relations: This test exercises the top-level token-mode decision function. It depends on writable-root calculation returning an empty list for a read-only profile.

Call graph: calls 2 internal fn (read_only, token_mode_for_permission_profile); 5 external calls (new, new, assert_eq!, create_dir_all, workspace_roots_for).

fn token_mode_for_profile_with_writable_roots_uses_write_capabilities()

Purpose: Verifies that a workspace-write profile selects the Windows token mode that supports writable roots. This confirms write permissions are reflected in the token choice.

Data flow: The test creates a temporary workspace, builds the workspace-root list, and calls token_mode_for_permission_profile with a workspace-write profile. It expects WritableRootsCapability as the result.

Call relations: This test calls the same top-level token-mode function as the read-only test, but with a profile that should produce writable roots. It proves that token selection changes when write access is present.

Call graph: calls 2 internal fn (workspace_write, token_mode_for_permission_profile); 5 external calls (new, new, assert_eq!, create_dir_all, workspace_roots_for).

fn permission_profile_rejects_disabled_profiles()

Purpose: Verifies that disabled sandbox profiles are rejected by Windows permission resolution. A disabled profile means there is no managed sandbox policy to enforce.

Data flow: The test passes PermissionProfile::Disabled into try_from_permission_profile. It expects an error and checks that the error message explains only managed profiles can be enforced.

Call relations: This test exercises the first safety gate inside ResolvedWindowsSandboxPermissions::try_from_permission_profile. It ensures callers do not accidentally treat “sandbox disabled” as a valid restricted Windows setup.

Call graph: calls 1 internal fn (try_from_permission_profile); 1 external calls (assert!).

fn permission_profile_rejects_unrestricted_managed_filesystem()

Purpose: Verifies that managed profiles with unrestricted file-system access are rejected. The Windows sandbox layer in this file only supports restricted file-system policies.

Data flow: The test builds a managed profile whose file-system permission is unrestricted and whose network policy is restricted. It passes that profile to try_from_permission_profile, expects an error, and checks that the message mentions restricted managed file-system permissions.

Call relations: This test targets the second safety gate in ResolvedWindowsSandboxPermissions::try_from_permission_profile. It makes sure unrestricted file access is not accepted as enforceable by this Windows sandbox path.

Call graph: calls 1 internal fn (try_from_permission_profile); 1 external calls (assert!).

fn token_mode_rejects_full_disk_write_entries()

Purpose: Verifies that token-mode selection rejects profiles asking for full-disk write access. This matters because the Windows sandbox code cannot safely enforce a permission that broad.

Data flow: The test creates a workspace and a managed restricted profile with write access to the root of the disk. It calls token_mode_for_permission_profile, expects an error, and checks that the error message says full-disk writes cannot be enforced.

Call relations: This test exercises the explicit full-disk-write check in token_mode_for_permission_profile. It confirms the top-level token decision fails closed instead of choosing a token for an unsafe profile.

Call graph: calls 1 internal fn (token_mode_for_permission_profile); 6 external calls (new, new, assert!, create_dir_all, vec!, workspace_roots_for).

fn compute_allow_paths_for_permissions(
    permissions: &ResolvedWindowsSandboxPermissions,
    command_cwd: &Path,
    env_map: &HashMap<String, String>,
) -> AllowDenyPaths

Purpose: Builds the concrete allow and deny path lists for a sandbox run. It answers the practical question: which existing places on disk should the command be able to write, and which existing subpaths should remain protected?

Data flow: It receives resolved permissions, the command's current working directory, and an environment-variable map. It asks the permissions object for writable roots that apply in that situation, normalizes each writable root path, keeps only paths that exist, and collects protected read-only subpaths into a separate deny set. It returns an AllowDenyPaths value containing those two sets.

Call relations: This is the production helper that other sandbox-building code relies on. It is called when building deny-write payloads, applying older session access-control rules, computing legacy capability roots, and preparing an elevated spawn context. In tests, tests::compute_allow_paths wraps it so each test can focus on a policy scenario rather than permission-resolution setup.

Call graph: calls 1 internal fn (writable_roots_for_cwd); called by 5 (compute_allow_paths, build_payload_deny_write_paths, apply_legacy_session_acl_rules, legacy_session_capability_roots, prepare_elevated_spawn_context_for_permissions); 2 external calls (new, canonicalize).

fn workspace_write_profile(
        writable_roots: &[AbsolutePathBuf],
        exclude_tmpdir_env_var: bool,
        exclude_slash_tmp: bool,
    ) -> PermissionProfile

Purpose: Creates a test permission profile that allows writing in workspace-related locations. The test can choose whether temporary directories should be excluded.

Data flow: It receives extra writable roots and two boolean choices about excluding temporary locations. It passes those choices into the protocol helper that creates a workspace-write permission profile. The result is a PermissionProfile ready for the test to resolve and use.

Call relations: Most tests call this helper before computing allow paths. It hides the noisy setup detail of creating a workspace-write profile, so the tests can read more like examples of expected sandbox behavior.

Call graph: calls 1 internal fn (workspace_write_with).

fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf>

Purpose: Turns one workspace path into the list format expected by the permission resolver. It is a small convenience helper for tests that only need one workspace root.

Data flow: It receives a filesystem path, checks and converts it into an absolute workspace path type, and wraps it in a one-item vector. The output is the workspace-root list passed into permission resolution.

Call relations: The test cases use this before calling tests::compute_allow_paths. It supplies the runtime workspace root that lets the permission resolver decide what the command's workspace is.

Call graph: 1 external calls (vec!).

fn compute_allow_paths(
        permission_profile: &PermissionProfile,
        workspace_roots: &[AbsolutePathBuf],
        command_cwd: &Path,
        env_map: &HashMap<String, String>,
    ) -> All

Purpose: Connects test-friendly permission profiles to the real allow-path computation. It lets tests start with a PermissionProfile and still exercise the production function.

Data flow: It receives a permission profile, workspace roots, the command's current directory, and an environment map. It first resolves the profile for those workspace roots, then passes the resolved permissions into compute_allow_paths_for_permissions. It returns the resulting allow and deny sets.

Call relations: All behavior-focused tests call this helper. It sits between the test setup helpers and the production function, ensuring the tests use the same permission-resolution path as real sandbox setup.

Call graph: calls 2 internal fn (compute_allow_paths_for_permissions, try_from_permission_profile_for_workspace_roots).

fn includes_additional_writable_roots()

Purpose: Checks that an explicitly added writable root is included along with the command workspace. This protects the feature where a user or policy grants write access to an extra folder.

Data flow: The test creates temporary workspace and extra-root directories, builds a workspace-write profile containing the extra root, resolves paths through tests::compute_allow_paths, and inspects the result. The expected output is that both existing directories appear in the allow set and the deny set is empty.

Call relations: The Rust test runner calls this test. Inside, it uses tests::workspace_write_profile, tests::workspace_roots_for, and tests::compute_allow_paths to drive the real compute_allow_paths_for_permissions function.

Call graph: 8 external calls (new, new, assert!, create_dir_all, vec!, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn uses_runtime_workspace_roots_for_workspace_root()

Purpose: Checks that the sandbox allows the actual runtime workspace root, not merely the command's deeper current directory. This matters when a command starts inside a subfolder but should still be allowed to write across the workspace.

Data flow: The test creates a workspace with a subdirectory as the command's current directory. It builds a profile with no extra roots, computes allow paths, and verifies that the workspace root is allowed while the subdirectory itself is not separately added as its own allow rule. The deny set should stay empty.

Call relations: The test runner invokes it as part of the allow-path test suite. It uses the shared test helpers, which in turn reach the production computation through tests::compute_allow_paths.

Call graph: 7 external calls (new, new, assert!, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn excludes_tmp_env_vars_when_requested()

Purpose: Checks that TEMP and TMP environment-variable folders are not allowed when the policy says to exclude them. This prevents accidental write access to temporary folders when that access has been deliberately turned off.

Data flow: The test creates a workspace and a temporary directory, places that temporary directory in the TEMP and TMP environment entries, and builds a profile that excludes environment temporary folders. After computing paths, it expects the workspace to be allowed, the temporary directory not to be allowed, and no denied subpaths.

Call relations: The test runner calls this test. The test uses the same helper chain as the others, ending in compute_allow_paths_for_permissions, to verify the real policy behavior.

Call graph: 7 external calls (new, new, assert!, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn includes_tmp_env_vars_when_requested()

Purpose: Checks that TEMP and TMP environment-variable folders are allowed when the policy permits them. This confirms that tools needing temporary write space can receive it.

Data flow: The test creates a workspace and a temporary directory, records the temporary directory in TEMP and TMP, and builds a profile that does not exclude those folders. It computes the allow paths and compares them to the expected set containing the workspace and temporary directory. The deny set should be empty.

Call relations: The test runner invokes it. It builds its setup through tests::workspace_write_profile and tests::workspace_roots_for, then uses tests::compute_allow_paths to exercise the production computation.

Call graph: 9 external calls (new, new, assert!, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn ignores_unix_slash_tmp_for_windows_allow_roots()

Purpose: Checks that the Unix-style /tmp rule does not add anything special on Windows. This keeps Windows sandbox rules tied to real Windows paths rather than Unix conventions.

Data flow: The test creates only a workspace directory and builds a profile where Unix /tmp would not be excluded, while environment temporary folders are excluded. After computing paths, it expects only the workspace to be allowed and no deny paths to appear.

Call relations: The Rust test runner calls this test. It uses the shared profile, workspace-root, and compute helpers to confirm the Windows-specific behavior of compute_allow_paths_for_permissions.

Call graph: 9 external calls (new, new, assert!, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn denies_git_dir_inside_writable_root()

Purpose: Checks that a .git directory inside an allowed workspace is still put into the deny set. This protects repository metadata even when the rest of the workspace is writable.

Data flow: The test creates a workspace with an actual .git directory, computes allow and deny paths, and compares the result to the expected sets. The workspace should be allowed, while the .git directory should be denied.

Call relations: The test runner invokes it. The helper path resolves the permission profile and calls compute_allow_paths_for_permissions, confirming that protected subpaths supplied by permission resolution become deny rules.

Call graph: 8 external calls (new, new, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn denies_git_file_inside_writable_root()

Purpose: Checks that a .git file, not just a .git directory, is protected inside a writable workspace. This matters for Git worktrees, where .git can be a file pointing elsewhere.

Data flow: The test creates a workspace and writes a .git file into it. It computes allow and deny paths, then expects the workspace in the allow set and the .git file in the deny set.

Call relations: The test runner calls this scenario. Through the shared helpers, it verifies that compute_allow_paths_for_permissions respects protected subpaths whether they are files or directories.

Call graph: 9 external calls (new, new, assert_eq!, canonicalize, create_dir_all, write, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn denies_codex_and_agents_inside_writable_root()

Purpose: Checks that .codex and .agents directories inside a writable workspace are still protected. These folders may contain tool or agent state that should not be freely modified by sandboxed commands.

Data flow: The test creates a workspace containing .codex and .agents directories. It computes the sandbox paths and expects the workspace to be allowed while both protected directories are returned in the deny set.

Call relations: The test runner invokes it with the same helper chain used by the other tests. It confirms that protected project metadata directories provided by permission resolution are passed through into the final deny paths.

Call graph: 8 external calls (new, new, assert_eq!, canonicalize, create_dir_all, compute_allow_paths, workspace_roots_for, workspace_write_profile).

fn skips_protected_subdirs_when_missing()

Purpose: Checks that missing protected folders are not added to the deny set. This keeps the sandbox rule list focused on paths that actually exist.