Core shared protocol and domain types

fn new() -> Self

Purpose: Creates a brand-new thread ID. Code uses this when it is starting a new thread and needs a unique name for it.

Data flow: Nothing is passed in. The function asks the UUID library to make a new version 7 UUID, wraps that value inside ThreadId, and returns the new ID.

Call relations: This is the starting point whenever tests or runtime code need a fresh thread identifier. ThreadId::default also uses it, so code that asks for a default thread ID gets a real new ID rather than an empty placeholder.

Call graph: called by 465 (collab_resume_begin_maps_to_item_started_resume_agent, collab_resume_end_maps_to_item_completed_resume_agent, ignores_user_message_item_lifecycle_events, preserves_user_message_client_id_from_legacy_event, rebuilds_sleep_item_from_persisted_completion, command_execution_started_helper_emits_once, complete_command_execution_item_emits_declined_once_for_pending_command, guardian_assessment_aborted_emits_completed_review_payload, guardian_assessment_completed_emits_review_payload, guardian_assessment_started_uses_event_turn_id_fallback (+15 more)); 1 external calls (now_v7).

fn from_string(s: &str) -> Result<Self, uuid::Error>

Purpose: Turns text into a ThreadId, but only if the text is a valid UUID. This is useful when an ID comes from JSON, a database, an API request, or a test fixture.

Data flow: A string slice goes in. The function asks the UUID library to parse it. If parsing succeeds, the UUID is wrapped in ThreadId; if parsing fails, the UUID parsing error comes back.

Call relations: Other conversion paths rely on this function so parsing rules stay in one place. It is used wherever the system receives a thread ID as plain text and needs to turn it into the safer internal type.

Call graph: called by 318 (thread_id, compaction_event_ingests_custom_fact, subagent_events_use_inherited_connection_unless_turn_connection_is_explicit, subagent_thread_started_other_serializes_explicit_parent_thread_id, subagent_thread_started_thread_spawn_serializes_thread_lineage, conversation_id_serializes_as_plain_string, serialize_get_conversation_summary, serialize_server_request, rollback_response_rebuilds_pathless_thread_from_stored_history, source_kind_matches_distinguishes_subagent_variants (+15 more)); 1 external calls (parse_str).

fn try_from(value: String) -> Result<Self, Self::Error>

Purpose: Provides a standard Rust conversion from text into ThreadId that can fail. Someone would use this when they want normal conversion syntax but still want invalid UUID strings to be rejected.

Data flow: Text goes in, either directly or as an owned String depending on the conversion being used. The function passes that text to ThreadId::from_string; the result is either a valid ThreadId or a parsing error.

Call relations: This is a convenience layer over ThreadId::from_string. Callers in tests and reconstruction code can use Rust’s try_from pattern while still sharing the same validation behavior.

Call graph: called by 10 (reconstructs_collab_spawn_end_item_with_model_metadata, reconstructs_interrupted_send_input_as_completed_collab_call, test_model_client_session, fixed_thread_id, try_from, try_from, get_phase2_input_selection, stage1_output_from_row_if_thread_enabled, generic_url_target, suggestion_target); 1 external calls (from_string).

fn from(value: ThreadId) -> Self

Purpose: Converts a ThreadId back into ordinary text. This is useful when the ID needs to be stored, sent over an API, or compared as a string.

Data flow: A ThreadId goes in. The function formats it as its UUID text form and returns that String.

Call relations: This complements the parsing functions. After the system has used the safer ThreadId type internally, this conversion lets it hand the value back to places that expect plain text.

Call graph: 1 external calls (to_string).

fn default() -> Self

Purpose: Provides the default value for ThreadId, and that default is a fresh real ID. It avoids using a fake all-zero UUID as a fallback.

Data flow: Nothing is passed in. The function calls ThreadId::new and returns the newly generated ID.

Call relations: Any code that asks Rust for a default ThreadId is routed through normal ID creation. The test in this file checks that this path does not produce the nil, or all-zero, UUID.

Call graph: called by 59 (app_server_event_sink_uses_listener_fifo_for_goal_updates_and_clears, record_initial_history_reconstructs_typed_inter_agent_message, record_initial_history_resumed_aborted_turn_without_id_clears_active_turn_for_compaction_accounting, record_initial_history_resumed_bare_turn_context_does_not_hydrate_previous_turn_settings, record_initial_history_resumed_bare_turn_context_does_not_seed_reference_context_item, record_initial_history_resumed_does_not_seed_reference_context_item_after_compaction, record_initial_history_resumed_hydrates_previous_turn_settings_from_lifecycle_turn_with_missing_turn_context_id, record_initial_history_resumed_replaced_incomplete_compacted_turn_clears_reference_context_item, record_initial_history_resumed_rollback_drops_incomplete_user_turn_compaction_metadata, record_initial_history_resumed_rollback_skips_only_user_turns (+15 more)); 1 external calls (new).

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

Purpose: Defines how a ThreadId is printed for humans or logs. It prints as the underlying UUID string.

Data flow: The function receives a ThreadId and a formatter, which is Rust’s object for building formatted text. It writes the UUID’s normal text form into that formatter and returns whether formatting succeeded.

Call relations: This supports .to_string() and other display-style formatting. The string conversion and serializer depend on this kind of text representation being stable and ordinary.

Call graph: 1 external calls (fmt).

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

Purpose: Teaches Serde, the Rust serialization library, how to write a ThreadId into formats like JSON. It stores the ID as a simple string, not as an object with internal fields.

Data flow: A ThreadId and a serializer go in. The function gives the UUID’s text form to the serializer. The output is whatever serialized representation the chosen format produces, such as a JSON string.

Call relations: This is used whenever protocol messages containing thread IDs are sent, saved, or compared in serialized form. It keeps the public wire format simple while preserving the safer internal type.

Call graph: 1 external calls (collect_str).

fn deserialize(deserializer: D) -> Result<Self, D::Error>

Purpose: Teaches Serde how to read a ThreadId from serialized data. It expects a string and rejects it if it is not a valid UUID.

Data flow: Serialized input goes in through a deserializer. The function first reads a String, then parses that string as a UUID. On success it returns a ThreadId; on failure it reports a deserialization error.

Call relations: This is the receiving-side partner to ThreadId::serialize. When JSON or another serialized format enters the system, this function turns the plain string back into the checked internal type.

Call graph: 2 external calls (deserialize, parse_str).

fn schema_name() -> String

Purpose: Gives schema-generation tools the name ThreadId for this type. A schema is a machine-readable description of what data should look like.

Data flow: Nothing is passed in. The function returns the fixed name ThreadId as a string.

Call relations: Schema generation calls this when documenting or validating protocol shapes. The name helps generated documentation and tooling refer to this type clearly.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Purpose: Describes ThreadId in JSON Schema as a string. This matches how the ID is actually serialized.

Data flow: A schema generator goes in. Instead of exposing the internal UUID field, the function reuses the schema for String and returns that schema.

Call relations: This works with ThreadId::schema_name to keep generated protocol schemas simple. Outside clients see that a thread ID is sent as text, just like the JSON serializer produces.

Call graph: 1 external calls (json_schema).

fn test_thread_id_default_is_not_zeroes()

Purpose: Checks that the default ThreadId is a real generated ID, not the all-zero UUID. This protects against accidentally using a meaningless placeholder as a thread identifier.

Data flow: The test creates a default ThreadId, reads its internal UUID, and compares it with the UUID library’s nil value. The test passes only if they are different.

Call relations: This test exercises ThreadId::default, which in turn uses ThreadId::new. It acts as a small safety check for code paths that rely on default thread IDs being usable.

Call graph: calls 1 internal fn (default); 1 external calls (assert_ne!).

fn new() -> Self

Purpose: Creates a fresh session identifier. Use this when the system starts a new session and needs a unique name for it.

Data flow: It takes no input. It asks the UUID library to make a new version 7 UUID, then wraps that UUID in a SessionId. The result is a new SessionId value ready to store, compare, print, or send over the protocol.

Call relations: This is the source of new session IDs. It is called by setup and test flows such as websocket_harness_with_provider_options, config_summary_entries_include_runtime_workspace_roots, and event-sending tests when they need a realistic session identity.

Call graph: called by 5 (websocket_harness_with_provider_options, config_summary_entries_include_runtime_workspace_roots, test_send_event_as_notification, test_send_event_as_notification_with_meta, test_send_event_as_notification_with_meta_and_thread_id); 1 external calls (now_v7).

fn from_string(s: &str) -> Result<Self, uuid::Error>

Purpose: Builds a SessionId from text. Use this when an ID arrives from JSON, a log, a stored value, or another string-based source.

Data flow: It receives a string slice. It asks the UUID library to parse that string as a UUID. If parsing succeeds, it wraps the UUID in SessionId; if the text is not a valid UUID, it returns the parsing error.

Call relations: This is the main text-to-session conversion helper. It is used by flows like session_configured_from_thread_response and serialize_event, where session IDs need to be reconstructed from their string form.

Call graph: called by 2 (session_configured_from_thread_response, serialize_event); 1 external calls (parse_str).

fn try_from(value: String) -> Result<Self, Self::Error>

Purpose: Provides a standard Rust conversion path from a string-like value into a SessionId, with failure if the text is not a valid UUID.

Data flow: It receives text, forwards that text to SessionId::from_string, and returns either the parsed SessionId or the UUID parsing error unchanged.

Call relations: This function exists so generic Rust conversion code can say “try to make a SessionId from this string” without knowing the parsing details. It delegates the real work to SessionId::from_string.

Call graph: 1 external calls (from_string).

fn from(value: SessionId) -> Self

Purpose: Turns a SessionId into an ordinary String. Use this when code needs to pass the ID to something that expects plain text.

Data flow: It receives a SessionId, formats it using its string representation, and returns that text as a String. The original identifier value is consumed by the conversion.

Call relations: This supports standard Rust From conversion in the outward direction: from a typed session ID to plain text. It relies on the display formatting behavior defined for SessionId.

Call graph: 1 external calls (to_string).

fn from(value: ThreadId) -> Self

Purpose: Creates a SessionId from a ThreadId while keeping the exact same underlying UUID. This is useful when a thread identity should also be treated as a session identity.

Data flow: It receives a ThreadId, reads its UUID, and puts that UUID into a new SessionId. No new ID is generated and no text parsing happens.

Call relations: This conversion is used in session and subagent setup flows such as make_session_and_context, session_configured_produces_thread_started_event, and stream_stage_one_prompt. The test converts_to_and_from_thread_id also uses it to prove the conversion does not change the identity.

Call graph: called by 8 (new, emit_subagent_session_started_includes_fork_lineage_from_session_configuration, make_session_and_context, make_session_and_context_with_auth_config_home_and_rx, resumed_subagent_session_keeps_inherited_session_id, session_configured_produces_thread_started_event, stream_stage_one_prompt, converts_to_and_from_thread_id).

fn from(value: SessionId) -> Self

Purpose: Creates a ThreadId from a SessionId while preserving the same UUID. This lets code move back from the session view of an ID to the thread view.

Data flow: It receives a SessionId, copies out its UUID, and returns a ThreadId containing that UUID. The identity remains the same; only the wrapper type changes.

Call relations: This is the reverse of SessionId::from for ThreadId. Together, they let session-oriented and thread-oriented parts of the protocol share the same identifier without inventing a new one.

fn default() -> Self

Purpose: Provides the default way to make a SessionId, which is to create a fresh one. This keeps default construction safe instead of producing an empty or placeholder ID.

Data flow: It takes no input. It calls SessionId::new and returns the newly generated ID.

Call relations: This is used when Rust code asks for a default SessionId. The test tests::test_session_id_default_is_not_zeroes calls it to confirm the default is a real generated UUID, not the all-zero UUID.

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

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

Purpose: Defines how a SessionId appears as text when printed or formatted. This makes logs, error messages, and string conversions show the UUID clearly.

Data flow: It receives a SessionId and a formatter. It forwards formatting to the inner UUID, so the output is the usual UUID string form.

Call relations: This formatting behavior is used anywhere SessionId is turned into text, including the String::from conversion and serializer behavior that collects the ID as a string.

Call graph: 1 external calls (fmt).

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

Purpose: Tells Serde, the Rust serialization library, to write a SessionId as a string. This is what makes the ID appear naturally in JSON and other serialized formats.

Data flow: It receives a SessionId and a serializer. It gives the UUID’s text form to the serializer, which produces the final serialized output for the chosen format.

Call relations: This is used whenever protocol data containing a SessionId is sent or stored through Serde. It ensures outside systems see a simple string rather than Rust’s internal wrapper structure.

Call graph: 1 external calls (collect_str).

fn deserialize(deserializer: D) -> Result<Self, D::Error>

Purpose: Tells Serde how to read a SessionId back from serialized data. It expects the incoming value to be a string containing a valid UUID.

Data flow: It receives a deserializer, reads a String from it, and tries to parse that string as a UUID. If parsing works, it returns a SessionId; if not, it turns the UUID parsing failure into a Serde error.

Call relations: This is the counterpart to SessionId::serialize. It is used when JSON or another serialized format is read back into Rust protocol types and the plain string must become a strongly typed SessionId again.

Call graph: 2 external calls (deserialize, parse_str).

fn schema_name() -> String

Purpose: Gives the JSON Schema name for this type. JSON Schema is a machine-readable description of what valid JSON data should look like.

Data flow: It takes no input and returns the fixed name SessionId as a string.

Call relations: Schema generation code calls this when it needs a human-readable type name for SessionId in generated API or protocol documentation.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Purpose: Describes a SessionId in JSON Schema as a string. This matches how the ID is actually serialized over the wire.

Data flow: It receives a schema generator and asks the existing String schema logic to produce the schema. The result is a schema saying that this value is represented as text.

Call relations: This keeps generated schemas aligned with serialization. Since SessionId::serialize writes a string, this function hands off to the string schema generator instead of exposing the internal UUID wrapper.

Call graph: 1 external calls (json_schema).

fn test_session_id_default_is_not_zeroes()

Purpose: Checks that the default SessionId is a real generated ID, not the all-zero UUID. This protects against accidentally using a meaningless placeholder as a session identity.

Data flow: It creates a default SessionId, compares its inner UUID with the nil UUID, and passes only if they are different.

Call relations: This test calls SessionId::default, which in turn calls SessionId::new. It verifies the expected behavior of default construction.

Call graph: calls 1 internal fn (default); 1 external calls (assert_ne!).

fn converts_to_and_from_thread_id()

Purpose: Checks that converting between ThreadId and SessionId preserves the same identity. This guards the assumption that these two ID types can share one UUID safely.

Data flow: It creates a new ThreadId, converts it into a SessionId, converts that back into a ThreadId, and checks that the final value equals the original.

Call relations: This test exercises the conversion functions SessionId::from and ThreadId::from. It confirms that no new UUID is generated and no value is lost during the round trip.

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

fn root() -> Self

Purpose: Creates the standard root agent path, /root. Code uses this when it needs the top of the agent tree.

Data flow: No input is needed. The function takes the built-in root path text and wraps it as an AgentPath. The result is a ready-to-use path for the root agent.

Call relations: Many parts of the system call this when they need a safe starting point for agent lookup, messaging, listing, tests, or recovery. It does not delegate to validation because /root is a fixed known-good value.

Call graph: called by 38 (list_agents, encrypted_inter_agent_communication_clears_existing_last_task_message, ensure_v2_agent_loaded_reloads_registered_unloaded_agent, list_agent_subtree_thread_ids_includes_anonymous_and_closed_descendants, multi_agent_v2_completion_ignores_dead_direct_parent, multi_agent_v2_completion_queues_message_for_direct_parent, resume_agent_from_rollout_does_not_reopen_v2_descendants, send_inter_agent_communication_without_turn_queues_message_without_triggering_turn, spawn_agent_can_fork_parent_thread_history_with_sanitized_items, spawn_agent_fork_last_n_turns_keeps_only_recent_turns (+15 more)).

fn morpheus() -> Self

Purpose: Creates the special Morpheus agent path, /morpheus. This is separate from the normal /root/... agent tree.

Data flow: No input is needed. The function takes the built-in Morpheus path text and wraps it as an AgentPath. The result is a valid special path.

Call relations: It is used by the Morpheus path test to confirm that this special path behaves like a normal AgentPath where appropriate, while not being mistaken for root.

Call graph: called by 1 (morpheus_has_expected_name).

fn from_string(path: String) -> Result<Self, String>

Purpose: Turns a plain string into an AgentPath, but only if the string follows the project’s path rules. This is the main checkpoint for accepting stored or incoming path text.

Data flow: It receives a String. It asks validate_absolute_path whether the text is allowed. If validation passes, it wraps the same string in AgentPath; if not, it returns a clear error message.

Call relations: Higher-level code calls this when restoring or filtering agents from stored path strings. The conversion helpers also route through it, so there is one shared validation path instead of many slightly different ones.

Call graph: calls 1 internal fn (validate_absolute_path); called by 2 (resume_thread_subagent_restores_stored_nickname_and_role, multi_agent_v2_list_agents_filters_by_relative_path_prefix).

fn as_str(&self) -> &str

Purpose: Returns the path as ordinary text without copying it. This is useful when other code needs to compare, print, store, or pass the path onward.

Data flow: It receives an existing AgentPath. It borrows the inner string slice and returns that borrowed view. Nothing is changed or allocated.

Call relations: Other convenience methods, such as display formatting, dereferencing, root checks, and name extraction, all call this so they read the path in the same simple way.

Call graph: called by 8 (agent_id_for_path, release_reserved_agent_path, forward_child_completion_to_parent, as_ref, deref, fmt, is_root, name).

fn is_root(&self) -> bool

Purpose: Checks whether this path is exactly /root. Code uses this when root needs special treatment.

Data flow: It reads the path through as_str, compares it with the fixed root path text, and returns true or false. The original path is unchanged.

Call relations: The name method calls this because root’s name is handled specially. Other agent-tree logic can also use it to decide whether a path is the top of the tree.

Call graph: calls 1 internal fn (as_str); called by 2 (agent_matches_prefix, name).

fn name(&self) -> &str

Purpose: Returns the last visible name in the path, such as researcher from /root/researcher. For /root, it returns root.

Data flow: It reads the current path. If the path is root, it returns the reserved root segment. Otherwise, it splits the path around / and returns the final non-empty segment, falling back to root only as a safety fallback.

Call relations: It builds on is_root and as_str. Callers use it when they need a human-friendly or local name for an agent rather than the full absolute path.

Call graph: calls 2 internal fn (as_str, is_root).

fn join(&self, agent_name: &str) -> Result<Self, String>

Purpose: Creates a child path below the current agent path. For example, joining worker onto /root/researcher produces /root/researcher/worker.

Data flow: It receives the current path and a proposed child agent name. It first validates that the child name is safe, then formats parent and child with a slash between them, and finally creates a new validated AgentPath. On failure, it returns an error message.

Call relations: This is the normal way to grow the agent tree one child at a time. It relies on validate_agent_name for the new segment and on from_string to ensure the final full path is valid too.

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

fn resolve(&self, reference: &str) -> Result<Self, String>

Purpose: Turns a path reference into a full AgentPath, using the current path as the base for relative references. This lets callers accept both worker and /root/other safely.

Data flow: It receives the current path and a reference string. Empty references are rejected. The exact /root reference becomes the root path. References starting with / are treated as absolute and validated directly. Other references are checked as relative segments, appended to the current path, and turned into a new AgentPath.

Call relations: This function sits between user-like input and the strict AgentPath type. It calls validate_relative_reference for relative text, uses try_from for absolute text, and uses root for the special root case.

Call graph: calls 1 internal fn (validate_relative_reference); 4 external calls (from_string, root, try_from, format!).

fn try_from(value: &str) -> Result<Self, Self::Error>

Purpose: Provides Rust’s standard fallible conversion into AgentPath. “Fallible” means the conversion can fail if the text is not a valid path.

Data flow: It receives path text and passes it to from_string. If validation succeeds, the output is an AgentPath; if validation fails, the output is the validation error.

Call relations: Many tests and agent workflows use this conversion when they already have path text. Internally it keeps all path checking centralized by handing off to from_string.

Call graph: called by 29 (interrupted_subagent_activity_removes_missing_thread_watch, encrypted_inter_agent_communication_clears_existing_last_task_message, ensure_v2_agent_loaded_reloads_registered_unloaded_agent, send_inter_agent_communication_without_turn_queues_message_without_triggering_turn, spawn_agent_can_fork_parent_thread_history_with_sanitized_items, spawn_agent_fork_last_n_turns_keeps_only_recent_turns, agent_path, input_queue_drains_mailbox_in_delivery_order, input_queue_notifies_mailbox_subscribers, input_queue_tracks_pending_trigger_turn_mail (+15 more)); 1 external calls (from_string).

fn from(value: AgentPath) -> Self

Purpose: Converts an AgentPath back into a plain String. This is useful for storage, serialization, or APIs that expect ordinary text.

Data flow: It receives an owned AgentPath, takes out its inner string, and returns that string. The AgentPath value is consumed in the process.

Call relations: Serialization support uses this pattern because the path should travel over the wire or into files as a simple string, while the Rust code can still keep the safer AgentPath wrapper internally.

fn from_str(s: &str) -> Result<Self, Self::Err>

Purpose: Lets code parse an AgentPath from a string slice using Rust’s standard parsing pattern. This is convenient for code that calls .parse().

Data flow: It receives borrowed text, sends it through try_from, and returns either a valid AgentPath or an error message. The input text is not changed.

Call relations: This is another doorway into the same validation rules. Instead of duplicating checks, it delegates to try_from.

Call graph: 1 external calls (try_from).

fn as_ref(&self) -> &str

Purpose: Lets an AgentPath be borrowed as a plain string reference in generic Rust code. This avoids unnecessary copying.

Data flow: It receives an AgentPath by reference, calls as_str, and returns a borrowed string view. No data is changed.

Call relations: It is a small adapter for Rust traits. Any code that accepts something “as a string reference” can use AgentPath through this method.

Call graph: calls 1 internal fn (as_str).

fn deref(&self) -> &Self::Target

Purpose: Lets an AgentPath behave like a string slice in places where Rust’s dereference rules apply. This makes the wrapper easier to use without exposing invalid construction.

Data flow: It receives a borrowed AgentPath, calls as_str, and returns a borrowed str. The path stays unchanged.

Call relations: Like as_ref, this is a convenience bridge. It hands off to as_str so all string views come from the same source.

Call graph: calls 1 internal fn (as_str).

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: Defines how an AgentPath is printed for users, logs, and formatted strings. It prints exactly the path text.

Data flow: It receives the path and a formatter, reads the path through as_str, and writes that text into the formatter. The result reports whether writing succeeded.

Call relations: This supports Rust’s display formatting, such as putting an AgentPath inside a formatted message. It delegates the actual write to the formatter after getting the string view.

Call graph: calls 1 internal fn (as_str); 1 external calls (write_str).

fn validate_agent_name(agent_name: &str) -> Result<(), String>

Purpose: Checks one agent name segment, such as researcher, before it is allowed into a path. It blocks empty names, reserved names, slashes, uppercase letters, and other unsupported characters.

Data flow: It receives one proposed agent name. It runs a series of checks: not empty, not root, not . or .., no /, and only lowercase letters, digits, or underscores. It returns success if all checks pass, otherwise a specific error message.

Call relations: Both full-path validation and relative-reference validation call this for each segment. join also calls it before appending a new child name, so unsafe names are rejected at the edge.

Call graph: called by 3 (join, validate_absolute_path, validate_relative_reference); 1 external calls (format!).

fn validate_absolute_path(path: &str) -> Result<(), String>

Purpose: Checks whether a full path is allowed as an absolute agent path. This protects the system from paths that do not start in the expected place.

Data flow: It receives path text. It immediately accepts the special /morpheus path. Otherwise, it requires the text to start with /, then requires the first segment to be root, rejects a trailing slash, and validates every later segment as an agent name. It returns either success or a clear error.

Call relations: from_string calls this before any plain string can become an AgentPath. It uses validate_agent_name so each child segment follows the same naming rules as joined paths.

Call graph: calls 1 internal fn (validate_agent_name); called by 1 (from_string).

fn validate_relative_reference(reference: &str) -> Result<(), String>

Purpose: Checks a relative path reference, such as worker/helper, before it is appended to a current path. It makes sure the reference cannot sneak in unsafe segments.

Data flow: It receives relative reference text. It rejects a trailing slash, then splits the reference into segments and validates each segment with validate_agent_name. It returns success or the first error it finds.

Call relations: resolve calls this when the reference does not start with /. This keeps relative navigation simple and safe: no empty trailing segment, no .., and no invalid agent names.

Call graph: calls 1 internal fn (validate_agent_name); called by 1 (resolve).

fn root_has_expected_name()

Purpose: Checks that the root path is created correctly and reports itself as root. This protects the special root behavior from accidental changes.

Data flow: The test creates AgentPath::root, reads its string form, asks for its name, and checks whether it is root. The expected results are /root, root, and true.

Call relations: It calls the public root-related methods the way normal code would. If any of those basics change unexpectedly, this test fails early.

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

fn morpheus_has_expected_name()

Purpose: Checks that the special Morpheus path has the right text and name, but is not treated as the root path.

