test: add E2E tests and scenario for tool overrides

Add E2E tests across all 4 SDKs verifying that registering a custom tool
with the same name as a built-in tool (e.g., 'grep') causes the custom
tool to be invoked instead of the built-in. This validates the
mergeExcludedTools feature end-to-end.

- Add 'overrides built-in tool with custom tool' test to Node, Python, Go, .NET
- Add YAML snapshot for the replay proxy
- Add test/scenarios/tools/tool-overrides/ with all 4 language implementations

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

Author: 2 people

dotnet/test/ToolsTests.cs

@@ -152,6 +152,29 @@ record City(int CountryId, string CityName, int Population);
     [JsonSerializable(typeof(JsonElement))]
     private partial class ToolsTestsJsonContext : JsonSerializerContext;
 
+    [Fact]
+    public async Task Overrides_Built_In_Tool_With_Custom_Tool()
+    {
+        var session = await CreateSessionAsync(new SessionConfig
+        {
+            Tools = [AIFunctionFactory.Create(CustomGrep, "grep")],
+            OnPermissionRequest = PermissionHandler.ApproveAll,
+        });
+
+        await session.SendAsync(new MessageOptions
+        {
+            Prompt = "Use grep to search for the word 'hello'"
+        });
+
+        var assistantMessage = await TestHelper.GetFinalAssistantMessageAsync(session);
+        Assert.NotNull(assistantMessage);
+        Assert.Contains("CUSTOM_GREP_RESULT", assistantMessage!.Data.Content ?? string.Empty);
+
+        [Description("A custom grep implementation that overrides the built-in")]
+        static string CustomGrep([Description("Search query")] string query)
+            => $"CUSTOM_GREP_RESULT: {query}";
+    }
+
     [Fact(Skip = "Behaves as if no content was in the result. Likely that binary results aren't fully implemented yet.")]
     public async Task Can_Return_Binary_Result()
     {

go/internal/e2e/tools_test.go

@@ -264,6 +264,41 @@ func TestTools(t *testing.T) {
 		}
 	})
 
