Core src tools and unified-exec tests

fn create_test_sync_tool() -> ToolSpec

Purpose: Creates the formal specification for the internal test_sync_tool. Someone uses it when registering available tools for tests, so the system knows the tool’s name, description, and accepted input fields.

Data flow: It starts with no caller-provided input. It builds small schema pieces for each accepted field, groups the barrier fields into a nested object, then groups all top-level fields into the final parameter schema. It returns a ToolSpec describing a function-style tool named test_sync_tool; it does not run the tool or wait on any barrier itself.

Call relations: When the broader tool specification setup asks for this test synchronization tool, it calls create_test_sync_tool. This function hands back the completed tool description, using schema-building helpers for strings, numbers, and objects so the rest of the system can validate or present the tool consistently.

Call graph: calls 3 internal fn (number, object, string); called by 1 (spec); 3 external calls (from, Function, vec!).

fn default_timeout_ms() -> u64

Purpose: Provides the fallback barrier timeout when the caller does not specify one. This keeps a test from waiting forever by default.

Data flow: It takes no input. It reads the file’s default timeout constant and returns that number of milliseconds.

Call relations: This is used by the argument deserializer for BarrierArgs when incoming JSON leaves out timeout_ms. It quietly supplies the safety limit before handle_call later sends the parsed arguments to wait_on_barrier.

fn barrier_map() -> &'static tokio::sync::Mutex<HashMap<String, BarrierState>>

Purpose: Gives access to the shared table of named barriers. The table lets separate tool calls find the same meeting point by ID.

Data flow: It takes no input. It checks whether the global barrier table already exists; if not, it creates an empty hash map wrapped in an asynchronous mutex. It returns a reference to that shared locked map.

Call relations: wait_on_barrier calls this whenever it needs to look up, create, or remove a barrier. This keeps all barrier storage in one place instead of passing it through every tool call.

Call graph: called by 1 (wait_on_barrier).

fn tool_name(&self) -> ToolName

Purpose: Reports the public name of this tool: test_sync_tool. The registry uses this name so callers can request the right handler.

Data flow: It takes the handler as input and constructs a plain tool name from the fixed string test_sync_tool. It returns that tool name.

Call relations: The tool registry calls this when identifying available tools. It delegates the actual name construction to ToolName::plain.

Call graph: calls 1 internal fn (plain).

fn spec(&self) -> ToolSpec

Purpose: Returns the formal description of the tool’s inputs and behavior. This tells the rest of the system how the tool may be called.

Data flow: It takes the handler as input and calls create_test_sync_tool, which builds the tool specification. It returns that specification.

Call relations: The registry or model-facing tool setup calls this when advertising the tool. The details are supplied by create_test_sync_tool, keeping the handler focused on execution.

Call graph: calls 1 internal fn (create_test_sync_tool).

fn supports_parallel_tool_calls(&self) -> bool

Purpose: Declares that this tool is allowed to run at the same time as other tool calls. That is essential because its barrier feature only works when multiple calls can wait together.

Data flow: It takes the handler as input and returns true. It does not read or change any state.

Call relations: The tool runtime checks this capability before scheduling calls in parallel. For this specific tool, parallel execution is not just safe; it is the main reason the tool exists.

fn handle(&self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Starts processing one invocation of the tool and returns it as an asynchronous task. This is the adapter between the generic tool runtime and this handler’s real work.

Data flow: It receives a ToolInvocation, wraps a call to handle_call in a pinned future, and returns that future to the runtime. The actual result will be produced later when the future runs.

Call relations: The tool runtime calls handle when test_sync_tool is invoked. handle immediately hands the invocation to handle_call, which performs the sleeps, barrier wait, and final response.

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

async fn handle_call(
        &self,
        invocation: ToolInvocation,
    ) -> Result<Box<dyn crate::tools::context::ToolOutput>, FunctionCallError>

Purpose: Carries out one test_sync_tool request. It reads the caller’s requested delays and optional barrier, waits as instructed, and returns a simple successful output.

Data flow: It receives a tool invocation and first checks that the payload is a function call with arguments. It parses those arguments into TestSyncArgs. If sleep_before_ms is present and greater than zero, it pauses for that long. If a barrier is present, it calls wait_on_barrier and waits until enough matching calls arrive or an error occurs. If sleep_after_ms is present and greater than zero, it pauses again. On success it returns a boxed tool output containing the text ok; on unsupported payloads, bad arguments, or barrier failure, it returns an error for the model.

Call relations: handle calls this for each tool invocation. This function is the main execution path: it uses parse_arguments to understand input, uses async sleep for timing, calls wait_on_barrier for synchronization, and uses FunctionToolOutput::from_text plus boxed_tool_output to send the final response back through the tool system.

Call graph: calls 4 internal fn (from_text, boxed_tool_output, parse_arguments, wait_on_barrier); called by 1 (handle); 3 external calls (from_millis, sleep, RespondToModel).

async fn wait_on_barrier(args: BarrierArgs) -> Result<(), FunctionCallError>

Purpose: Makes one tool call wait at a named barrier until the required number of participants have arrived. It protects tests from deadlock by rejecting invalid settings and timing out if the group never completes.

Data flow: It receives barrier arguments: an ID, participant count, and timeout. It rejects a participant count of zero and a timeout of zero. It locks the shared barrier map, then either finds the existing barrier for that ID or creates a new one. If the same ID is already registered with a different participant count, it returns an error. Then it waits on the barrier, but only up to the requested timeout. When all participants arrive, they are released. The leader among the released waiters locks the map again and removes the barrier if it is still the same one. On success it returns nothing; on invalid input or timeout it returns an error message.

Call relations: handle_call calls this when the request includes a barrier. It uses barrier_map to share named barriers across concurrent calls, tokio::time::timeout to avoid waiting forever, and Tokio’s Barrier to release all participants together once the expected group has arrived.

Call graph: calls 1 internal fn (barrier_map); called by 1 (handle_call); 7 external calls (new, ptr_eq, new, from_millis, format!, timeout, RespondToModel).

fn test_sync_tool_matches_expected_spec()

Purpose: This test verifies that create_test_sync_tool() returns the exact tool specification expected by the integration-test infrastructure. It is used to catch accidental changes to the tool’s public shape before they affect tests that rely on it.

Data flow: The test starts with no external input. It asks the code under test to create the synchronization tool specification, then builds the expected specification inline, including the tool name, description, accepted input fields, required fields, and whether extra fields are allowed. It compares the two values; if they match, the test passes, and if anything differs, the test fails with a readable comparison.

Call relations: During the automated test run, the Rust test runner calls this function. Inside it, the comparison is handed to assert_eq!, which checks the generated tool specification against the expected one and reports any mismatch.

Call graph: 1 external calls (assert_eq!).

fn described_object(description: &str) -> JsonSchema

Purpose: This helper creates a simple JSON object schema with a human-readable description attached. The tests use it to avoid repeating the same setup for fields that accept an object, such as a worker result or an output schema.

Data flow: It receives a description string. It starts with an empty object-shaped JSON Schema, adds the description text to it, and returns the finished schema. Nothing outside the returned value is changed.

Call relations: The test code uses this as a small building block while writing the expected tool specifications. Inside, it asks the JSON Schema object builder to make the empty object shape, using an empty map for its properties, then fills in the description before handing it back to the test.

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

fn spawn_agents_on_csv_tool_requires_csv_and_instruction()

Purpose: This test proves that the spawn_agents_on_csv tool requires the two essential inputs: the CSV file path and the instruction template. It also checks the rest of the advertised fields, such as optional output path, concurrency limits, timeout, and result schema.

Data flow: When the test runs, it builds the real tool specification and separately writes out the exact specification it expects. It then compares the two. If the name, description, allowed parameters, required parameters, or schema details differ, the test fails.

Call relations: The Rust test runner calls this during the test suite. The function relies on the equality assertion macro to compare the actual tool definition with the expected one, so this test acts like a guardrail around the public shape of the CSV agent-spawning tool.

Call graph: 1 external calls (assert_eq!).

fn report_agent_job_result_tool_requires_result_payload()

Purpose: This test proves that the report_agent_job_result tool requires a worker to send a job id, an item id, and a result object. It also checks the optional stop flag, which lets a worker cancel remaining work after reporting.

Data flow: When the test runs, it creates the real reporting-tool specification and an expected specification written directly in the test. It compares them exactly. If the required result payload or any other part of the schema changes unexpectedly, the test fails.

Call relations: The Rust test runner calls this as part of the automated tests. Like the CSV-spawning test, it uses the equality assertion macro as the final judge, making sure the worker-only reporting tool keeps the contract that job workers depend on.

Call graph: 1 external calls (assert_eq!).

fn parse_csv_supports_quotes_and_commas()

Purpose: This test proves that the CSV parser understands quoted fields that contain commas. Someone would rely on this behavior when a CSV cell contains natural text, such as a name or description, that includes punctuation.

Data flow: It starts with a short CSV string containing two headers and two rows. One row has a quoted value with a comma inside it. The test sends that text into the CSV parser, then compares the returned headers and rows with the expected clean values.

Call relations: During the test run, this function exercises the CSV parsing path and uses an equality check to confirm the parsed result is exactly right. If the parser split alpha, beta into two cells, this test would fail immediately.

Call graph: 1 external calls (assert_eq!).

fn csv_escape_quotes_when_needed()

Purpose: This test checks the rules for turning a single value into safe CSV text. It makes sure plain values stay plain, values with commas get wrapped in quotes, and quotes inside values are escaped correctly.

Data flow: It gives the CSV escaping helper three small strings: a simple word, a string with a comma, and a string containing a quote mark. Each input is transformed into CSV-safe text, and the test compares that output with the expected spelling.

Call relations: This test runs as a guard around the CSV-writing helper. Its equality checks catch changes that would produce CSV text other tools could misread.

Call graph: 1 external calls (assert_eq!).

fn render_instruction_template_expands_placeholders_and_escapes_braces()

Purpose: This test proves that an instruction template can be filled from row data, including column names with spaces, while still allowing literal braces in the final instruction. This matters because agent jobs often need to turn table rows into readable task prompts.

Data flow: It builds a small JSON object with values such as a file path and an area name. It then gives that object and a template string to the renderer. The renderer replaces known placeholders like {path} and {file path}, turns {{literal}} into {literal}, and returns the finished sentence, which the test checks exactly.

Call relations: This test uses a JSON-building helper to create row-like input, then checks the rendered instruction with an equality assertion. It protects the path from raw row data to final agent-facing text.

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

fn render_instruction_template_leaves_unknown_placeholders()

Purpose: This test checks that missing template values are not silently removed. Leaving an unknown placeholder visible is safer because it shows the user what could not be filled.

Data flow: It creates row data that contains only path, then renders a template containing both {path} and {missing}. The known placeholder is replaced, while the unknown one remains as {missing} in the final string.

Call relations: In the test suite, this function covers the renderer’s fallback behavior. Its equality check confirms the renderer does not guess, blank out, or error on an unknown placeholder in this case.

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

fn ensure_unique_headers_rejects_duplicates()

Purpose: This test verifies that CSV headers must be unique. Duplicate column names would make row data ambiguous, because {path} could refer to more than one column.

Data flow: It starts with a header list containing path twice. It passes that list to the header-checking helper and expects an error. The test then compares the error message with the exact user-facing message that should be returned; if no error appears, the test deliberately fails.

Call relations: This test covers the validation step before CSV data is used for jobs. It uses a failure check to ensure duplicates are rejected, then an equality assertion to ensure the reported problem is clear and stable.

Call graph: 3 external calls (assert_eq!, panic!, vec!).

fn create_apply_patch_freeform_tool_matches_expected_spec()

Purpose: This test verifies the standard apply_patch tool description when no environment ID is requested. It makes sure the tool name, user-facing instructions, format type, grammar syntax, and grammar text all match the expected specification.

Data flow: It starts by asking create_apply_patch_freeform_tool for the tool spec with environment IDs turned off. It then compares the returned value with a fully written-out expected value. If anything differs, the assertion reports the mismatch and the test fails.

Call relations: During the test suite, the Rust test runner calls this function. Inside the test, it uses assert_eq! to compare the generated tool spec against the expected one, so accidental changes to the public contract are caught immediately.

Call graph: 1 external calls (assert_eq!).

fn create_apply_patch_freeform_tool_includes_environment_id_when_requested()

Purpose: This test verifies the special apply_patch tool description used when patches need to name an environment. It checks that the grammar includes both the optional environment ID rule and the exact text header that introduces it.

Data flow: It asks create_apply_patch_freeform_tool for the tool spec with environment IDs turned on. It expects the result to be a freeform tool; if it is not, the test stops with a panic. It then looks inside the grammar text and confirms that the environment ID pieces are present.

Call relations: The Rust test runner calls this function as part of automated testing. The test first uses pattern matching to unwrap the freeform tool, calls panic! if the wrong kind of tool comes back, and then uses assert! checks to confirm the needed grammar fragments were included.

Call graph: 2 external calls (assert!, panic!).

fn sample_patch() -> &'static str

Purpose: Provides a tiny example patch used by the hook-payload tests. It keeps those tests focused on behavior instead of repeating patch text in multiple places.

Data flow: It takes no input. It returns a fixed patch string that says to add a file named hello.txt containing the word hello.

Call relations: The pre-tool and post-tool hook tests call this helper when they need a known patch body. It gives both tests the same input, so any difference in results comes from the hook logic being tested rather than from different patch text.

Call graph: called by 2 (post_tool_use_payload_uses_patch_input_and_tool_output, pre_tool_use_payload_uses_freeform_patch_input).

async fn invocation_for_payload(payload: ToolPayload) -> ToolInvocation

Purpose: Builds a realistic apply_patch tool invocation around a chosen payload. Tests use it when they need to ask the handler what it would send to hooks.

Data flow: It receives a ToolPayload, creates a test session and turn, adds a cancellation token, a diff tracker, a fixed call id, the apply_patch tool name, and marks the call as direct. It returns a ToolInvocation that looks like a real tool call but is safe for tests.

Call relations: The hook-payload tests call this helper before asking ApplyPatchHandler for pre-use or post-use data. Internally it relies on the session test helper and creates the small pieces a normal tool run would already have, so the tests do not need to hand-build that context.

Call graph: calls 3 internal fn (make_session_and_context, new, plain); called by 2 (post_tool_use_payload_uses_patch_input_and_tool_output, pre_tool_use_payload_uses_freeform_patch_input); 3 external calls (new, new, new).

async fn pre_tool_use_payload_uses_freeform_patch_input()

Purpose: Checks that the pre-tool hook receives the raw patch text when apply_patch is called with free-form input. This matters because hooks may inspect the exact command before the tool is allowed to run.

Data flow: It starts with the sample patch, wraps it as a custom tool payload, builds a tool invocation, and asks the default apply_patch handler for its pre-tool payload. It expects a payload whose tool name is apply_patch and whose input JSON contains the patch under the command field.

Call relations: The test runner calls this async test. The test uses sample_patch and invocation_for_payload to set up the scene, then calls the handler method under test and compares the result with the exact hook payload that downstream hook code should receive.

Call graph: calls 2 internal fn (invocation_for_payload, sample_patch); 2 external calls (assert_eq!, default).

async fn post_tool_use_payload_uses_patch_input_and_tool_output()

Purpose: Checks that the post-tool hook receives both the original patch text and the final tool output. This lets hooks record or react to what was requested and what happened.

Data flow: It creates the sample patch, wraps it in a custom payload, builds a tool invocation, and creates a successful apply_patch output message. It asks the handler for the post-tool payload and expects it to include the call id, patch command, and response text.

Call relations: The test runner calls this async test. It uses the same setup helper as the pre-tool test, then passes both the invocation and output into the handler so it can verify the data handed off after the tool finishes.

Call graph: calls 3 internal fn (from_text, invocation_for_payload, sample_patch); 2 external calls (assert_eq!, default).

fn diff_consumer_streams_apply_patch_changes()

Purpose: Checks that the diff consumer can read a patch arriving in pieces and report useful progress before the full patch is complete. This supports live UI updates while the model is still streaming tool arguments.

Data flow: It creates a fresh ApplyPatchArgumentDiffConsumer, feeds it patch fragments one by one, and watches when progress events appear. Early header text produces no event; once the added file is recognized, it reports hello.txt as being added with empty content; after the patch finishes, it reports the complete added content hello and world.

Call relations: The test runner calls this test. The test talks directly to the consumer through push_delta and finish_update_on_complete, exercising the same incremental path used when a tool argument is streamed rather than delivered all at once.

Call graph: 3 external calls (assert!, assert_eq!, default).

fn diff_consumer_streams_apply_patch_changes_with_environment_header()

Purpose: Checks that an optional environment header in the patch does not stop streaming diff detection. This is important because some patches may name a target environment before listing file edits.

Data flow: It creates a diff consumer, sends a patch start plus an Environment ID header, then sends the beginning of an added-file patch. The expected output is still a progress event showing hello.txt as an added file.

Call relations: The test runner calls this test. It feeds data directly into the diff consumer to confirm that environment-selection metadata is skipped over cleanly and the file-change parser still starts at the right place.

Call graph: 3 external calls (assert!, assert_eq!, default).

fn diff_consumer_sends_next_update_after_buffer_interval()

Purpose: Checks that the diff consumer sends another progress update after its buffer interval has passed. This prevents the interface from being flooded with updates while still keeping long-running streams fresh.

Data flow: It feeds the consumer enough patch text to trigger a first progress event. Then it manually moves the consumer's last-sent time into the past and sends more content. The result is a second progress event that includes the content known before the newest partial line.

Call relations: The test runner calls this test. It directly adjusts the consumer's timing state to simulate time passing, then uses push_delta to verify the rate-limiting behavior that normal streaming code depends on.

Call graph: 3 external calls (assert_eq!, default, now).

fn reconcile_environment_id_requires_selection_when_enabled()

Purpose: Checks the rule for environment selection in apply_patch input. A patch may name an environment only when the current turn allows that feature.

Data flow: It calls require_environment_id with a parsed environment id while environment selection is disallowed and expects an error message to the model. It also calls it with no parsed id while selection is allowed and expects success with no selected environment.

Call relations: The test runner calls this test. It exercises the environment-id validation function directly, confirming the gate that protects turns where remote or alternate environment selection should not be available.

Call graph: 1 external calls (assert_eq!).

async fn approval_keys_include_move_destination()

Purpose: Checks that approval tracking includes the destination path when a patch moves a file. This matters because a move writes to a new location, not just the old one.

Data flow: It creates a temporary workspace with an old file and a destination directory, builds a patch that updates and moves the file, and asks the apply-patch parser to verify it. From the parsed action, it collects the file paths used for approval and expects two paths: the source and the move destination.

Call relations: The test runner calls this async test. It uses the real apply-patch parser rather than a mock, then passes the parsed action to file_paths_for_action to confirm approval checks will see every path that needs attention.

Call graph: 7 external calls (new, assert_eq!, maybe_parse_apply_patch_verified, panic!, create_dir_all, write, vec!).

fn write_permissions_for_paths_skip_dirs_already_writable_under_workspace_root()

Purpose: Checks that the system does not request extra write permission for files already inside the writable workspace. This keeps sandbox permissions minimal and avoids unnecessary approval prompts.

Data flow: It creates a temporary workspace with a nested directory, builds an absolute path to a file inside it, and uses a workspace-write sandbox policy. When it asks for extra write permissions for that path, the expected result is None because the workspace already covers it.

Call relations: The test runner calls this test. It exercises write_permissions_for_paths directly with a path under the current workspace, confirming that normal in-workspace edits do not create redundant sandbox permission entries.

Call graph: calls 2 internal fn (workspace_write, try_from); 3 external calls (new, assert_eq!, create_dir_all).

fn write_permissions_for_paths_keep_dirs_outside_workspace_root()

Purpose: Checks that paths outside the workspace are still included when extra write permissions are needed. This protects the sandbox rule that only known writable locations may be changed.

Data flow: It creates a temporary workspace directory and a separate outside directory, then builds an absolute file path in the outside directory. With a workspace-write sandbox policy, it asks for permissions and expects the outside directory to appear as an added writable root.

Call relations: The test runner calls this test. It exercises write_permissions_for_paths with an out-of-workspace target, then inspects the resulting sandbox profile to make sure the permission request names the correct outside directory.

Call graph: calls 2 internal fn (workspace_write, try_from); 4 external calls (new, assert_eq!, simplified, create_dir_all).

fn list_mcp_resources_tool_matches_expected_spec()

Purpose: This test makes sure the list_mcp_resources tool is described correctly. It checks that the tool is named properly, explains that it lists MCP server resources, and accepts optional server and cursor inputs.

Data flow: The test starts with the tool specification produced by the real creation function. It builds a separate expected specification in the test, including the human-readable description and the JSON schema for inputs. It then compares the two; if anything differs, the test fails and shows the mismatch.

Call relations: During the test run, the Rust test runner calls this function. The function uses assert_eq! to compare the production tool definition against the expected one, so accidental changes to the public tool contract are caught immediately.

Call graph: 1 external calls (assert_eq!).

fn list_mcp_resource_templates_tool_matches_expected_spec()

Purpose: This test checks the advertised shape of the list_mcp_resource_templates tool. Resource templates are parameterized resources, so the test confirms the description and optional paging/filtering inputs match the intended contract.

Data flow: The test gets the actual resource-template listing tool specification from the production code. It creates the expected version inline, with optional server and cursor string parameters. The comparison produces no output when the values match, but fails the test if any name, description, or parameter schema has drifted.

Call relations: The test runner invokes this function as part of the automated test suite. Inside it, assert_eq! is the checkpoint that decides whether the generated tool specification still matches the documented expectation.

Call graph: 1 external calls (assert_eq!).

fn read_mcp_resource_tool_matches_expected_spec()

Purpose: This test verifies the read_mcp_resource tool specification. It confirms that reading a resource requires both the MCP server name and the resource URI, which prevents callers from trying to read an unspecified resource.

Data flow: The test asks the production code for the actual read-resource tool specification. It then builds the expected specification, including two required string inputs: server and uri. The assertion compares the full structures and fails if the tool’s public contract changes unexpectedly.

Call relations: The automated test runner calls this function during tests. The function relies on assert_eq! to compare the actual and expected tool specifications, helping ensure callers and language models receive stable instructions for reading MCP resources.

Call graph: 1 external calls (assert_eq!).

fn resource(uri: &str, name: &str) -> Resource

Purpose: Creates a simple test resource with just a URI and a name. The tests use it as a clean sample object so they can focus on wrapping and serialization behavior instead of filling in many optional fields.

Data flow: It receives a URI string and a name string. It builds a raw MCP resource with those values, leaves all optional details empty, removes annotations, and returns the finished Resource test value.

Call relations: In the recorded test flow, resource_with_server_serializes_server_field calls this helper when it needs a small sample resource. The helper hands back that sample so the test can pass it into the resource-with-server wrapper.

Call graph: called by 1 (resource_with_server_serializes_server_field).

fn template(uri_template: &str, name: &str) -> ResourceTemplate

Purpose: Creates a simple test resource template with just a URI pattern and a name. This gives the template serialization test a plain, predictable input.

Data flow: It receives a URI template string, such as one containing {id}, and a name string. It builds a raw MCP resource template, leaves optional display and media fields empty, removes annotations, and returns the finished ResourceTemplate value.

Call relations: template_with_server_serializes_server_field calls this helper to get a minimal template. The returned template is then wrapped with a server name and checked as JSON.

Call graph: called by 1 (template_with_server_serializes_server_field).

fn resource_with_server_serializes_server_field()

Purpose: Tests that a resource wrapped with its server name serializes to JSON with the expected server, uri, and name fields. This matters because clients need to know which server a listed resource came from.

Data flow: The test starts by making a sample resource and wrapping it with the server name test. It converts that wrapper into JSON, then checks that the JSON contains the server name, the resource URI, and the resource name exactly as expected.

Call relations: During the test run, Rust's test runner invokes this test. The test calls resource to make the sample input, calls the wrapper constructor new, then hands the wrapper to JSON serialization and compares the resulting fields with expected values.

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

fn list_resources_payload_from_single_server_copies_next_cursor()

Purpose: Tests that a resource-list response from one server keeps its pagination cursor and marks each resource with the server name. A pagination cursor is a bookmark clients use to ask for the next page of results.

Data flow: The test builds a fake list result containing one resource and a next_cursor value. It converts that result into a single-server payload, serializes it to JSON, then checks that the top-level server and cursor are present and that the resource entry also carries the same server name.

Call relations: The test runner calls this test as part of the suite. The test calls from_single_server to transform the raw server result into the project’s outgoing payload, then uses JSON serialization and assertions to verify the result.

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

fn list_resources_payload_from_all_servers_is_sorted()

Purpose: Tests that resources collected from multiple servers are output in a predictable sorted order. Predictable order keeps clients and tests from seeing random-looking changes when the same data is returned.

Data flow: The test creates a map with two server names and several resources. It asks the payload builder to combine all servers, serializes the combined payload to JSON, extracts the resource URIs, and checks that they appear in the expected alpha-before-beta order.

Call relations: The test runner invokes this test. Inside it, the map is filled with sample resources, from_all_servers does the combining and ordering work, and the test inspects the serialized JSON to confirm the order.

Call graph: calls 1 internal fn (from_all_servers); 4 external calls (new, assert_eq!, to_value, vec!).

fn call_tool_result_from_content_marks_success()

Purpose: Tests that tool output created from content is marked as successful when the success flag says so. This protects the meaning of the is_error field, which tells clients whether the tool call failed.

Data flow: The test passes a small content string and a success value into the result-building function. It then checks that the produced result has is_error set to false and contains exactly one content item.

Call relations: The test runner calls this test. The test exercises call_tool_result_from_content and then uses assertions to confirm that the result’s success/error signal and content count match the intended behavior.

Call graph: 1 external calls (assert_eq!).

fn parse_arguments_handles_empty_and_json()

Purpose: Tests how tool argument text is interpreted. Empty text and JSON null should mean “no arguments,” while a JSON object should become usable structured data.

Data flow: The test first sends whitespace-only text into the parser and expects no value. It then sends the text null and again expects no value. Finally it sends a JSON object containing a server name and checks that the parsed value includes that server.

Call relations: The test runner invokes this test. The test calls parse_arguments with three representative inputs, then uses assertions to confirm that missing arguments and real JSON arguments are distinguished correctly.

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

fn template_with_server_serializes_server_field()

Purpose: Tests that a resource template wrapped with a server name serializes to the expected compact JSON shape. This lets clients know which server owns a template for resources that can be filled in later.

Data flow: The test creates a simple template, wraps it with the server name srv, serializes the wrapper to JSON, and compares the whole JSON object with the exact expected object containing server, uriTemplate, and name.

Call relations: The test runner calls this test. It uses the template helper to make input data, calls the wrapper constructor new, serializes the result, and checks the final JSON with an equality assertion.

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

fn serialize_function_output_preserves_small_payload()

Purpose: Tests that normal-sized function output is serialized without being changed. Small responses should not be shortened or reformatted unexpectedly.

Data flow: The test builds a small JSON payload and separately creates the exact JSON string expected from it. It then serializes the payload through serialize_function_output with a generous byte limit and checks that the returned text matches the ordinary JSON string.

Call relations: The test runner invokes this test. The test creates a payload with the JSON helper, sets a byte-based truncation policy, sends both into the output serializer, and compares the text result with standard JSON serialization.

Call graph: 4 external calls (assert_eq!, json!, Bytes, to_string).

fn serialize_function_output_caps_read_resource_payload()

Purpose: Tests that very large resource-read output is shortened according to the configured size limit. This prevents oversized resource contents from flooding a tool response.

Data flow: The test builds a read-resource payload containing a long text resource. It serializes that full payload, computes the expected shortened text using the same truncation rule, then sends the payload through serialize_function_output. The final checks confirm the output is not the full original text and is exactly the expected shortened version.

Call relations: The test runner calls this test. The test constructs a large ReadResourcePayload, uses standard JSON serialization to know the full size, uses the truncation helper to calculate the expected capped output, and then verifies that serialize_function_output applies that cap.

Call graph: 6 external calls (new, assert_eq!, assert_ne!, Bytes, to_string, vec!).

fn search_info_uses_mcp_tool_metadata_and_parameter_names()

Purpose: This test proves that MCP tool metadata is gathered into the search entry. It checks that the handler includes both human-friendly labels and technical names, plus the tool’s parameter names, so the tool can be found through many search terms.

Data flow: It starts by asking tool_info for a sample calendar tool description. It gives that description to McpHandler::new, then asks the handler for its search information. The test compares the produced search text and source details against exact expected values, so any missing or extra search wording causes the test to fail.

Call relations: This test calls tool_info to get a realistic fake MCP tool, then calls the handler constructor to build the object under test. It is focused on the normal case where the MCP tool has a namespace description, and it uses assertions to lock down the search output format.

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

fn search_info_uses_connector_name_for_output_namespace_description()

Purpose: This test checks the fallback wording used when an MCP tool does not provide its own namespace description. It makes sure the system still gives the namespace a useful description based on the connector name.

Data flow: It first builds the sample calendar tool description, then removes its namespace description. After creating an McpHandler and asking for search information, it looks at the namespace output and verifies that its description became “Tools for working with Calendar.” It also checks that the source information keeps the connector name but has no source description.

Call relations: This test reuses tool_info but deliberately changes one field to simulate incomplete metadata. It then builds the handler, inspects the search output, and fails immediately if the output is not a namespace, because the rest of the check only makes sense for namespace search results.

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

fn tool_info() -> ToolInfo

Purpose: This helper builds a complete sample MCP calendar tool for the tests. It keeps the test setup in one place so both tests use the same realistic tool description.

Data flow: It creates and returns a ToolInfo value filled with calendar-related metadata: server and callable names, namespace text, an MCP tool called createEvent, a title, a description, a JSON-shaped parameter schema with start_time and attendees, a connector name, and plugin display names. It does not read outside state or change anything elsewhere.

Call relations: Both tests call this helper before constructing an McpHandler. The helper supplies the shared input data, while each test decides what behavior to check; one uses it unchanged, and the other removes the namespace description to test fallback behavior.

Call graph: called by 2 (search_info_uses_connector_name_for_output_namespace_description, search_info_uses_mcp_tool_metadata_and_parameter_names); 5 external calls (new, json!, new, object, vec!).

fn model_preset(id: &str, show_in_picker: bool) -> ModelPreset

Purpose: Creates a small sample model entry for the tests. It lets the tests quickly make visible or hidden model presets without repeating the same setup data each time.

Data flow: It takes a short model id and a true-or-false flag saying whether the model should be shown in the picker. It builds a complete ModelPreset value from that, filling in names, descriptions, reasoning settings, service tier information, and visibility. The result is a ready-made fake model preset used by the tests.

Call relations: This helper is called when a test needs a realistic model preset, especially in the reasoning-effort length test. It uses standard string creation and list-building tools to assemble the preset before handing it back to the test.

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

fn spawn_agent_tool_v2_requires_task_name_and_lists_visible_models()

Purpose: Checks that the newer spawn-agent tool has the right required inputs and only advertises models that are meant to be visible. It also confirms that sensitive message text is marked for encryption.

Data flow: The test starts with two fake model presets: one visible and one hidden. It creates the version 2 spawn-agent tool, opens its description, input schema, and output schema, then compares them with the expected contract. The result is either a passing test or a failure showing exactly which part of the tool contract changed.

Call relations: During the test run, this function exercises the spawn-agent tool builder and then uses assertions to check the returned specification. If the builder returns the wrong kind of tool, the test stops with a panic because the rest of the checks would not make sense.

Call graph: 4 external calls (assert!, assert_eq!, panic!, vec!).

fn spawn_agent_tool_v1_keeps_legacy_fork_context_field()

Purpose: Protects backward compatibility for the older spawn-agent tool. It verifies that version 1 still uses the old fork_context field and does not switch to the newer fork_turns field.

Data flow: The test creates a version 1 spawn-agent tool with no available models. It unwraps the namespace-style tool shape, reads the function’s parameters, and checks for the legacy field names, message encryption behavior, and model override descriptions. The output is a pass if the old contract is preserved, or a test failure if it has drifted.

Call relations: This test is part of the compatibility safety net. It calls into the version 1 tool creation path and then relies on assertions to prove that callers expecting the older namespace tool will still see the fields they know how to use.

Call graph: 4 external calls (new, assert!, assert_eq!, panic!).

fn spawn_agent_tool_caps_visible_model_summaries()

Purpose: Checks that the spawn-agent description does not grow too long when many models are available. It makes sure only the first five visible model summaries are included.

Data flow: The test builds six visible fake models and creates the version 2 spawn-agent tool. It reads the generated description and checks that the first five model names appear while the sixth does not. The result is a pass if the description is capped as intended.

Call relations: This test exercises the description-building behavior of the spawn-agent tool. It uses assertions to catch accidental changes that would make the model-facing instructions too long or noisy.

Call graph: 3 external calls (assert!, panic!, vec!).

fn spawn_agent_tool_caps_reasoning_effort_value_length()

Purpose: Checks that very long custom reasoning-effort names are shortened before being placed in the spawn-agent description. This prevents unusually long model metadata from bloating the tool instructions.

Data flow: The test starts with a fake visible model, then replaces its reasoning-effort setting with a custom value that is one character too long. It asks for the model description text and compares it with the expected shortened version. The output is a pass if the text is trimmed to the allowed length.

Call relations: This is the only listed test that directly calls model_preset to make its starting model. It then creates a custom reasoning effort and uses equality checks to confirm that the description helper applies the length limit correctly.

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

fn spawn_agent_tool_hides_service_tier_with_spawn_metadata()

Purpose: Checks that certain spawn-agent metadata fields can be hidden when requested. This is important when the system wants to keep agent type, model, reasoning effort, and service tier choices out of the tool interface.

Data flow: The test creates a version 2 spawn-agent tool with the option to hide agent type, model, and reasoning metadata. It then inspects the parameter list and description. The expected result is that those fields and their guidance text are absent.

Call relations: This test drives the spawn-agent tool builder with a privacy-or-simplification option turned on. Assertions confirm that the builder follows that option instead of exposing extra controls to the model.

Call graph: 3 external calls (assert!, panic!, vec!).

fn send_message_tool_requires_message_and_has_no_output_schema()

Purpose: Checks the tool used to send a message to an existing agent. It verifies that both the target agent and the message are required, and that the tool does not promise a structured output.

Data flow: The test creates the send-message tool, reads its parameter schema, and checks for the target and message fields. It confirms the message is marked encrypted, older or unrelated fields are absent, the target description is clear, and there is no output schema. The result is a pass if the tool contract matches these expectations.

Call relations: This test focuses on the send-message tool creation path. It uses assertions after unpacking the returned function tool, and it panics if the created tool has an unexpected shape.

Call graph: 3 external calls (assert!, assert_eq!, panic!).

fn followup_task_tool_requires_message_and_has_no_output_schema()

Purpose: Checks the tool used to send a follow-up task to an existing non-root agent. It makes sure the tool name, description, required fields, encryption marker, and lack of output schema all match the intended contract.

Data flow: The test creates the follow-up-task tool and inspects its name, description, parameters, and output schema. It expects a target and encrypted message to be required, and it expects no unrelated items field and no structured output. The output is simply a passing or failing test.

Call relations: This test exercises the follow-up-task tool builder during the test suite. It uses equality and presence checks to catch any accidental change in the tool instructions or schema.

Call graph: 3 external calls (assert!, assert_eq!, panic!).

fn wait_agent_tool_v2_uses_timeout_only_summary_output()

Purpose: Checks the newer wait-agent tool contract. It verifies that waiting is controlled by an optional timeout and that the tool returns only a brief summary, not the agent’s full content.

Data flow: The test creates the version 2 wait-agent tool with default, minimum, and maximum timeout values. It inspects the input schema to confirm there is a timeout_ms field and no targets field, then checks the description and output schema for summary-only wording. The result is a pass if the wait tool stays focused on polling for updates rather than returning detailed content.

Call relations: This test drives the wait-agent tool builder with explicit timeout settings. Assertions connect those settings to the generated human-facing description and machine-readable schema.

Call graph: 3 external calls (assert!, assert_eq!, panic!).

fn list_agents_tool_includes_path_prefix_and_agent_fields()

Purpose: Checks that the list-agents tool supports filtering by task path and returns the key fields needed to understand each live agent. This helps callers ask for a subset of agents and read useful status information back.

Data flow: The test creates the list-agents tool, reads its input schema, and looks for the path_prefix filter with the expected explanation. It then inspects the output schema and checks that each listed agent requires agent_name, agent_status, and last_task_message. The result is a pass if both input filtering and output shape are correct.

Call relations: This test exercises the list-agents tool creation path. It uses assertions to make sure the schema remains useful for consumers that need to display or reason about active agents.

Call graph: 3 external calls (assert!, assert_eq!, panic!).

fn list_agents_tool_status_schema_includes_interrupted()

Purpose: Checks that interrupted is included as a possible agent status in the list-agents output. This matters because callers need to distinguish an interrupted agent from one that is running, shut down, missing, or still starting.

Data flow: The test creates the list-agents tool, opens the nested output schema for an agent’s status field, and compares the allowed status values with the expected list. The result is a pass if interrupted is part of the official schema.

Call relations: This test is a narrow guard around the status enum in the list-agents schema. It panics if the tool is not returned as the expected function shape, then uses an equality check to protect the exact set of advertised statuses.

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

fn invocation(
    session: Arc<crate::session::session::Session>,
    turn: Arc<TurnContext>,
    tool_name: &str,
    payload: ToolPayload,
) -> ToolInvocation

Purpose: Builds a fake tool call object for tests. It lets each test call a handler as if the model had invoked a real tool.

Data flow: It receives a session, a turn context, a tool name, and a payload. It wraps them with a fresh cancellation token, diff tracker, call ID, and direct-call source, then returns a complete ToolInvocation.

Call relations: Most tests use this helper right before calling a handler. It hides the repetitive setup so the test can focus on the handler behavior being checked.

Call graph: calls 2 internal fn (default, plain); called by 76 (close_agent_submits_shutdown_and_returns_previous_status, handler_rejects_non_function_payloads, multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn, multi_agent_v2_followup_task_rejects_legacy_items_field, multi_agent_v2_followup_task_rejects_root_target_from_child, multi_agent_v2_full_history_fork_accepts_explicit_service_tier, multi_agent_v2_interrupt_agent_accepts_task_name_target, multi_agent_v2_interrupt_agent_accepts_unloaded_task_name_target, multi_agent_v2_interrupt_agent_rejects_root_target_and_id, multi_agent_v2_interrupt_agent_rejects_self_target_by_id (+15 more)); 3 external calls (new, new, new).

fn function_payload(args: serde_json::Value) -> ToolPayload

Purpose: Turns JSON test arguments into the function-call payload shape expected by tool handlers.

Data flow: It receives a JSON value, converts it to a string, and returns a ToolPayload::Function containing that string.

Call relations: Tests pass its result into invocation whenever they want to simulate a normal structured tool call from the model.

Call graph: called by 75 (close_agent_submits_shutdown_and_returns_previous_status, multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn, multi_agent_v2_followup_task_rejects_legacy_items_field, multi_agent_v2_followup_task_rejects_root_target_from_child, multi_agent_v2_full_history_fork_accepts_explicit_service_tier, multi_agent_v2_interrupt_agent_accepts_task_name_target, multi_agent_v2_interrupt_agent_accepts_unloaded_task_name_target, multi_agent_v2_interrupt_agent_rejects_root_target_and_id, multi_agent_v2_interrupt_agent_rejects_self_target_by_id, multi_agent_v2_interrupt_agent_rejects_self_target_by_task_name (+15 more)); 1 external calls (to_string).

fn parse_agent_id(id: &str) -> ThreadId

Purpose: Converts an agent ID string returned by a handler back into a ThreadId used by the test manager.

Data flow: It receives text, parses it as a ThreadId, and fails the test immediately if the text is not valid.

Call relations: Spawn-related tests use it after reading JSON output, then query the thread manager for the spawned child thread.

Call graph: calls 1 internal fn (from_string); called by 7 (spawn_agent_full_history_fork_accepts_explicit_service_tier, spawn_agent_reapplies_runtime_sandbox_after_role_config, spawn_agent_role_service_tier_falls_back_to_supported_parent_tier, spawn_agent_service_tier_inheritance_preserves_supported_or_configured_tiers, spawn_agent_service_tier_override_validates_the_effective_child_model, spawn_agent_uses_explorer_role_and_preserves_approval_policy, tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed).

fn thread_manager() -> ThreadManager

Purpose: Creates a test thread manager with dummy authentication and the built-in OpenAI provider. This gives tests a controllable place to start and inspect agent threads.

Data flow: It reads built-in provider information, combines it with a dummy API key, and returns a ThreadManager configured for tests.

Call relations: Most tests that need live agent control call this before assigning the manager's agent_control handle to the fake session.

Call graph: calls 2 internal fn (with_models_provider_for_tests, from_api_key); called by 56 (close_agent_submits_shutdown_and_returns_previous_status, multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn, multi_agent_v2_followup_task_rejects_legacy_items_field, multi_agent_v2_followup_task_rejects_root_target_from_child, multi_agent_v2_full_history_fork_accepts_explicit_service_tier, multi_agent_v2_interrupt_agent_accepts_task_name_target, multi_agent_v2_interrupt_agent_rejects_root_target_and_id, multi_agent_v2_interrupt_agent_rejects_self_target_by_id, multi_agent_v2_interrupt_agent_rejects_self_target_by_task_name, multi_agent_v2_interrupted_turn_does_not_notify_parent (+15 more)); 1 external calls (built_in_model_providers).

async fn install_role_with_model_override(turn: &mut TurnContext) -> String

Purpose: Adds a temporary agent role whose config file overrides the child model, provider, and reasoning effort. Tests use it to prove which spawn modes allow or reject role-based overrides.

Data flow: It writes a role TOML file under the test Codex home, inserts a matching AgentRoleConfig into the turn config, updates the turn, and returns the role name.

Call relations: Forking tests call this before spawning agents with an agent_type. The spawned handler then reads the role config through normal production paths.

Call graph: called by 3 (multi_agent_v2_spawn_fork_turns_all_rejects_agent_type_override, multi_agent_v2_spawn_partial_fork_turns_allows_agent_type_override, spawn_agent_fork_context_rejects_agent_type_override); 3 external calls (new, create_dir_all, write).

fn set_turn_config(turn: &mut TurnContext, config: crate::config::Config)

Purpose: Replaces a turn's config while also refreshing the derived multi-agent version. This keeps tests from accidentally enabling a feature flag without updating the turn state that handlers read.

Data flow: It receives a mutable turn and a config, computes the multi-agent version from the config's features, stores both on the turn, and returns nothing.

Call relations: MultiAgentV2 tests use this after enabling the feature flag so v2 handlers see a consistent turn context.

Call graph: called by 39 (multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn, multi_agent_v2_followup_task_rejects_legacy_items_field, multi_agent_v2_followup_task_rejects_root_target_from_child, multi_agent_v2_full_history_fork_accepts_explicit_service_tier, multi_agent_v2_interrupt_agent_accepts_task_name_target, multi_agent_v2_interrupt_agent_accepts_unloaded_task_name_target, multi_agent_v2_interrupt_agent_rejects_root_target_and_id, multi_agent_v2_interrupt_agent_rejects_self_target_by_id, multi_agent_v2_interrupt_agent_rejects_self_target_by_task_name, multi_agent_v2_interrupted_turn_does_not_notify_parent (+15 more)); 2 external calls (new, multi_agent_version_from_features).

fn expect_text_output(output: T) -> (String, Option<bool>)

Purpose: Extracts the text and success flag from a handler's tool output. It gives tests a simple way to inspect JSON returned to the model.

Data flow: It converts a ToolOutput into a response item, accepts either normal or custom function-call output, turns text or content items into plain text, and returns that text plus the optional success value.

Call relations: Successful handler tests call this after handle returns, then deserialize the text or compare it directly. If the output is not a function result, it fails the test.

Call graph: calls 1 internal fn (function_call_output_content_items_to_text); called by 35 (close_agent_submits_shutdown_and_returns_previous_status, multi_agent_v2_full_history_fork_accepts_explicit_service_tier, multi_agent_v2_interrupt_agent_accepts_task_name_target, multi_agent_v2_interrupt_agent_accepts_unloaded_task_name_target, multi_agent_v2_list_agents_filters_by_relative_path_prefix, multi_agent_v2_list_agents_keeps_interrupted_resident_agents, multi_agent_v2_list_agents_omits_closed_agents, multi_agent_v2_list_agents_returns_completed_status_without_encrypted_spawn_preview, multi_agent_v2_spawn_agent_ignores_configured_max_depth, multi_agent_v2_spawn_omits_agent_id_when_named (+15 more)); 2 external calls (to_response_item, panic!).

async fn handler_rejects_non_function_payloads()

Purpose: Checks that the spawn handler refuses payloads that are not normal function-call arguments. This prevents the tool from accepting unsupported input shapes.

Data flow: It creates a session and a custom text payload, sends it to SpawnAgentHandler, and expects a model-facing error saying the payload is unsupported.

Call relations: It uses the common invocation helper and directly exercises the legacy spawn handler's input validation path.

Call graph: calls 2 internal fn (make_session_and_context, invocation); 4 external calls (new, default, assert_eq!, panic!).

async fn spawn_agent_rejects_empty_message()

Purpose: Checks that an agent cannot be spawned with only blank text as its task. A child agent needs a real instruction.

Data flow: It passes a whitespace message to spawn_agent and expects the handler to return an error about empty messages.

Call relations: This test drives SpawnAgentHandler through the same function-payload path used by normal tool calls.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn spawn_agent_rejects_when_message_and_items_are_both_set()

Purpose: Checks that legacy spawn_agent rejects requests that provide both plain message text and structured items. This avoids ambiguous instructions.

Data flow: It sends both a message and an items array to the handler, then expects an error telling the caller to choose one format.

Call relations: It covers a shared validation rule also tested for send_input.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn spawn_agent_uses_explorer_role_and_preserves_approval_policy()

Purpose: Verifies that spawning an explorer agent applies the requested role while keeping the parent's approval policy. Approval policy controls when user permission is required.

Data flow: It sets up a manager, configures the parent to use the Ollama provider and on-request approvals, spawns an explorer, parses the returned agent ID, and checks the child snapshot.

Call relations: The test calls SpawnAgentHandler and then asks the test thread manager what configuration the child actually received.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, parse_agent_id, thread_manager); 8 external calls (new, default, assert!, assert_eq!, create_model_provider, built_in_model_providers, json!, from_str).

