[pull] main from github:main

.github/instructions/instruction-architecture.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: ".github/instructions/**,.github/agents/**"
+---
+
+# Editing Copilot content instruction and agent files
+
+This applies when you add, edit, or remove a Copilot instruction or shared agent file that guides how **content** (articles, data files) is written. It does **not** apply to code instructions or agents owned by the engineering team (for example `code.instructions.md`).
+
+When it applies, you **must** first read the instruction-architecture doc in full and follow it:
+
+https://github.com/github/docs-team/blob/main/contributing-to-docs/docs-work/copilot-instruction-architecture.md
+
+Read the current version every time (from a local `github/docs-team` checkout if you have one, otherwise fetch the URL); do not rely on your memory of it, because it changes. If you cannot access it, say so and stop rather than guessing.

content/copilot/how-tos/copilot-sdk/auth/authenticate.md

@@ -23,7 +23,7 @@ contentType: how-tos
 | [GitHub Signed-in User](#github-signed-in-user) | Interactive apps where users sign in with GitHub | Yes |
 | [OAuth GitHub App](#oauth-github-app) | Apps acting on behalf of users via OAuth | Yes |
 | [Environment Variables](#environment-variables) | CI/CD, automation, server-to-server | Yes |
-| [AUTOTITLE](/copilot/how-tos/copilot-sdk/auth/byok) | Using your own API keys (Azure AI Foundry, OpenAI, etc.) | No |
+| [AUTOTITLE](/copilot/how-tos/copilot-sdk/auth/byok) | Using your own API keys (Azure AI Foundry, OpenAI, and more) | No |
 
 ## GitHub signed-in user
 
@@ -216,7 +216,7 @@ client.start().get();
 
 **Supported token types:**
 * `gho_` - OAuth user access tokens
-* `ghu_` - GitHub App user access tokens  
+* `ghu_` - GitHub App user access tokens
 * `github_pat_` - Fine-grained personal access tokens
 
 **Not supported:**
@@ -269,7 +269,7 @@ await client.start()
 {% endcodetabs %}
 
 **When to use:**
-* CI/CD pipelines (GitHub Actions, Jenkins, etc.)
+* CI/CD pipelines (GitHub Actions, Jenkins, and more)
 * Automated testing
 * Server-side applications with service accounts
 * Development when you don't want to use interactive login

content/copilot/how-tos/copilot-sdk/auth/byok.md

@@ -41,7 +41,7 @@ import os
 from copilot import CopilotClient
 from copilot.session import PermissionHandler
 
-FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/"
+FOUNDRY_MODEL_URL = "https://<resource-name>.openai.azure.com/openai/v1/"
 # Set FOUNDRY_API_KEY environment variable
 
 async def main():
@@ -79,7 +79,7 @@ asyncio.run(main())
 ```typescript
 import { CopilotClient } from "@github/copilot-sdk";
 
-const FOUNDRY_MODEL_URL = "https://your-resource.openai.azure.com/openai/v1/";
+const FOUNDRY_MODEL_URL = "https://<resource-name>.openai.azure.com/openai/v1/";
 
 const client = new CopilotClient();
 const session = await client.createSession({
@@ -125,7 +125,7 @@ func main() {
         Model: "gpt-5.2-codex",  // Your deployment name
         Provider: &copilot.ProviderConfig{
             Type:    "openai",
-            BaseURL: "https://your-resource.openai.azure.com/openai/v1/",
+            BaseURL: "https://<resource-name>.openai.azure.com/openai/v1/",
             WireAPI: "responses",  // Use "completions" for older models
             APIKey:  os.Getenv("FOUNDRY_API_KEY"),
         },
@@ -160,7 +160,7 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
     Provider = new ProviderConfig
     {
         Type = "openai",
-        BaseUrl = "https://your-resource.openai.azure.com/openai/v1/",
+        BaseUrl = "https://<resource-name>.openai.azure.com/openai/v1/",
         WireApi = "responses",  // Use "completions" for older models
         ApiKey = Environment.GetEnvironmentVariable("FOUNDRY_API_KEY"),
     },
@@ -188,7 +188,7 @@ var session = client.createSession(new SessionConfig()
     .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
     .setProvider(new ProviderConfig()
         .setType("openai")
-        .setBaseUrl("https://your-resource.openai.azure.com/openai/v1/")
+        .setBaseUrl("https://<resource-name>.openai.azure.com/openai/v1/")
         .setWireApi("responses")  // Use "completions" for older models
         .setApiKey(System.getenv("FOUNDRY_API_KEY")))
 ).get();
@@ -213,6 +213,7 @@ client.stop().get();
 | `baseUrl` / `base_url` | string | **Required.** API endpoint URL |
 | `apiKey` / `api_key` | string | API key (optional for local providers like Ollama) |
 | `bearerToken` / `bearer_token` | string | Bearer token auth (takes precedence over apiKey) |
+| `bearerTokenProvider` / `bearer_token_provider` | callback | Returns a bearer token on demand (takes precedence over `apiKey` and `bearerToken`) |
 | `wireApi` / `wire_api` | `"completions"` \| `"responses"` | Select `"completions"` for broad model compatibility (the Chat Completions API); select `"responses"` for multi-turn state management, tool namespacing, and reasoning support (the Responses API). Anthropic models always use the Messages API regardless of this setting. |
 | `azure.apiVersion` / `azure.api_version` | string | Azure API version (default: `"2024-10-21"`) |
 
@@ -274,7 +275,7 @@ For Azure AI Foundry deployments with `/openai/v1/` endpoints, use `type: "opena
 ```typescript
 provider: {
     type: "openai",
-    baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
+    baseUrl: "https://<resource-name>.openai.azure.com/openai/v1/",
     apiKey: process.env.FOUNDRY_API_KEY,
     wireApi: "responses",  // For GPT-5 series models
 }
@@ -334,19 +335,37 @@ provider: {
 
 ### Bearer token authentication
 
-Some providers require bearer token authentication instead of API keys:
+Some providers require bearer token authentication instead of API keys. Supply a static token with `bearerToken`, or supply a `bearerTokenProvider` callback that the GitHub Copilot SDK runtime invokes before outbound provider requests. The callback or identity library it wraps manages token caching and refresh.
+
+Use `bearerToken` when your application already has a token:
 
 ```typescript
 provider: {
     type: "openai",
-    baseUrl: "https://my-custom-endpoint.example.com/v1",
+    baseUrl: "https://<resource-name>.openai.azure.com/openai/v1/",
     bearerToken: process.env.MY_BEARER_TOKEN,  // Sets Authorization header
 }
 ```
 
 > [!NOTE]
 > The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.
 
+Use `bearerTokenProvider` to acquire tokens on demand:
+
+<!-- docs-validate: skip -->
+
+```typescript
+provider: {
+    type: "openai",
+    baseUrl: "https://my-custom-endpoint.example.com/v1",
+    bearerTokenProvider: async () => {
+        return await acquireBearerToken();
+    },
+}
+```
+
+For more details about acquiring and refreshing Microsoft Entra bearer tokens, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/azure-managed-identity).
+
 ## Custom model listing
 
 When using BYOK, the CLI server may not know which models your provider supports. You can supply a custom `onListModels` handler at the client level so that `client.listModels()` returns your provider's models in the standard `ModelInfo` format. This lets downstream consumers discover available models without querying the CLI.
@@ -531,7 +550,7 @@ import { CopilotClient } from "@github/copilot-sdk";
 
 const client = new CopilotClient();
 const session = await client.createSession({
-    model: "gpt-4.1",
+    model: "gpt-5.4",
     provider: {
         type: "azure",
         baseUrl: "https://my-resource.openai.azure.com",
@@ -564,7 +583,7 @@ import { CopilotClient } from "@github/copilot-sdk";
 
 const client = new CopilotClient();
 const session = await client.createSession({
-    model: "gpt-4.1",
+    model: "gpt-5.4",
     provider: {
         type: "openai",
         baseUrl: "https://your-resource.openai.azure.com/openai/v1/",

content/copilot/how-tos/copilot-sdk/features/cloud-sessions.md

@@ -252,7 +252,7 @@ Capture the URL by subscribing to `session.info` and filtering by `infoType: "re
 session.on("session.info", (event) => {
   if (event.data?.infoType === "remote" && event.data.url) {
     console.log("Open from web or mobile:", event.data.url);
-    // e.g. surface in your UI as a shareable link or QR code.
+    // For example, surface in your UI as a shareable link or QR code.
   }
 });
 ```

content/copilot/how-tos/copilot-sdk/features/custom-agents.md

@@ -43,7 +43,7 @@ const client = new CopilotClient();
 await client.start();
 
 const session = await client.createSession({
-    model: "gpt-4.1",
+    model: "gpt-5.4",
     customAgents: [
         {
             name: "researcher",
@@ -75,7 +75,7 @@ await client.start()
 
 session = await client.create_session(
     on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
-    model="gpt-4.1",
+    model="gpt-5.4",
     custom_agents=[
         {
             "name": "researcher",
@@ -113,7 +113,7 @@ func main() {
 	client.Start(ctx)
 
 	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
-		Model: "gpt-4.1",
+		Model: "gpt-5.4",
 		CustomAgents: []copilot.CustomAgentConfig{
 			{
 				Name:        "researcher",
@@ -144,7 +144,7 @@ client := copilot.NewClient(nil)
 client.Start(ctx)
 
 session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
-    Model: "gpt-4.1",
+    Model: "gpt-5.4",
     CustomAgents: []copilot.CustomAgentConfig{
         {
             Name:        "researcher",
@@ -177,7 +177,7 @@ using GitHub.Copilot.Rpc;
 await using var client = new CopilotClient();
 await using var session = await client.CreateSessionAsync(new SessionConfig
 {
-    Model = "gpt-4.1",
+    Model = "gpt-5.4",
     CustomAgents = new List<CustomAgentConfig>
     {
         new()
@@ -215,7 +215,7 @@ try (var client = new CopilotClient()) {
 
     var session = client.createSession(
         new SessionConfig()
-            .setModel("gpt-4.1")
+            .setModel("gpt-5.4")
             .setCustomAgents(List.of(
                 new CustomAgentConfig()
                     .setName("researcher")
@@ -250,10 +250,14 @@ try (var client = new CopilotClient()) {
 | `mcpServers` | `object` | | MCP server configurations specific to this agent |
 | `infer` | `boolean` | | Whether the runtime can auto-select this agent (default: `true`) |
 | `skills` | `string[]` | | Skill names to preload into the agent's context at startup |
+| `model` | `string` | | Model identifier to use while this agent runs |
+| `reasoningEffort` | `string` | | Reasoning effort to use while this agent runs. When omitted, no override is sent and the backend chooses its default |
 
 > [!TIP]
 > A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities.
 
+Set `model` and `reasoningEffort` to override the parent session's model settings while a custom agent runs. When `reasoningEffort` is omitted, the SDK sends no per-agent override and the backend chooses its default. The parent session effort is not inherited, and the SDK does not add a per-agent default. Python uses `reasoning_effort`, .NET uses `ReasoningEffort`, Go uses `ReasoningEffort`, Java uses `setReasoningEffort`, and Rust uses `with_reasoning_effort`.
+
 In addition to per-agent configuration above, you can set `agent` on the **session config** itself to pre-select which custom agent is active when the session starts. See [Selecting an Agent at Session Creation](#selecting-an-agent-at-session-creation) below.
 
 | Session Config Property | Type | Description |
@@ -429,6 +433,8 @@ By default, all custom agents are available for automatic selection (`infer: tru
 
 When a sub-agent runs, the parent session emits lifecycle events. Subscribe to these events to build UIs that visualize agent activity.
 
+Sub-agent-originated session events share the parent session stream and include envelope-level `agentId`. Root/main agent events and session-level events omit `agentId`, so renderers can keep the parent response separate from sub-agent traces by checking the event envelope.
+
 ### Event types
 
 | Event | Emitted when | Data |
@@ -519,7 +525,7 @@ func main() {
 	client.Start(ctx)
 
 	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
-		Model: "gpt-4.1",
+		Model: "gpt-5.4",
 		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
 			return &rpc.PermissionDecisionApproveOnce{}, nil
 		},

content/copilot/how-tos/copilot-sdk/features/image-input.md

@@ -44,7 +44,7 @@ const client = new CopilotClient();
 await client.start();
 
 const session = await client.createSession({
-    model: "gpt-4.1",
+    model: "gpt-5.4",
     onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 
@@ -70,7 +70,7 @@ await client.start()
 
 session = await client.create_session(
     on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
-    model="gpt-4.1",
+    model="gpt-5.4",
 )
 
 await session.send(
@@ -102,7 +102,7 @@ func main() {
 	client.Start(ctx)
 
 	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
-		Model: "gpt-4.1",
+		Model: "gpt-5.4",
 		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
 			return &rpc.PermissionDecisionApproveOnce{}, nil
 		},
@@ -127,7 +127,7 @@ client := copilot.NewClient(nil)
 client.Start(ctx)
 
 session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
-    Model: "gpt-4.1",
+    Model: "gpt-5.4",
     OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
         return &rpc.PermissionDecisionApproveOnce{}, nil
     },
@@ -159,7 +159,7 @@ public static class ImageInputExample
         await using var client = new CopilotClient();
         await using var session = await client.CreateSessionAsync(new SessionConfig
         {
-            Model = "gpt-4.1",
+            Model = "gpt-5.4",
             OnPermissionRequest = (req, inv) =>
                 Task.FromResult(PermissionDecision.ApproveOnce()),
         });
@@ -187,7 +187,7 @@ using GitHub.Copilot.Rpc;
 await using var client = new CopilotClient();
 await using var session = await client.CreateSessionAsync(new SessionConfig
 {
-    Model = "gpt-4.1",
+    Model = "gpt-5.4",
     OnPermissionRequest = (req, inv) =>
         Task.FromResult(PermissionDecision.ApproveOnce()),
 });
@@ -219,7 +219,7 @@ try (var client = new CopilotClient()) {
 
     var session = client.createSession(
         new SessionConfig()
-            .setModel("gpt-4.1")
+            .setModel("gpt-5.4")
             .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
     ).get();
 
@@ -249,7 +249,7 @@ const client = new CopilotClient();
 await client.start();
 
 const session = await client.createSession({
-    model: "gpt-4.1",
+    model: "gpt-5.4",
     onPermissionRequest: async () => ({ kind: "approve-once" }),
 });
 
@@ -278,7 +278,7 @@ await client.start()
 
 session = await client.create_session(
     on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
-    model="gpt-4.1",
+    model="gpt-5.4",
 )
 
 base64_image_data = "..."  # your base64-encoded image
@@ -313,7 +313,7 @@ func main() {
 	client.Start(ctx)
 
 	session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
-		Model: "gpt-4.1",
+		Model: "gpt-5.4",
 		OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
 			return &rpc.PermissionDecisionApproveOnce{}, nil
 		},
@@ -364,7 +364,7 @@ public static class BlobAttachmentExample
         await using var client = new CopilotClient();
         await using var session = await client.CreateSessionAsync(new SessionConfig
         {
-            Model = "gpt-4.1",
+            Model = "gpt-5.4",
             OnPermissionRequest = (req, inv) =>
                 Task.FromResult(PermissionDecision.ApproveOnce()),
         });
@@ -416,7 +416,7 @@ try (var client = new CopilotClient()) {
 
     var session = client.createSession(
         new SessionConfig()
-            .setModel("gpt-4.1")
+            .setModel("gpt-5.4")
             .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
     ).get();