Thread and session orchestration

fn set_thread_manager_test_mode_for_tests(enabled: bool)

Purpose: Turns special thread-manager test behavior on or off. This is only meant for tests, so production code should leave it disabled.

Data flow: It receives a true-or-false value, stores that value in a shared atomic flag, and returns nothing. Afterward, constructors can read the flag and enable test-only tracking.

Call relations: Test setup code calls this before building managers through test helpers. The normal constructor later consults the companion reader to decide whether to keep an operation log for tests.

Call graph: called by 3 (set_thread_manager_test_mode, with_models_provider_for_tests, with_models_provider_home_and_state_for_tests).

fn should_use_test_thread_manager_behavior() -> bool

Purpose: Checks whether the test-only thread-manager behavior is currently enabled.

Data flow: It reads the shared atomic flag and returns a boolean. It does not change any state.

Call relations: The production and test constructors call this while building manager state, mainly to decide whether submitted operations should be captured for later inspection.

Call graph: called by 2 (new, with_models_provider_home_and_state_for_tests).

fn drop(&mut self)

Purpose: Cleans up a temporary Codex home directory when a test manager is dropped. It prevents test runs from leaving behind scratch files.

Data flow: It reads the stored path, tries to delete that whole directory tree, and ignores any deletion error. Nothing is returned because this runs automatically during cleanup.

Call relations: The test constructor installs this guard after creating a temporary home. Rust calls drop automatically when the guard goes out of scope.

Call graph: 1 external calls (remove_dir_all).

fn from(value: usize) -> Self

Purpose: Keeps older callers working by treating a plain number as “fork before this numbered user message.”

Data flow: It receives a usize number and wraps it in the ForkSnapshot::TruncateBeforeNthUserMessage option. The result is a full snapshot choice.

Call relations: Forking functions accept anything that can become a ForkSnapshot, so old fork_thread(number, ...) style calls still feed into the newer snapshot logic.

Call graph: 1 external calls (TruncateBeforeNthUserMessage).

fn build_models_manager(
    config: &Config,
    auth_manager: Arc<AuthManager>,
) -> SharedModelsManager

Purpose: Builds the shared model manager that knows which AI model presets are available for this configuration and authentication setup.

Data flow: It reads model-provider settings, Codex home, optional model catalog data, and authentication. It creates a model provider and asks it for a shared models manager.

Call relations: ThreadManager::new calls this during setup so every thread created by the manager can use the same model-listing and model-refresh service.

Call graph: called by 1 (new); 1 external calls (create_model_provider).

fn thread_store_from_config(
    config: &Config,
    state_db: Option<StateDbHandle>,
) -> Arc<dyn ThreadStore>

Purpose: Chooses the storage backend for threads based on configuration. It can use local persistent storage or an in-memory store for temporary/test-like use.

Data flow: It reads the configured thread-store mode and optional state database. For local storage it may also start a background compression worker, then returns a shared thread-store object.

Call relations: Higher-level setup code calls this before constructing a ThreadManager. The returned store is later used for resuming, forking, metadata updates, and reading saved history.

Call graph: calls 3 internal fn (for_id, new, from_config); called by 2 (build_prompt_input, tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed); 2 external calls (new, spawn_rollout_compression_worker).