async fn spawn_agent_fork_context_rejects_agent_type_override()

Purpose: Ensures a full-history fork cannot also change the agent type. A full-history fork is meant to continue the same context, not become a different role.

Data flow: It installs a role with model overrides, starts a root thread, asks spawn_agent for fork_context plus agent_type, and expects a clear rejection.

Call relations: It tests legacy spawn behavior and uses the role-install helper to make the forbidden override meaningful.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, install_role_with_model_override, invocation, thread_manager); 4 external calls (new, default, assert_eq!, json!).

async fn spawn_agent_fork_context_rejects_child_model_overrides()

Purpose: Ensures a full-history fork cannot override the model or reasoning effort. The child must inherit these from the parent in that mode.

Data flow: It starts a root thread, sends spawn_agent a fork_context request with explicit model and reasoning_effort, and checks for the inherited-settings error.

Call relations: It complements the agent_type fork test by covering direct model override fields.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, thread_manager); 4 external calls (new, default, assert_eq!, json!).

async fn multi_agent_v2_spawn_fork_turns_all_rejects_agent_type_override()

Purpose: Checks that MultiAgentV2 treats fork_turns="all" like a full-history fork and rejects agent type overrides.

Data flow: It enables MultiAgentV2, installs an overriding role, sends a spawn request with fork_turns all and agent_type, and expects the same inheritance error.

Call relations: This is the v2 version of the legacy full-history fork rule.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, install_role_with_model_override, invocation, thread_manager); 4 external calls (new, default, assert_eq!, json!).

async fn multi_agent_v2_spawn_defaults_to_full_fork_and_rejects_child_model_overrides()

Purpose: Checks that MultiAgentV2's default spawn is a full fork and therefore rejects child model overrides unless a partial or no fork is requested.

Data flow: It enables v2, starts a root thread, calls spawn_agent with model and reasoning_effort but no fork_turns, and expects the inherited-settings error.

Call relations: It confirms v2 default behavior through SpawnAgentHandlerV2.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 4 external calls (new, default, assert_eq!, json!).

async fn spawn_agent_service_tier_override_validates_the_effective_child_model()

Purpose: Checks that requested service tiers are validated against the model the child will actually use. A service tier is a provider option such as priority access.

Data flow: It runs three spawn cases: a supported tier succeeds and is stored, an unknown tier fails, and a tier unsupported by the chosen child model fails.

Call relations: It calls the legacy spawn handler and then inspects child config snapshots for successful cases.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, parse_agent_id, thread_manager); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn spawn_agent_service_tier_inheritance_preserves_supported_or_configured_tiers()

Purpose: Checks how service tier values move from parent config, explicit child model choices, and role files into spawned agents.

Data flow: It creates several parent and role configurations, spawns children, and inspects snapshots to see whether the tier is preserved or cleared when incompatible.

Call relations: It exercises SpawnAgentHandler with inherited settings, explicit model overrides, and role config overrides.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, parse_agent_id, thread_manager); 7 external calls (new, default, assert_eq!, json!, from_str, create_dir_all, write).

async fn spawn_agent_role_service_tier_falls_back_to_supported_parent_tier()

Purpose: Verifies that an unsupported service tier in a role file does not poison the spawn if the parent has a supported tier to use instead.

Data flow: It writes a role config with an invalid child tier, gives the parent a valid tier, spawns the role, and checks that the child uses the parent's supported tier.

Call relations: It focuses on the role-config path inside SpawnAgentHandler.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, parse_agent_id, thread_manager); 7 external calls (new, default, assert_eq!, json!, from_str, create_dir_all, write).

async fn spawn_agent_role_service_tier_does_not_hide_invalid_spawn_request()

Purpose: Ensures an invalid service tier explicitly requested in the spawn call is still rejected, even if the role file contains a valid tier.

Data flow: It creates a role with a supported tier, calls spawn_agent with service_tier="turbo", and expects the unsupported-tier error.

Call relations: This guards priority order: user request validation must not be hidden by role defaults.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 6 external calls (new, default, assert_eq!, json!, create_dir_all, write).

async fn spawn_agent_full_history_fork_accepts_explicit_service_tier()

Purpose: Checks that full-history fork restrictions still allow an explicit service tier when that tier is valid for the inherited model.

Data flow: It sets the parent model to one that supports the fast tier, spawns with fork_context and service_tier, then checks the child snapshot.

Call relations: It narrows the full-history fork rule tested earlier: model and role overrides are forbidden, but service tier can be supplied.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, parse_agent_id, thread_manager); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn multi_agent_v2_full_history_fork_accepts_explicit_service_tier()

Purpose: Checks the same valid service-tier exception for MultiAgentV2 full-history forks.

Data flow: It enables v2, spawns a named task with a supported service tier, resolves the task name to a child thread, and checks the child config.

Call relations: It proves SpawnAgentHandlerV2 follows the same service-tier rule as the legacy handler.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn multi_agent_v2_spawn_partial_fork_turns_allows_agent_type_override()

Purpose: Verifies that a partial v2 fork may use a different agent role. Partial forks do not inherit the entire parent history, so role changes are allowed.

Data flow: It enables v2, installs a role with model overrides, spawns with fork_turns="1", and checks the child model, provider, and reasoning effort.

Call relations: It contrasts with the v2 full-fork rejection tests.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, install_role_with_model_override, invocation, thread_manager); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn spawn_agent_returns_agent_id_without_task_name()

Purpose: Checks the legacy spawn response shape. In v1, an unnamed child should return a raw agent_id and nickname, not a task path.

Data flow: It spawns an agent, extracts the output JSON, and asserts agent_id exists, task_name does not, nickname exists, and success is true.

Call relations: It protects backwards compatibility for callers of the legacy SpawnAgentHandler.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager); 6 external calls (new, default, assert!, assert_eq!, json!, from_str).

async fn multi_agent_v2_spawn_requires_task_name()

Purpose: Checks that v2 spawn requests must name the task. V2 uses task paths as stable addresses.

Data flow: It enables v2, calls spawn_agent without task_name, and expects a parse error mentioning the missing field.

Call relations: It drives SpawnAgentHandlerV2's argument parsing rules.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert!, json!, panic!).

async fn multi_agent_v2_spawn_rejects_legacy_items_field()

Purpose: Ensures v2 spawn rejects the old structured items field. V2 expects a simpler encrypted message field shape.

Data flow: It enables v2, sends message plus items plus task_name, and expects an unknown-field error for items.

