Replace excludedTools merging with overridesBuiltInTool flag

Instead of merging SDK tool names into excludedTools (which semantically
abuses the exclude mechanism), each tool now declares overridesBuiltInTool
when it intentionally replaces a built-in tool. The runtime uses this flag
to detect accidental name clashes (error) vs intentional overrides.

Changes across all 4 SDKs (Node.js, Python, Go, .NET):
- Add overridesBuiltInTool field to tool definitions
- Remove mergeExcludedTools / inline merge logic
- Pass overridesBuiltInTool through wire protocol to runtime
- Update tests and documentation

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

Author: SteveSandersonMS

dotnet/README.md

@@ -417,15 +417,23 @@ When Copilot invokes `lookup_issue`, the client automatically runs your handler
 
 #### Overriding Built-in Tools
 
-If you register a tool with the same name as a built-in CLI tool (e.g. `edit_file`, `read_file`), your tool takes precedence. The SDK automatically adds the tool name to `ExcludedTools`, so the built-in is disabled and your handler is called instead. This is useful when you need custom behavior for built-in operations.
+If you register a tool with the same name as a built-in CLI tool (e.g. `edit_file`, `read_file`), the SDK will throw an error unless you explicitly opt in by setting `BuiltInToolOverrides` on the session config. This flag signals that you intend to replace the built-in tool with your custom implementation.
 
 ```csharp
+// Register the custom tool
 AIFunctionFactory.Create(
     async ([Description("File path")] string path, [Description("New content")] string content) => {
         // your logic
     },
     "edit_file",
     "Custom file editor with project-specific validation")
+
+// Opt in to overriding the built-in tool in session config
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    Model = "gpt-5",
+    BuiltInToolOverrides = new HashSet<string> { "edit_file" }
+});
 ```
 
 ### System Message Customization

dotnet/src/Client.cs

@@ -386,10 +386,11 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
             config.SessionId,
             config.ClientName,
             config.ReasoningEffort,
-            config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
+            config.Tools?.Select(f => ToolDefinition.FromAIFunction(f,
+                config.BuiltInToolOverrides?.Contains(f.Name) == true)).ToList(),
             config.SystemMessage,
             config.AvailableTools,
-            MergeExcludedTools(config.ExcludedTools, config.Tools),
+            config.ExcludedTools,
             config.Provider,
             (bool?)true,
             config.OnUserInputRequest != null ? true : null,
@@ -477,10 +478,11 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
             config.ClientName,
             config.Model,
             config.ReasoningEffort,
-            config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
+            config.Tools?.Select(f => ToolDefinition.FromAIFunction(f,
+                config.BuiltInToolOverrides?.Contains(f.Name) == true)).ToList(),
             config.SystemMessage,
             config.AvailableTools,
-            MergeExcludedTools(config.ExcludedTools, config.Tools),
+            config.ExcludedTools,
             config.Provider,
             (bool?)true,
             config.OnUserInputRequest != null ? true : null,
@@ -862,14 +864,6 @@ private void DispatchLifecycleEvent(SessionLifecycleEvent evt)
         }
     }
 
