Add low-level tool definition E2E coverage

Add a new Java failsafe integration test and replay snapshot that exercise the
current explicit tool-definition APIs before ergonomic annotations are added.

- add `LowLevelToolDefinitionIT` covering `create`, `createOverride`,
  `getArgumentsAs(record)`, `getArguments()`, and `ToolSet` available tools
- add `tools/low_level_tool_definition.yaml` with multi-tool call and final
  response replay conversations
- assert handler-driven state mutation (`currentPhase`) and expected response
  content

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: edburns

java/src/test/java/com/github/copilot/LowLevelToolDefinitionIT.java

@@ -0,0 +1,111 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import com.github.copilot.generated.AssistantMessageEvent;
+import com.github.copilot.rpc.MessageOptions;
+import com.github.copilot.rpc.PermissionHandler;
+import com.github.copilot.rpc.SessionConfig;
+import com.github.copilot.rpc.ToolDefinition;
+import com.github.copilot.rpc.ToolSet;
+
+/**
+ * Failsafe integration test for explicit (non-ergonomic) tool definition APIs.
+ *
+ * @see Snapshot: tools/low_level_tool_definition
+ */
+class LowLevelToolDefinitionIT {
+
+    private static E2ETestContext ctx;
+    private String currentPhase;
+
+    record PhaseArgs(String phase) {
+    }
+
+    @BeforeAll
+    static void setup() throws Exception {
+        ctx = E2ETestContext.create();
+    }
+
+    @AfterAll
+    static void teardown() throws Exception {
+        if (ctx != null) {
+            ctx.close();
+        }
+    }
+
+    @Test
+    void lowLevelToolDefinition() throws Exception {
+        ctx.configureForTest("tools", "low_level_tool_definition");
+
+        Map<String, Object> setPhaseSchema = Map.of("type", "object", "properties",
+                Map.of("phase", Map.of("type", "string", "enum", List.of("searching", "analyzing", "done"))),
+                "required", List.of("phase"));
+
+        ToolDefinition setPhaseTool = ToolDefinition.create("set_current_phase", "Sets the current phase of the agent",
+                setPhaseSchema, invocation -> {
+                    PhaseArgs args = invocation.getArgumentsAs(PhaseArgs.class);
+                    currentPhase = args.phase();
+                    return CompletableFuture.completedFuture("Phase set to " + currentPhase);
+                });
+
+        Map<String, Object> searchSchema = Map.of("type", "object", "properties",
+                Map.of("keyword", Map.of("type", "string")), "required", List.of("keyword"));
+
+        ToolDefinition searchTool = ToolDefinition.create("search_items", "Search for items by keyword", searchSchema,
+                invocation -> {
+                    Map<String, Object> args = invocation.getArguments();
+                    args.get("keyword");
+                    return CompletableFuture.completedFuture("Found: item_alpha, item_beta");
+                });
+
+        Map<String, Object> grepSchema = Map.of("type", "object", "properties",
+                Map.of("query", Map.of("type", "string")), "required", List.of("query"));
+
+        ToolDefinition grepOverrideTool = ToolDefinition.createOverride("grep", "Custom grep override", grepSchema,
+                invocation -> {
+                    Map<String, Object> args = invocation.getArguments();
+                    String query = (String) args.get("query");
+                    return CompletableFuture.completedFuture("CUSTOM_GREP: " + query);
+                });
+
+        try (CopilotClient client = ctx.createClient()) {
+            CopilotSession session = client
+                    .createSession(new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                            .setAvailableTools(new ToolSet().addCustom("*").addBuiltIn("web_fetch"))
+                            .setTools(List.of(setPhaseTool, searchTool, grepOverrideTool)))
+                    .get(30, TimeUnit.SECONDS);
+
+            try {
+                AssistantMessageEvent response = session.sendAndWait(new MessageOptions().setPrompt(
+                        "First, set the current phase to 'analyzing'. Then search for items with keyword 'copilot'. Report the phase and search results."),
+                        60_000).get(90, TimeUnit.SECONDS);
+
+                assertNotNull(response, "Expected a response from the assistant");
+                String content = response.getData().content().toLowerCase();
+                assertTrue(content.contains("analyzing"),
+                        "Response should contain the updated phase: " + response.getData().content());
+                assertTrue(content.contains("item_alpha") || content.contains("item_beta"),
+                        "Response should contain search results: " + response.getData().content());
+                assertTrue("analyzing".equals(currentPhase),
+                        "Expected currentPhase to be analyzing but was: " + currentPhase);
+            } finally {
+                session.close();
+            }
+        }
+    }
+}

test/snapshots/tools/low_level_tool_definition.yaml

@@ -0,0 +1,49 @@
+models:
+  - claude-sonnet-4.5
+conversations:
+  - messages:
+      - role: system
+        content: ${system}
+      - role: user
+        content: First, set the current phase to 'analyzing'. Then search for items with keyword 'copilot'. Report the phase and search results.
+      - role: assistant
+        content: I'll set the phase and run the search now.
+        tool_calls:
+          - id: toolcall_0
+            type: function
+            function:
+              name: set_current_phase
+              arguments: '{"phase":"analyzing"}'
+          - id: toolcall_1
+            type: function
+            function:
+              name: search_items
+              arguments: '{"keyword":"copilot"}'
+  - messages:
+      - role: system
+        content: ${system}
+      - role: user
+        content: First, set the current phase to 'analyzing'. Then search for items with keyword 'copilot'. Report the phase and search results.
+      - role: assistant
+        content: I'll set the phase and run the search now.
+        tool_calls:
+          - id: toolcall_0
+            type: function
+            function:
+              name: set_current_phase
+              arguments: '{"phase":"analyzing"}'
+          - id: toolcall_1
+            type: function
+            function:
+              name: search_items
+              arguments: '{"keyword":"copilot"}'
+      - role: tool
+        tool_call_id: toolcall_0
+        content: Phase set to analyzing
+      - role: tool
+        tool_call_id: toolcall_1
+        content: "Found: item_alpha, item_beta"
+      - role: assistant
+        content: |-
+          Current phase: analyzing
+          Search results: item_alpha, item_beta