Call relations: It is one of several v2 tests that keep legacy fields out of the new protocol.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert!, json!, panic!).

async fn spawn_agent_errors_when_manager_dropped()

Purpose: Checks that spawning fails cleanly when no agent manager is available. Without the manager, there is nowhere to create the child thread.

Data flow: It builds a normal session without installing agent_control, calls spawn_agent, and expects a "collab manager unavailable" error.

Call relations: It tests the handler's dependency check before any real spawn work happens.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn multi_agent_v2_spawn_returns_path_and_send_message_accepts_relative_path()

Purpose: Verifies that v2 spawn returns an absolute task path and that send_message can later address that child by a relative path.

Data flow: It spawns /root/test_process, checks the child's metadata and captured communication, then sends another message to test_process and checks the delivered operation.

Call relations: It connects SpawnAgentHandlerV2 and SendMessageHandlerV2 in one end-to-end path-addressing scenario.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager); 6 external calls (new, default, assert!, assert_eq!, json!, from_str).

async fn multi_agent_v2_spawn_rejects_legacy_fork_context()

Purpose: Checks that v2 does not accept the old fork_context flag. Callers must use fork_turns instead.

Data flow: It enables v2, sends a spawn request containing fork_context, and expects a specific error pointing to fork_turns.

Call relations: It enforces the v2 API boundary in SpawnAgentHandlerV2.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 4 external calls (new, default, assert_eq!, json!).

async fn multi_agent_v2_spawn_rejects_invalid_fork_turns_string()

Purpose: Checks that v2 fork_turns only accepts known words or a positive integer string.

Data flow: It sends fork_turns="banana" and expects an error explaining the allowed values.

Call relations: It tests parsing and validation before any child thread is created.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 4 external calls (new, default, assert_eq!, json!).

async fn multi_agent_v2_spawn_rejects_zero_fork_turns()

Purpose: Checks that fork_turns="0" is rejected. Zero turns must be written as the explicit word "none" instead.

Data flow: It sends a v2 spawn request with fork_turns set to zero and expects the allowed-values error.

Call relations: It covers a boundary case in SpawnAgentHandlerV2's fork-turn parser.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 4 external calls (new, default, assert_eq!, json!).

async fn multi_agent_v2_send_message_accepts_root_target_from_child()

Purpose: Verifies that a child agent can send a normal message back to the root agent in v2.

Data flow: It manually creates a child session source, calls send_message with target /root, and checks that the root thread receives an inter-agent communication from the child path.

Call relations: It exercises SendMessageHandlerV2 from a sub-agent context.

Call graph: calls 6 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager, try_from); 6 external calls (new, SubAgent, assert!, default, json!, vec!).

async fn multi_agent_v2_followup_task_rejects_root_target_from_child()

Purpose: Checks that a child cannot create a follow-up task targeting the root agent. Follow-up tasks are for continuing spawned agents, not commanding the root.

Data flow: It creates a child context, calls followup_task with target /root, expects a rejection, and verifies no root interrupt or message operation was submitted.

Call relations: It tests FollowupTaskHandlerV2's extra safety rule compared with send_message.

Call graph: calls 6 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager, try_from); 8 external calls (new, SubAgent, assert!, assert_eq!, default, json!, panic!, vec!).

async fn multi_agent_v2_list_agents_returns_completed_status_without_encrypted_spawn_preview()

Purpose: Checks that v2 list_agents reports completed agents clearly without leaking the encrypted spawn message as a preview.

Data flow: It spawns a worker, injects a completed event with the message "done", lists agents, and checks root and worker entries.

Call relations: It combines SpawnAgentHandlerV2, session event recording, and ListAgentsHandlerV2 output formatting.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager); 6 external calls (new, default, assert_eq!, json!, TurnComplete, from_str).

async fn multi_agent_v2_list_agents_filters_by_relative_path_prefix()

Purpose: Verifies that v2 list_agents can filter descendants using a relative path prefix from the caller's current agent path.

Data flow: It creates /root/researcher and /root/researcher/worker, makes the caller the researcher, lists with prefix worker, and expects only the worker.

Call relations: It exercises ListAgentsHandlerV2's path resolution and filtering behavior.

Call graph: calls 7 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager, from_string); 7 external calls (new, SubAgent, assert_eq!, default, json!, from_str, vec!).

async fn multi_agent_v2_list_agents_omits_closed_agents()

Purpose: Checks that closed v2 agents disappear from list_agents results.

Data flow: It spawns a worker, closes it through agent_control, lists agents, and expects only /root to remain.

Call relations: It confirms list_agents respects lifecycle state maintained by the manager.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn multi_agent_v2_list_agents_keeps_interrupted_resident_agents()

Purpose: Checks that interrupted but still resident agents remain visible in list_agents. Interrupted is not the same as closed.

Data flow: It spawns a worker, interrupts it through the v2 interrupt handler, lists agents, and expects both root and worker entries.

Call relations: It links InterruptAgentHandler behavior with ListAgentsHandlerV2 visibility rules.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn multi_agent_v2_send_message_rejects_legacy_items_field()

Purpose: Ensures v2 send_message rejects the old items field.

Data flow: It spawns a worker, calls send_message with items instead of message, and expects an unknown-field parse error.

Call relations: It mirrors the v2 spawn legacy-field rejection for the send-message handler.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert!, json!, panic!).

async fn multi_agent_v2_send_message_rejects_interrupt_parameter()

Purpose: Checks that v2 send_message cannot also request an interrupt. Interrupting is a separate tool action.

Data flow: It spawns a worker, calls send_message with interrupt=true, expects a parse error, and confirms neither interrupt nor message operations were sent.

Call relations: It protects SendMessageHandlerV2 from silently accepting a removed or dangerous option.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert!, json!, panic!).

async fn multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn()

Purpose: Verifies that a parent is notified each time a child completes a turn, including after a follow-up task.

Data flow: It spawns a worker, injects one completed turn, sends a follow-up task, injects a second completed turn, then waits until exactly one parent notification for each appears.

Call relations: It connects SpawnAgentHandlerV2, FollowupTaskHandlerV2, event handling, and inter-agent completion-message formatting.

Call graph: calls 8 internal fn (make_session_and_context, format_inter_agent_completion_message, function_payload, invocation, set_turn_config, thread_manager, root, try_from); 10 external calls (new, from_millis, from_secs, default, assert_eq!, json!, Completed, TurnComplete, sleep, timeout).

async fn multi_agent_v2_followup_task_rejects_legacy_items_field()

Purpose: Ensures v2 followup_task rejects the old items field.

Data flow: It spawns a worker, calls followup_task with items, and expects an unknown-field parse error.

Call relations: It is the follow-up-task version of the v2 legacy input-shape tests.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert!, json!, panic!).

async fn multi_agent_v2_interrupted_turn_does_not_notify_parent()

Purpose: Checks that an interrupted child turn does not produce a completion notification to the parent.

Data flow: It spawns a worker, sends a TurnAborted event with reason Interrupted, then checks that no parent communication from the worker was captured.

Call relations: It tests the event-to-notification path used by MultiAgentV2 child turns.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert_eq!, json!, TurnAborted).

async fn multi_agent_v2_spawn_omits_agent_id_when_named()

Purpose: Checks the v2 spawn response shape. Named v2 agents should be returned by task path, not raw internal thread ID.

Data flow: It spawns a named task, reads the JSON output, and asserts task_name exists while agent_id and nickname do not.

Call relations: It protects the public response contract of SpawnAgentHandlerV2.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager); 6 external calls (new, default, assert!, assert_eq!, json!, from_str).

async fn multi_agent_v2_spawn_surfaces_task_name_validation_errors()

Purpose: Checks that invalid v2 task names produce a clear model-facing error.

Data flow: It sends task_name="BadName" and expects the lowercase/digit/underscore validation message.

Call relations: It exercises the path-name validation used before v2 agents are created.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn spawn_agent_reapplies_runtime_sandbox_after_role_config()

Purpose: Verifies that role config loading does not erase runtime sandbox and permission settings. Sandbox settings limit what files, network, and commands a child can use.

Data flow: It builds a runtime permission profile different from the base config, spawns an explorer role, then checks the child config and first turn policies match the runtime values.

Call relations: It tests SpawnAgentHandler's interaction with config overlays, approval settings, and turn-level permission profiles.

Call graph: calls 11 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, parse_agent_id, set_turn_config, thread_manager, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd (+1 more)); 7 external calls (new, default, assert!, assert_eq!, assert_ne!, json!, from_str).

async fn spawn_agent_rejects_when_depth_limit_exceeded()

Purpose: Checks that legacy agents cannot keep spawning children past the configured depth limit.

Data flow: It marks the current turn as already at max depth, calls spawn_agent, and expects the "solve the task yourself" error.

Call relations: It exercises the legacy depth guard in SpawnAgentHandler.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, thread_manager); 6 external calls (new, default, SubAgent, assert_eq!, json!, panic!).

async fn spawn_agent_allows_depth_up_to_configured_max_depth()

Purpose: Checks that the depth limit is configurable and allows spawning when the parent is still below the new maximum.

Data flow: It raises agent_max_depth, marks the current agent at the default depth, spawns a child, and checks that a valid ID and nickname are returned.

Call relations: It complements the depth-limit rejection test.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager); 7 external calls (new, default, SubAgent, assert!, assert_eq!, json!, from_str).

async fn multi_agent_v2_spawn_agent_ignores_configured_max_depth()

Purpose: Verifies that MultiAgentV2 does not use the legacy max-depth rule. V2 path nesting is governed differently.

Data flow: It sets max depth to one, makes the caller a child agent, spawns another named child with fork_turns none, and expects /root/parent/child to be created.

Call relations: It proves SpawnAgentHandlerV2 intentionally differs from legacy SpawnAgentHandler on depth.

Call graph: calls 7 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager, try_from); 6 external calls (new, default, SubAgent, assert_eq!, json!, from_str).

async fn send_input_rejects_empty_message()

Purpose: Checks that send_input refuses an empty message. A resumed or existing agent should not be prompted with nothing.

Data flow: It sends an empty message to a random target ID and expects the empty-message error before target lookup matters.

Call relations: It exercises SendInputHandler's input validation.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 4 external calls (new, assert_eq!, json!, panic!).

async fn send_input_rejects_when_message_and_items_are_both_set()

Purpose: Checks that send_input rejects ambiguous requests containing both message and structured items.

Data flow: It passes both fields and expects the handler to tell the caller to choose one.

Call relations: It covers the same message-vs-items rule as legacy spawn.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 4 external calls (new, assert_eq!, json!, panic!).

async fn send_input_rejects_invalid_id()

Purpose: Checks that send_input reports malformed agent IDs clearly.

Data flow: It passes target="not-a-uuid" and expects a model-facing invalid-agent-id error.

Call relations: It tests parsing before SendInputHandler tries to contact the manager.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 4 external calls (new, assert!, json!, panic!).

async fn send_input_reports_missing_agent()

Purpose: Checks that send_input reports a well-formed but nonexistent agent ID.

Data flow: It installs a test manager, chooses a new ThreadId that has no thread, sends input, and expects an agent-not-found error.

Call relations: It exercises SendInputHandler's lookup path through agent_control.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, thread_manager, new); 4 external calls (new, assert_eq!, json!, panic!).

async fn send_input_interrupts_before_prompt()

Purpose: Verifies that send_input sends an interrupt before the new prompt when requested.

Data flow: It starts a thread, calls send_input with interrupt=true, then inspects captured operations to confirm Interrupt comes before UserInput.

Call relations: It tests operation ordering in SendInputHandler.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, thread_manager); 4 external calls (new, assert!, assert_eq!, json!).

async fn send_input_accepts_structured_items()

Purpose: Checks that legacy send_input can send structured input items such as mentions plus text.

Data flow: It starts a thread, sends an items array, builds the expected UserInput operation, and confirms the manager captured it.

Call relations: It verifies SendInputHandler's conversion from JSON items into protocol-level user input.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, thread_manager); 5 external calls (new, default, assert_eq!, json!, vec!).

async fn resume_agent_rejects_invalid_id()

Purpose: Checks that resume_agent rejects malformed IDs.

Data flow: It calls resume_agent with id="not-a-uuid" and expects an invalid-agent-id message.

Call relations: It tests ResumeAgentHandler's parsing guard.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 4 external calls (new, assert!, json!, panic!).

async fn resume_agent_reports_missing_agent()

Purpose: Checks that resume_agent reports a missing but well-formed agent ID.

Data flow: It installs a test manager, creates a fresh ThreadId with no stored agent, calls resume_agent, and expects an agent-not-found error.

Call relations: It exercises ResumeAgentHandler's lookup path.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, thread_manager, new); 4 external calls (new, assert_eq!, json!, panic!).

async fn resume_agent_noops_for_active_agent()

Purpose: Verifies that resuming an already active agent does not create a duplicate thread.

Data flow: It starts an agent, records its status, calls resume_agent, checks the returned status, and confirms the manager still has exactly one thread ID.

Call relations: It tests the harmless no-op path of ResumeAgentHandler.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager); 4 external calls (new, assert_eq!, json!, from_str).

async fn resume_agent_restores_closed_agent_and_accepts_send_input()

Purpose: Checks that a closed agent with saved history can be resumed and then receive input.

Data flow: It creates a thread from forked history, shuts it down, resumes it, confirms it is no longer NotFound, then sends input and checks a submission ID is returned.

Call relations: It combines ResumeAgentHandler and SendInputHandler to prove restored agents are usable.

Call graph: calls 7 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager, from_auth_for_testing, from_api_key); 8 external calls (new, assert!, assert_eq!, assert_ne!, json!, Forked, from_str, vec!).

async fn resume_agent_rejects_when_depth_limit_exceeded()

Purpose: Checks that legacy resume_agent also respects the agent depth limit.

Data flow: It marks the current turn as already at max depth, calls resume_agent, and expects the depth-limit error.

Call relations: It mirrors the spawn depth-limit test for ResumeAgentHandler.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, thread_manager); 5 external calls (new, SubAgent, assert_eq!, json!, panic!).

async fn wait_agent_rejects_non_positive_timeout()

Purpose: Checks that legacy wait_agent rejects timeout_ms values of zero or below.

Data flow: It calls wait_agent with one target and timeout_ms 0, then expects a greater-than-zero error.

Call relations: It tests argument validation in the legacy WaitAgentHandler.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn wait_agent_rejects_invalid_target()

Purpose: Checks that legacy wait_agent rejects malformed target IDs.

Data flow: It passes targets=["invalid"] and expects an invalid-agent-id error.

Call relations: It exercises WaitAgentHandler's target parsing.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 5 external calls (new, default, assert!, json!, panic!).

async fn wait_agent_rejects_empty_targets()

Purpose: Checks that legacy wait_agent requires at least one target.

Data flow: It passes an empty target list and expects an "agent ids must be non-empty" error.

Call relations: It covers a basic guard before waiting starts.

Call graph: calls 3 internal fn (make_session_and_context, function_payload, invocation); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn multi_agent_v2_wait_agent_accepts_timeout_only_argument()

Purpose: Verifies that v2 wait_agent can wait without explicit targets, using mailbox activity instead.

Data flow: It spawns a worker, starts wait_agent with only timeout_ms, enqueues a worker-to-root mailbox message, and expects wait to complete without timing out.

Call relations: It tests the mailbox-based waiting style of WaitAgentHandlerV2.

Call graph: calls 8 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager, root, new); 9 external calls (new, default, new, default, assert_eq!, json!, from_str, spawn, yield_now).

async fn multi_agent_v2_wait_agent_rejects_timeout_below_configured_min()

Purpose: Checks that v2 wait_agent honors the configured minimum timeout.

Data flow: It sets min timeout to 50 ms, calls wait_agent with timeout_ms 1, and expects an at-least-50 error.

Call relations: It tests WaitAgentHandlerV2 against configurable limits.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, set_turn_config); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn multi_agent_v2_wait_agent_accepts_explicit_timeout_at_configured_min()

Purpose: Checks that the v2 minimum timeout is inclusive.

Data flow: It sets min timeout to 1 ms, calls wait_agent with 1 ms, and expects a successful timed-out result.

Call relations: It complements the below-minimum rejection test.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn multi_agent_v2_wait_agent_uses_configured_default_timeout()

Purpose: Verifies that v2 wait_agent uses the configured default timeout when none is supplied.

Data flow: It sets the default to 50 ms, confirms an early 20 ms wrapper times out, then waits long enough and expects wait_agent's own timed-out result.

Call relations: It checks the default timeout path in WaitAgentHandlerV2.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config); 9 external calls (new, from_millis, from_secs, default, assert!, assert_eq!, json!, from_str, timeout).

async fn multi_agent_v2_wait_agent_allows_zero_configured_timeout()

Purpose: Checks that v2 can be configured to allow an immediate zero-timeout wait.

Data flow: It sets min, max, and default wait timeouts to zero, calls wait_agent with no arguments, and expects an immediate timed-out result.

Call relations: It covers a special configuration boundary in WaitAgentHandlerV2.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config); 7 external calls (new, from_secs, default, assert_eq!, json!, from_str, timeout).

async fn multi_agent_v2_wait_agent_rejects_timeout_above_configured_max()

Purpose: Checks that v2 wait_agent honors the configured maximum timeout.

Data flow: It sets max timeout to 50 ms, calls wait_agent with 500 ms, and expects an at-most-50 error.

Call relations: It tests the upper bound paired with the minimum-bound tests.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, set_turn_config); 5 external calls (new, default, assert_eq!, json!, panic!).

async fn multi_agent_v2_wait_agent_accepts_explicit_timeout_at_configured_max()

Purpose: Checks that the v2 maximum timeout is inclusive.

Data flow: It sets min, max, and default to 1 ms, calls wait_agent with 1 ms, and expects a successful timed-out result.

Call relations: It complements the above-maximum rejection test.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn wait_agent_returns_not_found_for_missing_agents()

Purpose: Checks that legacy wait_agent returns NotFound status for missing agents instead of failing.

Data flow: It installs a manager, waits on two new ThreadIds that do not exist, and expects a status map marking both NotFound with no timeout.

Call relations: It tests WaitAgentHandler's final-status reporting for absent agents.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager, new); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn wait_agent_times_out_when_status_is_not_final()

Purpose: Checks that legacy wait_agent times out if an agent remains active and does not reach a final status.

Data flow: It starts a thread, waits on it for the minimum timeout, and expects an empty status map with timed_out true.

Call relations: It exercises the normal waiting loop in WaitAgentHandler.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager); 5 external calls (new, default, assert_eq!, json!, from_str).

async fn wait_agent_clamps_short_timeouts_to_minimum()

Purpose: Verifies that legacy wait_agent silently raises very short positive timeouts to the minimum wait time.

Data flow: It asks for 10 ms but wraps the handler in a 50 ms timeout, expecting the wrapper to expire because the handler is still waiting.

Call relations: It tests legacy timeout clamping rather than rejection.

Call graph: calls 4 internal fn (make_session_and_context, function_payload, invocation, thread_manager); 6 external calls (new, from_millis, default, assert!, json!, timeout).

async fn wait_agent_returns_final_status_without_timeout()

Purpose: Checks that legacy wait_agent returns promptly when the target has already reached a final status.

Data flow: It starts and shuts down a thread, waits for the status update, then calls wait_agent and expects Shutdown with timed_out false.

Call relations: It tests WaitAgentHandler's fast path for completed agents.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager); 7 external calls (new, from_secs, default, assert_eq!, json!, from_str, timeout).

async fn multi_agent_v2_wait_agent_returns_summary_for_mailbox_activity()

Purpose: Checks that v2 wait_agent reports a generic completion summary when mailbox mail arrives.

Data flow: It spawns a task, starts wait_agent, enqueues a mailbox message to root, and expects "Wait completed" without exposing message details.

Call relations: It exercises WaitAgentHandlerV2's mailbox notification path.

Call graph: calls 8 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager, root, new); 9 external calls (new, default, new, default, assert_eq!, json!, from_str, spawn, yield_now).

async fn multi_agent_v2_wait_agent_returns_for_already_queued_mail()

Purpose: Verifies that v2 wait_agent returns immediately when relevant mailbox mail is already queued.

Data flow: It spawns a worker, queues a worker-to-root message before calling wait_agent, and expects completion within a short wrapper timeout.

Call relations: It tests WaitAgentHandlerV2's check-before-wait behavior.

Call graph: calls 8 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager, root, new); 9 external calls (new, from_millis, default, new, default, assert_eq!, json!, from_str, timeout).

async fn multi_agent_v2_wait_agent_wakes_on_any_mailbox_notification()

Purpose: Checks that v2 wait_agent wakes when any child sends mailbox mail, not only a particular target.

Data flow: It spawns two workers, starts wait_agent, sends mail from worker_b, and expects the wait to complete.

Call relations: It verifies targetless mailbox waiting across multiple spawned agents.

Call graph: calls 8 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager, root, new); 9 external calls (new, default, new, default, assert_eq!, json!, from_str, spawn, yield_now).

async fn multi_agent_v2_wait_agent_does_not_return_completed_content()

Purpose: Ensures v2 wait_agent does not leak child output content in its result. The wait tool only reports that something happened.

Data flow: It sends mailbox content containing sensitive text, waits, and asserts the result says "Wait completed" while the sensitive text is absent.

Call relations: It protects the output contract of WaitAgentHandlerV2.

Call graph: calls 8 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager, root, new); 10 external calls (new, default, new, default, assert!, assert_eq!, json!, from_str, spawn, yield_now).

async fn multi_agent_v2_interrupt_agent_accepts_task_name_target()

Purpose: Verifies that v2 interrupt_agent can target a spawned agent by task name and interrupts only that agent.

Data flow: It spawns /root/worker, spawns a child under it, interrupts worker, checks the previous status, confirms both agents remain resident, and verifies only the worker got Interrupt.

Call relations: It exercises InterruptAgentHandler's path resolution and non-cascading interrupt behavior.

Call graph: calls 6 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, set_turn_config, thread_manager); 7 external calls (new, default, assert!, assert_eq!, assert_ne!, json!, from_str).

async fn multi_agent_v2_interrupt_agent_accepts_unloaded_task_name_target()

Purpose: Checks that v2 interrupt_agent accepts a task-name target even when that agent is no longer loaded in memory.

Data flow: It uses a SQLite-backed manager, spawns a worker, removes and shuts down the live thread, calls interrupt_agent by task name, then checks database edges and list_agents output.

Call relations: It tests InterruptAgentHandler with persisted metadata rather than only resident threads.

Call graph: calls 8 internal fn (make_session_and_context, with_models_provider_home_and_state_for_tests, expect_text_output, function_payload, invocation, set_turn_config, default_for_tests, from_api_key); 6 external calls (new, default, assert_eq!, init_state_db, json!, from_str).

async fn multi_agent_v2_interrupt_agent_rejects_root_target_and_id()

Purpose: Ensures v2 interrupt_agent cannot target the root agent, whether by /root path or by root thread ID.

Data flow: It enables v2, calls interrupt_agent twice against root, and expects "root is not a spawned agent" both times.

Call relations: It enforces a core safety rule in InterruptAgentHandler.

Call graph: calls 5 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager); 3 external calls (new, assert_eq!, json!).

async fn multi_agent_v2_interrupt_agent_rejects_self_target_by_id()

Purpose: Checks that an agent cannot interrupt itself by using its own thread ID.

Data flow: It creates a child context, calls interrupt_agent targeting that child's ID, and expects a message telling the agent to return its result instead.

Call relations: It tests InterruptAgentHandler's self-target guard for ID addressing.

Call graph: calls 6 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager, try_from); 6 external calls (new, SubAgent, assert_eq!, default, json!, vec!).

async fn multi_agent_v2_interrupt_agent_rejects_self_target_by_task_name()

Purpose: Checks that an agent cannot interrupt itself by using its own task path.

Data flow: It creates a child context, calls interrupt_agent targeting that child's path, and expects the same self-interrupt rejection.

Call relations: It tests InterruptAgentHandler's self-target guard for path addressing.

Call graph: calls 6 internal fn (make_session_and_context, function_payload, invocation, set_turn_config, thread_manager, try_from); 6 external calls (new, SubAgent, assert_eq!, default, json!, vec!).

async fn close_agent_submits_shutdown_and_returns_previous_status()

Purpose: Verifies that close_agent shuts down a live agent and reports what its status was before closing.

Data flow: It starts a thread, records its status, calls close_agent, parses the result, checks success, confirms a Shutdown operation was submitted, and verifies the status is now NotFound.

Call relations: It directly exercises CloseAgentHandler against the test thread manager.

Call graph: calls 5 internal fn (make_session_and_context, expect_text_output, function_payload, invocation, thread_manager); 4 external calls (new, assert_eq!, json!, from_str).

async fn tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed()

Purpose: Tests a larger lifecycle story: closing a child closes its descendants, resuming the child brings that subtree back, and later resuming the parent does not reopen a subtree explicitly closed by the user.

Data flow: It builds a SQLite-backed manager, spawns parent-child-grandchild threads through handlers, closes and resumes the child subtree, closes it again, shuts down the parent, resumes the parent from another thread, and checks which agents are live.

Call relations: It ties together SpawnAgentHandler, CloseAgentHandler, ResumeAgentHandler, persistent thread-store state, and final manager shutdown.

Call graph: calls 10 internal fn (make_session_and_context, new, thread_store_from_config, expect_text_output, function_payload, invocation, parse_agent_id, default_for_tests, from_auth_for_testing, from_api_key); 9 external calls (new, from_secs, default, assert_eq!, assert_ne!, empty_extension_registry, init_state_db, json!, from_str).

async fn build_agent_spawn_config_uses_turn_context_values()

Purpose: Checks that the helper which builds a child spawn config copies the live turn context, not just the base config.

Data flow: It customizes base instructions, developer instructions, compact prompt, shell policy, cwd, sandbox executable, permission profile, and approval policy on a turn, builds the spawn config, and compares it to an expected config.

Call relations: It verifies build_agent_spawn_config, which SpawnAgentHandler relies on before creating child threads.

Call graph: calls 6 internal fn (make_session_and_context, default, from_runtime_permissions_with_enforcement, from_legacy_sandbox_policy, from_legacy_sandbox_policy_for_cwd, from); 3 external calls (from, assert_eq!, tempdir).

async fn build_agent_resume_config_clears_base_instructions()

Purpose: Checks that the helper for resuming an agent clears caller base instructions while preserving live runtime settings.

