Add customAgentDirectories session config option

Add a `customAgentDirectories` option to the session config across all six
SDK languages, mirroring the existing `instructionDirectories` /
`skillDirectories` passthrough options. It accepts a list of directory paths
that the CLI searches for custom agent definition files, forwarded on both
session create and resume.

- nodejs: SessionConfigBase.customAgentDirectories + create/resume forwarding
- go: SessionConfig/ResumeSessionConfig + request structs + forwarding
- python: create_session/resume_session custom_agent_directories param
- dotnet: SessionConfig.CustomAgentDirectories + Clone + create/resume/update
- java: SessionConfig/ResumeSessionConfig + request builders
- rust: SessionConfig::with_custom_agent_directories + create/resume wire

Unit tests verify the option is forwarded on the session.create and
session.resume JSON-RPC requests in every language. End-to-end tests (with
handcrafted replay-proxy snapshots) additionally assert that a custom agent
placed in a `customAgentDirectories` path is discovered by the CLI and
surfaced in the task tool's `agent_type` enum, on both create and resume.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d4c94c34-dda4-49a1-b876-687fc771d0e0

Author: timrogers

dotnet/src/Client.cs

@@ -1225,6 +1225,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 RemoteSession: config.RemoteSession,
                 Cloud: config.Cloud,
                 InstructionDirectories: config.InstructionDirectories,
+                CustomAgentDirectories: config.CustomAgentDirectories,
                 PluginDirectories: config.PluginDirectories,
                 DisabledMcpServers: config.DisabledMcpServers,
                 LargeOutput: config.LargeOutput,
@@ -1446,6 +1447,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 RemoteSession: config.RemoteSession,
                 ContinuePendingWork: config.ContinuePendingWork,
                 InstructionDirectories: config.InstructionDirectories,
+                CustomAgentDirectories: config.CustomAgentDirectories,
                 PluginDirectories: config.PluginDirectories,
                 DisabledMcpServers: config.DisabledMcpServers,
                 LargeOutput: config.LargeOutput,