Data flow: The test creates AgentPath::morpheus, reads its string form and final name, and checks that is_root is false. The expected text is /morpheus and the expected name is morpheus.

Call relations: It exercises the Morpheus constructor and the shared name/root logic. This confirms the special path fits into the type without becoming part of the root tree.

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

fn join_builds_child_paths()

Purpose: Checks that joining a valid child name onto root creates the expected child path. This verifies the basic tree-building behavior.

Data flow: The test starts with /root, joins researcher, then reads the resulting path and name. It expects /root/researcher and researcher.

Call relations: It calls root and then the public join method. This covers the common flow of creating a child agent path from a parent path.

Call graph: calls 1 internal fn (root); 1 external calls (assert_eq!).

fn resolve_supports_relative_and_absolute_references()

Purpose: Checks that resolve accepts both relative and absolute references and turns them into the right full paths.

Data flow: The test creates a current path /root/researcher. It resolves worker and expects /root/researcher/worker; it also resolves /root/other and expects /root/other.

Call relations: It uses try_from to create expected paths and compares them with resolve results. This confirms the two main branches inside resolve: relative append and absolute validation.

Call graph: calls 1 internal fn (try_from); 1 external calls (assert_eq!).

fn invalid_names_and_paths_are_rejected()

Purpose: Checks that bad names and bad paths produce the expected error messages. This is important because callers rely on these rejections to keep agent paths safe.

Data flow: The test tries to join an uppercase name, parse a path that does not start at /root or /morpheus, and resolve a reference containing ... Each attempt should return a specific error instead of an AgentPath.

Call relations: This test indirectly exercises validate_agent_name, validate_absolute_path, and validate_relative_reference through the public methods. It confirms the guardrails work from the outside, not just as private helpers.

Call graph: 1 external calls (assert_eq!).

fn new(namespace: Option<String>, name: impl Into<String>) -> Self

Purpose: Creates a ToolName when the caller already has a namespace that may or may not exist. This is useful when parsing or building tool calls from data where the namespace is optional.

Data flow: It receives an optional namespace and a name-like value. It turns the name into a String, keeps the namespace as given, and returns a new ToolName containing both pieces.

Call relations: Higher-level code such as from_parts and build_tool_call calls this when it has separated a tool name into its namespace part and its actual name. This function is the final small assembly step that packages those parts into the shared ToolName shape.

Call graph: called by 2 (from_parts, build_tool_call); 1 external calls (into).

fn plain(name: impl Into<String>) -> Self

Purpose: Creates a tool name with no namespace. Use this for built-in or simple tools where the name alone is enough.

Data flow: It receives a name-like value, turns it into a String, sets the namespace to None, and returns the finished ToolName.

Call relations: Many tests and tool-definition paths call this when they need a straightforward tool name. It is the common shortcut for code that does not need to think about namespaces.

Call graph: called by 73 (augment_tool_definition_appends_typed_declaration, augment_tool_definition_includes_property_descriptions_as_comments, code_mode_only_description_includes_nested_tools, blocking_tool, danger_full_access_tool_attempts_do_not_enforce_managed_network, guardian_allows_shell_command_additional_permissions_requests_past_policy_validation, guardian_allows_unified_exec_additional_permissions_requests_past_policy_validation, shell_command_allows_sticky_turn_permissions_without_inline_request_permissions_feature, strict_auto_review_turn_grant_forces_guardian_for_shell_command_policy_skip, rejects_escalated_permissions_when_policy_not_on_request (+15 more)); 1 external calls (into).

fn namespaced(namespace: impl Into<String>, name: impl Into<String>) -> Self

Purpose: Creates a tool name that belongs to a namespace. This is used when the same short tool name might exist in different tool collections, or when external tools need to stay clearly labeled.

Data flow: It receives a namespace and a name. It turns both into owned strings, wraps the namespace in Some, and returns a ToolName that keeps the two parts separate.

Call relations: Code that builds descriptions, canonical names, MCP-related tool names, and publication payloads calls this when it needs to preserve where a tool came from. This keeps namespaced tools distinct instead of flattening everything into one plain string too early.

Call graph: called by 32 (code_mode_only_description_groups_namespace_instructions_once, code_mode_only_description_omits_empty_namespace_sections, code_mode_only_description_renders_shared_mcp_types_once, canonical_tool_name, tool_name, image_generation_publication_is_finalized_by_core, mcp_post_tool_use_payload_uses_prefixed_tool_name_args_and_result, mcp_updated_input_rewrites_builtin_like_tool_names_as_mcp, tool_name, tool_name (+15 more)); 1 external calls (into).

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: Defines how a ToolName appears when it is printed or converted to display text. This matters for logs, user-facing descriptions, and serialized-looking output.

Data flow: It reads the ToolName. If there is a namespace, it writes the namespace followed directly by the tool name; if there is no namespace, it writes only the name. The output goes into Rust’s formatting system.

Call relations: This is called automatically whenever code formats a ToolName for display. It does not decide when names are shown; it only provides the shared rule for turning one into text.

Call graph: 2 external calls (write_str, write!).

fn cmp(&self, other: &Self) -> Ordering

Purpose: Defines the full ordering rule for sorting two tool names. This gives the system stable, repeatable ordering instead of relying on ad hoc comparisons.

Data flow: It reads both tool names, turns each into a comparison shape, and compares those shapes. Plain names compare by their name alone, while namespaced names compare first by namespace and then by the inner name. It returns whether this tool name comes before, after, or equal to the other one.

Call relations: Rust’s sorting and ordered collection machinery uses this method when it needs to order ToolName values. ToolName::partial_cmp also delegates directly to it so there is only one comparison rule.

Call graph: called by 1 (partial_cmp).

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Purpose: Provides the optional comparison hook Rust expects for values that can be ordered. For ToolName, every pair can always be compared, so this simply wraps the full comparison result.

Data flow: It receives another ToolName, calls ToolName::cmp to get the ordering, wraps that answer in Some, and returns it.

Call relations: This sits on top of ToolName::cmp. Code using general comparison features may call this, and it ensures those features follow the exact same ordering rule as normal sorting.

Call graph: calls 1 internal fn (cmp).

fn from(name: &str) -> Self

Purpose: Converts ordinary text into a plain, un-namespaced ToolName. This lets callers pass simple strings where a ToolName is expected without writing extra construction code.

Data flow: It receives text, passes it to ToolName::plain, and returns the resulting ToolName with no namespace.

Call relations: This is used by Rust’s standard conversion system. When other code asks to turn a string-like value into a ToolName, this function routes that conversion through the plain-name constructor so the behavior stays consistent.

Call graph: 1 external calls (plain).

fn new(text: String) -> Self

Purpose: Creates a new text stream result from a string. It starts with no truncation note, meaning the caller is saying this output has not been cut off.

Data flow: A text string goes in. The function wraps it in a StreamOutput object and sets truncated_after_lines to empty. The result is a ready-to-use stream record for stdout, stderr, or combined command output.

Call relations: Many parts of the command-running flow call this when they need to build output records, such as after executing a user shell command, mapping an execution result, or reporting the end of an execution. It is the simple constructor other code uses before adding the stream to a larger command result.

Call graph: called by 15 (make_exec_output, includes_timed_out_message, execute_user_shell_command, run, map_exec_result, emit_exec_end_for_unified_exec, emit_failed_exec_end_for_unified_exec, check_for_sandbox_denial_with_text, formats_basic_record, uses_aggregated_output_over_streams (+5 more)).

fn from_utf8_lossy(&self) -> StreamOutput<String>

Purpose: Turns a stream of raw bytes into a stream of readable text, while keeping the same truncation note. Despite the name, it uses the smarter encoding detection in this file rather than only doing basic UTF-8 replacement.

Data flow: A StreamOutput containing bytes goes in. The byte content is passed to bytes_to_string_smart, which tries to decode it correctly. The function returns a new StreamOutput containing a String, with truncated_after_lines copied unchanged.

Call relations: This is the bridge between byte-based process output and text-based command output. When callers have collected raw output, this function hands the bytes to bytes_to_string_smart and returns a stream that the rest of the system can display or store as text.

Call graph: calls 1 internal fn (bytes_to_string_smart).

fn default() -> Self

Purpose: Builds an empty, successful-looking command result. This is useful as a safe starting value before real command data is filled in.

Data flow: No input is needed. The function creates empty stdout, stderr, and combined-output streams, sets the exit code to 0, the duration to zero, and timed_out to false. The result is a complete ExecToolCallOutput with neutral default values.

Call relations: Code that needs an initial execution result can call this instead of filling every field by hand. It uses StreamOutput::new for the empty text streams, so the same stream structure is used consistently throughout command execution.

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

fn bytes_to_string_smart(bytes: &[u8]) -> String

Purpose: Converts arbitrary command-output bytes into a Rust String as accurately as possible. It solves the common problem where shell output is not valid UTF-8, especially on Windows.

Data flow: A slice of bytes goes in. If it is empty, the function returns an empty string. If it is already valid UTF-8, it returns that text directly. Otherwise it asks detect_encoding for the likely character encoding, then passes the bytes and encoding to decode_bytes. The output is readable text, or a best-effort replacement if perfect decoding is not possible.

Call relations: This is the main decoding function used when process output is collected, including through spawn_process_output, collect_spawn_process_output, and StreamOutput::from_utf8_lossy. It coordinates the lower-level steps: first deciding what encoding the bytes seem to use, then decoding them.

Call graph: calls 2 internal fn (decode_bytes, detect_encoding); called by 3 (spawn_process_output, collect_spawn_process_output, from_utf8_lossy); 2 external calls (new, from_utf8).

fn detect_encoding(bytes: &[u8]) -> &'static Encoding

Purpose: Guesses which character encoding was used for a byte stream. It also corrects one known bad guess where Windows smart punctuation can be mistaken for Cyrillic IBM866 text.

Data flow: Raw bytes go in. The function feeds them to an encoding detector, which returns a likely encoding. If the detector says IBM866, the function checks whether the bytes instead look like Windows-1252 punctuation around ordinary ASCII words. If so, it returns Windows-1252; otherwise it returns the detector’s guess.

Call relations: bytes_to_string_smart calls this after discovering the bytes are not valid UTF-8. detect_encoding may call looks_like_windows_1252_punctuation to guard against a specific real-world misread, then hands the chosen encoding back so decoding can continue.

Call graph: calls 1 internal fn (looks_like_windows_1252_punctuation); called by 1 (bytes_to_string_smart); 1 external calls (new).

