NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #3220 most downloaded on PyPI
Python SDK for GitHub Copilot CLI
Latest stable
1.0.31
Last release 7 days ago
10 Nov 2026
Ships on a steady schedule
a new release about every 8 days
Nearly every release is documented
notes for 49 of 53 stable releases
1 version withdrawn
withdrawn after publishing
10 months old
184 releases · first in 2026
Drag across the ruler to compare, or tap a release to open it.
The Copilot runtime supports rewinding conversation history and tracked file changes. SDKs can now opt into file-change tracking via a new enableFileC
The Copilot runtime supports rewinding conversation history and tracked file changes. SDKs can now opt into file-change tracking via a new enableFileChangeTracking session option, and then use rewind to restore the session to an earlier checkpoint. (#2321)
// TypeScript
const session = await client.startSession({ enableFileChangeTracking: true });
const rewindPoints = await session.rpc.session.listRewindPoints();
await session.rpc.session.rewind({ rewindPointId: rewindPoints[0].id });
// C#
var session = await client.StartSessionAsync(new SessionOptions { EnableFileChangeTracking = true });
var points = await session.Rpc.Session.ListRewindPointsAsync();
await session.Rpc.Session.RewindAsync(new RewindParams { RewindPointId = points[0].Id });
# Python
session = await client.start_session(enable_file_change_tracking=True)
points = await session.rpc.session.list_rewind_points()
await session.rpc.session.rewind(rewind_point_id=points[0].id)
// Go
session, _ := client.StartSession(ctx, &sdk.SessionOptions{EnableFileChangeTracking: true})
points, _ := session.RPC.Session.ListRewindPoints(ctx)
session.RPC.Session.Rewind(ctx, &sdk.RewindParams{RewindPointId: points[0].Id})
// Java
SessionOptions options = new SessionOptions().setEnableFileChangeTracking(true);
CopilotSession session = client.startSession(options).get();
List<RewindPoint> points = session.getRpc().getSession().listRewindPoints().get();
session.getRpc().getSession().rewind(new RewindParams().setRewindPointId(points.get(0).getId())).get();
// Rust
let session = client.start_session(SessionOptions { enable_file_change_tracking: Some(true), ..Default::default() }).await?;
let points = session.rpc().session().list_rewind_points().await?;
session.rpc().session().rewind(&RewindParams { rewind_point_id: points[0].id.clone() }).await?;
The Java SDK now supports loading the Copilot runtime as a native library (via JNA) directly in-process on Linux x64, eliminating the need for a separate CLI child process. This mirrors the in-process mode already available in .NET and Rust. The feature is marked @CopilotExperimental. (#2301)
To use it, add the native runtime classifier JAR to your Maven dependencies and configure the connection:
<dependency>
<groupId>com.github</groupId>
<artifactId>copilot-sdk-java-runtime</artifactId>
<version>${copilot.version}</version>
<classifier>linux-x64</classifier>
</dependency>
CopilotClientOptions options = new CopilotClientOptions()
.setConnection(RuntimeConnection.forInProcess());
CopilotClient client = new CopilotClient(options);
client.start().get();
JsonValue, ctx.agent() forwards reasoningEffort and contextTier, and a factory body can no longer start a second top-level run (#2309)Generated by Release Changelog Generator · sonnet46 28.7 AIC · ⌖ 7.73 AIC · ⊞ 8.1K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.73, model: claude-sonnet-4.6, id: 31653908535, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/31653908535 -->
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Nothing published for this version
Nothing published for this version
Two new capabilities are available in every SDK language:
history.clearContext and Tool.isTerminal across all SDKsTwo new capabilities are available in every SDK language:
history.clearContext clears the conversation context (keeping system and developer messages) and seeds the fresh context window with a required first user message. It can only be called from inside a tool handler with a tool call in flight. Also picks up the new session.context_cleared event. (#2129)
Tool.isTerminal lets a tool declare that a successful call ends the agent turn instead of feeding the result back to the model for another round. A failed call leaves the loop running so the model can read the error and retry. (#2129)
const session = await joinSession({
tools: [{
name: "clear_context",
isTerminal: true,
defer: "never",
parameters: {
type: "object",
properties: { prompt: { type: "string" } },
required: ["prompt"],
},
handler: async ({ prompt }) => {
const { messagesCleared } = await session.rpc.history.clearContext({ prompt });
return { textResultForLlm: `Cleared ${messagesCleared} message(s).`, resultType: "success" };
},
}],
});
session.DefineTool("clear_context", new ToolOptions { IsTerminal = true, Defer = DeferMode.Never }, async (params) => {
var result = await session.Rpc.History.ClearContext(new ClearContextParams { Prompt = params.Prompt });
return ToolResult.Success($"Cleared {result.MessagesCleared} message(s).");
});
Hosts can now inject enterprise permission policy at session startup across all six SDKs. This is independent of the runtime's server-managed settings fetch path. (#2139)
const session = await createSession({
managedSettings: {
permissions: {
disableBypassPermissionsMode: "disable",
deny: ["shell"],
allow: ["read_file"],
},
},
});
var session = await CopilotClient.CreateSessionAsync(new SessionOptions {
ManagedSettings = new ManagedSettings {
Permissions = new ManagedPermissions {
DisableBypassPermissionsMode = "disable",
Deny = ["shell"],
Allow = ["read_file"],
}
}
});
serverName, toolName, args) in PermissionRequest.extensionData (#2276)@Chuxel made their first contribution in #2283Generated by Release Changelog Generator · sonnet46 19 AIC · ⌖ 5.28 AIC · ⊞ 8.6K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.73, model: claude-sonnet-4.6, id: 31186148234, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/31186148234 -->
java: enforce non-blank @CopilotToolParam description at compile time by @rinceyuan in https://github.com/github/copilot-sdk/pull/1980
session.idle.backgroundTasks field with the current aborted field by @examon in https://github.com/github/copilot-sdk/pull/2232Full Changelog: https://github.com/github/copilot-sdk/compare/v1.0.8...v1.0.9
All SDKs now accept a githubMcpToolConfig option on session create/resume, exposing settings the runtime already supports. The most useful new control
All SDKs now accept a githubMcpToolConfig option on session create/resume, exposing settings the runtime already supports. The most useful new control is disableFormDeferral, which makes MCP write tools (like creating issues or PRs) execute directly instead of opening an interactive form — essential for autonomous workflows. (#2112)
const session = await client.createSession({
githubMcpToolConfig: { disableFormDeferral: true }
});
var session = await client.CreateSessionAsync(new SessionConfig {
GitHubMcpToolConfig = new GitHubMcpToolConfig { DisableFormDeferral = true }
});
A new enableExperimentalMode option lets SDK consumers control whether a session activates experimental runtime features. In empty mode the SDK defaults to false; in copilot-cli mode the runtime decides unless you set it explicitly. (#1600)
const session = await client.createSession({ enableExperimentalMode: true });
var session = await client.CreateSessionAsync(new SessionConfig { EnableExperimentalMode = true });
Sessions can now be created with an additionalDirectories field that exposes extra working directories to the session alongside the primary workspace. (#2180)
const session = await client.createSession({
additionalDirectories: ["/path/to/other/project"]
});
permission.requested events and permission handler callbacks now carry an optional managedApprovalRequired flag. When set, the permission must be approved by a person — built-in approve-all handlers refuse it loudly rather than silently approving, and custom handlers can inspect the flag to surface a proper UI prompt. (#2080)
mode='json' in tool results to avoid serialization errors (#2225)@joshspicer made their first contribution in #2080@connor4312 made their first contribution in #2112@DonJayamanne made their first contribution in #2180Generated by Release Changelog Generator · sonnet46 18.7 AIC · ⌖ 4.92 AIC · ⊞ 8.6K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.73, model: claude-sonnet-4.6, id: 30870194454, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/30870194454 -->
bugfix: [Python] sessions.list() raised ValueError for any non-empty session list due to boolean-discriminated union decoding bug
sessions.list() raised ValueError for any non-empty session list due to boolean-discriminated union decoding bug (#2123)PermissionDecisionApproveForIonApproval) for permission approval types; now emits the correct schema-named aliases (PermissionDecisionApproveForSessionApproval, PermissionDecisionApproveForLocationApproval) (#1652)CustomAgentsLocalOnly was only sent via session.options.update after session creation, arriving too late to restrict agent discovery to the working directory; it is now included in the session.create and session.resume wire payloads (#1899)@abhinavgautam01 made their first contribution in #1652@arimu1 made their first contribution in #2032Generated by Release Changelog Generator · sonnet46 21.4 AIC · ⌖ 4.16 AIC · ⊞ 8.6K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.73, model: claude-sonnet-4.6, id: 30652792188, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/30652792188 -->
Agent Factories let a trusted extension declare a JavaScript closure that orchestrates a fleet of subagents, then invoke it by name. The runtime invok
Agent Factories let a trusted extension declare a JavaScript closure that orchestrates a fleet of subagents, then invoke it by name. The runtime invokes the factory closure over a reverse RPC call, passing primitives to spawn subagents, journal results (so a resumed run replays completed work for free), compose work in parallel or as a pipeline, and report progress. (#2114)
import { defineFactory, joinSession } from "`@github/copilot-sdk`/extension";
const myFactory = defineFactory({
meta: { name: "my-factory", description: "Orchestrates subagents" },
run: async ({ spawnAgent, journal }) => {
const result = await spawnAgent({ prompt: "Summarize the repo" });
return journal("done", result);
},
});
const session = await joinSession({ factories: [myFactory] });
const run = await session.factory.run({ name: "my-factory", input: {} });
Everything is gated behind the runtime's agent_factories flag and billing gate, and all public types are marked @experimental.
@nytron88 made their first contribution in #2117@syedkazmi14 made their first contribution in #2101@smz202000 made their first contribution in #2019Generated by Release Changelog Generator · sonnet46 25.9 AIC · ⌖ 5.11 AIC · ⊞ 8.6K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.73, model: claude-sonnet-4.6, id: 30575593646, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/30575593646 -->
Applications can now intercept the natural stopping point of the top-level agent across all SDKs. Return { decision: "block", reason } to enqueue a fo
agentStop lifecycle hookApplications can now intercept the natural stopping point of the top-level agent across all SDKs. Return { decision: "block", reason } to enqueue a follow-up message and keep the agent running; omit or return no decision to let it stop normally. (#2054)
session.hooks.agentStop(async ({ stopHookActive }) => {
if (stopHookActive) return; // don't block continuation turns
return { decision: "block", reason: "Run final validation and fix any failures." };
});
session.Hooks.AgentStop(async (input, ct) => {
if (input.StopHookActive) return null; // don't block continuation turns
return new AgentStopOutput { Decision = "block", Reason = "Run final validation and fix any failures." };
});
Client::start now exposes a StartupTimings struct that breaks down initialization latency into per-phase millisecond fields (process_spawn_ms, transport_setup_ms, handshake_ms, and more), making it easier to diagnose cold-start performance. (#2066)
[Java] custom JSON schema override for @CopilotToolParamThe @CopilotToolParam annotation now accepts an optional schema attribute for passing an explicit JSON Schema string, enabling support for third-party types that the built-in schema generator cannot automatically map. (#2069)
`@CopilotTool`("Schedule a deployment")
public String scheduleDeployment(
`@CopilotToolParam`(value = "Deployment time in ISO-8601",
schema = "{\"type\":\"string\",\"format\":\"date-time\"}")
com.acme.internal.AcmeDateTime deployTime) { ... }
@CopilotToolParam descriptions at compile time (#1980)@adirh3 made their first contribution in #2047Generated by Release Changelog Generator · sonnet46 45.2 AIC · ⌖ 4.94 AIC · ⊞ 8.6K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.73, model: claude-sonnet-4.6, id: 30515313396, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/30515313396 -->
Custom sub-agents can now have their own reasoning effort level, independent of the parent session. When reasoningEffort is omitted on a custom agent,
Custom sub-agents can now have their own reasoning effort level, independent of the parent session. When reasoningEffort is omitted on a custom agent, the backend applies its own default — the session-level setting is not inherited. (#1981)
const session = await client.createSession({
customAgents: [{
name: "planner",
prompt: "You plan tasks.",
reasoningEffort: "high",
}],
});
var session = await client.CreateSessionAsync(new SessionOptions {
CustomAgents = [new CustomAgentConfig {
Name = "planner",
Prompt = "You plan tasks.",
ReasoningEffort = ReasoningEffort.High,
}],
});
expAssignments session config field across all SDKs (#2033)ask_user starving the per-session event loop (#2034)@lukewar made their first contribution in #1880[!WARNING] <details> <summary>Firewall blocked 1 domain</summary>
The following domain was blocked by the firewall during workflow execution:
awmgmcpgTo allow these domains, add them to the
network.allowedlist in your workflow frontmatter:network: allowed: - defaults - "awmgmcpg"See Network Configuration for more information.
</details>
Generated by Release Changelog Generator · 39.1 AIC · ⌖ 5.54 AIC · ⊞ 7.2K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.70, model: claude-sonnet-4.6, id: 29965645125, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/29965645125 -->
You can now set a per-agent reasoning effort level on custom agent configurations. When omitted, the backend chooses its default; an explicit value ov
You can now set a per-agent reasoning effort level on custom agent configurations. When omitted, the backend chooses its default; an explicit value overrides the backend default for that specific agent without affecting the parent session. (#1981)
const config: CustomAgentConfig = {
name: "my-agent",
prompt: "...",
reasoningEffort: "high",
};
var config = new CustomAgentConfig {
Name = "my-agent",
Prompt = "...",
ReasoningEffort = "high",
};
[!WARNING] <details> <summary>Firewall blocked 1 domain</summary>
The following domain was blocked by the firewall during workflow execution:
awmgmcpgTo allow these domains, add them to the
network.allowedlist in your workflow frontmatter:network: allowed: - defaults - "awmgmcpg"See Network Configuration for more information.
</details>
Generated by Release Changelog Generator · 53.4 AIC · ⌖ 4.74 AIC · ⊞ 7.3K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.70, model: claude-sonnet-4.6, id: 29849964843, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/29849964843 -->
The SDK can now host the Copilot runtime in-process by loading the native runtime library via its C ABI (FFI), eliminating the overhead of spawning a
The SDK can now host the Copilot runtime in-process by loading the native runtime library via its C ABI (FFI), eliminating the overhead of spawning a child process. This experimental transport is available for Node.js, Rust, Python, and Go. (#1953, #1915, #1975, #1976)
const client = new CopilotClient({ connection: RuntimeConnection.forInProcess() });
var client = new CopilotClient(new CopilotClientOptions { Connection = RuntimeConnection.ForInProcess() });
A new toolSearch session option controls how the SDK defers tools when the total tool count exceeds a threshold. When enabled (the default), excess MCP and external tools are surfaced on demand through the built-in tool_search_tool rather than pre-loaded into every prompt. Tool results can also include toolReferences to link cited sources back to the tool that produced them. (#1933)
const session = await client.createSession({
toolSearch: { defer: "auto" },
});
var session = await client.CreateSessionAsync(new SessionConfig
{
ToolSearch = new ToolSearchConfig { Defer = "auto" },
});
Tool definitions now accept an optional metadata bag that is forwarded verbatim in session.create and session.resume RPC calls. This lets hosts attach namespaced, implementation-specific metadata to tools without expanding the typed public contract; unknown keys are preserved and round-tripped untouched. (#1864)
session.defineTool("my-tool", { metadata: { "myapp:priority": 1 } }, handler);
session.DefineTool("my-tool", new ToolOptions { Metadata = new() { ["myapp:priority"] = 1 } }, handler);
canvasProvider field to session create/resume config so hosts can supply a stable canvas-provider identity that survives cold resume (#1847)enableManagedSettings flag in session create/resume for enterprise managed-settings enforcement (#1925)agentId, parentAgentId, and interactionType from LLM inference start frames into request-handler contexts (#1949)HashMap with IndexMap (#1931)native-tls for the build-time CLI download (#1964)@agoncal made their first contribution in #1951@Shivam60 made their first contribution in #1964@rinceyuan made their first contribution in #1978@belaltaher8 made their first contribution in #1864Full Changelog: https://github.com/github/copilot-sdk/compare/v1.0.6...v1.0.7
Generated by Release Changelog Generator · sonnet46 1.2M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 29510898443, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/29510898443 -->
Tool search lets the model discover tools on demand instead of loading every tool definition up front. When the active tool count exceeds the deferral
Tool search lets the model discover tools on demand instead of loading every tool definition up front. When the active tool count exceeds the deferral threshold, MCP and external tools are marked as deferred and surfaced through the built-in tool_search_tool. This release adds a toolSearch option to CreateSession/ResumeSession so applications can enable/disable the feature and tune the threshold. (#1933)
const session = await client.createSession({
toolSearch: { enabled: true, deferThreshold: 20 },
});
var session = await client.CreateSessionAsync(new SessionConfig
{
ToolSearch = new ToolSearchConfig { Enabled = true, DeferThreshold = 20 },
});
Tool results can now return toolReferences — a list of tool names chosen by a tool-search override — to narrow the active tool set before the next model turn.
The Python and Go SDKs now support loading the Copilot runtime as a native shared library in-process, matching the existing .NET, TypeScript, and Rust implementations. This avoids spawning a child process and communicates over the runtime's C ABI instead of stdio or TCP. (#1975, #1976)
Python — experimental, no new dependencies (uses stdlib ctypes):
from copilot import CopilotClient, RuntimeConnection
client = CopilotClient(connection=RuntimeConnection.for_inprocess())
Go — requires the copilot_inprocess build tag:
// build with: go build -tags copilot_inprocess
client, _ := sdk.NewClient(&sdk.ClientOptions{
Connection: &sdk.InProcessConnection{},
})
The SDK selects and provisions the native runtime automatically. Per-client Env, WorkingDirectory, and Telemetry settings are not supported with in-process transport (they cannot be isolated in a shared host process). Set COPILOT_SDK_DEFAULT_CONNECTION=inprocess to use in-process transport by default across your application.
@rinceyuan made their first contribution in #1978Generated by Release Changelog Generator · sonnet46 762.9K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 29385766972, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/29385766972 -->
The existing Transport::Stdio and Transport::Tcp variants are fully backward-compatible — no breaking changes for current consumers.
The Rust SDK can now host the Copilot runtime as an in-process cdylib instead of spawning a CLI subprocess. Select it with Transport::InProcess or set COPILOT_SDK_DEFAULT_CONNECTION=inprocess. (#1915)
let client = ClientOptions::new()
.transport(Transport::InProcess)
.build()?;
The existing Transport::Stdio and Transport::Tcp variants are fully backward-compatible — no breaking changes for current consumers.
rustls/ring to native-tls to resolve Microsoft Component Governance advisory (#1964)@Shivam60 made their first contribution in #1964Generated by Release Changelog Generator · sonnet46 447.1K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 29133943660, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/29133943660 -->
The Node.js SDK now supports an experimental in-process transport that hosts the Copilot runtime as a native library via FFI (using `koffi`, instead o
The Node.js SDK now supports an experimental in-process transport that hosts the Copilot runtime as a native library via FFI (using [koffi]((koffi.dev/redacted), instead of spawning a child process. This reduces process overhead and eliminates the need for a separate CLI installation when using a bundled native runtime. (#1953)
const connection = RuntimeConnection.forInProcess("/path/to/libcopilot-runtime.so");
const client = new CopilotClient({ runtimeConnection: connection });
canvasProvider field on session configAll SDKs (Node.js, .NET, Go, Python, Rust) now support an optional canvasProvider field on session create and resume config. This lets host connections supply a stable canvas-provider identity so host-provided canvases restore correctly across cold resume. (#1847)
canvasProvider: { id: "app:builtin:my-host", name: "My Host" }CanvasProvider = new CanvasProviderIdentity { Id = "app:builtin:my-host" }canvas_provider=CanvasProviderIdentity(id="app:builtin:my-host")CanvasProvider: &CanvasProviderIdentity{Id: "app:builtin:my-host"}Request handler callbacks across all SDKs (Node.js, Python, Go, .NET, Rust, Java) now expose agentId, parentAgentId, and interactionType from LLM inference request-start frames. This lets BYOK/CAPI request handlers identify which agent is making the inference request, and whether it is a subagent call. (#1949)
Generated by Release Changelog Generator · sonnet46 498.2K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 29070724716, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/29070724716 -->
Applications can now pass enableManagedSettings when creating or resuming a session to opt the runtime into enterprise managed-settings enforcement (b
enableManagedSettings for enterprise policy enforcement (all SDKs)Applications can now pass enableManagedSettings when creating or resuming a session to opt the runtime into enterprise managed-settings enforcement (bypass-permissions policy) using the session's gitHubToken. This is purely additive and opt-in — omitting it behaves exactly as before. (#1925)
const session = await client.createSession({
gitHubToken: "...",
enableManagedSettings: true,
});
var session = await client.CreateSessionAsync(new SessionConfig
{
GitHubToken = "...",
EnableManagedSettings = true,
});
enable_managed_settings=True kwarg on create_session / resume_sessionEnableManagedSettings: boolPtr(true) on SessionConfig / ResumeSessionConfig.with_enable_managed_settings(true) builder on SessionConfigsessionConfig.setEnableManagedSettings(true) on SessionConfigThe Rust SDK previously used HashMap for Tool.parameters and mcp_servers fields, causing random key ordering in serialized JSON each process startup. This busted the model provider's prompt cache on the system+tools prefix, increasing cost and latency. HashMap is now replaced with IndexMap for these model-visible maps. (#1931)
IndexMap mirrors HashMap's API and is re-exported as github_copilot_sdk::IndexMap — migration is mechanical:
// Before: use std::collections::HashMap;
// After:
use github_copilot_sdk::IndexMap; // same API, deterministic iteration order
Affected public types: Tool.parameters, mcp_servers on SessionConfig / ResumeSessionConfig / CustomAgentConfig, and the tool_parameters / try_tool_parameters return types.
@agoncal made their first contribution in #1951Generated by Release Changelog Generator · sonnet46 987.8K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 29030149715, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/29030149715 -->
Stream Anthropic /messages responses in E2E fake handlers by @stephentoub in https://github.com/github/copilot-sdk/pull/1868
Full Changelog: https://github.com/github/copilot-sdk/compare/v1.0.5...v1.0.6
Two new experimental methods on session.metadata provide per-source token attribution for the session's context window.
Two new experimental methods on session.metadata provide per-source token attribution for the session's context window. (#1886)
getContextAttribution() returns a flat list of attribution entries — skills, subagents, MCP servers, tools, plugins — each with a token count and hierarchical nesting via parentId. getContextHeaviestMessages() returns the largest individual messages currently in context, most-expensive first.
const attr = await session.metadata.getContextAttribution();
// attr.contextAttribution.entries → [{ kind: 'skill', id: 'skill:tmux', tokens: 1234, ... }, ...]
const heavy = await session.metadata.getContextHeaviestMessages({ limit: 10 });
var attr = await session.Metadata.GetContextAttributionAsync();
var heavy = await session.Metadata.GetContextHeaviestMessagesAsync(limit: 10);
SlashCommandInput now supports an optional choices field, allowing slash commands to declare selectable literal options with human-facing descriptions (#1886)ExternalToolTextResultForLlm now supports toolReferences for returning deferred tool names to the model from a tool-search override (#1886)Generated by Release Changelog Generator · claude-sonnet-4.6
Generated by Release Changelog Generator · sonnet46 1.8M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 28602028763, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/28602028763 -->
All SDKs now support an optional onGitHubTelemetry callback in ClientOptions that lets hosts receive per-session GitHub telemetry events forwarded by
All SDKs now support an optional onGitHubTelemetry callback in ClientOptions that lets hosts receive per-session GitHub telemetry events forwarded by the runtime. When a handler is registered, the client automatically opts sessions in via enableGitHubTelemetryRedirection and dispatches each incoming gitHubTelemetry.event notification to the callback. This feature is experimental, intentionally hidden from public IDE completion in C# ([EditorBrowsable(Never)]) and Rust (#[doc(hidden)]). (#1835)
const client = new CopilotClient({
onGitHubTelemetry: (notification) => { /* handle telemetry event */ },
});
var client = new CopilotClient(new CopilotClientOptions
{
OnGitHubTelemetry = (notification) => { /* handle telemetry event */ return Task.CompletedTask; },
});
Generated by Release Changelog Generator · sonnet46 1.2M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 28552536351, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/28552536351 -->
SDK applications can now handle OAuth challenges from MCP servers that require host-provided authentication. Register an onMcpAuthRequest callback on
SDK applications can now handle OAuth challenges from MCP servers that require host-provided authentication. Register an onMcpAuthRequest callback on the session config and the SDK will invoke it whenever an MCP server responds with a 401 WWW-Authenticate challenge; return an access token (or cancel the request). Supports initial auth, refresh, reauth, and upscope flows across all SDKs. (#1669)
const session = await client.createSession({
onMcpAuthRequest: async (request) => ({
accessToken: await myIdentityProvider.getToken(request.serverUrl),
}),
});
var session = await client.CreateSessionAsync(new SessionConfig
{
OnMcpAuthRequest = async ctx =>
McpAuthResult.FromToken(new McpAuthToken
{
AccessToken = await myIdentityProvider.GetTokenAsync(ctx.ServerUrl)
}),
});
Three additional session configuration options are now available across all SDKs. (#1865)
const session = await client.createSession({
enableCitations: true,
excludedBuiltinAgents: ["github-search"],
sessionLimits: { maxAiCredits: 10 },
});
var session = await client.CreateSessionAsync(new SessionConfig
{
EnableCitations = true,
ExcludedBuiltInAgents = ["github-search"],
SessionLimits = new SessionLimitsConfig { MaxAiCredits = 10 },
});
getBearerToken → bearerTokenProvider; add sessionId to ProviderTokenArgs for per-session token scoping (#1796)registerInterest sent before session.resume, causing "Session not found" errors when resuming a session with onMcpAuthRequest (#1861)@CopilotTool and @CopilotToolParam annotations with compile-time annotation processor for ergonomic tool registration via ToolDefinition.fromObject() (#1792, #1838)ToolInvocation parameter injection in @CopilotTool methods for accessing session context without exposing it to the LLM schema (#1832)Attachment enum (GitHubCommit, GitHubRelease, GitHubActionsJob, GitHubRepository, GitHubFileDiff, GitHubTreeComparison, GitHubUrl, GitHubFile, GitHubSnippet) (#1823)@pallaviraiturkar0 made their first contribution in #1823@roji made their first contribution in #1827@coleflennikenmsft made their first contribution in #1854@szabta89 made their first contribution in #1856Full Changelog: https://github.com/github/copilot-sdk/compare/v1.0.4...v1.0.5
Generated by Release Changelog Generator · sonnet46 2.6M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 28527869621, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/28527869621 -->
When a Copilot session connects to an OAuth-protected MCP server, the SDK now calls back to your application to supply OAuth tokens. Register an onMcp
When a Copilot session connects to an OAuth-protected MCP server, the SDK now calls back to your application to supply OAuth tokens. Register an onMcpAuthRequest handler in the session config to provide tokens or cancel the request. (#1669)
const session = await client.startSession({
onMcpAuthRequest: async (request) => {
const token = await myOAuthFlow(request.serverUrl, request.reason);
return token ? { kind: "token", accessToken: token } : { kind: "cancelled" };
},
});
var session = await client.StartSessionAsync(new SessionConfig
{
OnMcpAuthRequest = async (ctx) =>
{
var token = await MyOAuthFlow(ctx.ServerUrl, ctx.Reason);
return token is not null
? McpAuthResult.FromToken(new McpAuthToken { AccessToken = token })
: McpAuthResult.Cancel();
},
});
sessionId in BYOK bearer-token callback; field renamed to bearerTokenProviderThe BYOK config field has been renamed from getBearerToken to bearerTokenProvider across all SDKs. The callback now also receives a sessionId, so a single callback shared across multiple sessions can scope token acquisition or caching per session. (#1796)
const client = new CopilotClient({
provider: {
bearerTokenProvider: async ({ providerName, sessionId }) => {
return await getTokenForSession(sessionId);
},
},
});
var client = new CopilotClient(new CopilotClientConfig
{
Provider = new ProviderConfig
{
BearerTokenProvider = async (args) => await GetTokenForSession(args.SessionId),
},
});
@CopilotTool annotation-based tool definitionJava applications can now define Copilot tools by annotating methods with @CopilotTool and @CopilotToolParam instead of building ToolDefinition objects manually. A compile-time annotation processor generates the metadata, and ToolDefinition.fromObject() registers all annotated methods at once. (#1792)
`@CopilotTool`("Get the current weather for a given city")
public String getWeather(
`@CopilotToolParam`(value = "The city", required = true) String city,
`@CopilotToolParam`(value = "Unit: celsius or fahrenheit", defaultValue = "celsius") String unit) {
return fetchWeather(city, unit);
}
List<ToolDefinition> tools = ToolDefinition.fromObject(new WeatherTools());
@CopilotTool methods can declare ToolInvocation as a hidden injected parameter to access runtime context such as sessionId (#1832)@Param annotation to @CopilotToolParam (#1838)Attachment enum (GitHubCommit, GitHubRelease, GitHubActionsJob, GitHubRepository, GitHubFileDiff, GitHubTreeComparison, GitHubUrl, GitHubFile, GitHubSnippet) (#1823)@pallaviraiturkar0 made their first contribution in #1823@roji made their first contribution in #1827Generated by Release Changelog Generator · sonnet46 1.5M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 28432082983, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/28432082983 -->
The BYOK bearer-token provider callback now receives a sessionId parameter, enabling per-session token scoping or caching. The configuration field has
sessionId and is renamed to bearerTokenProviderThe BYOK bearer-token provider callback now receives a sessionId parameter, enabling per-session token scoping or caching. The configuration field has been renamed from getBearerToken to bearerTokenProvider across all six SDKs (and the callback type to BearerTokenProvider), aligning with the existing *Provider naming convention. (#1796)
const client = new CopilotClient({
bearerTokenProvider: async ({ sessionId }) => getTokenForSession(sessionId),
});
var client = new CopilotClient(new CopilotClientOptions {
BearerTokenProvider = async (args) => await GetTokenForSessionAsync(args.SessionId),
});
@CopilotTool annotation for ergonomic Java tool registrationJava applications can now declare tools using the @CopilotTool and @Param annotations. The SDK's annotation processor generates the necessary metadata at compile time; use ToolDefinition.fromObject(...) to register an entire object's annotated methods without manual JSON schema construction. (#1792)
Note: This API is currently
@CopilotExperimental.
`@CopilotTool`("Get the current weather for a city")
public String getWeather(
`@Param`(value = "City name", required = true) String city,
`@Param`(value = "Unit: celsius or fahrenheit", required = false, defaultValue = "celsius") String unit) {
// implementation
}
// Registration:
List<ToolDefinition> tools = ToolDefinition.fromObject(new WeatherTools());
The Rust Attachment enum now includes all 9 GitHub-anchored reference types that the CLI can deliver — GitHubCommit, GitHubRelease, GitHubActionsJob, GitHubRepository, GitHubFileDiff, GitHubTreeComparison, GitHubUrl, GitHubFile, and GitHubSnippet. Previously these variants were silently dropped at the SDK boundary when received. (#1823)
@pallaviraiturkar0 made their first contribution in #1823Generated by Release Changelog Generator · sonnet46 1.1M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 28381408107, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/28381408107 -->
Add experimental multi-provider BYOK registry config across all six SDKs by @stephentoub in https://github.com/github/copilot-sdk/pull/1718
Full Changelog: https://github.com/github/copilot-sdk/compare/v1.0.2...v1.0.4
improvement: [Java] rename SystemPromptSections to SystemMessageSections for cross-SDK consistency; old class deprecated with forRemoval=true
Sessions can now be configured with persistent memory, allowing the agent to recall information across turns. Set memory: { enabled: true } when creating or resuming a session; when omitted the runtime default applies. (#1617)
const session = await client.createSession({
memory: { enabled: true },
});
var session = await client.CreateSessionAsync(new SessionConfig
{
Memory = new MemoryConfiguration { Enabled = true }
});
defer parameter for tool definitionsTools now support a defer option controlling whether they are pre-loaded eagerly or surfaced lazily through tool search. Use "auto" (the default) to allow lazy loading, or "never" to force pre-loading. (#1632)
defineTool("lookup_issue", {
description: "Fetch issue details",
parameters: z.object({ id: z.string() }),
defer: "auto",
handler: async ({ id }) => { /* ... */ },
});
var tool = CopilotTool.DefineTool(
async ([Description("Issue ID")] string id) => { /* ... */ },
toolOptions: new CopilotToolOptions { Defer = CopilotToolDefer.Auto });
otlpProtocol telemetry option ("http/json" or "http/protobuf") for configuring OTLP export transport (#1648)ModelBilling.tokenPrices on public SDK types, exposing per-tier input/output/cache pricing and context window limits (#1633)runtime.shutdown during normal client stop for deterministic OTEL telemetry flush before process cleanup (#1667)context.Context through the JSON-RPC request path for proper cancellation support (#1643)getOpenCanvases() to CopilotSession to track currently open canvas instances, matching the other SDKs (#1606)SystemPromptSections to SystemMessageSections for cross-SDK consistency; old class deprecated with forRemoval=true (#1683)to_timedelta_int to avoid serialization errors (#1668)build.rs when DOCS_RS env var is set (#1660)@andyfeller made their first contribution in #1631@almaleksia made their first contribution in #1632@idryzhov made their first contribution in #1668@scottaddie made their first contribution in #1636Generated by Release Changelog Generator · sonnet46 1.8M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 27729623733, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/27729623733 -->
improvement: [Java] generated types now propagate schema stability and deprecation metadata — experimental items gain @apiNote Javadoc and deprecated…
@CopilotExperimental compile-time gate for Java SDKThe Java SDK now ships a @CopilotExperimental annotation and a JSR 269 annotation processor that causes compilation to fail when experimental SDK APIs are referenced without opting in. Annotate a class or method with @AllowCopilotExperimental, or pass -Acopilot.experimental.allowed=true to the compiler to acknowledge the experimental status. (#1601)
// Opt in at the declaration level
`@AllowCopilotExperimental`
public class MyApp {
// experimental SDK types and methods may be used here
}
<!-- Or opt in for the entire compilation unit via Maven -->
<compilerArgs>
<arg>-Acopilot.experimental.allowed=true</arg>
</compilerArgs>
open_canvases snapshot now correctly shrinks when session.canvas.closed is emitted — previously closed canvases were never removed (#1604)pub(crate) instead of pub (#1596)@apiNote Javadoc and deprecated items gain @Deprecated (#1591)Generated by Release Changelog Generator · sonnet46 1.9M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.55, model: claude-sonnet-4.6, id: 27291901369, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/27291901369 -->
Update vulnerable npm lockfile dependencies by @stephentoub in https://github.com/github/copilot-sdk/pull/1415
^1.0.52-1, add preMcpToolCall hook, fix PingResponse timestamp type by @edburns in https://github.com/github/copilot-sdk/pull/1389kind() method by @heaths in https://github.com/github/copilot-sdk/pull/1400session.mcp.apps.callTool result to JsonNode and harden mvn clean by @edburns in https://github.com/github/copilot-sdk/pull/1523@github/copilot dependency to ^1.0.57 by @edburns in https://github.com/github/copilot-sdk/pull/1546Full Changelog: https://github.com/github/copilot-sdk/compare/v0.3.0...v1.0.0
⚠️ Breaking change for Go callers. Key renames include:
All Go identifiers now use idiomatic uppercase initialisms as required by Go conventions. (#1527)
⚠️ Breaking change for Go callers. Key renames include:
Api → API, Rpc → RPC, Mcp → MCP, Sse → SSEUrl/Uri → URL/URI, Id → ID, Tcp → TCPAdo → ADO, Sdk → SDK, Fs → FSUriConnection → URIConnection, TcpConnection → TCPConnectionSessionConfig.EnableConfigDiscovery, ResumeSessionConfig.EnableConfigDiscovery, and ResumeSessionConfig.ContinuePendingWork are now *bool instead of bool, allowing callers to express explicit false (opt out) vs. unset (defer to runtime default). (#1536)
⚠️ Breaking change for Go callers. Use copilot.Bool(true) / copilot.Bool(false) to set a value, or leave the field nil to defer to the runtime default.
cfg := copilot.SessionConfig{
EnableConfigDiscovery: copilot.Bool(false), // explicitly opt out
}
Java callers can now retrieve responses from slash commands via the RPC layer. Previously it was possible to invoke slash commands but not to receive their responses programmatically. (#1520)
Generated types are no longer exposed under the internal generated sub-module. (#1535)
copilot.session_events.X and copilot.rpc.X instead of copilot.generated.*github_copilot_sdk::session_events::X and github_copilot_sdk::rpc::X instead of github_copilot_sdk::generated::*suppressResumeEvent to disableResume on the wire (#1529)session.mcp.apps.callTool result to JsonNode (#1523)__version__ from package metadata; align Node version sentinel (#1521)@dmytrostruk made their first contribution in #1515@willglas made their first contribution in #1529Generated by Release Changelog Generator · ● 1.4M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.48, model: claude-sonnet-4.6, id: 26783077412, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/26783077412 -->
Nothing published for this version
Fixes a race condition in the .NET CopilotClient where the stderr reader could outlive the CLI process during shutdown, causing TaskScheduler.Unobserv
Fixes a race condition in the .NET CopilotClient where the stderr reader could outlive the CLI process during shutdown, causing TaskScheduler.UnobservedTaskException errors. The stderr pump now has its own cancellation token and connection cleanup properly coordinates pump shutdown before disposing the process. (#1136)
install_bundled_cli and HAS_BUNDLED_CLITwo new public APIs make it easier to access the bundled CLI path before a Client exists, eliminating the need for consumers to duplicate the cache-path resolution logic. (#1489)
// Check if a bundled CLI is available at compile time
if copilot_sdk::HAS_BUNDLED_CLI {
// Extract and get the path to the bundled CLI
if let Some(path) = copilot_sdk::install_bundled_cli() {
println!("Bundled CLI at: {}", path.display());
}
}
[!NOTE] <details> <summary>🔒 Integrity filter blocked 2 items</summary>
The following items were blocked because they don't meet the GitHub integrity level.
- #1136
search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".- #868
search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".To allow these resources, lower
min-integrityin your GitHub frontmatter:tools: github: min-integrity: approved # merged | approved | unapproved | none</details>
Generated by Release Changelog Generator · ● 2.4M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.48, model: claude-sonnet-4.6, id: 26641549279, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/26641549279 -->
…with the Azure SDK for Rust design. This is a breaking change for Rust callers matching on error variants — update match arms to call .kind() instead.
CopilotClientMode.Empty for multi-tenant appsMulti-tenant applications can now opt into a hardened "empty" client mode that starts from a clean slate: no built-in tools, host integration disabled, system prompt sanitized, and storage explicitly required. This prevents user-specific state (plugins, custom agents, co-author trailers, etc.) from leaking across tenants. (#1428)
const client = new CopilotClient({
mode: "empty",
baseDirectory: "/tmp/per-tenant-state",
});
const session = await client.createSession({
onPermissionRequest: approveAll,
availableTools: new ToolSet()
.addBuiltIn(BuiltInTools.Isolated)
.addMcp("*"),
excludedTools: new ToolSet()
.addMcp("github-delete_repository"),
});
using var client = new CopilotClient(new CopilotClientOptions
{
Mode = CopilotClientMode.Empty,
BaseDirectory = "/tmp/per-tenant-state",
});
await using var session = await client.CreateSessionAsync(new SessionConfig
{
OnPermissionRequest = PermissionHandler.ApproveAll,
AvailableTools = new ToolSet()
.AddBuiltIn(BuiltInTools.Isolated)
.AddMcp("*"),
ExcludedTools = new ToolSet()
.AddMcp("github-delete_repository"),
});
A new postToolUseFailure / OnPostToolUseFailure hook lets SDK users observe failed tool executions and inject follow-up guidance, separate from the existing success-only postToolUse hook. Available across Node, Python, Go, .NET, and Rust. (#1421)
session.hooks.postToolUseFailure = async (event) => {
console.error(`Tool ${event.toolName} failed: ${event.error}`);
};
session.OnPostToolUseFailure = async (e, ct) =>
{
Console.Error.WriteLine($"Tool {e.ToolName} failed: {e.Error}");
};
agentMode on MessageOptionsAll six SDKs now expose an agentMode field on MessageOptions to set the per-message UI mode (interactive, plan, autopilot, shell). Previously there was no correct way to request plan/autopilot mode from the SDK. (#1438)
session.send(message, { agentMode: "plan" })session.SendAsync(message, new MessageOptions { AgentMode = "plan" })session.send(message, agent_mode="plan")session.Send(ctx, message, copilot.MessageOptions{AgentMode: "plan"})kind() methodRust SDK error types have been refactored from a flat #[non_exhaustive] enum to a struct-with-kind() pattern, aligning with the Azure SDK for Rust design. This is a breaking change for Rust callers matching on error variants — update match arms to call .kind() instead. (#1400)
error.data in the .NET client transport (#1425)@heaths made their first contribution in #1400Generated by Release Changelog Generator · ● 3.6M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.48, model: claude-sonnet-4.6, id: 26535875210, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/26535875210 -->
> ⚠️ Breaking changes: This release includes breaking changes from the API review. See the breaking changes summary below and the detailed migration d…
To make it easier to keep track of what's changed during the beta period, these release notes cover all the updates since beta 1.
This release consolidates a major round of API review, adds new capabilities (remote sessions, MCP hook, mode handlers), and introduces the Rust SDK. Every SDK went through a thorough final API review, resulting in cleaner, more consistent, and more idiomatic APIs that we can support post-GA.
🚀 GA timeline: The 1.0.0 GA release is planned for approximately one week from now.
⚠️ Breaking changes: This release includes breaking changes from the API review. See the breaking changes summary below and the detailed migration doc that you can give as context to Copilot to help it update your app code quickly.
A new Rust SDK joins the family, bringing the same Copilot capabilities to Rust applications. It supports the full feature set — sessions, tools, hooks, streaming, MCP, permissions, telemetry, canvases, and remote sessions — with idiomatic Rust patterns throughout.
use github_copilot_sdk::{Client, ClientOptions, SessionConfig, permission::ApproveAllHandler};
let client = Client::new(ClientOptions::default());
client.start().await?;
let session = client.create_session(
SessionConfig::default()
.with_permission_handler(Arc::new(ApproveAllHandler))
).await?;
let reply = session.send_and_wait("Hello!").await?;
The Rust SDK ships with the Copilot runtime bundled by default — just add the crate and go. The runtime is downloaded when your app builds and is embedded in your distributable binary. Opt out of bundling with default-features = false if you manage the CLI yourself.
Remote sessions connect a local Copilot session to GitHub's backend services, producing a shareable URL that lets users access the session from GitHub web or mobile — useful for monitoring a locally-running agent from your phone, or sharing a session with a teammate. Enable it globally or toggle it per-session with session.rpc.remote.enable().
const client = new CopilotClient({
enableRemoteSessions: true,
});
// Each session emits a remote URL via session.info events
session.on("session.info", (event) => {
if (event.data.infoType === "remote") {
console.log("Remote URL:", event.data.url); // Share this or render as QR code
}
});
var client = new CopilotClient(new CopilotClientOptions {
EnableRemoteSessions = true,
});
Requirements: the user must be authenticated (gitHubToken or useLoggedInUser), and the session's working directory must be a GitHub repository. The enableRemoteSessions option only applies when the SDK spawns the CLI process (ignored when connecting to an external server).
Cloud sessions go a step further — the session runs entirely in the cloud rather than on the local machine. Pass a cloud option with repository metadata when creating a session:
const session = await client.createSession({
onPermissionRequest: approveAll,
cloud: {
repository: { owner: "github", name: "my-repo", branch: "main" },
},
});
Both features are available in all languages.
A new preMcpToolCall hook fires before every MCP tool invocation, giving your application the chance to inspect, modify, or block MCP tool calls. This is useful for adding authorization, logging, or stripping sensitive metadata from tool call arguments.
const session = await client.createSession({
onPermissionRequest: approveAll,
preMcpToolCall: async (context) => {
console.log(
`MCP tool: ${context.toolName} on server: ${context.serverName}`,
);
// Return modified args, or throw to block the call
return context.arguments;
},
});
var session = await client.CreateSessionAsync(new SessionConfig {
OnPermissionRequest = PermissionHandler.ApproveAll,
PreMcpToolCall = async (context) => {
Console.WriteLine($"MCP tool: {context.ToolName} on server: {context.ServerName}");
return context.Arguments;
},
});
Available in all languages.
Every SDK went through a comprehensive API review to make the developer experience cleaner and more idiomatic. The highlights:
Simplified client connection config — Instead of scattering transport options (cliPath, cliUrl, port, tcpConnectionToken, useStdio) across client options, there's now a single connection property with typed factory methods:
// Connect to an external server
const client = new CopilotClient({
connection: RuntimeConnection.forUri("http://localhost:3000"),
});
// Or spawn a local CLI over stdio (the default if no connection is specified)
const client = new CopilotClient({
connection: RuntimeConnection.forStdio(),
});
var client = new CopilotClient(new CopilotClientOptions {
Connection = RuntimeConnection.ForStdio(),
});
CopilotClient(connection=RuntimeConnection.for_uri("http://localhost:3000"))copilot.NewClient(&copilot.ClientOptions{Connection: copilot.UriConnection{Uri: "http://localhost:3000"}})Client::new(ClientOptions { connection: Some(RuntimeConnection::Uri { uri: "http://localhost:3000".into() }), ..Default::default() })send() now accepts a plain string — The most common case just got simpler:
// Before
const reply = await session.send({ prompt: "Hello!" });
// After
const reply = await session.send("Hello!");
// Full options still available:
const reply = await session.send({ prompt: "Analyze this", attachments: [...] });
Permission decisions are now typed factories instead of stringly-typed objects:
// Before
return new PermissionRequestResult { Kind = "approve-once" };
// After
return PermissionDecision.ApproveOnce();
// Also: PermissionDecision.Reject(), .UserNotAvailable(), .NoResult()
getMessages() → getEvents() — The method name now accurately reflects what it returns (the full event stream, not just messages).
See the breaking changes guide for the complete list of API changes per language.
onExitPlanModeRequest and onAutoModeSwitchRequest handlers let your app handle plan-approval flows and automatic mode switching (e.g., rate-limit recovery). Available in all languages.runtime_instructions system message section — A new section in the system message customization API for runtime-generated instructions, giving you another hook to inject or transform prompt content.enableSessionTelemetry — A per-session toggle to enable or disable telemetry collection, independent of the client-level telemetry config.ProviderConfig now supports modelId, wireModel, maxInputTokens, and maxOutputTokens, letting BYOK users decouple the model ID visible to agents from the wire model sent to the provider.rpc.* types by name, expect renames.This release includes breaking changes from a comprehensive API review. The changes are mechanical — mostly renames and reshaping — and make the APIs cleaner and more consistent as we finalize the 1.0.0 shape.
💡 Migrating your app? Pass the breaking changes document to GitHub Copilot and ask it to update your code. The document is structured as a machine-readable migration guide with before/after examples for every change.
| Change | All SDKs |
|---|---|
Client transport config → RuntimeConnection |
✅ |
copilotHome → baseDirectory |
✅ |
getMessages() → getEvents() |
✅ |
Permission results → PermissionDecision factories |
✅ (C#, Python, Rust) |
Handler renames (onExitPlanMode → onExitPlanModeRequest) |
✅ |
| Generated RPC type renames | ✅ |
Each language also has its own idiomatic changes beyond the shared ones above. See the detailed breaking changes document for the full per-language list.
improvement: hide deprecated APIs where supported
Applications can now declare and handle canvases — interactive UI surfaces hosted by the Copilot runtime. Register a single CanvasHandler on a session and receive routed canvas.open, canvas.close, and canvas.action.invoke events; call session.canvas.* for native host actions. (#1401)
session.setCanvasHandler({
onOpen: async (ctx) => { /* render canvas */ },
onAction: async (ctx) => { /* handle action */ },
onClose: async (ctx) => { /* cleanup */ },
});
session.SetCanvasHandler(new MyCanvasHandler());
Applications can enable remote sessions either at the client level (all sessions in a GitHub repo get a remote URL) or on demand mid-session. (#1192)
// Always-on via client option:
const client = new CopilotClient({ remote: true });
// On-demand per session:
const result = await session.rpc.remote.enable();
console.log("Remote URL:", result.url);
await session.rpc.remote.disable();
// Always-on:
var client = new CopilotClient(new CopilotClientOptions { Remote = true });
// On-demand:
var result = await session.Rpc.Remote.EnableAsync();
await session.Rpc.Remote.DisableAsync();
A new hook lets applications intercept MCP tool invocations before they execute — inspect, replace, or remove the _meta field sent to MCP servers. (#1366)
session.hooks.onPreMcpToolCall = async (input) => {
return { metaToUse: { ...input.meta, traceId: myTraceId } };
};
session.Hooks.OnPreMcpToolCall = async (input) =>
new PreMcpToolCallHookOutput { MetaToUse = new { traceId = myTraceId } };
Sessions can now be created with a cloud option to request cloud-backed remote sessions with repository metadata, without requiring a local CLI process. (#1306)
const session = await client.createSession({
cloud: { repository: { owner: "my-org", name: "my-repo" } },
});
var session = await client.CreateSessionAsync(new SessionConfig {
Cloud = new CloudSessionConfig { Repository = new RepositoryConfig { Owner = "my-org", Name = "my-repo" } }
});
The Rust SDK now bundles the Copilot CLI binary at publish time by default — no configuration needed to get a working binary. Opt out with default-features = false. (#1385)
# Default: CLI bundled automatically
copilot-sdk = "1.0.0-beta.7"
# Opt out of bundled CLI:
copilot-sdk = { version = "1.0.0-beta.7", default-features = false }
The Java SDK is now part of the monorepo, providing full parity with the other language SDKs including session management, tool registration, hooks, and E2E test coverage. (#1348, #1369, #1389)
var client = new CopilotClient();
var session = client.createSession(new SessionConfig()).join();
session.send("Hello from Java!").join();
The .NET, Python, and Rust SDKs now emit structured trace/log output covering CLI startup, JSON-RPC timing, session operations, and callback paths — making it easier to diagnose slow or failing connections. (#1217)
ILogger via structured fields and TimeSpan elapsed valueslogging with elapsed_ms, session_id, and request identifierstracing crate with structured fieldsCopilotTool.DefineTool is a typed wrapper around AIFunctionFactory.Create that applies Copilot-specific metadata (override flag, skip-permission behavior) without magic strings. (#1321)
var tool = CopilotTool.DefineTool("edit",
new CopilotToolOptions { IsOverride = true },
async (params) => { /* custom edit */ });
session.AddTool(tool);
All hook input types (PreToolUseHookInput, PostToolUseHookInput, SessionStartHookInput, etc.) now include a sessionId field, allowing applications to distinguish parent session hooks from sub-agent hooks. (#1290)
enableSessionTelemetry session option across all SDKs (#1224)model field to CustomAgentConfig across all SDKs (#1309)remote_session field to SessionConfig across all SDKs (#1295)runtime_instructions system message section across all SDKs (#1377)SessionFs SQLite support for runtime routing (#1299)MCPStdioServerConfig.args optional across all SDKs (#1347)netstandard and net10 targets (#1320)x-opaque-json to JsonElement at RPC params boundary (#1359)Ms suffix for duration properties in generated types (#1339).snupkg symbols package to NuGet.org (#1345)SetProcessDone race condition (#863)from_dict() round-trip for optional fields with schema defaults (#1313)@cschleiden made their first contribution in #1222@claudiogodoy99 made their first contribution in #863@tiagonbotelho made their first contribution in #1306Generated by Release Changelog Generator · ● 3.7M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.48, model: claude-sonnet-4.6, id: 26370426039, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/26370426039 -->
These releases include coordinated, intentional breaking changes based on API review feedback. Key changes:
The Java SDK is now a first-class part of the github/copilot-sdk monorepo, with full CI, Maven publishing workflows, and generated types that stay in sync with the rest of the SDK family. (#1348)
CopilotClient client = new CopilotClient();
CopilotSession session = client.createSession(new SessionConfig());
session.send("Hello from Java!");
preMcpToolCall hook across all SDKsApplications can now intercept MCP tool invocations before they execute — useful for injecting, replacing, or removing the _meta field sent to MCP servers. The hook returns a tri-state result: return null to leave _meta unchanged, return a new object to replace it, or explicitly set metaToUse to null to strip it entirely. (#1366)
session.hooks.onPreMcpToolCall = async (input) => {
return { metaToUse: { traceId: myTraceId() } };
};
session.Hooks.OnPreMcpToolCall = async (input) => {
return new PreMcpToolCallHookOutput { MetaToUse = new { traceId = MyTraceId() } };
};
Tools and permission handlers can be declared without providing a callback, leaving them pending for manual resolution. This makes it easier to pause execution and resolve requests from event streams rather than inline callbacks. (#1308)
// Declare without a callback — permission requests stay pending
session.setPermissionHandler({ kinds: ["edit"] });
// Later, resume manually from an event
session.resolvePermissionRequest(event.requestId, { outcome: "allow" });
// Declaration-only tool — no callback supplied
session.DefineTool(new ToolDefinition { Name = "myTool", Description = "..." });
sessionId on hook inputs — hooks now fire for sub-agentsAll six hook input types (PreToolUseHookInput, PostToolUseHookInput, etc.) now carry a sessionId field. Hooks also fire for tool calls made by sub-agents spawned via the task tool, and input.sessionId lets you distinguish parent from sub-agent invocations. (#1290)
These releases include coordinated, intentional breaking changes based on API review feedback. Key changes:
Connection configuration — CliPath/Port/CliUrl properties are replaced by a single RuntimeConnection discriminated union:
new CopilotClient({ connection: RuntimeConnection.stdio(...) })new CopilotClientOptions { Connection = RuntimeConnection.Stdio(...) }CLIUrl equivalent updatedConvenience send overloads — send(string) / sendAndWait(string) string overloads added for all SDKs.
Lifecycle events — now a typed polymorphic hierarchy (SessionCreatedEvent, etc.) instead of stringly-typed discriminators.
C# specifics — CopilotHome → BaseDirectory, delegate types replaced with Func<...>, LogLevel retyped to CopilotLogLevel, SessionConfigBase extracted. (#1343, #1357, #1360)
model field on CustomAgentConfigWhen defining custom sub-agents programmatically, you can now specify which model to use. The runtime falls back to the parent session model if the specified model is unavailable. (#1309)
customAgents: [{ name: "my-agent", model: "gpt-4o", ... }]new CustomAgentConfig { Name = "my-agent", Model = "gpt-4o" }custom_agents=[{"name": "my-agent", "model": "gpt-4o"}]CustomAgentConfig{Name: "my-agent", Model: "gpt-4o"}Session creation now accepts a cloud option to request cloud-backed remote sessions with repository metadata, matching the new runtime capability. (#1306)
CopilotTool.DefineTool helper for .NETThe .NET SDK now provides a typed CopilotTool.DefineTool wrapper that applies Copilot-specific metadata (override flags, skip-permission behavior) without magic strings, aligning C# with the typed helper APIs already available in other SDKs. (#1321)
var tool = CopilotTool.DefineTool("edit", new CopilotToolOptions { IsOverride = true },
async (params, ctx) => { /* custom edit implementation */ });
netstandard2.0 and net10 target frameworks (#1320).snupkg symbols package to NuGet.org (#1345)MCPStdioServerConfig.args optional across all SDKs (#1347)remote_session field to all SDK SessionConfig types (#1295)from_dict() round-trip for optional fields with schema defaults (#1313)Default on generated types (#1272)@tiagonbotelho made their first contribution in #1306Generated by Release Changelog Generator · ● 6.2M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, version: 1.0.48, model: claude-sonnet-4.6, id: 26266286427, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/26266286427 -->
Nothing published for this version
…with the repo's naming policy — note: this is a breaking change for Go callers using generated RPC types
Go SDK union types are now modelled as typed interfaces with concrete variants instead of flattened structs with many optional fields. Callers can switch on concrete variants and get compile-time safety — invalid union states that were previously representable are no longer possible. Unknown union members and session event payloads are preserved rather than dropped. (#1252)
switch v := event.Data.(type) {
case *SessionEventDataAssistantMessage:
fmt.Println(v.Content)
case *RawSessionEventData:
// forward-compatible: unknown future event type preserved
}
Generated types that carry stability: "experimental" in the protocol schema now surface language-appropriate markers so callers get compiler warnings when using unstable APIs. (#1267)
[Experimental("GitHub.Copilot.SDK.Experimental")]@experimental JSDoc tag#[doc = "⚠️ Experimental"]@claudiogodoy99 made their first contribution in #863Generated by Release Changelog Generator · ● 302.2K
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, model: auto, id: 25790930825, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/25790930825 -->
Applications can now register callbacks for exitPlanMode.request and autoModeSwitch.request from the Copilot runtime, giving full control over plan-mo
Applications can now register callbacks for exitPlanMode.request and autoModeSwitch.request from the Copilot runtime, giving full control over plan-mode transitions and automatic model switching after rate-limit events. (#1228)
const session = await client.createSession({
onExitPlanMode: async (request) => ({ approved: true }),
onAutoModeSwitch: (request) => "yes",
});
var session = await client.CreateSessionAsync(new SessionConfig
{
OnExitPlanMode = (request, _) => Task.FromResult(new ExitPlanModeResult { Approved = true }),
OnAutoModeSwitch = (request, _) => Task.FromResult(AutoModeSwitchResponse.Yes),
});
on_exit_plan_mode / on_auto_mode_switch kwargs on create_session()ExitPlanModeHandler / AutoModeSwitchHandler fields on SessionConfigThe .NET, Python, and Rust SDKs now emit structured diagnostic logs covering CLI startup, TCP connection, JSON-RPC request timing, session lifecycle, and error paths. (#1217)
var client = new CopilotClient(new CopilotClientOptions
{
Logger = loggerFactory.CreateLogger<CopilotClient>(),
});
Python emits logs via stdlib logging under copilot.* loggers at DEBUG level. Rust uses tracing structured fields; wire up a tracing_subscriber as usual.
enableSessionTelemetry session optionA new enableSessionTelemetry option on SessionConfig and ResumeSessionConfig lets applications explicitly enable or disable the runtime's internal session telemetry. (#1224)
const session = await client.createSession({ enableSessionTelemetry: true });
var session = await client.CreateSessionAsync(new SessionConfig { EnableSessionTelemetry = true });
application/octet-stream when mimeType is absent (#1222)@sunbrye made their first contribution in #1208@cschleiden made their first contribution in #1222@IeuanWalker made their first contribution in #1232Generated by Release Changelog Generator · ● 225.2K
Generated by Release Changelog Generator · ● 1.3M
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, model: auto, id: 25566139290, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/25566139290 -->
We'll also carry out a final round of API reviews and will likely make further breaking changes to streamline naming before it locks down at 1.0.0.
This is the first beta release of the Copilot SDK. The release includes all features we have committed to including in the upcoming General Availability (GA) release.
But note - we're not stopping here! Before GA, we still plan to add more top-requested features, as well as any critical bugfixes. We'll also carry out a final round of API reviews and will likely make further breaking changes to streamline naming before it locks down at 1.0.0.
Highlights of 1.0.0 Beta 1 include custom instruction directories, configurable data directories, TCP connection tokens for headless servers, and a more self-contained .NET distribution (eliminating third-party dependencies).
Sessions can now specify additional directories to search for custom instruction files via the instructionDirectories option on session create and resume config. This lets applications point the CLI at project-specific or team-shared instruction files beyond the default locations. (#1190)
// TypeScript
const session = await client.createSession({
onPermissionRequest: approveAll,
instructionDirectories: [
"/repo/.copilot/instructions",
"/shared/team-instructions",
],
});
// C#
var session = await client.CreateSessionAsync(new() {
OnPermissionRequest = PermissionHandler.ApproveAll,
InstructionDirectories = ["/repo/.copilot/instructions", "/shared/team-instructions"],
});
await client.create_session(on_permission_request=..., instruction_directories=["/repo/.copilot/instructions"])client.CreateSession(ctx, &copilot.SessionConfig{InstructionDirectories: []string{"/repo/.copilot/instructions"}})When the SDK spawns a CLI server in TCP mode, it now auto-generates a connection token to authenticate the handshake — closing the loopback listener to unauthorized connections by default. For applications connecting to an externally managed TCP server that requires a token, the new tcpConnectionToken client option lets you supply it explicitly. (#1176)
// TypeScript
// After starting runtime with env var COPILOT_CONNECTION_TOKEN=<some_uuid>
const client = new CopilotClient({
cliUrl: "localhost:3000",
tcpConnectionToken: "<some_uuid>",
});
// C#
// After starting runtime with env var COPILOT_CONNECTION_TOKEN=<some_uuid>
var client = new CopilotClient(new() {
CliUrl = "localhost:3000",
TcpConnectionToken = "<some_uuid>",
});
CopilotClient(ExternalServerConfig(url="localhost:3000", tcp_connection_token="<some_uuid>"))copilot.NewClient(&copilot.ClientOptions{CLIUrl: "localhost:3000", TCPConnectionToken: "<some_uuid>"})A new copilotHome client option controls where the CLI stores session state, configuration, and other persistent data. This is useful for isolating data across environments, running multiple CLI instances side-by-side, or customizing the storage location for containerized deployments. Defaults to ~/.copilot when not set, and is applicable only when the SDK spawns the CLI process (ignored when connecting to an external server via cliUrl). (#1191).
const client = new CopilotClient({ copilotHome: "/var/data/copilot" });
If you need more control than simply passing a directory path, consider the existing and more advanced SessionFs API. This lets you map all session storage into your own custom storage through callbacks, for example to store data in the cloud or in a database. See Improved SessionFs provider API in the 0.3.0 release - full docs coming soon.
[.NET] Improved NativeAOT and trimming compatibility by replacing the StreamJsonRpc dependency with a custom JSON-RPC implementation, reducing external dependencies and deployment overhead (#1170)
[.NET] Fix AOT serialization for SetForegroundSessionIdAsync() by adding a source-generated request type (#1144)
Schema updates in this release renamed several generated types across all SDKs. If your code references these types by name (via imports or type annotations), you'll need to update:
| Previous | Now |
|---|---|
PermissionCompletedResult |
PermissionResult |
PermissionCompletedKind |
PermissionResultKind |
ToolsHandlePendingToolCallRequest |
HandlePendingToolCallRequest |
HandleToolCallResult |
HandlePendingToolCallResult |
The ToolCallResult type and ToolsHandlePendingToolCall type alias have been removed and replaced by the types above.
Cross-language note: As with previous releases, the same logical renames apply across all four SDKs with language-appropriate casing.
StreamJsonRpc dependency removedThe .NET SDK no longer depends on StreamJsonRpc, having replaced it with a custom JSON-RPC implementation (#1170). If your application was relying on StreamJsonRpc as a transitive dependency from the SDK, you'll need to add a direct reference to your project.
@Encryptoid made their first contribution in #1144[.NET] Deprecated APIs are now annotated with [Obsolete] with descriptive messages.
This release adds new capabilities — per-session authentication, scoped permissions, agent-level tool and skill control, MCP interop utilities, and more — alongside a broad naming cleanup across all four SDK languages. As we close in on a GA release, we've done a deep clean on our naming to bring it closer to the final state, reducing the amount of churn you should expect in subsequent releases. The result is a more consistent, more readable API surface across the board.
Sessions can now carry their own GitHub identity. Different sessions on the same CLI server can have different GitHub users, Copilot plans, and quota limits.
const session = await client.createSession({
onPermissionRequest: approveAll,
gitHubToken: userAToken, // Session-level identity
});
This is independent of the client-level gitHubToken (which authenticates the CLI process itself, and is not required if all sessions bring their own auth). The session-level token determines the identity used for content exclusion, model routing, and quota checks.
A new defaultAgent.excludedTools option lets you hide tools from the default agent while keeping them available to custom sub-agents, enabling the orchestrator pattern where the default agent delegates to specialized sub-agents. (#1098)
Custom agents can now declare skills: string[] to eagerly inject specific skills into their context at startup. Skills are opt-in — agents receive no skills by default, and sub-agents do not inherit skills from the parent. (#995)
When streaming is enabled, assistant.message_delta and assistant.reasoning_delta events are now also delivered for sub-agents. Each event carries an agentId field identifying which sub-agent produced it (absent for the root agent). If your application renders all streaming deltas to the UI, you'll want to filter by agentId (or for pure back-compat, set includeSubAgentStreamingEvents: false on SessionConfig to get the old behavior of only streaming main-agent content updates). (#1108)
A new sessionIdleTimeoutSeconds client option configures automatic session cleanup after inactivity. When set, sessions without activity for the specified duration are cleaned up. Disabled by default (sessions live indefinitely). Previously, sessions would always time out after 30 minutes of idleness - this change fixes that. (#1093)
Provider headers and per-message requestHeaders can now be passed through createSession, resumeSession, and send, enabling custom header forwarding to bring-your-own-key model providers. (#1094)
A new convertMcpCallToolResult() utility function converts MCP CallToolResult objects (with content arrays of text, image, and resource blocks) into the SDK's ToolResultObject format. This makes it easy to use MCP tool servers as backends for SDK tool handlers. (#1049)
ProviderConfig exportedProviderConfig is now re-exported from the Node.js and Python SDK entry points, so consumers no longer need to duplicate the type locally when configuring Responses API providers. (#1048)
Additional low-level RPC methods are now available via session.rpc:
session.rpc.skills.config.setDisabledSkills(), session.rpc.skills.discover()session.rpc.mcp.config.enable(), session.rpc.mcp.config.disable(), session.rpc.mcp.discover(), session.rpc.mcp.oauthLogin()session.rpc.permissions.setApproveAll(), session.rpc.permissions.resetSessionApprovals()session.rpc.instructions.getSources()session.rpc.usage.getMetrics()session.rpc.name.get(), session.rpc.name.set()Permission handlers can now return scoped approvals instead of just one-shot decisions. Two new kind values are available:
"approve-for-session" — Approves a permission for the remainder of the session, with a scoped rule specifying what's approved (commands, read, write, MCP, MCP sampling, memory, or custom tool)."approve-for-location" — Persists an approval to the workspace location, so it applies across future sessions too.The existing approval vocabulary has also been clarified to better describe each outcome:
| Previous | Now |
|---|---|
"approved" |
"approve-once" |
"denied-interactively-by-user" |
"reject" |
"denied-no-approval-rule-and-could-not-request-from-user" |
"user-not-available" |
The "denied-by-rules", "denied-by-content-exclusion-policy", and "denied-by-permission-request-hook" outcomes have been removed from the handler result type — these are now handled server-side and never reach the SDK permission handler.
The built-in approveAll handler has been updated and now returns { kind: "approve-once" }. The PermissionRequest.kind field now also covers "memory" and "hook" permission types in addition to the existing "shell", "write", "mcp", "read", "url", and "custom-tool".
Session events now have individually named types instead of being a single large inline union. In Node.js, the SessionEvent type is still available as a union of all event types, but each event now has a corresponding *Event interface and *Data type that you can import and use directly. Python and .NET received the same treatment — Python now has per-event typed classes, and .NET has dedicated event types with rich typing (long, DateTimeOffset, Guid, TimeSpan, data annotations, etc.).
import type { AssistantMessageData } from "@github/copilot-sdk";
session.onEvent("assistant.message", (event) => {
// event.data is AssistantMessageData — importable and reusable
});
The runtime JSON shape is unchanged — existing event-handling code continues to work.
MCP server configuration types have been renamed to match MCP protocol terminology (#1051):
| Previous | Now |
|---|---|
MCPLocalServerConfig |
MCPStdioServerConfig |
MCPRemoteServerConfig |
MCPHTTPServerConfig (covers both HTTP and SSE transports) |
The type field value correspondingly changes from "local"/"remote" to "stdio"/"http".
The SessionFs API now uses an idiomatic SessionFsProvider interface where methods take plain arguments and signal errors by throwing, instead of the previous RPC-shaped interface with parameter objects and error-result returns. Supply your provider via the createSessionFsHandler callback on SessionConfig:
createSessionFsHandler: (session) => ({
readFile: async (path) => {
return await fs.readFile(path, "utf8"); // throw on error
},
stat: async (path) => {
const s = await fs.stat(path);
return { size: s.size, isDirectory: s.isDirectory(), ... };
},
// ... other methods with plain args, throw on error
})
githubToken/GithubToken casing correctedThe githubToken/GithubToken property on CopilotClientOptions has been corrected to gitHubToken/GitHubToken (capital H) for consistency with GitHub's branding across all SDKs.
Streaming sessions now receive assistant.message_delta and assistant.reasoning_delta events from sub-agents as well as the root agent. If your code renders all deltas without checking the source, sub-agent content will be interleaved with the main agent's output. To handle this, either filter on event.agentId (absent for the root agent) or set includeSubAgentStreamingEvents: false on SessionConfig to suppress sub-agent deltas entirely. (#1108)
supports or limits fields (e.g., embedding models), preventing runtime errors. (cf5694c)integer → long, format: date-time → DateTimeOffset, format: uuid → Guid, format: duration → TimeSpan; data annotations ([Range], [RegularExpression], [Url], etc.). (#1067)[Obsolete] with descriptive messages. (#1099)As we close in on a GA release, we've done a deep clean on type naming across all four SDK languages to bring names closer to their final state. The goal is to reduce churn in subsequent releases — these names are now cleaner, more consistent, and better reflect what each type represents.
The changes follow a few simple rules:
*Params → *Request — parameter types now use the clearer Request suffix.Session prefix dropped — types like SessionAgentSelectParams become AgentSelectRequest. The session context is already clear from the session.rpc.* namespace.SessionSkillsListResult → SkillList, ModelsListResult → ModelList. These read more naturally.{} (void params or results for methods that take/return nothing) have been eliminated.These types appear in the session.rpc.* and client.rpc.* method signatures. If your code references them by name (via imports or TypeScript utility types like Parameters<> / ReturnType<>), you'll need to update. Code that accesses return values structurally without naming the types is unaffected.
Cross-language note: The same logical renames apply across all four SDKs with language-appropriate casing (e.g.,
McpConfigAddRequestin TypeScript/C#,MCPConfigAddRequestin Go/Python,FSvsFs,UIvsUi). The tables below use TypeScript names unless otherwise noted. Go, Python, and .NET had names for additional types that TypeScript left as structural (inline/anonymous) — those extra renames are called out where relevant.
<details> <summary>Params → Request renames (39 renames — all languages)</summary>
| v0.2.2 | v0.3.0 |
|---|---|
McpConfigAddParams |
McpConfigAddRequest |
McpConfigRemoveParams |
McpConfigRemoveRequest |
McpConfigUpdateParams |
McpConfigUpdateRequest |
PingParams |
PingRequest |
SessionAgentSelectParams |
AgentSelectRequest |
SessionCommandsHandlePendingCommandParams |
CommandsHandlePendingCommandRequest |
SessionExtensionsDisableParams |
ExtensionsDisableRequest |
SessionExtensionsEnableParams |
ExtensionsEnableRequest |
SessionFleetStartParams |
FleetStartRequest |
SessionFsAppendFileParams |
SessionFsAppendFileRequest |
SessionFsExistsParams |
SessionFsExistsRequest |
SessionFsMkdirParams |
SessionFsMkdirRequest |
SessionFsReadFileParams |
SessionFsReadFileRequest |
SessionFsReaddirParams |
SessionFsReaddirRequest |
SessionFsReaddirWithTypesParams |
SessionFsReaddirWithTypesRequest |
SessionFsRenameParams |
SessionFsRenameRequest |
SessionFsRmParams |
SessionFsRmRequest |
SessionFsSetProviderParams |
SessionFsSetProviderRequest |
SessionFsStatParams |
SessionFsStatRequest |
SessionFsWriteFileParams |
SessionFsWriteFileRequest |
SessionHistoryTruncateParams |
HistoryTruncateRequest |
SessionLogParams |
LogRequest |
SessionMcpDisableParams |
McpDisableRequest |
SessionMcpEnableParams |
McpEnableRequest |
SessionModeSetParams |
ModeSetRequest |
SessionModelSwitchToParams |
ModelSwitchToRequest |
SessionPermissionsHandlePendingPermissionRequestParams |
PermissionDecisionRequest |
SessionPlanUpdateParams |
PlanUpdateRequest |
SessionShellExecParams |
ShellExecRequest |
SessionShellKillParams |
ShellKillRequest |
SessionSkillsDisableParams |
SkillsDisableRequest |
SessionSkillsEnableParams |
SkillsEnableRequest |
SessionToolsHandlePendingToolCallParams |
ToolsHandlePendingToolCallRequest |
SessionUiElicitationParams |
UIElicitationRequest |
SessionUiHandlePendingElicitationParams |
UIHandlePendingElicitationRequest |
SessionWorkspaceCreateFileParams |
WorkspacesCreateFileRequest |
SessionWorkspaceReadFileParams |
WorkspacesReadFileRequest |
SessionsForkParams |
SessionsForkRequest |
ToolsListParams |
ToolsListRequest |
</details>
<details> <summary>Result / list-result renames (27 renames — all languages)</summary>
| v0.2.2 | v0.3.0 |
|---|---|
McpConfigListResult |
McpConfigList |
ModelsListResult |
ModelList |
SessionAgentGetCurrentResult |
AgentGetCurrentResult |
SessionAgentListResult |
AgentList |
SessionAgentReloadResult |
AgentReloadResult |
SessionAgentSelectResult |
AgentSelectResult |
SessionCommandsHandlePendingCommandResult |
CommandsHandlePendingCommandResult |
SessionExtensionsListResult |
ExtensionList |
SessionFleetStartResult |
FleetStartResult |
SessionHistoryCompactResult |
HistoryCompactResult |
SessionHistoryTruncateResult |
HistoryTruncateResult |
SessionLogResult |
LogResult |
SessionMcpListResult |
McpServerList |
SessionModeGetResult |
SessionMode |
SessionModelGetCurrentResult |
CurrentModel |
SessionModelSwitchToResult |
ModelSwitchToResult |
SessionPermissionsHandlePendingPermissionRequestResult |
PermissionRequestResult |
SessionPlanReadResult |
PlanReadResult |
SessionPluginsListResult |
PluginList |
SessionShellExecResult |
ShellExecResult |
SessionShellKillResult |
ShellKillResult |
SessionSkillsListResult |
SkillList |
SessionToolsHandlePendingToolCallResult |
HandleToolCallResult |
SessionUiElicitationResult |
UIElicitationResult |
SessionWorkspaceListFilesResult |
WorkspacesListFilesResult |
SessionWorkspaceReadFileResult |
WorkspacesReadFileResult |
ToolsListResult |
ToolList |
Go, Python, and .NET had named types for additional void results that TypeScript omitted (structural typing). These were also renamed — e.g.,
SessionModeSetResult→ModeSetResult,SessionPlanUpdateResult→PlanUpdateResult,SessionMcpDisableResult→McpDisableResult, etc. — following the same pattern.
</details>
<details> <summary>Enum and helper type renames (Go, Python, and .NET only)</summary>
TypeScript used inline/literal types for these, so they had no standalone names to rename. Go, Python, and .NET each had named types that have been renamed to be more descriptive and avoid collisions:
Go / Python:
| v0.2.2 | v0.3.0 |
|---|---|
Mode |
SessionMode |
Kind |
PermissionDecisionKind |
Level |
SessionLogLevel |
Signal |
ShellKillSignal |
EntryType |
SessionFSReaddirWithTypesEntryType |
Action |
UIElicitationResponseAction |
Conventions |
SessionFSSetProviderConventions |
Model |
ModelElement |
Billing |
ModelBilling |
Policy |
ModelPolicy |
Skill |
ServerSkill |
Plugin |
PluginElement |
Entry |
SessionFSReaddirWithTypesEntry |
QuotaSnapshot |
AccountQuotaSnapshot |
Source |
MCPServerSource |
ServerElement |
MCPServer |
ServerValue / MCPConfigAddParamsConfig |
MCPServerConfig |
ServerType |
MCPServerConfigType |
ServerStatus |
MCPServerStatus |
| Various UI elicitation sub-types | Prefixed with UIElicitation* |
C# (.NET) — most helper types lived in SessionEvents.cs; only 6 renames in Rpc.cs:
| v0.2.2 | v0.3.0 |
|---|---|
EntryType |
SessionFsReaddirWithTypesEntryType |
SessionFsSetProviderRequestConventions |
SessionFsSetProviderConventions |
SessionLogRequestLevel |
SessionLogLevel |
SessionModeGetResultMode |
SessionMode |
SessionShellKillRequestSignal |
ShellKillSignal |
SessionUiElicitationResultAction |
UIElicitationResponseAction |
</details>
TypeScript didn't have named sub-types for session event data before v0.3.0 (they were inline), and Python's event types were completely restructured rather than renamed. .NET and Go both had deeply-nested named sub-types that have been cleaned up following three patterns:
*Data* infix flattened — e.g., AssistantMessageDataToolRequestsItem → AssistantMessageToolRequestSession prefix dropped — e.g., SessionCompactionCompleteDataCompactionTokensUsed → CompactionCompleteCompactionTokensUsed*Item suffix singularized — e.g., PermissionRequestShellCommandsItem → PermissionRequestShellCommand<details> <summary>Full session event rename table (63 renames — C# names; Go follows the same pattern)</summary>
| v0.2.2 | v0.3.0 |
|---|---|
AssistantMessageDataToolRequestsItem |
AssistantMessageToolRequest |
AssistantMessageDataToolRequestsItemType |
AssistantMessageToolRequestType |
AssistantUsageDataCopilotUsage |
AssistantUsageCopilotUsage |
AssistantUsageDataCopilotUsageTokenDetailsItem |
AssistantUsageCopilotUsageTokenDetail |
CapabilitiesChangedDataUi |
CapabilitiesChangedUI |
CommandsChangedDataCommandsItem |
CommandsChangedCommand |
ElicitationCompletedDataAction |
ElicitationCompletedAction |
ElicitationRequestedDataMode |
ElicitationRequestedMode |
ElicitationRequestedDataRequestedSchema |
ElicitationRequestedSchema |
HookEndDataError |
HookEndError |
McpOauthRequiredDataStaticClientConfig |
McpOauthRequiredStaticClientConfig |
PermissionCompletedDataResult |
PermissionCompletedResult |
PermissionCompletedDataResultKind |
PermissionCompletedKind |
PermissionRequestShellCommandsItem |
PermissionRequestShellCommand |
PermissionRequestShellPossibleUrlsItem |
PermissionRequestShellPossibleUrl |
SessionCompactionCompleteDataCompactionTokensUsed |
CompactionCompleteCompactionTokensUsed |
SessionCustomAgentsUpdatedDataAgentsItem |
CustomAgentsUpdatedAgent |
SessionExtensionsLoadedDataExtensionsItem |
ExtensionsLoadedExtension |
SessionExtensionsLoadedDataExtensionsItemSource |
ExtensionsLoadedExtensionSource |
SessionExtensionsLoadedDataExtensionsItemStatus |
ExtensionsLoadedExtensionStatus |
SessionHandoffDataRepository |
HandoffRepository |
SessionHandoffDataSourceType |
HandoffSourceType |
SessionMcpServersLoadedDataServersItem |
McpServersLoadedServer |
SessionMcpServersLoadedDataServersItemStatus |
McpServersLoadedServerStatus |
SessionPlanChangedDataOperation |
PlanChangedOperation |
SessionResumeDataContext |
WorkingDirectoryContext |
SessionShutdownDataCodeChanges |
ShutdownCodeChanges |
SessionShutdownDataShutdownType |
ShutdownType |
SessionSkillsLoadedDataSkillsItem |
SkillsLoadedSkill |
SessionStartDataContext |
WorkingDirectoryContext |
SessionStartDataContextHostType |
WorkingDirectoryContextHostType |
SessionWorkspaceFileChangedDataOperation |
WorkspaceFileChangedOperation |
SystemMessageDataMetadata |
SystemMessageMetadata |
SystemMessageDataRole |
SystemMessageRole |
SystemNotificationDataKind |
SystemNotification |
SystemNotificationDataKindAgentCompleted |
SystemNotificationAgentCompleted |
SystemNotificationDataKindAgentCompletedStatus |
SystemNotificationAgentCompletedStatus |
SystemNotificationDataKindAgentIdle |
SystemNotificationAgentIdle |
SystemNotificationDataKindShellCompleted |
SystemNotificationShellCompleted |
SystemNotificationDataKindShellDetachedCompleted |
SystemNotificationShellDetachedCompleted |
ToolExecutionCompleteDataError |
ToolExecutionCompleteError |
ToolExecutionCompleteDataResult |
ToolExecutionCompleteResult |
ToolExecutionCompleteDataResultContentsItem |
ToolExecutionCompleteContent |
ToolExecutionCompleteDataResultContentsItemAudio |
ToolExecutionCompleteContentAudio |
ToolExecutionCompleteDataResultContentsItemImage |
ToolExecutionCompleteContentImage |
ToolExecutionCompleteDataResultContentsItemResource |
ToolExecutionCompleteContentResource |
ToolExecutionCompleteDataResultContentsItemResourceLink |
ToolExecutionCompleteContentResourceLink |
ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItem |
ToolExecutionCompleteContentResourceLinkIcon |
ToolExecutionCompleteDataResultContentsItemResourceLinkIconsItemTheme |
ToolExecutionCompleteContentResourceLinkIconTheme |
ToolExecutionCompleteDataResultContentsItemTerminal |
ToolExecutionCompleteContentTerminal |
ToolExecutionCompleteDataResultContentsItemText |
ToolExecutionCompleteContentText |
UserMessageDataAgentMode |
UserMessageAgentMode |
UserMessageDataAttachmentsItem |
UserMessageAttachment |
UserMessageDataAttachmentsItemBlob |
UserMessageAttachmentBlob |
UserMessageDataAttachmentsItemDirectory |
UserMessageAttachmentDirectory |
UserMessageDataAttachmentsItemFile |
UserMessageAttachmentFile |
UserMessageDataAttachmentsItemFileLineRange |
UserMessageAttachmentFileLineRange |
UserMessageDataAttachmentsItemGithubReference |
UserMessageAttachmentGithubReference |
UserMessageDataAttachmentsItemGithubReferenceReferenceType |
UserMessageAttachmentGithubReferenceType |
UserMessageDataAttachmentsItemSelection |
UserMessageAttachmentSelection |
UserMessageDataAttachmentsItemSelectionSelection |
UserMessageAttachmentSelectionDetails |
UserMessageDataAttachmentsItemSelectionSelectionEnd |
UserMessageAttachmentSelectionDetailsEnd |
UserMessageDataAttachmentsItemSelectionSelectionStart |
UserMessageAttachmentSelectionDetailsStart |
Go has ~57 equivalent renames following the same patterns, with minor casing differences to satisfy Go idioms (e.g.,
UIvsUi,FSvsFs).
</details>
<details> <summary>Removed empty types (32 types — Node.js)</summary>
These were empty {} types (void params or results for methods that take/return nothing) and are no longer generated:
SessionAgentDeselectParams, SessionAgentDeselectResult, SessionAgentGetCurrentParams, SessionAgentListParams, SessionAgentReloadParams, SessionExtensionsDisableResult, SessionExtensionsEnableResult, SessionExtensionsListParams, SessionExtensionsReloadParams, SessionExtensionsReloadResult, SessionHistoryCompactParams, SessionMcpDisableResult, SessionMcpEnableResult, SessionMcpListParams, SessionMcpReloadParams, SessionMcpReloadResult, SessionModeGetParams, SessionModeSetResult, SessionModelGetCurrentParams, SessionPlanDeleteParams, SessionPlanDeleteResult, SessionPlanReadParams, SessionPlanUpdateResult, SessionPluginsListParams, SessionSkillsDisableResult, SessionSkillsEnableResult, SessionSkillsListParams, SessionSkillsReloadParams, SessionSkillsReloadResult, SessionUiHandlePendingElicitationResult, SessionWorkspaceCreateFileResult, SessionWorkspaceListFilesParams
Go, Python, and .NET had additional named empty types that were also removed — including void result types like
SessionModeSetResult,SessionPlanUpdateResult,SessionMcpDisableResult,SessionExtensionsDisableResult, etc. that TypeScript never had names for (it used structuralvoidreturns). The same removal pattern applies.
</details>
Nothing published for this version
`autoRestart` removed — The autoRestart option has been deprecated across all SDKs (it was never fully implemented). The property still exists but has…
This is a big update with a broad round of API refinements, new capabilities, and cross-SDK consistency improvements that have shipped incrementally through preview releases since v0.1.32.
A new "customize" mode for systemMessage lets you surgically edit individual sections of the Copilot system prompt — without replacing the entire thing. Ten sections are configurable: identity, tone, tool_efficiency, environment_context, code_change_rules, guidelines, safety, tool_instructions, custom_instructions, and last_instructions.
Each section supports four static actions (replace, remove, append, prepend) and a transform callback that receives the current rendered content and returns modified text — useful for regex mutations, conditional edits, or logging what the prompt contains. (#816)
const session = await client.createSession({
onPermissionRequest: approveAll,
systemMessage: {
mode: "customize",
sections: {
identity: {
action: (current) => current.replace("GitHub Copilot", "Acme Assistant"),
},
tone: { action: "replace", content: "Be concise and professional." },
code_change_rules: { action: "remove" },
},
},
});
var session = await client.CreateSessionAsync(new SessionConfig {
OnPermissionRequest = PermissionHandler.ApproveAll,
SystemMessage = new SystemMessageConfig {
Mode = SystemMessageMode.Customize,
Sections = new Dictionary<string, SectionOverride> {
["identity"] = new() {
Transform = current => Task.FromResult(current.Replace("GitHub Copilot", "Acme Assistant")),
},
["tone"] = new() { Action = SectionOverrideAction.Replace, Content = "Be concise and professional." },
["code_change_rules"] = new() { Action = SectionOverrideAction.Remove },
},
},
});
All four SDK languages now support distributed tracing with the Copilot CLI. Set telemetry in your client options to configure an OTLP exporter; W3C trace context is automatically propagated on session.create, session.resume, and session.send, and restored in tool handlers so tool execution is linked to the originating trace. (#785)
const client = new CopilotClient({
telemetry: {
otlpEndpoint: "http://localhost:4318",
sourceName: "my-app",
},
});
var client = new CopilotClient(new CopilotClientOptions {
Telemetry = new TelemetryConfig {
OtlpEndpoint = "http://localhost:4318",
SourceName = "my-app",
},
});
CopilotClient(SubprocessConfig(telemetry={"otlp_endpoint": "http://localhost:4318", "source_name": "my-app"}))copilot.NewClient(&copilot.ClientOptions{Telemetry: &copilot.TelemetryConfig{OTLPEndpoint: "http://localhost:4318", SourceName: "my-app"}})A new blob attachment type lets you send images or other binary content directly to a session without writing to disk — useful when data is already in memory (screenshots, API responses, generated images). (#731)
await session.send({
prompt: "What's in this image?",
attachments: [{ type: "blob", data: base64Str, mimeType: "image/png" }],
});
await session.SendAsync(new MessageOptions {
Prompt = "What's in this image?",
Attachments = [new UserMessageDataAttachmentsItemBlob { Data = base64Str, MimeType = "image/png" }],
});
You can now specify which custom agent should be active when a session starts, eliminating the need for a separate session.rpc.agent.select() call. (#722)
const session = await client.createSession({
customAgents: [
{ name: "researcher", prompt: "You are a research assistant." },
{ name: "editor", prompt: "You are a code editor." },
],
agent: "researcher",
onPermissionRequest: approveAll,
});
var session = await client.CreateSessionAsync(new SessionConfig {
CustomAgents = [
new CustomAgentConfig { Name = "researcher", Prompt = "You are a research assistant." },
new CustomAgentConfig { Name = "editor", Prompt = "You are a code editor." },
],
Agent = "researcher",
OnPermissionRequest = PermissionHandler.ApproveAll,
});
skipPermission on tool definitions — Tools can now be registered with skipPermission: true to bypass the confirmation prompt for low-risk operations like read-only queries. Available in all four SDKs. (#808)reasoningEffort when switching models — All SDKs now accept an optional reasoningEffort parameter in setModel() for models that support it. (#712)onListModels in client options to override client.listModels() with their own model list. (#730)no-result permission outcome — Permission handlers can now return "no-result" so extensions can attach to sessions without actively answering permission requests. (#802)SessionConfig.onEvent catch-all — A new onEvent handler on session config is registered before the RPC is issued, guaranteeing that early events like session.start are never dropped. (#664)format: "cjs". No changes needed in consumer code. (#546)[Experimental] in C#, /** @experimental */ in TypeScript, and comments in Python and Go. (#875)system.notification events and a session log RPC API. (#737)Client.Start so cancellation no longer kills the child process (#689)DebuggerDisplay attribute to SessionEvent for easier debugging (#726)Task.WhenAny + Task.Delay timeout pattern with .WaitAsync(TimeSpan) (#805)cliPath when cliUrl is already set (#787)We've added low-level RPC methods to control a lot more of what's going on in the session. These are emerging APIs that don't yet have friendly wrappers, and some may be flagged as experimental or subject to change.
session.rpc.skills.list(), .enable(name), .disable(name), .reload()session.rpc.mcp.list(), .enable(name), .disable(name), .reload()session.rpc.extensions.list(), .enable(name), .disable(name), .reload()session.rpc.plugins.list()session.rpc.ui.elicitation(...) — structured user inputsession.rpc.shell.exec(command), .kill(pid)session.log(message, level, ephemeral)In an forthcoming update, we'll add friendlier wrappers for these.
SessionEvent.ToJson() failing for events with JsonElement-backed payloads (assistant.message, tool.execution_start, etc.) (#868)TypeInfoResolver for StreamJsonRpc.RequestId to fix NativeAOT compatibility (#783)autoRestart removed — The autoRestart option has been deprecated across all SDKs (it was never fully implemented). The property still exists but has no effect and will be removed in a future release. Remove any references to autoRestart from your client options. (#803)The Python SDK received a significant API surface overhaul in this release, replacing loosely-typed TypedDict config objects with proper keyword arguments and dataclasses. These changes improve IDE autocompletion, type safety, and readability.
CopilotClient constructor redesigned — The CopilotClientOptions TypedDict has been replaced by two typed config dataclasses. (#793)
# Before (v0.1.x)
client = CopilotClient({"cli_url": "localhost:3000"})
client = CopilotClient({"cli_path": "/usr/bin/copilot", "log_level": "debug"})
# After (v0.2.0)
client = CopilotClient(ExternalServerConfig(url="localhost:3000"))
client = CopilotClient(SubprocessConfig(cli_path="/usr/bin/copilot", log_level="debug"))
create_session() and resume_session() now take keyword arguments instead of a SessionConfig / ResumeSessionConfig TypedDict. on_permission_request is now a required keyword argument. (#587)
# Before
session = await client.create_session({
"on_permission_request": PermissionHandler.approve_all,
"model": "gpt-4.1",
})
# After
session = await client.create_session(
on_permission_request=PermissionHandler.approve_all,
model="gpt-4.1",
)
send() and send_and_wait() take a positional prompt string instead of a MessageOptions TypedDict. Attachments and mode are now keyword arguments. (#814)
# Before
await session.send({"prompt": "Hello!"})
await session.send_and_wait({"prompt": "What is 2+2?"})
# After
await session.send("Hello!")
await session.send_and_wait("What is 2+2?")
MessageOptions, SessionConfig, and ResumeSessionConfig removed from public API — These TypedDicts are no longer exported. Use the new keyword-argument signatures directly. (#587, #814)
Internal modules renamed to private — copilot.jsonrpc, copilot.sdk_protocol_version, and copilot.telemetry are now copilot._jsonrpc, copilot._sdk_protocol_version, and copilot._telemetry. If you were importing from these modules directly, update your imports. (#884)
Typed overloads for CopilotClient.on() — Event registration now uses typed overloads for better autocomplete. This shouldn't break existing code but changes the type signature. (#589)
Client.Start() context no longer kills the CLI process — Previously, canceling the context.Context passed to Start() would terminate the spawned CLI process (it used exec.CommandContext). Now the CLI process lifespan is independent of that context — call client.Stop() or client.ForceStop() to shut it down. (#689)
LogOptions.Ephemeral changed from bool to *bool — This enables proper three-state semantics (unset/true/false). Use copilot.Bool(true) instead of a bare true. (#827)
// Before
session.Log(ctx, copilot.LogOptions{Level: copilot.LevelInfo, Ephemeral: true}, "message")
// After
session.Log(ctx, copilot.LogOptions{Level: copilot.LevelInfo, Ephemeral: copilot.Bool(true)}, "message")
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.32...v0.2.0
SDK applications written against the v3 API now also work when connected to a v2 CLI server, with no code changes required.
SDK applications written against the v3 API now also work when connected to a v2 CLI server, with no code changes required.
Generated by Release Changelog Generator
Generated by Release Changelog Generator
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, id: 22801777640, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/22801777640 -->
SDK applications written against the v3 API now also work when connected to a v2 CLI server, with no code changes required. The SDK detects the server's protocol version and automatically adapts v2 tool.call and permission.request messages into the same user-facing handlers used by v3. (#706)
const session = await client.createSession({
tools: [myTool], // unchanged — works with v2 and v3 servers
onPermissionRequest: approveAll,
});
var session = await client.CreateSessionAsync(new SessionConfig {
Tools = [myTool], // unchanged — works with v2 and v3 servers
OnPermissionRequest = approveAll,
});
Rather than comparing result.Kind against undiscoverable magic strings like "approved" or "denied-interactively-by-user", .NET and Go now provide type
PermissionRequestResultKind for .NET and GoRather than comparing result.Kind against undiscoverable magic strings like "approved" or "denied-interactively-by-user", .NET and Go now provide typed constants. Node and Python already had typed unions for this; this brings full parity. (#631)
session.OnPermissionCompleted += (e) => {
if (e.Result.Kind == PermissionRequestResultKind.Approved) { /* ... */ }
if (e.Result.Kind == PermissionRequestResultKind.DeniedInteractivelyByUser) { /* ... */ }
};
// Go: PermissionKindApproved, PermissionKindDeniedByRules,
// PermissionKindDeniedCouldNotRequestFromUser, PermissionKindDeniedInteractivelyByUser
if result.Kind == copilot.PermissionKindApproved { /* ... */ }
get_last_session_id() / GetLastSessionID() for SDK-wide parity (was already available in Node and .NET) (#671)timeout parameter to generated RPC methods, allowing callers to override the default 30s timeout for long-running operations (#681)PermissionRequest fields are now properly typed (ToolName, Diff, Path, etc.) instead of a generic Extra map[string]any catch-all (#685)Generated by Release Changelog Generator
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, id: 22800112497, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/22800112497 -->
The SDK now uses protocol version 3, where the runtime broadcasts external_tool.requested and permission.requested as session events to all connected clients. This enables multi-client architectures where different clients contribute different tools, or where multiple clients observe the same permission prompts — if one client approves, all clients see the result. Your existing tool and permission handler code is unchanged. (#686)
// Two clients each register different tools; the agent can use both
const session1 = await client1.createSession({
tools: [defineTool("search", { handler: doSearch })],
onPermissionRequest: approveAll,
});
const session2 = await client2.resumeSession(session1.id, {
tools: [defineTool("analyze", { handler: doAnalyze })],
onPermissionRequest: approveAll,
});
var session1 = await client1.CreateSessionAsync(new SessionConfig {
Tools = [AIFunctionFactory.Create(DoSearch, "search")],
OnPermissionRequest = PermissionHandlers.ApproveAll,
});
var session2 = await client2.ResumeSessionAsync(session1.Id, new ResumeSessionConfig {
Tools = [AIFunctionFactory.Create(DoAnalyze, "analyze")],
OnPermissionRequest = PermissionHandlers.ApproveAll,
});
PermissionRequestResultKind for .NET and GoRather than comparing result.Kind against undiscoverable magic strings like "approved" or "denied-interactively-by-user", .NET and Go now provide typed constants. Node and Python already had typed unions for this; this brings full parity. (#631)
session.OnPermissionCompleted += (e) => {
if (e.Result.Kind == PermissionRequestResultKind.Approved) { /* ... */ }
if (e.Result.Kind == PermissionRequestResultKind.DeniedInteractivelyByUser) { /* ... */ }
};
// Go: PermissionKindApproved, PermissionKindDeniedByRules,
// PermissionKindDeniedCouldNotRequestFromUser, PermissionKindDeniedInteractivelyByUser
if result.Kind == copilot.PermissionKindApproved { /* ... */ }
get_last_session_id() / GetLastSessionID() for SDK-wide parity (was already available in Node and .NET) (#671)timeout parameter to generated RPC methods, allowing callers to override the default 30s timeout for long-running operations (#681)PermissionRequest fields are now properly typed (ToolName, Diff, Path, etc.) instead of a generic Extra map[string]any catch-all (#685)Applications can now override built-in tools such as grep, edit_file, or read_file. To do this, register a custom tool with the same name and set the
Applications can now override built-in tools such as grep, edit_file, or read_file. To do this, register a custom tool with the same name and set the override flag. Without the flag, the runtime will return an error if the name clashes with a built-in. (#636)
import { defineTool } from "`@github/copilot-sdk`";
const session = await client.createSession({
tools: [defineTool("grep", {
overridesBuiltInTool: true,
handler: async (params) => `CUSTOM_GREP_RESULT: \$\{params.query}`,
})],
onPermissionRequest: approveAll,
});
var grep = AIFunctionFactory.Create(
([Description("Search query")] string query) => $"CUSTOM_GREP_RESULT: {query}",
"grep",
"Custom grep implementation",
new AIFunctionFactoryOptions
{
AdditionalProperties = new ReadOnlyDictionary(string, object?)(
new Dictionary(string, object?) { ["is_override"] = true })
});
While session.rpc.model.switchTo() already worked, there is now a convenience method directly on the session object. (#621)
await session.setModel("gpt-4.1")await session.SetModelAsync("gpt-4.1")await session.set_model("gpt-4.1")err := session.SetModel(ctx, "gpt-4.1")OnDisposeCall and improve implementation (#626)SemaphoreSlim locks for handler fields (#625)PermissionHandler.approve_all type annotations (#618)@giulio-leone made their first contribution in #618Generated by Release Changelog Generator
Generated by Release Changelog Generator
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, id: 22635190936, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/22635190936 -->
bugfix: [Python] CopilotClient.stop() now raises an ExceptionGroup instead of silently returning a list of exceptions
CopilotClient.stop() now raises an ExceptionGroup instead of silently returning a list of exceptions (#603)Generated by Release Changelog Generator
<!-- gh-aw-agentic-workflow: Release Changelog Generator, engine: copilot, id: 22634115651, workflow_id: release-changelog, run: https://github.com/github/copilot-sdk/actions/runs/22634115651 -->
Breaking change: deny all permissions by default by @SteveSandersonMS in https://github.com/github/copilot-sdk/pull/509
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.25...v0.1.28
Update @github/copilot to 0.0.411-0 by @SteveSandersonMS in https://github.com/github/copilot-sdk/pull/491
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.24...v0.1.25
[go] Use types to encode and decode jsonrpc queries by @qmuntal in https://github.com/github/copilot-sdk/pull/372
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.23...v0.1.24
Bundling by @SteveSandersonMS in https://github.com/github/copilot-sdk/pull/382
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.22...v0.1.23
Bump githubnext/gh-aw from 0.38.2 to 0.39.4 by @dependabot[bot] in https://github.com/github/copilot-sdk/pull/322
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.21...v0.1.22
Set default vscode formatter for Go by @qmuntal in https://github.com/github/copilot-sdk/pull/295
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.20...v0.1.21
Fixes #227 - Premium requests consumed while running py dev test by @vivganes in https://github.com/github/copilot-sdk/pull/228
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.19...v0.1.20
Fix BYOK FAQ: clarify it refers to API keys, not encryption keys by @mohamedaminehamdi in https://github.com/github/copilot-sdk/pull/174
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.18...v0.1.19
feat: Infinite Sessions by @jmoseley in https://github.com/github/copilot-sdk/pull/76
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.17...v0.1.18
Modify npm init command for module type by @sinedied in https://github.com/github/copilot-sdk/pull/132
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.16...v0.1.17
Adding FAQ section to the README by @aaronpowell in https://github.com/github/copilot-sdk/pull/86
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.15...v0.1.16
Add Go submodule version tags for reproducible builds by @Copilot in https://github.com/github/copilot-sdk/pull/33
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.13...v0.1.16-preview.0
Update @github/copilot to 0.0.387 by @devm33 in https://github.com/github/copilot-sdk/pull/54
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.14...v0.1.15
Add Go submodule version tags for reproducible builds by @Copilot in https://github.com/github/copilot-sdk/pull/33
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.13...v0.1.14
Fix the event subscription in dotnet by @showpune in https://github.com/github/copilot-sdk/pull/11
@github/copilot to latest by @devm33 in https://github.com/github/copilot-sdk/pull/20Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.12...v0.1.13
Fix the event subscription in dotnet by @showpune in https://github.com/github/copilot-sdk/pull/11
Full Changelog: https://github.com/github/copilot-sdk/compare/v0.1.12...v0.1.13-preview.0
One column per month.