Merge branch 'main' into dev/qmuntal/ctxlife

Author: qmuntal

.github/agents/docs-maintenance.agent.md

@@ -344,7 +344,7 @@ cat nodejs/src/types.ts | grep -A 10 "export interface ExportSessionOptions"
 **Must match:**
 - `CopilotClient` constructor options: `cliPath`, `cliUrl`, `useStdio`, `port`, `logLevel`, `autoStart`, `autoRestart`, `env`, `githubToken`, `useLoggedInUser`
 - `createSession()` config: `model`, `tools`, `hooks`, `systemMessage`, `mcpServers`, `availableTools`, `excludedTools`, `streaming`, `reasoningEffort`, `provider`, `infiniteSessions`, `customAgents`, `workingDirectory`
-- `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `destroy()`, `abort()`, `on()`, `once()`, `off()`
+- `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `disconnect()`, `abort()`, `on()`, `once()`, `off()`
 - Hook names: `onPreToolUse`, `onPostToolUse`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`, `onErrorOccurred`
 
 #### Python Validation
@@ -362,7 +362,7 @@ cat python/copilot/types.py | grep -A 15 "class SessionHooks"
 **Must match (snake_case):**
 - `CopilotClient` options: `cli_path`, `cli_url`, `use_stdio`, `port`, `log_level`, `auto_start`, `auto_restart`, `env`, `github_token`, `use_logged_in_user`
 - `create_session()` config keys: `model`, `tools`, `hooks`, `system_message`, `mcp_servers`, `available_tools`, `excluded_tools`, `streaming`, `reasoning_effort`, `provider`, `infinite_sessions`, `custom_agents`, `working_directory`
-- `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `destroy()`, `abort()`, `export_session()`
+- `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `disconnect()`, `abort()`, `export_session()`
 - Hook names: `on_pre_tool_use`, `on_post_tool_use`, `on_user_prompt_submitted`, `on_session_start`, `on_session_end`, `on_error_occurred`
 
 #### Go Validation
@@ -380,7 +380,7 @@ cat go/types.go | grep -A 15 "type SessionHooks struct"
 **Must match (PascalCase for exported):**
 - `ClientOptions` fields: `CLIPath`, `CLIUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `AutoRestart`, `Env`, `GithubToken`, `UseLoggedInUser`
 - `SessionConfig` fields: `Model`, `Tools`, `Hooks`, `SystemMessage`, `MCPServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
-- `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Destroy()`, `Abort()`, `ExportSession()`
+- `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Disconnect()`, `Abort()`, `ExportSession()`
 - Hook fields: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
 
 #### .NET Validation

.github/workflows/cross-repo-issue-analysis.md

@@ -1,5 +1,5 @@
 ---
-description: Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue and suggested-fix PR there
+description: Analyzes copilot-sdk issues to determine if a fix is needed in copilot-agent-runtime, then opens a linked issue there
 on:
   issues:
     types: [labeled]
@@ -13,15 +13,13 @@ if: "github.event_name == 'workflow_dispatch' || github.event.label.name == 'run
 permissions:
   contents: read
   issues: read
-  pull-requests: read
 steps:
   - name: Clone copilot-agent-runtime
     run: git clone --depth 1 https://x-access-token:${{ secrets.RUNTIME_TRIAGE_TOKEN }}@github.com/github/copilot-agent-runtime.git ${{ github.workspace }}/copilot-agent-runtime
 tools:
   github:
     toolsets: [default]
     github-token: ${{ secrets.RUNTIME_TRIAGE_TOKEN }}
-  edit:
   bash:
     - "grep:*"
     - "find:*"
@@ -42,12 +40,6 @@ safe-outputs:
     labels: [upstream-from-sdk, ai-triaged]
     target-repo: "github/copilot-agent-runtime"
     max: 1
-  create-pull-request:
-    title-prefix: "[copilot-sdk] "
-    labels: [upstream-from-sdk, ai-suggested-fix]
-    draft: true
-    target-repo: "github/copilot-agent-runtime"
-
 timeout-minutes: 20
 ---
 
@@ -106,18 +98,13 @@ Classify the issue into one of these categories:
      - References the original SDK issue (e.g., `github/copilot-sdk#123`)
      - Includes the specific files and code paths involved
      - Suggests a fix approach