@@ -2805,6 +2807,7 @@ internal record CreateSessionRequest(
         RemoteSessionMode? RemoteSession = null,
         CloudSessionOptions? Cloud = null,
         IList<string>? InstructionDirectories = null,
+        IList<string>? CustomAgentDirectories = null,
         IList<string>? PluginDirectories = null,
         [property: JsonPropertyName("disabledMcpServers")] IList<string>? DisabledMcpServers = null,
         LargeToolOutputConfig? LargeOutput = null,
@@ -2920,6 +2923,7 @@ internal record ResumeSessionRequest(
         RemoteSessionMode? RemoteSession = null,
         bool? ContinuePendingWork = null,
         IList<string>? InstructionDirectories = null,
+        IList<string>? CustomAgentDirectories = null,
         IList<string>? PluginDirectories = null,
         [property: JsonPropertyName("disabledMcpServers")] IList<string>? DisabledMcpServers = null,
         LargeToolOutputConfig? LargeOutput = null,

dotnet/src/Types.cs

@@ -3222,6 +3222,7 @@ protected SessionConfigBase(SessionConfigBase? other)
         SkillDirectories = other.SkillDirectories is not null ? [.. other.SkillDirectories] : null;
         PluginDirectories = other.PluginDirectories is not null ? [.. other.PluginDirectories] : null;
         InstructionDirectories = other.InstructionDirectories is not null ? [.. other.InstructionDirectories] : null;
+        CustomAgentDirectories = other.CustomAgentDirectories is not null ? [.. other.CustomAgentDirectories] : null;
         SessionLimits = other.SessionLimits;
         Streaming = other.Streaming;
         IncludeSubAgentStreamingEvents = other.IncludeSubAgentStreamingEvents;
@@ -3583,6 +3584,9 @@ protected SessionConfigBase(SessionConfigBase? other)
     /// <summary>Additional directories to search for custom instruction files.</summary>
     public IList<string>? InstructionDirectories { get; set; }
 
+    /// <summary>Additional directories to search for custom agent files.</summary>
+    public IList<string>? CustomAgentDirectories { get; set; }
+
     /// <summary>List of skill names to disable.</summary>
     public IList<string>? DisabledSkills { get; set; }
 

dotnet/test/E2E/SessionConfigE2ETests.cs

@@ -446,6 +446,64 @@ await File.WriteAllTextAsync(
         await session2.DisposeAsync();
     }
 
+    [Fact]
+    public async Task Should_Apply_CustomAgentDirectories_On_Create()
+    {
+        var projectDir = Path.Join(Ctx.WorkDir, "agent-create-project");
+        var agentDir = Path.Join(Ctx.WorkDir, "extra-create-agents");
+        Directory.CreateDirectory(projectDir);
+        Directory.CreateDirectory(agentDir);
+        await File.WriteAllTextAsync(
+            Path.Join(agentDir, "reviewer.agent.md"),
+            "---\nname: reviewer\ndescription: Reviews code carefully.\n---\nYou review code carefully.");
+
+        var session = await CreateSessionAsync(new SessionConfig
+        {
+            WorkingDirectory = projectDir,
+            CustomAgentDirectories = [agentDir],
+        });
+
+        await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });
+
+        var exchanges = await Ctx.GetExchangesAsync();
+        Assert.NotEmpty(exchanges);
+        Assert.Contains("reviewer", GetTaskAgentTypes(exchanges[^1]));
+
+        await session.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Should_Apply_CustomAgentDirectories_On_Resume()
+    {
+        var projectDir = Path.Join(Ctx.WorkDir, "agent-resume-project");
+        var agentDir = Path.Join(Ctx.WorkDir, "extra-resume-agents");
+        Directory.CreateDirectory(projectDir);
+        Directory.CreateDirectory(agentDir);
+        await File.WriteAllTextAsync(
+            Path.Join(agentDir, "reviewer.agent.md"),
+            "---\nname: reviewer\ndescription: Reviews code carefully.\n---\nYou review code carefully.");
+
+        await using var session1 = await CreateSessionAsync(new SessionConfig
+        {
+            WorkingDirectory = projectDir,
+        });
+        var sessionId = session1.SessionId;
+        await SuspendAndUntrackSessionForResumeAsync(session1);
+        var session2 = await ResumeSessionAsync(sessionId, new ResumeSessionConfig
+        {
+            WorkingDirectory = projectDir,
+            CustomAgentDirectories = [agentDir],
+        });
+
+        await session2.SendAndWaitAsync(new MessageOptions { Prompt = "What is 1+1?" });
+
+        var exchanges = await Ctx.GetExchangesAsync();
+        Assert.NotEmpty(exchanges);
+        Assert.Contains("reviewer", GetTaskAgentTypes(exchanges[^1]));
+
+        await session2.DisposeAsync();
+    }
+
     [Fact]
     public async Task Should_Apply_AvailableTools_On_Session_Resume()
     {

dotnet/test/Unit/CloneTests.cs

@@ -103,6 +103,7 @@ public void SessionConfig_Clone_CopiesAllProperties()
             DefaultAgent = new DefaultAgentConfig { ExcludedTools = ["hidden-tool"] },
             SkillDirectories = ["/skills"],
             InstructionDirectories = ["/instructions"],
+            CustomAgentDirectories = ["/agents"],
             DisabledSkills = ["skill1"],
             DisabledMcpServers = ["server1"],
             PluginDirectories = ["/plugins"],
@@ -145,6 +146,7 @@ public void SessionConfig_Clone_CopiesAllProperties()
         Assert.Equal(original.DefaultAgent!.ExcludedTools, clone.DefaultAgent!.ExcludedTools);
         Assert.Equal(original.SkillDirectories, clone.SkillDirectories);
         Assert.Equal(original.InstructionDirectories, clone.InstructionDirectories);
+        Assert.Equal(original.CustomAgentDirectories, clone.CustomAgentDirectories);
         Assert.Equal(original.DisabledSkills, clone.DisabledSkills);
         Assert.Equal(original.DisabledMcpServers, clone.DisabledMcpServers);
         Assert.Equal(original.PluginDirectories, clone.PluginDirectories);
@@ -168,6 +170,7 @@ public void SessionConfig_Clone_CollectionsAreIndependent()
             AdditionalDirectories = ["/shared"],
             SkillDirectories = ["/skills"],
             InstructionDirectories = ["/instructions"],
+            CustomAgentDirectories = ["/agents"],
             DisabledSkills = ["skill1"],
             DisabledMcpServers = ["server1"],
         };
@@ -183,6 +186,7 @@ public void SessionConfig_Clone_CollectionsAreIndependent()
         clone.AdditionalDirectories!.Add("/generated");
         clone.SkillDirectories!.Add("/more");
         clone.InstructionDirectories!.Add("/more-instructions");
+        clone.CustomAgentDirectories!.Add("/more-agents");
         clone.DisabledSkills!.Add("skill99");
         clone.DisabledMcpServers!.Add("server99");
 
@@ -195,6 +199,7 @@ public void SessionConfig_Clone_CollectionsAreIndependent()
         Assert.Single(original.AdditionalDirectories!);
         Assert.Single(original.SkillDirectories!);
         Assert.Single(original.InstructionDirectories!);
+        Assert.Single(original.CustomAgentDirectories!);
         Assert.Single(original.DisabledSkills!);
         Assert.Single(original.DisabledMcpServers!);
     }
