GitHub Copilot SDK C# Instructions

Core Principles

- The SDK is in technical preview and may have breaking changes

- Requires .NET 10.0 or later

- Requires GitHub Copilot CLI installed and in PATH

- Uses async/await patterns throughout

- Implements IAsyncDisposable for resource cleanup

Installation

Always install via NuGet:

dotnet add package GitHub.Copilot.SDK

Client Initialization

Basic Client Setup

await using var client = new CopilotClient();
await client.StartAsync();

Client Configuration Options

When creating a CopilotClient, use `CopilotClientOptions`:

- `CliPath` - Path to CLI executable (default: "copilot" from PATH)

- `CliArgs` - Extra arguments prepended before SDK-managed flags

- `CliUrl` - URL of existing CLI server (e.g., "localhost:8080"). When provided, client won't spawn a process

- `Port` - Server port (default: 0 for random)

- `UseStdio` - Use stdio transport instead of TCP (default: true)

- `LogLevel` - Log level (default: "info")

- `AutoStart` - Auto-start server (default: true)

- `AutoRestart` - Auto-restart on crash (default: true)

- `Cwd` - Working directory for the CLI process

- `Environment` - Environment variables for the CLI process

- `Logger` - ILogger instance for SDK logging

Manual Server Control

For explicit control:

var client = new CopilotClient(new CopilotClientOptions { AutoStart = false });
await client.StartAsync();
// Use client...
await client.StopAsync();

Use `ForceStopAsync()` when `StopAsync()` takes too long.

Session Management

Creating Sessions

Use `SessionConfig` for configuration:

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    OnPermissionRequest = PermissionHandler.ApproveAll,
    Model = "gpt-5",
    Streaming = true,
    Tools = [...],
    SystemMessage = new SystemMessageConfig { ... },
    AvailableTools = ["tool1", "tool2"],
    ExcludedTools = ["tool3"],
    Provider = new ProviderConfig { ... }
});

Session Config Options

- `SessionId` - Custom session ID

- `Model` - Model name ("gpt-5", "claude-sonnet-4.5", etc.)

- `Tools` - Custom tools exposed to the CLI

- `SystemMessage` - System message customization

- `AvailableTools` - Allowlist of tool names

- `ExcludedTools` - Blocklist of tool names

- `Provider` - Custom API provider configuration (BYOK)

- `Streaming` - Enable streaming response chunks (default: false)

Resuming Sessions

var session = await client.ResumeSessionAsync(sessionId, new ResumeSessionConfig
{
    OnPermissionRequest = PermissionHandler.ApproveAll,
    // ...
});

Session Operations

- `session.SessionId` - Get session identifier

- `session.SendAsync(new MessageOptions { Prompt = "...", Attachments = [...] })` - Send message

- `session.AbortAsync()` - Abort current processing

- `session.GetMessagesAsync()` - Get all events/messages

- `await session.DisposeAsync()` - Clean up resources

Event Handling

Event Subscription Pattern

ALWAYS use TaskCompletionSource for waiting on session events:

var done = new TaskCompletionSource();

session.On(evt =>
{
    if (evt is AssistantMessageEvent msg)
    {
        Console.WriteLine(msg.Data.Content);
    }
    else if (evt is SessionIdleEvent)
    {
        done.SetResult();
    }
});

await session.SendAsync(new MessageOptions { Prompt = "..." });
await done.Task;

Unsubscribing from Events

The `On()` method returns an IDisposable:

var subscription = session.On(evt => { /* handler */ });
// Later...
subscription.Dispose();

Event Types

Use pattern matching or switch expressions for event handling:

session.On(evt =>
{
    switch (evt)
    {
        case UserMessageEvent userMsg:
            // Handle user message
            break;
        case AssistantMessageEvent assistantMsg:
            Console.WriteLine(assistantMsg.Data.Content);
            break;
        case ToolExecutionStartEvent toolStart:
            // Tool execution s