docs: fix inaccurate SDK/runtime claims found in docs audit

docs/auth/byok.md

@@ -207,7 +207,7 @@ client.stop().get();
 | `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"`) |
+| `azure.apiVersion` / `azure.api_version` | string | Azure API version. When set, the runtime uses the versioned deployment route; when omitted, it uses the GA versionless `v1` route. |
 
 ### Wire API format
 

docs/features/custom-agents.md

@@ -254,12 +254,12 @@ try (var client = new CopilotClient()) {
 | `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 |
+| `reasoningEffort` | `string` | | Reasoning effort to use while this agent runs. When omitted, the SDK sends no per-agent override and the runtime resolves the effort (see note below) |
 
 > [!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`.
+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 runtime resolves the effort from its own precedence: a per-call client option, the resolved model's default, or the agent definition all take priority; otherwise the runtime inherits the parent session's effort only when the subagent runs the same model as the parent. When the subagent resolves to a different model, it falls back to that model's default instead of inheriting the parent's effort. 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.
 

docs/hooks/user-prompt-submitted.md

@@ -415,11 +415,11 @@ const session = await client.createSession({
 });
 ```
 
-### Rate limiting
+### Usage threshold notices
 
 ```typescript
 const promptTimestamps: number[] = [];
-const RATE_LIMIT = 10; // prompts
+const NOTICE_THRESHOLD = 10; // prompts
 const RATE_WINDOW = 60000; // 1 minute
 
 const session = await client.createSession({
@@ -431,15 +431,16 @@ const session = await client.createSession({
       while (promptTimestamps.length > 0 && promptTimestamps[0] < now - RATE_WINDOW) {
         promptTimestamps.shift();
       }
-
-      if (promptTimestamps.length >= RATE_LIMIT) {
+
+      promptTimestamps.push(now);
+      if (promptTimestamps.length >= NOTICE_THRESHOLD) {
+        // This is advisory context for the model, not an enforced rate limit.
+        // Enforce hard limits before calling session.send().
         return {
-          reject: true,
-          rejectReason: `Rate limit exceeded. Please wait before sending more prompts.`,
+          additionalContext: `The user has sent ${promptTimestamps.length} prompts in the last minute. Suggest waiting before sending more.`,
         };
       }
-
-      promptTimestamps.push(now);
+
       return null;
     },
   },
@@ -490,7 +491,7 @@ const session = await client.createSession({
 
 1. **Use `additionalContext` over `modifiedPrompt`** - Adding context is less intrusive than rewriting the prompt.
 
-1. **Provide clear rejection reasons** - When rejecting prompts, explain why and how to fix it.
+1. **Use `additionalContext` for advisory guidance**: This hook cannot reject a prompt or enforce policy. Enforce hard limits before calling `session.send()`.
 
 1. **Keep processing fast** - This hook runs on every user message. Avoid slow operations.
 

docs/setup/bundled-cli.md

@@ -79,7 +79,7 @@ await client.stop()
 <summary><strong>Go</strong></summary>
 
 > [!NOTE]
-> The Go SDK does not bundle the CLI. You must install the CLI separately or set `Connection` to point to an existing binary. See [Local CLI Setup](./local-cli.md) for details.
+> Unlike Node.js, Python, and .NET, the Go SDK does not include a CLI as an automatic dependency. With no explicit path, `NewClient(nil)` uses an embedded CLI when available, then falls back to `copilot` on `PATH`. To embed a CLI, run the [bundler tool](../../go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli) at build time. You can also set `COPILOT_CLI_PATH` or point a `Connection` at an existing binary. See [Local CLI Setup](./local-cli.md) for details.
 
 <!-- docs-validate: hidden -->
 ```go
@@ -145,7 +145,7 @@ Console.WriteLine(response?.Data.Content);
 <summary><strong>Java</strong></summary>
 
 > [!NOTE]
-> The Java SDK does not bundle or embed the Copilot CLI. You must install the CLI separately and configure its path via `Connection` or the `COPILOT_CLI_PATH` environment variable.
+> The Java SDK does not bundle or embed the Copilot CLI. Install the CLI separately and either make `copilot` available on your `PATH` or set its location with `setCliPath(...)` (or connect to a running CLI server with `setCliUrl(...)`).
 
 ```java
 import com.github.copilot.CopilotClient;

docs/setup/local-cli.md

@@ -2,7 +2,7 @@
 
 Use a specific CLI binary instead of the SDK's automatic CLI management. This is an advanced option—you supply the CLI path explicitly, and you are responsible for ensuring version compatibility with the SDK.
 
-**Use when:** You need to pin a specific CLI version, or work with the Go SDK (which does not bundle a CLI).
+**Use when:** You need to pin a specific CLI version, or work with the Go SDK (which does not include a CLI automatically).
 
 ## How it works
 
@@ -78,7 +78,7 @@ await client.stop()
 <summary><strong>Go</strong></summary>
 
 > [!NOTE]
-> The Go SDK does not bundle a CLI, so you must always provide `Connection`.
+> The Go SDK does not ship a CLI automatically. Install `copilot` on `PATH`, set the `COPILOT_CLI_PATH` environment variable, embed a CLI with the [bundler tool](../../go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli), or point `StdioConnection.Path` at an installed binary.
 
 <!-- docs-validate: hidden -->
 ```go

dotnet/src/Types.cs

@@ -2275,7 +2275,7 @@ public sealed class CapiSessionOptions
 public sealed class AzureOptions
 {
     /// <summary>
-    /// Azure OpenAI API version to use (e.g., "2024-02-01").
+    /// Azure OpenAI API version. When omitted, the runtime uses the GA versionless v1 route.
     /// </summary>
     [JsonPropertyName("apiVersion")]
     public string? ApiVersion { get; set; }
@@ -2660,8 +2660,8 @@ public sealed class CustomAgentConfig
 
     /// <summary>
     /// Reasoning effort level for this agent's model.
-    /// When omitted, no per-agent override is sent and the backend chooses its
-    /// default. The parent session effort is not inherited.
+    /// When omitted, the runtime resolves model configuration, then inherits
+    /// the parent effort only if this agent uses the same model.
     /// </summary>
     [JsonPropertyName("reasoningEffort")]
     public string? ReasoningEffort { get; set; }

go/README.md

@@ -591,7 +591,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K
 - `APIKey` (string): API key (optional for local providers like Ollama)
 - `BearerToken` (string): Bearer token for authentication (takes precedence over APIKey)
 - `WireAPI` (string): API format for OpenAI/Azure - "completions" or "responses" (default: "completions")
-- `Azure.APIVersion` (string): Azure API version (default: "2024-10-21")
+- `Azure.APIVersion` (string): Azure API version; when empty, the runtime uses the GA versionless `v1` route
 
 **Example with Ollama:**
 

go/types.go

@@ -950,8 +950,8 @@ type CustomAgentConfig struct {
 	// falling back to the parent session model if unavailable.
 	Model string `json:"model,omitempty"`
 	// ReasoningEffort is the reasoning effort level for this agent's model.
-	// When empty, no per-agent override is sent and the backend chooses its
-	// default. The parent session effort is not inherited.
+	// When empty, the runtime resolves model configuration, then inherits the
+	// parent effort only for the same model.
 	ReasoningEffort string `json:"reasoningEffort,omitempty"`
 }
 
@@ -1966,7 +1966,8 @@ type CapiSessionOptions struct {
 
 // AzureProviderOptions contains Azure-specific provider configuration
 type AzureProviderOptions struct {
-	// APIVersion is the Azure API version. Defaults to "2024-10-21".
+	// APIVersion is the Azure API version. When empty, the runtime uses the GA
+	// versionless v1 route.
 	APIVersion string `json:"apiVersion,omitempty"`
 }
 

java/src/main/java/com/github/copilot/rpc/AzureOptions.java

@@ -12,6 +12,7 @@
  * <p>
  * When using a BYOK (Bring Your Own Key) setup with Azure OpenAI, this class
  * allows you to specify Azure-specific settings such as the API version to use.
+ * When no API version is set, the runtime uses the GA versionless v1 route.
  *
  * <h2>Example Usage</h2>
  *
@@ -32,7 +33,8 @@ public class AzureOptions {
     /**
      * Gets the Azure OpenAI API version.
      *
-     * @return the API version string
+     * @return the API version string, or {@code null} to use the GA versionless v1
+     *         route
      */
     public String getApiVersion() {
         return apiVersion;
@@ -41,7 +43,8 @@ public String getApiVersion() {
     /**
      * Sets the Azure OpenAI API version to use.
      * <p>
-     * Examples: {@code "2024-02-01"}, {@code "2023-12-01-preview"}
+     * Examples: {@code "2024-02-01"}, {@code "2023-12-01-preview"} When this option
+     * is not set, the runtime uses the GA versionless v1 route.
      *
      * @param apiVersion
      *            the API version string

java/src/main/java/com/github/copilot/rpc/CustomAgentConfig.java

@@ -298,8 +298,8 @@ public String getReasoningEffort() {
     /**
      * Sets the reasoning effort level for this agent's model.
      * <p>
-     * When omitted, no per-agent override is sent and the backend chooses its
-     * default. The parent session effort is not inherited.
+     * When omitted, the runtime resolves model configuration, then inherits the
+     * parent effort only if this agent uses the same model.
      *
      * @param reasoningEffort
      *            the reasoning effort level

nodejs/README.md

@@ -751,7 +751,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K
 - `apiKey?: string` - API key (optional for local providers like Ollama)
 - `bearerToken?: string` - Bearer token for authentication (takes precedence over apiKey)
 - `wireApi?: "completions" | "responses"` - API format for OpenAI/Azure (default: "completions")
-- `azure?.apiVersion?: string` - Azure API version (default: "2024-10-21")
+- `azure?.apiVersion?: string` - Azure API version; when omitted, the runtime uses the GA versionless `v1` route
 
 **Example with Ollama:**
 

nodejs/src/types.ts

@@ -1643,8 +1643,8 @@ export interface CustomAgentConfig {
     model?: string;
     /**
      * Reasoning effort level for this agent's model.
-     * When omitted, no per-agent override is sent and the backend chooses its
-     * default. The parent session effort is not inherited.
+     * When omitted, the runtime resolves the effort from model configuration,
+     * then inherits the parent effort only if this agent uses the same model.
      */
     reasoningEffort?: ReasoningEffort;
 }
@@ -2619,7 +2619,7 @@ export interface ProviderConfig {
      */
     azure?: {
         /**
-         * API version. Defaults to "2024-10-21".
+         * API version. When omitted, the runtime uses the GA versionless v1 route.
          */
         apiVersion?: string;
     };

python/README.md

@@ -586,7 +586,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K
 - `api_key` (str): API key (optional for local providers like Ollama)
 - `bearer_token` (str): Bearer token for authentication (takes precedence over `api_key`)
 - `wire_api` (str): API format for OpenAI/Azure - `"completions"` or `"responses"` (default: `"completions"`)
-- `azure` (dict): Azure-specific options with `api_version` (default: `"2024-10-21"`)
+- `azure` (dict): Azure-specific options with `api_version`; when omitted, the runtime uses the GA versionless `v1` route
 
 **Example with Ollama:**
 

python/copilot/session.py

@@ -1080,8 +1080,8 @@ class CustomAgentConfig(TypedDict, total=False):
     skills: NotRequired[list[str]]
     # Model identifier (e.g. "claude-haiku-4.5"); runtime falls back to parent model if unavailable
     model: NotRequired[str]
-    # Reasoning effort for this agent's model. When omitted, no per-agent override
-    # is sent and the backend chooses its default; the parent effort is not inherited.
+    # Reasoning effort for this agent's model. When omitted, the runtime resolves
+    # model configuration, then inherits the parent effort only for the same model.
     reasoning_effort: NotRequired[ReasoningEffort]
 
 
@@ -1183,7 +1183,8 @@ class MemoryConfiguration(TypedDict):
 class AzureProviderOptions(TypedDict, total=False):
     """Azure-specific provider configuration"""
 
-    api_version: str  # Azure API version. Defaults to "2024-10-21".
+    # Azure API version. When omitted, the runtime uses the GA versionless v1 route.
+    api_version: str
 
 
 class ProviderTokenArgs(TypedDict):

rust/src/types.rs

@@ -644,8 +644,8 @@ pub struct CustomAgentConfig {
     pub model: Option<String>,
     /// Reasoning effort level for this agent's model.
     ///
-    /// When unset, no per-agent override is sent and the backend chooses its
-    /// default. The parent session effort is not inherited.
+    /// When unset, the runtime resolves model configuration, then inherits the
+    /// parent effort only for the same model.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub reasoning_effort: Option<String>,
 }
@@ -1351,7 +1351,7 @@ impl CapiSessionOptions {
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AzureProviderOptions {
-    /// Azure API version. Defaults to `"2024-10-21"`.
+    /// Azure API version. When omitted, the runtime uses the GA versionless v1 route.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub api_version: Option<String>,
 }