@@ -223,6 +228,7 @@ public void ResumeSessionConfig_Clone_CollectionsAreIndependent()
             AdditionalDirectories = ["/shared"],
             SkillDirectories = ["/skills"],
             InstructionDirectories = ["/instructions"],
+            CustomAgentDirectories = ["/agents"],
             DisabledSkills = ["skill1"],
             DisabledMcpServers = ["server1"],
         };
@@ -238,6 +244,7 @@ public void ResumeSessionConfig_Clone_CollectionsAreIndependent()
         clone.AdditionalDirectories!.Add("/generated");
         clone.SkillDirectories!.Add("/more");
         clone.InstructionDirectories!.Add("/more-instructions");
+        clone.CustomAgentDirectories!.Add("/more-agents");
         clone.DisabledSkills!.Add("skill99");
         clone.DisabledMcpServers!.Add("server99");
 
@@ -250,6 +257,7 @@ public void ResumeSessionConfig_Clone_CollectionsAreIndependent()
         Assert.Single(original.AdditionalDirectories!);
         Assert.Single(original.SkillDirectories!);
         Assert.Single(original.InstructionDirectories!);
+        Assert.Single(original.CustomAgentDirectories!);
         Assert.Single(original.DisabledSkills!);
         Assert.Single(original.DisabledMcpServers!);
     }
@@ -311,6 +319,7 @@ public void Clone_WithNullCollections_ReturnsNullCollections()
         Assert.Null(clone.CustomAgents);
         Assert.Null(clone.SkillDirectories);
         Assert.Null(clone.InstructionDirectories);
+        Assert.Null(clone.CustomAgentDirectories);
         Assert.Null(clone.DisabledSkills);
         Assert.Null(clone.DisabledMcpServers);
         Assert.Null(clone.Tools);

dotnet/test/Unit/SerializationTests.cs

@@ -248,6 +248,39 @@ public void ResumeSessionRequest_CanSerializeInstructionDirectories_WithSdkOptio
         Assert.Equal("C:\\resume-instructions", root.GetProperty("instructionDirectories")[0].GetString());
     }
 