-   - Create a draft PR in `github/copilot-agent-runtime` with a suggested fix:
-     - Make the minimal, targeted code changes needed
-     - Include a clear PR description linking back to both issues
-     - If you're uncertain about the fix, still create the PR as a starting point for discussion
 
 3. **Needs-investigation**: You cannot confidently determine the root cause. Label the issue `needs-investigation`.
 
 ## Guidelines
 
 1. **Be thorough but focused**: Read enough code to be confident in your analysis, but don't read every file in both repos
 2. **Err on the side of creating the runtime issue**: If there's a reasonable chance the fix is in the runtime, create the issue. False positives are better than missed upstream bugs.
-3. **Make actionable PRs**: Even if the fix isn't perfect, a draft PR with a concrete starting point is more useful than just an issue description
-4. **Link everything**: Always cross-reference between the SDK issue, runtime issue, and runtime PR so maintainers can follow the trail
-5. **Be specific**: When describing the root cause, point to specific files, functions, and line numbers in both repos
-6. **Don't duplicate**: Before creating a runtime issue, search existing open issues in `github/copilot-agent-runtime` to avoid duplicates. If a related issue exists, reference it instead of creating a new one.
+3. **Link everything**: Always cross-reference between the SDK issue and runtime issue so maintainers can follow the trail
+4. **Be specific**: When describing the root cause, point to specific files, functions, and line numbers in both repos
+5. **Don't duplicate**: Before creating a runtime issue, search existing open issues in `github/copilot-agent-runtime` to avoid duplicates. If a related issue exists, reference it instead of creating a new one.

.github/workflows/publish.yml

@@ -14,6 +14,7 @@ on:
         options:
           - latest
           - prerelease
+          - unstable
       version:
         description: "Version override (optional, e.g., 1.0.0). If empty, auto-increments."
         type: string
@@ -66,8 +67,8 @@ jobs:
               fi
             else
               if [[ "$VERSION" != *-* ]]; then
-                echo "❌ Error: Version '$VERSION' has no prerelease suffix but dist-tag is 'prerelease'" >> $GITHUB_STEP_SUMMARY
-                echo "Use a version with suffix (e.g., '1.0.0-preview.0') for prerelease"
+                echo "❌ Error: Version '$VERSION' has no prerelease suffix but dist-tag is '${{ github.event.inputs.dist-tag }}'" >> $GITHUB_STEP_SUMMARY
+                echo "Use a version with suffix (e.g., '1.0.0-preview.0') for prerelease/unstable"
                 exit 1
               fi
             fi