-    internal static List<string>? MergeExcludedTools(List<string>? excludedTools, ICollection<AIFunction>? tools)
-    {
-        var toolNames = tools?.Select(t => t.Name).ToList();
-        if (toolNames is null or { Count: 0 }) return excludedTools;
-        if (excludedTools is null or { Count: 0 }) return toolNames;
-        return excludedTools.Union(toolNames).ToList();
-    }
-
     internal static async Task<T> InvokeRpcAsync<T>(JsonRpc rpc, string method, object?[]? args, CancellationToken cancellationToken)
     {
         return await InvokeRpcAsync<T>(rpc, method, args, null, cancellationToken);
@@ -1424,10 +1418,12 @@ internal record CreateSessionRequest(
     internal record ToolDefinition(
         string Name,
         string? Description,
-        JsonElement Parameters /* JSON schema */)
+        JsonElement Parameters, /* JSON schema */
+        bool? OverridesBuiltInTool = null)
     {
-        public static ToolDefinition FromAIFunction(AIFunction function)
-            => new ToolDefinition(function.Name, function.Description, function.JsonSchema);
+        public static ToolDefinition FromAIFunction(AIFunction function, bool overridesBuiltInTool = false)
+            => new ToolDefinition(function.Name, function.Description, function.JsonSchema,
+                overridesBuiltInTool ? true : null);
     }
 
     internal record CreateSessionResponse(

dotnet/src/Types.cs

@@ -775,6 +775,7 @@ protected SessionConfig(SessionConfig? other)
         Streaming = other.Streaming;
         SystemMessage = other.SystemMessage;
         Tools = other.Tools is not null ? [.. other.Tools] : null;
+        BuiltInToolOverrides = other.BuiltInToolOverrides is not null ? [.. other.BuiltInToolOverrides] : null;
         WorkingDirectory = other.WorkingDirectory;
     }
 
@@ -802,6 +803,14 @@ protected SessionConfig(SessionConfig? other)
     public string? ConfigDir { get; set; }
 
     public ICollection<AIFunction>? Tools { get; set; }
+
+    /// <summary>
+    /// Set of tool names that are intended to override built-in tools of the same name.
+    /// If a tool name clashes with a built-in tool and is not in this set, the runtime
+    /// will return an error.
+    /// </summary>
+    public HashSet<string>? BuiltInToolOverrides { get; set; }
+
     public SystemMessageConfig? SystemMessage { get; set; }
     public List<string>? AvailableTools { get; set; }
     public List<string>? ExcludedTools { get; set; }
@@ -912,6 +921,7 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
         Streaming = other.Streaming;
         SystemMessage = other.SystemMessage;
         Tools = other.Tools is not null ? [.. other.Tools] : null;
+        BuiltInToolOverrides = other.BuiltInToolOverrides is not null ? [.. other.BuiltInToolOverrides] : null;
         WorkingDirectory = other.WorkingDirectory;
     }
 
@@ -928,6 +938,13 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
 
     public ICollection<AIFunction>? Tools { get; set; }
 
+    /// <summary>
+    /// Set of tool names that are intended to override built-in tools of the same name.
+    /// If a tool name clashes with a built-in tool and is not in this set, the runtime
+    /// will return an error.
+    /// </summary>
+    public HashSet<string>? BuiltInToolOverrides { get; set; }
+
     /// <summary>
     /// System message configuration.
     /// </summary>

dotnet/test/MergeExcludedToolsTests.cs

@@ -4,74 +4,56 @@
 
 using Microsoft.Extensions.AI;
 using System.ComponentModel;
+using System.Text.Json;
 using Xunit;
 
 namespace GitHub.Copilot.SDK.Test;
 