+    [Fact]
+    public void CreateSessionRequest_CanSerializeCustomAgentDirectories_WithSdkOptions()
+    {
+        var options = GetSerializerOptions();
+        var requestType = GetNestedType(typeof(CopilotClient), "CreateSessionRequest");
+        var request = CreateInternalRequest(
+            requestType,
+            ("SessionId", "session-id"),
+            ("CustomAgentDirectories", new List<string> { "C:\\extra-agents", "C:\\more-agents" }));
+
+        var json = JsonSerializer.Serialize(request, requestType, options);
+        using var document = JsonDocument.Parse(json);
+        var root = document.RootElement;
+        Assert.Equal("C:\\extra-agents", root.GetProperty("customAgentDirectories")[0].GetString());
+        Assert.Equal("C:\\more-agents", root.GetProperty("customAgentDirectories")[1].GetString());
+    }
+
+    [Fact]
+    public void ResumeSessionRequest_CanSerializeCustomAgentDirectories_WithSdkOptions()
+    {
+        var options = GetSerializerOptions();
+        var requestType = GetNestedType(typeof(CopilotClient), "ResumeSessionRequest");
+        var request = CreateInternalRequest(
+            requestType,
+            ("SessionId", "session-id"),
+            ("CustomAgentDirectories", new List<string> { "C:\\resume-agents" }));
+
+        var json = JsonSerializer.Serialize(request, requestType, options);
+        using var document = JsonDocument.Parse(json);
+        var root = document.RootElement;
+        Assert.Equal("C:\\resume-agents", root.GetProperty("customAgentDirectories")[0].GetString());
+    }
+
     [Fact]
     public void SessionRequests_CanSerializeCapiOptions_WithSdkOptions()
     {

go/client.go

@@ -840,6 +840,7 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	req.SkillDirectories = config.SkillDirectories
 	req.PluginDirectories = config.PluginDirectories
 	req.InstructionDirectories = config.InstructionDirectories
+	req.CustomAgentDirectories = config.CustomAgentDirectories
 	req.DisabledSkills = config.DisabledSkills
 	if config.DisabledMCPServers != nil {
 		req.DisabledMCPServers = &config.DisabledMCPServers
@@ -1224,6 +1225,7 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	req.SkillDirectories = config.SkillDirectories
 	req.PluginDirectories = config.PluginDirectories
 	req.InstructionDirectories = config.InstructionDirectories
+	req.CustomAgentDirectories = config.CustomAgentDirectories
 	req.DisabledSkills = config.DisabledSkills
 	if config.DisabledMCPServers != nil {
 		req.DisabledMCPServers = &config.DisabledMCPServers

go/client_test.go

@@ -1584,6 +1584,65 @@ func TestResumeSessionRequest_InstructionDirectories(t *testing.T) {
 	})
 }
 
+func TestCreateSessionRequest_CustomAgentDirectories(t *testing.T) {
+	t.Run("includes customAgentDirectories in JSON when set", func(t *testing.T) {
+		req := createSessionRequest{CustomAgentDirectories: []string{`C:\extra-agents`, `C:\more-agents`}}
+		data, err := json.Marshal(req)
+		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)
+		}
+		got := m["customAgentDirectories"].([]any)
+		if len(got) != 2 || got[0] != `C:\extra-agents` || got[1] != `C:\more-agents` {
+			t.Errorf("Expected customAgentDirectories to be serialized, got %v", got)
+		}
+	})
+
+	t.Run("omits customAgentDirectories from JSON when empty", func(t *testing.T) {
+		req := createSessionRequest{}
+		data, _ := json.Marshal(req)
+		var m map[string]any
+		json.Unmarshal(data, &m)
+		if _, ok := m["customAgentDirectories"]; ok {
+			t.Error("Expected customAgentDirectories to be omitted when empty")
+		}
+	})
+}
+
+func TestResumeSessionRequest_CustomAgentDirectories(t *testing.T) {
+	t.Run("includes customAgentDirectories in JSON when set", func(t *testing.T) {
+		req := resumeSessionRequest{
+			SessionID:              "s1",
+			CustomAgentDirectories: []string{`C:\resume-agents`},
+		}
+		data, err := json.Marshal(req)
+		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)
+		}
+		got := m["customAgentDirectories"].([]any)
+		if len(got) != 1 || got[0] != `C:\resume-agents` {
+			t.Errorf("Expected customAgentDirectories to be serialized, got %v", got)
+		}
+	})
+
+	t.Run("omits customAgentDirectories from JSON when empty", func(t *testing.T) {
+		req := resumeSessionRequest{SessionID: "s1"}
+		data, _ := json.Marshal(req)
+		var m map[string]any
+		json.Unmarshal(data, &m)
+		if _, ok := m["customAgentDirectories"]; ok {
+			t.Error("Expected customAgentDirectories to be omitted when empty")
+		}
+	})
+}
+
 func TestCreateSessionRequest_MCPOAuthTokenStorage(t *testing.T) {
 	t.Run("includes mcpOAuthTokenStorage in JSON when set", func(t *testing.T) {
 		req := createSessionRequest{MCPOAuthTokenStorage: "in-memory"}