Data flow: It sets base instructions on the turn config, calls build_agent_resume_config, builds the expected config with base_instructions set to none and runtime values copied, and compares them.

Call relations: It verifies build_agent_resume_config, which ResumeAgentHandler uses when restoring agents.

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

async fn verified_plugin_install_completed_requires_installed_plugin()

Purpose: This test proves that Codex only treats a curated plugin install as complete after the plugin has actually been installed. It guards against a false success state where the plugin appears in the marketplace but is not yet available to use.

Data flow: It starts with a temporary Codex home folder, writes fake curated marketplace data for a plugin named sample, and loads the plugin configuration. Before installation, it asks whether sample@openai-curated is complete and expects false. Then it installs the plugin through PluginsManager, reloads the configuration, asks the same question again, and expects true.

Call relations: The async test runner calls this test. Inside the test, setup helpers create a curated marketplace and feature config, PluginsManager::new creates the plugin installer, and install_plugin performs the install. The assertions frame the important story: marketplace presence alone is not enough, but installation plus refreshed config is enough.

Call graph: calls 5 internal fn (new, curated_plugins_repo_path, write_curated_plugin_sha, write_plugins_feature_config, try_from); 4 external calls (assert!, load_plugins_config, write_openai_curated_marketplace, tempdir).

fn remote_plugin_install_suggestions_skip_core_installed_verification()

Purpose: This test checks how Codex recognizes remote plugin install suggestions. Remote plugins are not installed locally in the same way as core curated plugins, so they should skip the normal local installation verification.

Data flow: It feeds several plugin-like identifiers into the remote-suggestion checker. An identifier ending in @openai-curated-remote should return true, while a normal curated plugin and a plain plugin name should return false.

Call relations: The test runner calls this small unit test. It directly exercises the remote plugin detection helper and uses assertions to lock in the naming rule that later install-request code relies on.

Call graph: 1 external calls (assert!).

fn request_plugin_install_response_persists_only_decline_always_mode()

Purpose: This test makes sure Codex only saves a permanent “do not suggest this again” choice when the user both declines and chooses the “always” option. It prevents accidental permanent disabling from other responses.

Data flow: It builds several fake user responses. The first response is a decline with metadata saying always, and the checker should return true. The other responses change one important detail: accepting instead of declining, choosing session instead of always, or omitting metadata. Each of those should return false.

Call relations: The test runner calls this test, and the test calls the response-checking helper with carefully chosen ElicitationResponse values. The assertions document the contract for the higher-level request flow: only a very specific response should be written permanently.

Call graph: 1 external calls (assert!).

async fn persist_disabled_install_request_writes_connector_config()

Purpose: This test confirms that when a user permanently declines a connector install suggestion, Codex writes that connector into the disabled-tools section of the config file. This is what stops the same connector suggestion from coming back later.

Data flow: It creates a temporary Codex home folder and uses connector_tool to make a fake Google Calendar connector. It passes that connector to the persistence function, then reads config.toml back from disk, parses it, and compares it with the expected config: no discoverable tools and one disabled connector with the connector id.

Call relations: The async test runner calls this test. The test uses connector_tool to build realistic input, then hands it to persist_disabled_install_request, which is the behavior under test. Finally it reads and parses the written file to verify the disk output, not just an in-memory result.

Call graph: calls 1 internal fn (connector_tool); 4 external calls (assert_eq!, read_to_string, tempdir, from_str).

async fn persist_disabled_install_request_writes_plugin_config()

Purpose: This test confirms that permanently declining a plugin install suggestion is saved as a disabled plugin in the user config. It protects the plugin path of the same “do not suggest this again” behavior tested for connectors.

Data flow: It creates a temporary Codex home folder and builds a fake discoverable plugin called slack@openai-curated. It asks the persistence function to save the decline, then reads and parses config.toml. The expected result is a tool suggestion config with one disabled plugin entry and no discoverable entries.

Call relations: The async test runner calls this test. The test constructs a DiscoverableTool::Plugin, passes it to persist_disabled_install_request, and then checks the file that function wrote. This complements the connector test by proving both supported tool kinds are saved correctly.

Call graph: 7 external calls (new, new, assert_eq!, read_to_string, tempdir, from_str, Plugin).

async fn persist_disabled_install_request_dedupes_existing_disabled_tools()

Purpose: This test checks that saving a disabled tool cleans up the disabled-tools list instead of blindly adding another entry. It matters because real config files can contain duplicates, extra spaces, or broken blank entries.

Data flow: It creates a temporary config file that already contains one discoverable plugin, duplicate disabled connector entries, a blank connector entry, and a disabled plugin. Then it saves a permanent decline for the same connector. After reading and parsing the config, it expects a tidy result: the discoverable plugin is preserved, the connector appears only once with clean spacing, the blank entry is gone, and the existing disabled plugin remains.

Call relations: The async test runner calls this test. It uses connector_tool to create the input tool, writes a deliberately messy config file, and then calls persist_disabled_install_request. The final assertion shows the cleanup rules that the persistence code must follow when it updates existing user configuration.

Call graph: calls 1 internal fn (connector_tool); 5 external calls (assert_eq!, read_to_string, write, tempdir, from_str).

fn connector_tool(id: &str, name: &str) -> DiscoverableTool

Purpose: This helper builds a realistic connector-shaped test object from a simple id and display name. It keeps the connector tests focused on the behavior they care about instead of repeating a long AppInfo setup block.

Data flow: It receives an id and name as text. It copies those into an AppInfo structure, fills the optional details with empty values, sets accessibility and enabled flags to fixed test values, wraps the result as a DiscoverableTool::Connector, and returns it.

Call relations: This helper is called by the connector persistence tests: persist_disabled_install_request_writes_connector_config and persist_disabled_install_request_dedupes_existing_disabled_tools. Those tests need a valid connector object before they can call the persistence function, and this helper supplies that object in a consistent way.

Call graph: called by 2 (persist_disabled_install_request_dedupes_existing_disabled_tools, persist_disabled_install_request_writes_connector_config); 3 external calls (new, new, Connector).

fn default_mode_enabled_available_modes() -> Vec<ModeKind>

Purpose: Builds the list of modes where request_user_input is available when the special Default-mode feature is turned on. Tests use it as a small setup helper so they do not repeat the same feature-flag code.

Data flow: It starts with the normal default feature set, turns on the DefaultModeRequestUserInput feature, then asks the shared availability logic for the resulting allowed modes. The output is a list of ModeKind values, such as Default and Plan.

Call relations: This helper calls the feature system’s default setup and then hands those features to request_user_input_available_modes. The mode-related tests use its result to compare behavior with the feature flag enabled.

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

fn default_available_modes() -> Vec<ModeKind>

Purpose: Builds the normal list of modes where request_user_input is available without extra feature flags. Tests use it as the baseline case.

Data flow: It creates the default feature set and passes it to the shared availability function. The output is the list of modes allowed under ordinary settings.

Call relations: This helper calls the same availability function as the feature-enabled helper, but without changing any features first. Later tests use it when checking default unavailable messages and default description text.

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

fn request_user_input_tool_includes_questions_schema()

Purpose: Checks that the tool definition for request_user_input contains the exact input schema expected by clients. This protects the contract between the tool and anything that calls or displays it.

Data flow: The test creates the tool specification with a simple description, then compares the whole result with a hand-written expected structure. The expected structure says the tool accepts a required questions array and an optional autoResolutionMs number, and describes the nested question and option fields.

Call relations: During the test run, Rust’s test runner calls this function. It uses assert_eq! to compare the produced tool specification with the expected one, so a mismatch immediately fails the test.

Call graph: 1 external calls (assert_eq!).

fn normalize_request_user_input_args_clamps_out_of_range_auto_resolution_ms()

Purpose: Checks that too-small or too-large auto-resolution timeouts are corrected into the allowed range. This prevents callers from accidentally asking for an unreasonable wait time.

Data flow: The test builds sample request arguments with one question and a timeout just below the minimum. It expects normalization to raise that timeout to the minimum and mark the question as allowing an automatic “Other” option. Then it repeats the same idea with a timeout just above the maximum and expects it to be lowered to the maximum.

Call relations: The test runner calls this function as part of the suite. Inside, it uses vector construction for sample questions and assert_eq! to check that the normalization result is exactly what the tool promises.

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

fn normalize_request_user_input_args_accepts_auto_resolution_boundaries()

Purpose: Checks that the minimum and maximum allowed timeout values are accepted as-is. This makes sure the safety limits are inclusive, not accidentally too strict.

Data flow: The test creates request arguments with the timeout set to the minimum allowed value and expects normalization to keep that value. It then creates another version with the maximum allowed value and expects that value to stay unchanged too, while also confirming the question is marked for the client-added “Other” option.

Call relations: The test runner calls this function during testing. It builds sample input data and relies on assert_eq! to prove that boundary values pass through normalization without being changed.

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

fn request_user_input_unavailable_messages_respect_default_mode_feature_flag()

Purpose: Checks that the message explaining why request_user_input is unavailable matches the current mode and feature settings. This keeps user-facing error text honest.

Data flow: The test asks for unavailable messages in several modes. With default settings, Plan mode returns no message because it is allowed, while Default, Execute, and Pair Programming return clear unavailable messages. With the Default-mode feature enabled, Default mode also returns no message.

Call relations: The test runner invokes this function, and the function uses the two local mode-list helpers to set up the feature-off and feature-on cases. Each expected result is checked with assert_eq!.

Call graph: 1 external calls (assert_eq!).

fn request_user_input_tool_description_mentions_available_modes()

Purpose: Checks that the tool’s description tells callers which modes can use it. This matters because the description is guidance shown to the model or client before the tool is called.

Data flow: The test first generates the description using the normal available-mode list and expects text saying the tool is only available in Plan mode. Then it generates the description with the Default-mode feature enabled and expects text saying it is available in Default or Plan mode.

Call relations: The Rust test runner calls this function. It depends on the two helper functions that produce available-mode lists, then uses assert_eq! to lock down the exact wording.

Call graph: 1 external calls (assert_eq!).

async fn multi_agent_v2_request_user_input_rejects_subagent_threads()

Purpose: This test checks that a sub-agent thread is not allowed to use request_user_input. It proves the handler returns a clear error instead of opening a user prompt from a non-root thread.

Data flow: The test starts with a fake session and turn, then rewrites the turn’s source so it represents a spawned sub-agent. It builds a tool invocation containing a sample multiple-choice question and passes it into RequestUserInputHandler. The expected result is not an answer from the user, but an error saying the tool can only be used by the root thread.

Call relations: The test uses make_session_and_context to create the starting session state, then constructs supporting objects such as a thread ID, cancellation token, diff tracker, tool name, and JSON payload. It calls the handler’s handle method as the real code would during a tool call, then checks the returned error with assert_eq to lock in the intended behavior.

Call graph: calls 4 internal fn (make_session_and_context, default, new, plain); 8 external calls (new, new, new, SubAgent, assert_eq!, json!, panic!, new).

fn windows_shell_guidance_description() -> String

Purpose: Builds the Windows-specific extra guidance text used in expected tool descriptions. It wraps the shared Windows shell guidance with blank lines so the final description matches the production formatting.

Data flow: It takes no input directly. It reads the shared Windows shell guidance text from the surrounding module, prefixes it with two newline characters, and returns the combined string.

Call relations: The Windows branch of shell_command_tool_matches_expected_spec calls this helper when it needs to construct the exact expected description for the PowerShell command tool. The helper delegates the actual guidance content to windows_shell_guidance and only adds the formatting around it.

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

fn has_parameter(tool: &ToolSpec, parameter_name: &str) -> bool

Purpose: Checks whether a generated tool specification includes a named input parameter. This lets tests ask a simple yes-or-no question without manually digging through the nested schema structure.

Data flow: It receives a ToolSpec and a parameter name. It converts the whole tool specification into JSON, looks under parameters.properties.<parameter name>, and returns true if that entry exists or false if it does not.

Call relations: This is a small test helper for checking the shape of a tool specification. It uses JSON serialization as a convenient way to inspect the nested parameter map, then hands back a boolean result that assertions can use.

Call graph: 2 external calls (format!, to_value).

fn exec_command_tool_matches_expected_spec()

Purpose: Verifies that the exec_command tool is advertised exactly as expected. This matters because exec_command is the lower-level command runner, including options for working directory, shell choice, terminal behavior, output limits, and login-shell behavior.

Data flow: The test asks the real code to create an exec_command tool with login shells allowed and permission approvals disabled. It then builds the expected description, parameter schema, required fields, and output schema by hand. The final assertion compares the real tool and expected tool, and the test fails if any part differs.

Call relations: During the test run, this function exercises the production tool-building path for exec_command. It uses schema helpers such as string, number, and boolean schema builders, adds approval-related parameters, accounts for Windows-specific description text with a platform check, and then uses an exact equality assertion as the contract check.

Call graph: calls 3 internal fn (boolean, number, string); 4 external calls (from, assert_eq!, cfg!, format!).

fn exec_command_tool_can_hide_shell_parameter()

Purpose: Checks that the exec_command tool can be created without exposing the shell input parameter. This is useful when the system wants callers to run commands but not choose the shell binary themselves.

Data flow: The test creates an exec_command tool with environment IDs and the shell parameter both excluded. It then inspects the resulting tool schema: shell should be absent, while the basic cmd parameter should still be present.

Call relations: This test focuses on one configurable part of the exec_command tool factory. After creating the tool with the relevant flags, it relies on boolean assertions to confirm that hiding shell does not remove the core command input.

Call graph: 1 external calls (assert!).

fn write_stdin_tool_matches_expected_spec()

Purpose: Verifies that the write_stdin tool has the exact expected public shape. This tool is used to send text into an already-running command session and then read back recent output.

Data flow: The test creates the real write_stdin tool. It separately builds the expected parameter schema, including the required session identifier plus optional characters to write, wait time, and output budget. It compares the real and expected tool specifications exactly.

Call relations: This test runs as part of the tool contract suite. It uses schema-building helpers to describe each allowed input, then passes the completed expected schema into an equality assertion against the production result.

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

fn request_permissions_tool_includes_full_permission_schema()

Purpose: Confirms that the request_permissions tool includes the complete permission request schema. This matters because callers need a reliable way to ask for extra rights, such as broader file or command access, during a turn.

Data flow: The test creates the real permission-request tool with a chosen description. It builds the expected schema with an optional reason, an optional environment identifier, and the required permissions object. It then checks that the generated tool exactly matches that expected structure and has no output schema.

Call relations: This test exercises the production permission-tool builder. It pulls in the shared permission profile schema for the important permissions field, then uses an exact equality assertion to make sure the full permission shape is exposed.

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

fn shell_command_tool_matches_expected_spec()

Purpose: Verifies that the higher-level shell_command tool is described exactly as expected. This tool runs a shell command and returns its output, so its public instructions must be especially clear about command text, working directory, timeout, and login-shell behavior.

Data flow: The test creates the real shell_command tool with login shells allowed and permission approvals disabled. It builds the expected description differently depending on the operating system: Windows gets PowerShell examples and extra guidance, while other systems get a shorter shell-command description. It then constructs the expected parameter schema and compares the whole tool specification with the real one.

Call relations: This test is part of the same contract-checking suite as the other tool spec tests. On Windows it calls windows_shell_guidance_description to include the shared extra guidance. It also uses schema helpers and approval-parameter helpers before handing the completed expected object to an exact equality assertion.

Call graph: calls 4 internal fn (windows_shell_guidance_description, boolean, number, string); 3 external calls (from, assert_eq!, cfg!).

fn commands_generated_by_shell_command_handler_can_be_matched_by_is_known_safe_command()

Purpose: This test makes sure the command strings built for different shells can still be recognized by the safety checker when the original command is harmless. It matters because the handler wraps commands in shell-specific ways, and that wrapping must not confuse the safety logic.

Data flow: It starts with a few shell descriptions, such as Bash and Zsh, and uses PowerShell variants too if they are installed on the machine running the test. For each available shell, it sends a simple directory-listing command into the helper check. The result is not a returned value, but a set of assertions that must pass: both login-shell and non-login-shell forms must be considered known safe.

Call relations: This is the top-level test for safe-command recognition. It calls assert_safe to do the repeated check for each shell, and it asks the PowerShell lookup helpers whether PowerShell executables are available before testing those cases.

Call graph: calls 3 internal fn (assert_safe, try_find_powershell_executable_blocking, try_find_pwsh_executable_blocking); 1 external calls (from).

fn assert_safe(shell: &Shell, command: &str)

Purpose: This helper avoids repeating the same safety check for every shell. Given a shell and a command, it confirms that the shell-wrapped version is still accepted by the known-safe-command detector.

Data flow: It receives a shell description and a raw command string. It asks the shell to turn that command into executable arguments twice: once as a login shell and once as a non-login shell. Each argument list is then fed into the safety checker, and the function succeeds only if both checks pass.

Call relations: It is called by commands_generated_by_shell_command_handler_can_be_matched_by_is_known_safe_command whenever that test wants to validate another shell. It sits between shell command construction and the safety-checking function, making sure those two parts agree.

Call graph: called by 1 (commands_generated_by_shell_command_handler_can_be_matched_by_is_known_safe_command); 1 external calls (assert!).

async fn shell_command_handler_to_exec_params_uses_session_shell_and_turn_context()

Purpose: This test checks that a shell command request is translated into execution settings using the current session and turn context. In plain terms, it verifies that the handler uses the right shell, folder, environment, timeout, network setting, sandbox permission, and justification.

Data flow: It creates a fake session and turn context, then builds a shell command request with a command, relative working directory, timeout, sandbox setting, and justification text. It independently calculates what the command arguments, working directory, and environment should be. Then it asks ShellCommandHandler::to_exec_params to build the real execution parameters and compares each important field to the expected value.

Call relations: This test uses make_session_and_context to get realistic test state, create_env to compute the expected environment, and ShellCommandHandler::to_exec_params as the behavior under test. It proves that the handler correctly combines user input with session-level and turn-level settings before a command would be run.

Call graph: calls 3 internal fn (create_env, make_session_and_context, to_exec_params); 1 external calls (assert_eq!).

fn shell_command_handler_respects_explicit_login_flag()

Purpose: This test verifies that when code explicitly asks for a login shell or a non-login shell, the handler follows that choice. This matters because login shells can load extra user startup configuration, so the distinction is intentional.

Data flow: It creates a Bash shell description and asks ShellCommandHandler::base_command to build one command with login-shell mode enabled and another with it disabled. For each case, it compares the handler’s result to the shell’s own expected argument-building method. The output is a pair of passing assertions showing that the requested mode was preserved.

Call relations: This test focuses on ShellCommandHandler::base_command. It compares that function against the shell’s lower-level command-building behavior, so it confirms the handler is not silently changing the caller’s login-shell choice.

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

async fn shell_command_handler_defaults_to_non_login_when_disallowed()

Purpose: This test checks the safe default when login shells are disabled by configuration. If the request does not explicitly ask for a login shell, the handler should still run the command, but as a non-login shell.

Data flow: It creates a test session and turn context, then builds a command request with no explicit login preference. It calls ShellCommandHandler::to_exec_params while telling it login shells are not allowed. The resulting executable command is compared with the session shell’s non-login form of the same raw command.

Call relations: This test uses make_session_and_context to supply realistic state and then exercises ShellCommandHandler::to_exec_params. It complements the rejection test by showing that disabling login shells does not block ordinary shell commands.

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

fn shell_command_handler_rejects_login_when_disallowed()

Purpose: This test makes sure the handler refuses an explicit request for a login shell when configuration has disabled login shells. It protects the configuration rule from being bypassed.

Data flow: It calls ShellCommandHandler::resolve_use_login_shell with an explicit request for login-shell mode while login shells are not allowed. Instead of a normal result, it expects an error. The test then checks that the error message explains that login shells are disabled by configuration.

Call relations: This test goes directly to the decision function, ShellCommandHandler::resolve_use_login_shell, rather than building full execution parameters. It verifies the rule at the point where the handler decides whether login-shell mode may be used.

Call graph: calls 1 internal fn (resolve_use_login_shell); 1 external calls (assert!).

async fn shell_command_pre_tool_use_payload_uses_raw_command()

Purpose: This test checks the message sent to pre-use hooks before a shell command runs. It makes sure the hook receives the raw command text the user requested, not a shell-wrapped version.

Data flow: It builds a tool payload containing a command string, creates a test session and turn context, and constructs a shell command handler. It then creates a tool invocation and asks the handler for its pre-tool-use payload. The expected result is a hook payload named like the Bash hook, with JSON input containing exactly the original command.

Call relations: This test uses make_session_and_context to build the invocation context and ShellCommandHandler::from to create the handler. It then exercises the handler’s pre-use hook payload method, confirming that hook systems get clear user-facing command input before execution.

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

async fn build_post_tool_use_payload_uses_tool_output_wire_value()

Purpose: This test checks the message sent to post-use hooks after a shell command finishes. It verifies that the hook receives the tool output value meant for the wire format, which is the serialized value other parts of the system expect to see.

Data flow: It builds a command payload and a fake successful tool output whose post-use response is the JSON string shell output. It then creates a handler, session, turn context, and tool invocation. When it asks for the post-tool-use payload, it expects a payload containing the hook name, the original call ID, the raw command as input, and the chosen output value as the response.

Call relations: This test sets up a full ToolInvocation and calls the handler’s post-use hook payload method. It shows how the shell command handler connects the original tool call with the final output value so hook code can observe what happened after execution.

Call graph: calls 4 internal fn (make_session_and_context, from, new, plain); 6 external calls (new, new, assert_eq!, json!, new, vec!).

async fn invocation_for_payload(
    tool_name: &str,
    call_id: &str,
    payload: ToolPayload,
) -> ToolInvocation

Purpose: This helper builds a realistic tool invocation for tests. It saves the tests from repeating all the session, turn, cancellation, tracking, tool name, and payload setup every time they need to call a handler.

Data flow: It takes a tool name, a call id, and a tool payload. It creates a fresh test session and turn, adds a new cancellation token, a new diff tracker protected by a mutex (a lock that prevents overlapping access), and wraps the tool name in the project’s tool-name type. It returns a complete ToolInvocation that looks like one the real system would pass to a tool handler.

Call relations: Several post-tool-use tests call this helper before asking ExecCommandHandler or WriteStdinHandler to build hook output. It relies on make_session_and_context to supply a valid test session and uses small constructors such as plain and new to fill in the invocation fields.

Call graph: calls 3 internal fn (make_session_and_context, new, plain); called by 5 (exec_command_post_tool_use_payload_skips_running_sessions, exec_command_post_tool_use_payload_uses_output_for_interactive_completion, exec_command_post_tool_use_payload_uses_output_for_noninteractive_one_shot_commands, write_stdin_post_tool_use_payload_keeps_parallel_session_metadata_separate, write_stdin_post_tool_use_payload_uses_original_exec_call_id_and_command_on_completion); 3 external calls (new, new, new).

fn test_get_command_uses_default_shell_when_unspecified() -> anyhow::Result<()>

Purpose: This test proves that a command without a shell field still gets wrapped in a usable shell command. Without this behavior, a simple request like echo hello might not run consistently.

Data flow: It starts with JSON containing only cmd. After parsing, it checks that no explicit shell was supplied. It then resolves the command using the default user shell and direct execution mode, and confirms that the final command array contains the original text echo hello in the expected shell-command position.

Call relations: During the test run, this function calls default_user_shell and creates shared shell data before checking the result with assertions. It exercises the command-building path used when callers leave shell choice to the system.

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

fn test_get_command_respects_explicit_bash_shell() -> anyhow::Result<()>

Purpose: This test checks that when the caller asks for Bash explicitly, the command builder honors that request. It also guards against accidentally dropping the user’s command while adding shell-specific flags.

Data flow: It feeds in JSON with cmd and shell set to /bin/bash. After parsing, it verifies that the shell value survived parsing, resolves the command, and checks that the final command still ends with echo hello. If the produced command looks like a PowerShell command, it also checks that the no-profile flag is present.

Call relations: This test uses the default shell only as background context while focusing on an explicit shell request. Its assertions confirm that the command-building logic keeps the caller’s requested shell and command aligned.

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

fn test_get_command_respects_explicit_powershell_shell() -> anyhow::Result<()>

Purpose: This test makes sure an explicit PowerShell executable is recognized as PowerShell, even when it is given as a path. That matters because PowerShell needs different command-line wrapping than Unix-style shells.

Data flow: It creates a temporary fake PowerShell file, using a platform-appropriate name, then places that path into the JSON arguments. After parsing and command resolution, it checks that the shell path was preserved, the command text appears in the shell invocation, and the detected shell type is PowerShell.

Call relations: The test uses temporary file creation to make shell detection realistic without depending on a real system PowerShell location. It calls the same command-resolution path as production code, then uses assertions to verify the shell classification.

Call graph: calls 1 internal fn (default_user_shell); 6 external calls (new, assert_eq!, cfg!, json!, write, tempdir).

fn test_get_command_respects_explicit_cmd_shell() -> anyhow::Result<()>

Purpose: This test checks support for Windows cmd as an explicitly requested shell. It protects the command builder from treating cmd like an unknown or unsupported shell name.

Data flow: It parses JSON containing cmd and shell: cmd, verifies that the parsed shell is exactly cmd, resolves the command, and confirms that the requested command text appears in the resulting shell command array.

Call relations: The test supplies the default user shell as context but expects the explicit cmd choice to take priority. Its assertions pin down the behavior for callers who request the Windows command shell by name.

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

fn test_get_command_rejects_explicit_login_when_disallowed() -> anyhow::Result<()>

Purpose: This test confirms that the command builder refuses a login shell request when configuration says login shells are disabled. A login shell can load extra startup files, so allowing it accidentally could change behavior or bypass policy.

Data flow: It parses JSON where login is set to true, then asks for command resolution with allow_login_shell set to false. Instead of a command, it expects an error message saying that login shells are disabled by config.

Call relations: This function exercises the failure branch of command resolution. It uses the default shell setup, then checks with an assertion that the rejection is clear and specific.

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

fn test_get_command_rejects_explicit_shell_in_zsh_fork_mode() -> anyhow::Result<()>

Purpose: This test makes sure callers cannot choose their own shell when local execution is configured for zsh-fork mode. In that mode, the system needs to use its controlled zsh path, so an explicit shell would conflict with the execution design.

Data flow: It parses a command that asks for /bin/bash, builds a zsh-fork shell-mode configuration with absolute paths for zsh and the exec wrapper, and tries to resolve the command. The expected output is an error explaining that shell is not supported for local zsh-fork execution.

