docs: fix inaccurate SDK/runtime claims found in docs audit (#2064)

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

Cross-checked doc claims against the SDK and copilot-agent-runtime
repos and corrected five verified inaccuracies:

- setup/local-cli.md, setup/bundled-cli.md: the Go SDK is not
  bundle-less — it embeds a CLI via `go tool bundler` and reads
  COPILOT_CLI_PATH; corrected the "must always provide Connection"
  guidance.
- setup/bundled-cli.md: Java configures the CLI via setCliPath /
  setCliUrl (or `copilot` on PATH), not `Connection` /
  COPILOT_CLI_PATH.
- hooks/user-prompt-submitted.md: the hook output has no
  reject/rejectReason; replaced the rate-limit example and
  best-practice bullet with the real additionalContext behavior.
- auth/byok.md: omitted Azure apiVersion uses the GA versionless v1
  route, not a 2024-10-21 default.
- features/custom-agents.md: the runtime now inherits parent
  reasoning effort for same-model subagents (#13388); corrected the
  "parent effort is not inherited" statement.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: af5056fb-e73c-4bc2-bc11-753fd633cb98

* docs: address audit review feedback

Document the Go PATH fallback, reframe the hook example as advisory, and correct Azure versionless routing references across SDK docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: finish cross-SDK audit corrections

Correct the advisory threshold example and align Azure routing and reasoning-effort API documentation across all six SDKs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* style(java): format Azure options Javadoc

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Steve Sanderson <1101362+SteveSandersonMS@users.noreply.github.com>
Copilot-Session: af5056fb-e73c-4bc2-bc11-753fd633cb98

Author: 3 people

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