feat: add per-agent tool visibility via defaultAgent.excludedTools (#1098)

* feat: add per-agent tool visibility via defaultAgent.excludedTools

Add a new DefaultAgentConfig type and defaultAgent property to SessionConfig
across all four SDKs (Node.js, Python, Go, .NET). This allows tools
to be hidden from the default agent while remaining available to custom
sub-agents, enabling the orchestrator pattern where the default agent
delegates heavy-context work to specialized sub-agents.

The default agent is the built-in agent that handles turns when no
custom agent is selected. Tools listed in defaultAgent.excludedTools
are excluded from the default agent but remain available to sub-agents
that reference them in their tools array.

Changes:
- Node.js: DefaultAgentConfig interface, defaultAgent on SessionConfig/
  ResumeSessionConfig, RPC pass-through, 2 unit tests
- Python: DefaultAgentConfig TypedDict, default_agent parameter on
  create_session()/resume_session(), wire format conversion
- Go: DefaultAgentConfig struct, DefaultAgent on config and request structs
- .NET: DefaultAgentConfig class, DefaultAgent property on configs, copy
  constructors, and RPC request records
- Docs: Agent-Exclusive Tools section in custom-agents.md
- Test scenario: custom-agents scenario updated with defaultAgent usage

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

* fix: address CI validation failures

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

* fix: address PR review feedback

- Fix defineTool signature in TS scenario and docs (name, config)
- Remove unused System.Text.Json import from C# scenario

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

* fix: address remaining CI validation failures

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

---------

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

Author: MackinnonBuck

docs/features/custom-agents.md

@@ -759,6 +759,154 @@ const session = await client.createSession({
 
 > **Note:** When `tools` is `null` or omitted, the agent inherits access to all tools configured on the session. Use explicit tool lists to enforce the principle of least privilege.
 
+## Agent-Exclusive Tools
+
+Use the `defaultAgent` property on the session configuration to hide specific tools from the default agent (the built-in agent that handles turns when no custom agent is selected). This forces the main agent to delegate to sub-agents when those tools' capabilities are needed, keeping the main agent's context clean.
+
+This is useful when:
+- Certain tools generate large amounts of context that would overwhelm the main agent
+- You want the main agent to act as an orchestrator, delegating heavy work to specialized sub-agents
+- You need strict separation between orchestration and execution
+
+<details open>
+<summary><strong>Node.js / TypeScript</strong></summary>
+
+```typescript
+import { CopilotClient, defineTool, approveAll } from "@github/copilot-sdk";
+import { z } from "zod";
+
+const heavyContextTool = defineTool("analyze-codebase", {
+    description: "Performs deep analysis of the codebase, generating extensive context",
+    parameters: z.object({ query: z.string() }),
+    handler: async ({ query }) => {
+        // ... expensive analysis that returns lots of data
+        return { analysis: "..." };
+    },
+});
+
+const session = await client.createSession({
+    tools: [heavyContextTool],
+    defaultAgent: {
+        excludedTools: ["analyze-codebase"],
+    },
+    customAgents: [
+        {
+            name: "researcher",
+            description: "Deep codebase analysis agent with access to heavy-context tools",
+            tools: ["analyze-codebase"],
+            prompt: "You perform thorough codebase analysis using the analyze-codebase tool.",
+        },
+    ],
+});
+```
+
+</details>
+
+<details>
+<summary><strong>Python</strong></summary>
+
+```python
+from copilot import CopilotClient
+from copilot.tools import Tool
+
+heavy_tool = Tool(
+    name="analyze-codebase",
+    description="Performs deep analysis of the codebase",
+    handler=analyze_handler,
+    parameters={"type": "object", "properties": {"query": {"type": "string"}}},
+)
+
+session = await client.create_session(
+    tools=[heavy_tool],
+    default_agent={"excluded_tools": ["analyze-codebase"]},
+    custom_agents=[
+        {
+            "name": "researcher",
+            "description": "Deep codebase analysis agent",
+            "tools": ["analyze-codebase"],
+            "prompt": "You perform thorough codebase analysis.",
+        },
+    ],
+    on_permission_request=approve_all,
+)
+```
+
+</details>
+
+<details>
+<summary><strong>Go</strong></summary>
+
+<!-- docs-validate: skip -->
+```go
+session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+    Tools: []copilot.Tool{heavyTool},
+    DefaultAgent: &copilot.DefaultAgentConfig{
+        ExcludedTools: []string{"analyze-codebase"},
+    },
+    CustomAgents: []copilot.CustomAgentConfig{
+        {
+            Name:        "researcher",
+            Description: "Deep codebase analysis agent",
+            Tools:       []string{"analyze-codebase"},
+            Prompt:      "You perform thorough codebase analysis.",
+        },
+    },
+})
+```
+
+</details>
+
+<details>
+<summary><strong>C# / .NET</strong></summary>
+
+<!-- docs-validate: skip -->
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    Tools = [analyzeCodebaseTool],
+    DefaultAgent = new DefaultAgentConfig
+    {
+        ExcludedTools = ["analyze-codebase"],
+    },
+    CustomAgents =
+    [
+        new CustomAgentConfig
+        {
+            Name = "researcher",
+            Description = "Deep codebase analysis agent",
+            Tools = ["analyze-codebase"],
+            Prompt = "You perform thorough codebase analysis.",
+        },
+    ],
+});
+```
+
+</details>
+
+### How It Works
+
+Tools listed in `defaultAgent.excludedTools`:
+
+1. **Are registered** — their handlers are available for execution
+2. **Are hidden** from the main agent's tool list — the LLM won't see or call them directly
+3. **Remain available** to any custom sub-agent that includes them in its `tools` array
+
+### Interaction with Other Tool Filters
+
+`defaultAgent.excludedTools` is orthogonal to the session-level `availableTools` and `excludedTools`:
+
+| Filter | Scope | Effect |
+|--------|-------|--------|
+| `availableTools` | Session-wide | Allowlist — only these tools exist for anyone |
+| `excludedTools` | Session-wide | Blocklist — these tools are blocked for everyone |
+| `defaultAgent.excludedTools` | Main agent only | These tools are hidden from the main agent but available to sub-agents |
+
+Precedence:
+1. Session-level `availableTools`/`excludedTools` are applied first (globally)
+2. `defaultAgent.excludedTools` is applied on top, further restricting the main agent only
+
+> **Note:** If a tool is in both `excludedTools` (session-level) and `defaultAgent.excludedTools`, the session-level exclusion takes precedence — the tool is unavailable to everyone.
+
 ## Attaching MCP Servers to Agents
 
 Each custom agent can have its own MCP (Model Context Protocol) servers, giving it access to specialized data sources:

dotnet/src/Client.cs

@@ -501,6 +501,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 config.McpServers,
                 "direct",
                 config.CustomAgents,
+                config.DefaultAgent,
                 config.Agent,
                 config.ConfigDir,
                 config.EnableConfigDiscovery,
@@ -627,6 +628,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 config.McpServers,
                 "direct",
                 config.CustomAgents,
+                config.DefaultAgent,
                 config.Agent,
                 config.SkillDirectories,
                 config.DisabledSkills,
@@ -1642,6 +1644,7 @@ internal record CreateSessionRequest(
         IDictionary<string, McpServerConfig>? McpServers,
         string? EnvValueMode,
         IList<CustomAgentConfig>? CustomAgents,
+        DefaultAgentConfig? DefaultAgent,
         string? Agent,
         string? ConfigDir,
         bool? EnableConfigDiscovery,
@@ -1698,6 +1701,7 @@ internal record ResumeSessionRequest(
         IDictionary<string, McpServerConfig>? McpServers,
         string? EnvValueMode,
         IList<CustomAgentConfig>? CustomAgents,
+        DefaultAgentConfig? DefaultAgent,
         string? Agent,
         IList<string>? SkillDirectories,
         IList<string>? DisabledSkills,

dotnet/src/Types.cs

@@ -1656,6 +1656,21 @@ public class CustomAgentConfig
     public IList<string>? Skills { get; set; }
 }
 
+/// <summary>
+/// Configuration for the default agent (the built-in agent that handles turns when no custom agent is selected).
+/// Use <see cref="ExcludedTools"/> to hide specific tools from the default agent
+/// while keeping them available to custom sub-agents.
+/// </summary>
+public class DefaultAgentConfig
+{
+    /// <summary>
+    /// List of tool names to exclude from the default agent.
+    /// These tools remain available to custom sub-agents that reference them
+    /// in their <see cref="CustomAgentConfig.Tools"/> list.
+    /// </summary>
+    public IList<string>? ExcludedTools { get; set; }
+}
+
 /// <summary>
 /// Configuration for infinite sessions with automatic context compaction and workspace persistence.
 /// When enabled, sessions automatically manage context window limits through background compaction
@@ -1709,6 +1724,7 @@ protected SessionConfig(SessionConfig? other)
         Commands = other.Commands is not null ? [.. other.Commands] : null;
         ConfigDir = other.ConfigDir;
         CustomAgents = other.CustomAgents is not null ? [.. other.CustomAgents] : null;
+        DefaultAgent = other.DefaultAgent;
         Agent = other.Agent;
         DisabledSkills = other.DisabledSkills is not null ? [.. other.DisabledSkills] : null;
         EnableConfigDiscovery = other.EnableConfigDiscovery;
@@ -1871,6 +1887,13 @@ protected SessionConfig(SessionConfig? other)
     /// </summary>
     public IList<CustomAgentConfig>? CustomAgents { get; set; }
 
+    /// <summary>
+    /// Configuration for the default agent (the built-in agent that handles turns when no custom agent is selected).
+    /// Use <see cref="DefaultAgentConfig.ExcludedTools"/> to hide specific tools from the default agent
+    /// while keeping them available to custom sub-agents.
+    /// </summary>
+    public DefaultAgentConfig? DefaultAgent { get; set; }
+
     /// <summary>
     /// Name of the custom agent to activate when the session starts.
     /// Must match the <see cref="CustomAgentConfig.Name"/> of one of the agents in <see cref="CustomAgents"/>.
@@ -1950,6 +1973,7 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
         Commands = other.Commands is not null ? [.. other.Commands] : null;
         ConfigDir = other.ConfigDir;
         CustomAgents = other.CustomAgents is not null ? [.. other.CustomAgents] : null;
+        DefaultAgent = other.DefaultAgent;
         Agent = other.Agent;
         DisabledSkills = other.DisabledSkills is not null ? [.. other.DisabledSkills] : null;
         DisableResume = other.DisableResume;
@@ -2117,6 +2141,13 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
     /// </summary>
     public IList<CustomAgentConfig>? CustomAgents { get; set; }
 
+    /// <summary>
+    /// Configuration for the default agent (the built-in agent that handles turns when no custom agent is selected).
+    /// Use <see cref="DefaultAgentConfig.ExcludedTools"/> to hide specific tools from the default agent
+    /// while keeping them available to custom sub-agents.
+    /// </summary>
+    public DefaultAgentConfig? DefaultAgent { get; set; }
+
     /// <summary>
     /// Name of the custom agent to activate when the session starts.
     /// Must match the <see cref="CustomAgentConfig.Name"/> of one of the agents in <see cref="CustomAgents"/>.

dotnet/test/CloneTests.cs

@@ -90,6 +90,7 @@ public void SessionConfig_Clone_CopiesAllProperties()
             McpServers = new Dictionary<string, McpServerConfig> { ["server1"] = new McpStdioServerConfig { Command = "echo" } },
             CustomAgents = [new CustomAgentConfig { Name = "agent1" }],
             Agent = "agent1",
+            DefaultAgent = new DefaultAgentConfig { ExcludedTools = ["hidden-tool"] },
             SkillDirectories = ["/skills"],
             DisabledSkills = ["skill1"],
         };
@@ -109,6 +110,7 @@ public void SessionConfig_Clone_CopiesAllProperties()
         Assert.Equal(original.McpServers.Count, clone.McpServers!.Count);
         Assert.Equal(original.CustomAgents.Count, clone.CustomAgents!.Count);
         Assert.Equal(original.Agent, clone.Agent);
+        Assert.Equal(original.DefaultAgent!.ExcludedTools, clone.DefaultAgent!.ExcludedTools);
         Assert.Equal(original.SkillDirectories, clone.SkillDirectories);
         Assert.Equal(original.DisabledSkills, clone.DisabledSkills);
     }
@@ -245,6 +247,7 @@ public void Clone_WithNullCollections_ReturnsNullCollections()
         Assert.Null(clone.SkillDirectories);
         Assert.Null(clone.DisabledSkills);
         Assert.Null(clone.Tools);
+        Assert.Null(clone.DefaultAgent);
         Assert.True(clone.IncludeSubAgentStreamingEvents);
     }
 

dotnet/test/SessionTests.cs

@@ -162,6 +162,35 @@ public async Task Should_Create_A_Session_With_ExcludedTools()
         Assert.Contains("grep", toolNames);
     }
 
+    [Fact]
+    public async Task Should_Create_A_Session_With_DefaultAgent_ExcludedTools()
+    {
+        var session = await CreateSessionAsync(new SessionConfig
+        {
+            Tools =
+            [
+                AIFunctionFactory.Create(
+                    (string input) => "SECRET",
+                    "secret_tool",
+                    "A secret tool hidden from the default agent"),
+            ],
+            DefaultAgent = new DefaultAgentConfig
+            {
+                ExcludedTools = ["secret_tool"],
+            },
+        });
+
+        await session.SendAsync(new MessageOptions { Prompt = "What is 1+1?" });
+        await TestHelper.GetFinalAssistantMessageAsync(session);
+
+        // The real assertion: verify the runtime excluded the tool from the CAPI request
+        var traffic = await Ctx.GetExchangesAsync();
+        Assert.NotEmpty(traffic);
+
+        var toolNames = GetToolNames(traffic[0]);
+        Assert.DoesNotContain("secret_tool", toolNames);
+    }
+
     [Fact]
     public async Task Should_Create_Session_With_Custom_Tool()
     {

go/client.go

@@ -592,6 +592,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	req.MCPServers = config.MCPServers
 	req.EnvValueMode = "direct"
 	req.CustomAgents = config.CustomAgents
+	req.DefaultAgent = config.DefaultAgent
 	req.Agent = config.Agent
 	req.SkillDirectories = config.SkillDirectories
 	req.DisabledSkills = config.DisabledSkills
@@ -776,6 +777,7 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	req.MCPServers = config.MCPServers
 	req.EnvValueMode = "direct"
 	req.CustomAgents = config.CustomAgents
+	req.DefaultAgent = config.DefaultAgent
 	req.Agent = config.Agent
 	req.SkillDirectories = config.SkillDirectories
 	req.DisabledSkills = config.DisabledSkills

go/internal/e2e/session_test.go

@@ -313,6 +313,57 @@ func TestSession(t *testing.T) {
 		}
 	})
 
+	t.Run("should create a session with defaultAgent excludedTools", func(t *testing.T) {
+		ctx.ConfigureForTest(t)
+
+		session, err := client.CreateSession(t.Context(), &copilot.SessionConfig{
+			OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+			Tools: []copilot.Tool{
+				{
+					Name:        "secret_tool",
+					Description: "A secret tool hidden from the default agent",
+					Parameters: map[string]any{
+						"type":       "object",
+						"properties": map[string]any{"input": map[string]any{"type": "string"}},
+					},
+					Handler: func(invocation copilot.ToolInvocation) (copilot.ToolResult, error) {
+						return copilot.ToolResult{TextResultForLLM: "SECRET", ResultType: "success"}, nil
+					},
+				},
+			},
+			DefaultAgent: &copilot.DefaultAgentConfig{
+				ExcludedTools: []string{"secret_tool"},
+			},
+		})
+		if err != nil {
+			t.Fatalf("Failed to create session: %v", err)
+		}
+
+		_, err = session.Send(t.Context(), copilot.MessageOptions{Prompt: "What is 1+1?"})
+		if err != nil {
+			t.Fatalf("Failed to send message: %v", err)
+		}
+
+		_, err = testharness.GetFinalAssistantMessage(t.Context(), session)
+		if err != nil {
+			t.Fatalf("Failed to get assistant message: %v", err)
+		}
+
+		// The real assertion: verify the runtime excluded the tool from the CAPI request
+		traffic, err := ctx.GetExchanges()
+		if err != nil {
+			t.Fatalf("Failed to get exchanges: %v", err)
+		}
+		if len(traffic) == 0 {
+			t.Fatal("Expected at least one exchange")
+		}
+
+		toolNames := getToolNames(traffic[0])
+		if contains(toolNames, "secret_tool") {
+			t.Errorf("Expected 'secret_tool' to be excluded from default agent, got %v", toolNames)
+		}
+	})
+
 	t.Run("should create session with custom tool", func(t *testing.T) {
 		ctx.ConfigureForTest(t)