Call relations: The test constructs the special shell mode using absolute-path helpers and the ZshFork configuration. It then verifies that command resolution rejects the incompatible explicit shell instead of silently ignoring or honoring it.

Call graph: calls 2 internal fn (default_user_shell, from_absolute_path); 4 external calls (new, assert!, cfg!, ZshFork).

async fn shell_mode_for_environment_uses_direct_mode_for_remote_environments() -> anyhow::Result<()>

Purpose: This test checks that zsh-fork mode is used only for local environments, while remote environments use direct execution mode. That avoids trying to apply a local shell-wrapper setup to a remote exec server that may not have it.

Data flow: It builds a zsh-fork shell-mode configuration, then creates one local test environment and one remote test environment with a remote exec server URL. It asks which shell mode should apply to each environment. The local environment keeps zsh-fork; the remote environment becomes Direct.

Call relations: This async test uses environment test constructors and absolute-path helpers, then compares the selected shell modes with assertions. It documents the handoff point where environment type changes execution strategy.

Call graph: calls 3 internal fn (create_for_tests, default_for_tests, from_absolute_path); 3 external calls (assert_eq!, cfg!, ZshFork).

async fn exec_command_pre_tool_use_payload_uses_raw_command()

Purpose: This test proves that before an exec command runs, the hook payload contains the user’s raw command text. That lets hook consumers inspect the actual requested command, not a rewritten shell wrapper.

Data flow: It creates a function-style tool payload with cmd: printf exec command, builds a test session and turn, and asks the default exec command handler for its pre-tool-use payload. The expected result is a Bash-named hook payload whose input is { "command": "printf exec command" }.

Call relations: The test builds the invocation inline using make_session_and_context, then calls ExecCommandHandler’s pre-hook method. The assertion shows what information is handed to the hook system before command execution begins.

Call graph: calls 2 internal fn (make_session_and_context, default); 2 external calls (assert_eq!, json!).

async fn exec_command_pre_tool_use_payload_skips_write_stdin()

Purpose: This test confirms that write_stdin does not produce a pre-use hook payload. Writing characters into an already-running process is not the same as starting a new shell command, so there is no new raw command to announce.

Data flow: It creates a payload containing chars, builds a write_stdin invocation, and asks WriteStdinHandler for a pre-tool-use payload. The expected result is None, meaning no hook notification is produced before the write.

Call relations: The test uses make_session_and_context to form a realistic invocation, then checks that the write-stdin handler stays quiet at the pre-hook stage. This keeps hook behavior focused on command starts rather than every input write.

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

async fn exec_command_post_tool_use_payload_uses_output_for_noninteractive_one_shot_commands()

Purpose: This test checks that a completed non-interactive command produces a post-use hook payload containing its output. A one-shot command is expected to finish immediately, so its result can be reported to hook consumers.

Data flow: It creates an exec payload for echo three with tty set to false, then creates a fake completed output object with raw bytes three, exit code 0, and the original hook command. After building a realistic invocation, it asks the exec handler for a post-tool-use payload. The result includes the original command and the text output three.

Call relations: This test calls invocation_for_payload to prepare the invocation, then hands both invocation and output to ExecCommandHandler. The assertion confirms that completed command output flows into the hook response.

Call graph: calls 2 internal fn (default, invocation_for_payload); 3 external calls (assert_eq!, json!, from_millis).

async fn exec_command_post_tool_use_payload_uses_output_for_interactive_completion()

Purpose: This test verifies that an interactive command also produces a post-use hook payload once it has completed. Interactive mode may keep a process open, but when there is an exit code and no running process id, the result should be reportable.

Data flow: It builds an exec payload for echo three with tty set to true, then supplies fake output showing the command has finished: raw bytes three, exit code 0, and no process id. The handler turns that into a hook payload with the command and output text.

Call relations: Like the non-interactive test, it uses invocation_for_payload and the default exec handler. It covers the completion path for interactive commands, proving that interactivity alone does not suppress hook reporting.

Call graph: calls 2 internal fn (default, invocation_for_payload); 3 external calls (assert_eq!, json!, from_millis).

async fn exec_command_post_tool_use_payload_skips_running_sessions()

Purpose: This test makes sure the exec handler does not send a final post-use hook payload while an interactive session is still running. Reporting too early would make partial output look like the command’s final result.

Data flow: It creates an exec payload and a fake output object where process_id is present and exit_code is missing. That combination means the process is still alive. When passed to the handler, the result is None, so no completion hook is emitted.

Call relations: The test gets a realistic invocation from invocation_for_payload, then checks the default exec handler’s decision. It protects the larger flow from confusing in-progress session output with completed command output.

Call graph: calls 2 internal fn (default, invocation_for_payload); 3 external calls (assert_eq!, json!, from_millis).

async fn write_stdin_post_tool_use_payload_uses_original_exec_call_id_and_command_on_completion()

Purpose: This test checks that when write_stdin causes or observes an interactive command finishing, the post-use hook is tied back to the original exec command, not to the later stdin-write call. This keeps hook records attached to the command that actually ran.

Data flow: It builds a write_stdin payload for a session, then supplies completed output whose event call id is exec-call-45 and whose hook command is sleep 1; echo finished. The write-stdin handler returns a post-use payload using that original exec call id, the original command, and the finished output text.

Call relations: The test uses invocation_for_payload to represent the stdin write, then calls WriteStdinHandler’s post-hook method. It confirms that completion information is handed off under the original exec call identity.

Call graph: calls 1 internal fn (invocation_for_payload); 3 external calls (assert_eq!, json!, from_millis).

async fn write_stdin_post_tool_use_payload_keeps_parallel_session_metadata_separate()

Purpose: This test protects against mixing up metadata from two parallel interactive sessions. If two commands finish around the same time, each hook payload must keep its own command, call id, and output.

Data flow: It creates one shared write-stdin-style payload and two separate completed outputs: one for an alpha command and one for a beta command. It builds separate invocations and asks the handler for post-use payloads in beta-then-alpha order. The returned payloads preserve each output’s own exec call id, command text, and response text.

Call relations: This test calls invocation_for_payload twice and then uses WriteStdinHandler for both outputs. The final assertion shows that the handler follows the metadata carried by each output rather than relying on shared or stale session state.

Call graph: calls 1 internal fn (invocation_for_payload); 3 external calls (assert_eq!, json!, from_millis).

fn image_generation_tool_matches_expected_spec()

Purpose: This test makes sure that creating an image generation tool keeps the requested image format. It protects against accidentally changing the tool description sent for image generation.

Data flow: It starts with the input format "png". The test asks the tool-building code to create an image generation specification, then compares the result with the expected specification that contains the same "png" format. Nothing is changed outside the test; it either passes or fails.

Call relations: During the test run, the test framework calls this function. Inside it, the generated tool specification is checked with an equality assertion so any mismatch is reported immediately.

Call graph: 1 external calls (assert_eq!).

fn web_search_tool_preserves_configured_options()

Purpose: This test makes sure that web search settings are not lost or altered when the web search tool specification is created. It verifies the enabled mode, allowed domain filter, user location, context size, and requested content types.

Data flow: It builds a set of web search options: live search is enabled, only example.com is allowed, the user location is approximately in the US with a Los Angeles time zone, the search context size is low, and both text and image search are requested. The tool-building code turns those options into a web search specification. The test compares that output with the exact expected structure.

Call relations: The test framework calls this during the test suite. The function relies on an equality assertion to confirm that the tool builder passes configuration through to the final API-facing shape without dropping or rewriting important fields.

Call graph: 1 external calls (assert_eq!).

fn web_search_tool_is_absent_when_disabled()

Purpose: This test confirms that disabling web search really removes the web search tool. It prevents a serious mistake where web access could remain available even after configuration says it should be off.

Data flow: It starts with web search options where the mode is set to disabled and no extra web search configuration is supplied. The tool-building code is asked to create a web search tool. The expected result is no tool at all, represented by None, and the test checks for that result.

Call relations: The test framework runs this function as part of the test suite. It uses an equality assertion to verify that the disabled setting stops the web search tool from being produced.

Call graph: 1 external calls (assert_eq!).

fn custom_tool_calls_should_roundtrip_as_custom_outputs()

Purpose: This test makes sure a result from a custom tool comes back as a custom-tool output, not as an ordinary function output. It protects the distinction between different tool families.

Data flow: It starts with a custom-tool payload and a text result saying "patched" with success set to true. The result is converted into a response item. The test then checks that the response still has the same call id, carries the text body, has no separate content items, and keeps the success value.

Call relations: During the test run, the Rust test harness calls this test. The test uses the normal text-output constructor and then exercises the response conversion path, with assertions acting as the guardrails for the expected shape.

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

fn function_payloads_remain_function_outputs()

Purpose: This test confirms that ordinary function-call payloads are returned as ordinary function-call outputs. It prevents custom-tool behavior from accidentally leaking into the function-call path.

Data flow: It builds a function payload with empty JSON arguments and a simple text output of "ok". After conversion to a response item, it checks that the output is tied to the same call id, contains the same text, has no extra content-item list, and is marked successful.

Call relations: The test harness runs this as part of the tool context tests. It follows the same conversion route real function tool results use before they are sent back to the model.

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

fn mcp_code_mode_result_serializes_full_call_tool_result()

Purpose: This test verifies that an MCP tool result used in code mode keeps the full raw tool result as JSON. Code mode needs the structured data, not just a simplified text summary.

Data flow: It creates a fake MCP result with text content, structured content, an error flag, and metadata. It asks for the code-mode result and checks that the output JSON includes all of those pieces under the expected field names.

Call relations: The test is run by the test harness and focuses on the code-mode serialization path for MCP results. It makes sure the conversion hands forward the complete MCP result instead of trimming it down for display.

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

fn mcp_tool_output_response_item_includes_wall_time()

Purpose: This test checks that normal MCP tool output includes how long the tool took. That timing header gives the model and logs useful context about the tool call.

Data flow: It builds an MCP output with one text content item, a 1.25 second wall time, and a byte limit. After converting it into a response item, it checks the call id and success flag, then reads the text body and confirms it starts with a wall-time header followed by JSON output.

Call relations: The test harness calls this test to exercise the normal response-item path for MCP tool output. The path formats timing information, serializes the MCP content, and hands that formatted text into a function-call output.

Call graph: 7 external calls (assert_eq!, json!, panic!, Bytes, from_str, from_millis, vec!).

fn mcp_tool_output_response_item_truncates_large_structured_content()

Purpose: This test makes sure very large structured MCP output is shortened before it is put into a normal response item. That prevents oversized tool results from flooding the model context.

Data flow: It creates an MCP result with large structured content and a small byte limit. After conversion, it checks that the text starts with the wall-time header, includes a clear truncation notice, and does not include the fallback plain content that should be ignored when structured content exists.

Call relations: The test harness runs this against the MCP formatting path used for normal conversation responses. It verifies that the truncation policy is applied before the result is handed back as a function-call output.

Call graph: 8 external calls (assert!, assert_eq!, json!, panic!, Bytes, json!, from_millis, vec!).

fn mcp_tool_output_response_item_preserves_content_items()

Purpose: This test confirms that MCP output containing an image stays as content items instead of being reduced to plain text. This matters because flattening the result would lose the image.

Data flow: It creates an MCP result whose content is an image encoded as data. Conversion produces a response item with a text timing header plus an image item. The test checks both the structured content-item list and the plain text body derived from the text part.

Call relations: The test harness calls this when checking MCP response formatting. It exercises the branch that turns MCP media content into model-readable content items, while still keeping a text header for preview or fallback use.

Call graph: 6 external calls (assert_eq!, json!, panic!, Bytes, from_millis, vec!).

fn mcp_tool_output_code_mode_result_stays_raw_call_tool_result()

Purpose: This test ensures that code-mode MCP output is not shortened or reformatted into the normal chat-style response. Code mode should receive the raw structured result even when it is large.

Data flow: It builds an MCP result with large structured content and a very small truncation limit. Instead of converting it to a response item, it asks for the code-mode result and checks that the full original structured content is still present.

Call relations: The test harness runs this to protect the separate code-mode path. It shows that truncation used for normal responses does not affect the raw JSON handed to code-mode consumers.

Call graph: 6 external calls (assert_eq!, json!, Bytes, json!, from_millis, vec!).

fn custom_tool_calls_can_derive_text_from_content_items()

Purpose: This test checks that a custom-tool output made from content items can still provide useful plain text. Text parts are combined, while non-text parts such as images are preserved separately.

Data flow: It creates content containing text, an image, and more text, then converts it as a custom-tool output. The test checks that the response keeps the full content-item list, derives the plain text as "line 1\nline 2", keeps the call id, and preserves success.

Call relations: The test harness calls this to exercise content-based output construction. It connects the content-item storage path with the response conversion path, proving that both rich content and plain-text fallback survive.

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

fn tool_search_payloads_roundtrip_as_tool_search_outputs()

Purpose: This test verifies that a tool-search request produces a tool-search response, including the found tool descriptions. Tool search is how the system can tell the model what tools are available to load or use.

Data flow: It starts with a search payload asking for calendar tools and a fake search result containing one function tool named "create_event". After conversion, it checks that the response has the right call id, completed status, client execution label, and serialized tool definition.

Call relations: The test harness runs this to cover the tool-search conversion path. It makes sure search results are handed back in the special search-output format rather than being mistaken for ordinary function output.

Call graph: 3 external calls (assert_eq!, panic!, vec!).

fn log_preview_uses_content_items_when_plain_text_is_missing()

Purpose: This test checks that logs can still show a readable preview when an output was built from content items instead of plain text. It keeps logs useful even for richer output formats.

Data flow: It creates a content-based output containing one text item. The test asks for the log preview and also directly converts the content items to text, confirming both produce "preview".

Call relations: The test harness calls this to cover the preview path used for logging or telemetry. It ties the content-item representation to the helper that extracts readable text from it.

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

fn telemetry_preview_returns_original_within_limits()

Purpose: This test confirms that short telemetry previews are left unchanged. Telemetry here means small diagnostic data recorded for observing system behavior.

Data flow: It passes a short string into the preview function. Because the string is already within the allowed size, the same string comes back.

Call relations: The test harness runs this as the simplest case for telemetry previewing. It protects the rule that truncation should only happen when it is actually needed.

Call graph: 1 external calls (assert_eq!).

fn telemetry_preview_truncates_by_bytes()

Purpose: This test makes sure telemetry previews are shortened when they exceed the byte limit. A byte is a unit of stored text size, so this protects logs from growing too large.

Data flow: It creates a string longer than the maximum preview byte count and sends it through the preview function. The returned preview must contain a truncation notice and stay within the expected maximum size plus that notice.

Call relations: The test harness calls this to check the byte-size limit in the telemetry preview helper. It verifies that oversized data is reduced before it would be recorded.

Call graph: 1 external calls (assert!).

fn telemetry_preview_truncates_by_lines()

Purpose: This test checks that telemetry previews are also shortened when they have too many lines. This keeps multi-line output from taking over diagnostics.

Data flow: It builds text with more lines than allowed and passes it to the preview function. The result must have no more than the allowed number of content lines plus a final truncation notice.

Call relations: The test harness runs this alongside the byte-limit test. Together they prove the preview helper controls both width by size and height by line count.

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

fn exec_command_tool_output_formats_truncated_response()

Purpose: This test verifies the user-facing format for command execution output when the output has been shortened. It checks that important command details are still shown.

Data flow: It builds a fake command result with a chunk id, wall time, exit code, original token count, raw output, and a maximum output-token limit. After conversion, it checks that the response is successful and that the text includes the chunk id, timing, exit code, original token count, output section, and a truncation message.

Call relations: The test harness calls this to exercise the command-output response path. The conversion formats process details and truncated output into the function-call response that the model would read after running a command.

Call graph: 5 external calls (assert_eq!, assert_regex_match, panic!, Tokens, from_millis).

fn tool_name(&self) -> codex_tools::ToolName

Purpose: Returns the fake tool's name. Tests use this so the fake handler behaves like a real tool that can tell the registry what it is called.

Data flow: It reads the stored tool name from the TestHandler, makes a copy of it, and returns that copy. Nothing else is changed.

Call relations: This is part of the ToolExecutor interface used by registry code and tests. When a test or registry path needs the handler's identity, this method supplies the name without exposing the handler's internal storage.

Call graph: 1 external calls (clone).

fn spec(&self) -> codex_tools::ToolSpec

Purpose: Builds a basic tool description for the fake tool. A tool description tells the surrounding system what the tool is called and what kind of input shape it accepts.

Data flow: It reads the handler's stored tool name, passes it to test_spec, and returns the simple tool specification that helper creates.

Call relations: This method lets TestHandler satisfy the same interface as real tools. It hands off the actual construction work to test_spec so all fake tools in this file share the same simple specification format.

Call graph: calls 1 internal fn (test_spec).