+	t.Run("overrides built-in tool with custom tool", func(t *testing.T) {
+		ctx.ConfigureForTest(t)
+
+		type GrepParams struct {
+			Query string `json:"query" jsonschema:"Search query"`
+		}
+
+		session, err := client.CreateSession(t.Context(), &copilot.SessionConfig{
+			OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+			Tools: []copilot.Tool{
+				copilot.DefineTool("grep", "A custom grep implementation that overrides the built-in",
+					func(params GrepParams, inv copilot.ToolInvocation) (string, error) {
+						return "CUSTOM_GREP_RESULT: " + params.Query, nil
+					}),
+			},
+		})
+		if err != nil {
+			t.Fatalf("Failed to create session: %v", err)
+		}
+
+		_, err = session.Send(t.Context(), copilot.MessageOptions{Prompt: "Use grep to search for the word 'hello'"})
+		if err != nil {
+			t.Fatalf("Failed to send message: %v", err)
+		}
+
+		answer, err := testharness.GetFinalAssistantMessage(t.Context(), session)
+		if err != nil {
+			t.Fatalf("Failed to get assistant message: %v", err)
+		}
+
+		if answer.Data.Content == nil || !strings.Contains(*answer.Data.Content, "CUSTOM_GREP_RESULT") {
+			t.Errorf("Expected answer to contain 'CUSTOM_GREP_RESULT', got %v", answer.Data.Content)
+		}
+	})
+
 	t.Run("invokes custom tool with permission handler", func(t *testing.T) {
 		ctx.ConfigureForTest(t)
 

nodejs/test/e2e/tools.test.ts

@@ -162,6 +162,26 @@ describe("Custom tools", async () => {
         expect(customToolRequests[0].toolName).toBe("encrypt_string");
     });
 
+    it("overrides built-in tool with custom tool", async () => {
+        const session = await client.createSession({
+            onPermissionRequest: approveAll,
+            tools: [
+                defineTool("grep", {
+                    description: "A custom grep implementation that overrides the built-in",
+                    parameters: z.object({
+                        query: z.string().describe("Search query"),
+                    }),
+                    handler: ({ query }) => `CUSTOM_GREP_RESULT: ${query}`,
+                }),
+            ],
+        });
+
+        const assistantMessage = await session.sendAndWait({
+            prompt: "Use grep to search for the word 'hello'",
+        });
+        expect(assistantMessage?.data.content).toContain("CUSTOM_GREP_RESULT");
+    });
+
     it("denies custom tool when permission denied", async () => {
         let toolHandlerCalled = false;
 

python/e2e/test_tools.py

@@ -133,6 +133,22 @@ def db_query(params: DbQueryParams, invocation: ToolInvocation) -> list[City]:
         assert "135460" in response_content.replace(",", "")
         assert "204356" in response_content.replace(",", "")
 
+    async def test_overrides_built_in_tool_with_custom_tool(self, ctx: E2ETestContext):
+        class GrepParams(BaseModel):
+            query: str = Field(description="Search query")
+
+        @define_tool("grep", description="A custom grep implementation that overrides the built-in")
+        def custom_grep(params: GrepParams, invocation: ToolInvocation) -> str:
+            return f"CUSTOM_GREP_RESULT: {params.query}"
+
+        session = await ctx.client.create_session(
+            {"tools": [custom_grep], "on_permission_request": PermissionHandler.approve_all}
+        )
+
+        await session.send({"prompt": "Use grep to search for the word 'hello'"})
+        assistant_message = await get_final_assistant_message(session)
+        assert "CUSTOM_GREP_RESULT" in assistant_message.data.content
+
     async def test_invokes_custom_tool_with_permission_handler(self, ctx: E2ETestContext):
         class EncryptParams(BaseModel):
             input: str = Field(description="String to encrypt")

test/scenarios/tools/tool-overrides/README.md

@@ -0,0 +1,31 @@
+# Config Sample: Tool Overrides
+
+Demonstrates how registering a custom tool with the same name as a built-in tool automatically overrides the built-in. The SDK's `mergeExcludedTools` logic adds custom tool names to `excludedTools`, so the CLI uses your implementation instead.
+
+## What Each Sample Does
+
+1. Creates a session with a custom `grep` tool that returns `"CUSTOM_GREP_RESULT: <query>"`
+2. Sends: _"Use grep to search for the word 'hello'"_
+3. Prints the response — which should contain `CUSTOM_GREP_RESULT` (proving the custom tool ran, not the built-in)
+
+## Configuration
+
+| Option | Value | Effect |
+|--------|-------|--------|
+| `tools` | Custom `grep` tool | Overrides the built-in `grep` with a custom implementation |
+
+Behind the scenes, the SDK automatically adds `"grep"` to `excludedTools` so the CLI's built-in grep is disabled.
+
+## Run
+
+```bash
+./verify.sh
+```
+
+Requires the `copilot` binary (auto-detected or set `COPILOT_CLI_PATH`) and `GITHUB_TOKEN`.
+
+## Verification
+
+The verify script checks that:
+- The response contains `CUSTOM_GREP_RESULT` (custom tool was invoked)
+- The response does **not** contain typical built-in grep output patterns

test/scenarios/tools/tool-overrides/csharp/Program.cs

@@ -0,0 +1,39 @@
+using System.ComponentModel;
+using GitHub.Copilot.SDK;
+using Microsoft.Extensions.AI;
+
+using var client = new CopilotClient(new CopilotClientOptions
+{
+    CliPath = Environment.GetEnvironmentVariable("COPILOT_CLI_PATH"),
+    GitHubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN"),
+});
+
+await client.StartAsync();
+
+try
+{
+    await using var session = await client.CreateSessionAsync(new SessionConfig
+    {
+        Model = "claude-haiku-4.5",
+        OnPermissionRequest = PermissionHandler.ApproveAll,
+        Tools = [AIFunctionFactory.Create(CustomGrep, "grep")],
+    });
+
+    var response = await session.SendAndWaitAsync(new MessageOptions
+    {
+        Prompt = "Use grep to search for the word 'hello'",
+    });
+
+    if (response != null)
+    {
+        Console.WriteLine(response.Data?.Content);
+    }
+}
+finally
+{
+    await client.StopAsync();
+}
+
+[Description("A custom grep implementation that overrides the built-in")]
+static string CustomGrep([Description("Search query")] string query)
+    => $"CUSTOM_GREP_RESULT: {query}";

test/scenarios/tools/tool-overrides/csharp/csharp.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <RollForward>LatestMajor</RollForward>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <CopilotSkipCliDownload>true</CopilotSkipCliDownload>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="../../../../../dotnet/src/GitHub.Copilot.SDK.csproj" />
+  </ItemGroup>
+</Project>

test/scenarios/tools/tool-overrides/go/go.mod

@@ -0,0 +1,9 @@
+module github.com/github/copilot-sdk/samples/tools/tool-overrides/go
+
+go 1.24
+
+require github.com/github/copilot-sdk/go v0.0.0
+
+require github.com/google/jsonschema-go v0.4.2 // indirect
+
+replace github.com/github/copilot-sdk/go => ../../../../../go

test/scenarios/tools/tool-overrides/go/go.sum

@@ -0,0 +1,4 @@
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
+github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=

test/scenarios/tools/tool-overrides/go/main.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	copilot "github.com/github/copilot-sdk/go"
+)
+
+type GrepParams struct {
+	Query string `json:"query" jsonschema:"Search query"`
+}
+
+func main() {
+	client := copilot.NewClient(&copilot.ClientOptions{
+		GitHubToken: os.Getenv("GITHUB_TOKEN"),
+	})
+
+	ctx := context.Background()
+	if err := client.Start(ctx); err != nil {
+		log.Fatal(err)
+	}
+	defer client.Stop()
+
+	session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+		Model:              "claude-haiku-4.5",
+		OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+		Tools: []copilot.Tool{
+			copilot.DefineTool("grep", "A custom grep implementation that overrides the built-in",
+				func(params GrepParams, inv copilot.ToolInvocation) (string, error) {
+					return "CUSTOM_GREP_RESULT: " + params.Query, nil
+				}),
+		},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer session.Destroy()
+
+	response, err := session.SendAndWait(ctx, copilot.MessageOptions{
+		Prompt: "Use grep to search for the word 'hello'",
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	if response != nil && response.Data.Content != nil {
+		fmt.Println(*response.Data.Content)
+	}
+}