CustomAgentsLocalOnly - Incorrect Behaviour

[shudles]

The SessionConfig.CustomAgentsLocalOnly property's summary tag reads:

    /// <summary>
    /// When <see langword="true"/>, custom-agent discovery is restricted to the
    /// session's local working directory (no organisation-level discovery).
    /// When <see langword="null"/>, the SDK chooses based on
    /// <see cref="CopilotClientOptions.Mode"/>: <c>true</c> under
    /// <see cref="CopilotClientMode.Empty"/>, <c>null</c> otherwise.
    /// </summary>
    public bool? CustomAgentsLocalOnly { get; set; }

Using this simple example, you can discover it's not this the case. All agents at all organisation levels will be loaded. Which is counter to:
"Custom instruction files (.github/copilot-instructions.md, AGENTS.md, etc. are always loaded from the working directory regardless of this setting"

using GitHub.Copilot;

// path to a sub .github folder containing an agents folder like "myworkspace\subfolder\.github\agents"
// and a higher organisation .github folder also with an agents folder like in the example below:
//
//     myworkspace\.github\agents
//     myworkspace\subfolder\.github\agents
const string WorkingDirectory = @"C:\some-subfolder\";

await using var client = new CopilotClient();

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    WorkingDirectory = WorkingDirectory,
    EnableConfigDiscovery = true, // Note that this has to be true to get any agents to load from disk - (see https://github.com/github/copilot-sdk/issues/1887)
    CustomAgentsLocalOnly = true, // This should prevent loading agents at the higher organisation level, but it does not.
});

var agentsList = await session.Rpc.Agent.ListAsync();

foreach (var agent in agentsList.Agents)
{
    // You'll see both agents picked up, no matter the value of CustomAgentsLocalOnly
    Console.WriteLine(agent.Name);
}

First agent file I was using in a .github/agents/sample.agent.md file:

---
name: sample
description: Sample Agent
---

You are an sample agent for this repository, you're just happy to be here!

And second agent in a `subfolder/.github/agents/example.agent.md file:

---
name: example
description: Example Agent
---

You are an example agent for this repository, you're not happy to be here!

The property looks to disable the "walking upwards" agent loading behaviour as defined in https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agent-locations (I can't seem to find this documented for the SDK, but happy to be pointed towards it)

[github-actions]

Investigation findings: confirmed bug

Thanks for the detailed report. I investigated the root cause and can confirm this is a genuine bug in the .NET SDK.

What I found

CustomAgentsLocalOnly is never sent in the session.create request from the .NET SDK.

Looking at dotnet/src/Client.cs, the CreateSessionRequest record (and ResumeSessionRequest) does not include a CustomAgentsLocalOnly parameter. Instead, the property is only forwarded via a post-creation session.options.update call inside UpdateSessionOptionsForModeAsync.

By contrast, the Go SDK (go/client.go line 708 / go/types.go line 2077) correctly sends customAgentsLocalOnly as part of the session.create request body, in addition to the post-creation update.

Why this matters

Agent discovery happens during session initialization — when session.create is processed by the CLI. Because the .NET SDK doesn't include customAgentsLocalOnly in that request, the CLI initializes the session without the restriction and walks up to parent .github/agents/ directories as normal. The subsequent session.options.update (which does set customAgentsLocalOnly = true) arrives too late to affect the already-completed discovery, so Agent.ListAsync() returns agents from all levels regardless of the setting.

Affected requests

Both CreateSessionRequest and ResumeSessionRequest in dotnet/src/Client.cs are missing the customAgentsLocalOnly field.

Fix

Add bool? CustomAgentsLocalOnly to both CreateSessionRequest and ResumeSessionRequest, and populate it from config.CustomAgentsLocalOnly at the call sites — mirroring what the Go SDK already does.

Generated by Bug Handler for issue #1888 · sonnet46 1.9M · ◷