@@ -107,11 +108,12 @@ jobs:
           name: nodejs-package
           path: nodejs/*.tgz
       - name: Publish to npm
-        if: github.ref == 'refs/heads/main'
+        if: github.ref == 'refs/heads/main' || github.event.inputs.dist-tag == 'unstable'
         run: npm publish --tag ${{ github.event.inputs.dist-tag }} --access public --registry https://registry.npmjs.org
 
   publish-dotnet:
     name: Publish .NET SDK
+    if: github.event.inputs.dist-tag != 'unstable'
     needs: version
     runs-on: ubuntu-latest
     defaults:
@@ -147,6 +149,7 @@ jobs:
 
   publish-python:
     name: Publish Python SDK
+    if: github.event.inputs.dist-tag != 'unstable'
     needs: version
     runs-on: ubuntu-latest
     defaults:
@@ -183,7 +186,7 @@ jobs:
   github-release:
     name: Create GitHub Release
     needs: [version, publish-nodejs, publish-dotnet, publish-python]
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/main' && github.event.inputs.dist-tag != 'unstable'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6.0.2

CHANGELOG.md

@@ -5,6 +5,78 @@ All notable changes to the Copilot SDK are documented in this file.
 This changelog is automatically generated by an AI agent when stable releases are published.
 See [GitHub Releases](https://github.com/github/copilot-sdk/releases) for the full list.
 
+## [v0.1.32](https://github.com/github/copilot-sdk/releases/tag/v0.1.32) (2026-03-07)
+
+### Feature: backward compatibility with v2 CLI servers
+
+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](https://github.com/github/copilot-sdk/pull/706))
+
+```ts
+const session = await client.createSession({
+  tools: [myTool],           // unchanged — works with v2 and v3 servers
+  onPermissionRequest: approveAll,
+});
+```
+
+```cs
+var session = await client.CreateSessionAsync(new SessionConfig {
+    Tools = [myTool],          // unchanged — works with v2 and v3 servers
+    OnPermissionRequest = approveAll,
+});
+```
+
+## [v0.1.31](https://github.com/github/copilot-sdk/releases/tag/v0.1.31) (2026-03-07)
+
+### Feature: multi-client tool and permission broadcasts (protocol v3)
+
+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](https://github.com/github/copilot-sdk/pull/686))
+
+```ts
+// 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,
+});
+```
+
+```cs
+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,
+});
+```
+
+### Feature: strongly-typed `PermissionRequestResultKind` for .NET and Go
+
+Rather 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](https://github.com/github/copilot-sdk/pull/631))
+
+```cs
+session.OnPermissionCompleted += (e) => {
+    if (e.Result.Kind == PermissionRequestResultKind.Approved) { /* ... */ }
+    if (e.Result.Kind == PermissionRequestResultKind.DeniedInteractivelyByUser) { /* ... */ }
+};
+```
+
+```go
+// Go: PermissionKindApproved, PermissionKindDeniedByRules,
+//     PermissionKindDeniedCouldNotRequestFromUser, PermissionKindDeniedInteractivelyByUser
+if result.Kind == copilot.PermissionKindApproved { /* ... */ }
+```
+
+### Other changes
+
+- feature: **[Python]** **[Go]** add `get_last_session_id()` / `GetLastSessionID()` for SDK-wide parity (was already available in Node and .NET) ([#671](https://github.com/github/copilot-sdk/pull/671))
+- improvement: **[Python]** add `timeout` parameter to generated RPC methods, allowing callers to override the default 30s timeout for long-running operations ([#681](https://github.com/github/copilot-sdk/pull/681))
+- bugfix: **[Go]** `PermissionRequest` fields are now properly typed (`ToolName`, `Diff`, `Path`, etc.) instead of a generic `Extra map[string]any` catch-all ([#685](https://github.com/github/copilot-sdk/pull/685))
+
 ## [v0.1.30](https://github.com/github/copilot-sdk/releases/tag/v0.1.30) (2026-03-03)
 
 ### Feature: support overriding built-in tools

README.md

@@ -91,7 +91,12 @@ Yes, the GitHub Copilot SDK allows you to define custom agents, skills, and tool
 
 ### Are there instructions for Copilot to speed up development with the SDK?
 
-Yes, check out the custom instructions at [`github/awesome-copilot`](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md).
+Yes, check out the custom instructions for each SDK:
+
+- **[Node.js / TypeScript](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-nodejs.instructions.md)**
+- **[Python](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-python.instructions.md)**
+- **[.NET](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-csharp.instructions.md)**
+- **[Go](https://github.com/github/awesome-copilot/blob/main/instructions/copilot-sdk-go.instructions.md)**
 
 ### What models are supported?
 
@@ -107,8 +112,12 @@ Please use the [GitHub Issues](https://github.com/github/copilot-sdk/issues) pag
 
 ## Quick Links
 
+- **[Documentation](./docs/index.md)** – Full documentation index
 - **[Getting Started](./docs/getting-started.md)** – Tutorial to get up and running
+- **[Setup Guides](./docs/setup/index.md)** – Architecture, deployment, and scaling
 - **[Authentication](./docs/auth/index.md)** – GitHub OAuth, BYOK, and more
+- **[Features](./docs/features/index.md)** – Hooks, custom agents, MCP, skills, and more
+- **[Troubleshooting](./docs/troubleshooting/debugging.md)** – Common issues and solutions
 - **[Cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk)** – Practical recipes for common tasks across all languages
 - **[More Resources](https://github.com/github/awesome-copilot/blob/main/collections/copilot-sdk.md)** – Additional examples, tutorials, and community resources