fn handle(&self, _invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Pretends to run a tool and always produces a successful text result of ok. This gives tests a dependable tool result without doing any real work.

Data flow: It receives a tool invocation but ignores its contents. It creates an asynchronous result containing a text output marked as successful, boxes it behind the common tool-output interface, and returns it as a future.

Call relations: Registry dispatch can call this just like it would call a real tool handler. The returned output is then used by tests that care about hook payloads, response conversion, or dispatch behavior rather than the tool's actual job.

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

fn tool_name(&self) -> codex_tools::ToolName

Purpose: Returns the name of the lifecycle test tool. This lets the registry identify which fake lifecycle handler is being run.

Data flow: It reads the stored tool name, clones it, and returns the clone. The handler itself is not changed.

Call relations: This is the lifecycle-focused version of the normal tool-name method. Registry and test setup code can treat this fake handler as a normal tool because it provides the expected identity method.

Call graph: 1 external calls (clone).

fn spec(&self) -> codex_tools::ToolSpec

Purpose: Builds a simple tool description for a lifecycle test handler. The description is only detailed enough for registry tests.

Data flow: It takes the handler's stored tool name, sends it to test_spec, and returns the resulting generic function-tool specification.

Call relations: Like TestHandler::spec, this keeps test tool setup consistent. It relies on test_spec so lifecycle tests do not need to repeat the same specification-building code.

Call graph: calls 1 internal fn (test_spec).

fn handle(&self, _invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Starts the fake lifecycle handler's asynchronous work. It exists so the handler can be called through the same tool interface as real tools.

Data flow: It receives a tool invocation but does not inspect it directly. It wraps handle_call in an asynchronous future and returns that future to the caller.

Call relations: Registry dispatch calls this method when running the fake lifecycle tools. The real success-or-failure decision is delegated to LifecycleTestHandler::handle_call, which keeps this interface method small.

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

async fn handle_call(
        &self,
    ) -> Result<Box<dyn crate::tools::context::ToolOutput>, FunctionCallError>

Purpose: Produces the configured result for a lifecycle test tool: either an ok output with a chosen success flag, or a deliberate error. This lets tests check how the registry reports both completed and failed tool calls.

Data flow: It reads the handler's stored result setting. If the setting is Ok, it creates a text output saying ok and attaches the configured success value. If the setting is Err, it returns an error message saying the handler failed.

Call relations: It is called by LifecycleTestHandler::handle during dispatch. Its output or error is what drives the lifecycle notification test, because the registry turns those outcomes into finished-tool events.

Call graph: calls 1 internal fn (from_text); called by 1 (handle); 3 external calls (new, clone, RespondToModel).

fn test_spec(tool_name: &codex_tools::ToolName) -> codex_tools::ToolSpec

Purpose: Creates a minimal function-tool specification for a named test tool. It avoids repeating the same boilerplate in each fake handler.

Data flow: It receives a tool name, copies the display name into a simple function-tool description, uses a default empty JSON schema for parameters, and returns the completed tool specification.

Call relations: Both TestHandler::spec and LifecycleTestHandler::spec call this helper. It acts as the shared recipe for making fake tools look enough like real tools for registry tests.

Call graph: called by 2 (spec, spec); 2 external calls (default, Function).

fn on_tool_start(
        &'a self,
        input: codex_extension_api::ToolStartInput<'a>,
    ) -> codex_extension_api::ToolLifecycleFuture<'a>

Purpose: Records that a tool call has started. This gives tests a simple way to verify that lifecycle extensions are notified at the right time.

Data flow: It receives a start-event input containing the call id and tool name. It copies those values into a Start record, locks the shared record list, and appends the new record.

Call relations: The extension lifecycle system calls this when registry dispatch begins a tool call. Later, the lifecycle test reads the shared list to check that this start event appeared before the matching finish event.

Call graph: 2 external calls (clone, pin).

fn on_tool_finish(
        &'a self,
        input: codex_extension_api::ToolFinishInput<'a>,
    ) -> codex_extension_api::ToolLifecycleFuture<'a>

Purpose: Records that a tool call has finished, including whether it completed or failed. This lets tests confirm the registry reports final outcomes correctly.

Data flow: It receives finish-event input with the call id, tool name, and outcome. It copies those into a Finish record, locks the shared record list, and appends the record.

Call relations: The extension lifecycle system calls this after registry dispatch finishes a tool call. The dispatch lifecycle test compares these recorded finish events with the expected outcomes from successful and failing fake handlers.

Call graph: 2 external calls (clone, pin).

fn handler_looks_up_namespaced_aliases_explicitly()

Purpose: Checks that the registry treats a plain tool name and a namespaced tool name as different entries. This prevents one tool from accidentally shadowing another tool with the same short name.

Data flow: The test creates one plain name, one namespaced name, and a second missing namespaced name. It registers separate fake handlers for the first two names, asks the registry for each name, and checks that the correct handlers are returned while the missing namespace returns nothing.

Call relations: The Rust test runner calls this test. Inside the test, ToolRegistry::new is used to build the registry, and registry lookup is exercised directly to prove name matching is exact.

Call graph: calls 3 internal fn (new, namespaced, plain); 5 external calls (clone, new, from, assert!, assert_eq!).

async fn function_tools_expose_default_hook_payloads_and_rewrites() -> anyhow::Result<()>

Purpose: Verifies the default hook data for ordinary function tools and checks that hook input rewriting updates the function arguments. Hooks are extension points that can inspect or change tool input before or after a tool runs.

Data flow: The test builds a session, a function-style invocation with JSON arguments, and a fake text output. It checks the pre-use hook payload, the post-use hook payload, then asks the handler to replace the hook input and confirms the invocation still has function-shaped JSON arguments with the new value.

Call relations: The asynchronous test runner calls this test. It uses test_invocation to make a realistic invocation, then exercises the default hook methods on TestHandler and checks the rewritten payload.

Call graph: calls 4 internal fn (make_session_and_context, from_text, test_invocation, namespaced); 4 external calls (new, assert_eq!, panic!, json!).

async fn function_hook_input_defaults_empty_arguments_to_object()

Purpose: Checks that blank function arguments are treated as an empty JSON object for hook input. This avoids hooks receiving invalid or surprising data when a function call has no real arguments.

Data flow: The test creates a function invocation whose arguments are only whitespace. It asks the handler for the pre-use hook payload and expects the tool input to be {}.

Call relations: The asynchronous test runner calls this test. It relies on test_invocation for the common invocation setup and focuses only on the argument-parsing default.

Call graph: calls 3 internal fn (make_session_and_context, test_invocation, plain); 2 external calls (new, assert_eq!).

async fn spawn_agent_function_tools_use_agent_matcher_alias()

Purpose: Confirms that both the plain spawn_agent tool and its namespaced version appear to hooks under the same special hook name. This lets hook rules match agent-spawning consistently, no matter which alias was used.

Data flow: The test builds two invocations with the same JSON message: one for the plain tool name and one for the multi-agent namespace. It asks each handler for its pre-use hook payload and compares both results to the shared spawn_agent hook name.

Call relations: The asynchronous test runner calls this test. It uses shared session and turn objects for both invocations, then checks the hook-facing names produced by the handlers.

Call graph: calls 3 internal fn (make_session_and_context, namespaced, plain); 2 external calls (new, assert_eq!).

async fn code_mode_wait_does_not_expose_default_hook_payloads()

Purpose: Ensures the code-mode wait tool does not produce the normal pre-use or post-use hook payloads. Waiting is a control action, not a regular model-facing function call, so exposing it like a normal tool would be misleading.

Data flow: The test creates a wait-tool invocation and a simple output. It asks the wait handler for pre-use and post-use hook payloads and expects both answers to be None.

Call relations: The asynchronous test runner calls this test. It uses test_invocation to create the call, then checks the specialized behavior of CodeModeWaitHandler instead of the generic defaults.

Call graph: calls 3 internal fn (make_session_and_context, from_text, test_invocation); 2 external calls (new, assert_eq!).

async fn write_stdin_does_not_expose_default_pre_tool_use_payload()

Purpose: Checks that the tool for writing to standard input does not expose a default pre-use hook payload. Standard input is the stream of text sent into a running process, and treating this as an ordinary tool input could reveal or route data incorrectly.

Data flow: The test creates an invocation for the write-stdin handler. It asks for the pre-use hook payload and expects no payload to be produced.

Call relations: The asynchronous test runner calls this test. It uses test_invocation for setup and then verifies the special-case hook behavior of WriteStdinHandler.

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

fn post_tool_use_feedback_output_keeps_code_mode_result_typed()

Purpose: Checks that post-tool feedback can change what the model sees without losing the original typed result used by code mode. A typed result is structured data, such as JSON, rather than just plain text.

Data flow: The test builds a tool result whose original output is JSON and whose model-visible output is text feedback from a hook. It first converts the result into a model response and checks that the feedback text is used. Then it builds the same result again and checks that the code-mode result is still the original JSON.

Call relations: The Rust test runner calls this test. It exercises AnyToolResult conversion paths to ensure two consumers get the right view: the model gets feedback text, while code mode keeps structured data.

Call graph: calls 2 internal fn (from_text, new); 3 external calls (new, assert_eq!, json!).

async fn dispatch_notifies_tool_lifecycle_contributors() -> anyhow::Result<()>

Purpose: Tests that tool lifecycle extensions are told when each tool starts and finishes, including both completed and failed calls. This is important for logging, monitoring, or extensions that react to tool activity.

Data flow: The test creates a session with a lifecycle recorder extension, registers one fake tool that returns output and one fake tool that returns an error, then dispatches both through the registry. It checks the failing call's error message and then drains the recorder's shared list to compare the exact start and finish records.

Call relations: The asynchronous test runner calls this test. It builds a ToolRegistry, uses test_invocation to create realistic calls, dispatches them through the normal registry path, and relies on ToolLifecycleRecorder to capture the lifecycle events.

Call graph: calls 4 internal fn (make_session_and_context, new, test_invocation, plain); 9 external calls (clone, new, from, new, assert_eq!, new, panic!, new, vec!).

fn test_invocation(
    session: Arc<crate::session::session::Session>,
    turn: Arc<crate::session::turn_context::TurnContext>,
    call_id: &str,
    tool_name: codex_tools::ToolName,
) -> ToolInvo

Purpose: Creates a standard fake tool invocation for tests. This keeps each test from repeating the same session, turn, call id, cancellation, tracking, source, and empty function-argument setup.

Data flow: It receives a session, a turn context, a call id, and a tool name. It combines them with a fresh cancellation token, a fresh change tracker, a direct-call source, and default {} function arguments, then returns a complete ToolInvocation.

Call relations: Several tests call this helper when they need a realistic invocation object. The helper gives them a consistent starting point so each test can change only the part it cares about, such as arguments, tool name, or expected hook behavior.

Call graph: calls 1 internal fn (new); called by 5 (code_mode_wait_does_not_expose_default_hook_payloads, dispatch_notifies_tool_lifecycle_contributors, function_hook_input_defaults_empty_arguments_to_object, function_tools_expose_default_hook_payloads_and_rewrites, write_stdin_does_not_expose_default_pre_tool_use_payload); 3 external calls (new, new, new).

fn tools(
        &self,
        _session_store: &ExtensionData,
        _thread_store: &ExtensionData,
    ) -> Vec<Arc<dyn ToolExecutor<ExtensionToolCall>>>

Purpose: Supplies the fake extension tool used by this test file. It pretends to be an extension that contributes one executable tool, the echo tool.

Data flow: It receives extension data stores for the session and thread, but this test contributor does not need to read them. It creates an ExtensionEchoExecutor, wraps it so it can be shared, and returns it in a list of available extension tool executors.

Call relations: The test registry uses this contributor when building a fake extension environment. Later, the router asks the registry for extension tools, and this contributor is the source of the echo executor that becomes visible and dispatchable.

Call graph: 1 external calls (vec!).

fn tool_name(&self) -> ToolName

Purpose: Gives the fake extension tool its full routed name. The namespace extension/ keeps it separate from built-in or MCP tools that might also be called echo.

Data flow: It takes no outside input beyond the executor itself. It builds and returns a namespaced tool name made from extension/ and echo.

Call relations: The router and extension machinery use this name to identify which executor should receive a matching tool call. It supports the extension dispatch test by making the fake tool addressable as extension/echo.

Call graph: calls 1 internal fn (namespaced).

fn spec(&self) -> ToolSpec

Purpose: Describes the fake extension tool in the format the model can see. The spec says there is an extension/ namespace with an echo function that requires a string field called message.

Data flow: It builds a tool description from fixed test data: namespace name, human-readable descriptions, and a JSON input schema. It returns a ToolSpec that can be included in the router’s model-visible tool list.

Call relations: When the router collects tool descriptions, this method lets the fake extension advertise itself. The extension visibility test checks that this spec appears among the tools offered to the model.

Call graph: 3 external calls (default_namespace_description, Namespace, vec!).

fn handle(&self, call: ExtensionToolCall) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Starts execution of the fake extension tool in the async form expected by the tool system. Async means the work returns later without blocking the whole program while it runs.

Data flow: It receives an extension tool call, passes that call into handle_call, and wraps the resulting future so the generic tool executor interface can await it. It returns that future to the caller.

Call relations: The router calls this through the generic tool executor interface when it dispatches the extension echo call. This method is a small adapter between the trait’s required shape and the real test implementation in handle_call.

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

async fn handle_call(
        &self,
        call: ExtensionToolCall,
    ) -> Result<Box<dyn codex_tools::ToolOutput>, codex_tools::FunctionCallError>

Purpose: Runs the fake echo tool and creates a predictable JSON result for assertions. It proves that arguments, call identity, and conversation history reach an extension tool correctly.

Data flow: It reads the tool call’s function arguments as JSON text, parses them into structured JSON, and combines them with the call id and conversation history. It returns a JSON tool output containing those values plus ok: true; it does not change external state.

Call relations: It is called by ExtensionEchoExecutor::handle during extension tool dispatch. The main extension test inspects this output to confirm the router delivered the right call and context to the extension executor.

Call graph: calls 1 internal fn (new); called by 1 (handle); 4 external calls (new, function_arguments, json!, from_str).

fn extension_tool_test_registry() -> Arc<ExtensionRegistry<Config>>

Purpose: Builds a small extension registry containing only the fake echo contributor. This gives the tests a controlled extension setup instead of depending on real installed extensions.

Data flow: It creates a new registry builder, registers ExtensionEchoContributor, builds the registry, and returns it wrapped for shared ownership. The result can be installed into a test session’s services.

Call relations: The extension dispatch test calls this before creating the router. That makes the fake extension tools available when extension_tool_executors gathers executors from the session.

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

async fn parallel_support_does_not_match_namespaced_local_tool_names() -> anyhow::Result<()>

Purpose: Checks that a built-in local tool’s parallel-execution permission does not accidentally apply to a namespaced tool with the same final name. This prevents the router from treating mcp__server__shell_command as if it were the local shell_command.

Data flow: It creates a test session and router, finds a local shell-like tool that supports parallel calls, then builds a second call with the same tool name inside an MCP-style namespace. It asserts that the local call is recognized as parallel-safe but the namespaced lookalike is not.

Call relations: This test drives ToolRouter::from_turn_context and then asks the router’s parallel-support check about carefully chosen tool calls. It protects the routing rule that full names, including namespaces, matter.

Call graph: calls 2 internal fn (make_session_and_context, from_turn_context); 3 external calls (default, new, assert!).

async fn build_tool_call_uses_namespace_for_registry_name() -> anyhow::Result<()>

Purpose: Checks that a model function call with a namespace becomes a tool call whose name includes that namespace. Without this, two tools with the same short name from different places could be confused.

Data flow: It starts with a response item naming create_event and giving the namespace mcp__codex_apps__calendar. It asks the router to build a ToolCall, then verifies the output has the combined namespaced name, the original call id, and the original function arguments.

Call relations: This test exercises ToolRouter::build_tool_call, which is used when model responses are converted into executable tool requests. It confirms that namespacing is preserved before dispatch ever happens.

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

async fn mcp_parallel_support_uses_handler_data() -> anyhow::Result<()>

Purpose: Checks that parallel-execution support for MCP tools comes from the exact MCP tool’s metadata. MCP means Model Context Protocol, a way for external servers to provide tools to the model.

Data flow: It creates two fake MCP tool records with the same callable name but different namespaces and different parallel-support flags. It builds a router from those records, then verifies that only the tool from the server marked parallel-safe is treated as parallel-safe.

Call relations: This test feeds fake MCP tool info into ToolRouter::from_turn_context and queries the router with namespaced tool calls. It depends on mcp_tool_info to create the test tool records.

Call graph: calls 3 internal fn (make_session_and_context, from_turn_context, namespaced); 4 external calls (default, new, assert!, vec!).

async fn tools_without_handlers_do_not_support_parallel() -> anyhow::Result<()>

Purpose: Checks the safe default: if the router has no handler information for a tool, it must not assume the tool can run in parallel. This avoids racing tools whose behavior is unknown.

Data flow: It creates a router with no MCP tools, no extension executors, and no discoverable tools. It then asks whether a web_search call supports parallel execution and asserts the answer is false.

Call relations: This test exercises the router’s fallback behavior after ToolRouter::from_turn_context builds a minimal router. It protects against accidental optimistic parallelism when no concrete tool handler is registered.

Call graph: calls 2 internal fn (make_session_and_context, from_turn_context); 3 external calls (default, new, assert!).

async fn specs_filter_deferred_dynamic_tools() -> anyhow::Result<()>

Purpose: Checks that dynamic tools marked as deferred are hidden from the model until later discovery. Deferred here means “do not show this tool immediately.”

Data flow: It creates a dynamic namespace with two tools: one hidden because defer_loading is true, and one visible because it is false. After building the router, it asks for model-visible specs and confirms that only the visible tool name appears.

Call relations: This test uses ToolRouter::from_turn_context with custom dynamic tool specs and uses namespace_function_names to read the resulting visible tool names. It protects the feature that keeps undiscovered tools out of the model’s initial menu.

Call graph: calls 2 internal fn (make_session_and_context, from_turn_context); 4 external calls (default, new, assert_eq!, vec!).

fn mcp_tool_info(
    server_name: &str,
    supports_parallel_tool_calls: bool,
    callable_namespace: &str,
    tool_name: &str,
) -> codex_mcp::ToolInfo

Purpose: Creates a fake MCP tool record for tests. It packages the server name, namespace, tool name, and parallel-support flag into the same shape the router receives from real MCP connections.

Data flow: It receives simple strings and a boolean, then fills out a ToolInfo structure with those values plus harmless defaults for fields the tests do not care about. It also creates a minimal JSON schema saying the tool accepts an object.

Call relations: The MCP parallel-support test calls this helper to build two similar tools from different servers. That lets the test focus on router behavior instead of the many details needed to construct ToolInfo by hand.

Call graph: 5 external calls (new, new, json!, new, object).

async fn extension_tool_executors_are_model_visible_and_dispatchable() -> anyhow::Result<()>

Purpose: Checks the full extension tool path: an extension tool appears in the model-visible tool list, can be called by namespace, and receives the correct conversation history and arguments.

Data flow: It creates a test session, installs the fake extension registry, records a user message into conversation history, and builds a router with extension executors. It verifies the echo tool’s spec is visible, builds a namespaced call to extension/echo, dispatches it, then parses the returned function-call output and compares it to the expected JSON.

Call relations: This is the main end-to-end test in the file. It uses extension_tool_test_registry to install the fake extension, ToolRouter::build_tool_call to convert a model response into a call, and the router’s dispatch method to run the call through ExtensionEchoExecutor.

Call graph: calls 5 internal fn (make_session_and_context, build_tool_call, from_turn_context, extension_tool_test_registry, new); 12 external calls (new, new, default, assert!, assert_eq!, json!, panic!, from_str, from_ref, extension_tool_executors (+2 more)).

fn namespace_function_names(specs: &[ToolSpec], namespace_name: &str) -> Vec<String>

Purpose: Extracts the function names inside one namespace from a list of tool specs. It is a small test helper that makes visibility assertions easier to read.

Data flow: It receives a list of tool specs and a namespace name. It searches for a matching namespace, collects the names of function tools inside it, and returns those names; if the namespace is missing, it returns an empty list.

Call relations: The deferred dynamic tools test uses this helper after asking the router for model-visible specs. It turns the larger tool-spec structure into a simple list of names that can be compared directly in an assertion.

Call graph: 1 external calls (iter).

fn from_router(router: ToolRouter) -> Self

Purpose: Builds a compact test-friendly snapshot from a ToolRouter. It lets tests inspect what the model can see, what tools are registered, and how each registered tool is exposed.

Data flow: It receives a completed ToolRouter. It reads the router's visible tool specs and registered test-only tool names, extracts plain names and namespaced function lists, looks up exposure settings, and returns a ToolPlanProbe containing those summaries.

Call relations: The probe helpers call this after ToolRouter::from_turn_context has built a plan. The cache-specific test also uses it directly so it can compare two router plans made from the same cache.

Call graph: calls 2 internal fn (model_visible_specs, registered_tool_names_for_test); called by 2 (probe_with, tool_search_cache_rebuilds_when_deferred_sources_change).

fn assert_visible_contains(&self, expected: &[&str])

Purpose: Checks that certain tools are visible to the model. Tests use it when a setting should make tools appear in the public tool list.

Data flow: It receives expected tool names and compares each one with the probe's visible_names list. If any name is missing, the test fails with a message showing what was visible.

Call relations: Individual tests call this after creating a probe, usually to prove that enabling a feature or capability exposes the expected tool.

Call graph: 1 external calls (assert!).

fn assert_visible_lacks(&self, expected_absent: &[&str])

Purpose: Checks that certain tools are not visible to the model. This is used to confirm that gates, provider limits, or code-mode hiding rules are working.

Data flow: It receives names that should be absent and searches the probe's visible_names list. If any forbidden name is present, the test fails.

Call relations: Tests call it alongside assert_visible_contains to describe both sides of a tool-planning rule: what appears and what stays hidden.

Call graph: 1 external calls (assert!).

fn assert_registered_contains(&self, expected: &[&str])

Purpose: Checks that tools are registered for execution even if they may not be visible to the model. This matters for hidden or deferred tools that can still be called through another path.

Data flow: It receives expected registered names and compares them with registered_names. Missing names cause the test to fail with a helpful message.

Call relations: Tests use this after probing a router to verify the runtime side of planning, especially for legacy shell tools, deferred tools, and namespaced tools.

Call graph: 1 external calls (assert!).

fn assert_registered_lacks(&self, expected_absent: &[&str])

Purpose: Checks that tools are not registered at all. This is stronger than being invisible: it means the runtime should not know about that tool in this plan.

Data flow: It receives names that should be absent and scans registered_names. If any are found, the test fails.

Call relations: Tests call it when a feature is disabled, a schema is invalid, or no environment exists, proving the tool is not merely hidden but unavailable.

Call graph: 1 external calls (assert!).

fn namespace_function_names(&self, namespace: &str) -> &[String]

Purpose: Returns the function names inside a visible namespace tool. A namespace is a grouped tool surface, like a folder containing several related functions.

Data flow: It receives a namespace name, looks it up in the probe's namespace_functions map, and returns the stored list. If the namespace is missing, it returns an empty slice.

Call relations: Tests use it to check which functions appear inside MCP, multi-agent, dynamic, or configured namespaces.

fn visible_spec(&self, name: &str) -> &ToolSpec

Purpose: Finds the full visible tool specification for one tool name. Tests use it when checking details beyond simple visibility, such as parameters or descriptions.

Data flow: It receives a tool name, searches visible_specs for a matching spec name, and returns that spec. If it cannot find the tool, it fails the test.

Call relations: Many tests first confirm a tool exists, then call this to inspect its schema, description, or special type.

fn exposure(&self, name: &str) -> ToolExposure

Purpose: Returns how a registered tool is exposed, such as direct, hidden, or deferred. Exposure describes whether the model sees the tool directly or reaches it through another mechanism.

Data flow: It receives a registered tool name, looks it up in the probe's exposure map, and returns the ToolExposure value. If the name is not registered, the test fails.

Call relations: Tests use it to verify subtle planning decisions, such as hiding legacy shell tools or making request_user_input direct-model-only.

async fn probe_with(
    configure_turn: impl FnOnce(&mut TurnContext),
    inputs: ToolPlanInputs,
) -> ToolPlanProbe

Purpose: Creates a fake session turn, applies custom setup, feeds extra tool inputs into the ToolRouter, and returns a ToolPlanProbe. It is the main test harness for scenarios that need custom tool sources.

Data flow: It takes a function that mutates the TurnContext and a ToolPlanInputs bundle. It creates a session and turn, applies the mutation, builds a ToolRouter with MCP, deferred, discoverable, extension, and dynamic tools, then turns that router into a probe.

Call relations: Most tests use this directly when they need more than default settings. The simpler probe helper also calls it with empty inputs.

Call graph: calls 3 internal fn (make_session_and_context, from_turn_context, from_router); called by 10 (code_mode_only_exposes_code_executor_and_hides_nested_tools, deferred_extension_tools_are_discoverable_with_tool_search, excluded_deferred_namespaces_do_not_enable_nested_tool_guidance, hosted_tools_follow_provider_auth_model_and_config_gates, install_suggestion_tools_stay_visible_without_tool_search, invalid_mcp_tools_are_not_registered, mcp_and_tool_search_follow_direct_and_deferred_tool_exposure, probe, request_plugin_install_description_defers_inventory_to_list_tool, request_plugin_install_requires_all_discovery_features_and_discoverable_tools); 1 external calls (default).

async fn probe(configure_turn: impl FnOnce(&mut TurnContext)) -> ToolPlanProbe

Purpose: A shorter version of probe_with for tests that only need to change the turn context. It keeps simple tests easy to read.

Data flow: It receives a turn-configuration function, supplies default empty ToolPlanInputs, waits for probe_with, and returns the resulting ToolPlanProbe.

Call relations: Many tests call this when they only need to flip feature flags, provider settings, or model capabilities.

Call graph: calls 1 internal fn (probe_with); called by 19 (code_mode_only_can_expose_namespaced_multi_agent_v2_as_normal_tools, environment_count_controls_environment_backed_tools, host_context_gates_agent_job_tools, hosted_tools_follow_provider_auth_model_and_config_gates, mcp_and_tool_search_follow_direct_and_deferred_tool_exposure, multi_agent_feature_selects_one_agent_tool_family, multi_agent_v2_can_use_configured_tool_namespace, multi_agent_v2_message_schemas_are_encrypted, multi_agent_v2_namespace_is_supported_by_bedrock_provider, request_plugin_install_requires_all_discovery_features_and_discoverable_tools (+9 more)); 1 external calls (default).

fn set_feature(turn: &mut TurnContext, feature: Feature, enabled: bool)

Purpose: Turns one feature flag on or off in both the live turn and its copied config. This keeps the test context internally consistent.

Data flow: It receives a mutable turn, a feature, and whether it should be enabled. It updates the turn's feature set, clones and updates the config, recalculates multi-agent version and tool mode, and stores the updated config back on the turn.

Call relations: set_features calls it repeatedly. Tests rely on it so ToolRouter sees the same feature state through both TurnContext fields and config fields.

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

fn set_features(turn: &mut TurnContext, features: &[Feature])

Purpose: Enables several feature flags at once. It is a convenience helper for tests that need a bundle of capabilities.

Data flow: It receives a mutable turn and a list of features. For each feature, it calls set_feature with enabled set to true.

Call relations: Tests call it to prepare combinations like code mode plus code-mode-only, or all plugin-discovery features.

Call graph: calls 1 internal fn (set_feature).

fn zsh_fork_config_for_spec_plan_tests() -> codex_tools::ZshForkConfig

Purpose: Creates a safe placeholder Zsh-fork shell configuration for tests. The paths only need to look valid because these tests inspect tool specs and never actually launch the shell.

Data flow: It reads the current test executable path, checks that it is absolute, and uses it as both required executable paths in a ZshForkConfig.

Call relations: Zsh-fork unified-exec tests call this when they need the turn to appear configured for ZshFork mode without depending on packaged shell artifacts.

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

fn update_config(turn: &mut TurnContext, update: impl FnOnce(&mut crate::config::Config))

Purpose: Safely edits the turn's shared config for a test. Because the config is stored behind an Arc, it clones the config, changes it, and replaces the shared value.

Data flow: It receives a mutable turn and an update function. It clones the current config, lets the caller mutate the clone, wraps the result in a new Arc, and assigns it back to the turn.

Call relations: Other setup helpers use this for web search mode and provider changes. Tests also use it directly for one-off config tweaks.

Call graph: called by 2 (set_web_search_mode, use_bedrock_provider); 1 external calls (new).

fn set_web_search_mode(turn: &mut TurnContext, mode: WebSearchMode)

Purpose: Sets the test turn's web search mode, such as live search. This isolates the config-writing details from the tests.

Data flow: It receives a mutable turn and a WebSearchMode. It calls update_config and writes the mode through the config's validated setter.

Call relations: Hosted-tool tests call this before checking whether web_search should be visible.

Call graph: calls 1 internal fn (update_config).

fn use_chatgpt_auth(turn: &mut TurnContext)

Purpose: Makes a test turn look like it is authenticated with ChatGPT. Some hosted tools are only available with this kind of authentication.

Data flow: It creates dummy ChatGPT authentication, stores it in the turn's auth manager, rebuilds the model provider using that auth, and writes the provider back to the turn.

Call relations: Hosted-tool tests call it before expecting image generation to appear.

Call graph: calls 2 internal fn (from_auth_for_testing, create_dummy_chatgpt_auth_for_testing); 1 external calls (create_model_provider).

fn use_bedrock_provider(turn: &mut TurnContext)

Purpose: Switches a test turn to the Amazon Bedrock provider. Tests use this to check provider-specific tool support.

Data flow: It creates Bedrock provider info, updates the config's provider id and provider object, then rebuilds the turn's provider with the existing authentication.

Call relations: Tool-search, multi-agent namespace, and hosted web-search tests call this to verify behavior under Bedrock.

Call graph: calls 2 internal fn (update_config, create_amazon_bedrock_provider); 1 external calls (create_model_provider).

fn tool_name(&self) -> ToolName

Purpose: Names the fake extension tool as web.run. This lets tests simulate an extension that provides standalone web execution.

Data flow: It has no input besides the tool object. It returns a namespaced ToolName with namespace web and function run.

Call relations: ToolRouter calls this through the ToolExecutor trait when extension executors are supplied to probe_with.

Call graph: calls 1 internal fn (namespaced).

fn spec(&self) -> ToolSpec

Purpose: Describes the fake web.run extension tool as a namespace containing one function. The spec is what the planner would inspect when deciding visible tools.

Data flow: It builds a ToolSpec namespace named web with a single run function, a test description, empty JSON parameters, and no output schema.

Call relations: ToolRouter asks the extension executor for this spec while building a plan in the standalone web-search test.

Call graph: 2 external calls (Namespace, vec!).

fn handle(&self, _call: ExtensionToolCall) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Provides a dummy implementation for the fake web.run tool. It returns an empty JSON output if ever called.

Data flow: It ignores the incoming tool call, creates an async future, and returns an empty JSON object wrapped as tool output.

Call relations: The tests only need planning, not execution, so this exists to satisfy the ToolExecutor trait.

Call graph: calls 1 internal fn (new); 3 external calls (new, pin, json!).

fn tool_name(&self) -> ToolName

Purpose: Names the fake deferred extension tool as extension_echo. Tests use that name to check registration and visibility.

Data flow: It has no input besides the tool object and returns a plain, non-namespaced ToolName.

Call relations: ToolRouter calls this through the ToolExecutor trait when the deferred extension executor is included in probe_with.

Call graph: calls 1 internal fn (plain).

fn spec(&self) -> ToolSpec

Purpose: Describes a fake extension tool that echoes a message. The spec includes a required message parameter so it looks like a real callable function.

Data flow: It builds a function ToolSpec named extension_echo with a strict object schema containing a required string field called message.

Call relations: The deferred-extension test supplies this executor so ToolRouter can register it and make it discoverable through tool_search rather than directly visible.

Call graph: calls 2 internal fn (object, string); 3 external calls (from, Function, vec!).

fn exposure(&self) -> ToolExposure

Purpose: Marks the fake extension tool as deferred. Deferred means the model should not see the tool directly, but it may discover or call it through another tool-search flow.

Data flow: It returns the ToolExposure::Deferred value without reading other state.

Call relations: ToolRouter uses this trait method while planning extension tools, and the related test checks that the exposure is preserved.

fn handle(&self, _call: ExtensionToolCall) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Intentionally fails if the fake deferred tool is executed. These tests are about planning only, so execution would mean something unexpected happened.

Data flow: It ignores the call and returns an async future that panics when polled.

Call relations: The deferred-extension planning test should never trigger this; it exists only to complete the ToolExecutor implementation.

Call graph: 2 external calls (pin, panic!).

fn duplicate_primary_environment(turn: &mut TurnContext)

Purpose: Adds a second environment to a test turn by copying the primary one and giving it a new id. This lets tests check behavior when multiple execution targets exist.

Data flow: It reads the first environment, clones it, changes its environment_id to secondary, and pushes it into the turn's environment list.

Call relations: The environment-count test calls it before checking that tools include an environment_id parameter.

fn mcp_tool(server: &str, namespace: &str, name: &str) -> ToolInfo

Purpose: Builds a valid fake MCP tool for tests. MCP is a protocol that lets outside servers provide tools to the model.

Data flow: It receives server, namespace, and tool names. It creates a ToolInfo with a simple object input schema, namespace description, server metadata, and no connector information.

Call relations: MCP-related tests use it directly, and invalid_mcp_tool starts from it before corrupting the schema.

Call graph: called by 1 (invalid_mcp_tool); 6 external calls (new, new, format!, json!, new, object).

fn invalid_mcp_tool(server: &str, namespace: &str, name: &str) -> ToolInfo

Purpose: Builds a fake MCP tool with an invalid input schema. Tests use it to prove bad external tool definitions are rejected.

Data flow: It creates a normal fake MCP tool, replaces its input schema with a schema whose type is null, and returns the modified ToolInfo.

Call relations: The invalid-MCP test passes this into probe_with and checks that ToolRouter does not register or expose it.

Call graph: calls 1 internal fn (mcp_tool); 3 external calls (new, json!, object).

fn dynamic_tool(namespace: Option<&str>, name: &str, defer_loading: bool) -> DynamicToolSpec

Purpose: Creates a fake dynamic tool spec, either as a standalone function or inside a namespace. Dynamic tools are tool definitions supplied at runtime rather than compiled in.

Data flow: It receives an optional namespace, a tool name, and whether loading should be deferred. It builds a simple object input schema and returns either a function spec or a namespace spec containing that function.

Call relations: Code-mode tests use it to check how nested dynamic tools are shown, hidden, or registered under different tool modes.

Call graph: 5 external calls (format!, json!, Function, Namespace, vec!).

fn discoverable_plugin(id: &str, name: &str) -> DiscoverableTool

Purpose: Creates a fake plugin candidate that could be suggested for installation. Tests use it as inventory for plugin-discovery tools.

Data flow: It receives an id and display name, builds DiscoverablePluginInfo with a description and empty connector/server lists, and converts it into a DiscoverableTool.

Call relations: Plugin-installation tests pass these fake candidates into probe_with to decide whether list and request install tools should appear.

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

fn has_parameter(spec: &ToolSpec, parameter_name: &str) -> bool

Purpose: Checks whether a visible tool spec declares a particular input parameter. This helps tests inspect schemas without depending on all schema details.

Data flow: It serializes the ToolSpec to JSON, follows the /parameters/properties/<name> path, and returns true if that JSON location exists.

Call relations: Shell, environment, and view-image tests use it after visible_spec to confirm that parameters such as shell or environment_id are present or absent.

Call graph: 2 external calls (format!, to_value).

fn apply_patch_accepts_environment_id(spec: &ToolSpec) -> bool

Purpose: Checks whether the freeform apply_patch tool description mentions Environment ID. Freeform tools do not expose ordinary JSON parameters, so the test inspects the text definition.

Data flow: It receives a ToolSpec. If it is a freeform apply_patch tool, it searches the tool's format definition text for Environment ID; otherwise it returns false.

Call relations: The environment-count test uses this to confirm apply_patch adapts when more than one environment is available.

async fn request_user_input_tool_respects_experimental_config_gate()

Purpose: Tests that request_user_input appears only when its experimental config switch allows it. This protects an interactive user-prompting tool from appearing unexpectedly.

Data flow: It first probes the default config and checks the tool is visible, registered, and direct-model-only. Then it disables the experimental config setting, probes again, and checks the tool is absent from both visible and registered lists.

Call relations: The test relies on probe for setup and uses ToolPlanProbe assertions to compare enabled versus disabled plans.

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

async fn request_user_input_stays_direct_in_code_mode_only()

Purpose: Tests that request_user_input remains a direct model tool even when code-mode-only is active. It also ensures the code executor description does not advertise that nested tool.

Data flow: It enables code mode and code-mode-only, builds a plan, checks request_user_input plus code-mode entry tools are visible, verifies exposure, then inspects the exec tool description.

Call relations: It uses set_features inside probe and then calls visible_spec for the code-mode exec tool.

Call graph: calls 1 internal fn (probe); 3 external calls (assert!, assert_eq!, panic!).

async fn shell_family_registers_visible_unified_exec_and_hidden_legacy_shell()

Purpose: Tests the shell-tool family when unified exec is enabled. The new exec_command and write_stdin tools should be visible, while the old shell_command remains registered but hidden.

Data flow: It enables shell and unified exec features, disables ZshFork, sets the model shell type, and probes. It checks visible names, registered names, hidden exposure for shell_command, and the shell parameter on exec_command.

Call relations: This test uses probe plus helper assertions to verify both the public tool surface and the hidden compatibility runtime.

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

async fn shell_zsh_fork_stays_standalone_until_unified_exec_composition_is_enabled()

Purpose: Tests that ZshFork shell mode does not automatically use unified exec unless the specific composition feature is enabled. It also accounts for platforms where terminal support is unavailable.

Data flow: It builds one plan with ZshFork enabled but unified-exec composition disabled and expects shell_command only. Then it builds a second plan with composition enabled and checks either unified exec or standalone behavior depending on terminal support.

Call relations: It uses probe for both scenarios and the platform support check to avoid expecting unified terminal behavior where it cannot work.

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

async fn zsh_fork_unified_exec_hides_shell_parameter()

Purpose: Tests that unified exec hides the shell selector when ZshFork is the only local shell mode. This prevents the model from choosing a shell it cannot actually vary.

Data flow: If the platform lacks terminal support, it exits early. Otherwise it enables the needed shell features, sets ZshFork mode with a placeholder config, probes, and verifies exec_command lacks the shell parameter.

Call relations: It uses the ZshFork config helper and has_parameter to inspect the final exec_command schema.

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

async fn zsh_fork_unified_exec_keeps_shell_parameter_when_remote_environment_available()

Purpose: Tests that the shell selector comes back when a remote environment is available. A remote target may support different shell behavior, so the model needs a shell choice again.

Data flow: After a platform support check, it enables ZshFork unified exec, adds a remote test environment, probes, and checks exec_command includes both shell and environment_id parameters.

Call relations: It constructs an extra TurnEnvironment inside probe and then uses has_parameter to confirm the router noticed the multi-environment situation.

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

async fn environment_count_controls_environment_backed_tools()

Purpose: Tests that tools requiring an execution environment disappear when no environment exists, and gain environment selection when multiple environments exist.

Data flow: It first clears all environments, enables shell/apply_patch settings, and checks shell, exec, apply_patch, and view_image are absent. Then it duplicates the primary environment, enables relevant features, and checks visible tools include environment_id support.

Call relations: It uses duplicate_primary_environment, has_parameter, and apply_patch_accepts_environment_id to inspect how the tool plan changes with environment count.

Call graph: calls 1 internal fn (probe); 1 external calls (assert!).

async fn host_context_gates_agent_job_tools()

Purpose: Tests that agent-job reporting tools only appear when the current session is a worker agent job. Normal sessions should be able to spawn CSV agents but not report job results.

Data flow: It probes once with SpawnCsv enabled in a normal session and checks only spawn_agents_on_csv appears. It probes again after marking the session source as a subagent job and checks report_agent_job_result appears too.

Call relations: The test changes session_source inside probe so ToolRouter can gate tools based on where the session came from.

Call graph: calls 1 internal fn (probe).

async fn sleep_tool_follows_feature_gate()

Purpose: Tests that the sleep tool follows its feature flag. This keeps a simple timing tool from appearing unless explicitly enabled.

Data flow: It probes with SleepTool disabled and checks sleep is absent, then probes with SleepTool enabled and checks sleep is visible.

Call relations: It uses set_feature inside probe for the two opposite states.

Call graph: calls 1 internal fn (probe).

async fn mcp_and_tool_search_follow_direct_and_deferred_tool_exposure()

Purpose: Tests how MCP tools interact with direct visibility and deferred tool search. It confirms direct MCP tools are shown as namespaces, while deferred MCP tools require model support for tool_search.

Data flow: It builds several plans: direct MCP, deferred MCP without model search support, no deferred tools, Bedrock with namespace capability, and fully enabled search. It checks visible resource helpers, tool_search visibility, and registered deferred tool names.

Call relations: The test combines probe_with, mcp_tool, provider setup, and ToolName construction to cover direct and searchable MCP paths.

Call graph: calls 3 internal fn (probe, probe_with, namespaced); 3 external calls (assert_eq!, default, vec!).

async fn deferred_extension_tools_are_discoverable_with_tool_search()

Purpose: Tests that a deferred extension tool is registered but not directly visible, and that tool_search is shown so the model can discover it.

Data flow: It enables model support for search, supplies the fake DeferredExtensionTool executor, probes, and checks tool_search is visible, extension_echo is hidden from visible tools, and extension_echo is registered with deferred exposure.

Call relations: It uses probe_with because the scenario needs an extension executor in addition to turn configuration.

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

async fn tool_search_cache_rebuilds_when_deferred_sources_change()

Purpose: Tests that the tool-search handler cache does not reuse stale descriptions when the set of deferred tools changes. This prevents the model from seeing an old tool inventory.

Data flow: It creates one shared cache, builds a first router with a deferred MCP server named first, then builds a second router with a deferred MCP server named second. It inspects each tool_search description and confirms each mentions only its own source.

Call relations: Unlike most tests, it calls make_session_and_context and ToolRouter::from_turn_context directly so both routers share the same cache.

Call graph: calls 3 internal fn (make_session_and_context, from_turn_context, from_router); 5 external calls (new, assert!, default, panic!, vec!).

async fn invalid_mcp_tools_are_not_registered()

Purpose: Tests that MCP tools with invalid schemas are rejected. This protects the model and runtime from malformed external tool definitions.

Data flow: It supplies one invalid fake MCP tool, probes, and checks neither the namespace nor the namespaced callable is visible or registered.

Call relations: It uses invalid_mcp_tool and probe_with to feed bad external input into the normal router path.

Call graph: calls 2 internal fn (probe_with, namespaced); 2 external calls (default, vec!).

async fn request_plugin_install_requires_all_discovery_features_and_discoverable_tools()

Purpose: Tests that plugin-installation suggestion tools only appear when all required discovery features are enabled and there is at least one installable candidate.

Data flow: It loops over each required feature, disables that one while enabling the others, and checks install tools are absent. It also checks no candidates means absent, then supplies a fake plugin and confirms both list and request tools are visible.

Call relations: It uses discoverable_plugin plus probe_with for candidate inventory, and probe for the no-candidate case.

Call graph: calls 2 internal fn (probe, probe_with); 2 external calls (default, vec!).

async fn install_suggestion_tools_stay_visible_without_tool_search()

Purpose: Tests that plugin installation suggestion tools do not depend on the model's tool_search capability. They should still be directly visible when discovery is enabled.

Data flow: It disables model search support, enables the required plugin-discovery features, supplies a fake plugin candidate, probes, and checks install tools appear while tool_search does not.

Call relations: This complements the broader plugin gate test by isolating the relationship between plugin suggestions and tool_search.

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

async fn request_plugin_install_description_defers_inventory_to_list_tool()

Purpose: Tests that request_plugin_install's description does not contain a hardcoded plugin inventory. Instead, the model should first call the list tool and then request an exact match.

Data flow: It enables plugin discovery, supplies a fake GitHub plugin, probes, then inspects the descriptions of list_available_plugins_to_install and request_plugin_install. It checks the list tool describes returning candidates and the request tool points to the list tool without naming github.

Call relations: It uses visible_spec to inspect exact function descriptions rather than only checking tool presence.

Call graph: calls 1 internal fn (probe_with); 4 external calls (assert!, default, panic!, vec!).

async fn code_mode_only_exposes_code_executor_and_hides_nested_tools()

Purpose: Tests that code-mode-only changes the visible surface from nested dynamic tools to the code executor entrypoints. The model should use the code-mode wrapper rather than directly seeing nested tools.

Data flow: It first supplies a dynamic namespaced tool without code mode and checks the namespace function is visible. Then it enables code mode and code-mode-only with the same dynamic tool, checks exec and wait are visible, and confirms the original namespace no longer exposes the function.

Call relations: It uses dynamic_tool and probe_with to compare the same runtime tool under two different tool modes.

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

async fn excluded_deferred_namespaces_do_not_enable_nested_tool_guidance()

Purpose: Tests that deferred tools in excluded namespaces do not cause code-mode guidance text about omitted nested tools. Excluded namespaces should not affect that user-facing explanation.

Data flow: It enables code-mode-only, disables collaboration, enables model search support, configures an excluded namespace, and supplies a deferred dynamic tool in that namespace. It checks the code exec description lacks the deferred-tool guidance and that the tool plus tool_search are registered.

Call relations: It combines dynamic_tool, config updates, and visible_spec to inspect a subtle code-mode description rule.

Call graph: calls 2 internal fn (probe_with, namespaced); 4 external calls (assert!, default, panic!, vec!).

async fn multi_agent_feature_selects_one_agent_tool_family()

Purpose: Tests that the planner chooses exactly one multi-agent tool family: older v1 namespaced tools or newer v2 tools. It also verifies selected schema and exposure details.

Data flow: It probes with collaboration enabled and MultiAgentV2 disabled, expecting the v1 namespace and its functions. Then it probes with v2 enabled, expecting v2 standalone tools and specific description content. Finally it tests code-mode-only with non-code-mode-only v2 settings and checks direct-model-only exposure.

Call relations: This test uses feature setup and config updates to compare the major multi-agent planning branches.

Call graph: calls 1 internal fn (probe); 3 external calls (assert!, assert_eq!, panic!).

async fn multi_agent_v2_message_schemas_are_encrypted()

Purpose: Tests that message fields in v2 multi-agent tools are marked encrypted. This is important because those messages may contain user or task context that should be protected.

Data flow: It enables MultiAgentV2, probes, then inspects spawn_agent, send_message, and followup_task parameter schemas. For each one it checks the message property has encrypted set to true.

Call relations: It uses visible_spec to inspect schema metadata that simple visibility checks would miss.

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

async fn tool_mode_selector_overrides_feature_flags()

Purpose: Tests that an explicit model tool-mode setting wins over feature flags. Even if code-mode features are enabled, ToolMode::Direct should prevent code-mode entry tools from appearing.

Data flow: It enables code-mode flags, sets the model and turn tool mode to Direct, probes, and checks the code-mode exec and wait tools are absent.

Call relations: This test checks the interaction between set_feature's default tool-mode recalculation and an explicit override set afterward.

Call graph: calls 1 internal fn (probe).

async fn v1_multi_agent_tools_defer_when_tool_search_available()

Purpose: Tests that v1 multi-agent tools become deferred when tool_search is available. Instead of showing the whole namespace directly, the model sees tool_search and can discover those tools.

Data flow: It enables model search support, turns on collaboration, disables v2, probes, and checks tool_search is visible while v1 function names are not directly visible. It then verifies namespaced runtimes are registered with deferred exposure and the search description mentions multi-agent tools.

Call relations: It uses ToolName::namespaced to check the runtime names that should exist when v1 tools are deferred.

Call graph: calls 2 internal fn (probe, namespaced); 3 external calls (assert!, assert_eq!, panic!).

async fn multi_agent_v2_can_use_configured_tool_namespace()

Purpose: Tests that v2 multi-agent tools can be grouped under a configured namespace. It also confirms removed or unsupported tools, such as assign_task, do not sneak into that namespace.

Data flow: It enables MultiAgentV2, sets the namespace to agents, probes, and checks the visible surface is the agents namespace rather than standalone tool names. It verifies expected functions are registered and present inside the namespace, while assign_task is absent.

Call relations: This covers the configured namespace branch of multi-agent v2 planning.

Call graph: calls 1 internal fn (probe); 1 external calls (assert!).

async fn multi_agent_v2_namespace_is_supported_by_bedrock_provider()

Purpose: Tests that a namespaced v2 multi-agent tool surface works with the Bedrock provider. Provider differences should not remove the configured agents namespace.

Data flow: It enables MultiAgentV2, configures the agents namespace, switches the provider to Bedrock, probes, and checks the namespace is visible while plain standalone names are not registered.

Call relations: It combines use_bedrock_provider with the namespace configuration to verify provider-specific compatibility.

Call graph: calls 1 internal fn (probe); 1 external calls (assert!).

async fn code_mode_only_can_expose_namespaced_multi_agent_v2_as_normal_tools()

Purpose: Tests a code-mode-only setup where namespaced multi-agent v2 tools are still exposed as normal direct tools. This is a special case controlled by config.

Data flow: It enables code mode, code-mode-only, and MultiAgentV2, sets non_code_mode_only and the agents namespace, then probes. It checks the exact visible tool order and confirms the agents namespace contains expected functions but not assign_task.

Call relations: This test ties together code-mode visibility, multi-agent v2 namespace configuration, and hosted web-search ordering.

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

async fn hosted_tools_follow_provider_auth_model_and_config_gates()

Purpose: Tests the rules for hosted Responses API tools such as image generation and web search. These tools depend on authentication, provider support, model capabilities, feature flags, and extension-tool conflicts.

Data flow: It checks image generation is hidden with API-key auth but visible with ChatGPT auth and image-capable model settings. It checks web_search specs under live mode, hosted tools in code-mode-only ordering, standalone web-search behavior with and without a web.run extension, and hiding web_search on an unsupported provider.

Call relations: This is a broad integration-style planner test that uses probe, probe_with, authentication helpers, provider helpers, and web-search config helpers.

Call graph: calls 2 internal fn (probe, probe_with); 3 external calls (default, assert_eq!, vec!).

fn tool_name(&self) -> codex_tools::ToolName

Purpose: Returns the name of the fake tool used by these tests. The registry uses this name to decide which handler should receive a tool call.

Data flow: It reads the tool name stored inside the TestHandler, makes a copy of it, and gives that copy back. Nothing else is changed.

Call relations: This is part of the ToolExecutor behavior implemented by TestHandler. When the test registry is built with this handler, the registry can ask for the handler’s name so it can route matching invocations to it.

Call graph: 1 external calls (clone).

fn spec(&self) -> codex_tools::ToolSpec

Purpose: Builds the public description of the fake test tool. This description says the tool is a function-style tool named like the handler’s tool name, with a simple placeholder description and default input schema.

Data flow: It reads the stored tool name, fills out a tool specification object with that name and basic metadata, and returns the specification. It does not run the tool or inspect any invocation.

Call relations: This supports the same ToolExecutor interface as the real tools. The registry can use it when it needs to know what tools are available, although in these tests the main focus is dispatching and tracing rather than the schema itself.

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

fn handle(&self, _invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'_>

Purpose: Pretends to run a tool and always succeeds with the text result “ok”. This gives the tests a predictable successful tool execution without depending on any real tool behavior.

Data flow: It receives a tool invocation but ignores its contents. It creates a successful FunctionToolOutput containing “ok”, wraps it in the asynchronous return shape expected by the tool system, and returns it.

Call relations: The ToolRegistry calls this when a test invocation names the fake tool. Its simple success result lets the surrounding tests check whether dispatch tracing records the invocation and result payloads correctly.

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

async fn dispatch_lifecycle_trace_records_direct_and_code_mode_requesters() -> anyhow::Result<()>

Purpose: Checks that the trace records who requested a tool call correctly: either the model directly, or a code cell running in code mode. It also checks that the trace keeps the raw invocation and result payloads needed for replay.

Data flow: The test creates a temporary trace folder, makes a fake session and turn, attaches tracing, and starts a code-cell trace. It dispatches one direct tool call and one code-mode tool call through a registry containing TestHandler. Then it reloads the saved trace from disk and verifies that the direct call is marked as model-requested while the code-mode call is linked to the right code cell and runtime tool id.

Call relations: This is one of the main end-to-end tests in the file. It uses attach_test_trace to install the recorder, test_invocation to build dispatch inputs, TestHandler through ToolRegistry to produce successful outputs, and single_bundle_dir to find the saved trace before replaying it.

Call graph: calls 6 internal fn (make_session_and_context, with_handler_for_test, attach_test_trace, single_bundle_dir, test_invocation, plain); 6 external calls (clone, new, new, assert!, assert_eq!, replay_bundle).

async fn dispatch_lifecycle_trace_records_unsupported_tool_failures() -> anyhow::Result<()>

Purpose: Checks that asking for a tool that is not registered is still written to the trace as a failed tool call. This matters because failures are part of the real session history and must not disappear.

Data flow: The test creates a traced fake session, but uses an empty tool registry. It dispatches a call for a missing tool, expects an error that can be reported back to the model, then reloads the trace and confirms the tool call is marked failed and has a recorded result payload.

Call relations: This test exercises the registry’s failure path instead of TestHandler. It still uses the shared helpers attach_test_trace, test_invocation, and single_bundle_dir so the setup matches the successful dispatch tests.

Call graph: calls 5 internal fn (make_session_and_context, empty_for_test, attach_test_trace, single_bundle_dir, test_invocation); 5 external calls (new, new, assert!, assert_eq!, replay_bundle).

async fn dispatch_lifecycle_trace_records_incompatible_payload_failures() -> anyhow::Result<()>

Purpose: Checks that a tool call with the wrong kind of payload is recorded as a failure. This protects trace completeness when dispatch breaks before the tool can run normally.

Data flow: The test sets up tracing and registers TestHandler for the expected tool name. Instead of sending a normal function payload, it sends a custom payload that the dispatch path cannot use for this tool. It expects a fatal error, then replays the trace and verifies that the call was saved as failed with a result payload.

Call relations: This test uses test_invocation_with_payload directly because it needs to build an unusual payload. It relies on the normal registry dispatch path to reject the mismatch and on attach_test_trace and single_bundle_dir to inspect the resulting trace.

Call graph: calls 6 internal fn (make_session_and_context, with_handler_for_test, attach_test_trace, single_bundle_dir, test_invocation_with_payload, plain); 5 external calls (new, new, assert!, assert_eq!, replay_bundle).

async fn missing_code_mode_wait_traces_only_the_wait_tool_call() -> anyhow::Result<()>

Purpose: Checks a special code-mode wait tool case: if there is no matching code-cell trace, the system should still record the wait tool call, but should not invent a code cell. This avoids misleading trace data.

Data flow: The test creates a traced fake session and registers the CodeModeWaitHandler. It dispatches a wait-tool invocation referring to a non-existent cell id. After replaying the saved trace, it confirms there are no recorded code cells, while the wait tool call still has a saved result payload.

Call relations: This test uses a real wait-tool handler rather than TestHandler. Like the other tests, it builds the invocation with test_invocation, attaches tracing with attach_test_trace, and reads the single saved bundle with single_bundle_dir.

Call graph: calls 5 internal fn (make_session_and_context, with_handler_for_test, attach_test_trace, single_bundle_dir, test_invocation); 5 external calls (new, new, assert!, assert_eq!, replay_bundle).

fn test_invocation(
    session: Arc<Session>,
    turn: Arc<TurnContext>,
    call_id: &str,
    tool_name: &str,
    source: ToolCallSource,
    arguments: &str,
) -> ToolInvocation

Purpose: Builds a normal function-style ToolInvocation for tests. It is a convenience wrapper so each test does not have to repeat the same setup details.

Data flow: It receives a session, turn, call id, tool name, source, and argument text. It turns the plain tool-name string into a ToolName, wraps the argument text as a function payload, and passes everything to test_invocation_with_payload. The result is a ready-to-dispatch ToolInvocation.

Call relations: The main tests call this whenever they need an ordinary tool call. It delegates the common object construction to test_invocation_with_payload, keeping the tests focused on what behavior they are checking.

Call graph: calls 2 internal fn (test_invocation_with_payload, plain); called by 3 (dispatch_lifecycle_trace_records_direct_and_code_mode_requesters, dispatch_lifecycle_trace_records_unsupported_tool_failures, missing_code_mode_wait_traces_only_the_wait_tool_call).

fn test_invocation_with_payload(
    session: Arc<Session>,
    turn: Arc<TurnContext>,
    call_id: &str,
    tool_name: codex_tools::ToolName,
    source: ToolCallSource,
    payload: ToolPayload,
)

Purpose: Builds a ToolInvocation with a caller-supplied payload. Tests use it when they need full control over the payload, including deliberately invalid payloads.

Data flow: It receives the shared session and turn, cancellation setup information is created fresh, a new turn-diff tracker is made, and the call id, tool name, source, and payload are placed into a ToolInvocation. The completed invocation is returned for dispatch.

Call relations: test_invocation calls this for normal function payloads, and the incompatible-payload test calls it directly to create a bad input. The ToolRegistry then consumes the returned invocation during dispatch.

Call graph: calls 1 internal fn (new); called by 2 (dispatch_lifecycle_trace_records_incompatible_payload_failures, test_invocation); 3 external calls (new, new, new).

fn attach_test_trace(session: &mut Session, turn: &TurnContext, root: &Path) -> anyhow::Result<()>

Purpose: Connects a fake session to a fresh rollout trace stored under a temporary test directory. Without this, dispatch would run but the tests would have no trace file to replay and inspect.

Data flow: It reads the session’s thread id and receives the current turn and root directory. It starts a test trace with fixed metadata such as model name, provider name, working directory, approval policy, and sandbox policy. It records that the turn has started, then replaces the session’s trace recorder with this new test recorder.

Call relations: Every test calls this before dispatching tools. It prepares the shared tracing environment that the registry and tool dispatch code write into, and single_bundle_dir later finds the trace bundle it created.

Call graph: calls 1 internal fn (start_root_in_root_for_test); called by 4 (dispatch_lifecycle_trace_records_direct_and_code_mode_requesters, dispatch_lifecycle_trace_records_incompatible_payload_failures, dispatch_lifecycle_trace_records_unsupported_tool_failures, missing_code_mode_wait_traces_only_the_wait_tool_call); 1 external calls (from).

fn single_bundle_dir(root: &Path) -> anyhow::Result<PathBuf>

Purpose: Finds the one trace bundle directory created inside a temporary test root. It also checks that exactly one bundle exists, so the tests do not accidentally read the wrong trace.

Data flow: It reads the entries in the given root directory, converts them into paths, sorts them for stable behavior, and asserts that there is exactly one. It removes and returns that single path.

Call relations: After each test dispatches tool calls, it calls this helper before replaying the trace. This bridges the filesystem output from attach_test_trace and the replay step that verifies the recorded data.

Call graph: called by 4 (dispatch_lifecycle_trace_records_direct_and_code_mode_requesters, dispatch_lifecycle_trace_records_incompatible_payload_failures, dispatch_lifecycle_trace_records_unsupported_tool_failures, missing_code_mode_wait_traces_only_the_wait_tool_call); 2 external calls (assert_eq!, read_dir).

fn convert_apply_patch_maps_add_variant()

Purpose: This test proves that an apply-patch action for adding a file becomes a protocol FileChange::Add with the same content. It exists to catch mistakes in the conversion between the internal patch representation and the protocol representation used elsewhere.

Data flow: It starts by making a temporary directory, then builds an absolute path for a.txt inside it. That path and the text hello go into new_add_for_test, which creates an add-file patch action. The test sends that action into convert_apply_patch_to_protocol, then checks that looking up the same path in the converted result returns an add-file change containing hello.

Call relations: During the test, this function calls the test helper new_add_for_test to create a simple add-file action, uses tempdir to avoid depending on real project files, and finishes with assert_eq! to compare the converted output with the expected protocol value.

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

fn canonicalizes_word_only_shell_scripts_to_inner_command()

Purpose: This test checks that simple shell-wrapped commands are reduced to the actual command inside the shell. It also verifies that harmless differences, such as /bin/bash versus bash and extra spaces, do not change the approval key.

Data flow: It builds two command lists that both mean “run cargo test -p codex-core through bash.” It sends each list into the command canonicalization function, then compares the result with the expected clean list of words. The expected output is cargo, test, -p, and codex-core, with shell wrapper details removed.

Call relations: During the test run, the test framework calls this function. Inside it, the test uses assertion checks to prove that the canonicalization result matches the expected form, and that two differently written shell commands produce the same approval key.

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

fn canonicalizes_heredoc_scripts_to_stable_script_key()

Purpose: This test checks that shell scripts written as heredocs are not treated like simple word-only commands. A heredoc is a way to place a multi-line script directly inside a shell command, so the system gives it a stable script marker instead of trying to split it into ordinary words.

Data flow: It creates a small Python heredoc script and wraps it once with /bin/zsh and once with zsh. Each command is passed to the canonicalization function. The output should begin with the special marker __codex_shell_script__, keep the shell option -lc, and keep the full script text, making both wrapper forms compare the same.

Call relations: The test framework runs this as part of the test suite. The function then uses assertion checks to confirm that heredoc commands get a special shell-script approval key, and that the path-style shell name and short shell name are treated alike.

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

fn canonicalizes_powershell_wrappers_to_stable_script_key()

Purpose: This test checks that PowerShell-wrapped commands are turned into a consistent approval key. It ensures that wrapper differences like powershell.exe, powershell, and optional flags do not make the same script look like different commands.

Data flow: It creates two PowerShell command lists that both run the script Write-Host hi. One includes powershell.exe and -NoProfile; the other uses powershell with fewer wrapper arguments. Both are sent through canonicalization, and the expected result is a special PowerShell script marker plus the script text.

Call relations: The test framework calls this function during testing. The function relies on assertion checks to show that the canonicalization logic ignores non-essential PowerShell wrapper details and produces the same approval key for equivalent scripts.

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

fn preserves_non_shell_commands()

Purpose: This test checks that ordinary commands are not changed when they are not shell or PowerShell wrappers. This protects normal commands from being over-simplified by the approval-key logic.

Data flow: It creates the command list cargo fmt, sends it through the canonicalization function, and compares the result with the original command list. The before and after should be identical.

Call relations: The test framework runs this function with the other canonicalization tests. Its assertion confirms the boundary of the feature: shell wrappers may be normalized, but plain commands should pass through unchanged.

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

fn shell_with_snapshot(
    shell_type: ShellType,
    shell_path: &str,
    snapshot_path: AbsolutePathBuf,
) -> (Shell, AbsolutePathBuf)

Purpose: This helper builds the two pieces of test data that represent a user shell and its saved snapshot file. It keeps the main test shorter and easier to read.

Data flow: It receives a shell type, a shell executable path as text, and an absolute path to a snapshot file. It turns the shell path into a path object, puts the shell type and path into a Shell value, and returns that together with the snapshot path unchanged.

Call relations: The main test calls this helper after creating a temporary snapshot file. The returned shell description and snapshot path are then passed into the command-preparation code so the test can simulate running through a real user shell setup.

Call graph: called by 1 (user_shell_snapshot_preserves_package_path_prepend); 1 external calls (from).

fn user_shell_snapshot_preserves_package_path_prepend()

Purpose: This test checks that adding a package directory to the front of PATH still wins after a shell snapshot is loaded. It exists to catch regressions where the snapshot would accidentally erase or outrank the runtime package path.

Data flow: It creates a temporary directory, writes a snapshot script that sets PATH to /snapshot/bin, and builds a bash command that prints PATH. It starts with an environment containing /worktree/bin, asks the command-preparation function to rewrite the command while prepending a temporary package path, then runs the rewritten command with the resulting PATH. Finally, it checks that the command succeeded and that the printed PATH is package-path:/snapshot/bin.

Call relations: During the test, it calls shell_with_snapshot to build the shell-and-snapshot inputs. It then exercises prepare_user_shell_exec_command_with_path_prepend, the production code being tested, and uses the operating system process runner to execute the rewritten command. The final assertions confirm that the rewrite did the right thing from the user's point of view.

Call graph: calls 1 internal fn (shell_with_snapshot); 8 external calls (from, new, assert!, assert_eq!, new, write, tempdir, vec!).

async fn pending_approvals_are_deduped_per_host_protocol_and_port()

Purpose: This test checks that two approval requests for the same host, protocol, and port share one pending approval instead of creating two separate prompts. This matters because the user should not be asked the same network question twice at the same time.

Data flow: It starts with a fresh NetworkApprovalService and builds one key for example.com over http on port 443. It asks the service for a pending approval twice with the same key. The first request should become the owner of the approval, the second should reuse the same pending approval object, and the test confirms both references point to the same shared item.

Call relations: The test creates the service with its default setup, then exercises the service method that creates or reuses pending approvals. It uses assertions to prove the first caller owns the decision and later callers wait on that same decision instead of starting a duplicate flow.

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

async fn pending_approvals_do_not_dedupe_across_ports()

Purpose: This test checks that network approval requests are not merged when only the port differs. A port is like a numbered door on the same building, so access to one door should not automatically cover another.

Data flow: It creates a fresh service and two approval keys for the same host and protocol but different ports: 443 and 8443. It asks for a pending approval for each key. Both requests should be treated as separate owner requests, and the two pending approval objects should be different.

Call relations: The test relies on the service's default state and then calls the pending-approval lookup twice with different keys. Its assertions protect the rule that deduplication is scoped to host, protocol, and port together.

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

async fn session_approved_hosts_preserve_protocol_and_port_scope()

Purpose: This test checks that session-wide approved hosts keep their exact protocol and port information when copied to another service. It prevents a broad, unsafe interpretation such as treating all example.com access as approved.

Data flow: It creates a source service and manually fills its session-approved set with three entries for the same host but different protocol or port combinations. It then creates another service and copies the session approvals into it. Finally, it reads back and sorts the copied entries, confirming all three distinct approvals are still present exactly as entered.

Call relations: The test uses the service's default setup, directly prepares the approved-host set, and then exercises sync_session_approved_hosts_to. The final equality check confirms that syncing keeps the approval boundaries intact.

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

async fn sync_session_approved_hosts_to_replaces_existing_target_hosts()

Purpose: This test checks that copying session-approved hosts into another service replaces the target's old approvals instead of mixing old and new ones. This avoids stale permissions carrying over by accident.

Data flow: It creates a source service with one approved host and a target service with a different, stale approved host. After syncing from source to target, it reads the target's approvals. The result should contain only the source approval, with the stale target approval gone.

Call relations: The test sets up both services from defaults, mutates their stored approved-host sets, and calls the sync method. Its assertion verifies the sync behaves like replacing a list, not appending to it.

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

async fn pending_waiters_receive_owner_decision()

Purpose: This test checks that tasks waiting on a pending approval receive the decision made by the owner of that approval. It verifies the basic handoff between the person or task deciding and the tasks waiting for that decision.

Data flow: It creates a shared PendingHostApproval, starts a background task that waits for a decision, and then sets the decision to AllowOnce. The waiting task completes and returns that same AllowOnce decision.

Call relations: The test creates the pending approval with new, shares it through a clone of the shared pointer, and uses a spawned asynchronous task to behave like a waiter. After set_decision runs, the final assertion confirms wait_for_decision receives the chosen value.

Call graph: calls 1 internal fn (new); 4 external calls (clone, new, assert_eq!, spawn).

fn allow_once_and_allow_for_session_both_allow_network()

Purpose: This test checks that both temporary approval and session-long approval translate into the same immediate network result: allow the request. The difference is how long the approval is remembered, not whether the current request may proceed.

Data flow: It takes two pending approval decisions, AllowOnce and AllowForSession, and converts each into the lower-level network decision. Both conversions should produce NetworkDecision::Allow.

Call relations: This is a small conversion test. It does not set up a service; it directly checks the mapping from user-facing approval choices to the network decision used by the enforcement path.

Call graph: 1 external calls (assert_eq!).

fn only_never_policy_disables_network_approval_flow()

Purpose: This test checks which user approval settings allow the network approval flow to run. Only the setting that says never ask for approval should disable it.

Data flow: It passes several AskForApproval settings into the approval-flow check. The Never setting should return false, while OnRequest, OnFailure, and UnlessTrusted should return true.

Call relations: The test directly exercises allows_network_approval_flow. Its assertions define the expected behavior for higher-level configuration before the network approval service is used.

Call graph: 1 external calls (assert!).

fn network_approval_flow_is_limited_to_restricted_sandbox_modes()

Purpose: This test checks that network approval prompts are available only in the sandbox modes where they make sense. A sandbox is a safety boundary around a command, and this approval flow is meant for restricted built-in modes, not every permission setup.

Data flow: It passes several PermissionProfile values into the permission-profile check. Read-only and workspace-write profiles should allow the approval flow, while fully disabled permissions and an external restricted network policy should not.

Call relations: The test directly exercises permission_profile_allows_network_approval_flow. It ties the network approval feature to the broader permission profile rules used before commands run.

Call graph: 1 external calls (assert!).

fn denied_blocked_request(host: &str) -> BlockedRequest

Purpose: This helper builds a sample blocked network request that represents a denied attempt to reach a host. It gives several tests a consistent fake request to feed into the service.

Data flow: It receives a host name as text. It builds BlockedRequestArgs with that host, a denial decision, http protocol, port 80, and other fixed details, then turns those arguments into a BlockedRequest. The returned request says, in effect, that this host was blocked by policy.

Call relations: Several tests call this helper before record_blocked_request is exercised. It keeps those tests focused on the service behavior instead of repeating the same blocked-request construction.

Call graph: calls 1 internal fn (new); called by 3 (blocked_request_policy_does_not_override_user_denial_outcome, record_blocked_request_ignores_ambiguous_unattributed_blocked_requests, record_blocked_request_sets_policy_outcome_for_owner_call).

async fn register_call_with_default_shell_trigger(
    service: &NetworkApprovalService,
    registration_id: &str,
) -> CancellationToken

Purpose: This helper registers a fake active shell command that would trigger network access. It gives tests a realistic active call to attach approvals or denials to.

Data flow: It receives a NetworkApprovalService and a registration id. It creates a cancellation token, then registers a call for a curl command against example.com with a default sandbox permission setup and a test working directory. It returns the cancellation token so the test can later check whether the service cancelled the call.

Call relations: Many tests use this helper before recording blocked requests or call outcomes. It hands off to the service's register_call method and supplies the common trigger context that those tests need.

Call graph: calls 1 internal fn (register_call); called by 6 (blocked_request_policy_does_not_override_user_denial_outcome, deferred_finish_reuses_denial_result_after_first_consumer, finish_call_returns_denial_and_unregisters_active_call, record_blocked_request_ignores_ambiguous_unattributed_blocked_requests, record_blocked_request_sets_policy_outcome_for_owner_call, record_call_outcome_ignores_inactive_call); 3 external calls (new, test_path_buf, vec!).

async fn active_call_preserves_triggering_command_context()

Purpose: This test checks that when a call is registered, the service keeps the exact command context that caused the possible network request. That context is what the user or policy code needs to understand what is asking for access.

Data flow: It builds an expected GuardianNetworkAccessTrigger containing the call id, tool name, command arguments, working directory, sandbox permissions, and justification. It registers that call with a command string, then asks the service to resolve the single active call. The returned call should contain the same trigger and command text.

Call relations: The test creates a default service, registers one call, and then uses resolve_single_active_call to read it back. Its assertions protect the connection between the active call record and the original command details.

Call graph: calls 1 internal fn (default); 4 external calls (new, assert_eq!, test_path_buf, vec!).

async fn record_blocked_request_sets_policy_outcome_for_owner_call()

Purpose: This test checks that when there is one active call and a denied network request appears, the service marks that call as denied by policy and cancels it. This prevents the command from continuing after network access has been blocked.

Data flow: It creates a service, registers one fake shell call, and keeps the returned cancellation token. It then records a blocked request for example.com. After that, the cancellation token should be cancelled, and taking the call outcome should return a policy-denial message explaining that the domain is not on the allowlist for the current sandbox mode.

Call relations: The test uses register_call_with_default_shell_trigger to create the active call and denied_blocked_request to create the blocked event. It then drives record_blocked_request and checks both visible effects: cancellation and stored denial outcome.

Call graph: calls 3 internal fn (default, denied_blocked_request, register_call_with_default_shell_trigger); 2 external calls (assert!, assert_eq!).

async fn blocked_request_policy_does_not_override_user_denial_outcome()

Purpose: This test checks that a user's denial is not overwritten by a later policy-denial record. The user's explicit choice should remain the final reason shown for the call.

Data flow: It creates a service, registers one active call, and records that the call was denied by the user. It then records a blocked request for the same general situation. When the outcome is taken, it should still be DeniedByUser, not replaced by a policy denial.

Call relations: The test sets up the active call through the shared helper, then calls record_call_outcome before record_blocked_request. It confirms that the blocked-request path respects an outcome that was already recorded.

Call graph: calls 3 internal fn (default, denied_blocked_request, register_call_with_default_shell_trigger); 1 external calls (assert_eq!).

async fn finish_call_returns_denial_and_unregisters_active_call()

Purpose: This test checks that finishing a call with a stored denial returns an error to the caller and removes the call from the active-call list. It also checks that the stored outcome is consumed so it does not linger.

Data flow: It creates a service, registers one active call, and records a policy denial with the message "network denied". It then finishes the call. The result should be a rejected tool error with that message, there should be no single active call left, and taking the outcome afterward should return nothing.

Call relations: The test uses the registration helper, stores a DeniedByPolicy outcome, and then exercises finish_call. The assertions connect three cleanup steps: reporting the denial, unregistering the call, and clearing the saved outcome.

Call graph: calls 2 internal fn (default, register_call_with_default_shell_trigger); 3 external calls (assert!, assert_eq!, DeniedByPolicy).

async fn deferred_finish_reuses_denial_result_after_first_consumer()

Purpose: This test checks that deferred finish logic gives the same denial result to more than one consumer. This is important when different parts of the system may ask for the result after the network approval path has already finished once.

Data flow: It registers one call, builds a DeferredNetworkApproval with the call's registration id, cancellation token, and an empty one-time result cell. It records a policy denial, then calls finish on the deferred object twice. Both calls should return the same rejected tool error with the same denial message.

Call relations: The test uses register_call_with_default_shell_trigger to create the call, then constructs DeferredNetworkApproval directly. It checks that DeferredNetworkApproval::finish caches the finish result instead of losing it after the first caller.

Call graph: calls 2 internal fn (default, register_call_with_default_shell_trigger); 4 external calls (new, new, assert!, DeniedByPolicy).

async fn record_call_outcome_ignores_inactive_call()

Purpose: This test checks that the service does not record or act on an outcome for a call that has already been unregistered. This avoids cancelling or reporting errors for work that is no longer active.

Data flow: It creates a service, registers one call, and then unregisters that call. Afterward it tries to record a policy denial for the same registration id. The cancellation token should not be cancelled, and there should be no stored outcome to take.

Call relations: The test prepares a normal active call through the helper, removes it with unregister_call, and then calls record_call_outcome. Its assertions prove that inactive registrations are ignored.

Call graph: calls 2 internal fn (default, register_call_with_default_shell_trigger); 3 external calls (assert!, assert_eq!, DeniedByPolicy).

async fn record_blocked_request_ignores_ambiguous_unattributed_blocked_requests()

Purpose: This test checks that when multiple calls are active and a blocked request cannot be tied to one specific call, the service does not guess. Guessing could blame or cancel the wrong command.

Data flow: It creates a service and registers two active shell calls. It then records one denied blocked request for example.com without any clear attribution to either call. When it checks both registrations, neither should have a stored outcome.

Call relations: The test uses the shared registration helper twice and denied_blocked_request once. It then drives record_blocked_request and confirms the service only assigns a blocked request when ownership is unambiguous.

Call graph: calls 3 internal fn (default, denied_blocked_request, register_call_with_default_shell_trigger); 1 external calls (assert_eq!).

fn bash_permission_request_payload_omits_missing_description()

Purpose: This test checks that a bash permission request does not include a description field when no description was provided. That keeps the request payload clean and avoids pretending there is extra context when there is none.

Data flow: It starts with a bash command, echo hi, and no description. It builds the expected permission request by hand, containing the bash tool name and only the command in the input data. The test then compares the real payload against that expected shape; if an unwanted description appears, the test fails.

Call relations: During the test suite, this test exercises PermissionRequestPayload::bash through a direct comparison. It relies on the assertion helper to catch any change in the payload format, so later code that displays or sends permission requests can depend on this exact behavior.

Call graph: 1 external calls (assert_eq!).

fn bash_permission_request_payload_includes_description_when_present()

Purpose: This test checks that a bash permission request includes the description when one is supplied. The description gives a reviewer extra context, such as why a command may need network access.

Data flow: It starts with the command echo hi and a description string. It expects the resulting request to name the bash tool and include both the command and the description in the input data. The output is not returned to other code here; the test passes only if the built payload exactly matches the expected one.

Call relations: This test is the companion to the missing-description test. Together they define when PermissionRequestPayload::bash should and should not add optional context before a permission prompt is shown or transmitted elsewhere.

Call graph: 1 external calls (assert_eq!).

fn external_sandbox_skips_exec_approval_on_request()

Purpose: This test checks that an external sandbox does not require an extra execution approval under the “ask on request” policy. In plain terms, if another sandboxing system is already responsible for protection, this path should not unnecessarily stop the command for approval.

Data flow: It provides an approval policy of OnRequest and an external filesystem sandbox policy. It asks the approval-decision function what should happen. The expected result is to skip approval, without bypassing the sandbox and without suggesting any policy change.

Call relations: This test calls into the default execution approval decision logic and verifies one special case. It protects the flow where the broader tool-running code asks, “Do I need to prompt the user before running this command?”

Call graph: 1 external calls (assert_eq!).

fn restricted_sandbox_requires_exec_approval_on_request()

Purpose: This test checks that the normal restricted sandbox still requires approval when the policy says approvals should happen on request. It makes sure restricted execution does not accidentally become automatic.

Data flow: It provides the OnRequest approval policy and the default filesystem sandbox policy. The approval logic produces a decision. The expected decision says approval is needed, with no extra reason text and no suggested policy amendment.

Call relations: This test covers the ordinary restricted-sandbox path used by the command execution system. It pairs with the external-sandbox test to show that the same approval policy can lead to different outcomes depending on what kind of sandbox is active.

Call graph: 1 external calls (assert_eq!).

fn default_exec_approval_requirement_rejects_sandbox_prompt_when_granular_disables_it()

Purpose: This test checks that granular approval settings can forbid a sandbox approval prompt. Granular approval means separate switches control separate kinds of permission prompts, instead of one all-or-nothing setting.

Data flow: It builds a granular approval configuration where sandbox approval is turned off while several other approval features remain on. It passes that policy and the default sandbox policy into the approval-decision function. The expected result is a forbidden decision with a clear reason saying sandbox approval prompts are disallowed.

Call relations: This test exercises the branch where AskForApproval::Granular is used. It confirms that the execution approval logic respects the specific sandbox_approval switch instead of assuming all granular configurations allow sandbox prompts.

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

fn default_exec_approval_requirement_keeps_prompt_when_granular_allows_sandbox_approval()

Purpose: This test checks the opposite granular-approval case: when sandbox approval is allowed, the system should still ask for approval under the default sandbox policy. It prevents a configuration mix-up where allowing prompts might accidentally skip them.

Data flow: It builds a granular approval configuration with sandbox approval turned on. It sends that policy and the default filesystem sandbox policy into the approval-decision function. The expected result says approval is needed, with no special reason and no proposed policy amendment.

Call relations: This test works alongside the granular-disabled test. Together they show that the approval decision follows the sandbox-approval flag precisely: off means forbidden, on means a normal approval prompt can be requested.

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

fn additional_permissions_allow_bypass_sandbox_first_attempt_when_execpolicy_skips()

Purpose: This test checks that when extra permissions are requested and the execution policy already says approval can be skipped with sandbox bypass, the first attempt is allowed to bypass the sandbox. It verifies the fast path for commands that are already permitted to run with more access.

Data flow: It starts with sandbox permissions set to WithAdditionalPermissions, an execution approval result that skips approval and allows sandbox bypass, and the default filesystem sandbox policy. It asks the sandbox override logic what to do for the first command attempt. The expected answer is to bypass the sandbox on that first attempt.

Call relations: This test exercises sandbox_override_for_first_attempt, the decision point that turns approval results and requested sandbox permissions into an actual execution mode. It confirms that the tool runner can honor an already-approved bypass when no extra filesystem denial blocks it.

Call graph: 1 external calls (assert_eq!).

fn guardian_bypasses_sandbox_for_explicit_escalation_on_first_attempt()

Purpose: This test checks that an explicit escalation request can bypass the sandbox on the first attempt, even when the skip decision itself did not ask to bypass. Escalation here means the command is marked as needing higher access than the default sandbox allows.

Data flow: It provides RequireEscalated sandbox permissions, an execution approval result that skips approval but does not set its own bypass flag, and the default filesystem sandbox policy. The sandbox override logic combines those inputs. The expected result is still to bypass the sandbox for the first attempt.

Call relations: This test covers another path through sandbox_override_for_first_attempt. It shows that an explicit elevated-permission request can drive the execution mode, not only the bypass flag inside the approval requirement.

Call graph: 1 external calls (assert_eq!).

fn deny_read_blocks_explicit_escalation_and_policy_bypass()

Purpose: This test checks a critical safety rule: if the sandbox policy denies reading certain files, the system must not bypass the sandbox in a way that removes that deny rule. It uses *.env files as the example, because those often contain secrets.

Data flow: It first builds a restricted filesystem policy with a deny rule for paths matching **/*.env. It then tries several decisions against that policy: explicit escalation, unsandboxed execution checks, permission preservation, and an execution-policy bypass. Each expected result keeps the command sandboxed or downgrades the requested sandbox permissions so the denied-read rule stays in force. It also compares the same preservation helper against the default policy to confirm escalation is only blocked when denied reads are present.

Call relations: This test ties together several safety helpers: sandbox_override_for_first_attempt, unsandboxed_execution_allowed, and sandbox_permissions_preserving_denied_reads. It tells the story of a command that might otherwise receive broader access, and verifies that denied-read filesystem rules have the final say.

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

fn test_turn_environment(environment_id: &str) -> crate::session::turn_context::TurnEnvironment

Purpose: This helper builds a simple fake turn environment for tests. A turn environment is the context for one interaction, including which execution environment is being used and what base path represents it.

Data flow: It takes an environment id as text. It creates a default test execution environment, points it at the system temporary directory, leaves the shell unset, and returns a ready-to-use TurnEnvironment for the test request.

Call relations: The individual tests call this helper whenever they need to build an ApplyPatchRequest. It keeps those tests focused on what they are checking instead of repeating the setup for a fake local or remote environment each time.

Call graph: calls 3 internal fn (new, default_for_tests, from_abs_path); called by 6 (approval_keys_include_environment_id, file_system_sandbox_context_uses_active_attempt, guardian_review_request_includes_patch_context, no_sandbox_attempt_has_no_file_system_context, permission_request_payload_uses_apply_patch_hook_name_and_aliases, sandbox_cwd_uses_patch_action_cwd); 2 external calls (temp_dir, new).

fn wants_no_sandbox_approval_granular_respects_sandbox_flag()

Purpose: This test checks that the runtime correctly decides whether sandbox approval is wanted when approval settings are more detailed. It protects the rule that the specific sandbox-approval flag must be respected.

Data flow: It creates an ApplyPatchRuntime, then feeds it different approval modes. It expects normal on-request approval to require sandbox approval, expects granular settings with sandbox approval turned off to say no, and expects granular settings with sandbox approval turned on to say yes.

Call relations: This test calls directly into the runtime decision method. It does not hand work off elsewhere; its role is to lock down the approval decision that later patch execution relies on.

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

async fn guardian_review_request_includes_patch_context()

Purpose: This test makes sure a request sent to the guardian approval system contains the actual patch details. The guardian is the review step that needs enough context to approve or reject a file change.

Data flow: It creates a fake patch that adds text to a temporary file, wraps that in an ApplyPatchRequest, and asks the runtime to build a guardian review request. The output is checked to ensure it includes the call id, working directory, affected files, and patch text.

Call relations: The test uses the shared turn-environment helper to build a realistic request, then calls the runtime method that formats the guardian request. It verifies that the approval layer receives the same patch context that the apply-patch action was built with.

Call graph: calls 3 internal fn (new_add_for_test, build_guardian_review_request, test_turn_environment); 4 external calls (from, assert_eq!, temp_dir, vec!).

async fn permission_request_payload_uses_apply_patch_hook_name_and_aliases()

Purpose: This test checks the permission-request message produced for apply-patch. It ensures the message names the tool as apply_patch and also includes aliases like Write and Edit, so permission rules that refer to those names can still match.

Data flow: It creates a fake add-file patch, puts it into an ApplyPatchRequest, and asks the runtime for the permission request payload. It then checks that the payload has the expected tool name, expected matcher aliases, and a JSON input containing the patch command.

Call relations: The test calls the runtime method that prepares permission-request data. That data is meant for the broader approval and permission system, so this test protects the contract between apply-patch and that system.

Call graph: calls 3 internal fn (new_add_for_test, new, test_turn_environment); 4 external calls (new, assert_eq!, temp_dir, vec!).

async fn approval_keys_include_environment_id()

Purpose: This test confirms that approval keys include not only the file path but also the environment id. That matters because the same path may mean different things in different environments, such as local and remote machines.

Data flow: It creates an ApplyPatchRequest using a fake environment id of remote and a temporary file path. It asks the runtime for approval keys and checks that the serialized result contains both the remote environment id and the path.

Call relations: The test builds its request with the shared helper, then calls the runtime’s approval-key builder. The resulting key is used by approval caching or matching, so this test makes sure approvals are scoped to the right environment.

Call graph: calls 3 internal fn (new_add_for_test, new, test_turn_environment); 4 external calls (new, assert_eq!, temp_dir, vec!).

async fn sandbox_cwd_uses_patch_action_cwd()

Purpose: This test checks that the sandbox working directory comes from the patch action itself. The working directory is the folder context the sandbox should use when applying the patch.

Data flow: It creates a fake patch request for a temporary file, then asks the runtime for the sandbox current working directory. The returned value is expected to be the same directory stored on the ApplyPatchAction.

Call relations: The test calls the runtime method that supplies sandbox setup information. This connects the patch action to the sandbox runner, ensuring the sandbox starts from the same location the patch was prepared for.

Call graph: calls 3 internal fn (new_add_for_test, new, test_turn_environment); 4 external calls (new, assert_eq!, temp_dir, vec!).

async fn file_system_sandbox_context_uses_active_attempt()

Purpose: This test verifies that when a real sandbox attempt is active, the runtime builds a file-system sandbox context from that attempt. It checks that extra file permissions and platform-specific sandbox settings are preserved.

Data flow: It creates a patch request with additional read-write permission for a temporary path, builds a sandbox attempt using a macOS-style sandbox type, and asks the runtime for a sandbox context. It then calculates the expected effective permissions and compares them with the returned context, along with the sandbox working directory and Windows/Linux-related settings carried through the attempt.

Call relations: This test combines several pieces: the request, the additional permission profile, and the active SandboxAttempt. It calls the runtime conversion method and verifies that the result is suitable for downstream file-system sandbox reporting or execution.

Call graph: calls 10 internal fn (new_add_for_test, file_system_sandbox_context_for_attempt, test_turn_environment, from_read_write_roots, from_runtime_permissions, default, new, effective_file_system_sandbox_policy, effective_network_sandbox_policy, from_abs_path); 6 external calls (new, new, assert_eq!, temp_dir, from_ref, vec!).

async fn no_sandbox_attempt_has_no_file_system_context()

Purpose: This test checks the opposite case from the sandbox-context test: if the chosen sandbox type is none, the runtime should return no file-system sandbox context. This avoids reporting restrictions that are not actually in force.

Data flow: It creates a patch request and a sandbox attempt whose sandbox type is None and whose permissions are disabled. It asks the runtime for a file-system sandbox context and expects the answer to be None.

Call relations: The test uses the same request-building pattern as the other sandbox tests, then calls the same runtime conversion method. It confirms that the runtime only produces sandbox context when there is a real sandbox attempt to describe.

Call graph: calls 4 internal fn (new_add_for_test, test_turn_environment, new, from_abs_path); 5 external calls (new, assert_eq!, temp_dir, from_ref, vec!).