Merge remote-tracking branch 'upstream/main' into otel-genai-convention-fixes

# Conflicts:
#	go/session.go
#	python/copilot/session.py

Author: stephentoub

.github/aw/actions-lock.json

@@ -0,0 +1,29 @@
+{
+  "entries": {
+    "actions/checkout@v6.0.2": {
+      "repo": "actions/checkout",
+      "version": "v6.0.2",
+      "sha": "de0fac2e4500dabe0009e67214ff5f5447ce83dd"
+    },
+    "actions/download-artifact@v8.0.0": {
+      "repo": "actions/download-artifact",
+      "version": "v8.0.0",
+      "sha": "70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3"
+    },
+    "actions/github-script@v8": {
+      "repo": "actions/github-script",
+      "version": "v8",
+      "sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd"
+    },
+    "actions/upload-artifact@v7.0.0": {
+      "repo": "actions/upload-artifact",
+      "version": "v7.0.0",
+      "sha": "bbbca2ddaa5d8feaa63e36b76fdaad77386f024f"
+    },
+    "github/gh-aw/actions/setup@v0.52.1": {
+      "repo": "github/gh-aw/actions/setup",
+      "version": "v0.52.1",
+      "sha": "a86e657586e4ac5f549a790628971ec02f6a4a8f"
+    }
+  }
+}

.github/workflows/publish.yml

@@ -22,6 +22,7 @@ on:
 permissions:
   contents: write
   id-token: write # Required for OIDC
+  actions: write # Required to trigger changelog workflow
 
 concurrency:
   group: publish