fn new(
        config: &Config,
        auth_manager: Arc<AuthManager>,
        session_source: SessionSource,
        environment_manager: Arc<EnvironmentManager>,
        extensions: Arc<ExtensionR

Purpose: Creates a normal ThreadManager for real use. It wires together authentication, models, environments, skills, plugins, extensions, storage, analytics, and the live thread registry.

Data flow: It receives configuration and shared services, builds helper managers, creates a broadcast channel for new-thread notices, stores everything in shared state, and returns a ready manager.

Call relations: Application setup and many tests call this as the main constructor. Later thread-start, resume, fork, and shutdown methods all work from the state assembled here.

Call graph: calls 5 internal fn (new_with_options, new_with_restriction_product, new_with_extensions, build_models_manager, should_use_test_thread_manager_behavior); called by 17 (build_prompt_input, explicit_installation_id_skips_codex_home_file, interrupted_fork_snapshot_does_not_synthesize_turn_id_for_legacy_history, interrupted_fork_snapshot_preserves_explicit_turn_id, interrupted_fork_snapshot_uses_persisted_mid_turn_history_without_live_source, new_uses_active_provider_for_model_refresh, resume_active_thread_from_rollout_returns_running_thread, resume_and_fork_do_not_restore_thread_environments_from_rollout, resume_stopped_thread_from_rollout_preserves_thread_source, resume_stopped_thread_from_rollout_spawns_new_thread (+7 more)); 7 external calls (clone, new, new, new, bundled_skills_enabled, restriction_product, channel).

fn with_models_provider_for_tests(
        auth: CodexAuth,
        provider: ModelProviderInfo,
    ) -> Self

Purpose: Builds a thread manager for integration tests using a fake or supplied model provider and a fresh temporary Codex home.

Data flow: It enables test mode, creates a temporary directory, delegates to the test constructor that accepts an explicit home, installs a cleanup guard, and returns the manager.

Call relations: Test helper code calls this when it needs a realistic manager without touching the user’s real Codex home. The cleanup guard later removes the temporary directory.

Call graph: calls 2 internal fn (set_thread_manager_test_mode_for_tests, default_for_tests); called by 2 (thread_manager_with_models_provider, thread_manager); 5 external calls (new, with_models_provider_and_home_for_tests, format!, temp_dir, create_dir_all).

fn with_models_provider_and_home_for_tests(
        auth: CodexAuth,
        provider: ModelProviderInfo,
        codex_home: PathBuf,
        environment_manager: Arc<EnvironmentManager>,
    ) -> Se

Purpose: Builds a test manager with a supplied Codex home directory and model provider.

Data flow: It receives test authentication, provider information, a home path, and an environment manager. It forwards them to the fuller test constructor with no state database.

Call relations: Tests that need control over the filesystem location call this. It is a simpler wrapper around with_models_provider_home_and_state_for_tests.

Call graph: called by 10 (interrupted_v2_agent_is_lost_after_residency_eviction, residency_slot_reservation_unloads_oldest_idle_v2_agent, resume_agent_releases_slot_after_resume_failure, resume_agent_respects_max_threads_limit, spawn_agent_limit_shared_across_clones, spawn_agent_releases_slot_after_shutdown, spawn_agent_respects_max_threads_limit, thread_manager_with_models_provider_and_home, shutdown_all_threads_bounded_submits_shutdown_to_every_thread, start_thread_keeps_internal_threads_hidden_from_normal_lookups); 1 external calls (with_models_provider_home_and_state_for_tests).

fn with_models_provider_home_and_state_for_tests(
        auth: CodexAuth,
        provider: ModelProviderInfo,
        codex_home: PathBuf,
        environment_manager: Arc<EnvironmentManager>,

Purpose: Builds the most configurable test ThreadManager, including an optional state database. It mimics normal setup while using test authentication and local test storage.

Data flow: It enables test mode, creates an auth manager from test credentials, checks the home path, builds model, plugin, MCP, skills, and local thread-store services, and returns a manager.

Call relations: Other test constructors delegate here. Tests that need storage-state behavior call it directly.

Call graph: calls 8 internal fn (new_with_options, new_with_restriction_product, new, set_thread_manager_test_mode_for_tests, should_use_test_thread_manager_behavior, from_auth_for_testing, new, from_absolute_path_checked); called by 6 (new_with_config, list_agent_subtree_thread_ids_finds_live_descendants_of_unloaded_root, resume_agent_from_rollout_does_not_reopen_v2_descendants, resume_thread_subagent_restores_stored_nickname_and_role, thread_manager_with_models_provider_home_and_state, multi_agent_v2_interrupt_agent_accepts_unloaded_task_name_target); 10 external calls (clone, new, new, clone, new, channel, empty_extension_registry, create_model_provider, panic!, new_v4).

fn session_source(&self) -> SessionSource

Purpose: Returns the default source label used for sessions started by this manager.

Data flow: It reads the stored session source from shared state, clones it, and returns it.

Call relations: Callers use this when they need to know what kind of session this manager represents, such as exec-driven or another product mode.

fn auth_manager(&self) -> Arc<AuthManager>

Purpose: Gives callers access to the shared authentication manager.

Data flow: It clones the shared pointer to authentication state and returns it. The authentication service itself is not copied.

Call relations: Other components can call this when they need the same login or API-token context used by threads.

fn skills_manager(&self) -> Arc<SkillsManager>

Purpose: Returns the shared skills manager, which supplies bundled or configured agent skills.

Data flow: It clones and returns the shared skills-manager pointer.

Call relations: Thread configuration registration calls this so thread setup can expose the same skills service used by spawned sessions.

Call graph: called by 1 (register_thread_config).

fn plugins_manager(&self) -> Arc<PluginsManager>

Purpose: Returns the shared plugins manager, which knows about plugin availability and restrictions.

Data flow: It clones and returns the shared plugins-manager pointer.

Call relations: Thread configuration registration calls this when it needs plugin information for a thread.

Call graph: called by 1 (register_thread_config).

fn mcp_manager(&self) -> Arc<McpManager>

Purpose: Returns the shared MCP manager. MCP means Model Context Protocol, a way for tools and external servers to provide context or actions to the agent.

Data flow: It clones and returns the shared MCP-manager pointer.

Call relations: Callers use this when they need the same MCP/tool-server coordination used by thread startup.

fn environment_manager(&self) -> Arc<EnvironmentManager>

Purpose: Returns the shared environment manager, which describes where turns can run.

Data flow: It clones and returns the shared environment-manager pointer.

Call relations: Thread configuration registration and environment-selection code call this to use the manager’s known environments.

Call graph: called by 1 (register_thread_config).

fn default_environment_selections(
        &self,
        cwd: &AbsolutePathBuf,
    ) -> Vec<TurnEnvironmentSelection>

Purpose: Computes the default environments for a new turn based on the current working directory.

Data flow: It receives a working directory, reads the environment manager, and returns the default list of environment selections.

Call relations: This is a convenience wrapper around the environment-selection helper used by thread-start paths.

Call graph: calls 1 internal fn (default_thread_environment_selections).

fn validate_environment_selections(
        &self,
        environments: &[TurnEnvironmentSelection],
    ) -> CodexResult<()>

Purpose: Checks that a requested environment list is usable: no duplicate IDs and no unknown environment IDs.

Data flow: It receives a slice of environment selections, builds a set of IDs it has seen, asks the environment manager for each one, and returns success or a clear invalid-request error.

Call relations: Environment-resolution code calls this before a thread or turn uses caller-supplied environment choices.

Call graph: called by 1 (resolve_turn_environment_selections); 4 external calls (with_capacity, format!, InvalidRequest, len).

fn get_models_manager(&self) -> SharedModelsManager

Purpose: Returns the shared models manager.

Data flow: It clones the shared models-manager pointer and returns it.

Call relations: Callers use this when they need direct access to model listing or refresh behavior rather than using the small wrapper methods here.

async fn list_models(&self, refresh_strategy: RefreshStrategy) -> Vec<ModelPreset>

Purpose: Lists available model presets, optionally refreshing according to the caller’s strategy.

Data flow: It receives a refresh strategy, asks the shared models manager for model presets, waits for the result, and returns the list.

Call relations: User-facing model selection or configuration code can call this through the manager.

fn list_collaboration_modes(&self) -> Vec<CollaborationModeMask>

Purpose: Lists the collaboration modes supported by the available models.

Data flow: It asks the models manager for its collaboration-mode masks and returns them.

Call relations: Configuration or UI code can call this to know which multi-agent or collaboration options can be offered.

async fn list_thread_ids(&self) -> Vec<ThreadId>

Purpose: Lists the IDs of currently loaded, user-visible threads.

Data flow: It delegates to shared state, which reads the live thread map and filters out internal sessions. The returned value is a list of thread IDs.

Call relations: Callers use this to discover what the manager is currently tracking.

fn subscribe_thread_created(&self) -> broadcast::Receiver<ThreadId>

Purpose: Lets callers receive notifications when new threads are created.

Data flow: It creates a new receiver from the broadcast channel and returns it. Future sends on that channel will be visible to the receiver.

Call relations: Listeners subscribe here, while ThreadManagerState::notify_thread_created sends the actual notifications.

async fn get_thread(&self, thread_id: ThreadId) -> CodexResult<Arc<CodexThread>>

Purpose: Looks up a loaded thread by ID and returns it if it is user-visible.

Data flow: It receives a thread ID, delegates to shared state, and returns either the shared thread object or a not-found error.

Call relations: Operations such as subagent spawning and metadata updates call this before acting on a live thread.

Call graph: called by 3 (assert_thread_not_loaded, spawn_subagent, update_thread_metadata).

async fn update_thread_metadata(
        &self,
        thread_id: ThreadId,
        patch: ThreadMetadataPatch,
        include_archived: bool,
    ) -> CodexResult<StoredThread>

Purpose: Updates saved metadata, such as thread labels or archive state, whether the thread is currently loaded or only exists in storage.

Data flow: It receives a thread ID, metadata patch, and archive flag. If the thread is live, it routes through the live thread so writes stay ordered; otherwise it updates the store directly. It returns the updated stored thread or a mapped error.

Call relations: External callers use this single entry point instead of needing to know whether a thread is warm in memory or cold on disk.

Call graph: calls 1 internal fn (get_thread); 2 external calls (format!, InvalidRequest).

async fn list_agent_subtree_thread_ids(
        &self,
        thread_id: ThreadId,
    ) -> CodexResult<Vec<ThreadId>>

Purpose: Finds a thread and all known descendant agent threads spawned under it.

Data flow: It starts with the requested thread ID, gathers persisted descendants from the state database when available, adds live descendants from agent control, removes duplicates, and returns the list.

Call relations: This combines stored parent-child edges and currently running agent-control knowledge so callers can reason about an agent subtree even when some parts are unloaded.

Call graph: calls 1 internal fn (agent_control); 2 external calls (new, new).

async fn start_thread(&self, config: Config) -> CodexResult<NewThread>

Purpose: Starts a fresh thread with default settings and no extra dynamic tools.

Data flow: It receives a config, delegates to start_thread_with_tools with an empty tool list, waits for the new thread, and returns it.

Call relations: This is the simple public start path. It feeds into the richer start-options flow.

Call graph: calls 1 internal fn (start_thread_with_tools); called by 1 (start_thread); 2 external calls (pin, new).

async fn start_thread_with_tools(
        &self,
        config: Config,
        dynamic_tools: Vec<codex_protocol::dynamic_tools::DynamicToolSpec>,
    ) -> CodexResult<NewThread>

Purpose: Starts a fresh thread and adds caller-provided dynamic tools to it.

Data flow: It receives config and tool specs, computes default environments from the config working directory, builds StartThreadOptions, and delegates to start_thread_with_options.

Call relations: The simpler start_thread method calls this. It prepares common defaults before the full spawn path.

Call graph: calls 2 internal fn (default_thread_environment_selections, start_thread_with_options); called by 1 (start_thread); 2 external calls (pin, default).

async fn start_thread_with_options(
        &self,
        options: StartThreadOptions,
    ) -> CodexResult<NewThread>

Purpose: Starts a thread using the full set of start options.

Data flow: It receives StartThreadOptions, adds no fork-source ID, and delegates to the internal fork-aware start helper.

Call relations: start_thread_with_tools calls this for normal new threads. Subagent creation uses the fork-aware helper directly.

Call graph: calls 1 internal fn (start_thread_with_options_and_fork_source); called by 1 (start_thread_with_tools).

async fn start_thread_with_options_and_fork_source(
        &self,
        options: StartThreadOptions,
        forked_from_thread_id: Option<ThreadId>,
    ) -> CodexResult<NewThread>

Purpose: Starts a thread while optionally recording which existing thread it was forked from.

Data flow: It receives start options and an optional source thread ID, resolves session and thread source labels from explicit options or resumed history, and calls the shared spawn path.

Call relations: Normal option-based starts call it without a fork source. spawn_subagent calls it with the source thread ID after preparing forked history.

Call graph: calls 1 internal fn (agent_control); called by 2 (spawn_subagent, start_thread_with_options); 2 external calls (clone, pin).

async fn spawn_subagent(
        &self,
        forked_from_thread_id: ThreadId,
        mut options: StartThreadOptions,
    ) -> CodexResult<NewThread>

Purpose: Creates a subagent by copying a safe snapshot of another live thread’s saved history.

Data flow: It receives the source thread ID and start options, flushes the source thread’s rollout history to storage, reads that stored history, converts it to initial history, marks mid-turn history as interrupted, and starts the new thread as forked from the source.

Call relations: This method uses get_thread, stored_thread_to_initial_history, fork_history_from_snapshot, and the fork-aware start helper to turn a live parent thread into a child subagent.

Call graph: calls 5 internal fn (from_config_and_version, get_thread, start_thread_with_options_and_fork_source, fork_history_from_snapshot, stored_thread_to_initial_history).

async fn resume_thread_from_rollout(
        &self,
        config: Config,
        rollout_path: PathBuf,
        auth_manager: Arc<AuthManager>,
        parent_trace: Option<W3cTraceContext>,
    )

Purpose: Reopens a thread from a saved rollout file path. A rollout is the persisted event/history record of a thread.

Data flow: It receives config, a rollout path, authentication, and optional trace context. It loads initial history from the rollout path, then delegates to resume_thread_with_history.

Call relations: Conversation-resume code calls this when it only has a file path. The actual spawn logic happens in the history-based resume method.

Call graph: calls 2 internal fn (initial_history_from_rollout_path, resume_thread_with_history); called by 1 (resume_conversation); 1 external calls (pin).

async fn resume_thread_with_history(
        &self,
        config: Config,
        initial_history: InitialHistory,
        auth_manager: Arc<AuthManager>,
        parent_trace: Option<W3cTraceContex

Purpose: Reopens a thread from already-loaded history.

Data flow: It receives config, initial history, authentication, and trace context. It computes default environments, derives source labels from the history when present, and calls the shared spawn path.

Call relations: resume_thread_from_rollout calls this after reading storage. It eventually reaches ThreadManagerState::spawn_thread_with_source.

Call graph: calls 3 internal fn (default_thread_environment_selections, agent_control, get_resumed_session_sources); called by 1 (resume_thread_from_rollout); 3 external calls (pin, new, default).

async fn start_thread_with_user_shell_override_for_tests(
        &self,
        config: Config,
        user_shell_override: crate::shell::Shell,
    ) -> CodexResult<NewThread>

Purpose: Starts a new test thread while forcing a specific user shell.

Data flow: It receives config and a shell override, computes default environments, and calls the shared spawn path with the override included.

Call relations: Test support calls this to make shell-dependent behavior predictable.

Call graph: calls 2 internal fn (default_thread_environment_selections, agent_control); called by 1 (start_thread_with_user_shell_override); 4 external calls (clone, pin, new, default).

async fn resume_thread_from_rollout_with_user_shell_override_for_tests(
        &self,
        config: Config,
        rollout_path: PathBuf,
        auth_manager: Arc<AuthManager>,
        user_shell

Purpose: Resumes a saved rollout in tests while forcing a specific user shell.

Data flow: It loads initial history from the rollout path, computes environments, resolves resumed source labels, and calls the shared spawn path with the shell override.

Call relations: Test support uses this when it needs resume behavior plus controlled shell behavior.

Call graph: calls 3 internal fn (default_thread_environment_selections, agent_control, initial_history_from_rollout_path); called by 1 (resume_thread_from_rollout_with_user_shell_override); 3 external calls (pin, new, default).

async fn remove_thread(&self, thread_id: &ThreadId) -> Option<Arc<CodexThread>>

Purpose: Stops tracking a loaded thread in the manager’s in-memory map.

Data flow: It receives a thread ID reference, removes that entry from the map if present, and returns the shared thread object if one was removed.

Call relations: Callers use this when ownership or lifecycle control moves elsewhere. Other references to the same thread may still exist because threads are shared pointers.

async fn shutdown_all_threads_bounded(&self, timeout: Duration) -> ThreadShutdownReport

Purpose: Tries to shut down every tracked thread, but only waits a caller-specified amount of time for each one.

Data flow: It snapshots the current thread map, starts shutdown attempts concurrently, records whether each completed, failed submission, or timed out, removes completed threads from tracking, sorts the result lists, and returns a report.

Call relations: Shutdown or cleanup code calls this to close live sessions without hanging forever on a stuck thread.

Call graph: 1 external calls (default).

async fn fork_thread(
        &self,
        snapshot: S,
        config: Config,
        path: PathBuf,
        thread_source: Option<ThreadSource>,
        parent_trace: Option<W3cTraceContext>,

Purpose: Creates a new thread by reading saved history from a rollout path and applying a requested snapshot rule.

Data flow: It receives a snapshot choice, config, path, optional thread source, and trace context. It loads initial history from the path, then delegates to fork_thread_from_history.

Call relations: Public fork APIs call this when they know the rollout path rather than already having the history in memory.

Call graph: calls 2 internal fn (fork_thread_from_history, initial_history_from_rollout_path); called by 1 (fork_thread); 1 external calls (into).

async fn initial_history_from_rollout_path(
        &self,
        rollout_path: PathBuf,
    ) -> CodexResult<InitialHistory>

Purpose: Loads saved thread history from storage using a rollout path and turns it into resume-ready initial history.

Data flow: It receives a path, asks the thread store for the matching stored thread including history, maps storage errors into Codex errors, and converts the stored thread to InitialHistory.

Call relations: Resume and fork methods call this before spawning a runtime from saved data.

Call graph: calls 1 internal fn (stored_thread_to_initial_history); called by 3 (fork_thread, resume_thread_from_rollout, resume_thread_from_rollout_with_user_shell_override_for_tests); 1 external calls (clone).

async fn fork_thread_from_history(
        &self,
        snapshot: S,
        config: Config,
        history: InitialHistory,
        thread_source: Option<ThreadSource>,
        parent_trace: Optio

Purpose: Creates a fork from history that the caller has already loaded.

Data flow: It receives a snapshot rule, config, initial history, optional source label, and trace context. It converts the snapshot input and delegates to the internal fork helper.

Call relations: fork_thread calls this after loading history from storage. Other callers can use it to avoid reading storage twice.

Call graph: calls 1 internal fn (fork_thread_with_initial_history); called by 1 (fork_thread); 1 external calls (into).

async fn fork_thread_with_initial_history(
        &self,
        snapshot: ForkSnapshot,
        config: Config,
        history: InitialHistory,
        thread_source: Option<ThreadSource>,

Purpose: Applies the detailed fork rules to initial history, then starts the forked thread.

Data flow: It determines the source thread ID when possible, computes the multi-agent version to inherit or use, builds an interrupted marker if needed, rewrites history according to the snapshot mode, computes environments, and calls the shared spawn path.

Call relations: fork_thread_from_history leads here. This is where history-fork helpers connect to live thread creation.

Call graph: calls 5 internal fn (default_thread_environment_selections, from_config_and_version, agent_control, fork_history_from_snapshot, forked_from_id); called by 1 (fork_thread_from_history); 4 external calls (clone, pin, new, default).

fn agent_control(&self) -> AgentControl

Purpose: Creates an AgentControl handle that can talk back to this manager’s shared state without owning it strongly.

Data flow: It downgrades the shared state pointer to a weak reference and wraps it in AgentControl.

Call relations: Thread spawning and subtree listing call this so agents can request manager actions without creating ownership cycles.

Call graph: calls 1 internal fn (new); called by 6 (fork_thread_with_initial_history, list_agent_subtree_thread_ids, resume_thread_from_rollout_with_user_shell_override_for_tests, resume_thread_with_history, start_thread_with_options_and_fork_source, start_thread_with_user_shell_override_for_tests); 1 external calls (downgrade).

fn captured_ops(&self) -> Vec<(ThreadId, Op)>

Purpose: Returns the operations captured in test mode.

Data flow: It checks whether an operation log exists, locks it if possible, clones its contents, and returns the copied list. If no log exists, it returns an empty list.

Call relations: Tests use this to verify what operations were submitted through the manager.

fn state_db(&self) -> Option<StateDbHandle>

Purpose: Returns the optional state database handle.

Data flow: It clones the optional database handle and returns it.

Call relations: Subtree-listing code uses this to look up persisted spawn relationships when a state database is available.

async fn list_thread_ids(&self) -> Vec<ThreadId>

Purpose: Lists IDs for currently loaded, non-internal threads.

Data flow: It reads the live thread map, filters out internal session sources, collects the remaining IDs, and returns them.

Call relations: ThreadManager::list_thread_ids delegates here.

async fn list_live_thread_spawn_edges(&self) -> Vec<(ThreadId, ThreadId)>

Purpose: Lists parent-child relationships for currently loaded thread-spawn subagents.

Data flow: It reads the live thread map, skips internal sessions, finds subagent entries that record a parent thread ID, and returns pairs of parent and child IDs.

Call relations: Agent-control flows can use this to understand the live part of the agent tree.

async fn get_thread(&self, thread_id: ThreadId) -> CodexResult<Arc<CodexThread>>

Purpose: Fetches a user-visible live thread by ID or reports that it was not found.

Data flow: It reads the live thread map, checks whether the matching thread exists and is not internal, then returns a shared pointer or a not-found error.

Call relations: Operation sending, instruction inheritance, version inheritance, and rollout-trace lookup call this before using a live thread.

Call graph: called by 4 (initial_multi_agent_version_for_spawn, parent_rollout_thread_trace_for_source, send_op, user_instructions_for_spawn); 1 external calls (ThreadNotFound).

async fn read_stored_thread(
        &self,
        params: ReadThreadParams,
    ) -> CodexResult<StoredThread>

Purpose: Reads a thread from persistent storage and translates storage-layer errors into higher-level Codex errors.

Data flow: It receives read parameters, calls the configured thread store, and returns the stored thread or a clearer not-found, invalid-request, or fatal error.

Call relations: Manager-adjacent code can use this when it needs cold stored thread data through the same error conventions as live manager operations.

async fn send_op(&self, thread_id: ThreadId, op: Op) -> CodexResult<String>

Purpose: Sends an operation to a live thread. An operation is a command-like message such as submitting input or asking the thread to stop.

Data flow: It receives a thread ID and operation, looks up the thread, optionally records the operation in the test log, submits it to the thread, and returns the submit ID or an error.

Call relations: Agent-control and other manager users call this when they need to drive a specific live thread.

Call graph: calls 1 internal fn (get_thread); 1 external calls (clone).

async fn remove_thread(&self, thread_id: &ThreadId) -> Option<Arc<CodexThread>>

Purpose: Removes a thread from the live thread map by ID.

Data flow: It receives a thread ID reference, takes a write lock on the map, removes the entry if present, and returns it.

Call relations: Internal lifecycle code can call this when a thread should no longer be tracked.

async fn effective_multi_agent_version_for_spawn(
        &self,
        initial_history: &InitialHistory,
        session_source: Option<&SessionSource>,
        parent_thread_id: Option<ThreadId>,

Purpose: Chooses the multi-agent protocol version for a new spawn, falling back to the config if no history or parent provides one.

Data flow: It asks initial_multi_agent_version_for_spawn for an inherited or history-derived version. If none is found, it reads the version implied by feature flags in config.

Call relations: Fork setup uses this when it must create the right interrupted-history marker before the thread is actually spawned.

Call graph: calls 1 internal fn (initial_multi_agent_version_for_spawn).

async fn initial_multi_agent_version_for_spawn(
        &self,
        initial_history: &InitialHistory,
        session_source: Option<&SessionSource>,
        parent_thread_id: Option<ThreadId>,

Purpose: Finds the multi-agent version that should be inherited from history, a parent thread, or a fork source.

Data flow: It inspects the session source and initial history to choose a likely inherited thread ID, looks up that live thread when needed, and asks the resolver to combine history and inherited values.

Call relations: The main spawn path and the effective-version wrapper call this so child, resumed, and forked threads stay compatible with their lineage.

Call graph: calls 2 internal fn (resolve_multi_agent_version, get_thread); called by 2 (effective_multi_agent_version_for_spawn, spawn_thread_with_source).

async fn user_instructions_for_spawn(
        &self,
        session_source: &SessionSource,
        parent_thread_id: Option<ThreadId>,
        forked_from_thread_id: Option<ThreadId>,
    ) -> Loade

Purpose: Loads or inherits user instructions for a new thread. User instructions are extra guidance supplied outside the immediate prompt.

Data flow: For root agents, it asks the provider to load fresh instructions and warnings. For non-root agents, it tries to inherit instructions from the parent or fork source live thread and returns no warnings if inheritance fails.

Call relations: spawn_thread_with_source calls this before creating the Codex runtime so each thread starts with the right instruction context.

Call graph: calls 1 internal fn (get_thread); called by 1 (spawn_thread_with_source); 2 external calls (new, is_non_root_agent).

async fn spawn_new_thread(
        &self,
        config: Config,
        agent_control: AgentControl,
    ) -> CodexResult<NewThread>

Purpose: Starts a brand-new thread from config using this state’s default session source.

Data flow: It receives config and an agent-control handle, fills in default source and empty lineage fields, and delegates to spawn_new_thread_with_source.

Call relations: Internal agent-control paths can call this as the simplest state-level way to create a fresh thread.

Call graph: calls 1 internal fn (spawn_new_thread_with_source); 2 external calls (pin, clone).

async fn spawn_new_thread_with_source(
        &self,
        config: Config,
        agent_control: AgentControl,
        session_source: SessionSource,
        parent_thread_id: Option<ThreadId>,

Purpose: Starts a brand-new thread while allowing the caller to specify source, parent, fork, metrics, and inherited runtime details.

Data flow: It receives config and spawn context, computes default environments if none were supplied, sets initial history to new, and delegates to spawn_thread_with_source.

Call relations: spawn_new_thread calls this wrapper. It prepares a new-history spawn before the common spawn machinery.

Call graph: calls 1 internal fn (spawn_thread_with_source); called by 1 (spawn_new_thread); 4 external calls (clone, pin, new, default).

async fn resume_thread_with_history_with_source(
        &self,
        options: ResumeThreadWithHistoryOptions,
    ) -> CodexResult<NewThread>

Purpose: Resumes a thread from supplied history while preserving a caller-specified session source and inherited runtime details.

Data flow: It unpacks the options, computes default environments, extracts any thread-source information from the history, and delegates to the common spawn path.

Call relations: Agent-control or internal resume flows use this when resuming is tied to a parent or inherited environment policy.

Call graph: calls 2 internal fn (default_thread_environment_selections, spawn_thread_with_source); 4 external calls (clone, pin, new, default).

async fn fork_thread_with_source(
        &self,
        config: Config,
        initial_history: InitialHistory,
        agent_control: AgentControl,
        session_source: SessionSource,
        th

Purpose: Spawns a forked thread using caller-provided history and source information.

Data flow: It receives config, history, lineage IDs, optional inherited environment and execution policy, computes environments if needed, and delegates to the common spawn path.

Call relations: Internal fork flows use this to reach the same spawn code used by normal starts and resumes.

Call graph: calls 1 internal fn (spawn_thread_with_source); 4 external calls (clone, pin, new, default).

async fn spawn_thread(
        &self,
        config: Config,
        initial_history: InitialHistory,
        auth_manager: Arc<AuthManager>,
        agent_control: AgentControl,
        parent_threa

Purpose: Spawns a thread using this state’s default session source.

Data flow: It receives config, history, authentication, agent control, lineage, tools, metrics, trace, environments, extension data, and optional shell override, then forwards everything to the source-aware spawn method.

Call relations: Higher-level manager methods call this when they do not need to override the session source.

Call graph: calls 1 internal fn (spawn_thread_with_source); 2 external calls (pin, clone).

async fn spawn_thread_with_source(
        &self,
        config: Config,
        initial_history: InitialHistory,
        auth_manager: Arc<AuthManager>,
        agent_control: AgentControl,

Purpose: Creates or reuses a running Codex runtime and registers it as a managed thread. This is the central spawn path in the file.

Data flow: It receives the full spawn context. If resuming a thread that is already running with the same rollout path, it returns that live thread. Otherwise it gathers user instructions, trace context, and multi-agent version, calls Codex::spawn, then finalizes and stores the new thread.

Call relations: All start, resume, fork, and state-level spawn wrappers eventually call this. It hands the newly spawned runtime to finalize_thread_spawn.

Call graph: calls 5 internal fn (spawn, finalize_thread_spawn, initial_multi_agent_version_for_spawn, parent_rollout_thread_trace_for_source, user_instructions_for_spawn); called by 4 (fork_thread_with_source, resume_thread_with_history_with_source, spawn_new_thread_with_source, spawn_thread); 6 external calls (clone, pin, clone, format!, matches!, InvalidRequest).

async fn finalize_thread_spawn(
        &self,
        codex: Codex,
        thread_id: ThreadId,
        session_source: SessionSource,
    ) -> CodexResult<NewThread>

Purpose: Turns a freshly spawned Codex runtime into a registered CodexThread, but only if its first event is the required session-configuration event.

Data flow: It receives the runtime, thread ID, and session source, reads the next event, verifies it is SessionConfigured with the initial submit ID, inserts the new thread into the map if the ID is vacant, and returns NewThread. If the ID is already in use, it shuts down the duplicate runtime and returns an error.

Call relations: spawn_thread_with_source calls this immediately after Codex::spawn. It is the final gate before a thread becomes visible to the manager.

Call graph: calls 3 internal fn (new, next_event, shutdown_and_wait); called by 1 (spawn_thread_with_source); 4 external calls (new, format!, InvalidRequest, warn!).

fn notify_thread_created(&self, thread_id: ThreadId)

Purpose: Broadcasts that a thread was created.

Data flow: It receives a thread ID, sends it on the broadcast channel, and ignores the error that happens when no one is listening.

Call relations: Code that completes thread creation can call this; listeners created by ThreadManager::subscribe_thread_created receive the ID.

Call graph: 1 external calls (send).

async fn parent_rollout_thread_trace_for_source(
        &self,
        session_source: &SessionSource,
        initial_history: &InitialHistory,
    ) -> codex_rollout_trace::ThreadTraceContext

Purpose: Finds rollout tracing context from a parent thread for fresh thread-spawn subagents. Tracing context helps connect saved events into one replayable tree.

Data flow: It examines the session source and initial history. If this is not a fresh thread-spawn subagent, it returns disabled tracing. Otherwise it looks up the parent thread and returns its trace context, or disabled tracing if the parent is unavailable.

Call relations: spawn_thread_with_source calls this before spawning so child threads can write rollout trace data linked to their parent when appropriate.

Call graph: calls 2 internal fn (get_thread, disabled); called by 1 (spawn_thread_with_source); 1 external calls (matches!).

fn stored_thread_to_initial_history(
    stored_thread: StoredThread,
    rollout_path: Option<PathBuf>,
) -> CodexResult<InitialHistory>

Purpose: Converts a stored thread record into initial history suitable for resuming or forking.

Data flow: It receives a stored thread and optional rollout path, requires that stored history is present, and returns InitialHistory::Resumed with the thread ID, rollout items, and best rollout path.

Call relations: Rollout-path loading and subagent spawning call this after reading storage.

Call graph: called by 2 (initial_history_from_rollout_path, spawn_subagent); 1 external calls (Resumed).

fn thread_store_rollout_read_error(err: ThreadStoreError) -> CodexErr

Purpose: Translates thread-store errors from rollout-path reads into Codex-level errors.

Data flow: It receives a storage error and maps not-found, invalid-request, and all other failures into the appropriate public error shape.

Call relations: initial_history_from_rollout_path uses this so callers see consistent errors rather than raw storage details.

Call graph: 4 external calls (format!, Fatal, InvalidRequest, ThreadNotFound).

fn thread_store_metadata_update_error(thread_id: ThreadId, err: ThreadStoreError) -> CodexErr

Purpose: Translates storage errors from metadata updates into Codex-level errors.

Data flow: It receives a thread ID and storage error, maps known cases such as not found, invalid request, or unsupported operation, and wraps unexpected failures as fatal errors.

Call relations: ThreadManager::update_thread_metadata uses this for both live-thread and cold-store update failures.

Call graph: 5 external calls (format!, Fatal, InvalidRequest, ThreadNotFound, UnsupportedOperation).

fn truncate_before_nth_user_message(
    history: InitialHistory,
    n: usize,
    snapshot_state: &SnapshotTurnState,
) -> InitialHistory

Purpose: Builds fork history that stops just before a chosen user message, with special care for sources that end mid-turn.

Data flow: It receives initial history, a user-message index, and snapshot turn state. It extracts rollout items, finds user-message positions, cuts the item list at the requested place or before the active unfinished turn, and returns either new empty history or forked history.

Call relations: fork_history_from_snapshot calls this for TruncateBeforeNthUserMessage snapshots.

Call graph: calls 1 internal fn (get_rollout_items); called by 1 (fork_history_from_snapshot); 3 external calls (Forked, truncate_rollout_before_nth_user_message_from_start, user_message_positions_in_rollout).

fn snapshot_turn_state(history: &InitialHistory) -> SnapshotTurnState

Purpose: Determines whether a saved history snapshot ends in the middle of a turn and, when possible, where that active turn began.

Data flow: It receives initial history, feeds its rollout items into a history builder, checks active turn status and explicit turn IDs, and returns a small state record describing whether the snapshot is mid-turn.

Call relations: fork_history_from_snapshot calls this before deciding whether to cut history or add an interrupted boundary.

Call graph: calls 2 internal fn (new, get_rollout_items); called by 1 (fork_history_from_snapshot); 1 external calls (user_message_positions_in_rollout).

fn fork_history_from_snapshot(
    snapshot: ForkSnapshot,
    history: InitialHistory,
    interrupted_marker: InterruptedTurnHistoryMarker,
) -> InitialHistory

Purpose: Rewrites initial history according to the requested fork snapshot mode.

Data flow: It receives a snapshot mode, history, and interrupted marker. It first analyzes whether the history ends mid-turn. For truncation snapshots it cuts before a user message; for interrupted snapshots it converts resumed history to forked history and appends an interrupt boundary only when needed.

Call relations: Fork creation and subagent spawning call this so new threads start from a coherent copy of previous history.

Call graph: calls 3 internal fn (append_interrupted_boundary, snapshot_turn_state, truncate_before_nth_user_message); called by 2 (fork_thread_with_initial_history, spawn_subagent); 1 external calls (Forked).

fn append_interrupted_boundary(
    history: InitialHistory,
    turn_id: Option<String>,
    interrupted_marker: InterruptedTurnHistoryMarker,
) -> InitialHistory

Purpose: Adds the same saved “turn aborted because interrupted” boundary that the live interrupt path would write.

Data flow: It receives history, an optional turn ID, and marker settings. It optionally appends a response marker, appends a TurnAborted event, converts the result to forked history, and returns it.

Call relations: fork_history_from_snapshot calls this only after snapshot_turn_state has found that the source snapshot ends mid-turn.

Call graph: calls 1 internal fn (interrupted_turn_history_marker); called by 1 (fork_history_from_snapshot); 6 external calls (new, TurnAborted, Forked, push, EventMsg, ResponseItem).

fn default_thread_environment_selections(
    environment_manager: &EnvironmentManager,
    cwd: &AbsolutePathBuf,
) -> Vec<TurnEnvironmentSelection>

Purpose: Builds the default list of environment choices for a thread. It asks the environment manager which environment IDs should be used by default, then pairs each one with the current working directory.

Data flow: It receives an environment manager and a current directory. It reads the manager’s default environment IDs, converts the directory into a URI-style path, and returns a list of turn environment selections. It does not change the manager or the filesystem.

Call relations: Thread creation and resume paths call this when they need a sensible starting set of environments before a turn begins. It relies on the environment manager’s default_environment_ids answer, then hands the resulting selections to later resolution code.

Call graph: calls 1 internal fn (default_environment_ids); called by 7 (default_environment_selections, fork_thread_with_initial_history, resume_thread_from_rollout_with_user_shell_override_for_tests, resume_thread_with_history, start_thread_with_tools, start_thread_with_user_shell_override_for_tests, resume_thread_with_history_with_source).

fn new(
        environment_manager: Arc<EnvironmentManager>,
        local_shell: Shell,
        shell_snapshot: ShellSnapshot,
        current: TurnEnvironmentSnapshot,
    ) -> Self

Purpose: Creates the per-thread holder for environment state. It starts with an already-known snapshot, so callers can immediately ask for the current environments even before any update happens.

Data flow: It receives the shared environment manager, the local shell, a shell snapshot builder, and the current snapshot. It stores those pieces and wraps the current snapshot in a ready-made background task. The result is a ThreadEnvironments object ready to accept selection updates.

Call relations: Session setup code and tests call this to create the thread’s environment switchboard. Later, update_selections replaces the stored snapshot task when the requested environments change.

Call graph: called by 7 (latest_environment_update_wins_while_previous_resolution_is_pending, local_environment_uses_configured_shell, resolve_turn_environments, new, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, resolved_environments_for_configuration); 2 external calls (from_pointee, ready).

fn update_selections(&self, environments: &[TurnEnvironmentSelection])

Purpose: Starts resolving a new list of selected environments in the background. This lets the thread change from one set of execution places to another without blocking the caller while remote information is fetched.

Data flow: It reads the most recent completed snapshot if one is available, clones the manager, local shell, and snapshot builder, and copies the requested selections. It creates a background task that resolves those selections into a new snapshot, stores that task as the latest one, and spawns the work. The visible state changes because future calls to snapshot will wait for this newly stored task.

Call relations: Callers use this after they receive or compute new environment selections. It hands the real resolving work to ThreadEnvironments::resolve_snapshot. Because it stores the new task before the spawned work finishes, the latest update wins if an older remote resolution is still pending.

Call graph: 9 external calls (clone, new, load, store, resolve_snapshot, clone, clone, to_vec, spawn).

async fn resolve_snapshot(
        environment_manager: Arc<EnvironmentManager>,
        local_shell: Shell,
        shell_snapshot: ShellSnapshot,
        current: TurnEnvironmentSnapshot,
        en

Purpose: Turns a list of requested environment selections into a clean snapshot of usable turn environments. It removes duplicate environment IDs, reuses existing resolved environments when possible, and skips entries that cannot be resolved.

Data flow: It receives the manager, local shell, shell snapshot builder, the current snapshot, and the new selections. For each selection, it checks whether that environment ID has already appeared; if so, it ignores the later duplicate. If the current snapshot already contains the same environment ID and working directory, it reuses that environment. Otherwise it calls resolve_selection. It returns a new TurnEnvironmentSnapshot containing only successfully resolved environments.

Call relations: update_selections launches this as the background resolver. When it needs to create a fresh environment, it delegates to ThreadEnvironments::resolve_selection; when that fails, it logs a warning and continues with the remaining selections.

Call graph: 4 external calls (with_capacity, resolve_selection, with_capacity, warn!).

async fn resolve_selection(
        environment_manager: &EnvironmentManager,
        local_shell: &Shell,
        shell_snapshot: &ShellSnapshot,
        selected_environment: &TurnEnvironmentSelecti

Purpose: Resolves one selected environment into a TurnEnvironment, which is the ready-to-use form used during a conversation turn. It finds the environment, chooses the right shell, and starts preparing a shell snapshot for it.

Data flow: It receives the environment manager, local shell, shell snapshot builder, and one selection. It looks up the selected environment ID. If the environment is remote, it asks that environment for shell information and converts it into the project’s Shell type; if the environment is local, it clones the configured local shell. It creates a TurnEnvironment, starts a background task to build its shell snapshot, stores that task on the environment, and returns the completed turn environment or an error.

Call relations: resolve_snapshot calls this whenever it cannot reuse an existing resolved environment. It talks to EnvironmentManager::get_environment, may call remote environment info APIs, creates the TurnEnvironment, and starts the shell snapshot builder so later command execution can use that prepared shell state.

Call graph: calls 3 internal fn (new, from_environment_shell_info, get_environment); 4 external calls (clone, clone, spawn, warn!).

async fn snapshot(&self) -> TurnEnvironmentSnapshot

Purpose: Returns the latest resolved environment snapshot, waiting if the latest update is still being prepared. This gives callers a simple way to ask, “what environments should this turn use now?”

Data flow: It reads the currently stored shared snapshot task and awaits its result. The output is a TurnEnvironmentSnapshot. It does not start new work or change the stored selection.

Call relations: Code that needs to execute a turn calls this after selections have been updated. It depends on whatever task was most recently stored by new or update_selections.

Call graph: 1 external calls (load_full).

fn environment_manager(&self) -> Arc<EnvironmentManager>

Purpose: Returns a shared reference to the environment manager kept by this thread. Callers use it when they need the same environment registry that the thread uses.

Data flow: It reads the stored shared manager and clones the shared pointer. The returned value points to the same manager; no environment data is copied or changed.

Call relations: This is a small accessor for other parts of the session flow that need to reach the environment manager through ThreadEnvironments.

Call graph: 1 external calls (clone).

fn primary(&self) -> Option<&TurnEnvironment>

Purpose: Returns the first environment in the snapshot, if there is one. The first environment is treated as the primary place for actions that need a main execution target.

Data flow: It reads the snapshot’s environment list and returns a reference to the first item, or nothing if the list is empty. It does not change the snapshot.

Call relations: Other helper methods, such as primary_environment and primary_filesystem, build on this. The ordering is set earlier by resolve_snapshot, which preserves the first non-duplicate selection as primary.

Call graph: called by 2 (primary_environment, primary_filesystem).

fn local(&self) -> Option<&TurnEnvironment>

Purpose: Finds the first local environment in the snapshot. This is useful when a caller specifically needs something running on the user’s machine rather than a remote executor.

Data flow: It scans the snapshot’s environment list and checks each environment to see whether it is not remote. It returns a reference to the first local match, or nothing if all environments are remote or the list is empty.

Call relations: This helper is available to code that needs local-environment behavior. It depends on each environment’s is_remote answer to separate local from remote.

fn primary_environment(&self) -> Option<Arc<codex_exec_server::Environment>>

Purpose: In tests, returns the underlying environment object for the primary turn environment. It lets tests compare or inspect the actual shared environment behind the wrapper.

Data flow: It asks primary for the first turn environment. If one exists, it clones the shared pointer to that environment and returns it. The environment itself is not duplicated or changed.

Call relations: This test-only helper builds directly on TurnEnvironmentSnapshot::primary. It exists to make assertions about the primary environment easier.

Call graph: calls 1 internal fn (primary).

fn to_selections(&self) -> Vec<TurnEnvironmentSelection>

Purpose: Converts the resolved snapshot back into the simple selection form. This is useful for comparing, storing, or reporting what environments the snapshot represents.

Data flow: It reads each TurnEnvironment in the snapshot and asks it for its selection form. It returns a list of TurnEnvironmentSelection values in the same order as the snapshot.

Call relations: Tests use this to check that resolution kept or skipped the expected selections. It also acts as the reverse of the selection-to-snapshot flow performed by resolve_snapshot.

fn primary_filesystem(&self) -> Option<Arc<dyn ExecutorFileSystem>>

Purpose: Returns the filesystem for the primary environment, if there is one. This lets other parts of the program read files through the correct environment, whether local or remote.

Data flow: It asks primary for the first turn environment. If found, it asks that environment for its filesystem interface and returns it as a shared object. If there is no primary environment, it returns nothing.

Call relations: Plugin and skill warmup code calls this during session initialization so it can read from the same filesystem as the primary execution environment.

Call graph: calls 1 internal fn (primary); called by 1 (warm_plugins_and_skills_for_session_init).

fn single_local_environment(&self) -> Option<&TurnEnvironment>

Purpose: Returns the environment only when the snapshot contains exactly one environment and that environment is local. This avoids guessing when there are multiple possible places to run commands.

Data flow: It checks the snapshot’s list. If the list has exactly one item and that item is not remote, it returns a reference to it. Otherwise it returns nothing.

Call relations: single_local_environment_cwd calls this before converting the environment’s working directory into a local filesystem path. It protects callers from accidentally treating a remote or multi-environment setup as a simple local-only setup.

Call graph: called by 1 (single_local_environment_cwd).

fn single_local_environment_cwd(&self) -> Option<AbsolutePathBuf>

Purpose: Returns the local working directory only for the simple case of exactly one local environment. It exists as a compatibility bridge for code that still expects a normal absolute path instead of a URI-style path.

Data flow: It first asks single_local_environment for a safe local-only environment. If one exists, it converts that environment’s working directory from a path URI into an absolute path and returns it if the conversion succeeds. Otherwise it returns nothing.

Call relations: This builds on single_local_environment to avoid unsafe assumptions. The comment notes that it should eventually disappear once callers can use PathUri directly.

Call graph: calls 1 internal fn (single_local_environment).

async fn resolve_turn_environments(
        environment_manager: Arc<EnvironmentManager>,
        selections: &[TurnEnvironmentSelection],
    ) -> Arc<ThreadEnvironments>

Purpose: Test helper that creates a ThreadEnvironments, applies selections, waits for resolution, and returns the ready object. It keeps individual tests focused on what they are checking rather than on setup steps.

Data flow: It receives an environment manager and a slice of selections. It creates a thread environment holder with the default user shell, disabled shell snapshots, and an empty starting snapshot. It updates the selections, waits for the snapshot to finish resolving, and returns the shared holder.

Call relations: Several tests call this when they need resolved environments. It uses ThreadEnvironments::new, then exercises the same update_selections and snapshot path used by real code.

Call graph: calls 3 internal fn (new, default_user_shell, disabled); 2 external calls (new, default).

fn test_runtime_paths() -> ExecServerRuntimePaths

Purpose: Test helper that builds runtime path information needed by test environment managers. Runtime paths tell the execution server where the current executable is and, optionally, where sandbox tools are.

Data flow: It reads the path of the currently running test executable and passes it into ExecServerRuntimePaths::new with no Linux sandbox executable. It returns the resulting runtime path object, or fails the test if the paths cannot be built.

Call relations: Tests that create remote-capable environment managers call this so those managers have the path information they require.

Call graph: calls 1 internal fn (new); 1 external calls (current_exe).

async fn default_thread_environment_selections_use_manager_default_id()

Purpose: Checks that default environment selections follow the environment manager’s default ID. In this setup, the manager prefers the remote environment.

Data flow: The test gets the current directory, converts it to a path URI, creates a test environment manager with a remote URL, and calls default_thread_environment_selections. It compares the result with the expected single remote selection.

Call relations: This test verifies the public helper default_thread_environment_selections and uses test_runtime_paths to create the manager setup.

Call graph: calls 3 internal fn (create_for_tests, current_dir, from_abs_path); 2 external calls (assert_eq!, test_runtime_paths).

async fn toml_default_thread_environment_selections_include_local_and_remote()

Purpose: Checks that a configuration file can make the default selections include both local and remote environments. This protects the behavior where configured environments expand the default list.

Data flow: The test creates a temporary configuration directory, writes an environments.toml file defining a remote environment, gets the current directory as a path URI, and loads an environment manager from that config. It then checks that the default selections are local first and remote second.

Call relations: This test exercises default_thread_environment_selections through a manager loaded from configuration, using test_runtime_paths for required runtime path setup.

Call graph: calls 3 internal fn (from_codex_home, current_dir, from_abs_path); 4 external calls (assert_eq!, test_runtime_paths, write, tempdir).

async fn default_thread_environment_selections_empty_when_default_disabled()

Purpose: Checks that no default selections are produced when the environment manager has no environments enabled. This makes sure disabled defaults stay disabled.

Data flow: The test gets the current directory, creates an environment manager with no environments, calls default_thread_environment_selections, and expects an empty list.

Call relations: This directly verifies the empty-default branch of default_thread_environment_selections.

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

async fn local_environment_uses_configured_shell()

Purpose: Checks that local environments use the shell configured for the thread. This matters because local command behavior depends on using the user’s intended shell.

Data flow: The test creates a custom local shell, builds ThreadEnvironments with that shell, selects the local environment, waits for a snapshot, and inspects the primary environment’s shell. It expects the shell to match the configured one.

Call relations: This test goes through ThreadEnvironments::new, update_selections, and snapshot, and specifically confirms the local branch inside resolve_selection.

Call graph: calls 5 internal fn (new, disabled, default_for_tests, current_dir, from_abs_path); 4 external calls (new, assert_eq!, default, from).

async fn resolve_environment_selections_keeps_first_duplicate_id()

Purpose: Checks that if the same environment ID appears more than once, the first one wins. This avoids ambiguity when two selections name the same environment with different working directories.

Data flow: The test creates two selections with the same local environment ID but different working directories. It resolves them and converts the snapshot back to selections. The result should contain only the first selection.

Call relations: This test uses tests::resolve_turn_environments to exercise resolve_snapshot, especially its duplicate-ID filtering.

Call graph: calls 3 internal fn (default_for_tests, current_dir, from_abs_path); 3 external calls (new, assert_eq!, resolve_turn_environments).

async fn resolved_environment_selections_use_first_selection_as_primary()

Purpose: Checks that the first resolved selection becomes the primary environment. It also confirms that the shell for that environment is resolved from environment information.

Data flow: The test creates a local selection with a chosen working directory, resolves it, and then inspects the snapshot. It expects the primary environment ID and shell to match the selected local environment and the manager’s shell info.

Call relations: This test uses tests::resolve_turn_environments and verifies behavior from resolve_snapshot, resolve_selection, and TurnEnvironmentSnapshot::primary.

Call graph: calls 3 internal fn (default_for_tests, current_dir, from_abs_path); 4 external calls (clone, new, assert_eq!, resolve_turn_environments).

async fn unresolved_environment_selections_are_skipped()

Purpose: Checks that missing or invalid environment selections do not stop all resolution. Instead, unresolved selections are skipped and valid later selections remain available.

Data flow: The test asks for a missing environment first and a valid local environment second. After resolution, it converts the snapshot back to selections and expects only the valid local selection.

Call relations: This test exercises the error path in resolve_selection and the warning-and-continue behavior in resolve_snapshot.

Call graph: calls 3 internal fn (default_for_tests, current_dir, from_abs_path); 3 external calls (new, assert_eq!, resolve_turn_environments).

async fn latest_environment_update_wins_while_previous_resolution_is_pending()

Purpose: Checks that a newer environment update can replace an older one that is still waiting on remote work. This prevents the thread from getting stuck behind an outdated remote selection.

Data flow: The test starts a fake remote listener, creates a manager with both remote and local environments, and first selects the remote environment. It waits until remote resolution has begun, then updates the selections to local only. It waits for the snapshot and expects the local selection to be the final result.

Call relations: This test stresses ThreadEnvironments::update_selections. It confirms that storing the newest snapshot task lets snapshot follow the latest update rather than an older pending remote resolution.

Call graph: calls 6 internal fn (new, default_user_shell, disabled, create_for_tests_with_local, current_dir, from_abs_path); 9 external calls (new, assert_eq!, default, test_runtime_paths, format!, from_ref, from_secs, bind, timeout).

async fn matching_environment_id_and_cwd_reuse_resolved_environment()

Purpose: Checks that an already-resolved environment is reused when both its environment ID and working directory still match. It also checks that changing the working directory forces a fresh resolution.

Data flow: The test resolves a remote selection, then changes the manager’s remote URL. It applies the same selection again and checks that the underlying environment pointer is the same as before. Then it applies a selection with a changed working directory and checks that the underlying environment pointer is different.

Call relations: This test verifies the reuse shortcut inside resolve_snapshot. It protects the intended behavior that stable selections keep their resolved environment, while meaningful changes are re-resolved.

Call graph: calls 3 internal fn (create_for_tests, current_dir, from_abs_path); 6 external calls (clone, new, assert!, resolve_turn_environments, test_runtime_paths, from_ref).

async fn single_local_environment_cwd_requires_exactly_one_local_environment()

Purpose: Checks that a local working directory is returned only when the snapshot contains exactly one environment and that environment is local. This prevents remote or mixed setups from being mistaken for a simple local path.

Data flow: The test builds three snapshots: one with only a local environment, one with only a remote environment, and one with both. It asks each for single_local_environment_cwd. Only the local-only snapshot should return the current directory.

Call relations: This test verifies TurnEnvironmentSnapshot::single_local_environment_cwd and, through it, single_local_environment.

Call graph: calls 4 internal fn (create_for_tests, default_for_tests, current_dir, from_abs_path); 5 external calls (clone, new, assert_eq!, resolve_turn_environments, vec!).

fn new(reason: TryStartTurnIfIdleRejectionReason, input: Vec<ResponseItem>) -> Self

Purpose: Builds an error value for the case where automatic idle work was not allowed to start. It keeps both the reason and the original model-visible input so the caller does not lose anything.

Data flow: It receives a rejection reason and the response items that someone wanted to submit. It stores both inside a new error object. The result is an error that can be returned unchanged to the caller.

Call relations: The idle-turn path uses this when it decides a thread is not eligible for automatic work. Later, callers can inspect the returned object to decide whether to retry, log, or discard the original input.

Call graph: called by 1 (try_start_turn_if_idle).

fn reason(&self) -> TryStartTurnIfIdleRejectionReason

Purpose: Returns the stable reason why an automatic idle turn was rejected. This lets callers react differently to cases like “busy” versus “plan mode.”

Data flow: It reads the stored reason from the error object. It does not change anything. It returns that reason to the caller.

Call relations: This is used after an idle-turn attempt fails, when the caller wants to understand the rejection without unpacking the whole error.

fn into_input(self) -> Vec<ResponseItem>

Purpose: Gives back the original input that failed to start an automatic idle turn. This prevents hidden data loss when background work is rejected.

Data flow: It consumes the error object, takes out the saved response items, and returns them. After this, the error object itself is gone.

Call relations: A caller that receives this error can call this method when it wants to retry the same model-visible items later or log exactly what was not submitted.

fn cwd(&self) -> &AbsolutePathBuf

Purpose: Returns the thread’s current working directory, which is the default folder used when commands or file operations need a location. The current working directory is like the folder a terminal is “standing in.”

Data flow: It reads the legacy fallback current-directory field from the snapshot’s environment selections. It returns a borrowed path and does not change the snapshot.

Call relations: Code that rebuilds or compares thread settings calls this when it needs the thread’s directory. ThreadConfigSnapshot::sandbox_policy also uses it to calculate the correct sandbox behavior.

Call graph: called by 4 (build_thread_from_snapshot, collect_resume_override_mismatches, thread_settings_from_config_snapshot, sandbox_policy).

fn environment_selections(&self) -> &[TurnEnvironmentSelection]

Purpose: Returns the list of selected environments available to the thread. These selections describe where turns may run, such as different workspaces or execution contexts.

Data flow: It reads the environments stored in the snapshot and returns them as a borrowed list. Nothing is copied or changed.

Call relations: This is a simple accessor for callers that need to inspect the environment choices already captured in a thread configuration snapshot.

fn sandbox_policy(&self) -> SandboxPolicy

Purpose: Calculates the sandbox policy for this snapshot. A sandbox policy is the safety rule set that limits what code or commands may touch.

Data flow: It reads the snapshot’s permission profile and current working directory. It passes those to the sandbox compatibility helper, which returns the policy that should be applied. The snapshot itself is unchanged.

Call relations: Resume and settings-comparison code calls this when it needs to see whether sandbox-related behavior matches expectations. It depends on ThreadConfigSnapshot::cwd to supply the folder used in that calculation.

Call graph: calls 1 internal fn (cwd); called by 1 (collect_resume_override_mismatches); 1 external calls (compatibility_sandbox_policy_for_permission_profile).

fn new(
        codex: Codex,
        session_configured: SessionConfiguredEvent,
        rollout_path: Option<PathBuf>,
        session_source: SessionSource,
    ) -> Self

Purpose: Creates a new CodexThread wrapper around an already-created Codex session. This gives the rest of the app a thread-shaped handle instead of exposing all inner session details.

Data flow: It receives the inner Codex object, the session configuration event, an optional rollout file path, and the session source. It stores them and starts the out-of-band elicitation counter at zero. The result is a ready-to-use CodexThread.

Call relations: Thread-spawning code calls this near the end of creating a thread. After that, other parts of the system use the returned object for submissions, events, configuration reads, and lifecycle actions.

Call graph: called by 1 (finalize_thread_spawn); 1 external calls (new).

async fn submit(&self, op: Op) -> CodexResult<String>

Purpose: Submits a general operation to the thread. An operation is a command-like message telling the session to do something, such as accept input or update settings.

Data flow: It receives an operation and forwards it to the inner Codex object. The inner session processes or queues it and returns a submission id or an error. This method returns that result unchanged.

Call relations: Many app-server and turn-running paths use this as the common doorway for sending operations into the thread. It hands the work off to Codex::submit.

Call graph: calls 1 internal fn (submit); called by 8 (submit_thread_settings, close_realtime_conversation, start_realtime_conversation, capture_from_requests, submit_user_input, submit_queue_only_agent_mail, submit_user_input, run_turn).

fn session_telemetry(&self) -> SessionTelemetry

Purpose: Returns the telemetry handle for this thread. Telemetry is production measurement data, such as timing and usage signals, used to understand system behavior.

Data flow: It reads the telemetry handle from the session services and clones it. The clone is returned so callers can record thread-scoped measurements.

Call relations: Instrumentation code can call this when it needs to attach measurements to the current thread without getting broad access to the whole session.

async fn shutdown_and_wait(&self) -> CodexResult<()>

Purpose: Asks the thread to shut down and waits until that shutdown work completes. This is used for clean teardown rather than abruptly dropping a running session.

Data flow: It forwards the shutdown request to the inner Codex object. The inner object stops the session loop and returns success or an error. This method returns that result.

Call relations: Teardown paths call this when they are done with a thread. It hands the actual shutdown sequence to Codex::shutdown_and_wait.

Call graph: calls 1 internal fn (shutdown_and_wait).

async fn wait_until_terminated(&self)

Purpose: Waits until the underlying session loop has fully ended. This is useful when something else has already requested shutdown and the caller only needs to wait.

Data flow: It waits on the stored termination signal for the session loop. It does not send any new operation and returns nothing when the signal completes.

Call relations: Agent-loop code calls this while monitoring a running thread, so it can stop only after the session has truly terminated.

Call graph: called by 1 (loop_agent).

async fn emit_thread_resume_lifecycle(&self)

Purpose: Notifies extensions that this thread has resumed. Extensions are add-on components, and this gives them a chance to restore or update their own thread-related state.

Data flow: It asks the extension registry for thread lifecycle contributors. For each contributor, it passes session-level and thread-level extension data stores to on_thread_resume. It waits for each notification to finish.

Call relations: Resume orchestration uses this after a thread is brought back. The method fans the event out to all registered extension lifecycle contributors.

async fn emit_thread_idle_lifecycle_if_idle(&self)

Purpose: Triggers idle lifecycle work only if the session is actually idle. This lets extensions run background follow-up work without interrupting active user work.

Data flow: It asks the session to check its idle state and emit the idle lifecycle event if allowed. It returns after the session-level logic has completed.

Call relations: Resume-continuation code calls this after restoring goal state, so extensions can react if the resumed thread has no active work waiting.

Call graph: called by 1 (emit_resume_goal_snapshot_and_continue).

async fn ensure_rollout_materialized(&self)

Purpose: Makes sure the thread’s rollout record exists on disk or in its backing storage. A rollout is the persisted log of what happened in the session.

Data flow: It delegates to the session to create or materialize the rollout if needed. It does not return data.

Call relations: Hidden internal callers can use this before operations that assume the rollout record has been created.

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

Purpose: Forces pending rollout data to be written out. This reduces the chance that recent conversation state is still only in memory.

Data flow: It asks the session to flush its rollout data. The result is either success or an input/output error from the write operation.

Call relations: Internal persistence-sensitive code can call this when it needs the rollout log to be up to date before continuing.

async fn submit_with_trace(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
    ) -> CodexResult<String>

Purpose: Submits an operation while carrying optional tracing information. Tracing information helps connect work across services for debugging and monitoring.

Data flow: It receives an operation and an optional W3C trace context, then forwards both to the inner Codex object. The result is the submission id or an error.

Call relations: Core operation submission paths use this when they want normal thread submission plus cross-service trace tracking. It hands off to Codex::submit_with_trace.

Call graph: calls 1 internal fn (submit_with_trace); called by 2 (submit_core_op, submit_core_op).

async fn submit_user_input_with_client_user_message_id(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
        client_user_message_id: Option<String>,
    ) -> CodexResult<Stri

Purpose: Submits user input while preserving an optional client-provided message id. Before doing so, it checks that the agent has room to accept the operation.

Data flow: It receives an operation, optional trace context, and optional client message id. It first asks agent control to ensure execution capacity for this thread and operation. If allowed, it forwards the submission to the inner Codex; otherwise it returns the capacity error.

Call relations: Client-facing user-input paths use this when they need both safety checks and message-id tracking. It performs the thread-level guard, then hands off to the inner submission method.

Call graph: calls 1 internal fn (submit_user_input_with_client_user_message_id).

async fn set_thread_memory_mode(&self, mode: ThreadMemoryMode) -> anyhow::Result<()>

Purpose: Records whether this thread may be used for future memory generation. In plain terms, it marks whether the conversation is eligible to teach the system something later.

Data flow: It receives the desired memory mode and passes it to the inner Codex object. The result is success or an error from persisting that choice.

Call relations: Settings or policy flows call this when the thread’s memory eligibility changes. The actual storage update is done by the lower-level Codex session.

Call graph: calls 1 internal fn (set_thread_memory_mode).

async fn steer_input(
        &self,
        input: Vec<UserInput>,
        additional_context: BTreeMap<String, AdditionalContextEntry>,
        expected_turn_id: Option<&str>,
        client_user_me

Purpose: Adds steering input to an existing turn, meaning extra user guidance or context meant to influence ongoing model work. It can also check that the input applies to the expected turn.

Data flow: It receives user input, additional context, an optional expected turn id, an optional client message id, and optional client metadata. It forwards these to the inner Codex steering logic, which returns a result id or a steering error.

Call relations: The user-input steering path calls this when a client wants to nudge an active turn rather than start a completely separate one.

Call graph: calls 1 internal fn (steer_input); called by 1 (steer_user_input).

async fn inject_if_running(
        &self,
        items: Vec<ResponseItem>,
    ) -> Result<(), Vec<ResponseItem>>

Purpose: Injects model-visible response items into the currently active turn, but only if a turn is running. If no turn is active, it gives the items back unchanged.

Data flow: It receives response items and passes them to the session’s running-turn injection point. On success, the items are absorbed into the active turn. On failure, the same items are returned to the caller.

Call relations: Callers that only hold a CodexThread use this as a safe bridge into active-turn injection without receiving wider session mutation powers.

async fn try_start_turn_if_idle(
        &self,
        items: Vec<ResponseItem>,
    ) -> Result<(), TryStartTurnIfIdleError>

Purpose: Starts automatic background model work only when the thread is idle and policy allows it. This protects user-triggered work from being overtaken by extension-triggered work.

Data flow: It receives model-visible response items and asks the session to start a turn only if no client turn is queued, no task is active, and the thread is not in plan mode. If accepted, the items start a new turn. If rejected, an error explains why and carries the original items back.

Call relations: Extensions that receive an idle lifecycle callback are expected to use this entry point. The session performs the eligibility decision, and rejection errors preserve enough information for the extension to retry or drop the work deliberately.

async fn set_app_server_client_info(
        &self,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
        mcp_elicitations_auto_deny: bool,
    ) -

Purpose: Stores information about the app-server client connected to the thread, including name, version, and whether certain external prompts should be automatically denied. This lets the session adapt to client capabilities and safety choices.

Data flow: It receives optional client name and version plus a flag for auto-denying MCP elicitations. It forwards those values to the inner Codex validation and storage logic, returning success or a constraint error.

Call relations: App-server connection setup paths call this when a client identifies itself. The deeper Codex layer applies the actual constraints.

Call graph: calls 1 internal fn (set_app_server_client_info); called by 2 (set_app_server_client_info, set_app_server_client_info).

async fn preview_thread_settings_overrides(
        &self,
        overrides: CodexThreadSettingsOverrides,
    ) -> ConstraintResult<ThreadConfigSnapshot>

Purpose: Shows what the thread configuration would look like after applying proposed settings overrides, without actually saving them. This is a dry run for settings changes.

Data flow: It receives override values, converts them into a session settings update, and asks the session to preview that update. The output is either a new configuration snapshot or a constraint error.

Call relations: Settings-building code calls this before committing changes. It relies on CodexThread::thread_settings_update to translate thread-level override fields into the session’s update format.

Call graph: calls 1 internal fn (thread_settings_update); called by 1 (build_thread_settings_overrides).

async fn thread_settings_update(
        &self,
        overrides: CodexThreadSettingsOverrides,
    ) -> SessionSettingsUpdate

Purpose: Converts app-server thread setting overrides into the session’s internal update shape. It also fills in collaboration mode intelligently when the caller did not provide one.

Data flow: It receives optional override fields such as environments, workspace roots, approval policy, sandbox policy, model, effort, service tier, and personality. If collaboration mode is missing, it reads the current mode and applies model or effort changes to it. It returns a SessionSettingsUpdate ready for preview or application.

Call relations: CodexThread::preview_thread_settings_overrides calls this as its translation step. It is the adapter between external override requests and the session’s configuration-update format.

Call graph: called by 1 (preview_thread_settings_overrides); 1 external calls (default).

async fn submit_with_id(&self, sub: Submission) -> CodexResult<()>

Purpose: Submits a pre-built submission that already has its own id. The comment notes this is temporary and should be used sparingly.

Data flow: It receives a complete submission object and forwards it to the inner Codex object. The method returns success or an error from that submission.

Call relations: Legacy or transitional code can call this when it must preserve an existing submission id instead of letting the normal submit path create one.

Call graph: calls 1 internal fn (submit_with_id).

async fn next_event(&self) -> CodexResult<Event>

Purpose: Waits for and returns the next event produced by the thread. Events are the stream of updates a client reads to learn what the session did.

Data flow: It asks the inner Codex object for the next event. The result is either the next event or an error if the event stream cannot continue.

Call relations: Turn-running, settings, and waiting code call this after submitting work so they can observe progress and results from the session.

Call graph: calls 1 internal fn (next_event); called by 4 (submit_thread_settings, wait_for_event_with_timeout, wait_for_mcp_server, run_turn).

async fn agent_status(&self) -> AgentStatus

Purpose: Returns the current status of the agent for this thread, such as whether it is idle, working, or otherwise occupied.

Data flow: It asks the inner Codex object for the latest agent status and returns that value. It does not mutate the thread.

Call relations: Agent-loop code calls this to decide what the thread is doing right now. The actual status is maintained by the underlying Codex session.

Call graph: calls 1 internal fn (agent_status); called by 1 (loop_agent).

async fn list_background_terminals(&self) -> Vec<BackgroundTerminalInfo>

Purpose: Lists background terminal processes started by the thread. A background terminal is a command that keeps running while the conversation continues.

Data flow: It asks the session for its current background terminal records. It returns a list containing item id, process id, command, and working directory for each one.

Call relations: User interface or app-server code can call this when it wants to show running background commands attached to the thread.

async fn terminate_background_terminal(&self, process_id: i32) -> bool

Purpose: Attempts to stop a background terminal process by process id. This gives callers a controlled way to clean up long-running commands.

Data flow: It receives a process id, passes it to the session’s termination logic, and returns true if a matching terminal was stopped. It returns false if no matching process was terminated.

Call relations: Client-facing terminal control code can use this after listing background terminals or when the user asks to stop one.

fn subscribe_status(&self) -> watch::Receiver<AgentStatus>

Purpose: Creates a live subscription to the thread’s agent status. A subscription lets a caller be notified when the status changes instead of repeatedly asking.

Data flow: It clones the internal watch receiver for agent status and returns it. The thread state is not changed.

Call relations: Internal observers use this when they need ongoing status updates tied to the same status stream used by the Codex session.

async fn token_usage_info(&self) -> Option<TokenUsageInfo>

Purpose: Returns the complete cached token-usage snapshot for the thread. Tokens are the pieces of text the model reads and writes, and usage data is important for reporting cost and context size.

Data flow: It asks the session for its current token usage information. The result may be absent if no usage has been recorded yet. It does not expose broader session mutation access.

Call relations: Connection update code calls this when it needs to send accurate token usage, including both total and last-turn information, after resume or fork.

Call graph: called by 1 (send_thread_token_usage_update_to_connection).

async fn inject_user_message_without_turn(&self, message: String)

Purpose: Records a user-role message in the session without starting a new user turn. This is used for prefix or context messages that should be visible in history but not treated as a new request boundary.

Data flow: It receives plain text, wraps it as a user message response item, and asks the session to inject it without creating a new turn. It returns nothing.

Call relations: Internal setup or resume flows can use this when they need to add user-visible context to the conversation log without triggering model work.

Call graph: 1 external calls (vec!).

async fn inject_response_items(&self, items: Vec<ResponseItem>) -> CodexResult<()>

Purpose: Records raw Responses API items in the thread without starting a new turn. It is a controlled way to add already-formed model/API items into the session history.

Data flow: It receives response items and first rejects an empty list as an invalid request. For non-empty input, it creates a default turn context, records reference context if needed, injects the items without a new turn, flushes the rollout to storage, and returns success or an error.

Call relations: Callers that import or replay response items use this when they need persistence and context bookkeeping but do not want to trigger fresh model execution.

Call graph: 1 external calls (InvalidRequest).

fn rollout_path(&self) -> Option<PathBuf>

Purpose: Returns the file path or storage path for this thread’s rollout log, if one exists. The rollout log is the saved record of the session.

Data flow: It clones the optional path stored on the thread and returns it. The thread is not changed.

Call relations: Thread-loading code calls this when it needs to reconnect a live thread to its persisted rollout location.

Call graph: called by 1 (build_thread_from_loaded_snapshot).

fn session_configured(&self) -> SessionConfiguredEvent

Purpose: Returns the session configuration event captured when the thread was set up. This event includes important identity and configuration details for the running session.

Data flow: It clones the stored configuration event and returns the clone. No internal state changes.

Call relations: Resume and loaded-snapshot flows call this when they need the already-known configured-session details for building or reporting a thread.

Call graph: called by 2 (load_thread_from_resume_source_or_send_internal, build_thread_from_loaded_snapshot); 1 external calls (clone).

fn is_running(&self) -> bool

Purpose: Reports whether the thread’s submission channel is still open. In plain terms, it checks whether the thread can still receive work.

Data flow: It looks at the internal sender channel and returns true if that channel has not been closed. It does not wait or change anything.

Call relations: Internal code can use this as a quick liveness check before deciding whether a thread is still usable.

async fn guardian_trunk_rollout_path(&self) -> Option<PathBuf>

Purpose: Returns the rollout path for the guardian review trunk session, if there is one. This is related to review workflows that compare or protect a main line of work.

Data flow: It asks the session’s guardian review session for its trunk rollout path and returns the optional path. The current thread state is unchanged.

Call relations: Review-related orchestration can call this when it needs to locate the persisted record for the trunk side of a guardian review.

async fn load_history(
        &self,
        include_archived: bool,
    ) -> ThreadStoreResult<StoredThreadHistory>

Purpose: Loads the stored history for this live thread. It can include or exclude archived history depending on the caller’s request.

Data flow: It first asks the session for a persistence-ready live-thread handle. If that fails, it converts the problem into a thread-store internal error. Otherwise it asks that handle to load history and returns the result.

Call relations: Store-field application code calls this when it needs to attach saved conversation history to a thread read response.

Call graph: called by 1 (apply_thread_read_store_fields).

async fn read_thread(
        &self,
        include_archived: bool,
        include_history: bool,
    ) -> ThreadStoreResult<StoredThread>

Purpose: Reads the stored thread record, optionally including archived data and full history. This is the broader “give me the saved thread” operation.

Data flow: It obtains the live-thread persistence handle from the session, converting failures into thread-store errors. Then it asks that handle to read the thread with the requested archive and history options. The stored thread record is returned.

Call relations: Thread-store API paths use this when a caller wants the persisted representation of the current live thread.

async fn update_thread_metadata(
        &self,
        patch: ThreadMetadataPatch,
        include_archived: bool,
    ) -> ThreadStoreResult<StoredThread>

Purpose: Applies a metadata patch to the stored thread record. Metadata is descriptive information about the thread, separate from the conversation events themselves.

Data flow: It receives a metadata patch and an archive-inclusion flag. It obtains the live-thread persistence handle, then asks it to update the metadata. The updated stored thread is returned, or a store error if anything fails.

Call relations: Thread management endpoints use this when a client edits stored thread details. This method bridges from the live session to the thread store.

fn state_db(&self) -> Option<StateDbHandle>

Purpose: Returns the state database handle for this thread, if one is available. This database stores rollout or resume-related state outside the immediate session objects.

Data flow: It asks the inner Codex object for its optional state database handle and returns it. Nothing is mutated.

Call relations: Resume-goal and thread-spawn-edge persistence code call this when they need access to durable state associated with the thread.

Call graph: calls 1 internal fn (state_db); called by 2 (pending_resume_goal_state, persist_thread_spawn_edge_for_source).

async fn config_snapshot(&self) -> ThreadConfigSnapshot

Purpose: Returns a snapshot of the thread’s current configuration. This gives callers a stable view of settings such as model, approvals, environments, and workspace roots.

Data flow: It asks the inner Codex object to build the current thread configuration snapshot. The returned snapshot is independent data for the caller to inspect.

Call relations: Live-thread loading, resume, environment override, and settings override flows call this before comparing or preparing configuration changes.

Call graph: calls 1 internal fn (thread_config_snapshot); called by 4 (load_live_thread_view, load_thread_from_resume_source_or_send_internal, build_environment_override, build_thread_settings_overrides).

async fn instruction_sources(&self) -> Vec<AbsolutePathBuf>

Purpose: Returns the files that supplied the model instructions loaded for this thread. This helps explain where the thread’s guidance came from.

Data flow: It asks the inner Codex object for its instruction source paths and returns the list. It does not alter the loaded instructions.

Call relations: Diagnostics or configuration display code can call this when it wants to show the origin of the thread’s instructions.

Call graph: calls 1 internal fn (instruction_sources).

async fn config(&self) -> Arc<crate::config::Config>

Purpose: Returns the thread’s current configuration object. This is the fuller configuration, not just a lightweight snapshot.

Data flow: It asks the session for its current config and returns it inside a shared pointer. The shared pointer lets multiple parts of the program read the same config safely.

Call relations: Refresh-config building code calls this as the starting point for calculating runtime configuration updates.

Call graph: called by 1 (build_refresh_config).

async fn runtime_mcp_config(&self, config: &crate::config::Config) -> codex_mcp::McpConfig

Purpose: Builds the runtime MCP configuration for this thread. MCP, or Model Context Protocol, is a way for the model/session to talk to external tools and resources.

Data flow: It receives a base config and asks the session to resolve the MCP config using this thread’s extension data. It returns the ready-to-use MCP configuration.

Call relations: Refresh-config building code calls this after reading configuration so MCP tool/resource settings reflect the thread’s runtime extension state.

Call graph: called by 1 (build_refresh_config).

fn multi_agent_version(&self) -> Option<MultiAgentVersion>

Purpose: Returns which multi-agent protocol version this session is using, if any. Multi-agent mode means more than one agent-like participant may coordinate work.

Data flow: It reads the version from the session and returns an optional value. No state changes.

Call relations: Input-permission and resident-thread selection logic call this when behavior depends on whether the thread is using a multi-agent version.

Call graph: called by 2 (ensure_direct_input_allowed, is_resident_candidate).

async fn refresh_runtime_config(&self, next_config: crate::config::Config)

Purpose: Refreshes the thread’s runtime user configuration from a new config snapshot. Thread-specific layers and settings that are fixed for the session stay unchanged.

Data flow: It receives a new config object and passes it to the session’s refresh logic. The session updates its runtime config view; this method returns nothing.

Call relations: Configuration refresh orchestration uses this when external config changes need to be reflected in a live thread without rebuilding the whole session.

async fn environment_selections(&self) -> Vec<TurnEnvironmentSelection>

Purpose: Returns the current environment selections for the thread. These describe the execution environments available for turns.

Data flow: It asks the inner Codex object for the thread’s environment selections and returns the resulting list. The thread is unchanged.

Call relations: Callers use this when they need the live environment choices rather than a previously captured configuration snapshot.

Call graph: calls 1 internal fn (thread_environment_selections).

async fn read_mcp_resource(
        &self,
        server: &str,
        uri: &str,
    ) -> anyhow::Result<serde_json::Value>

Purpose: Reads a resource from an MCP server and returns it as JSON. This is how callers fetch external resource data through the thread’s configured tool protocol.

Data flow: It receives a server name and resource URI, builds MCP read parameters, and asks the session to read the resource. The result is converted into JSON and returned, or an error is passed back.

Call relations: Client or tool-facing code calls this when it needs to access an MCP resource through the same runtime configuration and permissions as the thread.

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

async fn call_mcp_tool(
        &self,
        server: &str,
        tool: &str,
        arguments: Option<serde_json::Value>,
        meta: Option<serde_json::Value>,
    ) -> anyhow::Result<CallTool

Purpose: Calls a tool exposed by an MCP server. It lets the thread invoke external tool functionality with optional arguments and metadata.

Data flow: It receives the server name, tool name, optional JSON arguments, and optional JSON metadata. It forwards them to the session’s MCP tool caller and returns the tool result or an error.

Call relations: Tool invocation paths use this as the thread-level bridge to MCP tool execution, keeping calls tied to this session’s configuration and extension data.

fn enabled(&self, feature: Feature) -> bool

Purpose: Checks whether a feature flag is enabled for this thread. Feature flags let the system turn behavior on or off in a controlled way.

Data flow: It receives a feature identifier and asks the inner Codex object whether that feature is enabled. It returns true or false.

Call relations: Any thread-level logic that needs to branch on optional behavior can call this instead of reaching into the underlying Codex object.

Call graph: calls 1 internal fn (enabled).

async fn increment_out_of_band_elicitation_count(&self) -> CodexResult<u64>

Purpose: Records that an out-of-band elicitation has started and pauses the session for that condition if this is the first one. An elicitation is a prompt for information or approval outside the normal turn flow.

Data flow: It locks the counter, checks whether it was zero, and safely adds one. If adding would overflow, it returns a fatal error. If this was the first active elicitation, it tells the session to enter the paused state. It returns the new count.

Call relations: Code that begins an external prompt uses this to make the thread aware that normal progress may need to pause. The matching decrement method clears the pause when the last such prompt finishes.

async fn decrement_out_of_band_elicitation_count(&self) -> CodexResult<u64>

Purpose: Records that an out-of-band elicitation has finished and unpauses the session when none remain. This keeps pause state accurate even if several prompts overlap.

Data flow: It locks the counter and rejects the request if the count is already zero. Otherwise it subtracts one. If the count reaches zero, it tells the session to leave the out-of-band elicitation paused state. It returns the new count.

Call relations: Code that completes or cancels an external prompt calls this after a previous increment. Together, the two methods act like a checkout counter: the session stays paused until the last outstanding prompt has checked back in.

Call graph: 1 external calls (InvalidRequest).

fn to_error_event(&self) -> ErrorEvent

Purpose: Turns a steering-input failure into an event that can be sent to the client. This gives callers a clear user-facing message and, when possible, a structured error code.

Data flow: It reads the specific error variant, chooses a plain message such as “no active turn to steer” or “input must not be empty,” and returns an ErrorEvent with optional machine-readable Codex error information.

Call relations: It is the bridge from internal steering validation to the public event stream. When steering fails, higher-level code can use this to report the problem in the same event format as other session errors.

Call graph: 1 external calls (format!).

fn resolve_multi_agent_version(
    conversation_history: &InitialHistory,
    inherited_multi_agent_version: Option<MultiAgentVersion>,
) -> Option<MultiAgentVersion>

Purpose: Decides which multi-agent behavior version a session should use. It preserves explicit disabling, honors saved thread metadata, and keeps older resumed or forked threads on the older behavior when no metadata exists.

Data flow: It takes the starting conversation history and an optional inherited version, checks them in priority order, and returns the chosen version or no version. Old resumed and forked histories default to V1 so their tool surface does not unexpectedly change.

Call relations: Session startup calls this while building the session configuration. A helper for spawn-time defaults also uses it so new, resumed, forked, and inherited sessions make the same compatibility decision.

Call graph: calls 1 internal fn (get_multi_agent_version); called by 2 (spawn_internal, initial_multi_agent_version_for_spawn).

async fn spawn(args: CodexSpawnArgs) -> CodexResult<CodexSpawnOk>

Purpose: Starts a new Codex thread from caller-provided startup arguments. It also attaches tracing information, which is metadata used to connect logs and telemetry across related work.

Data flow: It receives spawn arguments, validates any parent trace carrier, creates a tracing span for thread creation, attaches the parent trace when valid, and then delegates the real setup to Codex::spawn_internal. It returns the live Codex handle and the thread id.

Call relations: This is the friendly outer startup entry used by interactive runs and thread-spawn helpers. It wraps Codex::spawn_internal with tracing so the deeper setup work appears as one connected operation in observability tools.

Call graph: called by 3 (run_codex_thread_interactive, guardian_subagent_does_not_inherit_parent_exec_policy_rules, spawn_thread_with_source); 5 external calls (spawn_internal, context_from_w3c_trace_context, set_parent_from_w3c_trace_context, info_span!, warn!).

async fn spawn_internal(args: CodexSpawnArgs) -> CodexResult<CodexSpawnOk>

Purpose: Builds the live session and starts the background loop that processes submissions. This is where configuration, model choice, permissions, history, tools, and event channels are assembled into a working Codex instance.

Data flow: It unpacks startup arguments, creates channels for incoming submissions and outgoing events, loads or inherits execution policy rules, chooses a model, resolves instructions and multi-agent behavior, builds a SessionConfiguration, creates a Session, and starts a background task that runs the submission loop. It returns a Codex object connected to that loop plus the session thread id.

Call relations: Codex::spawn calls this after trace setup. It hands the finished Session to submission_loop, then exposes the channel endpoints through Codex so later calls like submit, next_event, and shutdown_and_wait can interact with the running session.

Call graph: calls 9 internal fn (default, load, get_service_tier, submission_loop, resolve_multi_agent_version, new, session_loop_termination_from_handle, session_permission_profile_state_from_config, new); 11 external calls (clone, new, pin, bounded, unbounded, is_guardian_reviewer_source, info_span!, matches!, from_config, spawn (+1 more)).

async fn submit(&self, op: Op) -> CodexResult<String>

Purpose: Sends an operation to the running session without explicitly providing trace metadata. It is the simple path for callers that just want to ask the session to do something.

Data flow: It receives an Op, passes it to Codex::submit_with_trace with no trace, and returns the generated submission id. If the session loop has died, the error is returned.

Call relations: Approval handlers, user-input handlers, shutdown helpers, and other public-facing wrappers use this when they do not need to carry a separate trace context.

Call graph: calls 1 internal fn (submit_with_trace); called by 8 (handle_exec_approval, handle_patch_approval, handle_request_permissions, handle_request_user_input, shutdown_delegate, submit, interrupt_and_drain_turn, shutdown_and_wait).

async fn submit_with_trace(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
    ) -> CodexResult<String>

Purpose: Sends an operation to the session and includes optional trace metadata. It creates a unique id so the caller can connect later events back to this submission.

Data flow: It takes an Op and optional W3C trace context, creates a time-ordered UUID string, wraps everything in a Submission, sends it through Codex::submit_with_id, and returns the id.

Call relations: Codex::submit delegates here for normal submissions. It hands the finished Submission to Codex::submit_with_id, which is the final channel-send step.

Call graph: calls 1 internal fn (submit_with_id); called by 2 (submit_with_trace, submit); 1 external calls (now_v7).

async fn submit_user_input_with_client_user_message_id(
        &self,
        op: Op,
        trace: Option<W3cTraceContext>,
        client_user_message_id: Option<String>,
    ) -> CodexResult<Stri

Purpose: Submits user input while preserving a caller-supplied user-message id. That lets outside clients match their own message records to Codex’s internal submission id.

Data flow: It expects an Op::UserInput operation, creates a new submission id, attaches the optional trace and client user message id, sends the submission, and returns the new id.

Call relations: This is the specialized user-input version of the submission path. Like Codex::submit_with_trace, it finishes by calling Codex::submit_with_id.

Call graph: calls 1 internal fn (submit_with_id); called by 1 (submit_user_input_with_client_user_message_id); 2 external calls (now_v7, debug_assert!).

async fn submit_with_id(&self, mut sub: Submission) -> CodexResult<()>

Purpose: Places a fully formed submission onto the session’s input channel. This is the last step before the background session loop receives the work.

Data flow: It takes a Submission, fills in the current tracing context if the submission lacks one, sends it through the bounded submission channel, and returns success or an InternalAgentDied error if the channel is closed.

Call relations: The higher-level submit helpers all end here. The background submission loop created during spawn reads from the other end of this channel.

Call graph: called by 3 (submit_with_id, submit_user_input_with_client_user_message_id, submit_with_trace); 2 external calls (send, current_span_w3c_trace_context).

async fn set_thread_memory_mode(
        &self,
        mode: codex_protocol::protocol::ThreadMemoryMode,
    ) -> anyhow::Result<()>

Purpose: Changes and persists the thread’s memory mode. Memory mode controls how the thread should remember or use past information.

Data flow: It receives the desired ThreadMemoryMode and asks the handlers layer to persist that update for the session. It returns any persistence error.

Call relations: The public thread-memory API calls this when a caller changes memory behavior. It delegates the actual write to handlers::persist_thread_memory_mode_update.

Call graph: calls 1 internal fn (persist_thread_memory_mode_update); called by 1 (set_thread_memory_mode).

async fn shutdown_and_wait(&self) -> CodexResult<()>

Purpose: Asks the session loop to shut down and waits until it has actually stopped. This avoids dropping a session while its background task is still running.

Data flow: It clones the shared termination future, submits an Op::Shutdown, ignores the special case where the agent already died, waits for the loop to end, and then returns success.

Call relations: Shutdown flows and thread-spawn finalization use this to perform orderly teardown. It uses Codex::submit to request shutdown and the termination handle made by session_loop_termination_from_handle to wait.

Call graph: calls 1 internal fn (submit); called by 3 (shutdown_and_wait, shutdown, finalize_thread_spawn); 1 external calls (clone).

async fn next_event(&self) -> CodexResult<Event>

Purpose: Waits for the next event produced by the session. Events are how the outside world learns about model output, tool calls, warnings, errors, and turn completion.

Data flow: It waits on the event receiver channel, returns the next Event, or reports InternalAgentDied if the channel is closed.

Call relations: Consumers such as interactive loops and shutdown helpers call this to drain the session outbox. Session::deliver_event_raw sends events into the matching channel.

Call graph: calls 1 internal fn (recv); called by 4 (shutdown_delegate, next_event, interrupt_and_drain_turn, finalize_thread_spawn).

async fn steer_input(
        &self,
        input: Vec<UserInput>,
        additional_context: BTreeMap<String, AdditionalContextEntry>,
        expected_turn_id: Option<&str>,
        client_user_me

Purpose: Adds steering input to an already running turn, such as extra user guidance or context. It is separate from starting a new turn.

Data flow: It receives user input items, extra context, an optional expected turn id, an optional client message id, and optional Responses API metadata, then forwards them to the Session. It returns a submission-like id or a SteerInputError.

Call relations: The outer Codex API exposes this to callers, while Session::steer_input performs the active-turn validation and insertion work.

Call graph: called by 1 (steer_input).

async fn set_app_server_client_info(
        &self,
        app_server_client_name: Option<String>,
        app_server_client_version: Option<String>,
        mcp_elicitations_auto_deny: bool,
    ) -

Purpose: Records which app-server client is connected and configures whether MCP elicitations should be automatically denied. MCP is a tool-connection protocol; elicitations are requests for extra input.

Data flow: It takes optional client name and version plus a boolean auto-deny flag, updates session settings with the client details, then updates the MCP connection manager with the elicitation behavior.

Call relations: External API code calls this after a client identifies itself. It uses Session::update_settings for stored settings and then directly adjusts the MCP service.

Call graph: called by 1 (set_app_server_client_info); 1 external calls (default).

async fn agent_status(&self) -> AgentStatus

Purpose: Returns the latest known status of the agent, such as pending, running, completed, or errored.

Data flow: It reads the current value from a watch channel, clones it, and returns it without changing session state.

Call relations: Status-facing APIs call this when they need a snapshot. Session::deliver_event_raw and multi-agent completion handling update the watched status.

Call graph: called by 1 (agent_status); 1 external calls (borrow).

async fn thread_config_snapshot(&self) -> ThreadConfigSnapshot

Purpose: Returns a safe snapshot of the thread’s current configuration. This lets callers inspect settings without taking ownership of the live configuration object.

Data flow: It locks session state, asks the SessionConfiguration to build a ThreadConfigSnapshot, and returns that snapshot.

Call relations: Configuration APIs call this to report current thread settings. It reads the same session configuration that Session::update_settings changes.

Call graph: called by 1 (config_snapshot).

async fn instruction_sources(&self) -> Vec<AbsolutePathBuf>

Purpose: Reports the files that supplied loaded agent instructions. This helps users understand where the model’s guidance came from.

Data flow: It locks session state, looks for loaded AGENTS-style instruction data, collects its source paths, and returns an empty list if none are loaded.

Call relations: Instruction-inspection APIs use this after session setup has loaded instruction files into the session configuration.

Call graph: called by 1 (instruction_sources).

async fn thread_environment_selections(&self) -> Vec<TurnEnvironmentSelection>

Purpose: Returns the environments selected for this thread, such as the workspace or runtime targets used for turns.

Data flow: It locks session state, reads the configuration’s environment selections, copies them into a vector, and returns them.

Call relations: Environment-inspection APIs call this. Session::update_settings can change the stored environment selections.

Call graph: called by 1 (environment_selections).

fn state_db(&self) -> Option<state_db::StateDbHandle>

Purpose: Exposes the optional state database handle for this session. The state database is persistent storage for session-related data when enabled.

Data flow: It asks the underlying Session for its state database handle and returns either a handle or None.

Call relations: Higher-level APIs use this Codex wrapper instead of reaching into Session directly. Session::state_db provides the actual handle.

Call graph: called by 1 (state_db).

fn enabled(&self, feature: Feature) -> bool

Purpose: Checks whether a feature flag is enabled for this session. Feature flags are switches that turn optional behavior on or off.

Data flow: It receives a Feature value, asks the Session whether that feature is enabled, and returns true or false.

Call relations: Callers use this as the Codex-level feature query. The Session owns the feature configuration used to answer.

Call graph: called by 1 (enabled).

fn get_service_tier(
    configured_service_tier: Option<String>,
    fast_mode_enabled: bool,
    model_info: &ModelInfo,
) -> Option<String>

Purpose: Decides whether to send a service-tier hint to the model provider. The tier is only used when fast mode is enabled and the selected model supports the requested tier.

Data flow: It receives the configured tier, whether fast mode is enabled, and model metadata. If fast mode is off it returns None; otherwise it returns the configured tier only if it is the default request value or supported by the model.

Call relations: Session startup calls this while building SessionConfiguration so model requests carry a valid service-tier value.

Call graph: called by 1 (spawn_internal).

fn session_permission_profile_state_from_config(
    config: &Config,
) -> CodexResult<PermissionProfileState>

Purpose: Extracts the initial permission-profile state from the configuration. The permission profile controls what the session is allowed to do.

Data flow: It reads config.permissions, clones its PermissionProfileState, wraps it in a successful CodexResult, and returns it.

Call relations: Codex::spawn_internal uses this while building the session configuration.

Call graph: called by 1 (spawn_internal).

fn completed_session_loop_termination() -> SessionLoopTermination

Purpose: Creates a termination handle that is already complete. This is useful in tests or fake sessions that do not have a real background loop.

Data flow: It builds a future that immediately resolves, boxes it, shares it, and returns it as a SessionLoopTermination.

Call relations: Tests use this instead of the real handle returned by session_loop_termination_from_handle.

Call graph: called by 1 (test_review_session); 1 external calls (ready).

fn session_loop_termination_from_handle(
    handle: JoinHandle<()>,
) -> SessionLoopTermination

Purpose: Turns a spawned background task handle into a shared future that completes when the session loop ends.

Data flow: It takes a JoinHandle, creates an async block that awaits it and ignores the join result, boxes and shares that future, and returns it.

Call relations: Codex::spawn_internal wraps the submission-loop task with this so Codex::shutdown_and_wait can wait for clean termination.

Call graph: called by 1 (spawn_internal).

async fn thread_title_from_thread_store(
    live_thread: Option<&LiveThread>,
    thread_store: &Arc<dyn ThreadStore>,
    conversation_id: ThreadId,
) -> Option<String>

Purpose: Finds a useful saved title for a thread. It avoids returning empty titles or titles that are merely the same as the preview text.

Data flow: It reads the thread either from a live thread object or from the thread store, trims the thread name, compares it with the preview, and returns a title only if it is non-empty and distinct.

Call relations: This helper is available to code that needs display names for existing threads, whether the thread is currently live or only stored.

async fn app_server_client_metadata(&self) -> AppServerClientMetadata

Purpose: Returns the app-server client name and version stored on the session. This lets downstream code tailor behavior or reporting to the connected client.

Data flow: It locks session state, copies the optional client name and version from the session configuration, and returns them in an AppServerClientMetadata value.

Call relations: The data returned here is set through Codex::set_app_server_client_info and Session::update_settings.

fn managed_network_proxy_active_for_permission_profile(
        permission_profile: &PermissionProfile,
    ) -> bool

Purpose: Answers whether the managed network proxy should be active for a permission profile. It treats the disabled profile as the only case where proxy enforcement is inactive.

Data flow: It receives a PermissionProfile and returns false if it is Disabled, otherwise true.

Call relations: This helper supports the network-permission logic used when the session starts or refreshes network proxy state.

Call graph: 1 external calls (matches!).

fn build_model_client_beta_features_header(config: &Config) -> Option<String>

Purpose: Builds the header value that tells the model client which experimental features are enabled. This lets the model side know about selected beta behavior.

Data flow: It scans all known feature specs, keeps the ones meant to be advertised and enabled in config, joins their keys with commas, and returns None if there are no enabled advertised features.

Call relations: Session setup can use this when constructing model-client requests or clients that need feature-advertising headers.

async fn start_managed_network_proxy(
        spec: &crate::config::NetworkProxySpec,
        exec_policy: &codex_execpolicy::Policy,
        permission_profile: &PermissionProfile,
        network_po

Purpose: Starts the session’s managed network proxy, which is a local gatekeeper for outbound network access. It combines configured network rules with execution-policy rules before launching the proxy.

Data flow: It receives a proxy spec, current execution policy, permission profile, optional policy hooks, requirement flags, and audit metadata. It tries to apply execution-policy network rules, starts the proxy, captures its HTTP and SOCKS addresses, and returns both the running proxy and runtime address data.

Call relations: Network setup and refresh flows call this when a proxy must be created. Session::refresh_managed_network_proxy_for_current_permission_profile uses it if no proxy is already running.

Call graph: calls 2 internal fn (start_proxy, with_exec_policy_network_rules).

async fn refresh_managed_network_proxy_for_current_permission_profile(&self)

Purpose: Updates the managed network proxy after the session’s permission profile changes. This keeps network enforcement aligned with the current sandbox and approval settings.

Data flow: It takes a refresh lock so only one refresh runs, reads current session configuration, exits if no network proxy is configured, recomputes the proxy spec for the current permission profile, applies execution-policy network rules, updates an existing proxy if present, or starts and stores a new proxy.

Call relations: Session::update_settings calls this when it detects a permission-profile change. It uses Session::start_managed_network_proxy for the create-new-proxy path.

Call graph: called by 1 (update_settings); 4 external calls (new, start_managed_network_proxy, error!, warn!).

async fn codex_home(&self) -> AbsolutePathBuf

Purpose: Returns the session’s Codex home directory, where configuration and persistent files live.

Data flow: It locks session state, clones the codex_home path from the configuration, and returns it.

Call relations: Helpers that need to read or write files under Codex home use this instead of reaching into configuration directly.

fn subscribe_out_of_band_elicitation_pause_state(&self) -> watch::Receiver<bool>

Purpose: Lets another task watch whether out-of-band elicitations are paused. Out-of-band means requests that happen outside the normal turn flow.

Data flow: It subscribes to the watch channel that stores the pause boolean and returns a receiver for future changes.

Call relations: Consumers that react to elicitation pause changes use this receiver. Session::set_out_of_band_elicitation_pause_state updates the watched value.

fn set_out_of_band_elicitation_pause_state(&self, paused: bool)

Purpose: Sets whether out-of-band elicitations are paused. This immediately notifies watchers of the new state.

Data flow: It receives a boolean and replaces the current value in the watch channel with that boolean.

Call relations: Control paths call this when elicitation behavior should pause or resume. Subscribers created by Session::subscribe_out_of_band_elicitation_pause_state see the update.

fn get_tx_event(&self) -> Sender<Event>

Purpose: Returns a sender for the session’s event channel. This gives internal helpers a way to deliver events to the outside Codex handle.

Data flow: It clones the event Sender and returns the clone, leaving the original sender in place.

Call relations: Code that needs to emit events can use this sender, though most event emission goes through Session::send_event or Session::send_event_raw.

fn state_db(&self) -> Option<state_db::StateDbHandle>

Purpose: Returns the optional state database handle held by the session services.

Data flow: It clones the state database handle option from services and returns it.

Call relations: Codex::state_db calls this as its session-level implementation.

fn live_thread_for_persistence(
        &self,
        operation: &str,
    ) -> anyhow::Result<&LiveThread>

Purpose: Gets the live thread object needed for persistence, or explains why it is unavailable. This prevents silent failures when code expects saved thread storage.

Data flow: It receives a human-readable operation name, checks whether live-thread persistence exists, and returns either the LiveThread reference or an error saying persistence is disabled for that operation.

Call relations: Persistence code uses this when the operation cannot safely proceed without a live thread. It builds on Session::live_thread.

Call graph: calls 1 internal fn (live_thread).

fn live_thread(&self) -> Option<&LiveThread>

Purpose: Returns the optional live thread object for this session. A live thread is the file-backed or store-backed object used to persist rollout data.

Data flow: It reads the live_thread field from session services and returns it as an optional reference.

Call relations: Rollout helpers such as flush, persist, and path lookup call this to decide whether persistence is enabled.

Call graph: called by 5 (current_rollout_path, flush_rollout, live_thread_for_persistence, persist_rollout_items, try_ensure_rollout_materialized).

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

Purpose: Flushes pending rollout data to storage if this session has persistence enabled. Flushing means asking storage to write buffered data out.

Data flow: It checks for a live thread. If one exists, it awaits its flush and converts errors into I/O errors; if not, it succeeds without doing anything.

Call relations: Session::record_initial_history calls this after resume or fork setup so saved history is stable on disk or in the backing store.

Call graph: calls 1 internal fn (live_thread); called by 1 (record_initial_history).

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

Purpose: Ensures the rollout has a concrete persisted backing when possible. This is important for forked or resumed threads that should remain file-backed immediately.

Data flow: It checks for a live thread, calls persist on it if present, converts errors to I/O errors, and otherwise returns success.

Call relations: Session::ensure_rollout_materialized wraps this with warning-only error handling for callers that should not fail the whole turn.

Call graph: calls 1 internal fn (live_thread); called by 1 (ensure_rollout_materialized).

async fn ensure_rollout_materialized(&self)

Purpose: Best-effort version of ensuring rollout persistence exists. It logs a warning instead of returning an error.

Data flow: It calls Session::try_ensure_rollout_materialized and, if that fails, logs the failure and continues.

Call relations: History recording and prompt-recording code use this when persistence is desired but should not stop the session if it fails.

Call graph: calls 1 internal fn (try_ensure_rollout_materialized); called by 3 (hook_transcript_path, record_initial_history, record_user_prompt_and_emit_turn_item); 1 external calls (warn!).

fn next_internal_sub_id(&self) -> String

Purpose: Generates a unique internal submission id for automatic session work. In this chunk it is used for realtime text routed into the normal input path.

Data flow: It atomically increments a counter and formats the previous number as an id like auto-compact-N.

Call relations: Session::route_realtime_text_input calls this before creating an internal user-input operation.

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

async fn route_realtime_text_input(self: &Arc<Self>, text: String)

Purpose: Feeds realtime text into the same machinery as normal user input. This lets live text input become a turn input without duplicating turn-start logic.

Data flow: It receives text, wraps it in a UserInput::Text item inside an Op::UserInput, assigns an internal submission id, and passes it to handlers::user_input_or_turn_inner.

Call relations: Realtime input handling calls this on the Session. It delegates to the normal user-input handler so the rest of the turn pipeline stays consistent.

Call graph: calls 2 internal fn (next_internal_sub_id, user_input_or_turn_inner); 2 external calls (default, vec!).

async fn get_total_token_usage(&self) -> i64

Purpose: Returns the total token usage as an integer count. Tokens are pieces of text counted by the model for billing and context-size limits.

Data flow: It locks state, asks state to compute total usage with the current reasoning-token inclusion setting, and returns the count.

Call relations: Usage-reporting code can call this for a simple total. More detailed methods below return structured token information.

async fn auto_compact_window_snapshot(&self) -> AutoCompactWindowSnapshot

Purpose: Returns the current auto-compaction window state. Auto-compaction is the process of shrinking old context when a conversation grows too large.

Data flow: It locks session state, asks state for an AutoCompactWindowSnapshot, and returns it.

Call relations: Compaction and UI code use this to understand where the current context window stands.

async fn estimated_tokens_after_last_model_generated_item(&self) -> i64

Purpose: Estimates how many tokens are in the history after the last item generated by the model. This helps reason about recent user or tool additions since the model last spoke.

Data flow: It locks state, asks the history object for the estimate, and returns the integer result.

Call relations: Token-budgeting and compaction logic can call this when deciding whether more model context can be added.

async fn total_token_usage(&self) -> Option<TokenUsage>

Purpose: Returns detailed total token usage if token information is available. Unlike the plain integer helper, this keeps the structured TokenUsage shape.

Data flow: It locks state, reads optional token info, maps it to the total_token_usage field, and returns None if no token info has been recorded.

Call relations: UI or metrics code can use this when it wants provider-style token breakdowns.

async fn token_usage_info(&self) -> Option<TokenUsageInfo>

Purpose: Returns the full token-usage information currently stored on the session.

Data flow: It locks state, reads token_info, and returns the optional TokenUsageInfo value.

Call relations: This is the broadest token-reporting accessor. Session::record_initial_history can seed this data from saved rollout events.

async fn get_estimated_token_count(
        &self,
        turn_context: &TurnContext,
    ) -> Option<i64>

Purpose: Estimates the token count for the current history under a given turn context. The turn context includes model and feature details that can affect counting.

Data flow: It receives a TurnContext, locks state, asks history to estimate the token count for that context, and returns an optional count.

Call relations: Turn planning, compaction, or UI code can use this before sending work to the model.

async fn get_base_instructions(&self) -> BaseInstructions

Purpose: Returns the base instructions currently used by the session. These are the core directions given to the model before conversation-specific content.

Data flow: It locks state, clones the base instruction text from session configuration, wraps it in BaseInstructions, and returns it.

Call relations: Rollout reconstruction and token-usage recomputation use this when rebuilding or counting the model-visible history.

Call graph: called by 2 (apply_rollout_reconstruction, recompute_token_usage).

async fn merge_connector_selection(
        &self,
        connector_ids: HashSet<String>,
    ) -> HashSet<String>

Purpose: Adds connector ids to the session’s selected connectors and returns the merged set. Connectors are external data or service integrations.

Data flow: It receives a set of connector ids, locks mutable state, merges them into the existing selection, and returns the resulting set.

Call relations: Connector-aware request paths use this when a turn or session adds more selected connectors.

async fn get_connector_selection(&self) -> HashSet<String>

Purpose: Returns the currently selected connector ids.

Data flow: It locks state, reads the connector-selection set, clones or builds the returned HashSet, and returns it.

Call relations: Connector-aware tools and UI code call this to know which connectors are active.

async fn clear_connector_selection(&self)

Purpose: Clears all selected connectors for the session.

Data flow: It locks mutable state and tells state to empty the connector-selection set. It returns no value.

Call relations: Code that resets connector context calls this before future turns should stop using previous connector choices.

async fn record_initial_history(&self, conversation_history: InitialHistory)

Purpose: Installs the starting conversation history for a new, resumed, cleared, or forked session. This is what makes a resumed thread remember what happened before.

Data flow: It checks whether the session is a subagent and whether prior user turns exist, updates first-turn state, then handles each InitialHistory case. New or cleared sessions defer initial context; resumed and forked sessions reconstruct history, seed token info from rollout events, warn if the saved model differs from the current model, persist forked items when needed, materialize storage, and flush rollout data for root sessions.

Call relations: Session startup calls this after creating the Session. It relies on apply_rollout_reconstruction, persistence helpers, and event sending to rebuild both internal state and user-visible warnings.

Call graph: calls 7 internal fn (apply_rollout_reconstruction, ensure_rollout_materialized, flush_rollout, persist_rollout_items, send_event, set_previous_turn_settings, initial_history_has_prior_user_turns); 4 external calls (last_token_info_from_rollout, format!, Warning, warn!).

async fn apply_rollout_reconstruction(
        &self,
        turn_context: &TurnContext,
        rollout_items: &[RolloutItem],
    ) -> Option<PreviousTurnSettings>

Purpose: Rebuilds in-memory conversation history from saved rollout items. This is the core step that makes resume and fork behave as though the earlier conversation is present.

Data flow: It reconstructs history and previous turn settings from rollout items, optionally prepares old image items for the current image-resizing feature, installs the rebuilt history and compaction window into state, and may estimate prefix tokens for body-after-prefix compaction scope. It returns the previous turn settings it found.

Call relations: Session::record_initial_history calls this for resumed and forked sessions. It also feeds compaction state through Session::set_auto_compact_window_estimated_prefill_for_scope.

Call graph: calls 4 internal fn (prepare_response_items, clone_history, get_base_instructions, set_auto_compact_window_estimated_prefill_for_scope); called by 1 (record_initial_history); 1 external calls (matches!).

async fn set_auto_compact_window_estimated_prefill_for_scope(
        &self,
        turn_context: &TurnContext,
        tokens: i64,
    )

Purpose: Stores the estimated prefix token count when the current compaction mode needs it. It does nothing for compaction modes that do not use this value.

Data flow: It receives a TurnContext and token count, checks whether the model auto-compact scope is BodyAfterPrefix, and if so locks state and stores the count.

Call relations: Rollout reconstruction and token-usage recomputation call this after estimating the relevant token prefix.

Call graph: called by 2 (apply_rollout_reconstruction, recompute_token_usage); 1 external calls (matches!).

fn last_token_info_from_rollout(rollout_items: &[RolloutItem]) -> Option<TokenUsageInfo>

Purpose: Finds the most recent token-count information saved in a rollout. This lets resumed and forked sessions show usage immediately.

Data flow: It scans rollout items backward, returns the first TokenCount event’s info it finds, or None if the rollout has no token-count event.

Call relations: Session::record_initial_history uses this when seeding token info for resumed or forked sessions.

Call graph: 1 external calls (iter).

async fn previous_turn_settings(&self) -> Option<PreviousTurnSettings>

Purpose: Returns the settings used by the previous turn, if known. These settings help build a clear context update for the next turn.

Data flow: It locks state, reads previous_turn_settings, and returns the optional value.

Call relations: Context-building helpers use this to compare past and current settings. Session::set_previous_turn_settings and rollout reconstruction update the stored value.

async fn set_previous_turn_settings(
        &self,
        previous_turn_settings: Option<PreviousTurnSettings>,
    )

Purpose: Stores the settings from the previous turn. This helps later turns explain what changed in model-visible context.

Data flow: It receives an optional PreviousTurnSettings value, locks mutable state, and replaces the stored previous-turn settings.

Call relations: Session::record_initial_history calls this for new or cleared histories, while reconstruction sets it for resumed or forked histories.

Call graph: called by 1 (record_initial_history).

async fn update_settings(
        &self,
        updates: SessionSettingsUpdate,
    ) -> ConstraintResult<()>

Purpose: Applies live setting changes to the session. It validates the requested update, notifies extensions if effective config changed, updates environment selections, and refreshes the network proxy when permissions change.

Data flow: It receives a SessionSettingsUpdate, locks state, attempts to apply the update to SessionConfiguration, builds previous and new effective configs if extension notification is needed, detects permission-profile changes, writes the updated configuration, emits config-change callbacks, and refreshes the managed network proxy if needed.

Call relations: Codex::set_app_server_client_info and other live configuration paths call this. It coordinates with emit_config_changed_contributors and refresh_managed_network_proxy_for_current_permission_profile.

Call graph: calls 2 internal fn (emit_config_changed_contributors, refresh_managed_network_proxy_for_current_permission_profile); 1 external calls (warn!).

async fn preview_settings(
        &self,
        updates: &SessionSettingsUpdate,
    ) -> ConstraintResult<ThreadConfigSnapshot>

Purpose: Shows what the thread configuration would look like after a settings update, without changing the live session.

Data flow: It receives a reference to SessionSettingsUpdate, locks state, applies the update to a copy of the configuration, converts the result to a ThreadConfigSnapshot, and returns either the snapshot or validation error.

Call relations: Configuration-preview APIs use this before committing changes through Session::update_settings.

async fn set_session_startup_prewarm(
        &self,
        startup_prewarm: SessionStartupPrewarmHandle,
    )

Purpose: Stores a startup prewarm handle on the session. A prewarm handle represents startup work prepared in advance for later use.

Data flow: It receives a SessionStartupPrewarmHandle, locks mutable state, and stores it.

Call relations: Startup optimization code can set this handle so later turn-start logic can take it.

async fn take_session_startup_prewarm(&self) -> Option<SessionStartupPrewarmHandle>

Purpose: Takes and removes the stored startup prewarm handle, if one exists.

Data flow: It locks mutable state, removes the handle from state, and returns it as Some or returns None if nothing was stored.

Call relations: Code that consumes prewarmed startup work uses this so the same handle is not reused twice.

async fn get_config(&self) -> std::sync::Arc<Config>

Purpose: Returns the session’s original configuration object. The name warns that callers should be careful because this is the stored configuration snapshot, not always a freshly derived view.

Data flow: It locks state, clones the Arc around original_config_do_not_use, and returns that shared configuration pointer.

Call relations: Internal code that needs the underlying Config uses this accessor. Runtime refresh functions update this stored Arc.

async fn user_instructions(&self) -> Option<codex_extension_api::UserInstructions>

Purpose: Returns user instructions loaded from agent instruction files, if present.

Data flow: It locks state, looks inside loaded_agents_md, asks it for user instructions, clones them if found, and returns the optional value.

Call relations: Turn-building or extension code can use this to include user-supplied instruction text.

async fn provider(&self) -> ModelProviderInfo

Purpose: Returns the model provider information for the session.

Data flow: It locks state, clones the provider field from session configuration, and returns it.

Call relations: Model-calling code uses this to know which provider configuration the session is using.

async fn refresh_runtime_config(&self, next_config: Config)

Purpose: Refreshes runtime pieces of configuration for an existing session from a new Config snapshot. It preserves thread-local layers while updating the user layer and rebuilding caches and hooks.

Data flow: It takes a new Config, locks state, copies the current session config, replaces only the user-layer portion from the new snapshot, recomputes derived tool-suggestion config, stores the new Arc, notifies config contributors if effective config changed, clears skill and plugin caches, rebuilds hooks for the current environment, and publishes those hooks only if no newer refresh won the race.

Call relations: Session::reload_user_config_layer calls this after reading config files. Hosts that already have a materialized config snapshot can call this path directly.

Call graph: calls 3 internal fn (resolve_tool_suggest_config_from_layer_stack, emit_config_changed_contributors, build_hooks_for_config); called by 1 (reload_user_config_layer); 3 external calls (clone, new, ptr_eq).

fn emit_config_changed_contributors(
        &self,
        previous_config: Option<&Config>,
        new_config: Option<&Config>,
    )

Purpose: Notifies extension contributors when the effective configuration has changed. Extensions can use this to update their own behavior.

Data flow: It receives optional previous and new Config references, returns early if either is missing or they are equal, then calls on_config_changed for each registered config contributor with session and thread extension data.

Call relations: Session::update_settings and Session::refresh_runtime_config call this after they compute old and new effective configs.

Call graph: called by 2 (refresh_runtime_config, update_settings).

async fn reload_user_config_layer(&self)

Purpose: Reloads user configuration files from disk for an already running session. This supports legacy local flows where the host does not provide a ready-made new Config snapshot.

Data flow: It finds the user config TOML files from the current layer stack, falls back to codex_home/config.toml if none are listed, reads and parses each file, treats missing files as empty config, overlays the reloaded user configs onto a copy of the current config, recomputes tool-suggestion config, and calls Session::refresh_runtime_config.

Call relations: File-watch or manual reload paths call this. It delegates the actual runtime update, cache clearing, extension notification, and hook rebuild to Session::refresh_runtime_config.

Call graph: calls 2 internal fn (resolve_tool_suggest_config_from_layer_stack, refresh_runtime_config); 6 external calls (default, with_capacity, read_to_string, Table, vec!, warn!).

async fn build_settings_update_items(
        &self,
        reference_context_item: Option<&TurnContextItem>,
        current_context: &TurnContext,
    ) -> Vec<ResponseItem>

Purpose: Builds model-visible response items that explain how settings changed for the current turn. This helps the model understand changes such as shell, execution policy, or personality behavior.

Data flow: It receives an optional reference context item and the current TurnContext, reads previous turn settings, current shell, current execution policy, and personality feature state, then delegates to the context manager to produce ResponseItems.

Call relations: Context-update recording calls this before setting the reference context item. It is the session-specific adapter around the shared context_manager update builder.

Call graph: calls 2 internal fn (build_settings_update_items, user_shell); called by 1 (record_context_updates_and_set_reference_context_item).

fn track_turn_codex_error(&self, turn_context: &TurnContext, error: &CodexErr)

Purpose: Records analytics for a Codex error that happened during a turn. Analytics here means structured facts used to understand failures.

Data flow: It receives the TurnContext and CodexErr, converts the error into a TurnCodexErrorFact with thread id and turn id, and sends it to the analytics events client.

Call relations: Turn execution code can call this when reporting errors so failures are visible outside the event stream.

Call graph: calls 1 internal fn (from_codex_err).

async fn send_event(&self, turn_context: &TurnContext, msg: EventMsg)

Purpose: Sends a high-level event for a turn and performs all side effects tied to event delivery. These include tracing, persistence, status updates, parent-agent notification, realtime mirroring, and legacy compatibility events.

Data flow: It receives a TurnContext and EventMsg, records terminal error text when the event affects turn status, records trace events, wraps the message in an Event, sends it through send_event_raw, maybe notifies a parent agent, maybe mirrors text to realtime output, maybe completes realtime handoff, and then emits any legacy-format events derived from the same message.

Call relations: Most turn-event helpers use this instead of sending directly. It coordinates with send_event_raw, maybe_notify_parent_of_terminal_turn, maybe_mirror_event_text_to_realtime, and maybe_clear_realtime_handoff_for_event.

Call graph: calls 5 internal fn (maybe_clear_realtime_handoff_for_event, maybe_mirror_event_text_to_realtime, maybe_notify_parent_of_terminal_turn, send_event_raw, show_raw_agent_reasoning); called by 13 (emit_model_verification, emit_turn_item_completed, emit_turn_item_started, emit_turn_moderation_metadata, maybe_warn_on_server_model_mismatch, notify_stream_error, record_initial_history, request_command_approval, request_patch_approval, request_permissions_for_environment (+3 more)); 1 external calls (clone).

async fn maybe_notify_parent_of_terminal_turn(
        &self,
        turn_context: &TurnContext,
        msg: &EventMsg,
    )

Purpose: When a V2 subagent finishes, this decides whether to tell the parent agent about the result. It only acts on final turn-complete or turn-aborted events from spawned child agents.

Data flow: It checks the multi-agent version, event type, and session source. It derives a final AgentStatus, using any stored terminal error if present, updates the watched agent status for errors, and if the status is final forwards completion to the parent thread.

Call relations: Session::send_event calls this for every event. It delegates the actual parent message delivery to Session::forward_child_completion_to_parent.

Call graph: calls 2 internal fn (is_final, forward_child_completion_to_parent); called by 1 (send_event); 3 external calls (agent_status_from_event, matches!, Errored).

async fn forward_child_completion_to_parent(
        &self,
        turn_context: &TurnContext,
        parent_thread_id: ThreadId,
        child_agent_path: &codex_protocol::AgentPath,
        status

Purpose: Sends a child-agent completion message back to its parent agent. This is how multi-agent work reports that a spawned child is done.

Data flow: It derives the parent agent path from the child path, formats a completion message for the status, creates an InterAgentCommunication that does not trigger a new turn, sends it through agent_control to the parent thread, and records a trace payload if tracing is enabled.

Call relations: Session::maybe_notify_parent_of_terminal_turn calls this after deciding a child-agent turn reached a final state.

Call graph: calls 3 internal fn (format_inter_agent_completion_message, as_str, new); called by 1 (maybe_notify_parent_of_terminal_turn); 3 external calls (new, debug!, clone).

async fn maybe_mirror_event_text_to_realtime(&self, msg: &EventMsg)

Purpose: Copies suitable event text into an active realtime conversation handoff. This lets normal session events also appear in realtime output streams.

Data flow: It asks whether the EventMsg has text suitable for realtime, checks that a realtime conversation is running, and sends the text through handoff_out, logging only if that fails.

Call relations: Session::send_event calls this after raw event delivery so realtime output stays in sync with the normal event stream.

Call graph: calls 1 internal fn (realtime_text_for_event); called by 1 (send_event); 1 external calls (debug!).

async fn maybe_clear_realtime_handoff_for_event(&self, msg: &EventMsg)

Purpose: Ends the active realtime handoff when a turn completes. This prevents later output from being attached to a finished handoff.

Data flow: It ignores all events except TurnComplete. On completion, it tries to mark handoff output complete and then clears the active handoff state.

Call relations: Session::send_event calls this for every event, but it only acts at turn completion.

Call graph: called by 1 (send_event); 2 external calls (debug!, matches!).

async fn send_event_raw(&self, event: Event)

Purpose: Persists and delivers an already-built event without the higher-level extras done by Session::send_event. It is the lower-level event output path.

Data flow: It wraps the event message as a rollout item, persists it, records the protocol event in the rollout trace, and passes the event to deliver_event_raw.

Call relations: Session::send_event and initial-context code call this when an Event is ready. It delegates the channel send and agent-status update to Session::deliver_event_raw.

Call graph: calls 2 internal fn (deliver_event_raw, persist_rollout_items); called by 2 (build_initial_context, send_event); 1 external calls (vec!).

async fn deliver_event_raw(&self, event: Event)

Purpose: Actually sends an event into the session’s outgoing event channel. It also updates the last known agent status when the event carries one.

Data flow: It receives an Event, derives an AgentStatus from its message if possible and stores it, then sends the event on tx_event. If the receiver is gone, it logs that the event was dropped.

Call relations: Session::send_event_raw calls this after persistence and tracing. Codex::next_event reads from the receiving end of the same channel.

Call graph: called by 1 (send_event_raw); 2 external calls (agent_status_from_event, debug!).

async fn emit_turn_item_started(&self, turn_context: &TurnContext, item: &TurnItem)

Purpose: Emits an event saying a turn item has started. A turn item is a visible unit of work such as user input, model output, or a tool action.

Data flow: It receives the TurnContext and TurnItem, clones the item, stamps the current time in milliseconds, wraps it in ItemStartedEvent, and sends it through Session::send_event.

Call relations: Recording code calls this when it begins tracking a user prompt or response item.

Call graph: calls 2 internal fn (send_event, now_unix_timestamp_ms); called by 2 (record_response_item_and_emit_turn_item, record_user_prompt_and_emit_turn_item); 2 external calls (clone, ItemStarted).

async fn emit_turn_item_completed(
        &self,
        turn_context: &TurnContext,
        item: TurnItem,
    )

Purpose: Emits an event saying a turn item has completed. It also records timing-to-first-model metrics when appropriate.

Data flow: It receives the TurnContext and finished TurnItem, records the turn timing metric, stamps the current time in milliseconds, wraps the item in ItemCompletedEvent, and sends it through Session::send_event.

Call relations: Recording code calls this after a user prompt or response item is fully recorded.

Call graph: calls 3 internal fn (send_event, now_unix_timestamp_ms, record_turn_ttfm_metric); called by 2 (record_response_item_and_emit_turn_item, record_user_prompt_and_emit_turn_item); 1 external calls (ItemCompleted).

async fn persist_execpolicy_amendment(
        &self,
        amendment: &ExecPolicyAmendment,
    ) -> Result<(), ExecPolicyUpdateError>

Purpose: Saves an execution-policy amendment and updates the live execution policy. Execution policy is the rule set that controls command execution permissions.

Data flow: It receives an ExecPolicyAmendment, reads codex_home from session configuration, asks the exec policy service to append the amendment and update its current policy, and returns any update error.

Call relations: Approval flows call this when a user approves a new command-rule change that should persist.

async fn turn_context_for_sub_id(&self, sub_id: &str) -> Option<Arc<TurnContext>>

Purpose: Finds the active turn context with a given submission id. This lets later approval or policy messages attach to the correct turn.

Data flow: It locks active_turn, checks whether an active task exists, compares its turn_context.sub_id with the requested id, and returns a cloned Arc to the TurnContext if it matches.

Call relations: Policy-amendment message recorders call this before injecting a message into the current turn context.

Call graph: called by 2 (record_execpolicy_amendment_message, record_network_policy_amendment_message).

async fn active_turn_context_and_cancellation_token(
        &self,
    ) -> Option<(Arc<TurnContext>, CancellationToken)>

Purpose: Returns the active turn context together with a child cancellation token. A cancellation token is a signal that can stop async work.

Data flow: It locks active_turn, gets the active task if present, clones the TurnContext Arc, creates a child token from the task’s cancellation token, and returns both as an option.

Call relations: Internal control paths use this when they need to operate on or cancel the currently running turn.

Call graph: 1 external calls (clone).

async fn record_execpolicy_amendment_message(
        &self,
        sub_id: &str,
        amendment: &ExecPolicyAmendment,
    )

Purpose: Adds a model-visible message saying an approved command prefix was saved. This keeps the conversation context aware that the user changed execution permissions.

Data flow: It receives a turn id and amendment, formats the approved command prefix, builds an ApprovedCommandPrefixSaved response item, finds the matching turn context, and injects the item without starting a new turn. If no prefix can be formatted, it logs a warning and stops.

Call relations: Execution-policy approval flows call this after persisting an amendment so the active conversation transcript reflects the permission change.

Call graph: calls 4 internal fn (into, new, turn_context_for_sub_id, format_allow_prefixes); 2 external calls (vec!, warn!).

async fn persist_network_policy_amendment(
        &self,
        amendment: &NetworkPolicyAmendment,
        network_approval_context: &NetworkApprovalContext,
    ) -> anyhow::Result<()>

Purpose: Persists a network allow or deny rule and updates the running managed proxy when present. This makes a user-approved network decision take effect immediately and survive later policy reloads.

Data flow: It takes a proxy-refresh lock, validates that the amendment host matches the approved host, reads codex_home, converts the amendment into an execution-policy network rule, updates the live proxy allowlist or denylist if a proxy is running, then appends the network rule to the execution policy service.

Call relations: Network approval flows call this when the user chooses to save a network rule. It uses Session::validated_network_policy_amendment_host to guard against saving a rule for the wrong host.

Call graph: calls 1 internal fn (execpolicy_network_rule_amendment); 1 external calls (validated_network_policy_amendment_host).

fn validated_network_policy_amendment_host(
        amendment: &NetworkPolicyAmendment,
        network_approval_context: &NetworkApprovalContext,
    ) -> anyhow::Result<String>

Purpose: Checks that a network policy amendment applies to the same host the user approved. This prevents a saved rule from silently targeting a different domain.

Data flow: It normalizes the approved host and amendment host, compares them, returns the normalized approved host on match, or returns an error describing the mismatch.

Call relations: Session::persist_network_policy_amendment calls this before changing the live proxy or persistent execution policy.

Call graph: 2 external calls (anyhow!, normalize_host).

async fn record_network_policy_amendment_message(
        &self,
        sub_id: &str,
        amendment: &NetworkPolicyAmendment,
    )

Purpose: Adds a model-visible message saying a network rule was saved. This lets the ongoing turn know that network permissions changed.

Data flow: It receives a turn id and NetworkPolicyAmendment, builds a NetworkRuleSaved response item, finds the active turn context for the id, and injects the message without starting a new turn.

Call relations: Network approval flows call this after saving a rule, similar to how command-policy amendments are recorded.

Call graph: calls 3 internal fn (into, new, turn_context_for_sub_id); 1 external calls (vec!).

async fn request_command_approval(
        &self,
        turn_context: &TurnContext,
        call_id: String,
        approval_id: Option<String>,
        command: Vec<String>,
        cwd: AbsoluteP

Purpose: Asks the client or reviewer whether a proposed shell command may run. It records a pending approval first, so the later answer can be delivered back to the task that is waiting.

Data flow: It receives the turn, command details, working directory, reason, optional network and permission details, and possible decisions. It stores a reply channel under the approval id, builds an approval request event with a timestamp and parsed command, sends it out, then waits for the answer; if the answer path closes, it returns Abort.

Call relations: This is the request side of the approval flow. Later, Session::notify_approval removes the matching pending approval and sends the ReviewDecision back through the waiting channel.

Call graph: calls 3 internal fn (send_event, now_unix_timestamp_ms, parse_command); 3 external calls (channel, ExecApprovalRequest, warn!).

async fn request_patch_approval(
        &self,
        turn_context: &TurnContext,
        call_id: String,
        changes: HashMap<PathBuf, FileChange>,
        reason: Option<String>,
        gran

Purpose: Asks whether a proposed file patch may be applied. It lets the assistant pause before changing files and wait for a human or reviewer decision.

Data flow: It receives the call id, file changes, reason, and optional grant root. It stores a reply channel in the active turn, sends an ApplyPatchApprovalRequest event, and returns the receiver so the caller can await the decision.

Call relations: Like command approval, this creates a pending approval entry before notifying the client. Session::notify_approval is the matching completion path that resolves the waiting receiver.

Call graph: calls 2 internal fn (send_event, now_unix_timestamp_ms); 3 external calls (channel, ApplyPatchApprovalRequest, warn!).

async fn request_permissions_for_environment(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        call_id: String,
        args: RequestPermissionsArgs,
        environment: Tur

Purpose: Requests extra permissions for a specific turn environment, such as broader file or network access. It also enforces safety rules around when permission requests are allowed and how much can be granted.

Data flow: It receives the requested permissions, environment, turn, call id, and cancellation token. It may immediately return empty permissions if policy forbids asking, may route the request through Guardian review, or may send a RequestPermissions event and wait for a response; before returning, it normalizes the response and records any granted permissions.

Call relations: Session::request_permissions_for_cwd calls this after choosing an environment and setting its current directory. It uses Session::normalize_request_permissions_response to limit grants and Session::record_granted_request_permissions_for_turn to remember approved permissions.

Call graph: calls 3 internal fn (record_granted_request_permissions_for_turn, send_event, now_unix_timestamp_ms); called by 1 (request_permissions_for_cwd); 12 external calls (clone, clone, normalize_request_permissions_response, default, new_guardian_review_id, routes_approval_to_guardian, spawn_approval_request_review, channel, RequestPermissions, clone (+2 more)).

async fn request_permissions_for_cwd(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        call_id: String,
        args: RequestPermissionsArgs,
        cwd: AbsolutePathBuf,

Purpose: Convenience wrapper that asks for permissions relative to a given current working directory. It finds the right environment first, then delegates the real request.

Data flow: It receives permission request arguments, a directory, and a cancellation token. It selects the named environment or the primary one, replaces that environment’s current directory with the provided path, and returns the result from Session::request_permissions_for_environment; if no environment exists, it returns an empty turn-scoped grant.

Call relations: This is a small adapter in front of Session::request_permissions_for_environment. It exists so callers that only know a working directory do not have to build a full environment selection themselves.

Call graph: calls 2 internal fn (request_permissions_for_environment, from_abs_path); 1 external calls (default).

async fn request_user_input(
        &self,
        turn_context: &TurnContext,
        call_id: String,
        args: RequestUserInputArgs,
    ) -> Option<RequestUserInputResponse>

Purpose: Asks the user one or more questions during a turn and waits for their response. This is used when the assistant needs information before it can continue.

Data flow: It receives a call id and user-input request arguments. It stores a response channel keyed by the turn id, marks that user input was requested during the turn, sends a RequestUserInput event, then waits for the response and returns it if one arrives.

Call relations: This is paired with Session::notify_user_input_response. The request function creates the pending slot; the notify function fills it when the client replies.

Call graph: calls 1 internal fn (send_event); 3 external calls (channel, RequestUserInput, warn!).

async fn notify_user_input_response(
        &self,
        sub_id: &str,
        response: RequestUserInputResponse,
    )

Purpose: Delivers a user-input answer back to the turn that asked for it. It prevents replies from being lost by looking up the waiting request by turn id.

Data flow: It receives a turn id and response. It removes the matching pending user-input sender from active turn state, sends the response through it, or logs a warning if nothing was waiting.

Call relations: This completes the flow started by Session::request_user_input. It is called when an outside client reports the user’s answer.

Call graph: 1 external calls (warn!).

async fn notify_request_permissions_response(
        &self,
        call_id: &str,
        response: RequestPermissionsResponse,
    )

Purpose: Delivers a permission-request answer back to the waiting task. It also checks that the answer is safe before recording or returning it.

Data flow: It receives a call id and response. It removes the pending permission request, converts the environment directory to a local path, normalizes the response so it cannot exceed what was requested, records granted permissions, and sends the final response back through the waiting channel.

Call relations: This completes the non-Guardian path started by Session::request_permissions_for_environment. It uses Session::normalize_request_permissions_response and Session::record_granted_request_permissions_for_turn before waking the requester.

Call graph: calls 1 internal fn (record_granted_request_permissions_for_turn); 3 external calls (normalize_request_permissions_response, default, warn!).

fn normalize_request_permissions_response(
        requested_permissions: RequestPermissionProfile,
        response: RequestPermissionsResponse,
        cwd: &Path,
    ) -> RequestPermissionsRespons

Purpose: Cleans up a permission response so it follows the rules. Most importantly, it prevents granting permissions that were not actually requested.

Data flow: It receives the requested permissions, the proposed response, and the working directory. It rejects invalid session-wide strict auto-review grants, leaves empty grants alone, and otherwise intersects the requested and granted profiles, returning a safer response.

Call relations: Session::request_permissions_for_environment and Session::notify_request_permissions_response both call this before recording or returning granted permissions.

Call graph: calls 1 internal fn (intersect_permission_profiles); 3 external calls (default, into, matches!).

async fn record_granted_request_permissions_for_turn(
        &self,
        response: &RequestPermissionsResponse,
        environment_id: &str,
        originating_turn_state: Option<&Arc<Mutex<crat

Purpose: Stores newly granted permissions in the right place: either only for the current turn or for the whole session. This lets later tool calls know what has already been approved.

Data flow: It receives a permission response, environment id, and optional turn state. If the grant is empty it does nothing; turn-scoped grants go into the active turn state, while session-scoped grants go into session state.

Call relations: It is called after permission responses are normalized in Session::request_permissions_for_environment and Session::notify_request_permissions_response.

Call graph: called by 2 (notify_request_permissions_response, request_permissions_for_environment).

async fn granted_turn_permissions(
        &self,
        environment_id: &str,
    ) -> Option<AdditionalPermissionProfile>

Purpose: Looks up permissions granted only for the current turn and environment. Callers use this to decide whether a tool action is already allowed.

Data flow: It receives an environment id. It reads the active turn state, asks for that environment’s granted permissions, and returns them if there is an active turn and a grant exists.

Call relations: This is a read-side helper for the permission system. It reflects grants recorded by Session::record_granted_request_permissions_for_turn.

async fn strict_auto_review_enabled_for_turn(&self) -> bool

Purpose: Reports whether the current turn has strict automatic review enabled. This flag affects how later actions are checked during the same turn.

Data flow: It reads the active turn state. If there is no active turn it returns false; otherwise it returns the turn state’s strict-auto-review flag.

Call relations: The flag can be enabled when Session::record_granted_request_permissions_for_turn records a turn-scoped response with strict auto-review.

async fn granted_session_permissions(
        &self,
        environment_id: &str,
    ) -> Option<AdditionalPermissionProfile>

Purpose: Looks up permissions that were granted for the whole session in a given environment. These grants survive beyond a single turn.

Data flow: It receives an environment id, reads session state, and returns any saved permission profile for that environment.

Call relations: This is the read-side companion to session-scoped writes in Session::record_granted_request_permissions_for_turn.

async fn notify_dynamic_tool_response(&self, call_id: &str, response: DynamicToolResponse)

Purpose: Delivers a response from a dynamically provided tool back to the waiting turn. It matches the response by call id.

Data flow: It receives a call id and tool response. It removes the pending dynamic-tool sender from active turn state, sends the response through it, or logs a warning if no matching call is pending.

Call relations: This is the completion path for a dynamic tool call that was earlier registered in turn state elsewhere in the session flow.

Call graph: 1 external calls (warn!).

async fn notify_approval(&self, approval_id: &str, decision: ReviewDecision)

Purpose: Delivers an approval decision, such as approve, deny, or abort, back to the command or patch request that is waiting. It is the common reply path for approval prompts.

Data flow: It receives an approval id and decision. It removes the matching pending approval from active turn state and sends the decision through the stored channel, or logs a warning if there is no match.

Call relations: This completes approvals started by Session::request_command_approval and Session::request_patch_approval.

Call graph: 1 external calls (warn!).

fn prepare_conversation_items_for_history(
        &self,
        turn_context: &TurnContext,
        items: &'a [ResponseItem],
    ) -> Cow<'a, [ResponseItem]>

Purpose: Prepares response items before they are stored in conversation history. When image resizing is enabled, it copies and adjusts items so stored history uses the prepared form.

Data flow: It receives a turn and a slice of response items. If the ResizeAllImages feature is off, it returns a borrowed view of the original items; if on, it clones the items, prepares them, and returns the owned copy.

Call relations: Session::record_conversation_items and Session::record_inter_agent_communication call this before adding items to history and persistence.

Call graph: calls 1 internal fn (prepare_response_items); called by 2 (record_conversation_items, record_inter_agent_communication); 3 external calls (Borrowed, Owned, to_vec).

fn response_item_from_user_input(
        &self,
        turn_context: &TurnContext,
        input: Vec<UserInput>,
    ) -> ResponseItem

Purpose: Converts raw user input into the model-facing response item format. It decides whether image processing happens now or is deferred, based on the image-resizing feature.

Data flow: It receives a turn and user input list. It chooses local image preparation mode, converts the user input into a ResponseInputItem, wraps it as a ResponseItem, and returns it.

Call relations: Session::record_user_prompt_and_emit_turn_item calls this before recording the user message in conversation history.

Call graph: calls 2 internal fn (from_user_input, from); called by 1 (record_user_prompt_and_emit_turn_item).

async fn record_conversation_items(
        &self,
        turn_context: &TurnContext,
        items: &[ResponseItem],
    )

Purpose: Adds model-visible items to the conversation record, persists them to the rollout transcript, and emits them to the client as raw response items. This keeps memory, disk, and client view aligned.

Data flow: It receives a turn and response items. It prepares them for history, records them in session state using the turn’s truncation policy, persists them as rollout response items, and sends each raw item event.

Call relations: Several higher-level flows call this, including recording user prompts, model response items, and context updates. It delegates persistence to Session::persist_rollout_response_items and event emission to Session::send_raw_response_items.

Call graph: calls 3 internal fn (persist_rollout_response_items, prepare_conversation_items_for_history, send_raw_response_items); called by 3 (record_context_updates_and_set_reference_context_item, record_response_item_and_emit_turn_item, record_user_prompt_and_emit_turn_item); 2 external calls (as_ref, iter).

async fn record_inter_agent_communication(
        &self,
        turn_context: &TurnContext,
        communication: InterAgentCommunication,
    )

Purpose: Records a message exchanged between agents as part of the conversation. This makes inter-agent communication visible to history and durable rollout logs.

Data flow: It receives an InterAgentCommunication value. It converts it to a model input item, prepares it for history, records it in state, persists the communication as a rollout item, and emits the raw response item.

Call relations: It follows the same history path as Session::record_conversation_items, but persists a specialized InterAgentCommunication rollout item.

Call graph: calls 4 internal fn (persist_rollout_items, prepare_conversation_items_for_history, send_raw_response_items, to_model_input_item); 2 external calls (InterAgentCommunication, from_ref).

async fn maybe_warn_on_server_model_mismatch(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        server_model: String,
    ) -> bool

Purpose: Checks whether the server used a different model than the one requested and warns the client if so. This is important because model rerouting changes what the user is actually getting.

Data flow: It receives the server-reported model. It compares it case-insensitively with the requested model; if they match it returns false, and if not it sends a ModelReroute event plus a warning message and returns true.

Call relations: This is used after server model information is known. It hands off user-visible reporting through Session::send_event.

Call graph: calls 1 internal fn (send_event); 5 external calls (format!, info!, ModelReroute, Warning, warn!).

async fn emit_model_verification(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        verifications: Vec<ModelVerification>,
    )

Purpose: Sends model verification information to the client. This lets the UI or caller show evidence about the model used for a turn.

Data flow: It receives a list of model verifications, wraps them in a ModelVerification event, and sends the event for the current turn.

Call relations: This is a direct event-emission helper built on Session::send_event.

Call graph: calls 1 internal fn (send_event); 1 external calls (ModelVerification).

async fn emit_turn_moderation_metadata(
        self: &Arc<Self>,
        turn_context: &Arc<TurnContext>,
        metadata: TurnModerationMetadataEvent,
    )

Purpose: Sends moderation-related metadata for a turn to the client. This exposes safety or policy metadata without changing the conversation history.

Data flow: It receives a moderation metadata event value, wraps it as the corresponding session event, and sends it to the client.

Call relations: This is another focused wrapper around Session::send_event for turn metadata.

Call graph: calls 1 internal fn (send_event); 1 external calls (TurnModerationMetadata).

async fn replace_history(
        &self,
        items: Vec<ResponseItem>,
        reference_context_item: Option<TurnContextItem>,
    )

Purpose: Replaces the in-memory conversation history with a new list of response items. This is used when the session needs to reset its model context baseline.

Data flow: It receives replacement items and an optional reference context item. It locks session state and swaps the stored history and reference context.

Call relations: This is a low-level state update used by higher-level context reconstruction or compaction flows.

async fn replace_compacted_history(
        &self,
        items: Vec<ResponseItem>,
        reference_context_item: Option<TurnContextItem>,
        compacted_item: CompactedItem,
    )

Purpose: Replaces history after compaction and records that compaction in the rollout transcript. Compaction shrinks old context into a smaller form so the conversation can continue within the model’s limits.

Data flow: It receives replacement history, an optional reference context item, and the compacted item. It updates state, persists the compacted rollout item and reference context when present, then queues a session-start source that says the next start came from compaction.

Call relations: It uses Session::persist_rollout_items to make the compaction durable and updates state for later session-start hooks.

Call graph: calls 1 internal fn (persist_rollout_items); 2 external calls (Compacted, TurnContext).

async fn persist_rollout_response_items(&self, items: &[ResponseItem])

Purpose: Converts regular response items into rollout items and persists them. A rollout is the durable transcript used to recover or inspect a session later.

Data flow: It receives response items, clones each into a RolloutItem::ResponseItem, and passes the list to Session::persist_rollout_items.

Call relations: Session::record_conversation_items calls this after updating in-memory history.

Call graph: calls 1 internal fn (persist_rollout_items); called by 1 (record_conversation_items); 1 external calls (iter).

fn enabled(&self, feature: Feature) -> bool

Purpose: Answers whether a feature flag is enabled for this session. Feature flags turn optional behavior on or off.

Data flow: It receives a Feature value, checks the session’s managed feature set, and returns true or false.

Call relations: This is a small public convenience around the session’s feature store.

fn features(&self) -> ManagedFeatures

Purpose: Returns the session’s managed feature set. Callers use it when they need more than a single yes-or-no feature check.

Data flow: It reads the session’s feature holder, clones it, and returns the clone.

Call relations: This exposes feature configuration to other session code without giving them direct ownership of the original field.

async fn collaboration_mode(&self) -> CollaborationMode

Purpose: Returns the current collaboration mode, which describes how the assistant should work with the user or other agents. This may affect instructions and behavior.

Data flow: It locks session state, reads the session configuration’s collaboration mode, clones it, and returns it.

Call relations: This is a read helper for code that needs the current collaboration policy.

fn multi_agent_version(&self) -> Option<MultiAgentVersion>

Purpose: Returns the multi-agent protocol version already chosen for this session, if one has been set. This keeps a session from switching versions halfway through.

Data flow: It reads the once-initialized multi-agent version slot and returns a copied value if present.

Call relations: Session::resolve_multi_agent_version_for_model calls this before deciding a new version.

Call graph: called by 1 (resolve_multi_agent_version_for_model).

fn set_multi_agent_version_if_unset(
        &self,
        multi_agent_version: MultiAgentVersion,
    ) -> MultiAgentVersion

Purpose: Sets the session’s multi-agent version only if it has not already been chosen. If another value was already set, that existing value wins.

Data flow: It receives a proposed version, initializes the stored value if empty, and returns the stored version.

Call relations: Session::resolve_multi_agent_version_for_model calls this after selecting the best version from model or config.

Call graph: called by 1 (resolve_multi_agent_version_for_model).

fn resolve_multi_agent_version_for_model(
        &self,
        model_info: &ModelInfo,
        config: &Config,
    ) -> MultiAgentVersion

Purpose: Chooses the multi-agent version for the session using the model’s preference first, then configuration defaults. It also locks that choice in for future calls.

Data flow: It receives model info and config. If a version is already set it returns it; otherwise it selects the model-provided version or config-derived version and stores it if unset.

Call relations: It coordinates Session::multi_agent_version and Session::set_multi_agent_version_if_unset.

Call graph: calls 2 internal fn (multi_agent_version, set_multi_agent_version_if_unset).

async fn send_raw_response_items(&self, turn_context: &TurnContext, items: &[ResponseItem])

Purpose: Sends each response item to the client as a raw event. This gives consumers a faithful stream of the model-visible conversation items.

Data flow: It receives a turn and response items. For each item, it clones the item, wraps it in a RawResponseItem event, and sends it.

Call relations: Session::record_conversation_items and Session::record_inter_agent_communication call this after recording history.

Call graph: calls 1 internal fn (send_event); called by 2 (record_conversation_items, record_inter_agent_communication); 1 external calls (RawResponseItem).

async fn build_initial_context(
        &self,
        turn_context: &TurnContext,
    ) -> Vec<ResponseItem>

Purpose: Builds the initial set of model-visible context messages for a turn or new context window. These messages tell the model about permissions, environment, apps, skills, plugins, personality, collaboration mode, and other session facts.

Data flow: It reads session state, turn configuration, feature flags, connectors, skills, plugins, extension contributors, shell information, and environment data. It gathers text sections into developer and contextual-user messages, emits warnings when needed, and returns response items that should be inserted into history.

Call relations: Session::maybe_start_new_context_window and Session::record_context_updates_and_set_reference_context_item call this when full context needs to be injected. It is the main assembler for the session’s starting prompt material.

Call graph: calls 19 internal fn (list_accessible_and_enabled_connectors_from_manager, from_connectors, from_plugins, from, from_collaboration_mode, from_turn_context, new, new, build_contextual_user_message, build_developer_update_item (+9 more)); called by 2 (maybe_start_new_context_window, record_context_updates_and_set_reference_context_item); 9 external calls (new, new, with_capacity, with_capacity, build_available_skills, default_skill_metadata_budget, is_guardian_reviewer_source, Warning, vec!).

async fn persist_rollout_items(&self, items: &[RolloutItem])

Purpose: Appends rollout items to the live thread transcript if one exists. This is the durable write path for history and session events that should survive later inspection or recovery.

Data flow: It receives rollout items. It asks for the live thread, appends the items when available, and logs an error if the append fails.

Call relations: Many history and context flows call this, including response persistence, compaction, initial history, context updates, and raw event persistence.

Call graph: calls 1 internal fn (live_thread); called by 7 (maybe_start_new_context_window, persist_rollout_response_items, record_context_updates_and_set_reference_context_item, record_initial_history, record_inter_agent_communication, replace_compacted_history, send_event_raw); 1 external calls (error!).

async fn clone_history(&self) -> ContextManager

Purpose: Returns a copy of the current conversation history manager. This lets other code inspect or estimate history without holding the session lock.

Data flow: It locks session state, clones the history object, and returns the clone.

Call relations: Session::recompute_token_usage and rollout reconstruction code use this to work from a snapshot.

Call graph: called by 2 (apply_rollout_reconstruction, recompute_token_usage).

async fn current_window_id(&self) -> String

Purpose: Builds a human-readable id for the current context window. It combines the thread id with the auto-compaction window number.

Data flow: It reads session state for the current window number, combines it with the thread id, and returns a string like thread:window.

Call relations: This is a small reporting helper for code that needs to identify the active context window.

Call graph: 1 external calls (format!).

async fn advance_auto_compact_window_id(&self) -> u64

Purpose: Moves the auto-compaction window counter forward. This marks that a new context window should be identified separately from the previous one.

Data flow: It locks mutable session state, advances the stored window id, and returns the new number.

Call relations: This supports the broader context-compaction lifecycle.

async fn request_new_context_window(&self)

Purpose: Marks that the session should start a fresh context window soon. It does not rebuild immediately; it sets a request flag in state.

Data flow: It locks session state and records that a new context window has been requested.

Call relations: Session::maybe_start_new_context_window later consumes this request and performs the rebuild.

async fn maybe_start_new_context_window(
        &self,
        turn_context: &TurnContext,
    ) -> Option<u64>

Purpose: Starts a new context window if one was requested. This resets model-visible history to fresh context messages and records the compaction event.

Data flow: It asks state whether a new window should start. If not, it returns None; if yes, it builds initial context, replaces history, persists a compacted item plus turn context, queues a compact session-start source, recomputes token usage, and returns the new window id.

Call relations: It consumes requests made by Session::request_new_context_window and relies on Session::build_initial_context, Session::persist_rollout_items, and Session::recompute_token_usage.

Call graph: calls 4 internal fn (build_initial_context, persist_rollout_items, recompute_token_usage, to_turn_context_item); 3 external calls (new, Compacted, TurnContext).

async fn reference_context_item(&self) -> Option<TurnContextItem>

Purpose: Returns the current reference context item used as the baseline for context diffs. This helps decide what has changed between turns.

Data flow: It locks session state, clones or retrieves the stored reference context item, and returns it.

Call relations: This is a read helper for context-management code.

async fn record_context_updates_and_set_reference_context_item(
        &self,
        turn_context: &TurnContext,
    )

Purpose: Adds the right context messages for a turn and updates the stored baseline used for future diffs. On the first turn it injects full context; later it only records changes.

Data flow: It reads the old reference context item. If none exists it builds initial context; otherwise it builds settings-update items, records any resulting conversation items, persists the current turn context item, and updates state’s reference context item.

Call relations: It uses Session::build_initial_context for full setup, build_settings_update_items for steady-state diffs, Session::record_conversation_items for model-visible updates, and Session::persist_rollout_items for durable turn context.

Call graph: calls 5 internal fn (build_initial_context, build_settings_update_items, persist_rollout_items, record_conversation_items, to_turn_context_item); 1 external calls (TurnContext).

async fn update_token_usage_info(
        &self,
        turn_context: &TurnContext,
        token_usage: Option<&TokenUsage>,
    )

Purpose: Updates token usage information and tells the client the latest count. Tokens are the chunks of text the model consumes and produces.

Data flow: It receives optional token usage from a model response. It records the usage in state, then sends a TokenCount event with current token and rate-limit data.

Call relations: It coordinates Session::record_token_usage_info and Session::send_token_count_event.

Call graph: calls 2 internal fn (record_token_usage_info, send_token_count_event).

async fn record_token_usage_info(
        &self,
        turn_context: &TurnContext,
        token_usage: Option<&TokenUsage>,
    )

Purpose: Stores token usage from the latest model call and notifies extension contributors. This keeps internal accounting and plugin-like observers up to date.

Data flow: If token usage is present, it updates session token info using the turn’s model context window, may update auto-compaction prefill data, then passes the resulting token info to registered token-usage contributors.

Call relations: Session::update_token_usage_info calls this before sending the user-visible token-count event.

Call graph: calls 1 internal fn (model_context_window); called by 1 (update_token_usage_info); 1 external calls (matches!).

async fn recompute_token_usage(&self, turn_context: &TurnContext)

Purpose: Re-estimates token usage from the current saved history when there is no fresh server count, such as after compaction. This gives the client and auto-compaction logic a reasonable updated count.

Data flow: It clones history, reads base instructions, estimates token count, writes a synthetic token usage record into state, updates auto-compaction prefill estimates, and sends a token-count event.

Call relations: Session::maybe_start_new_context_window calls this after replacing history.

Call graph: calls 5 internal fn (clone_history, get_base_instructions, send_token_count_event, set_auto_compact_window_estimated_prefill_for_scope, model_context_window); called by 1 (maybe_start_new_context_window); 1 external calls (default).

async fn update_rate_limits(
        &self,
        turn_context: &TurnContext,
        new_rate_limits: RateLimitSnapshot,
    )

Purpose: Stores new rate-limit information and sends an updated token-count event. Rate limits describe how much usage is still allowed by the service.

Data flow: It receives a rate-limit snapshot, records it in session state, then emits the combined token and rate-limit status.

Call relations: It coordinates Session::record_rate_limits_info and Session::send_token_count_event.

Call graph: calls 2 internal fn (record_rate_limits_info, send_token_count_event).

async fn record_rate_limits_info(&self, new_rate_limits: RateLimitSnapshot)

Purpose: Stores the latest rate-limit snapshot in session state. This separates the state write from later event emission.

Data flow: It receives a RateLimitSnapshot, locks mutable session state, and replaces the stored rate-limit data.

Call relations: Session::update_rate_limits calls this before notifying the client.

Call graph: called by 1 (update_rate_limits).

async fn mcp_dependency_prompted(&self) -> HashSet<String>

Purpose: Returns the set of MCP dependencies that have already prompted the user. MCP here means Model Context Protocol, a way to connect external tools or services.

Data flow: It locks session state, reads the recorded dependency names, and returns the set.

Call relations: This is a read helper paired with Session::record_mcp_dependency_prompted.

async fn record_mcp_dependency_prompted(&self, names: I)

Purpose: Records MCP dependency names that have already shown a prompt. This avoids prompting repeatedly for the same dependency.

Data flow: It receives an iterable collection of names, locks session state, and adds them to the prompted set.

Call relations: This is the write-side companion to Session::mcp_dependency_prompted.

async fn set_server_reasoning_included(&self, included: bool)

Purpose: Records whether server-provided reasoning was included. This affects how later state or reporting understands the response stream.

Data flow: It receives a boolean, locks session state, and stores that boolean.

Call relations: This is a simple state-setting helper used by response-processing code elsewhere in the session.

async fn send_token_count_event(&self, turn_context: &TurnContext)

Purpose: Sends the current token and rate-limit status to the client. This keeps the UI informed about context usage and service limits.

Data flow: It reads token info and rate limits from state, wraps them in a TokenCount event, and sends it for the turn.

Call relations: Session::update_token_usage_info, Session::recompute_token_usage, Session::update_rate_limits, and Session::set_total_tokens_full call this after changing accounting data.

Call graph: calls 1 internal fn (send_event); called by 4 (recompute_token_usage, set_total_tokens_full, update_rate_limits, update_token_usage_info); 1 external calls (TokenCount).

async fn set_total_tokens_full(&self, turn_context: &TurnContext)

Purpose: Marks token usage as full for the model’s context window and reports that to the client. This is used when the session knows the context is at capacity.

Data flow: It checks the turn’s model context window. If present, it updates state to say token usage is full, then sends a token-count event.

Call relations: It uses Session::send_token_count_event for the reporting side.

Call graph: calls 2 internal fn (send_token_count_event, model_context_window).

async fn record_response_item_and_emit_turn_item(
        &self,
        turn_context: &TurnContext,
        response_item: ResponseItem,
    )

Purpose: Records one response item and emits higher-level turn-item lifecycle events when the item can be interpreted that way. This keeps history and UI activity in sync.

Data flow: It receives a response item, records it into conversation history, then tries to parse it into a turn item. If parsing succeeds, it emits started and completed events for that turn item.

Call relations: It builds on Session::record_conversation_items and the turn-item emitters elsewhere in the session.

Call graph: calls 3 internal fn (emit_turn_item_completed, emit_turn_item_started, record_conversation_items); 2 external calls (parse_turn_item, from_ref).

async fn record_user_prompt_and_emit_turn_item(
        &self,
        turn_context: &TurnContext,
        input: &[UserInput],
        client_id: Option<String>,
    )

Purpose: Records the user’s prompt and emits the corresponding user-message turn item. It preserves UI-only spans that would be lost if it emitted from the stored response item alone.

Data flow: It receives user input and an optional client id. It converts input to a response item for history, records it, builds a UserMessage turn item with the client id, emits started and completed events, and ensures the rollout transcript exists.

Call relations: It uses Session::response_item_from_user_input and Session::record_conversation_items before sending turn-item events.

Call graph: calls 6 internal fn (emit_turn_item_completed, emit_turn_item_started, ensure_rollout_materialized, record_conversation_items, response_item_from_user_input, new); 3 external calls (to_vec, UserMessage, from_ref).

async fn notify_stream_error(
        &self,
        turn_context: &TurnContext,
        message: impl Into<String>,
        codex_error: CodexErr,
    )

Purpose: Reports that the response stream disconnected or failed. It includes both a user-facing message and technical details from the Codex error.

Data flow: It receives a message and CodexErr. It extracts a status code and detail string, wraps them in a StreamError event, and sends it to the client.

Call relations: This is a focused error-reporting helper built on Session::send_event.

Call graph: calls 2 internal fn (send_event, http_status_code_value); 3 external calls (into, to_string, StreamError).

async fn steer_input(
        &self,
        input: Vec<UserInput>,
        additional_context: BTreeMap<String, AdditionalContextEntry>,
        expected_turn_id: Option<&str>,
        client_user_me

Purpose: Adds new user steering input to an active regular turn. Steering lets a user guide an in-progress answer, but only when the current turn type supports it.

Data flow: It receives user input, extra context, optional expected turn id, optional client message id, and optional client metadata. It validates that a regular active turn exists and matches the expected id, rejects empty input, merges extra context into state, attaches metadata when present, queues context items plus user input, and returns the active turn id.

Call relations: It writes into the input queue for the active turn. It rejects review and compact turns because those flows are not steerable.

Call graph: 1 external calls (NoActiveTurn).

async fn record_memory_citation_for_turn(&self, sub_id: &str)

Purpose: Marks that a turn used or cited memory. This lets later reporting know the turn involved memory content.

Data flow: It receives a turn id, asks the input queue for that turn’s state, and if found sets a has_memory_citation flag to true.

Call relations: This is a small state update tied to the active turn lookup maintained by the input queue.

async fn interrupt_task(self: &Arc<Self>)

Purpose: Interrupts current work, aborting active tasks if any. If there was no active turn, it cancels MCP startup instead.

Data flow: It logs the interrupt, checks whether an active turn exists, aborts all tasks with an Interrupted reason, and cancels MCP startup only when there was no active turn.

Call relations: This is an external control path for stopping work. It calls broader abort and startup-cancel routines defined elsewhere in the session.

Call graph: 1 external calls (info!).

fn hooks(&self) -> Arc<Hooks>

Purpose: Returns the current hook runner configuration. Hooks are user or plugin commands that run around session events.

Data flow: It loads the current Hooks object from shared services and returns it in an Arc, which is a thread-safe shared pointer.

Call relations: This exposes hook services to code that needs to run or inspect hooks.

fn user_shell(&self) -> Arc<shell::Shell>

Purpose: Returns the shell configuration for the user’s environment. The shell is needed when building prompts or running hook commands in a familiar way.

Data flow: It clones the shared shell pointer from services and returns it.

Call relations: Session::build_initial_context and build_settings_update_items use this when they need shell-aware environment context.

Call graph: called by 2 (build_initial_context, build_settings_update_items); 1 external calls (clone).

async fn current_rollout_path(&self) -> anyhow::Result<Option<PathBuf>>

Purpose: Returns the local filesystem path to the current rollout transcript, if there is one. This lets hooks or other tools know where the transcript lives.

Data flow: It asks for the live thread. If none exists it returns Ok(None); otherwise it asks the live thread for its local rollout path and converts any error into anyhow’s general error type.

Call relations: Session::hook_transcript_path calls this after ensuring the rollout has been materialized.

Call graph: calls 1 internal fn (live_thread); called by 1 (hook_transcript_path).

async fn hook_transcript_path(&self) -> Option<PathBuf>

Purpose: Provides hooks with the transcript path, creating the rollout file first if needed. If the path cannot be read, it logs a warning and returns nothing.

Data flow: It ensures the rollout transcript is materialized, calls Session::current_rollout_path, and returns the path on success or None on error.

Call relations: This is the hook-facing wrapper around Session::current_rollout_path.

Call graph: calls 2 internal fn (current_rollout_path, ensure_rollout_materialized); 1 external calls (warn!).

async fn take_pending_session_start_source(
        &self,
    ) -> Option<codex_hooks::SessionStartSource>

Purpose: Takes and clears the pending reason for a session start. This tells hook or lifecycle code why the next session start event is happening.

Data flow: It locks mutable session state, removes the pending SessionStartSource value, and returns it if one was queued.

Call relations: Compaction flows such as Session::replace_compacted_history and Session::maybe_start_new_context_window queue this value for later consumption.

fn show_raw_agent_reasoning(&self) -> bool

Purpose: Reports whether raw agent reasoning should be shown. This controls how much internal reasoning detail is exposed in outgoing events.

Data flow: It reads a boolean from services and returns it.

Call relations: Session::send_event calls this when deciding how to format or filter outgoing reasoning-related data.

Call graph: called by 1 (send_event).

fn emit_subagent_session_started(
    analytics_events_client: &AnalyticsEventsClient,
    client_metadata: AppServerClientMetadata,
    session_id: SessionId,
    thread_id: ThreadId,
    parent_thre

Purpose: Sends an analytics event when a subagent thread starts. This helps the product understand when and how subagents are being used.

Data flow: It receives analytics client, inherited client metadata, session and thread ids, thread configuration, and subagent source. If client name or version is missing it logs a warning and stops; otherwise it builds a SubAgentThreadStartedInput with ids, model, source, time, and client details, then tracks it.

Call relations: run_codex_thread_interactive calls this when starting an interactive subagent thread.

Call graph: calls 1 internal fn (track_subagent_thread_started); called by 1 (run_codex_thread_interactive); 4 external calls (now, to_string, to_string, warn!).

async fn build_hooks_for_config(
    config: &Config,
    plugins_manager: &PluginsManager,
    environment: Option<&TurnEnvironment>,
) -> Hooks

Purpose: Builds a Hooks object from the current configuration, plugins, and optional turn environment. This decides which notification commands and plugin hook sources are active.

Data flow: It receives config, plugin manager, and optional environment. It derives shell program and arguments when an environment shell exists, loads plugins for the config, gathers hook sources and warnings, and constructs Hooks with feature flags, trust settings, config layers, shell data, and legacy notify settings.

Call relations: refresh_runtime_config calls this when runtime configuration changes, so hook behavior matches the latest config and plugins.

Call graph: calls 2 internal fn (plugins_for_config, new); called by 1 (refresh_runtime_config); 1 external calls (plugins_config_input).

fn cwd(&self) -> &AbsolutePathBuf

Purpose: Returns the session’s fallback current working directory. This is the directory used when a turn does not choose a more specific environment.

Data flow: It reads the legacy_fallback_cwd stored inside the session’s environment selections and returns it by reference. Nothing is changed.

Call relations: Startup code and configuration-building code ask this for the session’s working directory. Permission helpers also use it when turning permission settings into sandbox rules, because file access rules often depend on the current project directory.

Call graph: called by 4 (new, apply, sandbox_policy, build_effective_session_config).

fn environment_selections(&self) -> &[TurnEnvironmentSelection]

Purpose: Returns the list of environment choices attached to the thread. These selections tell the system which runtime environments, such as local shells or other configured environments, are available for turns.

Data flow: It reads the environments field and returns the stored selection list. It does not copy or modify the selections.

Call relations: Session startup uses this to apply the thread’s environments before resolving the actual runtime snapshot. Other environment-resolution code also uses it when it needs to rebuild what environments a configuration represents.

Call graph: called by 2 (new, resolved_environments_for_configuration).

fn codex_home(&self) -> &AbsolutePathBuf

Purpose: Returns the directory where Codex stores state for this session or installation. Callers use it when they need the filesystem location for Codex-owned files.

Data flow: It reads the codex_home path from the configuration and returns a reference to it. There are no side effects.

Call relations: The function is a simple accessor. The provided call graph does not show a caller, but it exists so other session code can ask for the Codex state directory without reaching into the struct directly.

fn permission_profile_state(&self) -> &PermissionProfileState

Purpose: Returns the full permission-profile state for the session. This is the source of truth for which file and network permissions are active.

Data flow: It reads the permission_profile_state field and returns it by reference. It does not change any permission data.

Call relations: The function is an accessor for code that needs the whole permission state, not just the simplified active profile. The provided graph does not show a direct caller, but session startup uses the same permission state when reporting the configured session.

fn permission_profile(&self) -> PermissionProfile

Purpose: Builds the effective permission profile for the current session. It also fills in project-root placeholders using the session’s actual workspace roots, so symbolic rules become concrete enough to enforce.

Data flow: It reads the stored permission profile state and workspace roots. It clones the profile, replaces project-root placeholders with the runtime workspace roots, and returns the resulting permission profile.

Call relations: Many parts of the session ask for this when they need the real safety rules: startup reports it to the client, sandbox helpers derive runtime policies from it, and turn-building code uses it before executing tools.

Call graph: calls 1 internal fn (permission_profile); called by 7 (new, file_system_sandbox_policy, sandbox_policy, thread_config_snapshot, build_per_turn_config, make_turn_context, new_turn_context_from_configuration).

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

Purpose: Returns the named active permission profile, if the session is using one. This is the user- or config-selected profile rather than only the expanded runtime rules.

Data flow: It reads the permission profile state and returns its active profile information, or nothing if the session is in legacy permission mode.

Call relations: Session startup includes this in the configured-session event, and configuration snapshots include it so clients or persistence layers can see which named profile is active.

Call graph: calls 1 internal fn (active_permission_profile); called by 2 (new, thread_config_snapshot).

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

Purpose: Returns the workspace roots that came from the active permission profile. These roots are separate from thread-level workspace roots and help explain where profile-defined access applies.

Data flow: It reads the permission profile state and returns the stored profile workspace roots. The configuration is not changed.

Call relations: The thread snapshot code calls this so a snapshot contains both the general workspace roots and the roots contributed by the permission profile.

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

fn apply_permission_profile_to_permissions(
        &self,
        permissions: &mut crate::config::Permissions,
    )

Purpose: Copies the session’s current permission-profile state into a mutable permissions object. This keeps per-turn permissions aligned with the session’s thread-level permission settings.

Data flow: It takes a mutable permissions structure, clones the session’s permission profile state, and stores that clone into the permissions structure. The session configuration itself is unchanged.

Call relations: Per-turn configuration building calls this before a turn runs. In plain terms, the session hands its current safety rules to the object that will be used for that specific turn.

Call graph: calls 1 internal fn (set_permission_profile_state); called by 1 (build_per_turn_config); 1 external calls (clone).

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

Purpose: Lets tests replace the session’s permission profile directly. This is test-only support for checking behavior under different permission setups.

Data flow: It takes a permission profile, asks the permission state to install it as a legacy-style profile, and returns success or a constraint error if the profile is not allowed.

Call relations: This exists only in test builds. It bypasses normal update flows so tests can set up a session configuration quickly and then exercise permission-related behavior.

Call graph: calls 1 internal fn (set_legacy_permission_profile).

fn sandbox_policy(&self) -> SandboxPolicy

Purpose: Returns a legacy-style sandbox policy derived from the current permission profile. A sandbox policy is the set of limits used to keep commands from accessing things they should not.

Data flow: It gets the effective permission profile, reads the current working directory, and converts those into a compatibility sandbox policy. It returns that policy without changing the configuration.

Call relations: The update logic uses this when comparing old and new permission settings. This helper is also part of the bridge between newer permission profiles and older sandbox-based code.

Call graph: calls 2 internal fn (cwd, permission_profile); called by 1 (apply); 1 external calls (compatibility_sandbox_policy_for_permission_profile).

fn file_system_sandbox_policy(&self) -> FileSystemSandboxPolicy

Purpose: Returns the file-access part of the session’s permission rules. This says which filesystem paths can be read or written.

Data flow: It builds the effective permission profile and asks that profile for its filesystem sandbox policy. The result is returned as a separate policy object.

Call relations: The configuration update path uses this before applying changes, so it can preserve important file restrictions when settings are modified.

Call graph: calls 1 internal fn (permission_profile); called by 1 (apply).

fn network_sandbox_policy(&self) -> NetworkSandboxPolicy

Purpose: Returns the network-access part of the session’s permission rules. This says what network activity is allowed or blocked.

Data flow: It reads the stored permission profile from the permission state and extracts its network sandbox policy. No configuration fields are changed.

Call relations: The update path uses this when it needs to carry forward existing network rules while changing other session settings.

Call graph: calls 1 internal fn (permission_profile); called by 1 (apply).

fn thread_config_snapshot(&self) -> ThreadConfigSnapshot

Purpose: Creates a compact snapshot of the session settings that describe the thread. This is useful when another part of the system needs a stable picture of the model, permissions, environments, and thread metadata.

Data flow: It reads many fields from the configuration, including model settings, approval policy, permission profile, environment selections, workspace roots, reasoning settings, personality, and thread ancestry. It packages those values into a ThreadConfigSnapshot and returns it.

Call relations: Code that needs to expose or store thread-level configuration calls this instead of picking fields one by one. The helper pulls in other accessors so the snapshot contains the effective permission profile and active profile information.

Call graph: calls 6 internal fn (value, active_permission_profile, permission_profile, profile_workspace_roots, model, reasoning_effort); 3 external calls (clone, clone, clone).

fn apply(&self, updates: &SessionSettingsUpdate) -> ConstraintResult<Self>

Purpose: Applies a requested settings update and returns a new session configuration. It is careful to keep model settings, service tier, working directory, workspace roots, and permission rules consistent.

Data flow: It starts by cloning the current configuration. It reads the requested updates, changes only the fields that were supplied, normalizes service-tier values, retargets workspace roots if the working directory moved, and converts permission or sandbox updates into the internal permission-profile state. If a requested change violates constraints, it returns an error; otherwise it returns the updated configuration.

Call relations: This is the main update gate for session settings. It calls the permission and sandbox helpers to compare current rules with new ones, and it uses set_permission_profile_projection when a new profile must be translated into runtime file and network permissions.

Call graph: calls 10 internal fn (active, cwd, file_system_sandbox_policy, network_sandbox_policy, sandbox_policy, from_request_value, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_preserving_deny_entries, from); 2 external calls (new, with_capacity).

fn set_permission_profile_projection(
        &mut self,
        permission_profile: PermissionProfile,
        active_permission_profile: Option<ActivePermissionProfile>,
        profile_workspace_ro

Purpose: Installs a permission profile into the session after translating it into the runtime rules the system actually enforces. It also preserves selected existing deny-read restrictions when asked to do so.

Data flow: It receives a permission profile, optional active-profile metadata, optional profile workspace roots, and an optional existing filesystem policy. It converts the profile into file and network rules, preserves deny-read restrictions from the old policy if provided, rebuilds an effective permission profile, wraps it in either an active-profile or legacy snapshot, and stores that snapshot in the permission state.

Call relations: The settings update flow uses this when the caller supplies a new permission profile. It is the narrow helper that keeps the public profile view and the lower-level enforcement rules synchronized.

Call graph: calls 6 internal fn (active_with_profile_workspace_roots, legacy, set_permission_profile_snapshot, enforcement, from_runtime_permissions_with_enforcement, to_runtime_permissions).

async fn warm_plugins_and_skills_for_session_init(
    config: Arc<Config>,
    plugins_manager: Arc<PluginsManager>,
    skills_manager: Arc<SkillsManager>,
    turn_environments: &TurnEnvironmentSna

Purpose: Preloads plugin and skill information during session startup. This reduces later delay and lets startup report skill-loading problems early.

Data flow: It receives the global config, plugin manager, skill manager, and resolved turn environments. It chooses the primary filesystem from the environments, loads plugin configuration, derives the skill roots contributed by plugins, asks the skills manager to load skills for those roots, and returns any skill errors found.

Call relations: Session::new calls this after environments are resolved and project instructions are loaded. It hands plugin-derived skill roots to the skills system so the session starts with its available abilities warmed up.

Call graph: calls 1 internal fn (primary_filesystem); called by 1 (new).

fn thread_id(&self) -> ThreadId

Purpose: Returns this session’s concrete thread identifier. The thread id names this particular conversation thread.

Data flow: It reads the thread_id field from the session and returns it. No state changes.

Call relations: This is a basic identity accessor. The provided call graph does not show callers, but other session code can use it whenever it needs to label events, persistence records, or telemetry with the current thread.

fn session_id(&self) -> SessionId

Purpose: Returns the broader session identifier shared through the agent-control service. For root threads this may match the thread id, while child or sub-agent threads can share a parent session identity.

Data flow: It asks agent_control inside the session services for the current session id and returns it. It does not alter the session.

Call relations: The function delegates identity ownership to the agent-control service. This lets callers ask the session for its shared conversation identity without knowing how root and child agents are wired.

async fn new(
        mut session_configuration: SessionConfiguration,
        config: Arc<Config>,
        user_instructions: Option<codex_extension_api::UserInstructions>,
        installation_id: S

Purpose: Builds a fully initialized session and returns it as a shared object. This is the startup pipeline for a new, resumed, cleared, or forked conversation thread.

Data flow: It takes the session configuration plus many shared services such as config, authentication, model access, persistence, environment management, plugins, skills, MCP tools, event channels, and telemetry support. It determines the thread identity, starts or resumes persistence, loads auth and MCP configuration, creates trace and telemetry data, resolves the shell and environments, loads instructions, warms plugins and skills, validates config locks, starts network proxy support if needed, builds hooks and extension data, creates SessionServices, constructs the Session, sends the initial configured event and warnings, installs the real MCP connection manager, prewarms startup work, records initial history, and finally commits persistence. On failure it discards unfinished persistence and returns the error.

Call relations: This is called by higher-level session creation paths, including internal agent spawning and test helpers. It calls many smaller constructors and helpers because it is the point where independent subsystems become one live session: persistence, auth, tools, environments, permissions, telemetry, network policy, and event delivery all meet here before user turns can run.

Call graph: calls 34 internal fn (new, new, new_uninitialized_with_permission_profile, new, new, session_id, with_session_id, new, new, new (+15 more)); called by 4 (spawn_internal, make_session_with_config_and_rx, make_session_with_history_source_and_agent_control_and_rx, session_new_fails_when_zsh_fork_enabled_without_packaged_zsh); 39 external calls (clone, downgrade, new, new, pin, new, default, default, default, new (+15 more)).

fn new() -> Self

Purpose: Creates an empty session input queue. It starts with no queued mailbox messages and prepares a notification channel so other parts of the session can hear when new input arrives.

Data flow: Nothing comes in. The function creates a fresh activity notifier whose initial activity is mailbox-related, creates an empty first-in-first-out mailbox list, and returns a ready-to-use InputQueue.

Call relations: Session setup code and the tests call this when they need a new queue. After it is created, later methods add mailbox items, subscribe to activity, or drain pending input from it.

Call graph: called by 8 (input_queue_drains_mailbox_in_delivery_order, input_queue_notifies_mailbox_subscribers, input_queue_notifies_steer_subscribers, input_queue_reports_already_pending_steer, input_queue_tracks_pending_trigger_turn_mail, new, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx); 3 external calls (new, new, channel).

async fn subscribe_activity(
        &self,
        turn_state: Option<&Mutex<TurnState>>,
    ) -> (
        watch::Receiver<InputQueueActivity>,
        Option<InputQueueActivity>,
    )

Purpose: Lets another task listen for future input activity, and also tells it if there is already something waiting right now. This prevents a listener from missing work that arrived just before it subscribed.

Data flow: It receives an optional current turn state. It creates a receiver for future activity notices, checks whether that turn already has user input waiting, otherwise checks whether the session mailbox has mail waiting, and returns both the receiver and an optional immediate activity hint.

Call relations: Callers use this when they begin waiting for input activity. It relies on has_pending_mailbox_items when no pending user steering is found, so the listener can be woken for either user input or mailbox mail.

Call graph: calls 1 internal fn (has_pending_mailbox_items); 1 external calls (subscribe).

async fn enqueue_mailbox_communication(
        &self,
        communication: InterAgentCommunication,
    )

Purpose: Adds a new agent-to-agent mailbox message to the session queue. It also wakes activity listeners so the session can notice that mailbox work is available.

Data flow: A mailbox communication comes in. The function locks the mailbox queue, appends the communication at the back to preserve arrival order, then sends a mailbox activity notice. It does not return a value, but it changes the queue and notifies watchers.

Call relations: This is used when mail arrives from another agent. Later, get_pending_input or drain_mailbox_input_items can pull those messages out for delivery to a turn.

Call graph: 1 external calls (send_replace).

async fn has_pending_mailbox_items(&self) -> bool

Purpose: Answers the simple question: is there any mailbox mail waiting in the session queue?

Data flow: Nothing comes in except access to the queue itself. It locks the mailbox list, checks whether it is empty, and returns true if at least one message is waiting.

Call relations: subscribe_activity uses this to report already-waiting mailbox work to new listeners. has_pending_input uses it after checking the current turn, so the broader session can know whether there is any input to process.

Call graph: called by 2 (has_pending_input, subscribe_activity).

async fn has_trigger_turn_mailbox_items(&self) -> bool

Purpose: Checks whether any queued mailbox message is marked as important enough to trigger a turn. This is useful because not every piece of mail necessarily needs to wake the system immediately.

Data flow: It reads the mailbox queue, looks through each waiting communication, and returns true if any one has its trigger_turn flag set. The queue itself is not changed.

Call relations: This is a query helper for higher-level session logic that needs to decide whether waiting mail should start or wake a turn. It does not hand work to another function.

async fn drain_mailbox_input_items(&self) -> Vec<TurnInput>

Purpose: Removes all waiting mailbox messages and converts them into turn input items. This is the point where session-level mail becomes input that a turn can consume.

Data flow: It locks the mailbox queue, removes every message in stored order, wraps each one as TurnInput::InterAgentCommunication, and returns the resulting list. Afterward, the mailbox queue is empty.

Call relations: get_pending_input calls this when the current turn accepts mailbox delivery. It is also tested directly to make sure mailbox order is preserved.

Call graph: called by 1 (get_pending_input).

async fn turn_state_for_sub_id(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
        sub_id: &str,
    ) -> Option<Arc<Mutex<TurnState>>>

Purpose: Finds the turn state for the active turn, but only if that active turn belongs to the requested subscription id. This protects one conversation branch from accidentally changing another branch's turn.

Data flow: It receives the shared active-turn slot and a subscription id string. It locks the active-turn slot, checks whether there is an active turn with a task, compares that task's subscription id, and returns a shared pointer to the turn state only on a match.

Call relations: defer_mailbox_delivery_to_next_turn and accept_mailbox_delivery_for_current_turn call this before changing mailbox delivery rules. If it returns nothing, those callers quietly do nothing.

Call graph: called by 2 (accept_mailbox_delivery_for_current_turn, defer_mailbox_delivery_to_next_turn).

async fn clear_pending(&self, active_turn: &ActiveTurn)

Purpose: Clears waiters and buffered input for the current turn. This is used when the system needs to cancel or reset pending turn work cleanly.

Data flow: It receives the active turn. It locks that turn's state, clears any pending waiters recorded there, and empties the turn-local pending input list. It returns nothing, but the turn is left with no buffered input.

Call relations: Higher-level session code can call this during cancellation, reset, or turn cleanup. It works directly on the active turn state and does not call other helpers in this file.

async fn defer_mailbox_delivery_to_next_turn(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
        sub_id: &str,
    )

Purpose: Marks mailbox delivery as something that should wait for the next turn, but only for the matching active subscription and only if no input is already buffered for this turn.

Data flow: It receives the active-turn slot and a subscription id. It first finds the matching turn state. If there is no match, it stops. If the turn already has pending input, it leaves delivery unchanged. Otherwise it sets the turn's mailbox delivery phase to NextTurn.

Call relations: This function calls turn_state_for_sub_id to avoid touching the wrong active turn. It is part of the control flow that decides whether mail is delivered now or saved until a later turn.

Call graph: calls 1 internal fn (turn_state_for_sub_id).

async fn accept_mailbox_delivery_for_current_turn(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
        sub_id: &str,
    )

Purpose: Allows the matching active turn to receive mailbox messages during the current turn. It is a safe wrapper that first verifies the subscription id.

Data flow: It receives the active-turn slot and subscription id. It finds the matching turn state, and if one exists, passes that turn state to the lower-level accept function. It returns nothing.

Call relations: This function uses turn_state_for_sub_id for the safety check, then hands off to accept_mailbox_delivery_for_turn_state to do the actual state update.

Call graph: calls 2 internal fn (accept_mailbox_delivery_for_turn_state, turn_state_for_sub_id).

async fn accept_mailbox_delivery_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
    )

Purpose: Updates a specific turn state so mailbox messages may be delivered to the current turn. This is the direct version used when the caller already has the correct turn state.

Data flow: It receives a locked turn state. It locks it, changes its mailbox delivery setting to accept mail for the current turn, and returns nothing.

Call relations: accept_mailbox_delivery_for_current_turn calls this after finding the right active turn. Other code in the same module can use it when it already has a turn state and does not need the subscription-id lookup.

Call graph: called by 1 (accept_mailbox_delivery_for_current_turn).

async fn extend_pending_input_and_accept_mailbox_delivery_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
        input: Vec<TurnInput>,
    )

Purpose: Adds input to a turn and makes sure that turn is allowed to receive mailbox delivery now. It also announces steering activity so listeners wake up for the new turn input.

Data flow: It receives a turn state and a list of turn input items. It locks the state, appends the new items to the turn-local pending list, marks mailbox delivery as accepted for this turn, unlocks the state, and sends a steering activity notice.

Call relations: Tests use this to simulate user steering arriving. In normal flow, it is the helper for adding urgent turn-local input and waking anything waiting on activity updates.

Call graph: 1 external calls (send_replace).

async fn extend_pending_input_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
        input: Vec<TurnInput>,
    )

Purpose: Adds input items to a specific turn without changing mailbox delivery settings or sending an activity notification. It is the quieter append-only helper.

Data flow: It receives a turn state and a list of input items. It locks the state and appends those items to the turn's pending input list. It returns nothing.

Call relations: This is useful for code that already controls notification or delivery policy elsewhere. It does not call other helpers and does not wake activity subscribers.

async fn take_pending_input_for_turn_state(
        &self,
        turn_state: &Mutex<TurnState>,
    ) -> Vec<TurnInput>

Purpose: Removes and returns all turn-local pending input from a specific turn. After this call, that turn's pending input list is empty.

Data flow: It receives a turn state, locks it, splits all items out of the pending input list, and returns those items as a vector. The state remains, but its pending input storage is cleared.

Call relations: This is a direct turn-state drain helper. It is separate from get_pending_input because it only takes turn-local input and does not also pull session mailbox messages.

async fn get_pending_input(
        &self,
        active_turn: &Mutex<Option<ActiveTurn>>,
    ) -> Vec<TurnInput>

Purpose: Collects the input that should be delivered right now. It first takes input already buffered for the active turn, then adds mailbox mail only if the turn currently accepts mailbox delivery.

Data flow: It receives the shared active-turn slot. While holding the relevant locks, it removes pending turn-local input and checks whether mailbox delivery is allowed. If delivery is not allowed, it returns only the turn-local input. If delivery is allowed, it drains mailbox mail and either returns it alone or appends it after the turn-local input.

Call relations: This is the main pickup point for the session loop when it is ready to feed new input into processing. It calls drain_mailbox_input_items only after confirming that mailbox mail is allowed for the current situation.

Call graph: calls 1 internal fn (drain_mailbox_input_items); 1 external calls (new).

async fn has_pending_input(&self, active_turn: &Mutex<Option<ActiveTurn>>) -> bool

Purpose: Checks whether there is any input ready to be processed, while respecting the current turn's mailbox delivery rules. It avoids reporting mailbox mail as ready if the active turn has deferred mailbox delivery.

Data flow: It receives the shared active-turn slot. It checks whether the active turn has turn-local pending input and whether that turn accepts mailbox delivery. If turn-local input exists, it returns true. If mailbox delivery is not accepted, it returns false. Otherwise it checks the session mailbox queue and returns whether mail is waiting.

Call relations: This is a readiness check for higher-level session code before it decides to fetch input. It calls has_pending_mailbox_items only when mailbox mail is allowed to count as ready.

Call graph: calls 1 internal fn (has_pending_mailbox_items).

fn has_user_input(&self) -> bool

Purpose: Checks whether a turn's pending input includes direct user input. This matters because user steering is treated differently from mailbox activity when deciding what kind of work is pending.

Data flow: It reads the turn-local list of input items, looks for any item shaped as TurnInput::UserInput, and returns true if it finds one. It does not change the list.

Call relations: subscribe_activity uses this through the current turn state to decide whether a new subscriber should be told that steering work is already waiting.

fn make_mail(
        author: AgentPath,
        recipient: AgentPath,
        content: &str,
        trigger_turn: bool,
    ) -> InterAgentCommunication

Purpose: Builds a test mailbox message with the chosen sender, recipient, content, and trigger flag. It keeps the tests short and consistent.

Data flow: It receives an author path, recipient path, message text, and trigger_turn boolean. It creates an InterAgentCommunication value with no extra metadata and returns it.

Call relations: The mailbox-related tests call this whenever they need sample agent mail. It delegates construction to the protocol type's constructor.

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

async fn input_queue_notifies_mailbox_subscribers()

Purpose: Tests that adding mailbox mail wakes subscribers with mailbox activity. This protects the notification path that lets the rest of the session notice new mail.

Data flow: The test creates an empty queue, subscribes to activity, verifies there is no immediate pending work, enqueues two mailbox messages, waits for a change notification, and checks that the reported activity is Mailbox.

Call relations: It exercises InputQueue::new, subscribe_activity, enqueue_mailbox_communication, and the test mail builder. The story it verifies is: subscribe first, mail arrives later, listener wakes up.

Call graph: calls 3 internal fn (new, root, try_from); 2 external calls (assert_eq!, make_mail).

async fn input_queue_notifies_steer_subscribers()

Purpose: Tests that adding user steering input wakes subscribers with steering activity. This makes sure direct user input is signaled differently from mailbox mail.

Data flow: The test creates a queue and a default turn state, subscribes to activity, confirms no work is already pending, adds a user input item through the helper that also accepts mailbox delivery, waits for the notification, and checks that the activity is Steer.

Call relations: It uses InputQueue::new and extend_pending_input_and_accept_mailbox_delivery_for_turn_state. The scenario proves that turn-local user input sends the steering signal expected by subscribers.

Call graph: calls 1 internal fn (new); 4 external calls (new, default, assert_eq!, vec!).

async fn input_queue_reports_already_pending_steer()

Purpose: Tests that a new subscriber is told about user steering that was already waiting before it subscribed. This prevents a race where work could be missed.

Data flow: The test creates a queue and turn state, adds user input before subscribing, then subscribes with that turn state. It checks that the returned immediate pending activity is Steer.

Call relations: It uses the same input-adding helper as the steering notification test, but flips the order: input first, subscription second. This covers the immediate pending_activity part of subscribe_activity.

Call graph: calls 1 internal fn (new); 4 external calls (new, default, assert_eq!, vec!).

async fn input_queue_drains_mailbox_in_delivery_order()

Purpose: Tests that mailbox messages come back out in the same order they were queued, and that draining empties the mailbox queue. This protects message ordering.

Data flow: The test creates two messages, enqueues them one after the other, drains the mailbox into turn input items, and compares the result to the expected ordered list. It then checks that no mailbox items remain.

Call relations: It uses InputQueue::new, enqueue_mailbox_communication, drain_mailbox_input_items, and has_pending_mailbox_items. The scenario confirms the queue behaves like a proper first-in-first-out line.

Call graph: calls 3 internal fn (new, root, try_from); 3 external calls (assert!, assert_eq!, make_mail).

async fn input_queue_tracks_pending_trigger_turn_mail()

Purpose: Tests that the queue can tell whether any waiting mailbox message is marked to trigger a turn. This ensures important wake-up mail is not hidden among ordinary mail.

Data flow: The test creates a queue, enqueues a non-triggering message, and checks that no trigger-turn mail is reported. It then enqueues a triggering message and checks that the query now returns true.

Call relations: It uses InputQueue::new, enqueue_mailbox_communication, has_trigger_turn_mailbox_items, and the test mail builder. The scenario proves the trigger check looks across all queued mail.

Call graph: calls 3 internal fn (new, root, try_from); 2 external calls (assert!, make_mail).

async fn inject_if_running(
        &self,
        input: Vec<ResponseItem>,
    ) -> Result<(), Vec<ResponseItem>>

Purpose: This tries to add new response items to the session’s currently running turn. If no turn is active, it gives the items back unchanged so the caller can choose another path.

Data flow: It receives a list of response items. It locks the session’s active-turn slot, like checking whether the help desk is already serving someone. If there is an active turn, it wraps each item as turn input and appends them to that turn’s pending input queue, then reports success. If there is no active turn, it returns the original items as an error value, meaning nothing was injected and nothing was lost.

Call relations: This is the first step used by Session::inject_no_new_turn. That caller asks, “Can these items join work already in progress?” If this function says yes, the story ends there. If it says no, Session::inject_no_new_turn records the items instead of starting new work.

Call graph: called by 1 (inject_no_new_turn).

async fn try_start_turn_if_idle(
        self: &Arc<Self>,
        input: Vec<ResponseItem>,
    ) -> Result<(), TryStartTurnIfIdleError>

Purpose: This starts a normal assistant turn for automatic idle work, but only when it is safe and polite to do so. It refuses to start if user-triggered work is waiting, if the session is busy, or if the session is in Plan mode.

Data flow: It receives response items that an extension wants to process. Empty input immediately becomes a successful no-op. Otherwise it checks for pending user-triggered work, checks the current collaboration mode, and reserves an active-turn slot only if nothing is already running. After reserving, it checks again for newly arrived user work, builds a fresh turn context with a new unique sub-id, checks whether that context is still allowed to run, possibly emits a model warning, checks again for queued user work, and confirms its reservation was not stolen or replaced. If all checks pass, it adds the items to the reserved turn’s input queue and starts a regular task. If any check fails, it returns an error containing the reason and the original input so the caller can keep or retry it.

Call relations: This function is the gatekeeper for extension-initiated idle work. During its flow it creates error values with new, creates a unique id with new_v4, clones shared turn state, and calls Session::clear_reserved_idle_turn whenever it made a temporary reservation that must be undone. After cleanup, it may let pending user work start instead of the idle work.

Call graph: calls 3 internal fn (new, clear_reserved_idle_turn, new); 3 external calls (clone, new, new_v4).

async fn clear_reserved_idle_turn(&self, turn_state: &Arc<tokio::sync::Mutex<TurnState>>)

Purpose: This removes a temporary idle-turn reservation if it still belongs to the caller and no task has actually started. It is a safety cleanup step that prevents a failed idle-start attempt from leaving the session looking busy.

Data flow: It receives the shared turn state that was reserved earlier. It locks the active-turn slot and checks three things: there is an active turn, that turn has no task attached yet, and its turn state is the exact same shared object as the one passed in. If all three are true, it clears the active-turn slot. If not, it leaves the session untouched, because some other work may have started or changed the state.

Call relations: Session::try_start_turn_if_idle calls this whenever it has reserved an idle turn but later discovers it should not proceed, such as when user work appears or Plan mode is detected. The function uses pointer equality through ptr_eq to avoid clearing a different turn by mistake.

Call graph: called by 1 (try_start_turn_if_idle); 1 external calls (ptr_eq).

async fn inject_no_new_turn(
        &self,
        items: Vec<ResponseItem>,
        current_turn_context: Option<&TurnContext>,
    )

Purpose: This adds items to active work if possible, but deliberately does not start a new assistant turn. If nothing is running, it simply records the items in the conversation history.

Data flow: It receives response items and optionally the current turn context, which is the bundle of information describing the current assistant turn. First it passes the items to Session::inject_if_running. If that succeeds, the items have joined the active turn and the function stops. If injection fails because no turn is running, it chooses a turn context: it uses the supplied one if available, or creates a default one. It then records the items as conversation history, changing stored session history but not launching new work.

Call relations: This function depends on Session::inject_if_running as its fast path. It is used when callers want incoming items preserved or attached to current work, but they specifically do not want those items to wake up the assistant by creating a fresh turn.

Call graph: calls 1 internal fn (inject_if_running).

async fn install_mcp_connection_manager(
        &self,
        manager: McpConnectionManager,
    ) -> Result<()>

Purpose: This function makes a newly created MCP connection manager the active one for the session, then checks that all required MCP servers are available. It is used during setup so MCP-related work can safely go through the session’s official manager.

Data flow: It receives an McpConnectionManager. It wraps that manager in a shared reference so other tasks can hold it safely, stores it as the current manager, then reads it back and asks it to validate required servers. If validation succeeds, it returns success. If a required server check fails, it returns an error.

Call relations: During session setup, once an MCP connection manager has been built, this function is the step that publishes it into SessionServices. Internally it calls the shared-pointer constructor, then hands control to the manager’s server validation step so startup can continue only after required MCP connections have been checked.

Call graph: 1 external calls (new).

fn new(session_configuration: SessionConfiguration) -> Self

Purpose: Creates a fresh SessionState for a newly started session. It fills in empty history, empty sets and queues, no known rate limits yet, and marks the next turn as the first turn.

Data flow: It receives the session configuration that describes how this session should run. It builds new helper objects for history and auto-compaction, starts optional values as missing, starts collections as empty, and returns the completed state object ready for use.

Call relations: This is the starting point for session state. Session setup code and tests call it when they need a clean session, and later methods build on the objects and defaults created here.

Call graph: calls 2 internal fn (new, new); called by 12 (new, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, set_rate_limits_retains_previous_credits, set_rate_limits_updates_plan_type_when_present, clear_connector_selection_removes_entries, merge_connector_selection_deduplicates_entries, replace_history_clears_auto_compact_window_prefill, set_rate_limits_carries_account_metadata_from_codex_to_codex_other, set_rate_limits_defaults_limit_id_to_codex_when_missing (+2 more)); 4 external calls (new, new, new, default).

fn record_items(&mut self, items: I, policy: TruncationPolicy)

Purpose: Adds response items to the stored conversation history. The truncation policy tells the history layer how to shorten oversized output when needed.

Data flow: It receives a group of response items plus a rule for truncating long content. It passes both to the history store, which records the items in the session's remembered context.

Call relations: When the session receives new conversation items, this method is the state-level doorway into ContextManager::record_items. It keeps callers from reaching directly into the history object for this common update.

Call graph: calls 1 internal fn (record_items).

fn previous_turn_settings(&self) -> Option<PreviousTurnSettings>

Purpose: Returns the settings remembered from the latest normal user turn. These settings help later turns keep behavior such as model or realtime choices consistent.

Data flow: It reads the optional stored settings, clones them if present, and gives the caller its own copy. The internal stored value is not changed.

Call relations: Code preparing a new turn can ask this method what the previous turn used. It pairs with SessionState::set_previous_turn_settings, which writes the value after a turn has chosen its settings.

fn set_previous_turn_settings(
        &mut self,
        previous_turn_settings: Option<PreviousTurnSettings>,
    )

Purpose: Stores or clears the settings from the latest regular user turn. This lets the next turn know what choices were used before.

Data flow: It receives either some previous-turn settings or None. It replaces the stored value with that input and returns nothing.

Call relations: Turn orchestration code calls this after deciding the effective settings for a turn. Later, SessionState::previous_turn_settings reads the value back.

fn set_next_turn_is_first(&mut self, value: bool)

Purpose: Sets whether the next user turn should be treated as the first turn of the session. This is useful when session flow needs to reset or explicitly control first-turn behavior.

Data flow: It receives a true-or-false value and stores it in the session state. Nothing is returned.

Call relations: Code that prepares or resets session flow can set this flag. SessionState::take_next_turn_is_first later consumes it when a turn starts.

fn take_next_turn_is_first(&mut self) -> bool

Purpose: Checks whether the next turn was marked as the first turn, then clears that mark. This makes the flag a one-time signal.

Data flow: It reads the current flag, immediately changes the stored flag to false, and returns the old value. After this call, following turns will not see the same first-turn signal unless it is set again.

Call relations: Turn-start code uses this when it needs to know whether special first-turn behavior should run. It works like taking a ticket from a dispenser: once taken, the same ticket is no longer there.

fn clone_history(&self) -> ContextManager

Purpose: Returns a copy of the current conversation history manager. This lets other code inspect or work with the history without directly owning the session's internal copy.

Data flow: It reads the current ContextManager, clones it, and returns the clone. The original history inside the session remains unchanged.

Call relations: Callers use this when they need a snapshot-like copy of history. It relies on the history manager's own clone behavior rather than exposing mutable access.

Call graph: 1 external calls (clone).

fn replace_history(
        &mut self,
        items: Vec<ResponseItem>,
        reference_context_item: Option<TurnContextItem>,
    )

Purpose: Replaces the stored conversation history with a new list of response items and a new reference context item. It also clears auto-compaction prefill information because the old token assumptions may no longer match the new history.

Data flow: It receives replacement history items and an optional context reference. It swaps the history contents, stores the reference item, clears prefill tracking in the auto-compaction window, and returns nothing.

Call relations: This is used when the session history is rebuilt, such as after compaction or resume. It coordinates both the history store and the auto-compaction tracker so they do not disagree.

Call graph: calls 3 internal fn (replace, set_reference_context_item, clear_prefill).

fn set_token_info(&mut self, info: Option<TokenUsageInfo>)

Purpose: Sets the current token usage information stored with the conversation history. Token information describes how much model context has been used.

Data flow: It receives optional token usage information. It forwards that value to the history manager, replacing the token information held there.

Call relations: Code that learns or recalculates token information calls this method. The actual storage lives in the history manager, and this method is the session-level wrapper.

Call graph: calls 1 internal fn (set_token_info).

fn set_reference_context_item(&mut self, item: Option<TurnContextItem>)

Purpose: Stores the context item that should be treated as the reference point for the current history. This helps later context-building know which item the current context is based on.

Data flow: It receives an optional reference context item and forwards it into the history manager. The session state itself returns nothing.

Call relations: This is called when session logic needs to update the history's context anchor. SessionState::reference_context_item reads the same value back later.

Call graph: calls 1 internal fn (set_reference_context_item).

fn reference_context_item(&self) -> Option<TurnContextItem>

Purpose: Returns the current reference context item, if one is stored. This gives callers the context anchor associated with the current history.

Data flow: It asks the history manager for its reference context item and returns that optional value. No state is changed.

Call relations: Context-building code calls this when it needs to know what the stored history is anchored to. It is the read-side partner to SessionState::set_reference_context_item.

Call graph: calls 1 internal fn (reference_context_item).

fn update_token_info_from_usage(
        &mut self,
        usage: &TokenUsage,
        model_context_window: Option<i64>,
    )

Purpose: Updates stored token information using a token usage report from the model or server. The optional model context window tells it the total size of the model's available context, if known.

Data flow: It receives raw token usage and an optional context-window size. It passes both into the history manager, which recalculates the stored token information.

Call relations: After a model response or usage update arrives, session code calls this to keep token accounting current. The detailed calculation is delegated to the history manager.

Call graph: calls 1 internal fn (update_token_info).

fn ensure_auto_compact_window_server_prefill_from_usage(
        &mut self,
        usage: &TokenUsage,
    )

Purpose: Makes sure the auto-compaction tracker has a server-observed prefill value based on token usage. Prefill means tokens already present in the model context before the latest generation.

Data flow: It receives token usage from the server and passes it to the auto-compaction window. The window records the server-observed prefill only if it needs one.

Call relations: This is part of keeping auto-compaction decisions grounded in real usage data. It hands usage information to AutoCompactWindow, which owns that specific accounting.

Call graph: calls 1 internal fn (ensure_server_observed_prefill_from_usage).

fn set_auto_compact_window_estimated_prefill(&mut self, tokens: i64)

Purpose: Stores an estimated prefill token count for the active auto-compaction window. This is used when the system has an estimate rather than a server-measured number.

Data flow: It receives a token count and passes it into the auto-compaction window as the estimated prefill. Nothing is returned.

Call relations: Context preparation code can call this before exact server usage is known. Later auto-compaction snapshots and decisions use the value stored in AutoCompactWindow.

Call graph: calls 1 internal fn (set_estimated_prefill).

fn auto_compact_window_snapshot(&self) -> AutoCompactWindowSnapshot

Purpose: Returns a snapshot of the current auto-compaction window. A snapshot is a read-only picture of the window's current counters and identifiers.

Data flow: It asks the auto-compaction window to produce its snapshot and returns that snapshot to the caller. The live window is not changed.

Call relations: Other parts of the session use this when they need to report or reason about compaction state without mutating it. The underlying snapshot is produced by AutoCompactWindow.

Call graph: calls 1 internal fn (snapshot).

fn auto_compact_window_id(&self) -> u64

Purpose: Returns the identifier of the active auto-compaction window. The identifier separates one context window from the next.

Data flow: It reads the window id from the auto-compaction tracker and returns it. No state changes.

Call relations: Code that tags work with the current context-window generation calls this. It delegates the actual value to AutoCompactWindow.

Call graph: calls 1 internal fn (window_id).

fn set_auto_compact_window_id(&mut self, window_id: u64)

Purpose: Forces the auto-compaction window to use a specific identifier. This is useful when restoring or synchronizing state.

Data flow: It receives a window id number and stores it inside the auto-compaction tracker. Nothing is returned.

Call relations: Session flow can call this when the window id must match an outside source or restored state. Later reads through SessionState::auto_compact_window_id return the new value.

Call graph: calls 1 internal fn (set_window_id).

fn advance_auto_compact_window_id(&mut self) -> u64

Purpose: Moves the auto-compaction tracker to the next window id and returns that new id. This marks the start of a new context-window generation.

Data flow: It asks the auto-compaction window to increment its id. The updated id is returned to the caller.

Call relations: Compaction or context-reset code calls this when it deliberately starts a new window. It is a direct session-level wrapper around the auto-compaction tracker.

Call graph: calls 1 internal fn (advance_window_id).

fn request_new_context_window(&mut self)

Purpose: Marks that a new context window should be started soon. It records the request without immediately changing the window.

Data flow: It sets a pending request flag inside the auto-compaction window and returns nothing. The current window id and prefill remain unchanged until the request is acted on.

Call relations: Code that detects the need for a fresh context calls this as a signal. SessionState::start_new_context_window_if_requested later consumes the signal and performs the actual switch.

Call graph: calls 1 internal fn (request_new_context_window).

fn start_new_context_window_if_requested(&mut self) -> Option<u64>

Purpose: Starts a new auto-compaction context window only if one was previously requested. If no request is pending, it leaves everything alone.

Data flow: It asks the auto-compaction window whether a new-window request is pending. If not, it returns None; if yes, it advances the window id, clears prefill data, and returns the new id.

Call relations: This is the follow-through step after SessionState::request_new_context_window. It is likely called at a safe transition point, so the session only changes windows when the rest of the flow is ready.

Call graph: calls 3 internal fn (advance_window_id, clear_prefill, take_new_context_window_request).

fn token_info(&self) -> Option<TokenUsageInfo>

Purpose: Returns the current token usage information, if known. This tells callers how full the model context is believed to be.

Data flow: It asks the history manager for its stored token information and returns that optional value. It does not change the history.

Call relations: This is used directly by callers that only need token information and internally by SessionState::token_info_and_rate_limits, which bundles token information with rate-limit information.

Call graph: calls 1 internal fn (token_info); called by 1 (token_info_and_rate_limits).

fn set_rate_limits(&mut self, snapshot: RateLimitSnapshot)

Purpose: Stores the latest rate-limit snapshot from the server while preserving older details that the new snapshot may omit. Rate limits describe usage caps, credits, and plan information.

Data flow: It receives a new rate-limit snapshot and compares it with the previously stored one. It fills missing fields where appropriate, stores the merged result, and returns nothing.

Call relations: When fresh rate-limit data arrives, session code calls this method. It relies on merge_rate_limit_fields so incomplete server updates do not erase useful prior information.

Call graph: calls 1 internal fn (merge_rate_limit_fields).

fn token_info_and_rate_limits(
        &self,
    ) -> (Option<TokenUsageInfo>, Option<RateLimitSnapshot>)

Purpose: Returns token usage information and rate-limit information together. This is convenient for status reporting or responses that need both pieces of accounting.

Data flow: It reads token information through SessionState::token_info, clones the latest stored rate-limit snapshot if present, and returns both as a pair. No state changes.

Call relations: Callers use this when they need a combined view of model-context usage and account/server limits. It builds on the token-info accessor and the stored rate-limit field.

Call graph: calls 1 internal fn (token_info).

fn set_token_usage_full(&mut self, context_window: i64)

Purpose: Marks token usage as full for a given context-window size. This tells the history layer that the model's available context should be considered filled.

Data flow: It receives a context-window size and passes it to the history manager. The history manager updates its token accounting to reflect a full context.

Call relations: Session logic can call this when it knows the context has reached capacity. The detailed token state is stored inside the history manager.

Call graph: calls 1 internal fn (set_token_usage_full).

fn get_total_token_usage(&self, server_reasoning_included: bool) -> i64

Purpose: Returns the total token usage currently known for the session history. The caller chooses whether server-side reasoning tokens should be included in that total.

Data flow: It receives a true-or-false choice about including server reasoning. It passes that choice to the history manager and returns the resulting token count.

Call relations: Reporting or compaction code calls this when it needs a single token total. The calculation is owned by the history manager, while this method exposes it at the session-state level.

Call graph: calls 1 internal fn (get_total_token_usage).

fn set_server_reasoning_included(&mut self, included: bool)

Purpose: Records whether server-side reasoning tokens are included in the session's accounting. Server reasoning means internal model work that may be counted separately from visible text.

Data flow: It receives a true-or-false value and stores it in the session state. Nothing is returned.

Call relations: Code that learns how the server is reporting usage updates this flag. SessionState::server_reasoning_included later reads the value.

fn server_reasoning_included(&self) -> bool

Purpose: Returns whether server-side reasoning tokens are currently considered included in usage accounting. This lets other code interpret token totals correctly.

Data flow: It reads the stored boolean flag and returns it. No state changes.

Call relations: Callers use this after SessionState::set_server_reasoning_included has recorded the server's behavior. It helps keep token reporting consistent.

fn record_mcp_dependency_prompted(&mut self, names: I)

Purpose: Remembers which MCP dependency names have already prompted the user. MCP refers to Model Context Protocol, a way external tools or services can provide context to the model.

Data flow: It receives a collection of dependency names and adds them to a set. Because it is a set, repeated names are kept only once.

Call relations: Code that prompts about MCP dependencies calls this afterward so the same dependency is not treated as new again. SessionState::mcp_dependency_prompted returns the remembered set.

fn mcp_dependency_prompted(&self) -> HashSet<String>

Purpose: Returns the set of MCP dependency names that have already prompted the user. This helps avoid duplicate prompts.

Data flow: It clones the stored set of dependency names and returns the clone. The internal set is unchanged.

Call relations: Prompting logic can call this before deciding whether to ask the user about a dependency. It reads the information written by SessionState::record_mcp_dependency_prompted.

fn set_session_startup_prewarm(
        &mut self,
        startup_prewarm: SessionStartupPrewarmHandle,
    )

Purpose: Stores a startup prewarm handle prepared during session initialization. A prewarm handle represents work done early so the session can respond faster later.

Data flow: It receives a prewarm handle and stores it as the current optional startup prewarm value. Any previous value is replaced.

Call relations: Session startup code calls this after preparing prewarm work. Later, SessionState::take_session_startup_prewarm removes and returns it when the session is ready to use it.

fn take_session_startup_prewarm(&mut self) -> Option<SessionStartupPrewarmHandle>

Purpose: Takes the stored startup prewarm handle out of the session state, if one exists. Taking it means it can only be consumed once.

Data flow: It removes the optional prewarm handle from the state and returns it. Afterward, the stored value is empty.

Call relations: Code that wants to use the prewarmed session calls this at the point of use. It pairs with SessionState::set_session_startup_prewarm, which stores the handle earlier.

fn merge_connector_selection(&mut self, connector_ids: I) -> HashSet<String>

Purpose: Adds connector IDs to the session's active connector selection and returns the full merged selection. Connector IDs identify external integrations or data sources chosen for the session.

Data flow: It receives connector ID strings, adds them to the stored set, and returns a cloned set containing all active connector IDs. Duplicates naturally collapse because the storage is a set.

Call relations: Connector-selection code calls this when new connectors become active. SessionState::get_connector_selection can later read the same set, and SessionState::clear_connector_selection can empty it.

fn get_connector_selection(&self) -> HashSet<String>

Purpose: Returns the current active connector selection. This tells callers which connector IDs the session is tracking right now.

Data flow: It clones the stored connector ID set and returns the clone. The session's internal set is not changed.

Call relations: Code preparing connector-related work calls this after selections have been merged in through SessionState::merge_connector_selection.

fn clear_connector_selection(&mut self)

Purpose: Removes all active connector selections from the session state. This resets connector tracking to empty.

Data flow: It clears the stored connector ID set and returns nothing. After the call, SessionState::get_connector_selection will return an empty set unless new IDs are merged in.

Call relations: Session or turn flow calls this when connector selections should no longer carry forward. It is the reset counterpart to SessionState::merge_connector_selection.

fn queue_pending_session_start_source(
        &mut self,
        value: codex_hooks::SessionStartSource,
    )

Purpose: Adds a session-start source to a waiting queue. A session-start source records something that should be processed as part of session-start handling.

Data flow: It receives one session-start source and pushes it onto the back of the queue. Nothing is returned.

Call relations: Startup or hook-related code calls this when it has another start source to process later. SessionState::take_pending_session_start_source removes them in first-in, first-out order.

Call graph: 1 external calls (push_back).

fn take_pending_session_start_source(
        &mut self,
    ) -> Option<codex_hooks::SessionStartSource>

Purpose: Removes and returns the oldest queued session-start source, if any. This lets start sources be processed in the same order they were queued.

Data flow: It pops one item from the front of the queue. If the queue has an item, that item is returned; if not, it returns None.

Call relations: Session-start processing calls this repeatedly to drain queued sources. It consumes values added earlier by SessionState::queue_pending_session_start_source.

Call graph: 1 external calls (pop_front).

fn record_granted_permissions(
        &mut self,
        environment_id: &str,
        permissions: AdditionalPermissionProfile,
    )

Purpose: Records additional permissions granted for a specific environment, merging them with any permissions already stored for that environment. An environment ID distinguishes one sandbox or execution setting from another.

Data flow: It receives an environment ID and a permission profile. It looks up any existing permissions for that environment, merges old and new profiles, and stores the merged result if there is one.

Call relations: Permission approval code calls this after extra permissions are granted. It delegates the details of combining permission profiles to merge_permission_profiles, then makes the result available through SessionState::granted_permissions.

Call graph: calls 1 internal fn (merge_permission_profiles).

fn granted_permissions(
        &self,
        environment_id: &str,
    ) -> Option<AdditionalPermissionProfile>

Purpose: Returns the additional permissions remembered for a given environment, if any. This lets later work reuse permissions that were already granted.

Data flow: It receives an environment ID, looks for a stored permission profile under that ID, clones it if present, and returns it. The stored permission map is unchanged.

Call relations: Before asking for or applying permissions, session code can call this to see what has already been granted. It reads the records written by SessionState::record_granted_permissions.

fn merge_rate_limit_fields(
    previous: Option<&RateLimitSnapshot>,
    mut snapshot: RateLimitSnapshot,
) -> RateLimitSnapshot

Purpose: Combines an older rate-limit snapshot with a newer one so missing fields in the new update do not erase useful known information. It also treats a missing limit bucket ID as the default codex bucket.

Data flow: It receives an optional previous snapshot and a new snapshot. It fills in missing limit ID, credits, individual-limit, and plan-type fields from defaults or the previous snapshot where appropriate, then returns the completed snapshot.

Call relations: SessionState::set_rate_limits calls this whenever new rate-limit data arrives. This helper keeps the merging rule in one place, so the rest of session state can simply store the corrected snapshot.

Call graph: called by 1 (set_rate_limits).

fn new() -> Self

Purpose: Creates a fresh auto-compact window tracker. It starts at window 0, with no pending request for a new window and no token baseline yet.

Data flow: Nothing is provided as input. The function builds a new AutoCompactWindow with default starting values and returns it to the caller.

Call relations: This is used when the surrounding state object is first created, and the test also uses it to start from a clean example. It gives the rest of the auto-compaction flow a known starting point.

Call graph: called by 2 (tracks_prefill_and_window_boundaries, new).

fn clear_prefill(&mut self)

Purpose: Forgets the stored prefill token baseline. This is useful when the conversation history is replaced or a new context window begins, because the old baseline no longer describes the current window.

Data flow: It takes the current window tracker as mutable state. It changes only the prefill field, setting it back to empty, and returns no value.

Call relations: The history replacement path and the new-context-window startup path call this when they need to discard old token accounting. After this, another part of the system can set a fresh estimate or wait for server-reported usage.

Call graph: called by 2 (replace_history, start_new_context_window_if_requested).

fn window_id(&self) -> u64

Purpose: Returns the identifier of the current auto-compact window. Other code can use this to tell whether it is still looking at the same accounting period or a newer one.

Data flow: It reads the stored window number from the tracker and returns that number without changing anything.

Call relations: The higher-level auto_compact_window_id accessor calls this to expose the current window number. It is a simple read-only doorway into this piece of state.

Call graph: called by 1 (auto_compact_window_id).

fn set_window_id(&mut self, window_id: u64)

Purpose: Sets the current window identifier to a specific value. This is useful when restoring or synchronizing state rather than simply moving to the next window.

Data flow: It receives a window number from the caller. It writes that number into the tracker and returns no separate result.

Call relations: The surrounding state API calls this through set_auto_compact_window_id. That lets code outside this small struct update the saved window identity in a controlled way.

Call graph: called by 1 (set_auto_compact_window_id).

fn advance_window_id(&mut self) -> u64

Purpose: Moves the tracker to the next auto-compact window and clears any pending request for a new window. This marks that the requested transition has actually happened.

Data flow: It reads the current window number, increases it by one without overflowing past the maximum integer value, clears the new-window request flag, and returns the updated window number.

Call relations: This is called when higher-level code advances the auto-compact window directly or when start_new_context_window_if_requested follows through on a pending request. It hands back the new ID so the caller can continue using the updated window identity.

Call graph: called by 2 (advance_auto_compact_window_id, start_new_context_window_if_requested).

fn request_new_context_window(&mut self)

Purpose: Marks that the system should start a new context window soon. It does not perform the reset immediately; it leaves a flag for the part of the system that is responsible for doing the transition.

Data flow: It takes the current tracker as mutable state, changes the request flag from false to true, and returns no value.

Call relations: The higher-level request_new_context_window path calls this when something decides a fresh accounting window is needed. Later, start_new_context_window_if_requested checks and consumes this request.

Call graph: called by 1 (request_new_context_window).

fn take_new_context_window_request(&mut self) -> bool

Purpose: Checks whether a new context window was requested, then clears the request. This makes the request a one-time signal, so the same request is not acted on repeatedly.

Data flow: It reads the request flag, stores that answer, resets the flag to false, and returns the stored answer to the caller.

Call relations: start_new_context_window_if_requested calls this when it is ready to decide whether to begin a new window. If the answer is true, that caller can continue with the reset; if false, it can leave the current window alone.

Call graph: called by 1 (start_new_context_window_if_requested).

fn ensure_server_observed_prefill_from_usage(&mut self, usage: &TokenUsage)

Purpose: Records the input-token baseline reported by the server, but only if a server-confirmed baseline has not already been recorded. Server-reported usage is treated as more reliable than an earlier estimate.

Data flow: It receives token usage from the model server and reads the input_tokens value. If no server-observed prefill is already present, it stores the input-token count, never below zero; if a server-observed value already exists, it leaves the existing value unchanged.

Call relations: ensure_auto_compact_window_server_prefill_from_usage calls this after token usage information is available. This function then upgrades the window’s accounting from a guess to a server-confirmed baseline, and protects that confirmed value from later replacement.

Call graph: called by 1 (ensure_auto_compact_window_server_prefill_from_usage); 2 external calls (ServerObserved, matches!).

fn set_estimated_prefill(&mut self, tokens: i64)

Purpose: Stores an estimated input-token baseline for the current window. It is a fallback for times when the system needs a baseline before it has a server-confirmed number.

Data flow: It receives a token count from the caller. If a server-observed baseline is already stored, it does nothing; otherwise it stores the given count, with negative values treated as zero.

Call relations: set_auto_compact_window_estimated_prefill calls this when higher-level state has to make an estimated baseline. If a later server usage sample arrives, ensure_server_observed_prefill_from_usage can replace this estimate with a more trustworthy value.

Call graph: called by 1 (set_auto_compact_window_estimated_prefill); 2 external calls (Estimated, matches!).

fn snapshot(&self) -> AutoCompactWindowSnapshot

Purpose: Creates a simple read-only summary of the current prefill token baseline. This lets other code inspect the accounting state without exposing the internal distinction between estimated and server-observed values.

Data flow: It reads the stored prefill value, whether estimated or server-observed. It returns an AutoCompactWindowSnapshot containing just the token number if one exists, or nothing if no baseline has been set.

Call relations: The higher-level auto_compact_window_snapshot accessor calls this when code needs a compact view of the window state. The snapshot is safe to pass around because it does not allow callers to mutate the underlying tracker.

Call graph: called by 1 (auto_compact_window_snapshot).

fn tracks_prefill_and_window_boundaries()

Purpose: Checks that the window tracker behaves as intended across common state changes. It verifies window IDs, one-time new-window requests, estimated prefill values, and the rule that server-observed prefill wins over estimates.

Data flow: The test creates a fresh tracker, changes its window ID, requests and consumes new windows, sets estimated and server-observed token baselines, and compares snapshots against expected results. Its output is a pass or fail result from the test runner.

Call relations: This test calls the tracker’s public-in-module methods in the same kind of sequence the real state system would use. It acts as a safety net so future changes do not accidentally break token baseline accounting or window-boundary behavior.

Call graph: calls 1 internal fn (new); 3 external calls (default, assert!, assert_eq!).

fn from_config_and_version(
        config: &Config,
        multi_agent_version: MultiAgentVersion,
    ) -> Self

Purpose: Chooses what kind of conversation marker should be written when a turn is interrupted. It uses configuration and the multi-agent protocol version to decide whether the marker is disabled, written as contextual user text, or written as developer guidance.

Data flow: It receives the session configuration and the multi-agent version. If interrupt messages are turned off in the config, it returns Disabled. Otherwise it returns Developer for version 2 and ContextualUser for older versions.

Call relations: The abort path calls this when a task is interrupted so it can record the right kind of marker. Forking and subagent flows also use it so snapshots and child agents describe interruptions consistently.

Call graph: called by 3 (handle_task_abort, fork_thread_with_initial_history, spawn_subagent).

fn interrupted_turn_history_marker(
    marker: InterruptedTurnHistoryMarker,
) -> Option<ResponseItem>

Purpose: Builds the actual conversation item that tells the model a previous turn was interrupted. This is what later model calls can read to avoid treating the cut-off response as complete.

Data flow: It receives a marker choice. Disabled becomes no item. ContextualUser becomes a contextual user fragment with interruption guidance. Developer becomes a developer-role message containing developer-facing interruption guidance.

Call relations: The abort code calls this after deciding which marker style is allowed. Other history-building paths also call it so real interrupts and copied conversation snapshots use the same marker format.

Call graph: calls 2 internal fn (into, new); called by 4 (handle_task_abort, append_interrupted_boundary, contextual_user_interrupted_marker, developer_interrupted_marker); 1 external calls (vec!).

fn emit_turn_network_proxy_metric(
    session_telemetry: &SessionTelemetry,
    network_proxy_active: bool,
    tmp_mem: (&str, &str),
)

Purpose: Records whether the managed network proxy was active during a turn. This helps operators understand how often turns run with network routing enabled.

Data flow: It receives telemetry, a true-or-false proxy status, and an extra temporary memory-related tag. It converts the status into the text tag "true" or "false" and increments the network proxy metric.

Call relations: Session::on_task_finished calls this near the end of a turn after checking the current proxy state. It hands the result to the telemetry system as one small part of the turn summary.

Call graph: calls 1 internal fn (counter); called by 1 (on_task_finished).

fn emit_turn_memory_metric(
    session_telemetry: &SessionTelemetry,
    feature_enabled: bool,
    config_enabled: bool,
    has_citations: bool,
)

Purpose: Records whether memory reading was allowed and whether the turn actually cited memory. This helps compare feature settings with real memory use.

Data flow: It receives telemetry plus three booleans: whether the memory feature exists, whether config allows it, and whether citations appeared. It combines feature and config into a read_allowed value, converts booleans into metric tags, and increments the memory metric.

Call relations: Session::on_task_finished calls this after reading the turn state. It uses bool_tag to format values the telemetry system expects.

Call graph: calls 2 internal fn (bool_tag, counter); called by 1 (on_task_finished).

fn emit_compact_metric(
    session_telemetry: &SessionTelemetry,
    compact_type: &'static str,
    manual: bool,
)

Purpose: Records that conversation compaction ran. Compaction means shortening or summarizing stored context so future model calls fit within limits.

Data flow: It receives telemetry, the type of compaction, and whether it was started manually. It converts the manual flag into a text tag and increments the compaction metric with those labels.

Call relations: Automatic compaction code calls this when compaction happens. This file exposes it because compaction is one of the task types coordinated by the session task system.

Call graph: calls 2 internal fn (bool_tag, counter); called by 1 (run_auto_compact).

fn bool_tag(value: bool) -> &'static str

Purpose: Converts a true-or-false value into the exact text labels used by telemetry tags. It keeps metric formatting consistent.

Data flow: It receives a boolean. True becomes "true" and false becomes "false".

Call relations: Metric helpers call this before sending data to telemetry. It is deliberately tiny so all related metrics use the same spelling.

Call graph: called by 2 (emit_compact_metric, emit_turn_memory_metric).

fn new(session: Arc<Session>, turn_extension_data: Arc<ExtensionData>) -> Self

Purpose: Creates the small shared context object that task runners receive. It gives tasks access to the session and extension data without exposing every detail directly.

Data flow: It receives a shared Session and shared ExtensionData. It stores both inside a SessionTaskContext and returns that context.

Call relations: Session::start_task uses this when launching a task. Session::handle_task_abort uses it again when giving an interrupted task a chance to clean up.

Call graph: called by 2 (handle_task_abort, start_task).

fn clone_session(&self) -> Arc<Session>

Purpose: Returns another shared reference to the session for code that needs to call session methods. This avoids moving or owning the session outright.

Data flow: It reads the session reference stored in the context and returns a cloned shared pointer to the same session object.

Call relations: Task-running code can call this after receiving a SessionTaskContext. It is especially useful inside spawned background work where ownership must be shared safely.

Call graph: 1 external calls (clone).

fn turn_extension_data(&self) -> Arc<ExtensionData>

Purpose: Returns the extension data attached to this turn. Extensions can use this to read or write information tied to the current turn.

Data flow: It reads the stored ExtensionData reference and returns another shared pointer to the same data.

Call relations: Session tasks use this through the context when they need turn-specific extension state. The context was created by Session::start_task or the abort cleanup path.

Call graph: 1 external calls (clone).

fn auth_manager(&self) -> Arc<AuthManager>

Purpose: Gives a task access to the authentication manager, which is the component responsible for login and credentials. This lets task code perform authenticated operations when needed.

Data flow: It reaches through the stored session to the session services, clones the shared AuthManager pointer, and returns it.

Call relations: Task implementations can call this through their SessionTaskContext instead of knowing how services are stored inside Session.

Call graph: 1 external calls (clone).

fn models_manager(&self) -> SharedModelsManager

Purpose: Gives a task access to the shared model manager, the component that tracks available model information. This lets tasks ask about or use models without owning that service.

Data flow: It reads the models manager from the session services, clones the shared pointer, and returns it.

Call relations: Task implementations use this when they need model-related services. It keeps task code connected to session services through a narrow wrapper.

Call graph: 1 external calls (clone).

fn abort(
        &self,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
    ) -> impl std::future::Future<Output = ()> + Send

Purpose: Provides the default cleanup hook for a task that is being aborted. By default it does nothing, but task types can override it when they need special shutdown work.

Data flow: It receives the session context and turn context, then ignores them and completes immediately. No state is changed by the default version.

Call relations: The generic task adapter exposes this method, and Session::handle_task_abort eventually calls it through that adapter. Specific tasks can replace this no-op behavior with real cleanup.

Call graph: called by 1 (abort).

fn kind(&self) -> TaskKind

Purpose: Adapts any concrete SessionTask so it can be treated as a generic task object. It asks the concrete task what kind of work it represents.

Data flow: It receives a task value through the trait object adapter and forwards the request to that task’s own kind method. The TaskKind result comes back unchanged.

Call relations: Session::start_task stores tasks behind a common AnySessionTask interface. This adapter method lets the session ask for the task kind without knowing the concrete task type.

Call graph: 1 external calls (kind).

fn span_name(&self) -> &'static str

Purpose: Adapts any concrete SessionTask so tracing can name its background span. A tracing span is a labeled timing/logging scope used to follow work across async code.

Data flow: It receives the task through the adapter and forwards the call to the concrete task’s span_name method. It returns the static name supplied by that task.

Call relations: Session::start_task uses this through the generic task interface before spawning the background task, so logs and telemetry carry the right task name.

Call graph: 1 external calls (span_name).

fn run(
        self: Arc<Self>,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
        input: Vec<TurnInput>,
        cancellation_token: CancellationToken,
    ) -> BoxFutu

Purpose: Wraps a concrete task’s run method into a boxed future, which is a uniform async job value. This lets different task types be stored and launched through one shared interface.

Data flow: It receives the shared task, session context, turn context, input items, and cancellation token. It calls the task’s real run method and boxes the returned future so callers do not need to know its exact concrete type.

Call relations: Session::start_task calls run through AnySessionTask after converting a concrete SessionTask into a generic object. The adapter then hands execution to the real task implementation.

Call graph: 2 external calls (pin, run).

fn abort(
        &'a self,
        session: Arc<SessionTaskContext>,
        ctx: Arc<TurnContext>,
    ) -> BoxFuture<'a, ()>

Purpose: Wraps a concrete task’s abort cleanup method into a boxed future. This allows the session to call cleanup in the same way for every task type.

Data flow: It receives the task plus session and turn contexts. It calls the concrete task’s abort method and boxes the resulting async work.

Call relations: Session::handle_task_abort calls this through the generic AnySessionTask interface after cancelling the task. The adapter forwards cleanup to the task-specific implementation or the default no-op.

Call graph: calls 1 internal fn (abort); 1 external calls (pin).

async fn spawn_task(
        self: &Arc<Self>,
        turn_context: Arc<TurnContext>,
        input: Vec<TurnInput>,
        task: T,
    )

Purpose: Starts a new session task after first stopping any currently running one. This is the safe public path for replacing the active turn with new work.

Data flow: It receives a turn context, turn input, and a concrete task. It aborts existing tasks with the Replaced reason, clears connector selection, then passes the new task to start_task.

Call relations: Callers use this when a new explicit task should begin. It delegates the detailed launch work to Session::start_task after making sure the session is not already busy.

Call graph: calls 2 internal fn (abort_all_tasks, start_task).

async fn start_task(
        self: &Arc<Self>,
        turn_context: Arc<TurnContext>,
        input: Vec<TurnInput>,
        task: T,
    )

Purpose: Launches a turn task in the background and records all the state needed to track, cancel, and finish it. This is the main setup point for a running turn.

Data flow: It receives the turn context, input, and task. It records start time and starting token usage, prepares cancellation and notification objects, attaches pending input to turn state, builds a task context, creates a tracing span, spawns the async task, starts a duration timer, and stores a RunningTask in the active turn.

Call relations: Session::spawn_task calls this for normal new work, and pending-work startup calls it when mailbox input should wake an idle session. The spawned task eventually calls Session::on_task_finished unless it was cancelled.

Call graph: calls 1 internal fn (new); called by 2 (maybe_start_turn_for_pending_work_with_sub_id, spawn_task); 15 external calls (new, clone, new, new, now, new, kind, span_name, debug_assert!, format! (+5 more)).

async fn maybe_start_turn_for_pending_work(self: &Arc<Self>)

Purpose: Starts a new regular turn if the session is idle and queued input says a turn should be triggered. It creates a fresh turn id for that synthetic turn.

Data flow: It creates a new random sub-id, then passes that id to maybe_start_turn_for_pending_work_with_sub_id. The result is either no action or a newly started regular task.

Call relations: Abort paths call this after an interruption because pending mailbox work may need to resume immediately. It delegates the actual checks and task startup to the sub-id-specific helper.

Call graph: calls 1 internal fn (maybe_start_turn_for_pending_work_with_sub_id); called by 2 (abort_all_tasks, abort_turn_if_active); 1 external calls (new_v4).

async fn maybe_start_turn_for_pending_work_with_sub_id(
        self: &Arc<Self>,
        sub_id: String,
    )

Purpose: Starts a regular task for queued work, but only when queued mailbox items request it and no turn is already active. This prevents background mail from being ignored while also avoiding overlapping turns.

Data flow: It receives the sub-id to use for the new turn. It checks whether trigger-turn mailbox items exist, checks and marks the session as active if idle, builds a default turn context with that sub-id, possibly emits an unknown-model warning, and starts a RegularTask with no direct user input.

Call relations: maybe_start_turn_for_pending_work calls this with a fresh id. It calls Session::start_task once it has proven that a pending turn should actually begin.

Call graph: calls 3 internal fn (default, start_task, new); called by 1 (maybe_start_turn_for_pending_work); 1 external calls (new).

async fn abort_all_tasks(self: &Arc<Self>, reason: TurnAbortReason)

Purpose: Stops the currently active task, if there is one, and cleans up turn state afterward. This is used when new work replaces old work or when the user interrupts the session.

Data flow: It takes the active turn out of the session, removes its task, and if a task existed sends it to handle_task_abort with the given reason. It emits abort lifecycle events, clears pending input after the task has seen cancellation, and may start pending work again after an interruption.

Call relations: Session::spawn_task calls this before launching replacement work. It relies on take_active_turn to remove the active turn and handle_task_abort to perform the actual task cancellation.

Call graph: calls 3 internal fn (handle_task_abort, maybe_start_turn_for_pending_work, take_active_turn); called by 1 (spawn_task); 1 external calls (clone).

async fn abort_turn_if_active(
        self: &Arc<Self>,
        turn_id: &str,
        reason: TurnAbortReason,
    ) -> bool

Purpose: Stops a specific active turn only if its turn id matches the requested id. This lets callers cancel one known turn without accidentally cancelling newer work.

Data flow: It receives a turn id and abort reason. It checks the active task’s turn id; if it matches, it removes the active turn, aborts the task, emits lifecycle cleanup, clears pending input, possibly starts pending work, and returns true. If there is no match, it returns false.

Call relations: External or higher-level cancellation flows can use this targeted abort path. Like abort_all_tasks, it delegates the cancellation details to handle_task_abort.

Call graph: calls 2 internal fn (handle_task_abort, maybe_start_turn_for_pending_work); 1 external calls (clone).

async fn on_task_finished(
        self: &Arc<Self>,
        turn_context: Arc<TurnContext>,
        last_agent_message: Option<String>,
    )

Purpose: Finalizes a turn that completed normally. It records useful facts, sends the TurnComplete event to the client, clears active state, and marks the thread idle if nothing else is running.

Data flow: It receives the turn context and optional final agent message. It detaches the task handle, gathers pending input and turn state, runs hooks for pending input, computes token usage since turn start, emits metrics and analytics, emits lifecycle stop events, sends a completion event, clears rejection state, and removes the active turn if it still matches this turn.

Call relations: The background task spawned by Session::start_task calls this after the task’s run method returns and the transcript is flushed. It calls helper functions for pending-input inspection and telemetry such as emit_turn_network_proxy_metric and emit_turn_memory_metric.

Call graph: calls 5 internal fn (inspect_pending_input, record_additional_contexts, record_pending_input, emit_turn_memory_metric, emit_turn_network_proxy_metric); 5 external calls (ptr_eq, current, try_from, TurnComplete, warn!).

async fn take_active_turn(&self) -> Option<ActiveTurn>

Purpose: Removes and returns the current active turn from the session. This is a small helper used when the session needs to stop owning the active turn before aborting it.

Data flow: It locks the active-turn slot, takes out the Option value, leaves the slot empty, and returns the previous active turn if one existed.

Call relations: Session::abort_all_tasks calls this before aborting so the task is no longer considered active while cancellation and cleanup proceed.

Call graph: called by 1 (abort_all_tasks).

async fn close_unified_exec_processes(&self)

Purpose: Terminates all background execution processes owned by the unified execution manager. This is a cleanup tool for shell or command processes that may still be running.

Data flow: It reads the unified execution manager from session services and asks it to terminate every process. It does not return process details.

Call relations: Other session control code can call this when shutting down or cleaning up execution resources. The actual process work is delegated to the unified execution manager.

async fn list_background_terminals(&self) -> Vec<BackgroundTerminalInfo>

Purpose: Returns information about currently running background terminal processes. This lets clients show users what background command sessions exist.

Data flow: It asks the unified execution manager for its process list and returns that list as BackgroundTerminalInfo values.

Call relations: UI or protocol code can call this when it needs to display background terminals. This method is a session-level doorway to the underlying execution manager.

async fn terminate_background_terminal(&self, process_id: i32) -> bool

Purpose: Stops one background terminal process by process id. It gives callers a focused way to kill a single running command session.

Data flow: It receives a numeric process id, passes it to the unified execution manager, and returns true or false depending on whether termination succeeded.

Call relations: Client-facing terminal controls can call this when a user chooses to stop one background process. The session delegates the actual termination to the unified execution manager.

async fn handle_task_abort(self: &Arc<Self>, task: RunningTask, reason: TurnAbortReason)

Purpose: Performs the detailed shutdown of one running task. It cancels the task, waits briefly for a graceful stop, forces abort if needed, lets the task clean up, records interruption history when appropriate, and sends the TurnAborted event.

Data flow: It receives a RunningTask and an abort reason. If the task is not already cancelled, it cancels the token, cancels git enrichment, waits up to a short timeout for the task to finish, aborts the task handle, calls task-specific cleanup, optionally writes an interruption marker to conversation history, records timing and analytics, sends the abort event, and clears guardian rejection state.

Call relations: Session::abort_all_tasks and Session::abort_turn_if_active call this after removing a task from active state. It uses InterruptedTurnHistoryMarker::from_config_and_version and interrupted_turn_history_marker to make interruptions visible in later conversation history.

Call graph: calls 3 internal fn (from_config_and_version, new, interrupted_turn_history_marker); called by 2 (abort_all_tasks, abort_turn_if_active); 7 external calls (clone, new, TurnAborted, select!, from_ref, trace!, warn!).

fn default() -> Self

Purpose: Creates a fresh ActiveTurn with no running task and a new, empty TurnState. This is used when a session needs a clean starting point for turn-scoped state.

Data flow: No input is needed. The function builds an ActiveTurn where task is empty, creates a default TurnState, wraps it in a shared pointer and mutex for safe async sharing, and returns the ready-to-use value.

Call relations: Tests and session flows call this when they need a blank active-turn container. It relies on the default TurnState setup so all pending request lists, mailbox rules, counters, and flags start in their normal empty state.

Call graph: called by 17 (handle_request_permissions_uses_tool_call_id_for_round_trip, codex_apps_auth_elicitation_feature_enabled_requests_elicitation, prompt_mode_waits_for_approval_when_annotations_do_not_require_approval, enable_strict_auto_review_for_turn_uses_originating_turn, request_permissions_guardian_review_stops_when_cancelled, request_permissions_routes_to_guardian_when_reviewer_is_enabled, shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature, strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip, notify_request_permissions_response_ignores_unmatched_call_id, record_granted_request_permissions_for_turn_uses_originating_turn (+7 more)); 3 external calls (new, new, default).

fn insert_pending_approval(
        &mut self,
        key: String,
        tx: oneshot::Sender<ReviewDecision>,
    ) -> Option<oneshot::Sender<ReviewDecision>>

Purpose: Registers that the current turn is waiting for a review or approval decision. The stored sender is the route used later to deliver that decision back to the waiting code.

Data flow: It takes a text key and a single-use sender for a ReviewDecision. It puts that sender into the pending approvals map under the key, and returns any older sender that was already stored for the same key.

Call relations: Other turn-processing code uses this before asking for an approval. A later response path is expected to use TurnState::remove_pending_approval with the same key so the answer can be sent to the original waiter.

fn remove_pending_approval(
        &mut self,
        key: &str,
    ) -> Option<oneshot::Sender<ReviewDecision>>

Purpose: Finds and removes a waiting approval request. This is how an incoming approval answer is matched back to the code that asked for it.

Data flow: It receives a key, looks in the pending approvals map, removes the matching sender if present, and returns it. If no request with that key is waiting, it returns nothing.

Call relations: This is the counterpart to TurnState::insert_pending_approval. Response-handling code calls it when an approval decision arrives, then uses the returned sender to wake the original requester.

fn clear_pending_waiters(&mut self)

Purpose: Drops all outstanding waiters for approvals, permission requests, user input, elicitations, and dynamic tool responses. This is useful when a turn is cancelled or ended and nobody should keep waiting for old answers.

Data flow: It reads no outside data. It empties each pending-response map in the TurnState, which also drops the one-shot senders stored there. Afterward, those pending requests are no longer tracked.

Call relations: Turn cleanup or cancellation code can call this to make the state safe to discard. It does not hand work to another function; it simply clears every category of pending waiter at once.

fn insert_pending_request_permissions(
        &mut self,
        key: String,
        pending_request_permissions: PendingRequestPermissions,
    ) -> Option<PendingRequestPermissions>

Purpose: Records that the turn has asked for extra permissions and is waiting for a permissions response. It keeps not just the reply route, but also what permissions were requested and which environment they apply to.

Data flow: It takes a key and a PendingRequestPermissions record. It stores that record in the pending permission-request map and returns any previous record that used the same key.

Call relations: Permission-request code uses this before sending a request out for review or user approval. When the response comes back, the matching path should call TurnState::remove_pending_request_permissions to recover the saved request details and response sender.

fn remove_pending_request_permissions(
        &mut self,
        key: &str,
    ) -> Option<PendingRequestPermissions>

Purpose: Retrieves and removes a pending permission request. This lets the system match an incoming permissions answer to the exact request that started it.

Data flow: It receives a key, removes the matching PendingRequestPermissions record from the map if one exists, and returns it. If the key is unknown, it returns nothing.

Call relations: This pairs with TurnState::insert_pending_request_permissions. Response-handling code uses it when a permissions decision arrives so it can send the answer back and know which requested permissions and environment were involved.

fn insert_pending_user_input(
        &mut self,
        key: String,
        tx: oneshot::Sender<RequestUserInputResponse>,
    ) -> Option<oneshot::Sender<RequestUserInputResponse>>

Purpose: Records that the turn is waiting for direct user input. The stored sender is the channel used to return the user’s answer to the waiting task.

Data flow: It takes a key and a single-use sender for a RequestUserInputResponse. It stores the sender under the key and returns any older sender that had the same key.

Call relations: Code that asks the user a follow-up question uses this before sending the prompt. Later, when the user answers, the response path should call TurnState::remove_pending_user_input to find where to deliver that answer.

fn remove_pending_user_input(
        &mut self,
        key: &str,
    ) -> Option<oneshot::Sender<RequestUserInputResponse>>

Purpose: Finds and removes the waiting slot for a user-input request. It is the lookup step that connects a user’s answer with the task that asked the question.

Data flow: It receives a key, removes the matching user-input sender from the map, and returns it if present. If no matching request is waiting, it returns nothing.

Call relations: This is the response-side partner of TurnState::insert_pending_user_input. User-input response handling uses it to wake the task that was paused for the user’s answer.

fn insert_pending_elicitation(
        &mut self,
        server_name: String,
        request_id: RequestId,
        tx: oneshot::Sender<ElicitationResponse>,
    ) -> Option<oneshot::Sender<Elicitat

Purpose: Registers that an external server has asked for more information and the turn is waiting for that elicitation response. “Elicitation” here means a tool or server prompting the user or system for extra details.

Data flow: It takes the server name, that server’s request ID, and a single-use sender for an ElicitationResponse. It stores the sender under the combined server-and-request key and returns any older sender for the same pair.

Call relations: External-tool or server integration code uses this when it starts an elicitation request. The matching answer path should later call TurnState::remove_pending_elicitation with the same server name and request ID.

fn remove_pending_elicitation(
        &mut self,
        server_name: &str,
        request_id: &RequestId,
    ) -> Option<oneshot::Sender<ElicitationResponse>>

Purpose: Looks up and removes a waiting elicitation response for a specific server and request ID. This prevents responses from different servers or repeated request IDs from being mixed up.

Data flow: It receives a server name and request ID, builds the same combined key used for insertion, removes the sender if present, and returns it. It clones the request ID only to form the lookup key safely.

Call relations: This completes the flow started by TurnState::insert_pending_elicitation. When an elicitation answer arrives, response-handling code calls this to recover the correct sender and deliver the answer.