fn decode_bytes(bytes: &[u8], encoding: &'static Encoding) -> String

Purpose: Decodes bytes using a chosen character encoding, while falling back safely if that decoding reports errors. This keeps bad or unexpected bytes from breaking the output display.

Data flow: Raw bytes and an encoding choice go in. The function asks the encoding library to decode the bytes. If the library reports decoding errors, the function falls back to a lossy UTF-8 conversion, which replaces unreadable parts rather than failing. The output is always a String.

Call relations: bytes_to_string_smart calls this after detect_encoding has chosen an encoding. It is the final step in turning raw command output into text that can be returned to users.

Call graph: called by 1 (bytes_to_string_smart); 2 external calls (decode, from_utf8_lossy).

fn looks_like_windows_1252_punctuation(bytes: &[u8]) -> bool

Purpose: Checks whether a byte stream looks like ordinary ASCII text decorated with Windows-1252 smart punctuation, such as curly quotes or long dashes. This prevents those punctuation marks from being displayed as unrelated Cyrillic letters.

Data flow: A byte slice goes in. The function scans each byte. If it sees bytes outside the narrow pattern it is looking for, it returns false. It requires at least one allowed Windows-1252 punctuation byte and at least one ASCII letter. If both are present and nothing disqualifies the stream, it returns true.

Call relations: detect_encoding calls this only when the detector guessed IBM866. This helper acts like a second opinion: if the bytes match the known smart-punctuation pattern, detect_encoding switches to Windows-1252 before decoding.

Call graph: calls 1 internal fn (is_windows_1252_punct); called by 1 (detect_encoding).

fn is_windows_1252_punct(byte: u8) -> bool

Purpose: Answers whether one byte is one of the known Windows-1252 smart punctuation bytes handled by this file. It is a small allowlist check used to avoid guessing too broadly.

Data flow: One byte goes in. The function checks whether it appears in the fixed list of Windows-1252 punctuation byte values. It returns true for those known punctuation bytes and false for everything else.

Call relations: looks_like_windows_1252_punctuation calls this while scanning a byte stream. By keeping the punctuation rule narrow, it helps the larger encoding-detection path fix the smart-quotes case without damaging legitimate Cyrillic output.

Call graph: called by 1 (looks_like_windows_1252_punctuation).

fn is_protected_metadata_name(name: &OsStr) -> bool

Purpose: Checks whether a filename is one of the workspace metadata names that Codex treats as sensitive: .git, .agents, or .codex.

Data flow: It receives a filename, compares it with the protected-name list, and returns true if it matches one of them.

Call relations: Other metadata-protection helpers use the same protected-name concept when deciding whether a write should be blocked.

fn is_protected_metadata_directory_name(name: &OsStr) -> bool

Purpose: Checks whether a directory name is one of the protected Codex-controlled metadata directories, .agents or .codex.

Data flow: It receives a filename-like value, compares it with those two directory names, and returns a yes-or-no answer.

Call relations: It is a small public helper for callers that need to treat Codex metadata directories specially without including .git pointer-file behavior.

Call graph: 1 external calls (new).

fn forbidden_agent_metadata_write(
    path: &Path,
    cwd: &Path,
    file_system_sandbox_policy: &FileSystemSandboxPolicy,
) -> Option<&'static str>

Purpose: Decides whether an agent write should be stopped because it targets protected workspace metadata under a writable root.

Data flow: It takes the target path, current working directory, and filesystem policy. It resolves the target, checks whether it falls under .git, .agents, or .codex inside a writable root, honors any explicit write exception, and returns the protected metadata name when the write should be blocked.

Call relations: This is the early warning gate before execution. It relies on path resolution, metadata-root detection, explicit-write checks, and the policy's write decision so callers can reject dangerous writes before they happen.

Call graph: calls 4 internal fn (can_write_path_with_cwd, has_explicit_write_entry_for_metadata_path, metadata_child_of_writable_root, resolve_candidate_path); 1 external calls (matches!).

fn is_enabled(self) -> bool

Purpose: Answers whether network access is allowed by this network policy.

Data flow: It receives the policy value and returns true only for the enabled variant.

Call relations: Sandbox setup and compatibility code call this when converting a high-level permission profile into concrete network behavior.

Call graph: called by 10 (spawn_debug_sandbox_child, should_install_network_seccomp, bwrap_network_mode, network_access_from_policy, from, to_legacy_sandbox_policy, compatibility_workspace_write_policy, should_require_platform_sandbox, dynamic_network_policy_for_network, should_apply_network_block); 1 external calls (matches!).

fn can_read(self) -> bool

Purpose: Answers whether this access mode allows reading.

Data flow: It receives an access mode and returns false only for deny; both read and write imply read permission.

Call relations: Policy resolution code uses this when collecting readable roots and deciding whether an entry grants enough access.

Call graph: called by 1 (access_covers); 1 external calls (matches!).

fn can_write(self) -> bool

Purpose: Answers whether this access mode allows writing.

Data flow: It receives an access mode and returns true only for write.

Call relations: Write checks, writable-root collection, and legacy conversion use this as the simple test for write authority.

Call graph: called by 1 (access_covers); 1 external calls (matches!).

fn project_roots(subpath: Option<PathBuf>) -> Self

Purpose: Builds the special path token that means the current project root, optionally with a subpath such as .git.

Data flow: It receives an optional subpath and returns a ProjectRoots special-path value containing it.

Call relations: Workspace-write policies use this to describe permissions relative to the active project without hard-coding one absolute directory.

fn unknown(path: impl Into<String>, subpath: Option<PathBuf>) -> Self

Purpose: Builds a placeholder for a future special path token that this runtime does not understand yet.

Data flow: It receives the unknown token text and an optional subpath, stores both, and returns an Unknown value.

Call relations: Deserialization and compatibility paths use this so newer config files can be loaded by older runtimes and then ignored safely instead of failing outright.

Call graph: 1 external calls (into).

fn from(value: FileSystemSandboxEntry<AbsolutePathBuf>) -> Self

Purpose: Converts a sandbox entry that uses absolute paths into one that uses URI-style paths for transport or serialization.

Data flow: It receives an entry, converts only the path representation, keeps the same access mode, and returns the converted entry.

Call relations: This supports moving permission data across protocol boundaries where file paths may be represented as URIs.

fn try_from(value: FileSystemSandboxEntry<PathUri>) -> Result<Self, Self::Error>

Purpose: Converts a URI-style sandbox entry back into one with absolute filesystem paths.

Data flow: It receives a URI-based entry, tries to turn the path into an absolute path, keeps the access mode, and returns either the converted entry or an I/O error.

Call relations: Protocol receivers use this when turning serialized permission data back into local filesystem rules.

fn new(file_system_sandbox_policy: &FileSystemSandboxPolicy, cwd: &Path) -> Option<Self>

Purpose: Builds a runtime checker for read-deny rules, choosing safety over permissiveness if a glob pattern is malformed.

Data flow: It receives a filesystem policy and current directory, builds internal exact-path and glob matchers when deny rules exist, and returns None if there is nothing to check.

Call relations: Test helpers and runtime read checks call this when they want malformed deny patterns to fail closed, meaning reads are denied rather than accidentally allowed.

Call graph: called by 1 (is_read_denied); 2 external calls (build, unreachable!).

fn try_new(
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        cwd: &Path,
    ) -> Result<Option<Self>, String>

Purpose: Builds a read-deny matcher but reports malformed glob patterns as errors.

Data flow: It receives a policy and current directory, attempts to compile deny patterns, and returns either an optional matcher or a readable error string.

Call relations: Host-side expansion code uses this before execution so a bad pattern can stop setup instead of silently changing what paths may be touched.

Call graph: called by 1 (resolve_windows_deny_read_paths); 1 external calls (build).

fn build(
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        cwd: &Path,
        invalid_glob_behavior: InvalidDenyReadGlobBehavior,
    ) -> Result<Option<Self>, String>

Purpose: Does the shared work of constructing the read-deny matcher.

Data flow: It reads deny roots and deny glob patterns from the policy, resolves them against the current directory, builds exact candidates and glob matchers, records malformed patterns according to the requested behavior, and returns the matcher or an error.

Call relations: Both public constructors call this. It gathers policy information through get_unreadable_roots_with_cwd and get_unreadable_globs_with_cwd, then delegates pattern compilation to build_glob_matcher.

Call graph: calls 4 internal fn (get_unreadable_globs_with_cwd, get_unreadable_roots_with_cwd, has_denied_read_restrictions, build_glob_matcher); 2 external calls (new, format!).

fn is_read_denied(&self, path: &Path) -> bool

Purpose: Checks whether a particular path is blocked by read-deny rules.

Data flow: It receives a path, builds both normalized and canonical candidate spellings, compares them with denied roots, then tests glob matchers. It returns true if any rule blocks the path, or if the matcher was built from an invalid pattern in fail-closed mode.

Call relations: Runtime collection code calls this when deciding whether a file read should be allowed. It uses canonical candidates so symlink aliases cannot trivially bypass a deny rule.

Call graph: calls 1 internal fn (normalized_and_canonical_candidates); called by 1 (collect_existing_glob_matches).

fn from(value: FileSystemPath<AbsolutePathBuf>) -> Self

Purpose: Converts a filesystem path description from absolute-path form into URI form.

Data flow: It receives a path enum, converts concrete paths to URIs, leaves glob patterns and special tokens unchanged, and returns the converted enum.

Call relations: This supports serialization of permission paths for protocol messages.

Call graph: calls 1 internal fn (from_abs_path).

fn try_from(value: FileSystemPath<PathUri>) -> Result<Self, Self::Error>

Purpose: Converts a URI-based filesystem path description back into absolute-path form.

Data flow: It receives a path enum, converts URI paths into absolute paths when possible, leaves glob patterns and special tokens unchanged, and returns either the converted enum or an I/O error.

Call relations: This is the reverse of FileSystemPath::from and is used when received protocol data must become local permission rules.

fn project_roots_glob_pattern(subpath: &Path) -> String

Purpose: Marks a glob pattern as being relative to project roots rather than to one concrete directory.

Data flow: It receives a subpath pattern, prefixes it with a special codex-project-roots:// marker, and returns the marked pattern string.

Call relations: Pattern-compilation code calls this when it needs project-root-relative deny patterns that can later be expanded for each workspace root.

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

fn read_only_file_system_entries() -> Vec<FileSystemSandboxEntry>

Purpose: Creates the basic entry list for a read-only filesystem policy.

Data flow: It produces one entry: the filesystem root is readable.

Call relations: FileSystemSandboxPolicy::read_only calls this to build the default restricted read-only policy.

Call graph: called by 1 (read_only); 1 external calls (vec!).

fn default() -> Self

Purpose: Makes the default filesystem policy read-only.

Data flow: It takes no inputs and returns the same policy as read_only.

Call relations: Many setup and test paths rely on this conservative default so missing configuration does not imply write access.

Call graph: called by 8 (file_system_sandbox_context_uses_active_attempt, default_exec_approval_requirement_keeps_prompt_when_granular_allows_sandbox_approval, default_exec_approval_requirement_rejects_sandbox_prompt_when_granular_disables_it, extension_tool_receives_turn_environment_sandbox, view_image_tool_applies_local_sandbox_read_denies, default_policy_with_unreadable_glob, default_policy_with_unreadable_glob, unreadable_glob_policy_includes_canonicalized_static_prefix); 1 external calls (read_only).

fn read_only() -> Self

Purpose: Builds a restricted policy that allows reading the disk but not writing it.

Data flow: It creates read-only root entries and wraps them in a restricted sandbox policy.

Call relations: Configuration defaults and parent permission profiles use this when the agent should inspect files but not modify them.

Call graph: calls 1 internal fn (read_only_file_system_entries); called by 2 (extensible_builtin_parent_profile, read_only); 1 external calls (restricted).

fn unrestricted() -> Self

Purpose: Builds a policy that grants full filesystem access.

Data flow: It returns a policy marked unrestricted with no per-path entries.

Call relations: Full-access profiles and compatibility conversion use this when the sandbox should not limit filesystem reads or writes.

Call graph: called by 15 (managed_full_disk_with_restricted_network_reports_external_sandbox, windows_restricted_token_rejects_network_only_restrictions, exec_server_params_use_path_uri_and_env_policy_overlay_contract, full_disk_write_full_network_returns_unwrapped_command, full_disk_write_proxy_only_keeps_full_filesystem_but_unshares_network, managed_proxy_preflight_argv_is_wrapped_for_full_access_policy, to_sandbox_policy, file_system_sandbox_policy, disabled_permission_profile_ignores_runtime_network_policy, permission_profile_from_runtime_permissions_preserves_unrestricted_managed_network (+5 more)); 1 external calls (new).

fn external_sandbox() -> Self

Purpose: Builds a policy that says filesystem control is handled by something outside this policy object.

Data flow: It returns an external-sandbox kind with no local filesystem entries.

Call relations: Runtime setup and legacy conversion use this when another sandbox mechanism is expected to enforce access.

Call graph: called by 4 (external_sandbox_auto_approves_in_on_request, file_system_sandbox_policy, permission_profile_from_runtime_permissions_preserves_external_sandbox, from); 1 external calls (new).

fn restricted(entries: Vec<FileSystemSandboxEntry>) -> Self

Purpose: Builds a restricted filesystem policy from explicit path rules.

Data flow: It receives entries, stores them with restricted kind, and leaves optional glob scan depth unset.

Call relations: Most policy constructors and tests use this as the common way to create a detailed allow-and-deny rule set.

Call graph: called by 138 (requested_permissions_trust_project_uses_permission_profile_intent, permission_profile_override_keeps_memories_root_out_of_legacy_projection, permission_profile_override_preserves_split_write_roots, compile_permission_profile, workspace_write_permission_profile_with_private_denials, managed_cwd_write_profile_has_filesystem_restrictions, managed_full_disk_write_profile_has_no_filesystem_restrictions, managed_unresolvable_write_profile_has_filesystem_restrictions, writable_windows_policy_without_sandbox_backend_still_requires_approval, windows_elevated_allows_split_restricted_read_policies (+15 more)).

fn has_root_access(&self, predicate: impl Fn(FileSystemAccessMode) -> bool) -> bool

Purpose: Checks whether a restricted policy grants a chosen kind of access at the filesystem root.

Data flow: It receives a test function, scans root special-path entries, and returns true if any root entry passes that test.

Call relations: Full-disk read and write checks call this as their first question: does the policy start with broad root access?

Call graph: called by 2 (has_full_disk_read_access, has_full_disk_write_access); 1 external calls (matches!).

fn has_denied_read_restrictions(&self) -> bool

Purpose: Checks whether a restricted policy contains any explicit deny entries.

Data flow: It scans entries only when the policy is restricted and returns true if any entry has deny access.

Call relations: Read-deny matcher construction and full-read detection use this to know whether extra blocking rules exist.

Call graph: called by 3 (unsandboxed_execution_allowed, has_full_disk_read_access, build); 1 external calls (matches!).

fn from_legacy_sandbox_policy_preserving_deny_entries(
        sandbox_policy: &SandboxPolicy,
        cwd: &Path,
        existing: &Self,
    ) -> Self

Purpose: Rebuilds a filesystem policy from an older sandbox policy while keeping existing deny rules.

Data flow: It converts the legacy policy for the current directory, copies over glob scan depth, then appends deny entries from the existing policy that are not already present.

Call relations: Configuration application uses this when the allow side is refreshed from legacy settings but read-deny restrictions must survive.

Call graph: called by 2 (apply, legacy_bridge_preserves_explicit_deny_entries); 2 external calls (from_legacy_sandbox_policy_for_cwd, matches!).

fn preserve_deny_read_restrictions_from(&mut self, existing: &Self)

Purpose: Copies read-deny restrictions from an old policy into this policy.

Data flow: It looks for deny entries in the existing policy. If the new policy is unrestricted, it turns it into a restricted full-write policy so denies can still be enforced, then copies depth and missing deny entries.

Call relations: This is used when replacing permissions would otherwise accidentally drop explicit private-read blocks.

Call graph: 3 external calls (restricted, matches!, vec!).

fn has_write_narrowing_entries(&self) -> bool

Purpose: Detects whether any rule limits an otherwise broad write permission.

Data flow: It scans restricted entries and returns true for read or deny rules that actually carve away write access, ignoring rules that are shadowed by an equal-target write rule.

Call relations: has_full_disk_write_access calls this to avoid saying the disk is fully writable when a child path or pattern is read-only or denied.

Call graph: called by 1 (has_full_disk_write_access); 1 external calls (matches!).

fn has_same_target_write_override(&self, entry: &FileSystemSandboxEntry) -> bool

Purpose: Checks whether a write rule for the exact same target overrides a narrower-looking rule.

Data flow: It receives an entry, searches for a higher-precedence write entry that points at the same path target, and returns true if one exists.

Call relations: has_write_narrowing_entries uses this to avoid treating a shadowed read or deny rule as a real reduction in write access.

fn workspace_write(
        writable_roots: &[AbsolutePathBuf],
        exclude_tmpdir_env_var: bool,
        exclude_slash_tmp: bool,
    ) -> Self

Purpose: Builds the standard policy for workspace editing: read broadly, write project roots and selected temporary locations, and protect metadata.

Data flow: It receives extra writable roots and temporary-directory exclusions, creates root read access, adds project-root and temp write entries, adds requested write roots, then adds read-only carveouts for .git, .agents, and .codex unless explicitly overridden.

Call relations: Legacy conversion and workspace-write permission profiles call this to produce the detailed filesystem rules behind the familiar workspace-write mode.

Call graph: calls 4 internal fn (restricted, append_default_read_only_path_if_no_explicit_rule, append_default_read_only_project_root_subpath_if_no_explicit_rule, default_read_only_subpaths_for_writable_root); called by 8 (extensible_builtin_parent_profile, test_writable_roots_constraint, write_permissions_for_paths_keep_dirs_outside_workspace_root, write_permissions_for_paths_skip_dirs_already_writable_under_workspace_root, ignores_missing_writable_roots, mounts_dev_before_writable_dev_binds, workspace_write_with, from); 3 external calls (project_roots, iter, vec!).

fn from_legacy_sandbox_policy_for_cwd(sandbox_policy: &SandboxPolicy, cwd: &Path) -> Self

Purpose: Converts an older sandbox policy into the newer filesystem policy for a specific current directory.

Data flow: It first performs the basic conversion, then for workspace-write policies adds default protected metadata paths for the current workspace and any extra writable roots.

Call relations: Session setup, agent spawning, and compatibility paths call this when old configuration must be represented with the newer per-path policy model.

Call graph: calls 3 internal fn (append_default_read_only_path_if_no_explicit_rule, default_read_only_subpaths_for_writable_root, from_absolute_path); called by 19 (exec_one_off_command_inner, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, file_system_policy_with_unreadable_glob, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries, session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update, non_legacy_file_system_sandbox_policy, build_agent_spawn_config_uses_turn_context_values, spawn_agent_reapplies_runtime_sandbox_after_role_config, network_approval_retry_keeps_deny_read_sandbox_for_escalated_command (+9 more)); 1 external calls (from).

fn has_full_disk_read_access(&self) -> bool

Purpose: Answers whether filesystem reads are effectively unrestricted.

Data flow: It returns true for unrestricted or external sandbox policies. For restricted policies, it requires readable root access and no deny-read restrictions.

Call relations: Sandbox argument builders and readable-root collectors call this to decide whether they need to pass any read allowlist at all.

Call graph: calls 2 internal fn (has_denied_read_restrictions, has_root_access); called by 7 (add_helper_runtime_permissions, create_filesystem_args, get_readable_roots_with_cwd, include_platform_defaults, semantic_signature, with_additional_readable_roots, has_full_disk_read_access).

fn has_full_disk_write_access(&self) -> bool

Purpose: Answers whether filesystem writes are effectively unrestricted.

Data flow: It returns true for unrestricted or external sandbox policies. For restricted policies, it requires write access at root and no rules that narrow that write access.

Call relations: Execution setup, prompts, legacy conversion, and write checks call this to detect full-write mode.

Call graph: calls 2 internal fn (has_root_access, has_write_narrowing_entries); called by 10 (patch_rejection_reason, create_bwrap_command_args, create_filesystem_args, sandbox_prompt_from_policy, can_write_path_with_cwd, get_writable_roots_with_cwd, semantic_signature, to_legacy_sandbox_policy, ensure_linux_bubblewrap_is_supported, should_require_platform_sandbox).

fn include_platform_defaults(&self) -> bool

Purpose: Decides whether platform-default readable paths should be added to a restricted policy.

Data flow: It returns true only when full read access is absent, the policy is restricted, and it contains a readable Minimal special-path entry.

Call relations: Filesystem sandbox builders and semantic comparison use this to preserve the meaning of minimal access profiles.

Call graph: calls 1 internal fn (has_full_disk_read_access); called by 3 (create_filesystem_args, semantic_signature, include_platform_defaults); 1 external calls (matches!).

fn resolve_access_with_cwd(&self, path: &Path, cwd: &Path) -> FileSystemAccessMode

Purpose: Finds the effective access mode for one path under this policy.

Data flow: It resolves the candidate path against the current directory, finds all resolved entries that contain it, chooses the most specific rule with tie-breaking by access precedence, and returns read, write, or deny.

Call relations: Read and write convenience checks call this. It is the central path-decision function for detailed filesystem policies.

Call graph: calls 2 internal fn (resolved_entries_with_cwd, resolve_candidate_path); called by 3 (can_read_path_with_cwd, can_write_path_with_cwd, granted_file_system_entry_within_request).

fn can_read_path_with_cwd(&self, path: &Path, cwd: &Path) -> bool

Purpose: Answers whether a path may be read under this policy.

Data flow: It receives a path and current directory, resolves the path's access mode, and returns whether that mode permits reading.

Call relations: Permission-expansion and Windows sandbox helpers use this when adding readable roots or checking effective read access.

Call graph: calls 1 internal fn (resolve_access_with_cwd); called by 3 (windows_policy_has_root_read_access, add_helper_runtime_permissions, with_additional_readable_roots).

fn can_write_path_with_cwd(&self, path: &Path, cwd: &Path) -> bool

Purpose: Answers whether a path may be written under this policy, including protected metadata checks.

Data flow: It resolves the path's access mode. If it is not write, it returns false. If full-disk write is active, it returns true. Otherwise, it denies writes to protected metadata unless explicitly allowed.

Call relations: Write-root expansion, compatibility policy building, and forbidden_agent_metadata_write rely on this final write decision.

Call graph: calls 3 internal fn (has_full_disk_write_access, is_metadata_write_denied, resolve_access_with_cwd); called by 4 (with_additional_writable_roots, forbidden_agent_metadata_write, compatibility_workspace_write_policy, protected_metadata_names_for_writable_root).

fn is_metadata_write_denied(&self, path: &Path, cwd: &Path) -> bool

Purpose: Checks whether a write is blocked specifically because it targets protected metadata inside a writable root.

Data flow: It resolves the target, detects whether it is under .git, .agents, or .codex below a writable root, and returns true unless an explicit write entry covers that metadata path.

Call relations: can_write_path_with_cwd calls this after normal write permission succeeds, adding the extra metadata safety layer.

Call graph: calls 3 internal fn (has_explicit_write_entry_for_metadata_path, metadata_child_of_writable_root, resolve_candidate_path); called by 1 (can_write_path_with_cwd); 1 external calls (matches!).

fn materialize_project_roots_with_cwd(mut self, cwd: &Path) -> Self

Purpose: Turns project-root-relative entries into concrete paths based on the current directory.

Data flow: It walks entries, replaces ProjectRoots special paths with absolute paths from cwd, and rewrites project-root-marked glob patterns into absolute glob patterns.

Call relations: Callers use this when a permission profile must keep the same project-root meaning even if the process later changes directories.

Call graph: calls 4 internal fn (parse_project_roots_glob_pattern, resolve_file_system_path, resolve_project_roots_glob_pattern, from_absolute_path); 1 external calls (as_ref).

fn materialize_project_roots_with_workspace_roots(
        mut self,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Self

Purpose: Expands project-root-relative entries into one concrete entry for each known workspace root.

Data flow: It receives workspace roots, replaces project-root special entries and marked glob patterns with per-root concrete entries, and preserves entries that are already concrete or unrelated.

Call relations: Workspace-aware setup uses this when more than one project root should receive the same symbolic permission rule.

Call graph: calls 1 internal fn (parse_project_roots_glob_pattern); 2 external calls (with_capacity, iter).

fn with_materialized_project_roots_for_workspace_roots(
        mut self,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Self

Purpose: Adds concrete workspace-root entries while keeping the original symbolic entries too.

Data flow: It clones and materializes the policy for the provided roots, then appends any generated entries that are not already present.

Call relations: This is useful when a policy should work both with symbolic project-root interpretation and with runtimes that need concrete paths.

fn with_additional_readable_roots(
        mut self,
        cwd: &Path,
        additional_readable_roots: &[AbsolutePathBuf],
    ) -> Self

Purpose: Adds extra readable roots when they are not already readable.

Data flow: It receives current directory and extra roots, skips work if full read access exists, checks each root's current read access, and appends read entries only for missing access.

Call relations: Permission setup uses this to extend read access without duplicating rules already covered by broader entries.

Call graph: calls 2 internal fn (can_read_path_with_cwd, has_full_disk_read_access).

fn with_additional_writable_roots(
        mut self,
        cwd: &Path,
        additional_writable_roots: &[AbsolutePathBuf],
    ) -> Self

Purpose: Adds extra writable roots when they are not already writable.

Data flow: It receives extra roots, checks each one with the current policy, and appends write entries only for paths that are not already writable.

Call relations: Runtime setup uses this to grant additional write locations while respecting existing effective access.

Call graph: calls 1 internal fn (can_write_path_with_cwd).

fn with_additional_legacy_workspace_writable_roots(
        mut self,
        additional_writable_roots: &[AbsolutePathBuf],
    ) -> Self

Purpose: Adds writable roots using legacy workspace-write rules, including metadata protection.

Data flow: It receives extra roots, adds exact write entries if missing, then adds default read-only protected metadata subpaths for each new root.

Call relations: Legacy compatibility code uses this when it needs the old behavior, where explicit roots and their metadata carveouts are added even if symbolic project roots already cover them.

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

fn needs_direct_runtime_enforcement(
        &self,
        network_policy: NetworkSandboxPolicy,
        cwd: &Path,
    ) -> bool

Purpose: Decides whether the newer filesystem policy cannot safely be represented by the older sandbox runtime.

Data flow: It tries to convert to the legacy policy, compares semantic signatures with what the legacy runtime would actually enforce, and separately checks protected metadata names.

Call relations: Platform sandbox setup calls this to know whether it must enforce FileSystemSandboxPolicy directly instead of relying only on the older SandboxPolicy bridge.

Call graph: calls 4 internal fn (semantic_signature, to_legacy_sandbox_policy, legacy_runtime_file_system_policy_for_cwd, protected_metadata_names_need_direct_runtime_enforcement); called by 1 (ensure_legacy_landlock_mode_supports_policy); 1 external calls (matches!).

fn is_semantically_equivalent_to(&self, other: &Self, cwd: &Path) -> bool

Purpose: Checks whether two policies mean the same thing for a current directory, ignoring entry order.

Data flow: It computes a semantic signature for both policies and compares those signatures.

Call relations: Tests and enforcement classification use this to avoid treating harmless reordering as a real permission difference.

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

fn get_readable_roots_with_cwd(&self, cwd: &Path) -> Vec<AbsolutePathBuf>

Purpose: Lists the explicit readable roots for this policy after resolving special paths.

Data flow: It returns an empty list for full-read policies. Otherwise it resolves entries, keeps entries that effectively allow reading, deduplicates paths, and returns them.

Call relations: Sandbox argument builders and semantic comparison call this when they need concrete readable roots.

Call graph: calls 3 internal fn (has_full_disk_read_access, resolved_entries_with_cwd, dedup_absolute_paths); called by 3 (create_filesystem_args, semantic_signature, readable_roots_for_cwd); 1 external calls (new).

fn get_writable_roots_with_cwd(&self, cwd: &Path) -> Vec<WritableRoot>

Purpose: Lists writable roots and the read-only subpaths carved out inside them.

Data flow: It returns an empty list for full-write policies. Otherwise it resolves writable entries, deduplicates effective roots, computes protected metadata names and read-only carveouts, preserves important symlink spellings, and returns WritableRoot records.

Call relations: Sandbox builders, prompts, compatibility checks, and metadata-enforcement comparison use this to turn high-level rules into mountable writable areas.

Call graph: calls 3 internal fn (has_full_disk_write_access, resolved_entries_with_cwd, dedup_absolute_paths); called by 6 (patch_rejection_reason, create_filesystem_args, sandbox_prompt_from_policy, semantic_signature, protected_metadata_names_need_direct_runtime_enforcement, compatibility_workspace_write_policy); 1 external calls (new).

fn get_unreadable_roots_with_cwd(&self, cwd: &Path) -> Vec<AbsolutePathBuf>

Purpose: Lists explicit path roots that should be unreadable.

Data flow: It resolves deny entries, keeps only those that are effectively unreadable, avoids materializing a whole-root deny that would erase narrower read allows, deduplicates paths, and returns them.

Call relations: Sandbox builders, read-deny text display, semantic comparison, and ReadDenyMatcher::build use this to enforce exact deny roots.

Call graph: calls 3 internal fn (resolved_entries_with_cwd, dedup_absolute_paths, from_absolute_path); called by 5 (create_filesystem_args, denied_reads_text, semantic_signature, build, resolve_windows_deny_read_paths); 2 external calls (new, matches!).

fn get_unreadable_globs_with_cwd(&self, cwd: &Path) -> Vec<String>

Purpose: Lists unreadable glob patterns resolved against the current directory.

Data flow: It scans restricted deny entries that are glob patterns, makes relative patterns absolute against cwd, sorts and deduplicates them, and returns strings.

Call relations: Sandbox builders and read-deny matcher construction call this to enforce pattern-based read blocks.

Call graph: called by 7 (create_bwrap_command_args, create_filesystem_args, denied_reads_text, semantic_signature, build, build_seatbelt_unreadable_glob_policy, resolve_windows_deny_read_paths); 2 external calls (new, matches!).

fn to_legacy_sandbox_policy(
        &self,
        network_policy: NetworkSandboxPolicy,
        cwd: &Path,
    ) -> io::Result<SandboxPolicy>

Purpose: Converts the detailed filesystem policy plus network policy into the older SandboxPolicy format when possible.

Data flow: It examines policy kind, network setting, full-write status, workspace-root writes, temporary-directory writes, and extra writable roots. It returns a matching legacy policy or an error when the detailed policy asks for writes the legacy model cannot express safely.

Call relations: needs_direct_runtime_enforcement uses this as the bridge test: if conversion fails or loses meaning, direct enforcement is required.

Call graph: calls 5 internal fn (has_full_disk_write_access, is_enabled, dedup_absolute_paths, resolve_file_system_special_path, from_absolute_path); called by 1 (needs_direct_runtime_enforcement); 2 external calls (new, new).

fn resolved_entries_with_cwd(&self, cwd: &Path) -> Vec<ResolvedFileSystemEntry>

Purpose: Resolves policy entries into concrete absolute path entries for a current directory.

Data flow: It converts cwd to an absolute path when possible, resolves each entry's path if it can be concrete, and returns resolved path-plus-access records.

Call relations: Most path-based operations call this before comparing policy entries to actual filesystem paths.

Call graph: calls 1 internal fn (from_absolute_path); called by 6 (get_readable_roots_with_cwd, get_unreadable_roots_with_cwd, get_writable_roots_with_cwd, resolve_access_with_cwd, has_explicit_write_entry_for_metadata_path, metadata_child_of_writable_root).

fn semantic_signature(&self, cwd: &Path) -> FileSystemSemanticSignature

Purpose: Builds a normalized summary of what a policy means for a current directory.

Data flow: It records broad read/write flags, platform-default behavior, sorted readable roots, writable roots, unreadable roots, and unreadable globs.

Call relations: Policy equivalence and direct-enforcement checks use this so they compare behavior rather than raw entry order.

Call graph: calls 9 internal fn (get_readable_roots_with_cwd, get_unreadable_globs_with_cwd, get_unreadable_roots_with_cwd, get_writable_roots_with_cwd, has_full_disk_read_access, has_full_disk_write_access, include_platform_defaults, sorted_absolute_paths, sorted_writable_roots); called by 2 (is_semantically_equivalent_to, needs_direct_runtime_enforcement).

fn from(value: &SandboxPolicy) -> Self

Purpose: Creates the new network policy from an older sandbox policy.

Data flow: It asks the legacy policy whether it has full network access and returns enabled or restricted accordingly.

Call relations: Session and agent setup call this when translating legacy configuration into the split network/filesystem permission model.

Call graph: called by 14 (exec_one_off_command_inner, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, apply, session_configuration_apply_preserves_profile_file_system_policy_on_cwd_only_update, session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update, build_agent_spawn_config_uses_turn_context_values, spawn_agent_reapplies_runtime_sandbox_after_role_config, from_legacy_sandbox_policy, from_legacy_sandbox_policy (+4 more)); 1 external calls (has_full_network_access).

fn from(value: &SandboxPolicy) -> Self

Purpose: Creates the new filesystem policy from an older sandbox policy.

Data flow: It maps full access to unrestricted, external sandbox to external, read-only to root read, and workspace-write to the detailed workspace-write policy.

Call relations: Legacy conversion paths and runtime-policy reconstruction use this as the basic bridge into the newer permission model.

Call graph: calls 4 internal fn (external_sandbox, restricted, unrestricted, workspace_write); called by 2 (from_legacy_sandbox_policy, legacy_runtime_file_system_policy_for_cwd); 1 external calls (vec!).

fn resolve_file_system_path(
    path: &FileSystemPath,
    cwd: Option<&AbsolutePathBuf>,
) -> Option<AbsolutePathBuf>

Purpose: Turns a filesystem path description into an absolute path when that is possible.

Data flow: It returns concrete path entries directly, ignores glob patterns, and resolves special paths such as project roots or temp directories using the optional current directory.

Call relations: Project-root materialization and entry resolution call this as the common special-path resolver.

Call graph: calls 1 internal fn (resolve_file_system_special_path); called by 2 (materialize_project_roots_with_cwd, resolve_entry_path); 1 external calls (clone).

fn resolve_entry_path(
    path: &FileSystemPath,
    cwd: Option<&AbsolutePathBuf>,
) -> Option<AbsolutePathBuf>

Purpose: Resolves a policy entry path into the concrete path used for prefix matching.

Data flow: It treats the special root token as the filesystem root for the current directory, otherwise delegates to resolve_file_system_path.

Call relations: resolved_entries_with_cwd uses this to prepare entries for access decisions.

Call graph: calls 1 internal fn (resolve_file_system_path).

fn parse_project_roots_glob_pattern(pattern: &str) -> Option<&Path>

Purpose: Recognizes glob patterns that were marked as project-root-relative.

Data flow: It receives a pattern string, strips the special prefix if present, and returns the remaining subpath as a path.

Call relations: Materialization functions use this to expand symbolic glob patterns for a current directory or a list of workspace roots.

Call graph: called by 2 (materialize_project_roots_with_cwd, materialize_project_roots_with_workspace_roots).

fn resolve_project_roots_glob_pattern(subpath: &Path, root: &AbsolutePathBuf) -> String

Purpose: Turns a project-root-relative glob subpath into an absolute glob pattern for one root.

Data flow: It receives a subpath and root, resolves the subpath against the root, and returns the path as a string.

Call relations: Project-root materialization calls this after detecting the special glob prefix.

Call graph: calls 2 internal fn (as_path, resolve_path_against_base); called by 1 (materialize_project_roots_with_cwd).

fn resolve_candidate_path(path: &Path, cwd: &Path) -> Option<AbsolutePathBuf>

Purpose: Converts a path being checked into an absolute path candidate.

Data flow: It returns the path directly if it is absolute, or joins it to an absolute current directory if it is relative. It returns None if the current directory cannot be made absolute.

Call relations: Access resolution and protected-metadata checks use this before comparing a user-supplied path with policy entries.

Call graph: calls 1 internal fn (from_absolute_path); called by 3 (is_metadata_write_denied, resolve_access_with_cwd, forbidden_agent_metadata_write); 1 external calls (is_absolute).

fn file_system_paths_share_target(left: &FileSystemPath, right: &FileSystemPath) -> bool

Purpose: Checks whether two policy path descriptions refer to the same exact target for same-specificity conflict handling.

Data flow: It compares concrete paths, special paths, stable special-path-to-absolute matches, and identical glob patterns, returning false for unlike or unresolved targets.

Call relations: Write-narrowing and default read-only append helpers use this to decide whether an explicit rule already covers a target.

Call graph: calls 2 internal fn (special_path_matches_absolute_path, special_paths_share_target).

fn special_paths_share_target(left: &FileSystemSpecialPath, right: &FileSystemSpecialPath) -> bool

Purpose: Compares two special path tokens that can be judged without a current directory.

Data flow: It receives two special paths and returns true when they are the same stable token or the same project-root/unknown token with the same subpath data.

Call relations: file_system_paths_share_target uses this for special-path entries.

Call graph: called by 1 (file_system_paths_share_target).

fn special_path_matches_absolute_path(
    value: &FileSystemSpecialPath,
    path: &AbsolutePathBuf,
) -> bool

Purpose: Checks whether a stable special path token names the same location as an absolute path.

Data flow: It recognizes only cwd-independent meanings, such as filesystem root and /tmp, and returns whether the absolute path matches.

Call relations: file_system_paths_share_target uses this when comparing a special path with a concrete path.

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

fn resolved_entry_precedence(entry: &ResolvedFileSystemEntry) -> (usize, FileSystemAccessMode)

Purpose: Ranks resolved entries so access resolution can choose the winning rule.

Data flow: It receives a resolved entry and returns a pair: path specificity measured by component count, then access-mode precedence.

Call relations: resolve_access_with_cwd uses this ranking so more specific paths win, and ties prefer deny over write over read according to the enum ordering.

fn absolute_root_path_for_cwd(cwd: &AbsolutePathBuf) -> AbsolutePathBuf

Purpose: Finds the filesystem root that contains the current directory.

Data flow: It walks the current directory's ancestors to the last ancestor, converts it to an absolute path, and returns it.

Call relations: Root special-path resolution and unreadable-root filtering use this when they need the real root path for the current platform.

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

fn normalized_and_canonical_candidates(path: &Path) -> Vec<PathBuf>

Purpose: Builds the path spellings used to compare read-deny rules safely.

Data flow: It starts with the lexical absolute form when possible, then adds the canonical filesystem target if it exists, avoiding duplicates.

Call relations: ReadDenyMatcher::is_read_denied uses these candidates so both symlink paths and their real targets can match deny rules.

Call graph: calls 2 internal fn (push_unique, from_absolute_path); called by 1 (is_read_denied); 3 external calls (canonicalize, to_path_buf, new).

fn push_unique(candidates: &mut Vec<PathBuf>, candidate: PathBuf)

Purpose: Adds a path to a list only if it is not already present.

Data flow: It receives a mutable vector and a candidate path, checks for equality with existing items, and appends only new values.

Call relations: normalized_and_canonical_candidates uses this to keep candidate lists small and duplicate-free.

Call graph: called by 1 (normalized_and_canonical_candidates).

fn build_glob_matcher(pattern: &str) -> Result<GlobMatcher, String>

Purpose: Compiles a glob pattern into a matcher with Codex's expected path-pattern behavior.

Data flow: It receives a pattern string, configures glob parsing so * and ? do not cross path separators and unclosed [ is literal, then returns a matcher or an error message.

Call relations: ReadDenyMatcher::build calls this for each deny-read glob pattern.

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

fn resolve_file_system_special_path(
    value: &FileSystemSpecialPath,
    cwd: Option<&AbsolutePathBuf>,
) -> Option<AbsolutePathBuf>

Purpose: Resolves special path tokens such as project roots, TMPDIR, and /tmp into concrete absolute paths when possible.

Data flow: It receives a special path and optional current directory. Some tokens cannot resolve directly, project roots use cwd, temp dir uses the TMPDIR environment variable, and slash-tmp returns /tmp only if it exists.

Call relations: Path resolution and legacy conversion call this whenever symbolic policy entries need concrete paths.

Call graph: calls 2 internal fn (from_absolute_path, resolve_path_against_base); called by 2 (to_legacy_sandbox_policy, resolve_file_system_path); 2 external calls (from, var_os).

fn dedup_absolute_paths(
    paths: Vec<AbsolutePathBuf>,
    normalize_effective_paths: bool,
) -> Vec<AbsolutePathBuf>

Purpose: Removes duplicate absolute paths, optionally after normalizing their effective filesystem spelling.

Data flow: It receives paths and a flag, normalizes each path when requested, tracks seen path buffers, and returns the first unique version of each.

Call relations: Readable-root, writable-root, unreadable-root, legacy conversion, and default-metadata helpers use this to avoid duplicate sandbox entries.

Call graph: calls 1 internal fn (normalize_effective_absolute_path); called by 5 (get_readable_roots_with_cwd, get_unreadable_roots_with_cwd, get_writable_roots_with_cwd, to_legacy_sandbox_policy, default_read_only_subpaths_for_writable_root); 2 external calls (new, with_capacity).

fn sorted_absolute_paths(mut paths: Vec<AbsolutePathBuf>) -> Vec<AbsolutePathBuf>

Purpose: Sorts absolute paths into stable order.

Data flow: It receives a vector of absolute paths, sorts by the underlying path text, and returns it.

Call relations: Semantic signatures and writable-root sorting use this so comparisons are not affected by entry order.

Call graph: called by 2 (semantic_signature, sorted_writable_roots).

fn sorted_writable_roots(mut roots: Vec<WritableRoot>) -> Vec<WritableRoot>

Purpose: Normalizes writable-root ordering for stable comparison.

Data flow: It sorts each root's read-only subpaths, sorts and deduplicates protected metadata names, then sorts the roots themselves by path.

Call relations: semantic_signature uses this to compare policies by meaning instead of construction order.

Call graph: calls 1 internal fn (sorted_absolute_paths); called by 1 (semantic_signature); 1 external calls (take).

fn normalize_effective_absolute_path(path: AbsolutePathBuf) -> AbsolutePathBuf

Purpose: Normalizes an absolute path using the longest existing ancestor while preserving symlink path components where intended.

Data flow: It walks ancestors of the raw path, tries to canonicalize an existing ancestor in a symlink-preserving way, rejoins the missing suffix, and returns the first successful normalized absolute path or the original path.

Call relations: dedup_absolute_paths uses this when effective path aliases should collapse to one root.

Call graph: calls 2 internal fn (from_absolute_path, to_path_buf); called by 1 (dedup_absolute_paths); 2 external calls (canonicalize_preserving_symlinks, symlink_metadata).

fn default_read_only_subpaths_for_writable_root(
    writable_root: &AbsolutePathBuf,
    protect_missing_dot_codex: bool,
) -> Vec<AbsolutePathBuf>

Purpose: Finds metadata paths inside a writable root that should be read-only by default.

Data flow: It checks for .git, .agents, and .codex, follows Git pointer files to their real git directory when needed, optionally protects missing .codex, deduplicates the results, and returns the subpaths.

Call relations: Workspace-write construction, legacy conversion, and adding legacy writable roots call this to keep sensitive metadata out of normal write access.

Call graph: calls 4 internal fn (dedup_absolute_paths, is_git_pointer_file, resolve_gitdir_from_file, join); called by 5 (from_legacy_sandbox_policy_for_cwd, with_additional_legacy_workspace_writable_roots, workspace_write, legacy_runtime_file_system_policy_for_cwd, legacy_workspace_write_projection_accepts_relative_cwd); 1 external calls (new).

fn legacy_runtime_file_system_policy_for_cwd(
    sandbox_policy: &SandboxPolicy,
    cwd: &Path,
) -> FileSystemSandboxPolicy

Purpose: Reconstructs what the older sandbox runtime would actually enforce for a current directory.

Data flow: It converts non-workspace policies directly. For workspace-write, it rebuilds read root, workspace write, temp writes, extra writable roots, and only the concrete metadata protections legacy runtime would add.

Call relations: needs_direct_runtime_enforcement compares this with the desired new policy to detect rules that the older runtime cannot express.

Call graph: calls 5 internal fn (from, restricted, append_default_read_only_path_if_no_explicit_rule, default_read_only_subpaths_for_writable_root, from_absolute_path); called by 4 (needs_direct_runtime_enforcement, legacy_projection_runtime_enforcement_ignores_entry_order, missing_symbolic_metadata_carveouts_need_direct_runtime_enforcement, split_only_nested_carveouts_need_direct_runtime_enforcement); 1 external calls (vec!).

fn append_default_read_only_project_root_subpath_if_no_explicit_rule(
    entries: &mut Vec<FileSystemSandboxEntry>,
    subpath: impl Into<PathBuf>,
)

Purpose: Adds a read-only project-root subpath rule unless the user already wrote an explicit rule for the same target.

Data flow: It receives entries and a subpath, wraps the subpath in a project-root special path, and delegates to the generic default-entry appender.

Call relations: workspace_write uses this to add symbolic .git, .agents, and .codex protections without overriding user intent.

Call graph: calls 1 internal fn (append_default_read_only_entry_if_no_explicit_rule); called by 1 (workspace_write); 2 external calls (into, project_roots).

fn append_default_read_only_path_if_no_explicit_rule(
    entries: &mut Vec<FileSystemSandboxEntry>,
    path: AbsolutePathBuf,
)

Purpose: Adds a read-only concrete path rule unless an explicit rule already targets it.

Data flow: It receives entries and an absolute path, wraps the path in a FileSystemPath::Path, and delegates to the generic default-entry appender.

Call relations: Workspace-write and legacy conversion use this for concrete protected metadata paths.

Call graph: calls 1 internal fn (append_default_read_only_entry_if_no_explicit_rule); called by 4 (from_legacy_sandbox_policy_for_cwd, with_additional_legacy_workspace_writable_roots, workspace_write, legacy_runtime_file_system_policy_for_cwd).

fn append_default_read_only_entry_if_no_explicit_rule(
    entries: &mut Vec<FileSystemSandboxEntry>,
    path: FileSystemPath,
)

Purpose: Adds a default read-only entry only when no existing entry targets the same location.

Data flow: It scans existing entries with file_system_paths_share_target; if none match, it pushes a read entry for the given path.

Call relations: The project-root and concrete-path append helpers use this to protect metadata while respecting explicit configuration.

Call graph: called by 2 (append_default_read_only_path_if_no_explicit_rule, append_default_read_only_project_root_subpath_if_no_explicit_rule).

fn has_explicit_resolved_path_entry(
    entries: &[ResolvedFileSystemEntry],
    path: &AbsolutePathBuf,
) -> bool

Purpose: Checks whether a resolved entry list already contains a specific path.

Data flow: It receives resolved entries and a path, scans for exact path equality, and returns a boolean.

Call relations: Writable-root construction uses this to avoid adding default read-only carveouts that an explicit resolved rule already covers.

Call graph: 1 external calls (iter).

fn metadata_path_name(name: &OsStr) -> Option<&'static str>

Purpose: Returns the protected metadata name if a path component is .git, .agents, or .codex.

Data flow: It receives a path component name, compares it with the protected-name list, and returns the matching static name or None.

Call relations: metadata_child_of_writable_root uses this to identify protected first components inside writable roots.

fn metadata_child_of_writable_root(
    policy: &FileSystemSandboxPolicy,
    target: &Path,
    cwd: &Path,
) -> Option<(AbsolutePathBuf, &'static str)>

Purpose: Detects whether a target path is inside protected metadata below a writable root.

Data flow: It resolves writable entries for the current directory, strips each writable root from the target, checks the first remaining component for a protected metadata name, and returns the metadata path and name.

Call relations: Both early write blocking and policy write checks use this to apply the .git, .agents, and .codex safety rule.

Call graph: calls 1 internal fn (resolved_entries_with_cwd); called by 2 (is_metadata_write_denied, forbidden_agent_metadata_write).

fn protected_metadata_names_for_writable_root(
    policy: &FileSystemSandboxPolicy,
    root: &AbsolutePathBuf,
    raw_writable_roots: &[&AbsolutePathBuf],
    cwd: &Path,
) -> Vec<String>

Purpose: Computes which protected metadata names should remain blocked for a writable root.

Data flow: It tests .git, .agents, and .codex under the effective root and raw writable-root aliases. If none of those paths are writable under the policy, it records the metadata name.

Call relations: get_writable_roots_with_cwd uses this to tell downstream sandboxes which top-level metadata names need special protection.

Call graph: 3 external calls (new, iter, vec!).

fn protected_metadata_names_need_direct_runtime_enforcement(
    policy: &FileSystemSandboxPolicy,
    legacy_policy: &SandboxPolicy,
    cwd: &Path,
) -> bool

Purpose: Checks whether protected metadata-name behavior is missing from the older legacy runtime representation.

Data flow: It compares writable roots from the new policy with writable roots from the legacy policy and returns true when a protected metadata name is not covered by a legacy read-only subpath.

Call relations: needs_direct_runtime_enforcement calls this before semantic comparison because metadata-name protections are partly outside the older sandbox contract.

Call graph: calls 1 internal fn (get_writable_roots_with_cwd); called by 1 (needs_direct_runtime_enforcement); 1 external calls (get_writable_roots_with_cwd).

fn has_explicit_write_entry_for_metadata_path(
    policy: &FileSystemSandboxPolicy,
    protected_metadata_path: &AbsolutePathBuf,
    target: &Path,
    cwd: &Path,
) -> bool

Purpose: Checks whether a protected metadata path has an explicit write rule that should override the default block.

Data flow: It resolves entries, then looks for a writable entry that both covers the target and is itself inside the protected metadata path.

Call relations: Protected-metadata write checks call this so users can deliberately grant write access to .git, .agents, or .codex when configured.

Call graph: calls 1 internal fn (resolved_entries_with_cwd); called by 2 (is_metadata_write_denied, forbidden_agent_metadata_write).

fn is_git_pointer_file(path: &AbsolutePathBuf) -> bool

Purpose: Checks whether a path is a .git file that may point to a real Git directory elsewhere.

Data flow: It tests that the path is a file and its filename is .git, then returns a boolean.

Call relations: default_read_only_subpaths_for_writable_root uses this for worktrees and submodules where .git is a pointer file rather than a directory.

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

fn resolve_gitdir_from_file(dot_git: &AbsolutePathBuf) -> Option<AbsolutePathBuf>

Purpose: Reads a .git pointer file and resolves the Git directory it points to.

Data flow: It reads the file, expects gitdir: <path>, trims and validates the target, resolves it relative to the .git file's parent, checks that it exists, logs errors on failure, and returns the resolved path when valid.

Call relations: Default protected-subpath detection calls this so the real Git metadata directory can be made read-only too.

Call graph: calls 2 internal fn (as_path, resolve_path_against_base); called by 1 (default_read_only_subpaths_for_writable_root); 2 external calls (error!, read_to_string).

fn symlink_dir(original: &Path, link: &Path) -> std::io::Result<()>

Purpose: Creates a directory symlink for Unix-only tests.

Data flow: It receives the original directory and link path, calls the operating system symlink function, and returns the I/O result.

Call relations: Symlink-focused tests call this to build realistic filesystem layouts.

Call graph: 1 external calls (symlink).

fn unknown_special_paths_are_ignored_by_legacy_bridge() -> std::io::Result<()>

Purpose: Verifies that unknown future special paths do not break legacy conversion.

Data flow: It builds a policy with an unknown write special path, converts it to a legacy policy, and checks that the result safely becomes read-only.

Call relations: This protects forward compatibility for configuration written by newer Codex versions.

Call graph: calls 1 internal fn (restricted); 3 external calls (new, assert_eq!, vec!).

fn writable_roots_proactively_protect_missing_dot_codex()

Purpose: Verifies that a workspace root protects .codex even before the directory exists.

Data flow: It creates a temporary workspace, builds a project-root write policy, asks for writable roots, and checks that .codex appears as a read-only subpath.

Call relations: This test covers the metadata-protection path used by get_writable_roots_with_cwd.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 4 external calls (new, assert!, assert_eq!, vec!).

fn legacy_workspace_write_projection_preserves_symbolic_project_root()

Purpose: Verifies that legacy workspace-write conversion keeps symbolic project-root entries.

Data flow: It creates a legacy workspace-write policy, converts it, and compares the full expected entry list including symbolic metadata carveouts.

Call relations: This guards the bridge implemented by FileSystemSandboxPolicy::from and workspace_write.

Call graph: 2 external calls (new, assert_eq!).

fn legacy_current_working_directory_special_path_deserializes_as_project_roots() -> serde_json::Result<()>

Purpose: Verifies that the old current_working_directory special-path name still loads as project_roots.

Data flow: It deserializes JSON with the old name, checks the resulting value, then serializes it back and checks the modern name.

Call relations: This keeps older config files compatible with the renamed special path.

Call graph: 2 external calls (assert_eq!, json!).

fn writable_roots_skip_default_dot_codex_when_explicit_user_rule_exists()

Purpose: Verifies that an explicit write rule for .codex overrides the default protection.

Data flow: It builds a workspace-write policy plus an explicit .codex write entry, then checks writable-root metadata names, read-only subpaths, and direct write permission.

Call relations: This exercises the explicit-rule exceptions in metadata-protection logic.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 3 external calls (new, assert!, vec!).

fn filesystem_policy_blocks_protected_metadata_path_writes_by_default()

Purpose: Verifies that .git, .agents, and .codex are not writable by default inside a writable root.

Data flow: It creates a root write policy, checks write decisions for protected metadata paths, then checks writable-root metadata protection output.

Call relations: This test covers both direct write checks and downstream writable-root construction.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 4 external calls (new, assert!, assert_eq!, vec!).

fn legacy_workspace_write_projection_accepts_relative_cwd()

Purpose: Verifies that legacy conversion works even when the current directory is relative.

Data flow: It builds expected absolute paths from the process current directory plus a relative workspace, converts a legacy policy, and checks metadata protections and forbidden writes.

Call relations: This guards from_legacy_sandbox_policy_for_cwd and relative-path resolution.

Call graph: calls 3 internal fn (from_legacy_sandbox_policy_for_cwd, default_read_only_subpaths_for_writable_root, from_absolute_path); 5 external calls (new, assert!, assert_eq!, current_dir, vec!).

fn effective_runtime_roots_preserve_symlinked_paths()

Purpose: Verifies that writable roots and carveouts preserve important symlink path spellings.

Data flow: It creates a real directory and symlinked root, adds a denied subpath, and checks unreadable roots and writable-root read-only subpaths.

Call relations: This tests the symlink-sensitive behavior in writable and unreadable root collection.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 6 external calls (new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!).

fn project_roots_special_path_preserves_symlinked_root()

Purpose: Verifies that project-root special paths keep a symlinked current directory as the visible root.

Data flow: It creates a symlinked workspace with blocked and metadata directories, builds a policy, and checks readable, unreadable, and writable-root outputs.

Call relations: This protects the project-root resolution path used during sandbox setup.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 6 external calls (new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!).

fn writable_roots_preserve_symlinked_protected_subpaths()

Purpose: Verifies that a protected metadata symlink itself is kept as the read-only subpath.

Data flow: It makes .codex a symlink to another directory, builds a writable-root policy, and checks that the read-only subpath is .codex, not just the symlink target.

Call relations: This guards downstream sandbox behavior that must mask the user-visible symlink inode.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 6 external calls (new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!).

fn writable_roots_preserve_explicit_symlinked_carveouts_under_symlinked_roots()

Purpose: Verifies that explicit deny carveouts under symlinked roots keep their logical path.

Data flow: It creates a symlinked root and a denied symlinked child, then checks the writable root and read-only subpath list.

Call relations: This covers the raw-carveout preservation branch in get_writable_roots_with_cwd.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 6 external calls (new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!).

fn writable_roots_preserve_explicit_symlinked_carveouts_that_escape_root()

Purpose: Verifies that a denied symlink inside a root is protected even when it points outside the root.

Data flow: It creates a root with a symlink to an outside directory, denies the symlink path, and checks that the read-only subpath is the symlink path, not the outside target.

Call relations: This prevents symlink escapes from weakening carveout enforcement.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 6 external calls (new, assert!, assert_eq!, create_dir_all, symlink_dir, vec!).

fn writable_roots_preserve_explicit_symlinked_carveouts_that_alias_root()

Purpose: Verifies that a symlink inside a root pointing back to the root can still be carved out.

Data flow: It creates an alias symlink, denies it, and checks that the writable root reports the alias path as read-only.

Call relations: This covers a subtle symlink loop-like case in writable-root carveout handling.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 5 external calls (new, assert_eq!, create_dir_all, symlink_dir, vec!).

fn tmpdir_special_path_preserves_symlinked_tmpdir()

Purpose: Verifies that the TMPDIR special path preserves a symlinked temporary directory.

Data flow: It runs in a subprocess with a test environment variable, sets TMPDIR to a symlink, builds a policy, and checks unreadable and writable-root outputs.

Call relations: This guards resolve_file_system_special_path and writable-root behavior for environment-based temp directories.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 10 external calls (new, assert!, assert_eq!, new, create_dir_all, symlink_dir, current_exe, set_var, var_os, vec!).

fn resolve_access_with_cwd_uses_most_specific_entry()

Purpose: Verifies that the most specific matching path rule wins.

Data flow: It builds a policy with workspace write, read-only docs, denied private docs, and writable nested public docs, then checks effective access at each level.

Call relations: This directly tests resolve_access_with_cwd and entry precedence.

Call graph: calls 2 internal fn (restricted, resolve_path_against_base); 3 external calls (new, assert_eq!, vec!).

fn split_only_nested_carveouts_need_direct_runtime_enforcement()

Purpose: Verifies that nested read-only carveouts require direct enforcement when legacy sandboxing cannot express them.

Data flow: It builds a workspace-write policy with a read-only child path and checks that direct runtime enforcement is required.

Call relations: This covers needs_direct_runtime_enforcement and the legacy runtime comparison.

Call graph: calls 3 internal fn (restricted, legacy_runtime_file_system_policy_for_cwd, resolve_path_against_base); 4 external calls (new, new_workspace_write_policy, assert!, vec!).

fn legacy_projection_runtime_enforcement_ignores_entry_order()

Purpose: Verifies that policy entry order does not affect semantic equivalence or enforcement classification.

Data flow: It builds a legacy runtime policy, reverses its entries, and checks semantic equivalence and direct-enforcement results.

Call relations: This guards the normalized semantic-signature comparison.

Call graph: calls 2 internal fn (restricted, legacy_runtime_file_system_policy_for_cwd); 4 external calls (new, new, assert!, assert_eq!).

fn missing_symbolic_metadata_carveouts_need_direct_runtime_enforcement()

Purpose: Verifies that symbolic metadata protections need direct enforcement when legacy runtime cannot represent missing paths.

Data flow: It builds both profile and legacy runtime projections for workspace-write and checks that direct enforcement is required.

Call relations: This protects the special handling for metadata names and missing .codex paths.

Call graph: calls 2 internal fn (from_legacy_sandbox_policy_for_cwd, legacy_runtime_file_system_policy_for_cwd); 3 external calls (new, new, assert!).

fn root_write_with_read_only_child_is_not_full_disk_write()

Purpose: Verifies that root write plus a read-only child is not treated as full disk write.

Data flow: It builds that policy, checks full-write status, checks child access, checks direct enforcement, and expects legacy conversion to fail.

Call relations: This guards has_write_narrowing_entries, has_full_disk_write_access, and legacy conversion safety.

Call graph: calls 2 internal fn (restricted, resolve_path_against_base); 4 external calls (new, assert!, assert_eq!, vec!).

fn root_deny_does_not_materialize_as_unreadable_root()

Purpose: Verifies that a root deny does not get exported as an unreadable root when a narrower read allow exists.

Data flow: It builds root deny plus readable docs, checks docs access and readable roots, and confirms unreadable roots are empty.

Call relations: This protects the filtering behavior in get_unreadable_roots_with_cwd.

Call graph: calls 3 internal fn (restricted, from_absolute_path, resolve_path_against_base); 5 external calls (new, assert!, assert_eq!, canonicalize_preserving_symlinks, vec!).

fn duplicate_root_deny_prevents_full_disk_write_access()

Purpose: Verifies that an explicit root deny defeats a root write grant at the same target.

Data flow: It builds root write and root deny entries, checks that full write is false, and checks root access resolves to deny.

Call relations: This covers access-mode conflict precedence.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 4 external calls (new, assert!, assert_eq!, vec!).

fn same_specificity_write_override_keeps_full_disk_write_access()

Purpose: Verifies that a same-target write entry can override a read entry for full-write detection.

Data flow: It builds root write plus both read and write entries for the same child path, then checks full-write status and resolved child access.

Call relations: This guards has_same_target_write_override and conflict precedence.

Call graph: calls 2 internal fn (restricted, resolve_path_against_base); 4 external calls (new, assert!, assert_eq!, vec!).

fn with_additional_readable_roots_skips_existing_effective_access()

Purpose: Verifies that adding readable roots does not duplicate access already granted.

Data flow: It builds a project-root read policy, tries to add the current root as readable, and checks that the policy is unchanged.

Call relations: This tests with_additional_readable_roots.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 4 external calls (new, assert_eq!, from_ref, vec!).

fn with_additional_writable_roots_skips_existing_effective_access()

Purpose: Verifies that adding writable roots skips paths already writable through project-root access.

Data flow: It builds a project-root write policy, tries to add the current root as writable, and checks that the policy is unchanged.

Call relations: This tests with_additional_writable_roots.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 4 external calls (new, assert_eq!, from_ref, vec!).

fn with_additional_writable_roots_adds_new_root()

Purpose: Verifies that a truly new writable root is appended.

Data flow: It builds a project-root write policy, adds a separate extra root, and checks the expected new write entry.

Call relations: This covers the positive path in with_additional_writable_roots.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 4 external calls (new, assert_eq!, from_ref, vec!).

fn materialize_project_roots_with_workspace_roots_expands_exact_and_glob_entries()

Purpose: Verifies that project-root special paths and marked glob patterns expand for every workspace root.

Data flow: It builds symbolic write, symbolic read, and symbolic glob deny entries, materializes them for two roots, and checks the full expanded entry list.

Call relations: This tests materialize_project_roots_with_workspace_roots and project-root glob expansion.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 3 external calls (new, assert_eq!, vec!).

fn materialize_project_roots_with_cwd_expands_symbolic_glob_entries()

Purpose: Verifies that a project-root-marked glob can be materialized using the current directory.

Data flow: It builds a deny glob with the project-root marker, materializes with a temp current directory, and checks the absolute glob pattern.

Call relations: This tests materialize_project_roots_with_cwd.

Call graph: calls 1 internal fn (restricted); 3 external calls (new, assert_eq!, vec!).

fn with_additional_legacy_workspace_writable_roots_protects_metadata()

Purpose: Verifies that adding legacy writable roots also adds protected metadata carveouts.

Data flow: It creates an extra root with .git, adds it through the legacy helper, and checks that the result includes both write root and read-only .git entry.

Call relations: This tests with_additional_legacy_workspace_writable_roots.

Call graph: calls 2 internal fn (restricted, from_absolute_path); 5 external calls (new, assert_eq!, create_dir_all, from_ref, vec!).

fn file_system_access_mode_orders_by_conflict_precedence()

Purpose: Verifies the intended ordering of access modes for conflict resolution.

Data flow: It checks that write outranks read and deny outranks write.

Call relations: This protects the enum ordering used by resolved_entry_precedence.

Call graph: 1 external calls (assert!).

fn legacy_bridge_preserves_explicit_deny_entries()

Purpose: Verifies that legacy policy rebuilding does not drop existing deny entries.

Data flow: It builds an existing policy with a denied path, rebuilds from a legacy workspace-write policy, and checks that the denied path remains.

Call relations: This tests from_legacy_sandbox_policy_preserving_deny_entries.

Call graph: calls 3 internal fn (from_legacy_sandbox_policy_preserving_deny_entries, restricted, try_from); 4 external calls (new, new_workspace_write_policy, assert!, vec!).

fn preserving_deny_entries_keeps_unrestricted_policy_enforceable()

Purpose: Verifies that preserving deny entries turns an unrestricted replacement into an enforceable restricted policy.

Data flow: It creates an existing deny-glob policy with scan depth, starts with unrestricted replacement, preserves denies, and compares the expected restricted full-write-plus-deny policy.

Call relations: This tests preserve_deny_read_restrictions_from.

Call graph: calls 2 internal fn (restricted, unrestricted); 3 external calls (assert_eq!, unreadable_glob_entry, vec!).

fn deny_policy(path: &Path) -> FileSystemSandboxPolicy

Purpose: Builds a small test policy that denies one absolute path.

Data flow: It receives a path, converts it to an absolute path, wraps it in a deny entry, and returns a restricted policy.

Call relations: Read-deny tests use this fixture to avoid repeating policy construction.

Call graph: calls 1 internal fn (restricted); 1 external calls (vec!).

fn unreadable_glob_entry(pattern: String) -> FileSystemSandboxEntry

Purpose: Builds a test deny entry from a glob pattern.

Data flow: It receives a pattern string and returns a filesystem sandbox entry with deny access.

Call relations: Read-deny tests and helper policies use this fixture for glob-based denials.

fn default_policy_with_unreadable_glob(pattern: String) -> FileSystemSandboxPolicy

Purpose: Builds a default read-only test policy with one extra unreadable glob.

Data flow: It starts from the default policy, appends a deny glob entry, and returns the policy.

Call relations: Glob read-deny tests use this to focus on matcher behavior.

Call graph: calls 1 internal fn (default); 1 external calls (unreadable_glob_entry).

fn is_read_denied(
        path: &Path,
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        cwd: &Path,
    ) -> bool

Purpose: Convenience helper for testing whether a path is denied by a policy.

Data flow: It builds a ReadDenyMatcher from the policy and current directory, then asks it whether the path is denied; if no matcher exists, it returns false.

Call relations: The read-deny test cases call this to exercise ReadDenyMatcher::new and ReadDenyMatcher::is_read_denied.

Call graph: calls 1 internal fn (new).

fn exact_path_and_descendants_are_denied()

Purpose: Verifies that an exact deny root blocks both that directory and its children.

Data flow: It creates a denied directory and nested file, builds a deny policy, and checks that those paths are denied while an unrelated path is not.

Call relations: This tests exact-root matching in ReadDenyMatcher.

Call graph: 5 external calls (new, assert!, deny_policy, create_dir_all, write).

fn canonical_target_matches_denied_symlink_alias()

Purpose: Verifies that a symlink alias to a denied directory is also denied.

Data flow: It creates a real directory, a symlink alias, and a file, denies the real directory, and checks that reading through the alias is denied.

Call relations: This tests canonical candidate matching in read-deny logic.

Call graph: 6 external calls (new, assert!, deny_policy, symlink_dir, create_dir_all, write).

fn literal_patterns_and_globs_are_denied()

Purpose: Verifies that exact deny roots and glob deny patterns both work in the same policy.

Data flow: It creates a literal denied directory and a text file matched by a glob, then checks both are denied.

Call relations: This covers combined root and glob matching in ReadDenyMatcher.

Call graph: 7 external calls (new, assert!, format!, deny_policy, unreadable_glob_entry, create_dir_all, write).

fn glob_patterns_deny_matching_paths()

Purpose: Verifies that a simple glob pattern denies matching paths.

Data flow: It creates a path like private/secret1.txt, adds a secret?.txt deny glob, and checks that the file is denied.

Call relations: This tests pattern compilation and matching.

Call graph: 6 external calls (new, assert!, format!, default_policy_with_unreadable_glob, create_dir_all, write).

fn glob_patterns_do_not_cross_path_separators()

Purpose: Verifies that *, ?, and character classes do not match across directory separators.

Data flow: It creates matching, nested, short, and letter-containing filenames, applies a glob, and checks only the intended same-directory numeric filename is denied.

Call relations: This protects the literal_separator behavior configured in build_glob_matcher.

Call graph: 6 external calls (new, assert!, format!, default_policy_with_unreadable_glob, create_dir_all, write).

fn globstar_patterns_deny_root_and_nested_matches()

Purpose: Verifies that ** glob patterns match both root-level and nested files.

Data flow: It creates .env files at root and nested locations plus a nonmatching notes file, applies a **/*.env deny glob, and checks the expected denials.

Call relations: This tests globstar behavior in deny-read patterns.

Call graph: 6 external calls (new, assert!, format!, default_policy_with_unreadable_glob, create_dir_all, write).

fn unclosed_character_classes_match_literal_brackets()

Purpose: Verifies that an unclosed [ in a glob pattern is treated as a literal bracket.

Data flow: It creates a file named [, adds a glob ending in [, and checks that only that file is denied.

Call relations: This protects the allow_unclosed_class behavior in build_glob_matcher.

Call graph: 5 external calls (new, assert!, format!, default_policy_with_unreadable_glob, write).

fn requires_escalated_permissions(self) -> bool

Purpose: Answers whether a command is asking to run fully outside the sandbox. Callers use this as a safety check before allowing stronger permissions.

Data flow: It receives one sandbox-permission choice, compares it with the escalated option, and returns true only for that exact choice. It does not change anything.

Call relations: Command execution and sandbox-planning code call this before deciding whether to bypass normal restrictions or preserve denied reads.

Call graph: called by 4 (exec_env_for_sandbox_permissions, managed_network_for_sandbox_permissions, sandbox_override_for_first_attempt, sandbox_permissions_preserving_denied_reads); 1 external calls (matches!).

fn requests_sandbox_override(self) -> bool

Purpose: Answers whether a command asked for any permission behavior different from the default. This lets UI and event code show that a command made a special request.

Data flow: It receives a permission choice, checks whether it is not the default choice, and returns a boolean. Nothing is modified.

Call relations: Shell event builders call it when recording command events so they can mark commands that requested extra sandbox treatment.

Call graph: called by 3 (exec_command_event, shell_event_with_prefix_rule, exec_command_event); 1 external calls (matches!).

fn uses_additional_permissions(self) -> bool

Purpose: Answers whether a command wants to stay sandboxed but temporarily widen access. This distinguishes limited extra access from full escalation.

Data flow: It receives one permission value, compares it with the additional-permissions option, and returns true only in that case.

Call relations: Permission-granting code calls it when applying approved turn permissions or inferring what permissions were granted.

Call graph: called by 2 (apply_granted_turn_permissions, implicit_granted_permissions); 1 external calls (matches!).

fn try_from(value: FileSystemPermissions<PathUri>) -> Result<Self, Self::Error>

Purpose: Converts file-system permissions written with URI-style paths into permissions using absolute local paths. This is needed when JSON-friendly paths come back into runtime code.

Data flow: It takes permission entries containing path URIs, tries to convert every entry into an absolute path, keeps the glob depth setting, and returns either converted permissions or an I/O error.

Call relations: It supports boundary crossings where protocol data must become local filesystem data before sandbox enforcement.

fn default() -> Self

Purpose: Creates an empty file-system permission set. This is the safe starting point: no entries and no glob scanning depth.

Data flow: It takes no input, creates an empty list and no depth limit, and returns the new permission object.

Call relations: Normalization code uses this when dropping empty nested permission profiles.

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

fn is_empty(&self) -> bool

Purpose: Checks whether there are no file-system permission entries. Callers can use this to avoid treating an empty permission block as meaningful access.

Data flow: It reads the entries list and returns true if that list has no items.

Call relations: It is a small helper for code that needs to tell empty permissions from explicit read or write grants.

fn from_read_write_roots(
        read: Option<Vec<PathType>>,
        write: Option<Vec<PathType>>,
    ) -> Self

Purpose: Builds modern file-system permission entries from older separate read-root and write-root lists. This keeps older configuration shapes useful.

Data flow: It receives optional read paths and optional write paths, turns each path into a permission entry with the matching access mode, and returns one combined permission object.

Call relations: Many permission-request and sandbox-context paths call it when turning legacy root lists into the current entry-based model.

Call graph: called by 39 (request_permissions_response_materializes_session_cwd_grants_before_recording, write_permissions_for_paths, file_system_permissions, file_system_sandbox_context_uses_active_attempt, preapproved_additional_permissions_escalate_intercepted_exec, shell_request_escalation_execution_is_explicit, extension_tool_uses_granted_turn_permissions, remote_request_permissions_grant_unblocks_later_remote_exec, normalized_directory_write_permissions, partial_request_permissions_grants_do_not_preapprove_new_permissions (+15 more)); 1 external calls (new).

fn explicit_path_entries(&self) -> impl Iterator<Item = (&PathType, FileSystemAccessMode)>

Purpose: Iterates only over direct path-based permissions, ignoring glob patterns and special symbolic paths. This helps callers that specifically need concrete filesystem paths.

Data flow: It reads each permission entry, keeps entries whose path is a normal path, and yields the path plus its access mode.

Call relations: It is used as a filtering view over the broader permission model when concrete paths are required.

fn legacy_read_write_roots(&self) -> Option<LegacyReadWriteRoots<PathType>>

Purpose: Attempts to express current permissions in the older read-list/write-list format. It only succeeds when nothing in the permissions is too new for that format.

Data flow: It reads the permission entries, asks the private legacy converter to validate and split them, and returns optional read and write root lists.

Call relations: It delegates to as_legacy_permissions, which is also used by serialization to decide whether old JSON can be emitted.

Call graph: calls 1 internal fn (as_legacy_permissions).

fn as_legacy_permissions(&self) -> Option<LegacyFileSystemPermissions<PathType>>

Purpose: Checks whether file-system permissions can safely be represented in the old format. It rejects newer features such as glob depth, glob entries, special paths, or explicit denies.

Data flow: It scans all entries, separates read paths from write paths, and returns a legacy object if every entry is compatible; otherwise it returns none.

Call relations: Both legacy_read_write_roots and custom serialization rely on this to avoid losing meaning when using the older shape.

Call graph: called by 2 (legacy_read_write_roots, serialize); 1 external calls (new).

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

Purpose: Writes file-system permissions to JSON in the simplest compatible shape. It uses the old read/write shape when possible and the full canonical shape when needed.

Data flow: It receives the permission object, tries the legacy conversion, then serializes either that legacy form or the full entries-plus-depth form.

Call relations: Serde, the Rust JSON serialization framework, calls this whenever these permissions are sent over the wire or stored.

Call graph: calls 1 internal fn (as_legacy_permissions).

fn deserialize(deserializer: D) -> Result<Self, D::Error>

Purpose: Reads file-system permissions from either the new canonical JSON shape or the older read/write shape. This protects compatibility with stored data and older clients.

Data flow: It receives JSON data, lets Serde parse it as one of the supported shapes, then returns a unified FileSystemPermissions value.

Call relations: Serde calls it during config, rollout, or protocol loading; it uses from_read_write_roots for legacy data.

Call graph: 2 external calls (from_read_write_roots, deserialize).

fn is_empty(&self) -> bool

Purpose: Checks whether a network permission override says nothing. An absent setting means there is no network change requested.

Data flow: It reads the optional enabled flag and returns true when that flag is missing.

Call relations: It is a simple helper for permission overlay logic that needs to ignore empty network blocks.

fn is_empty(&self) -> bool

Purpose: Checks whether a per-command or granted permission overlay contains no file or network section. This prevents empty wrappers from being mistaken for real grants.

Data flow: It reads the optional network and file-system fields and returns true only if both are absent.

Call relations: Tests and permission-normalization paths use this to distinguish no overlay from an explicit, even if nested-empty, overlay.

fn from_legacy_sandbox_policy(sandbox_policy: &SandboxPolicy) -> Self

Purpose: Translates an older sandbox policy into the newer idea of who enforces the sandbox. This is part of the bridge from old configuration to permission profiles.

Data flow: It receives a legacy sandbox policy and returns managed, disabled, or external enforcement based on the policy kind.

Call relations: Configuration application, one-off command execution, and agent-spawn setup call it before building modern permission profiles.

Call graph: called by 12 (exec_one_off_command_inner, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, apply, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries, session_configuration_apply_preserves_profile_file_system_policy_on_cwd_only_update, session_configuration_apply_retargets_legacy_workspace_root_on_cwd_update, build_agent_spawn_config_uses_turn_context_values, spawn_agent_reapplies_runtime_sandbox_after_role_config, from_legacy_sandbox_policy (+2 more)).

fn from(value: ManagedFileSystemPermissions<AbsolutePathBuf>) -> Self

Purpose: Converts managed file-system permissions from local absolute paths into URI-style paths. This makes the data safe to send through protocol JSON.

Data flow: It takes either restricted entries or unrestricted access, converts each path entry when restricted, and returns the same permission meaning with URI paths.

Call relations: It supports protocol boundaries where local runtime permission data must be represented in client-friendly path form.

fn try_from(value: ManagedFileSystemPermissions<PathUri>) -> Result<Self, Self::Error>

Purpose: Converts managed file-system permissions from URI-style paths back into local absolute paths. This is needed before the runtime can enforce paths on disk.

Data flow: It takes URI-based permissions, converts every restricted entry into an absolute path, preserves unrestricted access as-is, and returns an error if any path conversion fails.

Call relations: It is the reverse of the URI conversion used when protocol data returns to runtime enforcement code.

fn from_sandbox_policy(file_system_sandbox_policy: &FileSystemSandboxPolicy) -> Self

Purpose: Builds the managed permission form from a runtime file-system sandbox policy. It keeps the profile model aligned with the lower-level sandbox model.

Data flow: It reads whether the sandbox policy is restricted or unrestricted, copies entries and scan depth for restricted policies, and returns the matching managed permission variant.

Call relations: Permission-profile constructors call it for read-only, workspace-write, materialized roots, and runtime-policy conversion.

Call graph: called by 4 (from_runtime_permissions_with_enforcement, materialize_project_roots_with_workspace_roots, read_only, workspace_write_with); 1 external calls (unreachable!).

fn to_sandbox_policy(&self) -> FileSystemSandboxPolicy

Purpose: Turns managed profile permissions back into the runtime sandbox policy that enforcement code understands.

Data flow: It reads the managed variant, clones restricted entries and depth into a sandbox policy, or returns an unrestricted sandbox policy.

Call relations: Permission-profile methods call it when they need to hand file-system rules to sandbox execution or legacy conversion.

Call graph: calls 1 internal fn (unrestricted).

fn try_from(value: PermissionProfile<PathUri>) -> Result<Self, Self::Error>

Purpose: Converts a permission profile using URI paths into one using absolute local paths. This prepares protocol data for runtime use.

Data flow: It receives a URI-based profile, converts the file-system part when the profile is managed, leaves disabled and external profiles structurally unchanged, and returns an error on bad paths.

Call relations: It is used when permission profiles cross from serialized/client form back into local execution form.

fn new(id: impl Into<String>) -> Self

Purpose: Creates metadata naming the permission profile currently in effect. This is for display and traceability, not enforcement.

Data flow: It receives an identifier, converts it into a string, sets no parent profile, and returns the metadata object.

Call relations: ActivePermissionProfile::read_only calls it for the built-in read-only profile, and callers can use it for user-defined profile IDs.

Call graph: 1 external calls (into).

fn read_only() -> Self

Purpose: Creates active-profile metadata for the built-in read-only profile. This gives clients a stable label to show.

Data flow: It takes no input, passes the reserved read-only profile ID to new, and returns the metadata.

Call relations: It is a convenience wrapper over ActivePermissionProfile::new for the common safest built-in profile.

Call graph: 1 external calls (new).

fn default() -> Self

Purpose: Creates the default permission profile: managed sandboxing, no file entries, and restricted network. This is a conservative baseline.

Data flow: It takes no input and returns a managed profile with empty restricted file-system permissions and restricted network access.

Call relations: Tool-listing and setup tests rely on this default when no special profile is supplied.

Call graph: called by 14 (list_all_tools_accepts_canonical_namespaced_tool_names, list_all_tools_adds_server_metadata_to_cached_tools, list_all_tools_applies_legacy_mcp_prefix_by_default, list_all_tools_blocks_while_client_is_pending_without_cached_tool_info_snapshot, list_all_tools_does_not_block_when_cached_tool_info_snapshot_is_empty, list_all_tools_uses_cached_tool_info_snapshot_when_client_startup_fails, list_all_tools_uses_cached_tool_info_snapshot_while_client_is_pending, list_available_server_infos_uses_cache_while_client_is_pending, no_local_runtime_fails_local_stdio_but_keeps_local_http_server, shutdown_cancels_pending_tool_listing (+4 more)); 1 external calls (new).

fn read_only() -> Self

Purpose: Builds the built-in read-only permission profile. It lets Codex read but not freely write files, with network access restricted.

Data flow: It creates a read-only file-system sandbox policy, converts it into managed profile permissions, attaches restricted network policy, and returns the profile.

Call relations: Configuration, rollback, sandbox execution, and many tests call it when they need the safest built-in permission mode.

Call graph: calls 2 internal fn (from_sandbox_policy, read_only); called by 153 (rollback_response_rebuilds_pathless_thread_from_stored_history, cancellation_expiration_keeps_process_alive_until_terminated, timeout_or_cancellation_reports_cancellation_without_timeout_exit_code, windows_sandbox_exec_request, requested_permissions_trust_project_uses_permission_profile_intent, summary_from_stored_thread_preserves_millisecond_precision, default, try_from, derive_permission_profile, load_config_with_layer_stack (+15 more)).

fn workspace_write() -> Self

Purpose: Builds the built-in workspace-write profile. This lets Codex write in workspace areas while keeping network access restricted.

Data flow: It calls workspace_write_with with no extra roots and default exclusion flags, then returns that profile.

Call relations: Sandbox-mode derivation and permission-profile selection call it for the common editable-project mode.

Call graph: called by 77 (requested_permissions_trust_project_uses_permission_profile_intent, debug_sandbox_honors_explicit_builtin_permission_profile, derive_permission_profile, derive_sandbox_policy_preserves_windows_downgrade_for_unsupported_fallback, permission_snapshot_setter_preserves_permission_constraints, managed_allowed_domains_only_disables_default_mode_allowlist_expansion, managed_allowed_domains_only_ignores_user_allowlist_and_hard_denies_misses, managed_allowed_domains_only_without_managed_allowlist_blocks_all_user_domains, requirements_allowed_domains_do_not_override_user_denies_for_same_pattern, requirements_allowlist_expansion_keeps_user_entries_mutable (+15 more)); 1 external calls (workspace_write_with).

fn workspace_write_with(
        writable_roots: &[AbsolutePathBuf],
        network: NetworkSandboxPolicy,
        exclude_tmpdir_env_var: bool,
        exclude_slash_tmp: bool,
    ) -> Self

Purpose: Builds a workspace-write profile with explicit writable roots and network behavior. This is the configurable version of the workspace preset.

Data flow: It receives writable roots, network policy, and temporary-directory exclusion flags, asks the sandbox policy layer to build file rules, converts those rules into managed permissions, and returns a profile.

Call relations: Configuration loading and sandbox approval tests call it when workspace-write needs custom roots or flags.

Call graph: calls 2 internal fn (from_sandbox_policy, workspace_write); called by 33 (deserialize_allowed_sandbox_modes, remote_sandbox_config_first_match_overrides_top_level, derive_permission_profile, builtin_permission_profile, windows_restricted_token_allows_workspace_write_profiles, granular_sandbox_approval_false_rejects_out_of_root_patch, granular_with_all_flags_true_matches_on_request_for_out_of_root_patch, missing_project_dot_codex_config_requires_approval, restrictive_workspace_write_profile, restrictive_workspace_write_profile (+15 more)).

fn materialize_project_roots_with_workspace_roots(
        self,
        workspace_roots: &[AbsolutePathBuf],
    ) -> Self

Purpose: Replaces symbolic workspace-root permissions with actual project root paths. This makes a profile ready for real enforcement.

Data flow: It consumes a profile, and if it is managed, converts its file-system rules through sandbox-policy materialization using the provided workspace roots; other profile kinds pass through unchanged.

Call relations: It bridges profile definitions that mention symbolic roots with runtime policies that need concrete paths.

Call graph: calls 1 internal fn (from_sandbox_policy).

fn from_runtime_permissions(
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        network_sandbox_policy: NetworkSandboxPolicy,
    ) -> Self

Purpose: Builds a permission profile from the lower-level runtime file and network sandbox policies. This lets old runtime settings be viewed as the newer profile model.

Data flow: It reads the file-system policy kind to infer enforcement, then delegates to the more explicit conversion function with the network policy included.

Call relations: Config loading and many sandbox tests call it when turning runtime permission pieces into one profile.

Call graph: called by 65 (requested_permissions_trust_project_uses_permission_profile_intent, load_config_with_layer_stack, permission_profile_override_keeps_memories_root_out_of_legacy_projection, workspace_write_permission_profile_with_private_denials, managed_cwd_write_profile_has_filesystem_restrictions, managed_full_disk_write_profile_has_no_filesystem_restrictions, managed_unresolvable_write_profile_has_filesystem_restrictions, writable_windows_policy_without_sandbox_backend_still_requires_approval, windows_elevated_allows_split_restricted_read_policies, windows_elevated_rejects_reopened_writable_descendants (+15 more)); 1 external calls (from_runtime_permissions_with_enforcement).

fn from_runtime_permissions_with_enforcement(
        enforcement: SandboxEnforcement,
        file_system_sandbox_policy: &FileSystemSandboxPolicy,
        network_sandbox_policy: NetworkSandboxPolic

Purpose: Builds a permission profile from runtime sandbox policies plus an explicit enforcement choice. This preserves subtle cases like unrestricted files but restricted network.

Data flow: It receives enforcement, file-system policy, and network policy, then returns external, disabled, or managed profile form according to the combination.

Call relations: It is the central constructor used by legacy conversion, config application, one-off command setup, and permission projection.

Call graph: calls 1 internal fn (from_sandbox_policy); called by 23 (managed_full_disk_with_restricted_network_reports_external_sandbox, exec_one_off_command_inner, load_config_with_layer_stack, can_set_legacy_sandbox_policy, set_legacy_sandbox_policy, permission_profile_override_preserves_split_write_roots, apply, set_permission_profile_projection, record_context_updates_and_set_reference_context_item_persists_split_file_system_policy_to_rollout, session_configuration_apply_permission_profile_preserves_existing_deny_read_entries (+13 more)).

fn from_legacy_sandbox_policy(sandbox_policy: &SandboxPolicy) -> Self

Purpose: Converts an old SandboxPolicy into a modern permission profile. This keeps older callers and stored settings compatible.

Data flow: It receives the legacy policy, derives enforcement, file-system policy, and network policy from it, then delegates to the explicit runtime conversion.

Call relations: Round-trip tests call it directly, and production paths use the same pattern when migrating legacy sandbox settings.

Call graph: calls 3 internal fn (from_legacy_sandbox_policy, from, from); called by 2 (permission_profile_round_trip_preserves_disabled_sandbox, permission_profile_round_trip_preserves_external_sandbox); 1 external calls (from_runtime_permissions_with_enforcement).

fn from_legacy_sandbox_policy_for_cwd(sandbox_policy: &SandboxPolicy, cwd: &Path) -> Self

Purpose: Converts an old sandbox policy into a permission profile while taking the current working directory into account. This matters because some legacy policies are relative to where the session runs.

Data flow: It receives a legacy policy and a directory, derives cwd-aware file-system rules plus network and enforcement settings, then returns the modern profile.

Call relations: Turn submission, session settings, and thread-resume code call it when applying older sandbox settings to an active session.

Call graph: calls 3 internal fn (from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from); called by 6 (submit_turn_with_policies, deserialize, apply_thread_settings_to_session, display_permission_profile_from_thread_response, thread_session_state_from_thread_resume_response, apply_thread_settings); 1 external calls (from_runtime_permissions_with_enforcement).

fn enforcement(&self) -> SandboxEnforcement

Purpose: Reports who is responsible for sandbox enforcement for this profile. This is useful for execution setup and UI summaries.

Data flow: It reads the profile variant and returns managed, disabled, or external enforcement.

Call relations: Sandbox-context builders and permission projection code call it before deciding how to execute commands.

Call graph: called by 4 (set_permission_profile_projection, file_system_sandbox_context, with_managed_mitm_ca_readable_root, effective_permission_profile).

fn file_system_sandbox_policy(&self) -> FileSystemSandboxPolicy

Purpose: Extracts the runtime file-system sandbox policy represented by a permission profile. This is the shape that sandbox enforcement code understands.

Data flow: It reads the profile: managed profiles convert their file-system permissions, disabled profiles become unrestricted, and external profiles become an external-sandbox marker.

Call relations: Sandbox mode calculation, trust checks, and runtime permission conversion call it whenever file access rules are needed.

Call graph: calls 2 internal fn (external_sandbox, unrestricted); called by 13 (sandbox_policy_mode, permission_profile_trusts_project, sandbox_mode_requirement_for_permission_profile, profile_has_managed_filesystem_restrictions, permission_profile_policy_tag, file_system_sandbox_policy, sandbox_mode_from_permission_profile, from_permission_profile, to_runtime_permissions, add_dir_warning_message (+3 more)).

fn network_sandbox_policy(&self) -> NetworkSandboxPolicy

Purpose: Extracts the network sandbox policy from a permission profile. Disabled profiles imply network enabled because there is no sandbox.

Data flow: It reads the profile and returns its stored network policy for managed or external profiles, or enabled network for disabled profiles.

Call relations: Network proxy setup, sandbox spawning, and runtime permission conversion call it to decide whether network access is allowed.

Call graph: called by 11 (sandbox_policy_mode, network_proxy_spec_for_active_permission_profile, spawn_command_under_linux_sandbox, network_sandbox_policy, sandbox_mode_from_permission_profile, from_permission_profile, to_runtime_permissions, sandbox_mode_from_permission_profile, preset_matches_current, legacy_compatible_permission_profile (+1 more)).

fn to_legacy_sandbox_policy(&self, cwd: &Path) -> io::Result<SandboxPolicy>

Purpose: Attempts to represent the modern permission profile as an old SandboxPolicy. This supports older APIs and summaries that still use the legacy type.

Data flow: It receives a current working directory, converts managed profiles through the file-system sandbox policy, maps disabled to full access, and maps external profiles to the legacy external form.

Call relations: Compatibility and summary code call it when they must speak the older sandbox-policy language.

Call graph: called by 4 (turn_permission_fields, compatibility_sandbox_policy_for_permission_profile, legacy_compatible_permission_profile, summarize_permission_profile).

fn to_runtime_permissions(&self) -> (FileSystemSandboxPolicy, NetworkSandboxPolicy)

Purpose: Splits a permission profile into the file-system and network policies used by command execution. This is a convenience for runtime setup.

Data flow: It reads the profile, calls the file-system and network extraction helpers, and returns the two policies as a pair.

Call relations: Execution request builders, sandbox contexts, and thread permission application call it before launching or configuring work.

Call graph: calls 2 internal fn (file_system_sandbox_policy, network_sandbox_policy); called by 12 (build_exec_request, resolve_windows_elevated_filesystem_overrides, resolve_windows_restricted_token_filesystem_overrides, new, set_permission_profile_projection, file_system_sandbox_context, sandbox_exec_request, apply_permission_profile_to_current_thread, should_warn_about_system_bwrap, with_managed_mitm_ca_readable_root (+2 more)).

fn from(value: LegacyPermissionProfile<PathType>) -> Self

Purpose: Converts a tagged deserialized permission profile into the main PermissionProfile enum. This separates JSON parsing details from the runtime type.

Data flow: It receives a tagged profile value, matches its kind, and returns the corresponding managed, disabled, or external profile.

Call relations: Custom deserialization uses this after Serde has recognized the tagged JSON shape.

fn deserialize(deserializer: D) -> Result<Self, D::Error>

Purpose: Reads permission profiles from JSON in either the modern tagged shape or an older rollout shape. This keeps stored histories and older data readable.

Data flow: It lets Serde parse the incoming JSON as tagged or legacy, converts whichever form was found, and returns a unified permission profile.

Call relations: Serde calls it whenever a PermissionProfile is loaded from protocol JSON, config, or stored rollout data.

Call graph: 1 external calls (deserialize).

fn from(value: NetworkSandboxPolicy) -> Self

Purpose: Converts a runtime network sandbox policy into a simple optional enabled flag. This is mainly for permission overlay formats.

Data flow: It reads whether the runtime network policy is enabled and stores that boolean in NetworkPermissions.

Call relations: Permission conversion code uses it when projecting runtime network state into protocol-friendly permission data.

Call graph: calls 1 internal fn (is_enabled).

fn from(value: &FileSystemSandboxPolicy) -> Self

Purpose: Converts a runtime file-system sandbox policy into the simpler file-system permissions structure. Unrestricted or external policies become a root write entry.

Data flow: It reads the sandbox policy kind, copies restricted entries or creates an all-root write marker, converts glob depth to a non-zero value if present, and returns permissions.

Call relations: Permission projection code uses it when representing runtime sandbox policy as protocol-level permissions.

Call graph: 1 external calls (vec!).

fn from(value: &FileSystemPermissions) -> Self

Purpose: Converts protocol-level file-system permissions into a restricted runtime sandbox policy. This gives enforcement code the rule set it expects.

Data flow: It receives file-system permissions, copies entries into a restricted policy, copies the glob depth, and returns the policy.

Call relations: This conversion is used when permission overlays or serialized permission data must become sandbox rules.

Call graph: calls 1 internal fn (restricted).

fn plaintext_agent_message_content(content: &[AgentMessageInputContent]) -> Option<String>

Purpose: Returns readable text from an agent message only if every part is plain text. If any part is encrypted, it refuses to pretend the whole message is readable.

Data flow: It receives content parts, collects text parts, stops with none if encrypted content appears, joins text with newlines, and returns none for empty text.

Call relations: Transcript, thread-section, and visible-message builders call it when deciding what can safely be shown as local plaintext.

Call graph: called by 3 (collect_guardian_transcript_entries, build_current_thread_section, push_visible_message); 2 external calls (with_capacity, len).

fn is_user_message(&self) -> bool

Purpose: Checks whether a response item is a normal message from the user. This is a quick filter for conversation processing.

Data flow: It reads the item variant and role field, returning true only for a message whose role is exactly user.

Call relations: Callers use it when separating user input messages from tool calls, assistant messages, and other response items.

Call graph: 1 external calls (matches!).

fn turn_id(&self) -> Option<&str>

Purpose: Reads the non-empty turn ID attached to a response item, if it has one. A turn ID links items back to a conversation turn.

Data flow: It asks for the item metadata, reads the optional turn ID, filters out empty strings, and returns a borrowed string if present.

Call relations: stamp_turn_id_if_missing calls it before deciding whether a new turn ID needs to be added.

Call graph: calls 1 internal fn (metadata); called by 1 (stamp_turn_id_if_missing).

fn stamp_turn_id_if_missing(&mut self, turn_id: &str)

Purpose: Adds a turn ID to an item only when the item can carry metadata and does not already have a non-empty turn ID. This avoids overwriting existing attribution.

Data flow: It receives a mutable item and a turn ID string, ignores empty IDs or already-stamped items, creates metadata if needed, and stores the turn ID.

Call relations: It uses turn_id and metadata_mut; tests exercise it on messages and compaction triggers.

Call graph: calls 2 internal fn (metadata_mut, turn_id).

fn clear_metadata(&mut self)

Purpose: Removes response metadata before sending an item to a provider that does not accept it. This keeps provider requests clean.

Data flow: It receives a mutable item, finds its metadata slot if the variant has one, and sets that slot to none.

Call relations: Provider-facing cleanup code calls it as a final sanitation step before serialization.

Call graph: calls 1 internal fn (metadata_mut).

fn metadata(&self) -> Option<&ResponseItemMetadata>

Purpose: Provides read-only access to metadata for every response-item variant that supports it. It hides the repetitive matching over many enum cases.

Data flow: It receives a response item, matches variants with metadata fields, and returns a reference to metadata if present.

Call relations: turn_id calls it so turn-ID lookup works uniformly across message, tool, search, and compaction items.

Call graph: called by 1 (turn_id).

fn metadata_mut(&mut self) -> Option<&mut Option<ResponseItemMetadata>>

Purpose: Provides mutable access to the metadata slot for response-item variants that support it. This lets code stamp or clear metadata without duplicating variant matches.

Data flow: It receives a mutable response item, returns a mutable reference to the optional metadata field when available, or none for unsupported variants.

Call relations: stamp_turn_id_if_missing and clear_metadata call it when they need to change metadata.

Call graph: called by 2 (clear_metadata, stamp_turn_id_if_missing).

fn default() -> Self

Purpose: Creates the default base instructions sent to the model. These are the system-level instructions that shape model behavior in a thread.

Data flow: It takes no input, copies the bundled default markdown prompt into a string, and returns a BaseInstructions object.

Call relations: Thread creation, persistence tests, and default configuration paths call it whenever no custom base instructions are supplied.

Call graph: called by 12 (get_conversation_summary_by_thread_id_reads_pathless_store_thread, thread_delete_with_non_local_thread_store_does_not_create_local_persistence, seed_pathless_store_thread, thread_unarchive_preserves_pathless_store_metadata, default, attach_thread_persistence, shutdown_complete_does_not_append_to_thread_store_after_shutdown, find_locates_rollout_file_written_by_recorder, persist_reports_filesystem_error_and_retries_buffered_items, recorder_materializes_on_flush_with_pending_items (+2 more)).

fn format_allow_prefixes(prefixes: Vec<Vec<String>>) -> Option<String>

Purpose: Turns allowed command prefixes into a short readable bullet list. It prevents giant policy lists from flooding messages by sorting and truncating them.

Data flow: It receives command-prefix token lists, sorts them by simplicity, renders up to a fixed count, trims the byte size on a character boundary, and adds a truncation marker if needed.

Call relations: Execution-policy amendment and approval-text code call it to show users which command prefixes are allowed.

Call graph: called by 5 (record_execpolicy_amendment_message, approved_command_prefixes_text, format_allow_prefixes_limits_output, render_command_prefix_list_limits_output_to_max_prefixes, render_command_prefix_list_sorts_by_len_then_total_len_then_alphabetical); 1 external calls (format!).

fn prefix_combined_str_len(prefix: &[String]) -> usize

Purpose: Calculates the total text length of all tokens in a command prefix. This helps sort shorter, simpler prefixes before longer ones.

Data flow: It receives a prefix token slice, sums each token’s string length, and returns the total.

Call relations: format_allow_prefixes uses it as one of the sorting tie-breakers before rendering policy text.

fn render_command_prefix(prefix: &[String]) -> String

Purpose: Formats one command prefix as a JSON-like list of quoted tokens. Quoting makes spaces and special characters clear to humans.

Data flow: It receives command tokens, serializes each token as a JSON string when possible, joins them with commas, and wraps them in brackets.

Call relations: format_allow_prefixes calls it for each prefix that will appear in the final bullet list.

Call graph: 1 external calls (format!).

fn should_serialize_reasoning_content(content: &Option<Vec<ReasoningItemContent>>) -> bool

Purpose: Decides whether optional reasoning content should be skipped during serialization. The rule avoids serializing some reasoning-text content while preserving other cases.

Data flow: It receives optional reasoning content, checks whether any item is explicit reasoning text, and returns the skip decision used by Serde.

Call relations: Serde uses it through the ResponseItem::Reasoning field annotation when writing response items.

fn local_image_error_placeholder(
    path: &std::path::Path,
    error: impl std::fmt::Display,
) -> ContentItem

Purpose: Creates a text message explaining that Codex could not read or process a local image. This gives the model and user a visible explanation instead of silently dropping the image.

Data flow: It receives an image path and an error, formats them into a human-readable string, and returns that string as an input-text content item.

Call relations: Local image preparation calls it for read, encode, decode, size, and other processing failures.

Call graph: 1 external calls (format!).

fn image_open_tag_text() -> String

Purpose: Returns the generic opening image tag text. This tag is used in plain text around image references.

Data flow: It takes no input and returns the constant <image> as an owned string.

Call relations: UI and parsing tests use it when checking how unnamed image labels are represented.

Call graph: called by 1 (skips_unnamed_image_label_text).

fn image_close_tag_text() -> String

Purpose: Returns the generic closing image tag text. This gives callers one source for the closing image marker.

Data flow: It takes no input and returns the constant </image> as an owned string.

Call relations: Image parsing and tests use it alongside local image tagging helpers.

fn local_image_label_text(label_number: usize) -> String

Purpose: Builds the visible label for a numbered local image, such as [Image #2]. Labels let text refer to attached local images clearly.

Data flow: It receives a label number, formats it into the standard label string, and returns it.

Call relations: Local image tag builders, attachment relabeling, and edit-handling code call it to keep image numbering consistent.

Call graph: called by 12 (local_image_open_tag_text_with_path, attach_image, relabel_local_images, apply_external_edit_drops_missing_attachments, apply_external_edit_limits_duplicates_to_occurrences, apply_external_edit_rebuilds_text_and_attachments, apply_external_edit_renumbers_image_placeholders, clear_for_ctrl_c_preserves_image_draft_state, deleting_reordered_image_one_renumbers_text_in_place, set_text_content_reattaches_images_without_placeholder_metadata (+2 more)); 1 external calls (format!).

fn local_image_open_tag_text_with_path(label_number: usize, path: &std::path::Path) -> String

Purpose: Builds an opening tag for a local image that includes both its numbered label and file path. This preserves where the image came from.

Data flow: It receives a label number and path, creates the label, formats the path for display, and returns the full opening tag string.

Call relations: local_image_content_items calls it when wrapping a local image with text markers.

Call graph: calls 1 internal fn (local_image_label_text); called by 1 (local_image_content_items); 2 external calls (display, format!).

fn is_local_image_open_tag_text(text: &str) -> bool

Purpose: Checks whether a text string looks like a local-image opening tag. This helps parse previously constructed user messages.

Data flow: It receives text, checks for the local-image prefix and suffix, and returns a boolean.

Call relations: User-message parsing calls it to recognize image attachment markers embedded in text.

Call graph: called by 1 (parse_user_message).

fn is_local_image_close_tag_text(text: &str) -> bool

Purpose: Checks whether a text string is the local-image closing tag. Currently local image closing uses the same closing marker as generic images.

Data flow: It receives text and delegates to the generic image-close check.

Call relations: User-message parsing calls it while matching local image tag pairs.

Call graph: calls 1 internal fn (is_image_close_tag_text); called by 1 (parse_user_message).

fn is_image_open_tag_text(text: &str) -> bool

Purpose: Checks whether text is exactly the generic image opening tag. This is a small parser helper.

Data flow: It receives text, compares it to <image>, and returns true or false.

Call relations: User-message parsing calls it when recognizing image sections.

Call graph: called by 1 (parse_user_message).

fn is_image_close_tag_text(text: &str) -> bool

Purpose: Checks whether text is exactly the generic image closing tag. This is used for both generic and local image closing markers.

Data flow: It receives text, compares it to </image>, and returns a boolean.

Call relations: User-message parsing and is_local_image_close_tag_text call it to recognize image boundaries.

Call graph: called by 2 (parse_user_message, is_local_image_close_tag_text).

fn invalid_image_error_placeholder(
    path: &std::path::Path,
    error: impl std::fmt::Display,
) -> ContentItem

Purpose: Creates a text message saying a local file was found but is not a valid image. This is more specific than a generic read failure.

Data flow: It receives a path and error, formats them into an explanation, and returns an input-text content item.

Call relations: Local image preparation calls it when image decoding says the file data is invalid.

Call graph: 1 external calls (format!).

fn unsupported_image_error_placeholder(path: &std::path::Path, mime: &str) -> ContentItem

Purpose: Creates a text message saying the local image format is unsupported. This tells the user which MIME type caused the problem.

Data flow: It receives a path and MIME type, formats a clear unsupported-image message, and returns it as input text.

Call relations: Local image preparation calls it when the image loader recognizes a format Codex cannot attach.

Call graph: 1 external calls (format!).

fn local_image_content_items_with_label_number(
    path: &std::path::Path,
    file_bytes: Vec<u8>,
    label_number: Option<usize>,
    detail: ImageDetail,
) -> Vec<ContentItem>

Purpose: Turns local image bytes into prompt content items, with optional labeling. It also converts failures into readable placeholder text.

Data flow: It receives a path, file bytes, optional label number, and requested detail level; it chooses resize or original mode, loads the image for prompting, and returns image content or an error placeholder.

Call relations: User-input conversion calls this when local images should be processed before being sent to the model.

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

fn local_image_content_items(
    path: &std::path::Path,
    image_url: String,
    label_number: Option<usize>,
    detail: ImageDetail,
) -> Vec<ContentItem>

Purpose: Builds the actual content-item sequence for a prepared image URL. With a label, it wraps the image between opening and closing text tags.

Data flow: It receives a path, image data URL, optional label number, and detail setting; it returns text-open, image, and text-close items when labeled, or just the image item when unlabeled.

Call relations: Local image processing and deferred image preparation call it after bytes have been turned into a data URL.

Call graph: calls 1 internal fn (local_image_open_tag_text_with_path); called by 1 (local_image_content_items_with_label_number); 1 external calls (with_capacity).

fn from(item: ResponseInputItem) -> Self

Purpose: Converts input items into full response items. This lets user inputs and tool outputs enter the same conversation-history format used elsewhere.

Data flow: It receives a ResponseInputItem, maps each variant to the matching ResponseItem, fills fields such as metadata and IDs with defaults, and converts MCP tool output into function-call output payloads.

Call relations: Response-building code and tests call it when moving from input-side protocol objects to stored or provider-facing response items.

Call graph: called by 2 (response_item_from_user_input, response_input_message_conversion_preserves_phase).

fn from(items: Vec<UserInput>) -> Self

Purpose: Creates a user message input item from a list of user input parts. It uses normal image processing by default.

Data flow: It receives user input values, calls from_user_input with local-image processing enabled, and returns a message input item.

Call relations: Compaction, image tests, and user-input conversion paths call it as the standard conversion entry.

Call graph: called by 8 (run_compact_task_inner_impl, image_user_input_preserves_requested_detail, local_image_non_image_adds_placeholder, local_image_read_error_adds_placeholder, local_image_unsupported_image_format_adds_placeholder, local_image_user_input_preserves_requested_detail, mixed_remote_and_local_images_share_label_sequence, serializes_image_user_input_without_tags); 1 external calls (from_user_input).

fn from_user_input(
        items: Vec<UserInput>,
        local_image_preparation: LocalImagePreparation,
    ) -> Self

Purpose: Converts typed user input into the content items that can be sent to a model. It supports text, remote images, local images, and skips inputs injected later by other code.

Data flow: It receives user inputs plus a choice to process or defer local image preparation, reads local files when needed, labels images in sequence, and returns a user-role message with content items.

Call relations: The From<Vec<UserInput>> implementation and response-building paths call it when preparing a turn’s user message.

Call graph: called by 1 (response_item_from_user_input).

fn function_call_output_content_items_to_text(
    content_items: &[FunctionCallOutputContentItem],
) -> Option<String>

Purpose: Extracts a plain-text preview from structured tool output. It intentionally drops images and encrypted content because those cannot be faithfully represented as simple text.

Data flow: It receives structured output items, collects non-blank input-text values, joins them with newlines, and returns none if there is no text.

Call relations: Logging, legacy output paths, call handlers, and FunctionCallOutputBody::to_text call it when they need a human-readable string.

Call graph: called by 9 (into_text, log_preview, handle_call, handle_call, handle_call, expect_text_output, to_text, function_call_output_content_items_to_text_ignores_blank_text_and_images, function_call_output_content_items_to_text_joins_text_segments); 1 external calls (iter).

fn from(item: crate::dynamic_tools::DynamicToolCallOutputContentItem) -> Self

Purpose: Converts dynamic-tool output items into the protocol’s function-call output item format. This lets dynamically defined tools reuse the same response shape.

Data flow: It receives a dynamic text or image item, maps text directly, maps images to input-image items, and applies the default image detail.

Call relations: Dynamic tool code uses this conversion before packaging tool results for the model.

fn to_text(&self) -> Option<String>

Purpose: Best-effort conversion of a tool output body into plain text. It is useful for logs and old interfaces that cannot display structured output.

Data flow: It receives either text or structured items; text is cloned directly, while structured items are passed through the lossy text extractor.

Call relations: Callers needing previews call it, and it delegates structured extraction to function_call_output_content_items_to_text.

Call graph: calls 1 internal fn (function_call_output_content_items_to_text).

fn default() -> Self

Purpose: Creates an empty text tool-output body. This gives the payload a harmless default value.

Data flow: It takes no input and returns the text variant containing an empty string.

Call relations: Default construction for FunctionCallOutputPayload uses it when no body has been supplied.

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

fn from_text(content: String) -> Self

Purpose: Builds a function-call output payload from plain text. This is the common path for simple tool results.

Data flow: It receives a string, stores it as the text body, leaves success unset, and returns the payload.

Call relations: Dynamic tool calls, response item conversion, guardian history seeding, and tests call it for string-only outputs.

Call graph: called by 9 (dynamic_tool_call_round_trip_sends_text_content_items_to_model, custom_tool_call_output, record_items_truncates_custom_tool_call_output_content, ensure_call_outputs_present, seed_guardian_parent_history, external_context_pollution_items_exclude_local_tool_calls, to_response_item, azure_responses_request_includes_store_and_reasoning_ids, serializes_success_as_plain_string); 1 external calls (Text).

fn from_content_items(content_items: Vec<FunctionCallOutputContentItem>) -> Self

Purpose: Builds a function-call output payload from structured content items such as text, images, or encrypted content.

Data flow: It receives a list of content items, stores them as the body, leaves success unset, and returns the payload.

Call relations: Image-output handling, encrypted output handling, and size-estimation tests call it when output is not just text.

Call graph: called by 12 (encrypted_function_output_uses_plaintext_byte_estimate, image_data_url_payload_does_not_dominate_custom_tool_call_output_estimate, image_data_url_payload_does_not_dominate_function_call_output_estimate, non_base64_image_urls_are_unchanged, non_image_base64_data_url_is_unchanged, original_detail_images_are_capped_at_max_patch_count, original_detail_images_scale_with_dimensions, original_detail_webp_images_scale_with_dimensions, image_output, to_response_item (+2 more)); 1 external calls (ContentItems).

fn text_content(&self) -> Option<&str>

Purpose: Returns the text content if this payload is plain text. It avoids pretending structured output is a string.

Data flow: It reads the body and returns a string reference for the text variant, or none for content items.

Call relations: Callers use it when they specifically need borrowed plain text from a tool result.

fn text_content_mut(&mut self) -> Option<&mut String>

Purpose: Returns mutable access to plain text output when the payload is text. This allows in-place edits only for text bodies.

Data flow: It reads the mutable body and returns a mutable string reference for the text variant, or none for structured content.

Call relations: Post-processing code can use it to alter simple text outputs without touching structured item payloads.

fn content_items(&self) -> Option<&[FunctionCallOutputContentItem]>

Purpose: Returns structured output items if this payload contains them. This is how image outputs and other item arrays are inspected.

Data flow: It reads the body and returns a slice of content items for the structured variant, or none for plain text.

Call relations: Image URL extraction code calls it when looking for images inside tool outputs.

Call graph: called by 1 (output_image_urls).

fn content_items_mut(&mut self) -> Option<&mut Vec<FunctionCallOutputContentItem>>

Purpose: Returns mutable access to structured content items when the payload uses that form. It avoids modifying plain text as if it were a list.

Data flow: It reads the mutable body and returns the item vector for structured output, or none for text output.

Call relations: Post-processing code can use it to rewrite or filter structured tool output items.

fn serialize(&self, serializer: S) -> Result<S::Ok, S::Error>

Purpose: Writes a tool-output payload to JSON using the provider’s expected shape: either a string or an array. Internal success metadata is not written.

Data flow: It reads the payload body, serializes text as a JSON string or content items as a JSON array, and returns the serializer result.

Call relations: Serde calls it when response input or response items containing tool output are sent or stored.

Call graph: 1 external calls (serialize_str).

fn deserialize(deserializer: D) -> Result<Self, D::Error>

Purpose: Reads a tool-output payload from JSON that may be either a string or an array of content items. It restores only the wire body, not internal success metadata.

Data flow: It deserializes the incoming value as a FunctionCallOutputBody, wraps it in a payload, sets success to none, and returns it.

Call relations: Serde calls it when tool output comes back from stored history or protocol JSON.

Call graph: 1 external calls (deserialize).

fn from_result(result: Result<Self, String>) -> Self

Purpose: Turns a Rust Result from an MCP tool call into a CallToolResult. Errors become structured error results instead of panics.

Data flow: It receives either a successful tool result or an error string; successes pass through, and errors are converted with from_error_text.

Call relations: MCP tool-call handling can use it to normalize fallible tool execution into protocol output.

Call graph: 1 external calls (from_error_text).

fn from_error_text(text: String) -> Self

Purpose: Creates an MCP tool result that clearly represents an error message. This gives downstream code a consistent error shape.

Data flow: It receives error text, wraps it as a JSON text content item, marks is_error true, and returns the result.

Call relations: from_result calls it when a tool execution returns an error string.

Call graph: 1 external calls (vec!).

fn success(&self) -> bool

Purpose: Reports whether an MCP tool result should be treated as successful. Only an explicit is_error: true counts as failure.

Data flow: It reads the optional error flag and returns false only when that flag is true.

Call relations: as_function_call_output_payload calls it to attach internal success metadata to converted tool output.

Call graph: called by 1 (as_function_call_output_payload).

fn as_function_call_output_payload(&self) -> FunctionCallOutputPayload

Purpose: Converts an MCP tool result into the function-call output payload shape sent back to the model. It preserves images as structured items when possible.

Data flow: It first prefers non-null structured content as serialized text, otherwise serializes raw content, tries to convert MCP text/image content into structured output items, records success, and returns a payload.

Call relations: into_function_call_output_payload delegates to it, and response-item conversion uses that path for MCP tool outputs.

Call graph: calls 2 internal fn (success, convert_mcp_content_to_items); called by 1 (into_function_call_output_payload); 3 external calls (ContentItems, Text, to_string).

fn into_function_call_output_payload(self) -> FunctionCallOutputPayload

Purpose: Consumes an MCP tool result and converts it into a function-call output payload. It is the ownership-taking wrapper for the borrowed conversion.

Data flow: It receives the result by value, calls as_function_call_output_payload, and returns the converted payload.

Call relations: Conversion from ResponseInputItem::McpToolCallOutput calls it before storing the result as a normal function-call output.

Call graph: calls 1 internal fn (as_function_call_output_payload).

fn convert_mcp_content_to_items(
    contents: &[serde_json::Value],
) -> Option<Vec<FunctionCallOutputContentItem>>

Purpose: Tries to convert MCP content JSON into structured function-call output items. It only switches to structured output when at least one image is present.

Data flow: It receives JSON content values, parses each as MCP text or image, builds text or image items, creates data URLs for image bytes when needed, applies image detail metadata, and returns none if no image was seen.

Call relations: CallToolResult::as_function_call_output_payload calls it so multimodal MCP results can reach the model as images instead of opaque JSON text.

Call graph: called by 3 (as_function_call_output_payload, convert_mcp_content_to_items_builds_data_urls_when_missing_prefix, convert_mcp_content_to_items_preserves_data_urls); 4 external calls (len, with_capacity, format!, to_string).

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

Purpose: Formats a function-call output payload for logging, display, or simple string checks. Text is shown directly; structured items are shown as JSON.

Data flow: It receives a formatter, writes the text body as-is or serializes content items to JSON and writes that string.

Call relations: Rust’s display formatting calls it when code treats a payload like a printable string.

Call graph: 2 external calls (write_str, to_string).

fn plaintext_agent_message_content_rejects_mixed_encrypted_content()

Purpose: Checks that plaintext extraction refuses messages containing encrypted parts. This protects against accidentally showing incomplete or private content.

Data flow: It builds mixed plaintext and encrypted content, calls the extractor, and asserts that the result is none.

Call relations: The test directly exercises plaintext_agent_message_content.

Call graph: 2 external calls (assert_eq!, vec!).

fn response_input_message_conversion_preserves_phase()

Purpose: Checks that converting an input message into a response item keeps the message phase. This preserves commentary versus final-answer information.

Data flow: It builds an assistant input message with a commentary phase, converts it, and compares the full response item.

Call relations: The test calls ResponseItem::from for the message conversion path.

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

fn response_item_metadata_round_trips_and_stamps_turn_ids() -> Result<()>

Purpose: Checks that response-item metadata survives JSON round trips and that missing turn IDs are stamped correctly. This guards conversation-turn attribution.

Data flow: It serializes and deserializes metadata-bearing items, tries stamping existing, empty, missing, and unsupported cases, and asserts the expected turn IDs.

Call relations: The test exercises turn_id, stamp_turn_id_if_missing, and metadata serialization behavior.

Call graph: 6 external calls (assert_eq!, response_item_metadata, response_item_with_metadata, from_value, json!, to_value).

fn response_item_with_metadata(metadata: Option<ResponseItemMetadata>) -> ResponseItem

Purpose: Builds a small user message response item for metadata tests. It keeps those tests readable.

Data flow: It receives optional metadata, inserts it into a fixed user message with one text content item, and returns the item.

Call relations: The metadata round-trip test calls this helper to create test items.

Call graph: 1 external calls (vec!).

fn response_item_metadata(turn_id: &str) -> ResponseItemMetadata

Purpose: Builds metadata containing a chosen turn ID for tests. This avoids repeating the struct construction.

Data flow: It receives a turn ID string, copies it into metadata, and returns the metadata object.

Call relations: The response-item metadata test calls this helper for expected and input values.

fn image_detail_roundtrips_all_wire_values() -> Result<()>

Purpose: Checks that image detail settings serialize and deserialize with the expected JSON names. This protects compatibility with provider wire values.

Data flow: It parses and writes image detail values, parses an input-image content item, and asserts the expected Rust values.

Call relations: The test covers ImageDetail and ContentItem::InputImage serialization behavior.

Call graph: 3 external calls (assert_eq!, from_value, json!).

fn sandbox_permissions_helpers_match_documented_semantics()

Purpose: Checks that sandbox-permission helper methods return the documented booleans. This protects command-permission decisions.

Data flow: It runs all sandbox permission variants through the helper methods and compares them with expected truth values.

Call relations: The test directly exercises the three SandboxPermissions helper methods.

Call graph: 1 external calls (assert_eq!).

fn convert_mcp_content_to_items_preserves_data_urls()

Purpose: Checks that MCP image content already using a data URL is not wrapped again. This avoids corrupting image output.

Data flow: It builds image JSON with a data URL, converts it, and asserts the image URL is unchanged.

Call relations: The test directly calls convert_mcp_content_to_items.

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

fn response_item_parses_image_generation_call()

Purpose: Checks that image-generation response items parse when a revised prompt is present. This keeps provider image-generation events usable.

Data flow: It deserializes example JSON and compares it with the expected ImageGenerationCall item.

Call relations: The test exercises ResponseItem deserialization.

Call graph: 2 external calls (assert_eq!, json!).

fn response_item_parses_image_generation_call_without_revised_prompt()

Purpose: Checks that image-generation response items also parse when the revised prompt is omitted. This supports partial provider payloads.

Data flow: It deserializes JSON without revised_prompt and asserts the field becomes none.

Call relations: The test exercises optional-field behavior in ResponseItem deserialization.

Call graph: 2 external calls (assert_eq!, json!).

fn additional_permission_profile_is_empty_when_all_fields_are_none()

Purpose: Checks that a default additional-permission profile counts as empty. This guards overlay cleanup.

Data flow: It creates the default profile, calls is_empty, and asserts true.

Call relations: The test directly exercises AdditionalPermissionProfile::is_empty.

Call graph: 1 external calls (assert_eq!).

fn additional_permission_profile_is_not_empty_when_field_is_present_but_nested_empty()

Purpose: Checks that a present permission section counts as meaningful even if its nested value says little. This preserves explicit user intent.

Data flow: It creates a profile with a network section but no enabled value, calls is_empty, and asserts false.

Call relations: The test directly exercises AdditionalPermissionProfile::is_empty.

Call graph: 1 external calls (assert_eq!).

fn permission_profile_round_trip_preserves_glob_scan_max_depth()

Purpose: Checks that permission profiles preserve glob scan depth through runtime conversion. This protects deny rules that depend on controlled glob scanning.

Data flow: It creates a restricted sandbox policy with a deny glob and depth, converts it to a profile, and compares the extracted policy with the original.

Call relations: The test calls PermissionProfile::from_runtime_permissions and file_system_sandbox_policy.

Call graph: calls 2 internal fn (from_runtime_permissions, restricted); 2 external calls (assert_eq!, vec!).

fn permission_profile_deserializes_legacy_rollout_shape() -> Result<()>

Purpose: Checks that old rollout JSON for permission profiles still loads correctly. This protects stored conversation history.

Data flow: It deserializes legacy-shaped JSON with network and file-system fields and compares it with the expected managed profile.

Call relations: The test exercises custom PermissionProfile::deserialize legacy handling.

Call graph: 3 external calls (assert_eq!, from_value, json!).

fn permission_profile_presets_match_legacy_defaults()

Purpose: Checks that built-in read-only and workspace-write profiles match legacy sandbox defaults. This prevents silent permission behavior changes.

Data flow: It creates each modern preset and compares it with conversion from the matching legacy policy.

Call relations: The test calls PermissionProfile::read_only, workspace_write, and legacy conversion.

Call graph: 1 external calls (assert_eq!).

fn permission_profile_round_trip_preserves_disabled_sandbox() -> Result<()>

Purpose: Checks that full-access legacy sandbox policy becomes and remains a disabled permission profile. This avoids accidentally re-sandboxing full-access sessions.

Data flow: It converts danger-full-access to a profile, converts back to legacy and runtime permissions, and asserts all forms match full access.

Call relations: The test calls PermissionProfile::from_legacy_sandbox_policy and to_legacy_sandbox_policy.

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

fn disabled_permission_profile_ignores_runtime_network_policy()

Purpose: Checks that disabled enforcement wins over a restricted network policy. If there is no sandbox, network is treated as enabled.

Data flow: It builds a profile from disabled enforcement plus unrestricted files and restricted network, then asserts the profile is disabled.

Call relations: The test exercises PermissionProfile::from_runtime_permissions_with_enforcement.

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

fn permission_profile_from_runtime_permissions_preserves_external_sandbox()

Purpose: Checks that an external filesystem sandbox remains external in the profile model. This respects callers that enforce isolation outside Codex.

Data flow: It converts an external sandbox policy into a profile and compares both normal and explicit-enforcement conversion results.

Call relations: The test calls PermissionProfile::from_runtime_permissions and the explicit enforcement converter.

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

fn permission_profile_from_runtime_permissions_preserves_unrestricted_managed_network()

Purpose: Checks that unrestricted managed filesystem access with restricted network is not misrepresented as an external sandbox. This preserves split file/network meaning.

Data flow: It builds a profile from unrestricted filesystem, restricted network, and external enforcement input, then asserts the result is managed and runtime permissions round-trip.

Call relations: The test exercises from_runtime_permissions_with_enforcement and to_runtime_permissions.

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

fn permission_profile_round_trip_preserves_external_sandbox() -> Result<()>

Purpose: Checks that legacy external-sandbox policies round-trip through permission profiles. This preserves compatibility for externally enforced sessions.

Data flow: It converts a legacy external sandbox to a profile, converts back to legacy and runtime permissions, and asserts all expected forms.

Call relations: The test calls PermissionProfile::from_legacy_sandbox_policy, to_legacy_sandbox_policy, and to_runtime_permissions.

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

fn file_system_permissions_with_glob_scan_depth_uses_canonical_json() -> Result<()>

Purpose: Checks that permissions with glob scan depth serialize in the new canonical shape, not the old read/write shape. The old shape cannot express that depth.

Data flow: It builds permissions with a path entry and non-zero depth, serializes them to JSON, checks which fields appear, and deserializes back.

Call relations: The test exercises FileSystemPermissions::serialize and deserialize.

Call graph: calls 1 internal fn (try_from); 7 external calls (new, from, assert!, assert_eq!, cfg!, to_value, vec!).

fn file_system_permissions_rejects_zero_glob_scan_depth()

Purpose: Checks that zero is rejected for glob scan depth. A non-zero type is used because zero would be meaningless for the limit.

Data flow: It tries to deserialize JSON with depth zero and expects an error.

Call relations: The test exercises Serde deserialization for FileSystemPermissions.

Call graph: 1 external calls (json!).

fn convert_mcp_content_to_items_builds_data_urls_when_missing_prefix()

Purpose: Checks that raw base64 MCP image data is turned into a proper data URL. This makes the image usable by model APIs.

Data flow: It builds image JSON with base64 data and MIME type, converts it, and asserts the generated data URL.

Call relations: The test directly calls convert_mcp_content_to_items.

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

fn convert_mcp_content_to_items_returns_none_without_images()

Purpose: Checks that MCP content with only text stays in the plain serialized path. Structured item output is only needed for images.

Data flow: It builds text-only MCP content, converts it, and asserts the result is none.

Call relations: The test directly calls convert_mcp_content_to_items.

Call graph: 2 external calls (assert_eq!, vec!).

fn function_call_output_content_items_to_text_joins_text_segments()

Purpose: Checks that text segments in structured output are joined while images are ignored. This verifies the intended lossy preview behavior.

Data flow: It creates text-image-text items, converts them to text, and asserts the two text lines are joined.

Call relations: The test directly calls function_call_output_content_items_to_text.

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

fn function_call_output_content_items_to_text_ignores_blank_text_and_images()

Purpose: Checks that blank text, images, and encrypted content do not produce a fake text preview. This avoids misleading logs.

Data flow: It creates only blank or non-text items, converts them, and asserts there is no text result.

Call relations: The test directly calls function_call_output_content_items_to_text.

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

fn function_call_output_body_to_text_returns_plain_text_content()

Purpose: Checks that a text output body converts to that same text. This covers the simple preview path.

Data flow: It builds a text body, calls to_text, and compares the returned string.

Call relations: The test exercises FunctionCallOutputBody::to_text.

Call graph: 2 external calls (assert_eq!, Text).

fn function_call_output_body_to_text_uses_content_item_fallback()

Purpose: Checks that structured output uses the content-item text extractor. This protects preview behavior for mixed text and image results.

Data flow: It builds structured content with text and image, calls to_text, and asserts only the text remains.

Call relations: The test exercises FunctionCallOutputBody::to_text and its helper.

Call graph: 3 external calls (assert_eq!, ContentItems, vec!).

fn function_call_deserializes_optional_namespace()

Purpose: Checks that function-call items can include an optional namespace. This supports namespaced tools such as MCP tools.

Data flow: It deserializes function-call JSON with a namespace and compares it with the expected response item.

Call relations: The test exercises ResponseItem deserialization for function calls.

Call graph: 3 external calls (assert_eq!, from_value, json!).

fn render_command_prefix_list_sorts_by_len_then_total_len_then_alphabetical()

Purpose: Checks that allowed command prefixes are displayed in a stable, simple-first order. This makes approval messages easier to read.

Data flow: It builds unsorted prefixes, formats them, and compares the exact bullet-list order.

Call relations: The test calls format_allow_prefixes, which uses the prefix length helpers.

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

fn render_command_prefix_list_limits_output_to_max_prefixes()

Purpose: Checks that only the maximum number of command prefixes is rendered and that truncation is marked. This prevents huge messages.

Data flow: It creates more prefixes than the limit, formats them, and checks the truncation marker and line count.

Call relations: The test calls format_allow_prefixes.

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

fn format_allow_prefixes_limits_output()

Purpose: Checks that rendered command-prefix text stays under the byte budget plus truncation marker. This protects prompts and UI from oversized policy text.

Data flow: It builds many long allowed prefixes through an execution policy, formats them, and asserts the output length bound.

Call relations: The test calls format_allow_prefixes with prefixes obtained from codex_execpolicy.

Call graph: calls 1 internal fn (format_allow_prefixes); 3 external calls (assert!, empty, format!).

fn serializes_success_as_plain_string() -> Result<()>

Purpose: Checks that successful plain text tool output serializes as a JSON string. This matches the provider wire format.

Data flow: It builds a function-call output item from text, serializes it, parses the JSON, and asserts output is the plain string.

Call relations: The test calls FunctionCallOutputPayload::from_text and exercises custom serialization.

Call graph: calls 1 internal fn (from_text); 3 external calls (assert_eq!, from_str, to_string).

fn serializes_failure_as_string() -> Result<()>

Purpose: Checks that failed plain text tool output still serializes as a JSON string. The internal success flag should not change the wire body shape.

Data flow: It builds a payload with text and success: false, serializes it, and asserts the JSON output field is the text.

Call relations: The test exercises FunctionCallOutputPayload::serialize.

Call graph: 4 external calls (assert_eq!, Text, from_str, to_string).

fn serializes_image_outputs_as_array() -> Result<()>

Purpose: Checks that MCP results containing images serialize as an array of structured content items. This lets the model receive images, not only JSON text.

Data flow: It builds an MCP result with caption and image, converts it to a payload, checks content items and success, serializes it, and asserts output is an array.

Call relations: The test exercises CallToolResult::into_function_call_output_payload, content_items, and payload serialization.

Call graph: 6 external calls (assert!, assert_eq!, panic!, from_str, to_string, vec!).

fn serializes_custom_tool_image_outputs_as_array() -> Result<()>

Purpose: Checks that custom tool outputs with images also serialize as structured arrays. This keeps custom tools consistent with function-call outputs.

Data flow: It builds a custom tool output payload from image items, serializes it, and asserts the output field is an array.

Call relations: The test calls FunctionCallOutputPayload::from_content_items.

Call graph: calls 1 internal fn (from_content_items); 4 external calls (assert!, from_str, to_string, vec!).

fn serializes_encrypted_function_output_content_as_array() -> Result<()>

Purpose: Checks that encrypted function output content serializes as a structured array item. This preserves opaque encrypted data without flattening it to text.

Data flow: It builds encrypted content items, serializes the response input item to JSON, and compares the exact JSON structure.

Call relations: The test calls FunctionCallOutputPayload::from_content_items and custom serialization.

Call graph: calls 1 internal fn (from_content_items); 3 external calls (assert_eq!, to_value, vec!).

fn preserves_existing_image_data_urls() -> Result<()>

Purpose: Checks that MCP image data already in data-URL form is preserved through payload conversion. This prevents double-prefixing.

Data flow: It builds an MCP image result with a data URL, converts it, extracts content items, and compares the preserved URL.

Call relations: The test exercises CallToolResult::into_function_call_output_payload and convert_mcp_content_to_items indirectly.

Call graph: 3 external calls (assert_eq!, panic!, vec!).

fn preserves_original_detail_metadata_on_mcp_images() -> Result<()>

Purpose: Checks that MCP image metadata requesting original detail is preserved. This keeps image quality choices from being lost.

Data flow: It builds an MCP image with codex/imageDetail set to original, converts it, and asserts the resulting image detail.

Call relations: The test exercises image metadata parsing inside convert_mcp_content_to_items.

Call graph: 3 external calls (assert_eq!, panic!, vec!).

fn preserves_standard_detail_metadata_on_mcp_images() -> Result<()>

Purpose: Checks that standard image detail metadata such as high is preserved for MCP images. This guards expected quality settings.

Data flow: It builds an MCP image with detail metadata, converts it, and asserts the resulting structured image item.

Call relations: The test exercises image metadata parsing inside convert_mcp_content_to_items.

Call graph: 3 external calls (assert_eq!, panic!, vec!).

fn deserializes_array_payload_into_items() -> Result<()>

Purpose: Checks that a JSON array output payload deserializes into structured content items and serializes back the same way. This protects multimodal tool output storage.

Data flow: It parses an array with text and image items, checks the payload body and success flag, then compares serialization with the expected items.

Call relations: The test exercises FunctionCallOutputPayload::deserialize and serialize.

Call graph: 3 external calls (assert_eq!, from_str, vec!).

fn deserializes_encrypted_array_payload_into_items() -> Result<()>

Purpose: Checks that encrypted output arrays deserialize into structured content items. This keeps encrypted payloads round-trippable.

Data flow: It parses an encrypted-content array, checks the payload body and success flag, and verifies serialization returns the array.

Call relations: The test exercises FunctionCallOutputPayload::deserialize and serialize.

Call graph: 3 external calls (assert_eq!, from_str, vec!).

fn deserializes_compaction_alias() -> Result<()>

Purpose: Checks that the old compaction_summary type name still parses as the current compaction item. This keeps older stored data readable.

Data flow: It deserializes alias JSON and compares the resulting response item.

Call relations: The test exercises ResponseItem deserialization alias behavior.

Call graph: 2 external calls (assert_eq!, from_str).

fn deserializes_context_compaction() -> Result<()>

Purpose: Checks that context compaction items deserialize with optional encrypted content. This supports compacted conversation context records.

Data flow: It parses context-compaction JSON and compares the resulting response item.

Call relations: The test exercises ResponseItem deserialization.

Call graph: 2 external calls (assert_eq!, from_str).

fn serializes_compaction_trigger_without_payload() -> Result<()>

Purpose: Checks that a compaction trigger with no metadata serializes as just its type. This keeps the wire payload minimal.

Data flow: It creates a compaction trigger, serializes it to JSON, and compares the exact object.

Call relations: The test exercises ResponseItem serialization.

Call graph: 1 external calls (assert_eq!).

fn serializes_stamped_compaction_trigger_metadata() -> Result<()>

Purpose: Checks that turn metadata can be stamped onto compaction triggers and serialized. This keeps compaction events attributable to a turn.

Data flow: It stamps a turn ID on a trigger, serializes it, and compares the expected metadata JSON.

Call relations: The test exercises ResponseItem::stamp_turn_id_if_missing and serialization.

Call graph: 1 external calls (assert_eq!).

fn deserializes_compaction_trigger_without_payload() -> Result<()>

Purpose: Checks that a bare compaction trigger JSON object can be read. This supports compact trigger events with no extra fields.

Data flow: It deserializes trigger JSON and compares the resulting response item.

Call relations: The test exercises ResponseItem deserialization.

Call graph: 2 external calls (assert_eq!, from_str).

fn deserializes_legacy_ghost_snapshot_as_other() -> Result<()>

Purpose: Checks that an old unknown ghost-snapshot item is safely parsed as Other. This prevents old data from breaking readers.

Data flow: It deserializes legacy JSON with an unknown type and asserts the result is ResponseItem::Other.

Call relations: The test exercises the catch-all ResponseItem deserialization branch.

Call graph: 2 external calls (assert_eq!, from_str).

fn roundtrips_web_search_call_actions() -> Result<()>

Purpose: Checks parsing and serialization of web-search call actions. This covers search, open-page, find-in-page, and partial events.

Data flow: It loops over example JSON cases, deserializes each, compares expected fields, serializes back, and accounts for skipped ID fields.

Call relations: The test exercises ResponseItem::WebSearchCall and WebSearchAction serialization behavior.

Call graph: 4 external calls (assert_eq!, from_str, to_value, vec!).

fn serializes_image_user_input_without_tags() -> Result<()>

Purpose: Checks that remote image user input becomes an image content item without local-image tags. Remote images do not need local file labels.

Data flow: It converts a remote image user input and asserts the resulting message content contains only the image item.

Call relations: The test calls ResponseInputItem::from.

Call graph: calls 1 internal fn (from); 3 external calls (assert_eq!, panic!, vec!).

fn image_user_input_preserves_requested_detail() -> Result<()>

Purpose: Checks that remote image input preserves the requested detail level. This keeps user image-quality intent.

Data flow: It converts a remote image with original detail and asserts the resulting content item has original detail.

Call relations: The test calls ResponseInputItem::from.

Call graph: calls 1 internal fn (from); 3 external calls (assert_eq!, panic!, vec!).

fn tool_search_call_roundtrips() -> Result<()>

Purpose: Checks that tool-search call items deserialize and serialize with their arguments intact. This supports tool discovery flows.

Data flow: It parses a tool-search call JSON object, compares the response item, serializes it, and compares JSON.

Call relations: The test exercises ResponseItem::ToolSearchCall serialization behavior.

Call graph: 2 external calls (assert_eq!, from_str).

fn tool_search_output_roundtrips() -> Result<()>

Purpose: Checks that tool-search output input items convert to response items and serialize correctly. This preserves discovered tool lists.

Data flow: It builds a tool-search output with tool JSON, converts it to a response item, and compares both conversion and serialized input JSON.

Call relations: The test exercises ResponseItem::from for ToolSearchOutput and ResponseInputItem serialization.

Call graph: 2 external calls (assert_eq!, vec!).

fn tool_search_server_items_allow_null_call_id() -> Result<()>

Purpose: Checks that server-side tool-search calls and outputs can have a null call ID. This supports providers that do not supply one.

Data flow: It deserializes call and output JSON with null call IDs and compares the resulting response items.

Call relations: The test exercises optional call-ID handling in ResponseItem deserialization.

Call graph: 2 external calls (assert_eq!, from_str).

fn mixed_remote_and_local_images_share_label_sequence() -> Result<()>

Purpose: Checks that remote and local images share one numbering sequence. This makes labels match the order users supplied images.

Data flow: It creates a remote image and a local image file, converts both, and asserts the local image is labeled as the second image.

Call relations: The test calls ResponseInputItem::from and local image tag helpers.

Call graph: calls 1 internal fn (from); 6 external calls (assert!, assert_eq!, panic!, write, tempdir, vec!).

fn local_image_open_tag_preserves_path()

Purpose: Checks that local image opening tags include the path exactly as displayed, even with special characters. This preserves user-visible file identity.

Data flow: It builds a tag for a path containing special characters and compares the exact string.

Call relations: The test directly exercises local_image_open_tag_text_with_path.

Call graph: 1 external calls (assert_eq!).

fn local_image_user_input_preserves_requested_detail() -> Result<()>

Purpose: Checks that local image input preserves requested image detail. This matters when users ask to send the original image.

Data flow: It writes a tiny PNG, converts it as local image input with original detail, and asserts the resulting image item has original detail.

Call relations: The test calls ResponseInputItem::from and local image processing.

Call graph: calls 1 internal fn (from); 5 external calls (assert!, panic!, write, tempdir, vec!).

fn local_image_read_error_adds_placeholder() -> Result<()>

Purpose: Checks that a missing local image becomes a readable placeholder message. This avoids dropping the user’s intended attachment silently.

Data flow: It points to a missing file, converts local image input, and asserts the content is one text item mentioning the path and read issue.

Call relations: The test calls ResponseInputItem::from, which uses local_image_error_placeholder.

Call graph: calls 1 internal fn (from); 5 external calls (assert!, assert_eq!, panic!, tempdir, vec!).

fn local_image_non_image_adds_placeholder() -> Result<()>

Purpose: Checks that a local file with a non-image MIME type becomes an unsupported-image placeholder. This gives a clear explanation to the user.

Data flow: It writes a JSON file, converts it as a local image, and asserts the placeholder mentions the unsupported MIME type and path.

Call relations: The test calls ResponseInputItem::from and local image processing.

Call graph: calls 1 internal fn (from); 6 external calls (assert!, assert_eq!, panic!, write, tempdir, vec!).

fn local_image_unsupported_image_format_adds_placeholder() -> Result<()>

Purpose: Checks that an unsupported image format such as SVG produces a specific placeholder. This gives users a precise failure reason.

Data flow: It writes an SVG file, converts it as local image input, and compares the exact unsupported-format placeholder text.

Call relations: The test calls ResponseInputItem::from, which reaches unsupported_image_error_placeholder through image loading.

Call graph: calls 1 internal fn (from); 6 external calls (assert_eq!, format!, panic!, write, tempdir, vec!).

fn is_team_like(self) -> bool

Purpose: This answers whether a plan should be treated like a team plan. It is useful when different plan names should unlock the same team-style behavior.

Data flow: It starts with one PlanType value. It compares that value against the team-family options, Team and SelfServeBusinessUsageBased. It returns true if the plan belongs to that family, and false otherwise; it does not change any data.

Call relations: Other code can call this when it needs a simple yes-or-no answer instead of repeating the same plan list everywhere. Inside, it uses Rust's matches! check, which is just a compact way to ask whether a value is one of a few listed cases.

Call graph: 1 external calls (matches!).

fn is_business_like(self) -> bool

Purpose: This answers whether a plan should be treated like a business plan. It lets the rest of the system group the regular business plan and its usage-based version together.

Data flow: It receives one PlanType value. It checks whether that value is Business or EnterpriseCbpUsageBased. It returns true for those two cases and false for all others, without modifying anything.

Call relations: Callers use this as a shared rule for business-plan behavior. The function hands the actual comparison to Rust's matches! macro, which keeps the rule short and explicit.

Call graph: 1 external calls (matches!).

fn is_workspace_account(self) -> bool

Purpose: This answers whether a plan represents a workspace-style account rather than an individual account. Workspace plans include team, business, enterprise, and education-style plans.

Data flow: It takes a PlanType value as input. It compares it with the set of plans considered workspace accounts: Team, SelfServeBusinessUsageBased, Business, EnterpriseCbpUsageBased, Enterprise, and Edu. It returns true if the plan is in that set and false otherwise.

Call relations: This is the shared shortcut for any code that needs to decide whether account behavior should follow workspace rules. It uses Rust's matches! macro to keep the full list in one clear place.

Call graph: 1 external calls (matches!).

fn from(plan: KnownPlan) -> Self

Purpose: This converts a known authentication-layer plan into the account protocol's PlanType. It is the bridge between the plan names used during sign-in or authentication and the plan names exposed through account protocol data.

Data flow: It receives a KnownPlan value from the authentication module. It maps each known authentication plan to the matching PlanType value, such as KnownPlan::Free to PlanType::Free or KnownPlan::Enterprise to PlanType::Enterprise. The result is a protocol-friendly PlanType; nothing else is changed.

Call relations: This conversion is used when account information moves out of authentication code and into the account data model defined here. It prevents callers from hand-writing their own mapping and possibly forgetting a plan or choosing the wrong protocol name.

fn usage_based_plan_types_use_expected_wire_names()

Purpose: This test makes sure important plan names turn into the exact JSON text expected by other parts of the system. It especially protects long usage-based plan names, where spelling and underscores must match exactly.

Data flow: The test starts with selected PlanType values and serializes them to JSON strings. It also starts with JSON strings and deserializes them back into PlanType values. It checks that both directions produce the expected result.

Call relations: This test supports the serialization rules declared on PlanType. It uses equality checks to catch accidental changes that would break communication with clients or services expecting names like self_serve_business_usage_based or enterprise_cbp_usage_based.

Call graph: 1 external calls (assert_eq!).

fn plan_family_helpers_group_usage_based_variants_with_existing_plans()

Purpose: This test confirms that the helper methods group newer usage-based plans with the older plan families they behave like. It protects product logic that depends on those families.

Data flow: The test calls is_team_like and is_business_like on several PlanType values. It compares each returned true or false value with the expected grouping. No persistent data is changed.

Call relations: This test directly backs the family-checking helpers on PlanType. It makes sure team-like and business-like rules stay intentional when plan names are added or adjusted.

Call graph: 1 external calls (assert_eq!).

fn workspace_account_helper_includes_usage_based_workspace_plans()

Purpose: This test verifies that all workspace-style plans are recognized as workspace accounts, including usage-based variants. It also checks that an individual plan, Pro, is not treated as a workspace.

Data flow: The test feeds several PlanType values into is_workspace_account. It checks that workspace plans return true and that Pro returns false. The only output is the test pass or failure.

Call relations: This test protects the shared workspace-account rule. If someone later changes is_workspace_account and accidentally drops one of these plans, this test is meant to fail and point out the mistake.

Call graph: 1 external calls (assert_eq!).

fn auth_plan_type_converts_to_account_plan_type()

Purpose: This test checks that authentication plan values become the expected account PlanType values. It also verifies that an unknown authentication plan safely becomes PlanType::Unknown instead of pretending to be a known plan.

Data flow: The test builds authentication-layer plan values, converts them with PlanType::from, and compares the converted result with the expected PlanType. Known plans keep their meaning, while an unknown string becomes Unknown.

Call relations: This test protects the bridge between the authentication module and this account protocol model. It ensures callers can rely on PlanType::from to produce safe, app-facing account plan values.

Call graph: 1 external calls (assert_eq!).

fn new(command: Vec<String>) -> Self

Purpose: Creates a proposed command-policy change from a list of command words. This is used when the system wants to suggest, “commands starting with these words can be allowed in the future.”

Data flow: It receives a list of strings, such as the words that make up the beginning of a command. It stores that list inside an ExecPolicyAmendment. The result is a small object that can be sent as part of an approval request.

Call relations: This is a simple constructor for the approval data model. Other code can use it when preparing an approval request that includes a proposed exec policy amendment, before that request is shown to a user or client.

fn command(&self) -> &[String]

Purpose: Returns the command prefix stored in an ExecPolicyAmendment without giving ownership of it away. Someone would use this to inspect what command prefix is being proposed.

Data flow: It reads the command list already stored in the ExecPolicyAmendment. It does not change anything. It returns a borrowed view of that list so callers can look at it safely.

Call relations: This accessor supports code that needs to read an amendment after it has been created or received. It does not call into other parts of the approval flow; it simply exposes the stored command prefix.

fn from(command: Vec<String>) -> Self

Purpose: Converts a plain list of command words into an ExecPolicyAmendment. This makes it easier to build the amendment from existing command-token data.

Data flow: It receives a vector of strings. It wraps that vector in the ExecPolicyAmendment structure. The output is the same information, now labeled as a proposed policy amendment.

Call relations: This is used through Rust’s standard conversion pattern, so code can turn a Vec<String> into an ExecPolicyAmendment without calling the constructor directly. It sits at the edge of the data model and does not trigger approval behavior by itself.

fn effective_approval_id(&self) -> String

Purpose: Finds the identifier that should be used for this approval decision. If a separate approval ID exists, it uses that; otherwise it falls back to the command’s call ID.

Data flow: It reads the approval_id field and the call_id field from the request. If approval_id has a value, it returns a copy of that value. If not, it returns a copy of call_id. The request itself is not changed.

Call relations: The command approval handlers handle_exec_approval and handle_exec_approval_now call this when they need one reliable ID to track the user’s answer. This matters because normal command approvals and intercepted subcommand approvals identify themselves slightly differently.

Call graph: called by 2 (handle_exec_approval, handle_exec_approval_now).

fn effective_available_decisions(&self) -> Vec<ReviewDecision>

Purpose: Figures out which approval choices should be shown for a command request. It uses the explicit choices if they were sent, or reconstructs the older default choices when that newer field is missing.

Data flow: It reads available_decisions first. If that field is present, it returns a copy of those choices. If it is missing, it reads the network context, proposed policy amendments, and additional permission request, then asks the default decision logic to build the choice list.

Call relations: handle_exec_approval_now calls this while preparing an approval prompt. When newer senders provide exact choices, this function preserves them. When older senders do not, it hands off to default_available_decisions so clients still get sensible approve-or-abort options.

Call graph: called by 1 (handle_exec_approval_now); 1 external calls (default_available_decisions).

fn default_available_decisions(
        network_approval_context: Option<&NetworkApprovalContext>,
        proposed_execpolicy_amendment: Option<&ExecPolicyAmendment>,
        proposed_network_policy_

Purpose: Builds the fallback list of choices for older approval requests that did not include an explicit decision list. The choices depend on what kind of permission is being requested.

Data flow: It receives optional information about network access, proposed command-policy changes, proposed network-policy changes, and extra filesystem permissions. For network requests, it offers approve, approve for session, possibly a network policy amendment, and abort. For extra permission requests, it offers approve or abort. For ordinary command requests, it offers approve, possibly approve with a command-policy amendment, and abort.

Call relations: effective_available_decisions uses this when an approval request does not already say which decisions are available. This keeps older protocol messages working while still letting newer messages provide an exact ordered list.

Call graph: 1 external calls (vec!).

fn message(&self) -> &str

Purpose: Returns the human-readable message from an elicitation request, whether the request is a form or a URL. This gives callers one simple way to get the text to show to the user.

Data flow: It looks at which kind of ElicitationRequest it has. For both Form and Url variants, it extracts the message field. It returns a borrowed string and does not modify the request.

Call relations: This is a convenience method for code that displays or logs elicitation prompts. It hides the difference between the form-shaped and URL-shaped requests when all the caller needs is the message.

fn guardian_assessment_action_deserializes_command_shape()

Purpose: Checks that a JSON object describing a shell command can be read into the GuardianAssessmentAction command form correctly. This protects the protocol shape expected by clients and reviewers.

Data flow: The test builds a JSON value with a type of command, a source, a command string, and a working directory. It deserializes that JSON into a GuardianAssessmentAction. Then it compares the result with the exact Rust value expected.

Call relations: This test uses JSON construction, JSON deserialization, and equality checking to guard the command-review message format. If someone changes the field names or representation by accident, this test should fail.

Call graph: 3 external calls (assert_eq!, from_value, json!).

fn guardian_assessment_action_round_trips_execve_shape()

Purpose: Checks that an execve-style guardian action can be read from JSON and written back to the same JSON shape. Execve means a lower-level program launch with a program path and argument list.

Data flow: The test starts with JSON containing an execve action, including the program, argument list, and working directory. It deserializes the JSON into a GuardianAssessmentAction, serializes it back to JSON, and checks that nothing changed. It also checks that the Rust value has the expected fields.

Call relations: This Unix-only test protects the wire format for intercepted process launches. It uses JSON construction, deserialization, serialization, and equality checks so the guardian review protocol stays compatible with clients expecting this exact shape.

Call graph: 3 external calls (assert_eq!, from_value, json!).

fn from_raw_value(raw: &str) -> Self

Purpose: This turns a raw plan name string into a structured PlanType. It recognizes known plan names and aliases, while preserving unknown values so new server-side plans do not break the client.

Data flow: It receives a text value, lowercases it so capitalization does not matter, and compares it with the plan names this file knows about. If it matches, the output is a known plan value; if it does not match, the output keeps the original text inside an unknown plan value.

Call relations: This is the front-door translator for plan strings. Internally it creates either the known-plan form or the unknown-plan form, so later code can work with a clear category instead of repeatedly checking raw text.

Call graph: 2 external calls (Known, Unknown).

fn display_name(self) -> &'static str

Purpose: This gives a plan a readable name for people. It is useful anywhere the program needs to show a plan in logs, settings, or user-facing text instead of using protocol-style names like prolite.

Data flow: It receives one known plan value and maps it directly to a fixed display string. Nothing is changed elsewhere; the result is just the friendly name for that plan.

Call relations: After some other part of the system has identified a plan as known, this function provides the human-readable label. It does not call out to other helpers; it is a simple lookup table in code.

fn raw_value(self) -> &'static str

Purpose: This returns the exact protocol spelling for a known plan. It is useful when the program needs to send or compare the compact server-facing value rather than a display label.

Data flow: It receives one known plan value and returns the matching fixed raw string, such as free, team, or enterprise_cbp_usage_based. It does not modify any state.

Call relations: This is the reverse side of plan interpretation: once code has a structured plan, this function can turn it back into the standard raw form expected by other protocol code.

fn is_workspace_account(self) -> bool

Purpose: This answers whether a known plan belongs to a workspace-style account. That distinction matters because team, business, enterprise, and education accounts often behave differently from individual plans.

Data flow: It receives one known plan value and checks whether it is one of the workspace account plans. The output is a simple true-or-false answer.

Call relations: Code that needs to branch between individual-account behavior and workspace-account behavior can call this after a plan has been identified. Inside, it uses Rust's pattern-matching shortcut to test the plan against the workspace list.

Call graph: 1 external calls (matches!).

fn new(reason: RefreshTokenFailedReason, message: impl Into<String>) -> Self

Purpose: This builds a standard error value for a failed token refresh. It keeps both the machine-friendly reason and the human-readable message together.

Data flow: It receives a failure reason and some message-like input. It converts the message into a stored string, then returns a RefreshTokenFailedError containing both pieces of information.

Call relations: This constructor is called by refresh-token paths and failure-classification code when they need to report that refreshing authentication did not succeed. It packages the failure so callers such as refresh_token, next, and related tests can pass around one clear error value.

Call graph: called by 4 (refresh_failure_is_scoped_to_the_matching_auth_snapshot, refresh_token, next, classify_refresh_token_failure); 1 external calls (into).

fn plan_type_deserializes_raw_aliases()

Purpose: This test proves that alternate raw plan names still turn into the correct known plans. In particular, it checks compatibility for hc as Enterprise and education as Edu.

Data flow: It feeds small JSON strings into deserialization, which means converting JSON text into Rust values. It then compares the result with the expected known plan values and fails the test if they differ.

Call relations: This test protects the plan parsing behavior from accidental changes. It calls assertion helpers to confirm that the aliases accepted by the serialized data model keep working.

Call graph: 1 external calls (assert_eq!).

fn as_str(&self) -> &str

Purpose: Returns the stored profile name as plain text. This lets other code read the validated name without taking ownership of it.

Data flow: It starts with a ProfileV2Name that already passed validation. It reads the inner string and returns it as a borrowed string slice, without changing anything.

Call relations: This is the basic reader for profile names. ProfileV2Name::deref calls it so a profile name can be treated like a normal string when needed.

Call graph: called by 1 (deref).

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: Creates the human-readable error message shown when someone passes an invalid profile name. The message explains that the value must be a plain name, such as work.

Data flow: It reads the invalid value stored in the error, writes a clear message into the formatter, and returns the formatting result.

Call relations: This is used by Rust’s display system when the error needs to be printed for a person. It relies on the standard write! formatting helper.

Call graph: 1 external calls (write!).

fn from_str(value: &str) -> Result<Self, Self::Err>

Purpose: Checks whether a profile name is safe and turns it into a ProfileV2Name. It rejects empty names and names containing anything except letters, numbers, underscores, and dashes.

Data flow: It receives raw text from outside the program. If the text is empty or contains unsafe characters such as slashes or dots, it returns a parse error holding that value. Otherwise it stores the text in a new validated profile-name object.

Call relations: This is the gatekeeper for profile names. Code that parses command-line or config input can use it to avoid treating arbitrary paths as profile files.

fn deref(&self) -> &Self::Target

Purpose: Lets a ProfileV2Name be used like a regular string in places that expect string-like access. This is a convenience after the name has already been validated.

Data flow: It receives a reference to the profile-name object, calls ProfileV2Name::as_str, and returns the same borrowed text.

Call relations: It builds directly on ProfileV2Name::as_str. This makes the type easier to pass around without weakening its validation rule.

Call graph: calls 1 internal fn (as_str).

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

Purpose: Prints a validated profile name as its plain text value. This is used when the name needs to appear in logs, messages, or formatted strings.

Data flow: It reads the inner string and writes it to the formatter. The profile name itself is not changed.

Call relations: This plugs ProfileV2Name into Rust’s normal display formatting system.

fn schema_name() -> String

Purpose: Gives the JSON schema name for the approval-reviewer setting. A JSON schema is a machine-readable description of valid config values.

Data flow: It takes no runtime input and returns the fixed schema name ApprovalsReviewer.

Call relations: Schema generation code calls this when documenting or validating configuration that chooses who reviews approval requests.

fn json_schema(_generator: &mut SchemaGenerator) -> Schema

Purpose: Builds the JSON schema for the approval-reviewer setting, including the accepted string values and a description. It documents both the current values and the legacy guardian_subagent spelling.

Data flow: It ignores the schema generator input, lists the accepted strings, passes them with a plain-language description to string_enum_schema_with_description, and returns the resulting schema object.

Call relations: This is called by schema generation. It delegates the common work of building a string-enum schema to string_enum_schema_with_description.

Call graph: calls 1 internal fn (string_enum_schema_with_description).

fn default() -> Self

Purpose: Creates the default policy for which environment variables a shell command should receive. By default it inherits all parent environment variables, skips built-in secret filtering, adds nothing, restricts nothing, and does not use a shell profile.

Data flow: It takes no input. It creates empty lists and an empty map for exclusions, insertions, and include-only filters, then returns a complete default policy.

Call relations: This default is used by several configuration-building and test paths, including flows that build agent spawn settings and environment-variable behavior.

Call graph: called by 7 (from_approval_and_profile, populate_env_inserts_thread_id, populate_env_omits_thread_id_when_missing, test_core_inherit_defaults_keep_sensitive_vars, build_agent_spawn_config_uses_turn_context_values, create_env_from_core_vars, create_env_from_core_vars); 2 external calls (new, new).

fn string_enum_schema_with_description(values: &[&str], description: &str) -> Schema

Purpose: Creates a JSON schema for a setting whose valid values are a fixed list of strings. It also attaches a description so generated docs are useful to humans.

Data flow: It receives a list of allowed strings and a description. It builds a schema object marked as a string, stores the description, stores the allowed values, and returns the finished schema.

Call relations: This helper is used by ApprovalsReviewer::json_schema so that custom enum schema code stays small and consistent.

Call graph: called by 1 (json_schema); 3 external calls (new, default, Object).

fn merge(&self, other: &Self) -> Self

Purpose: Combines two web search locations, treating the second one as an overlay. Any location field present in the overlay wins; missing overlay fields fall back to the original.

Data flow: It reads country, region, city, and timezone from both location objects. For each field, it chooses the overlay value if it exists, otherwise the base value, and returns a new merged location.

Call relations: This is used by WebSearchToolConfig::merge when both configs include location details. It is the field-by-field merge step for nested location settings.

fn merge(&self, other: &Self) -> Self

Purpose: Combines two web search tool configurations, with the second one overriding only the fields it actually sets. This allows defaults and user overrides to be layered cleanly.

Data flow: It reads context size, allowed domains, and location from the base and overlay configs. It chooses overlay values when present, keeps base values when the overlay is missing them, and merges nested locations field by field when both exist.

Call relations: This is the larger merge operation for web search tool settings. It calls WebSearchLocation::merge for the location part so the same overlay rule applies inside that nested object.

fn from(location: WebSearchLocation) -> Self

Purpose: Converts the project’s internal web search location format into the user-location format expected by the web search API configuration. It marks the location as approximate.

Data flow: It receives a WebSearchLocation, moves over its country, region, city, and timezone fields, sets the type to Approximate, and returns a WebSearchUserLocation.

Call relations: This conversion is used by WebSearchConfig::from when turning a tool-specific config into the broader web search config shape.

fn from(config: WebSearchToolConfig) -> Self

Purpose: Converts WebSearchToolConfig into WebSearchConfig, which is the shape used for web search requests. It maps allowed domains, location, and context size into the request-facing names.

Data flow: It receives a tool config. If allowed domains are present, it wraps them in WebSearchFilters; if location is present, it converts it into WebSearchUserLocation; it copies the context size into search_context_size; then it returns the new config.

Call relations: This function sits between local configuration and request configuration. It uses WebSearchUserLocation::from for the location conversion.

fn request_value(self) -> &'static str

Purpose: Returns the service-tier string that should be sent in a model request. It maps the user-facing Fast tier to the request value priority and Flex to flex.

Data flow: It receives a service-tier enum value and returns the matching static string. Nothing is changed.

Call relations: Request-building code can call this when it needs the exact value expected by the backend service.

fn from_request_value(value: &str) -> Option<Self>

Purpose: Parses a service-tier string from request or config form back into a ServiceTier. It accepts both fast and priority for the fast tier.

Data flow: It receives text. If the text is fast or priority, it returns Fast; if it is flex, it returns Flex; otherwise it returns nothing.

Call relations: This is called by an apply flow when turning incoming configuration into typed settings. It protects the rest of the code from unknown service-tier strings.

Call graph: called by 1 (apply).

fn timeout(&self) -> Duration

Purpose: Turns the configured authentication-command timeout from milliseconds into a Duration, which is Rust’s standard time-span type. Callers use this when deciding how long to wait for a token command.

Data flow: It reads the non-zero millisecond value from the config, converts it into a duration, and returns that duration.

Call relations: Code that runs a provider authentication command can call this before spawning or waiting on the command.

Call graph: 2 external calls (from_millis, get).

fn refresh_interval(&self) -> Option<Duration>

Purpose: Turns the configured token refresh interval into an optional time span. A value of zero means proactive refresh is disabled.

Data flow: It reads refresh_interval_ms. If the number is non-zero, it converts it into a duration and returns it wrapped in Some; if it is zero, it returns None.

Call relations: Token-caching code can use this to decide whether to refresh a provider token on a timer or only after an authentication failure.

Call graph: 1 external calls (new).

fn default_provider_auth_timeout_ms() -> NonZeroU64

Purpose: Provides the default timeout for a provider authentication command. The default is 5,000 milliseconds and is guaranteed to be non-zero.

Data flow: It passes the default timeout number and the field name to non_zero_u64, then returns the validated non-zero value.

Call relations: Serde, the config loading library, calls this as the default for ModelProviderAuthInfo.timeout_ms when the user does not set one.

Call graph: calls 1 internal fn (non_zero_u64).

fn default_provider_auth_refresh_interval_ms() -> u64

Purpose: Provides the default interval for proactively refreshing a cached provider token. The default is 300,000 milliseconds, or five minutes.

Data flow: It takes no input and returns the fixed default number of milliseconds.

Call relations: Serde uses this as the default for ModelProviderAuthInfo.refresh_interval_ms when that field is missing from configuration.

fn non_zero_u64(value: u64, field_name: &str) -> NonZeroU64

Purpose: Converts a plain unsigned number into a non-zero number type, and crashes immediately if the supplied default is accidentally zero. This is a safeguard for constants that must never be zero.

Data flow: It receives a number and the name of the config field it belongs to. If the number is non-zero, it returns the non-zero wrapper; if it is zero, it panics with a field-specific message.

Call relations: default_provider_auth_timeout_ms calls this to prove its timeout default is valid before using it in configuration.

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

fn default_provider_auth_cwd() -> AbsolutePathBuf

Purpose: Chooses the default working directory for a provider authentication command. It tries to resolve . as an absolute path, and falls back to the process’s current directory if needed.

Data flow: It first asks AbsolutePathBuf to deserialize . into an absolute path. If that works, it returns that path. If not, it asks the operating system for the current directory; if even that fails, it panics because the default cannot be safely resolved.

Call relations: Serde uses this as the default for ModelProviderAuthInfo.cwd. is_default_provider_auth_cwd also calls it when deciding whether a path is the default and can be skipped during schema serialization.

Call graph: calls 2 internal fn (current_dir, deserialize); called by 1 (is_default_provider_auth_cwd); 2 external calls (panic!, new).

fn is_default_provider_auth_cwd(path: &AbsolutePathBuf) -> bool

Purpose: Checks whether a provider authentication working directory is the default value. This is used so generated schemas or serialized config can omit the field when it has the default.

Data flow: It receives a path, computes the default provider-auth working directory, compares the two, and returns true if they match.

Call relations: It calls default_provider_auth_cwd. The ModelProviderAuthInfo.cwd schema annotation uses this as its skip condition.

Call graph: calls 1 internal fn (default_provider_auth_cwd).

fn display_name(self) -> &'static str

Purpose: Returns the friendly name for a collaboration mode, suitable for showing to a user. For example, Plan becomes Plan and PairProgramming becomes Pair Programming.

Data flow: It receives a mode value and returns the matching static display string.

Call relations: User-facing messaging, including request_user_input_unavailable_message, calls this when it needs to mention a mode in readable text.

Call graph: called by 1 (request_user_input_unavailable_message).

fn is_tui_visible(self) -> bool

Purpose: Reports whether a collaboration mode should be shown in the terminal user interface. Only Plan and Default are visible choices.

Data flow: It receives a mode, checks whether it is Plan or Default, and returns true or false.

Call relations: The mask_for_kind flow calls this when deciding which modes can appear as selectable terminal UI options.

Call graph: called by 1 (mask_for_kind); 1 external calls (matches!).

fn allows_request_user_input(self) -> bool

Purpose: Reports whether this collaboration mode allows the assistant to ask the user for input. Currently only Plan mode allows that.

Data flow: It receives a mode, checks whether it is Plan, and returns true or false.

Call relations: This is a policy check for features that may request user input. Callers can use it before offering or performing that behavior.

Call graph: 1 external calls (matches!).

fn settings_ref(&self) -> &Settings

Purpose: Returns a borrowed reference to the settings inside a collaboration mode. It is a small internal helper that keeps other methods from repeating direct field access.

Data flow: It receives a collaboration mode and returns a reference to its settings field without copying or changing it.

Call relations: CollaborationMode::model, CollaborationMode::reasoning_effort, CollaborationMode::with_updates, and CollaborationMode::apply_mask call this before reading or copying settings.

Call graph: called by 4 (apply_mask, model, reasoning_effort, with_updates).

fn model(&self) -> &str