@@ -213,6 +214,10 @@ jobs:
             --target ${{ github.sha }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Trigger changelog generation
+        run: gh workflow run release-changelog.lock.yml -f tag="v${{ needs.version.outputs.version }}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Tag Go SDK submodule
         if: github.event.inputs.dist-tag == 'latest' || github.event.inputs.dist-tag == 'prerelease'
         run: |

.github/workflows/release-changelog.lock.yml

@@ -0,0 +1,169 @@
+---
+description: Generates release notes from merged PRs/commits. Triggered by the publish workflow or manually via workflow_dispatch.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to generate changelog for (e.g., v0.1.30)"
+        required: true
+        type: string
+permissions:
+  contents: read
+  actions: read
+  issues: read
+  pull-requests: read
+tools:
+  github:
+    toolsets: [default]
+  edit:
+safe-outputs:
+  create-pull-request:
+    title-prefix: "[changelog] "
+    labels: [automation, changelog]
+    draft: false
+  update-release:
+    max: 1
+timeout-minutes: 15
+---
+
+# Release Changelog Generator
+
+You are an AI agent that generates well-formatted release notes when a release of the Copilot SDK is published.
+
+- **For stable releases** (tag has no prerelease suffix like `-preview`): update `CHANGELOG.md` via a PR AND update the GitHub Release notes.
+- **For prerelease releases** (tag contains `-preview` or similar suffix): update the GitHub Release notes ONLY. Do NOT modify `CHANGELOG.md` or create a PR.
+
+Determine which type of release this is by inspecting the tag or fetching the release metadata.
+
+## Context
+
+- Repository: ${{ github.repository }}
+- Release tag: ${{ github.event.inputs.tag }}
+
+Use the GitHub API to fetch the release corresponding to `${{ github.event.inputs.tag }}` to get its name, publish date, prerelease status, and other metadata.
+
+## Your Task
+
+### Step 1: Identify the version range
+
+1. The **new version** is the release tag: `${{ github.event.inputs.tag }}`
+2. Fetch the release metadata to determine if this is a **stable** or **prerelease** release.
+3. Determine the **previous version** to diff against:
+   - **For stable releases**: find the previous **stable** release (skip prereleases). Check `CHANGELOG.md` for the most recent version heading (`## [vX.Y.Z](...)`), or fall back to listing releases via the API. This means stable changelogs include ALL changes since the last stable release, even if some were already mentioned in prerelease notes.
+   - **For prerelease releases**: find the most recent release of **any kind** (stable or prerelease) that precedes this one. This way prerelease notes only cover what's new since the last release.
+4. If no previous release exists at all, use the first commit in the repo as the starting point.
+
+### Step 2: Gather changes
+
+1. Use the GitHub tools to list commits between the last documented tag (from Step 1) and the new release tag.
+2. Also list merged pull requests in that range. For each PR, note:
+   - PR number and title
+   - The PR author
+   - Which SDK(s) were affected (look for prefixes like `[C#]`, `[Python]`, `[Go]`, `[Node]` in the title, or infer from changed files)
+3. Ignore:
+   - Dependabot/bot PRs that only bump internal dependencies (like `Update @github/copilot to ...`) unless they bring user-facing changes
+   - Merge commits with no meaningful content
+   - Preview/prerelease-only changes that were already documented
+
+### Step 3: Categorize and write up
+
+Separate the changes into two groups:
+
+1. **Highlighted features**: Any interesting new feature or significant improvement that deserves its own section with a description and code snippet(s). Read the PR diff and source code to understand the feature well enough to write about it.
+2. **Other changes**: Bug fixes, minor improvements, and smaller features that can be summarized in a single bullet each.
+
+Only include changes that are **user-visible in the published SDK packages**. Skip anything that only affects docs, CI, build tooling, GitHub workflows, test infrastructure, or other internal-only concerns.
+
+Additionally, identify **new contributors** — anyone whose first merged PR to this repo falls within this release range. You can determine this by checking whether the author has any earlier merged PRs in the repository.
+
+### Step 4: Update CHANGELOG.md (stable releases only)
+
+**Skip this step entirely for prerelease releases.**
+
+1. Read the current `CHANGELOG.md` file.
+2. Add the new version entry **at the top** of the file, right after the title/header.
+
+**Format for each highlighted feature** — use an `### Feature:` or `### Fix:` heading, a 1-2 sentence description explaining what it does and why it matters, and at least one short code snippet (max 3 lines). Focus on **TypeScript** and **C#** as the primary languages. Only show Go/Python when giving a list of one-liner equivalents across all languages, or when their usage pattern is meaningfully different.
+
+**Format for other changes** — a single `### Other changes` section with a flat bulleted list. Each bullet has a lowercase prefix (`feature:`, `bugfix:`, `improvement:`) and a one-line description linking to the PR. **However, if there are no highlighted features above it, omit the `### Other changes` heading entirely** — just list the bullets directly under the version heading.
+
+3. Use the release's publish date (from the GitHub Release metadata), not today's date. For `workflow_dispatch` runs, fetch the release by tag to get the date.
+4. If there are new contributors, add a `### New contributors` section at the end listing each with a link to their first PR:
+   ```
+   ### New contributors
+   - @username made their first contribution in [#123](https://github.com/github/copilot-sdk/pull/123)
+   ```
+   Omit this section if there are no new contributors.
+5. Make sure the existing content below is preserved exactly as-is.
+
+### Step 5: Create a Pull Request (stable releases only)
+
+**Skip this step entirely for prerelease releases.**
+
+Use the `create-pull-request` output to submit your changes. The PR should:
+- Have a clear title like "Add changelog for vX.Y.Z"
+- Include a brief body summarizing the number of changes
+
+### Step 6: Update the GitHub Release
+
+Use the `update-release` output to replace the auto-generated release notes with your nicely formatted changelog. **Do not include the version heading** (`## [vX.Y.Z](...) (date)`) in the release notes — the release already has a title showing the version. Start directly with the feature sections or other changes list.
+
+## Example Output
+
+Here is an example of what a changelog entry should look like, based on real commits from this repo. **Follow this style exactly.**
+
+````markdown
+## [v0.1.28](https://github.com/github/copilot-sdk/releases/tag/v0.1.28) (2026-02-14)
+
+### Feature: support overriding built-in tools
+
+Applications can now override built-in tools such as `edit` or `grep`. To do this, register a custom tool with the same name and set the override flag. ([#636](https://github.com/github/copilot-sdk/pull/636))
+
+```ts
+session.defineTool("edit", { isOverride: true }, async (params) => {
+  // custom edit implementation
+});
+```
+
+```cs
+session.DefineTool("edit", new ToolOptions { IsOverride = true }, async (params) => {
+    // custom edit implementation
+});
+```
+
+### Feature: simpler API for changing model mid-session
+
+While `session.rpc.models.setModel()` already worked, there is now a convenience method directly on the session object. ([#621](https://github.com/github/copilot-sdk/pull/621))
+
+- TypeScript: `session.setModel("gpt-4o")`
+- C#: `session.SetModel("gpt-4o")`
+- Python: `session.set_model("gpt-4o")`
+- Go: `session.SetModel("gpt-4o")`
+
+### Other changes
+
+- bugfix: **[Python]** correct `PermissionHandler.approve_all` type annotations ([#618](https://github.com/github/copilot-sdk/pull/618))
+- improvement: **[C#]** use event delegate for thread-safe, insertion-ordered event handler dispatch ([#624](https://github.com/github/copilot-sdk/pull/624))
+- improvement: **[C#]** deduplicate `OnDisposeCall` and improve implementation ([#626](https://github.com/github/copilot-sdk/pull/626))
+- improvement: **[C#]** remove unnecessary `SemaphoreSlim` locks for handler fields ([#625](https://github.com/github/copilot-sdk/pull/625))
+
+### New contributors
+
+- @chlowell made their first contribution in [#586](https://github.com/github/copilot-sdk/pull/586)
+- @feici02 made their first contribution in [#566](https://github.com/github/copilot-sdk/pull/566)
+````
+
+**Key rules visible in the example:**
+- Highlighted features get their own `### Feature:` heading, a short description, and code snippets
+- Code snippets are TypeScript and C# primarily; Go/Python only when listing one-liner equivalents or when meaningfully different
+- The `### Other changes` section is a flat bulleted list with lowercase `bugfix:` / `feature:` / `improvement:` prefixes
+- PR numbers are linked inline, not at the end with author attribution (keep it clean)
+
+## Guidelines
+
+1. **Be concise**: Each bullet should be one short sentence. Don't over-explain.
+2. **Be accurate**: Only include changes that actually landed in this release range. Don't hallucinate PRs.
+3. **Attribute correctly**: Always link to the PR number. Do not add explicit author attribution.
+4. **Skip noise**: Don't include trivial changes (typo fixes in comments, whitespace changes) unless they're the only changes.
+5. **Preserve history**: Never modify existing entries in CHANGELOG.md — only prepend new ones.
+6. **Handle edge cases**: If there are no meaningful changes (e.g., only internal dependency bumps), still create an entry noting "Internal dependency updates only" or similar.

.github/workflows/release-changelog.md

@@ -0,0 +1,56 @@
+# Changelog
+
+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.30](https://github.com/github/copilot-sdk/releases/tag/v0.1.30) (2026-03-03)
+
+### Feature: support overriding built-in tools
+
+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](https://github.com/github/copilot-sdk/pull/636))
+
+```ts
+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,
+});
+```
+
+```cs
+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 })
+    });
+```
+
+### Feature: simpler API for changing model mid-session
+
+While `session.rpc.model.switchTo()` already worked, there is now a convenience method directly on the session object. ([#621](https://github.com/github/copilot-sdk/pull/621))
+
+- TypeScript: `await session.setModel("gpt-4.1")`
+- C#: `await session.SetModelAsync("gpt-4.1")`
+- Python: `await session.set_model("gpt-4.1")`
+- Go: `err := session.SetModel(ctx, "gpt-4.1")`
+
+### Other changes
+
+- improvement: **[C#]** use event delegate for thread-safe, insertion-ordered event handler dispatch ([#624](https://github.com/github/copilot-sdk/pull/624))
+- improvement: **[C#]** deduplicate `OnDisposeCall` and improve implementation ([#626](https://github.com/github/copilot-sdk/pull/626))
+- improvement: **[C#]** remove unnecessary `SemaphoreSlim` locks for handler fields ([#625](https://github.com/github/copilot-sdk/pull/625))
+- bugfix: **[Python]** correct `PermissionHandler.approve_all` type annotations ([#618](https://github.com/github/copilot-sdk/pull/618))
+
+### New contributors
+
+- @giulio-leone made their first contribution in [#618](https://github.com/github/copilot-sdk/pull/618)

CHANGELOG.md

@@ -418,6 +418,30 @@ var session = await client.CreateSessionAsync(new SessionConfig
 
 When Copilot invokes `lookup_issue`, the client automatically runs your handler and responds to the CLI. Handlers can return any JSON-serializable value (automatically wrapped), or a `ToolResultAIContent` wrapping a `ToolResultObject` for full control over result metadata.
 
+#### Overriding Built-in Tools
+
+If you register a tool with the same name as a built-in CLI tool (e.g. `edit_file`, `read_file`), the runtime will return an error unless you explicitly opt in by setting `is_override` in the tool's `AdditionalProperties`. This flag signals that you intend to replace the built-in tool with your custom implementation.
+
+```csharp
+var editFile = AIFunctionFactory.Create(
+    async ([Description("File path")] string path, [Description("New content")] string content) => {
+        // your logic
+    },
+    "edit_file",
+    "Custom file editor with project-specific validation",
+    new AIFunctionFactoryOptions
+    {
+        AdditionalProperties = new ReadOnlyDictionary<string, object?>(
+            new Dictionary<string, object?> { ["is_override"] = true })
+    });
+
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    Model = "gpt-5",
+    Tools = [editFile],
+});
+```
+
 ### System Message Customization
 
 Control the system prompt using `SystemMessage` in session config:

dotnet/README.md

@@ -1451,10 +1451,15 @@ internal record CreateSessionRequest(
     internal record ToolDefinition(
         string Name,
         string? Description,
-        JsonElement Parameters /* JSON schema */)
+        JsonElement Parameters, /* JSON schema */
+        bool? OverridesBuiltInTool = null)
     {
         public static ToolDefinition FromAIFunction(AIFunction function)
-            => new ToolDefinition(function.Name, function.Description, function.JsonSchema);
+        {
+            var overrides = function.AdditionalProperties.TryGetValue("is_override", out var val) && val is true;
+            return new ToolDefinition(function.Name, function.Description, function.JsonSchema,
+                overrides ? true : null);
+        }
     }
 
     internal record CreateSessionResponse(

dotnet/src/Client.cs

@@ -556,6 +556,22 @@ await InvokeRpcAsync<object>(
             "session.abort", [new SessionAbortRequest { SessionId = SessionId }], cancellationToken);
     }
 
+    /// <summary>
+    /// Changes the model for this session.
+    /// The new model takes effect for the next message. Conversation history is preserved.
+    /// </summary>
+    /// <param name="model">Model ID to switch to (e.g., "gpt-4.1").</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <example>
+    /// <code>
+    /// await session.SetModelAsync("gpt-4.1");
+    /// </code>
+    /// </example>
+    public async Task SetModelAsync(string model, CancellationToken cancellationToken = default)
+    {
+        await Rpc.Model.SwitchToAsync(model, cancellationToken);
+    }
+
     /// <summary>
     /// Disposes the <see cref="CopilotSession"/> and releases all associated resources.
     /// </summary>

dotnet/src/Session.cs

@@ -837,6 +837,7 @@ protected SessionConfig(SessionConfig? other)
     public string? ConfigDir { get; set; }
 
     public ICollection<AIFunction>? Tools { get; set; }
+
     public SystemMessageConfig? SystemMessage { get; set; }
     public List<string>? AvailableTools { get; set; }
     public List<string>? ExcludedTools { get; set; }

dotnet/src/Types.cs

@@ -441,4 +441,19 @@ public async Task Should_Create_Session_With_Custom_Config_Dir()
         Assert.NotNull(assistantMessage);
         Assert.Contains("2", assistantMessage!.Data.Content);
     }
+
+    [Fact]
+    public async Task Should_Set_Model_On_Existing_Session()
+    {
+        var session = await CreateSessionAsync();
+
+        // Subscribe for the model change event before calling SetModelAsync
+        var modelChangedTask = TestHelper.GetNextEventOfTypeAsync<SessionModelChangeEvent>(session);
+
+        await session.SetModelAsync("gpt-4.1");
+
+        // Verify a model_change event was emitted with the new model
+        var modelChanged = await modelChangedTask;
+        Assert.Equal("gpt-4.1", modelChanged.Data.NewModel);
+    }
 }