-public class MergeExcludedToolsTests
+public class OverridesBuiltInToolTests
 {
     [Fact]
-    public void Tool_Names_Are_Added_To_ExcludedTools()
+    public void ToolDefinition_FromAIFunction_Sets_OverridesBuiltInTool()
     {
-        var tools = new List<AIFunction>
-        {
-            AIFunctionFactory.Create(Noop, "my_tool"),
-        };
+        var fn = AIFunctionFactory.Create(Noop, "grep");
+        var def = CopilotClient.ToolDefinition.FromAIFunction(fn, overridesBuiltInTool: true);
 
-        var result = CopilotClient.MergeExcludedTools(null, tools);
-
-        Assert.NotNull(result);
-        Assert.Contains("my_tool", result!);
+        Assert.Equal("grep", def.Name);
+        Assert.True(def.OverridesBuiltInTool);
     }
 
     [Fact]
-    public void Merges_With_Existing_ExcludedTools_And_Deduplicates()
+    public void ToolDefinition_FromAIFunction_Omits_OverridesBuiltInTool_When_False()
     {
-        var existing = new List<string> { "view", "my_tool" };
-        var tools = new List<AIFunction>
-        {
-            AIFunctionFactory.Create(Noop, "my_tool"),
-            AIFunctionFactory.Create(Noop, "another_tool"),
-        };
-
-        var result = CopilotClient.MergeExcludedTools(existing, tools);
+        var fn = AIFunctionFactory.Create(Noop, "custom_tool");
+        var def = CopilotClient.ToolDefinition.FromAIFunction(fn, overridesBuiltInTool: false);
 
-        Assert.NotNull(result);
-        Assert.Equal(3, result!.Count);
-        Assert.Contains("view", result);
-        Assert.Contains("my_tool", result);
-        Assert.Contains("another_tool", result);
+        Assert.Equal("custom_tool", def.Name);
+        Assert.Null(def.OverridesBuiltInTool);
     }
 
     [Fact]
-    public void Returns_Null_When_No_Tools_Provided()
+    public void SessionConfig_BuiltInToolOverrides_Is_Used()
     {
-        var result = CopilotClient.MergeExcludedTools(null, null);
-        Assert.Null(result);
-    }
-
-    [Fact]
-    public void Returns_ExcludedTools_Unchanged_When_Tools_Empty()
-    {
-        var existing = new List<string> { "view" };
-        var result = CopilotClient.MergeExcludedTools(existing, new List<AIFunction>());
+        var config = new SessionConfig
+        {
+            Tools = new List<AIFunction> { AIFunctionFactory.Create(Noop, "grep") },
+            BuiltInToolOverrides = new HashSet<string> { "grep" },
+        };
 
-        Assert.Same(existing, result);
+        Assert.Contains("grep", config.BuiltInToolOverrides);
     }
 
     [Fact]
-    public void Returns_Tool_Names_When_ExcludedTools_Null()
+    public void ResumeSessionConfig_BuiltInToolOverrides_Is_Used()
     {
-        var tools = new List<AIFunction>
+        var config = new ResumeSessionConfig
         {
-            AIFunctionFactory.Create(Noop, "my_tool"),
+            Tools = new List<AIFunction> { AIFunctionFactory.Create(Noop, "grep") },
+            BuiltInToolOverrides = new HashSet<string> { "grep" },
         };
 
-        var result = CopilotClient.MergeExcludedTools(null, tools);
-
-        Assert.NotNull(result);
-        Assert.Single(result!);
-        Assert.Equal("my_tool", result[0]);
+        Assert.NotNull(config.BuiltInToolOverrides);
+        Assert.Contains("grep", config.BuiltInToolOverrides!);
     }
 
     [Description("No-op")]

dotnet/test/ToolsTests.cs

@@ -158,6 +158,7 @@ public async Task Overrides_Built_In_Tool_With_Custom_Tool()
         var session = await CreateSessionAsync(new SessionConfig
         {
             Tools = [AIFunctionFactory.Create(CustomGrep, "grep")],
+            BuiltInToolOverrides = ["grep"],
             OnPermissionRequest = PermissionHandler.ApproveAll,
         });
 

go/README.md

@@ -269,13 +269,14 @@ When the model selects a tool, the SDK automatically runs your handler (in paral
 
 #### Overriding Built-in Tools
 
-If you register a tool with the same name as a built-in CLI tool (e.g. `edit_file`, `read_file`), your tool takes precedence. The SDK automatically adds the tool name to `ExcludedTools`, so the built-in is disabled and your handler is called instead. This is useful when you need custom behavior for built-in operations.
+If you register a tool with the same name as a built-in CLI tool (e.g. `edit_file`, `read_file`), the SDK will throw an error unless you explicitly opt in by setting `OverridesBuiltInTool = true`. This flag signals that you intend to replace the built-in tool with your custom implementation.
 
 ```go
 editFile := copilot.DefineTool("edit_file", "Custom file editor with project-specific validation",
     func(params EditFileParams, inv copilot.ToolInvocation) (any, error) {
         // your logic
     })
+editFile.OverridesBuiltInTool = true
 ```
 
 ## Streaming

go/client.go

@@ -491,7 +491,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	req.Tools = config.Tools
 	req.SystemMessage = config.SystemMessage
 	req.AvailableTools = config.AvailableTools
-	req.ExcludedTools = mergeExcludedTools(config.ExcludedTools, config.Tools)
+	req.ExcludedTools = config.ExcludedTools
 	req.Provider = config.Provider
 	req.WorkingDirectory = config.WorkingDirectory
 	req.MCPServers = config.MCPServers
@@ -588,7 +588,7 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	req.Tools = config.Tools
 	req.Provider = config.Provider
 	req.AvailableTools = config.AvailableTools
-	req.ExcludedTools = mergeExcludedTools(config.ExcludedTools, config.Tools)
+	req.ExcludedTools = config.ExcludedTools
 	if config.Streaming {
 		req.Streaming = Bool(true)
 	}
@@ -1410,29 +1410,6 @@ func buildFailedToolResult(internalError string) ToolResult {
 	}
 }
 
-// mergeExcludedTools returns a deduplicated list combining excludedTools with
-// the names of any SDK-registered tools, so the CLI won't handle them.
-func mergeExcludedTools(excludedTools []string, tools []Tool) []string {
-	if len(tools) == 0 {
-		return excludedTools
-	}
-	seen := make(map[string]bool, len(excludedTools)+len(tools))
-	merged := make([]string, 0, len(excludedTools)+len(tools))
-	for _, name := range excludedTools {
-		if !seen[name] {
-			seen[name] = true
-			merged = append(merged, name)
-		}
-	}
-	for _, t := range tools {
-		if !seen[t.Name] {
-			seen[t.Name] = true
-			merged = append(merged, t.Name)
-		}
-	}
-	return merged
-}
-
 // buildUnsupportedToolResult creates a failure ToolResult for an unsupported tool.
 func buildUnsupportedToolResult(toolName string) ToolResult {
 	return ToolResult{

go/client_test.go

@@ -448,6 +448,47 @@ func TestResumeSessionRequest_ClientName(t *testing.T) {
 	})
 }
 
+func TestOverridesBuiltInTool(t *testing.T) {
+	t.Run("OverridesBuiltInTool is serialized in tool definition", func(t *testing.T) {
+		tool := Tool{
+			Name:                 "grep",
+			Description:          "Custom grep",
+			OverridesBuiltInTool: true,
+			Handler:              func(_ ToolInvocation) (ToolResult, error) { return ToolResult{}, nil },
+		}
+		data, err := json.Marshal(tool)
+		if err != nil {
+			t.Fatalf("failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("failed to unmarshal: %v", err)
+		}
+		if v, ok := m["overridesBuiltInTool"]; !ok || v != true {
+			t.Errorf("expected overridesBuiltInTool=true, got %v", m)
+		}
+	})
+
+	t.Run("OverridesBuiltInTool omitted when false", func(t *testing.T) {
+		tool := Tool{
+			Name:        "custom_tool",
+			Description: "A custom tool",
+			Handler:     func(_ ToolInvocation) (ToolResult, error) { return ToolResult{}, nil },
+		}
+		data, err := json.Marshal(tool)
+		if err != nil {
+			t.Fatalf("failed to marshal: %v", err)
+		}
+		var m map[string]any
+		if err := json.Unmarshal(data, &m); err != nil {
+			t.Fatalf("failed to unmarshal: %v", err)
+		}
+		if _, ok := m["overridesBuiltInTool"]; ok {
+			t.Errorf("expected overridesBuiltInTool to be omitted, got %v", m)
+		}
+	})
+}
+
 func TestClient_CreateSession_RequiresPermissionHandler(t *testing.T) {
 	t.Run("returns error when config is nil", func(t *testing.T) {
 		client := NewClient(nil)

go/internal/e2e/tools_test.go

@@ -271,13 +271,16 @@ func TestTools(t *testing.T) {
 			Query string `json:"query" jsonschema:"Search query"`
 		}
 
+		grepTool := 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
+				})
+		grepTool.OverridesBuiltInTool = true
+
 		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
-					}),
+				grepTool,
 			},
 		})
 		if err != nil {

go/types.go

@@ -410,10 +410,11 @@ type SessionConfig struct {
 
 // Tool describes a caller-implemented tool that can be invoked by Copilot
 type Tool struct {
-	Name        string         `json:"name"`
-	Description string         `json:"description,omitempty"`
-	Parameters  map[string]any `json:"parameters,omitempty"`
-	Handler     ToolHandler    `json:"-"`
+	Name                 string         `json:"name"`
+	Description          string         `json:"description,omitempty"`
+	Parameters           map[string]any `json:"parameters,omitempty"`
+	OverridesBuiltInTool bool           `json:"overridesBuiltInTool,omitempty"`
+	Handler              ToolHandler    `json:"-"`
 }
 
 // ToolInvocation describes a tool call initiated by Copilot