@github/copilot-sdk 1.0.23 → 1.0.24-preview.1

package/README.md

@@ -387,9 +387,9 @@ Create a new conversation session.
 - `systemMessage?: SystemMessageConfig` - System message customization (see below)
 - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
 - `workingDirectory?: string` - Working directory for the session (default: runtime process cwd).
+- `trustWorkingDirectory?: "session" | "user"` - Grant trust to the canonical working directory during session creation. `"session"` trusts it only for this session; `"user"` persists trust for later sessions. Omit to leave trust unchanged. Not available on resume.
 - `refreshCustomInstructions?: boolean` - Invalidates the process-wide custom-instruction discovery cache before creating this session, so instruction-file edits made in the same runtime are read again. Defaults to `false` (cache reuse). Other sessions in this runtime may observe updated instructions on later turns or discovery. This does not watch files or enable disabled instruction loading. Available on `SessionConfig`, not `ResumeSessionConfig`.
 - `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
-- `enableGitHubCacheStore?: boolean` - Requests the read-only GitHub cache store (`github-cache-store` capability) on create or resume. The runtime registers the `github_sql` tool only when its `GITHUB_CACHE_STORE` feature flag is also on. Defaults to disabled in every mode.
 - `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require a positive `expiresIn` value in seconds remaining when the callback completes; production tokens typically last eight hours. Cannot be combined with `gitHubToken`.
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
 - `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `approveAll` approves requests when managed settings are disabled and throws when `enableManagedSettings` is true. Custom handlers can inspect `managedApprovalRequired` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.

package/dist/cjs/cliVersion.js

@@ -22,7 +22,7 @@ __export(cliVersion_exports, {
   COPILOT_CLI_VERSION: () => COPILOT_CLI_VERSION
 });
 module.exports = __toCommonJS(cliVersion_exports);
-const COPILOT_CLI_VERSION = "1.0.100";
+const COPILOT_CLI_VERSION = "1.0.101-1";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/client.js

@@ -780,11 +780,19 @@ class CopilotClient {
       const sessionId = session.sessionId;
       let lastError = null;
       for (let attempt = 1; attempt <= 3; attempt++) {
+        if (this.connectionClosed) {
+          lastError = null;
+          break;
+        }
         try {
           await session.disconnect();
           lastError = null;
           break;
         } catch (error) {
+          if (this.connectionClosed) {
+            lastError = null;
+            break;
+          }
           lastError = error instanceof Error ? error : new Error(String(error));
           if (attempt < 3) {
             const delay = 100 * Math.pow(2, attempt - 1);
@@ -970,8 +978,10 @@ class CopilotClient {
    * - Clears all sessions immediately without destroying them
    * - Force closes the connection
    * - Sends SIGKILL to the CLI process (if spawned by this client)
+   * - Waits for the spawned CLI process to exit
    *
    * @returns A promise that resolves when the force stop is complete
+   * @throws If the spawned CLI process cannot be terminated
    *
    * @example
    * ```typescript
@@ -1018,13 +1028,6 @@ class CopilotClient {
       }
       this.socket = null;
     }
-    if (this.cliProcess && !this.isExternalServer) {
-      try {
-        this.cliProcess.kill("SIGKILL");
-      } catch {
-      }
-      this.cliProcess = null;
-    }
     if (this.ffiHost) {
       const host = this.ffiHost;
       this.ffiHost = null;
@@ -1041,6 +1044,20 @@ class CopilotClient {
     this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
+    if (this.cliProcess && !this.isExternalServer) {
+      const child = this.cliProcess;
+      if (child.exitCode == null && child.signalCode == null) {
+        child.kill("SIGKILL");
+        if (!await waitForChildExit(child, RUNTIME_SHUTDOWN_TIMEOUT_MS)) {
+          throw new Error(
+            `Timed out waiting for CLI process to exit after SIGKILL: ${RUNTIME_SHUTDOWN_TIMEOUT_MS}ms`
+          );
+        }
+      }
+      if (this.cliProcess === child) {
+        this.cliProcess = null;
+      }
+    }
   }
   /**
    * Creates a new conversation session with the Copilot CLI.
@@ -1313,7 +1330,8 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer,
           metadata: tool.metadata,
-          isTerminal: tool.isTerminal
+          isTerminal: tool.isTerminal,
+          namespace: tool.namespace
         })),
         toolSearch: config.toolSearch,
         imageGeneration: config.imageGeneration,
@@ -1352,6 +1370,7 @@ class CopilotClient {
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
+        trustWorkingDirectory: config.trustWorkingDirectory,
         additionalDirectories: config.additionalDirectories,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
@@ -1375,7 +1394,6 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
-        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
         ...config.skillProvider ? { hasSkillProvider: true } : {},
@@ -1385,6 +1403,7 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         disabledMcpServers: config.disabledMcpServers,
+        sandboxConfig: config.sandboxConfig,
         infiniteSessions: config.infiniteSessions,
         memory: config.memory,
         gitHubToken: config.gitHubToken,
@@ -1594,7 +1613,8 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer,
           metadata: tool.metadata,
-          isTerminal: tool.isTerminal
+          isTerminal: tool.isTerminal,
+          namespace: tool.namespace
         })),
         toolSearch: config.toolSearch,
         imageGeneration: config.imageGeneration,
@@ -1635,7 +1655,6 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
-        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
@@ -1657,6 +1676,7 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         disabledMcpServers: config.disabledMcpServers,
+        sandboxConfig: config.sandboxConfig,
         infiniteSessions: config.infiniteSessions,
         memory: config.memory,
         disableResume: config.suppressResumeEvent,
@@ -2436,7 +2456,13 @@ stderr: ${stderrOutput}`
       this.cliStartTimeout = setTimeout(() => {
         if (!resolved) {
           resolved = true;
-          reject(new Error("Timeout waiting for CLI server to start"));
+          reject(
+            new Error(
+              `Timeout waiting for CLI server to start
+stdout: ${stdout.trim().slice(-8192) || "(empty)"}
+stderr: ${this.stderrBuffer.trim().slice(-8192) || "(empty)"}`
+            )
+          );
         }
       }, 3e4);
     });
@@ -2571,6 +2597,9 @@ stderr: ${stderrOutput}`
 stderr: ${stderrOutput}` : ""}`
       );
       this.logDebug(`stdin pipe error: ${reason}`);
+      if (this.messageWriter) {
+        this.messageWriter.suppressWriteErrors = true;
+      }
       try {
         this.connection?.dispose();
       } catch {

package/dist/cjs/session.js

@@ -47,7 +47,8 @@ function toToolDefinition(tool) {
     skipPermission: tool.skipPermission,
     defer: tool.defer,
     metadata: tool.metadata,
-    isTerminal: tool.isTerminal
+    isTerminal: tool.isTerminal,
+    namespace: tool.namespace
   };
 }
 const workflowExecutionStore = new import_node_async_hooks.AsyncLocalStorage();

package/dist/cliVersion.d.ts

@@ -1,2 +1,2 @@
-export declare const COPILOT_CLI_VERSION = "1.0.100";
+export declare const COPILOT_CLI_VERSION = "1.0.101-1";
 export declare const COPILOT_CLI_USE_NPM_PACKAGE = false;

package/dist/cliVersion.js

@@ -1,4 +1,4 @@
-const COPILOT_CLI_VERSION = "1.0.100";
+const COPILOT_CLI_VERSION = "1.0.101-1";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 export {
   COPILOT_CLI_USE_NPM_PACKAGE,

package/dist/client.d.ts

@@ -179,8 +179,10 @@ export declare class CopilotClient {
      * - Clears all sessions immediately without destroying them
      * - Force closes the connection
      * - Sends SIGKILL to the CLI process (if spawned by this client)
+     * - Waits for the spawned CLI process to exit
      *
      * @returns A promise that resolves when the force stop is complete
+     * @throws If the spawned CLI process cannot be terminated
      *
      * @example
      * ```typescript

package/dist/client.js

@@ -760,11 +760,19 @@ class CopilotClient {
       const sessionId = session.sessionId;
       let lastError = null;
       for (let attempt = 1; attempt <= 3; attempt++) {
+        if (this.connectionClosed) {
+          lastError = null;
+          break;
+        }
         try {
           await session.disconnect();
           lastError = null;
           break;
         } catch (error) {
+          if (this.connectionClosed) {
+            lastError = null;
+            break;
+          }
           lastError = error instanceof Error ? error : new Error(String(error));
           if (attempt < 3) {
             const delay = 100 * Math.pow(2, attempt - 1);
@@ -950,8 +958,10 @@ class CopilotClient {
    * - Clears all sessions immediately without destroying them
    * - Force closes the connection
    * - Sends SIGKILL to the CLI process (if spawned by this client)
+   * - Waits for the spawned CLI process to exit
    *
    * @returns A promise that resolves when the force stop is complete
+   * @throws If the spawned CLI process cannot be terminated
    *
    * @example
    * ```typescript
@@ -998,13 +1008,6 @@ class CopilotClient {
       }
       this.socket = null;
     }
-    if (this.cliProcess && !this.isExternalServer) {
-      try {
-        this.cliProcess.kill("SIGKILL");
-      } catch {
-      }
-      this.cliProcess = null;
-    }
     if (this.ffiHost) {
       const host = this.ffiHost;
       this.ffiHost = null;
@@ -1021,6 +1024,20 @@ class CopilotClient {
     this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
+    if (this.cliProcess && !this.isExternalServer) {
+      const child = this.cliProcess;
+      if (child.exitCode == null && child.signalCode == null) {
+        child.kill("SIGKILL");
+        if (!await waitForChildExit(child, RUNTIME_SHUTDOWN_TIMEOUT_MS)) {
+          throw new Error(
+            `Timed out waiting for CLI process to exit after SIGKILL: ${RUNTIME_SHUTDOWN_TIMEOUT_MS}ms`
+          );
+        }
+      }
+      if (this.cliProcess === child) {
+        this.cliProcess = null;
+      }
+    }
   }
   /**
    * Creates a new conversation session with the Copilot CLI.
@@ -1293,7 +1310,8 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer,
           metadata: tool.metadata,
-          isTerminal: tool.isTerminal
+          isTerminal: tool.isTerminal,
+          namespace: tool.namespace
         })),
         toolSearch: config.toolSearch,
         imageGeneration: config.imageGeneration,
@@ -1332,6 +1350,7 @@ class CopilotClient {
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
+        trustWorkingDirectory: config.trustWorkingDirectory,
         additionalDirectories: config.additionalDirectories,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
@@ -1355,7 +1374,6 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
-        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
         ...config.skillProvider ? { hasSkillProvider: true } : {},
@@ -1365,6 +1383,7 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         disabledMcpServers: config.disabledMcpServers,
+        sandboxConfig: config.sandboxConfig,
         infiniteSessions: config.infiniteSessions,
         memory: config.memory,
         gitHubToken: config.gitHubToken,
@@ -1574,7 +1593,8 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer,
           metadata: tool.metadata,
-          isTerminal: tool.isTerminal
+          isTerminal: tool.isTerminal,
+          namespace: tool.namespace
         })),
         toolSearch: config.toolSearch,
         imageGeneration: config.imageGeneration,
@@ -1615,7 +1635,6 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
-        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
@@ -1637,6 +1656,7 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         disabledMcpServers: config.disabledMcpServers,
+        sandboxConfig: config.sandboxConfig,
         infiniteSessions: config.infiniteSessions,
         memory: config.memory,
         disableResume: config.suppressResumeEvent,
@@ -2416,7 +2436,13 @@ stderr: ${stderrOutput}`
       this.cliStartTimeout = setTimeout(() => {
         if (!resolved) {
           resolved = true;
-          reject(new Error("Timeout waiting for CLI server to start"));
+          reject(
+            new Error(
+              `Timeout waiting for CLI server to start
+stdout: ${stdout.trim().slice(-8192) || "(empty)"}
+stderr: ${this.stderrBuffer.trim().slice(-8192) || "(empty)"}`
+            )
+          );
         }
       }, 3e4);
     });
@@ -2551,6 +2577,9 @@ stderr: ${stderrOutput}`
 stderr: ${stderrOutput}` : ""}`
       );
       this.logDebug(`stdin pipe error: ${reason}`);
+      if (this.messageWriter) {
+        this.messageWriter.suppressWriteErrors = true;
+      }
       try {
         this.connection?.dispose();
       } catch {

package/dist/generated/rpc.d.ts

@@ -2994,18 +2994,18 @@ export type SessionLogLevel =
 /** Error message describing a failure. */
  | "error";
 /**
- * Administrator-configured Ensemble preference, independent of execution support.
+ * Administrator-configured Fusion preference, independent of execution support.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
- * via the `definition` "ManagedEnsembleTier".
+ * via the `definition` "ManagedFusionTier".
  */
 /** @experimental */
-export type ManagedEnsembleTier = 
-/** Balance efficiency and intelligence. */
-"balance"
-/** Prefer higher intelligence. */
+export type ManagedFusionTier = 
+/** Use Auto Balance to balance capability, speed, and cost. */
+"standard"
+/** Use HydraFusion, falling back to Auto Intelligence when unavailable. */
  | "high"
-/** Prefer maximum intelligence. */
+/** Use HydraFusion Max to prioritize quality. */
  | "max"
 /** Leave tier selection unmanaged without falling back to legacy Auto policy. */
  | "unmanaged";
@@ -5011,8 +5011,6 @@ export type SessionCapability =
  | "elicitation"
 /** Cross-session history tools and session-store SQL prompt/tool metadata. */
  | "session-store"
-/** Read-only GitHub cache SQL tool (github_sql). */
- | "github-cache-store"
 /** MCP Apps UI passthrough. */
  | "mcp-apps"
 /** Host-provided canvas rendering support. */
@@ -8246,6 +8244,49 @@ export interface AutopilotObjectiveState {
     creditCountNanoAiu: string;
     creditLimit?: AutopilotObjectiveCreditLimit;
 }
+/**
+ * Billing information for a server-advertised routing preference.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "AutoTierBilling".
+ */
+/** @experimental */
+export interface AutoTierBilling {
+    promo?: AutoTierBillingPromo;
+}
+/**
+ * Server-driven promotion for an Auto routing preference. It can be announced before it starts.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "AutoTierBillingPromo".
+ */
+/** @experimental */
+export interface AutoTierBillingPromo {
+    /**
+     * Stable identifier for the promotion campaign.
+     */
+    id?: string;
+    /**
+     * Percentage discount (0-100) while the promotion is active. Absent or 0 means the promotion is an announcement only: do not present a discount.
+     */
+    discountPercent?: number;
+    /**
+     * UTC ISO 8601 timestamp marking when the promotion starts. The service can announce a promotion before it starts, so do not present the discount as active before this time. Absent means it has already started.
+     */
+    startsAt?: string;
+    /**
+     * UTC ISO 8601 timestamp marking when the promotion ends. Absent means open-ended. The runtime omits promotions that have already ended.
+     */
+    endsAt?: string;
+    /**
+     * Human-readable promotion message. Does not include the start or end timestamps.
+     */
+    message?: string;
+    /**
+     * Whether the service asked hosts to give this promotion a prominent surface, such as a banner. Absent means the service expressed no preference, so hosts should apply their own default rather than read it as `false`.
+     */
+    showBanner?: boolean;
+}
 /**
  * A server-advertised routing preference. Identifiers and execution types are extensible.
  *
@@ -8267,10 +8308,15 @@ export interface AutoTierDescriptor {
      */
     description: string;
     /**
-     * Execution kind; this client supports `auto` preferences on the Auto model.
+     * Execution kind; supported preferences use `auto` or the runtime's `fusion` modes.
      */
     type: string;
+    /**
+     * Runtime-owned managed Fusion tier represented by this execution descriptor, if any.
+     */
+    fusionTier?: string;
     status: AutoTierStatus;
+    billing?: AutoTierBilling;
 }
 /**
  * Availability of a server-advertised routing preference.
@@ -8284,6 +8330,10 @@ export interface AutoTierStatus {
      * Whether the provider permits selecting this preference.
      */
     enabled: boolean;
+    /**
+     * Whether hosts should list this preference in a picker. Absent means visible. A hidden preference can still be requested explicitly through the SDK.
+     */
+    pickerVisible?: boolean;
     /**
      * Extensible machine-readable unavailability reason.
      */
@@ -15726,7 +15776,7 @@ export interface ManagedSettingsValues {
      */
     model?: string;
     autoTier?: AutoTier;
-    ensembleTier?: ManagedEnsembleTier;
+    fusionTier?: ManagedFusionTier;
     /**
      * Managed reasoning-effort default for the managed concrete model. The runtime clamps it to an entitled effort when model availability is known.
      */
@@ -15743,7 +15793,7 @@ export interface ManagedSettingsValues {
 export interface ManagedSettingsMeta {
     model?: ManagedSettingMeta;
     autoTier?: ManagedSettingMeta;
-    ensembleTier?: ManagedSettingMeta;
+    fusionTier?: ManagedSettingMeta;
     effortLevel?: ManagedSettingMeta;
     contextTier?: ManagedSettingMeta;
 }
@@ -19732,7 +19782,7 @@ export interface ModelSwitchToRequest {
      */
     compactionDecision?: string;
     /**
-     * When true, evaluate context-window compaction policy before applying the switch.
+     * When true, evaluate context-window compaction policy before applying the switch, including effort-only and unchanged selections while idle. An effort-only change applies immediately without compaction when a turn is active, including when the turn starts during preflight; an explicit `compactionDecision: "cancel"` still cancels the change. Other switches retain preflight and may be deferred until the active turn ends.
      */
     runCompactionPreflight?: boolean;
     /**
@@ -20768,6 +20818,10 @@ export interface PermissionDecisionContext {
     source: PermissionDecisionSource;
     surface: PermissionDecisionSurface;
     responseCapability?: PermissionResponseCapability;
+    /**
+     * Optional user-authored explanation of this decision, independent of approval scope. Collected only in restricted telemetry for accepted human responses to Assisted Permissions prompts. Never persisted in session history, sent to the agent or judge, or used to create approval rules. Existing rejection feedback is separate.
+     */
+    userFeedback?: string;
 }
 /**
  * Pending permission request ID and the decision to apply (approve/reject and scope).
@@ -21300,6 +21354,10 @@ export interface PermissionsConfigureParams {
      * If specified, replaces the host-supplied GitHub Content Exclusion policies on the session (combined with natively-discovered policies when evaluating tool/file access). Omit to leave the current policies unchanged.
      */
     additionalContentExclusionPolicies?: PermissionsConfigureAdditionalContentExclusionPolicy[];
+    /**
+     * User-authored instructions appended verbatim to the assisted-approval judge's system prompt. Applies to subsequent judge requests in this local session without changing permission mode, pre-judge gates, or the coding agent's prompt. Omit to leave unchanged; an empty or whitespace-only string clears the instructions. Hosts must reapply their configuration after resuming a session. Remote sessions are not supported.
+     */
+    assistedApprovalInstructions?: string;
 }
 /**
  * If specified, replaces the session's URL-permission policy. The runtime constructs a fresh DefaultUrlManager based on these inputs. Omit to leave the current URL policy unchanged.
@@ -22233,6 +22291,24 @@ export interface ProtocolExternalToolDefinition {
     metadata?: {
         [k: string]: JsonValue | undefined;
     };
+    namespace?: ProtocolExternalToolNamespace;
+}
+/**
+ * Namespace that groups related caller-implemented tools for model tool discovery.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "ProtocolExternalToolNamespace".
+ */
+/** @experimental */
+export interface ProtocolExternalToolNamespace {
+    /**
+     * Namespace name: 1-64 ASCII letters, digits, underscores, or hyphens.
+     */
+    name: string;
+    /**
+     * Optional model-visible explanation of the tools in this namespace.
+     */
+    description?: string;
 }
 /**
  * Opt into native CAPI image generation.
@@ -22246,6 +22322,16 @@ export interface ProtocolImageGenerationOptions {
      * Disabled by default for SDK sessions. CAPI model access and permissions still apply.
      */
     enabled?: boolean;
+    /**
+     * Experimental. Request a visible "Made with AI" label on generated and edited images.
+     * This option may change or be removed in a future release.
+     * Overrides the user's imageGenerationWatermark preference for this session;
+     * otherwise that preference applies, defaulting to false. Re-supply after a
+     * cold resume. Does not enable image generation or enforce enterprise policy.
+     *
+     * @experimental
+     */
+    watermark?: boolean;
 }
 /**
  * BYOK providers and/or models to add to the session's registry at runtime. Both fields are optional; provide providers, models, or both.
@@ -22296,6 +22382,10 @@ export interface ProviderConfig {
      * API key. Optional for local providers like Ollama.
      */
     apiKey?: string;
+    /**
+     * Command run by the runtime before each provider request to obtain a fresh API key. Credential-command failures fail the turn without sending a model request. Bearer authentication takes precedence.
+     */
+    apiKeyCommand?: string;
     /**
      * Bearer token for authentication. Sets the Authorization header directly. Takes precedence over apiKey when both are set.
      */

package/dist/generated/session-events.d.ts

@@ -499,7 +499,7 @@ export type CompactionTrigger =
  | "manual"
 /** Emergency compaction triggered by high process memory usage. */
  | "memory_pressure"
-/** Compaction requested while switching to a model with a smaller context window. */
+/** Compaction requested while switching to a model with a smaller context window, including a HydraFusion turn's routed root model. */
  | "model_switch";
 /**
  * Category of structured task blocker
@@ -3942,7 +3942,7 @@ export interface CompactionStartData {
      */
     model?: string;
     /**
-     * Destination model for a model-switch compaction when it differs from the compacting model
+     * Destination model for a model-switch compaction when it differs from the compacting model; for a HydraFusion turn, the routed root model
      */
     switchTargetModel?: string;
     /**
@@ -4084,7 +4084,7 @@ export interface CompactionCompleteData {
      */
     summaryContent?: string;
     /**
-     * Destination model for a model-switch compaction when it differs from the compacting model
+     * Destination model for a model-switch compaction when it differs from the compacting model; for a HydraFusion turn, the routed root model
      */
     switchTargetModel?: string;
     /**
@@ -4766,6 +4766,12 @@ export interface FusionCompletedEvent {
  */
 /** @experimental */
 export interface FusionCompletedData {
+    /**
+     * True when the committed first pass ended with background work outstanding, so that work's completion notifications continue the conversation; absent otherwise.
+     *
+     * @experimental
+     */
+    awaitingBackgroundWork?: boolean;
     /**
      * Total cached input tokens reported across all phases.
      */
@@ -5679,6 +5685,12 @@ export interface FusionPhaseCompletedData {
      * Elapsed execution time for the phase in milliseconds.
      */
     durationMs: number;
+    /**
+     * True when a first pass (Cascade primary or Critique draft) ended with background work outstanding, whether or not the turn then committed it without review; absent otherwise.
+     *
+     * @experimental
+     */
+    endedWithBackgroundWork?: boolean;
     /**
      * Identifier of the HydraFusion turn containing the phase.
      */
@@ -6946,7 +6958,7 @@ export interface ModelCallFailureData {
      */
     durationMs?: number;
     /**
-     * For HTTP 400 failures only: the `code` from the CAPI error envelope (e.g. 'model_max_prompt_tokens_exceeded') identifying which deterministic validation failure occurred. Raw server-controlled string, emitted only through restricted telemetry. Absent for bodyless or non-400 failures.
+     * The `code` from the CAPI error envelope of an HTTP failure of any status (e.g. 'model_max_prompt_tokens_exceeded' on a 400, 'model_overloaded' on a 5xx) identifying which upstream failure occurred. Raw server-controlled string, emitted only through restricted telemetry. Absent when the response carried no error envelope.
      */
     errorCode?: string;
     /**
@@ -6954,7 +6966,7 @@ export interface ModelCallFailureData {
      */
     errorMessage?: string;
     /**
-     * For HTTP 400 failures only: the `type` from the CAPI error envelope (e.g. 'websocket_error'), a coarser companion to errorCode for envelopes that carry no code. Raw server-controlled string, emitted only through restricted telemetry. Absent for bodyless or non-400 failures.
+     * The `type` from the CAPI error envelope of an HTTP failure of any status (e.g. 'websocket_error'), a coarser companion to errorCode for envelopes that carry no code. Raw server-controlled string, emitted only through restricted telemetry. Absent when the response carried no error envelope.
      */
     errorType?: string;
     failureKind?: ModelCallFailureKind;
@@ -7069,6 +7081,10 @@ export interface ModelCallFailureData {
  * Content-free structural summary of the failing request for diagnosing malformed 4xx calls
  */
 export interface ModelCallFailureRequestFingerprint {
+    /**
+     * Free-form custom tool calls in the request history before request shaping, counted apart from named function calls (rejected by strict providers)
+     */
+    customToolCallCount?: number;
     /**
      * Summed byte length of opaque or encrypted reasoning payloads
      */
@@ -7097,6 +7113,10 @@ export interface ModelCallFailureRequestFingerprint {
      * Tool calls whose name is missing or empty (rejected by strict providers)
      */
     namelessToolCallCount: number;
+    /**
+     * Tool calls in the request history before request shaping that no later tool result message answers
+     */
+    orphanToolCallCount?: number;
     /**
      * Number of messages carrying opaque or encrypted reasoning
      */
@@ -7109,6 +7129,10 @@ export interface ModelCallFailureRequestFingerprint {
      * Number of "tool" result messages in the request
      */
     toolResultMessageCount: number;
+    /**
+     * Tool result messages in the request history before request shaping that answer no earlier unanswered tool call
+     */
+    unmatchedToolResultCount?: number;
 }
 /**
  * Session event "model.call_finished". Final lifecycle outcome for one logical model dispatch. A logical dispatch may include internal reconnect or fallback work, so event count is not provider HTTP-request count.
@@ -9741,6 +9765,10 @@ export interface PermissionRequestMemory {
 /** @experimental */
 export interface PermissionAssistedApproval {
     evaluation?: PermissionApprovalEvaluation;
+    /**
+     * Runtime-generated correlation ID for the original judge invocation. Cached recommendations retain it. Absent when review was skipped or the event predates correlation support; never part of the judge prompt.
+     */
+    evaluationId?: string;
     failureReason?: AssistedApprovalJudgeFailureReason;
     /**
      * Model id that produced the recommendation, when the judge was consulted and reported one. Absent for `excluded` (the judge was not consulted) and for failures that occurred before a model was selected.
@@ -9798,6 +9826,8 @@ export interface PermissionApprovalEvaluation {
      | "authorization-history-incomplete"
     /** Managed policy required a human decision. */
      | "managed-approval-required"
+    /** An extension capability grant required explicit user consent. */
+     | "extension-permission-access"
     /** The request asked to bypass sandbox restrictions. */
      | "sandbox-bypass"
     /** An action field exceeded the judge input limit. */

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * JSON-RPC based SDK for programmatic control of GitHub Copilot CLI
  */
 export { CopilotClient } from "./client.js";
-export type { HostLocalServerOptions, HostGitHubEnvironmentOptions, ModelGetReasoningSummariesRequest, ModelGetReasoningSummariesResult, } from "./generated/rpc.js";
+export type { HostLocalServerOptions, HostGitHubEnvironmentOptions, ModelGetReasoningSummariesRequest, ModelGetReasoningSummariesResult, SandboxConfig, } from "./generated/rpc.js";
 export { AhpHost, type AhpHostExit, type AhpHostOptions, type AhpSessionCreateRequest, type AhpSessionResumeRequest, } from "./host.js";
 export { DisableBypassPermissionsModes, RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
@@ -13,5 +13,5 @@ export { defineWorkflow, WorkflowResumeError, isWorkflowRunTerminal } from "./wo
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, createAttributedPermissionResult, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SessionFsWriteFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, SubagentStartHandler, SubagentStartHookInput, SubagentStartHookOutput, SubagentStopHandler, SubagentStopHookInput, SubagentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, InstallationConfirmationHandler, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionLaunchProfile, ExtensionLaunchProvider, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, ExtensionContextAttachment, MessageOptions, ResponseSchema, MessageSource, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, AutoTier, CapiSessionOptions, CurrentModel, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, ProviderConfig, ProviderConfigModelProvider, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, SandboxConfigSource, ResumeSessionConfig, TranscriptRecovery, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, SkillProvider, SkillProviderCallOptions, SkillProviderDescriptor, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, ImageGenerationConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, SubagentStartHandler, SubagentStartHookInput, SubagentStartHookOutput, SubagentStopHandler, SubagentStopHookInput, SubagentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, InstallationConfirmationHandler, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionLaunchProfile, ExtensionLaunchProvider, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, ExtensionContextAttachment, MessageOptions, ResponseSchema, MessageSource, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, AutoTier, CapiSessionOptions, CurrentModel, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, ProviderConfig, ProviderConfigModelProvider, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, SandboxConfigSource, ResumeSessionConfig, TranscriptRecovery, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, WorkingDirectoryTrust, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, SkillProvider, SkillProviderCallOptions, SkillProviderDescriptor, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolNamespace, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, ImageGenerationConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
 export type { JsonValue, WorkflowRunOptions, WorkflowResumeOptions, WorkflowLimitOverrides, WorkflowResumeErrorCode, SessionWorkflowApi, WorkflowAgentOptions, WorkflowContext, WorkflowDefinition, WorkflowHandle, WorkflowJsonSchema, WorkflowLimits, WorkflowMeta, WorkflowPipelineStage, WorkflowStepOptions, WorkflowRunResult, WorkflowRunStatus, WorkflowRunSummary, WorkflowListRunsOptions, WorkflowRunsPage, WorkflowRunDetail, WorkflowProgressPage, WorkflowProgressLine, WorkflowPhaseObservation, WorkflowPhaseStatus, WorkflowAgentSummary, } from "./workflow.js";

package/dist/session.d.ts

@@ -1,7 +1,7 @@
 import { createSessionRpc } from "./generated/rpc.js";
 import type { ModelSwitchAutoTierResult } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
-import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, Tool, TranscriptRecovery, TypedSessionEventHandler } from "./types.js";
+import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TranscriptRecovery, TypedSessionEventHandler } from "./types.js";
 import { type SessionWorkflowApi } from "./workflow.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
@@ -417,7 +417,7 @@ export declare class CopilotSession {
      * ]);
      * ```
      */
-    setTools(tools: Tool[]): Promise<void>;
+    setTools(tools: NonNullable<SessionConfig["tools"]>): Promise<void>;
     /**
      * Log a message to the session timeline.
      * The message appears in the session event stream and is visible to SDK consumers

package/dist/session.js

@@ -29,7 +29,8 @@ function toToolDefinition(tool) {
     skipPermission: tool.skipPermission,
     defer: tool.defer,
     metadata: tool.metadata,
-    isTerminal: tool.isTerminal
+    isTerminal: tool.isTerminal,
+    namespace: tool.namespace
   };
 }
 const workflowExecutionStore = new AsyncLocalStorage();

package/dist/types.d.ts

@@ -6,14 +6,14 @@ import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { InstallationConfirmationHandler } from "./installationConfirmation.js";
 export type { InstallationConfirmationHandler } from "./installationConfirmation.js";
-import type { AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { AgentModelPolicy, AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 import type { JsonValue } from "./workflow.js";
-import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
+import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, ProtocolExternalToolNamespace, RemoteSessionMode, CurrentToolMetadata, SandboxConfig } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type { CurrentToolMetadata } from "./generated/rpc.js";
-export type { SandboxConfigSource } from "./generated/rpc.js";
+export type { SandboxConfig, SandboxConfigSource } from "./generated/rpc.js";
 export type { AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, ExtensionLaunchProfile, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, } from "./generated/rpc.js";
 /**
  * Arguments passed to a session's {@link GitHubTokenProvider}.
@@ -608,7 +608,29 @@ export interface Tool<TArgs = unknown> {
      * continue from.
      */
     isTerminal?: boolean;
+    /**
+     * Groups this tool with related tools for model tool discovery.
+     *
+     * On models and providers that support native tool namespaces, deferred
+     * tools sharing a namespace are presented to the model as one group with
+     * this name and description, like the tools of an MCP server. Elsewhere,
+     * and for tools that are always loaded, the tool stays a flat function.
+     * The tool keeps its own name, so calls still reach this tool's handler
+     * by name.
+     *
+     * @experimental
+     */
+    namespace?: ToolNamespace;
 }
+/**
+ * A namespace that groups related {@link Tool}s for model tool discovery.
+ * Tools sharing a name share a namespace. An invalid namespace is reported as a
+ * session warning and the tool is presented without it; a missing description
+ * defaults to a generic description of the namespace.
+ *
+ * @experimental
+ */
+export type ToolNamespace = ProtocolExternalToolNamespace;
 /**
  * Helper to define a tool with Zod schema and get type inference for the handler.
  * Without this helper, TypeScript cannot infer handler argument types from Zod schemas.
@@ -622,6 +644,7 @@ export declare function defineTool<T = unknown>(name: string, config: {
     defer?: "auto" | "never";
     metadata?: Record<string, unknown>;
     isTerminal?: boolean;
+    namespace?: ToolNamespace;
 }): Tool<T>;
 /**
  * Non-persisted opt-in to image generation.
@@ -636,6 +659,13 @@ export interface ImageGenerationConfig {
      * apply. BYOK image generation is not supported.
      */
     enabled?: boolean;
+    /**
+     * Request a visible "Made with AI" label on generated and edited images.
+     * Overrides the user's imageGenerationWatermark preference, which defaults
+     * to false. Re-supply after cold resume. Does not enable image generation
+     * or enforce enterprise policy.
+     */
+    watermark?: boolean;
 }
 /**
  * SDK-supplied override for the runtime's built-in tool-search behavior.
@@ -1645,9 +1675,15 @@ export interface CustomAgentConfig {
     /**
      * Model identifier for this agent (e.g. "claude-haiku-4.5").
      * When set, the runtime will attempt to use this model for the agent,
-     * falling back to the parent session model if unavailable.
+     * falling back to the parent session model if unavailable unless
+     * `modelPolicy` is `"required"`.
      */
     model?: string;
+    /**
+     * Whether the authored model is a preference or a requirement for this agent.
+     * Defaults to `"preferred"` when omitted.
+     */
+    modelPolicy?: AgentModelPolicy;
     /**
      * Reasoning effort level for this agent's model.
      * When omitted, the runtime resolves the effort from model configuration,
@@ -1735,6 +1771,10 @@ export type ReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
  * long-context tier when the selected model supports it.
  */
 export type ContextTier = "default" | "long_context";
+/**
+ * Scope of a working-directory trust grant made during session creation.
+ */
+export type WorkingDirectoryTrust = "session" | "user";
 /** Parsed parameters from an MCP server's WWW-Authenticate response. */
 export interface McpAuthWwwAuthenticateParams {
     /** Parsed resource_metadata URL used for protected-resource metadata discovery, if present. */
@@ -2521,6 +2561,14 @@ export interface SessionConfigBase {
      * this on a resident resume cannot stop servers that are already running.
      */
     disabledMcpServers?: string[];
+    /**
+     * Sandbox configuration applied before MCP servers or session tools start.
+     * Uses the same direct-host semantics and managed-policy validation as
+     * `session.rpc.options.update({ sandboxConfig })`. A policy conflict fails
+     * create or resume; an identical later update does not restart MCP servers.
+     * Re-supply on cold resume. Requires runtime-version support.
+     */
+    sandboxConfig?: SandboxConfig;
     /**
      * Infinite session configuration for persistent workspaces and automatic compaction.
      * When enabled (default), sessions automatically manage context limits and persist state.
@@ -2636,13 +2684,6 @@ export interface SessionConfigBase {
      * read from the shared session store.
      */
     enableSessionStore?: boolean;
-    /**
-     * When true, requests the read-only GitHub cache store for this session
-     * (the `github-cache-store` capability). The runtime registers the
-     * `github_sql` tool only when its `GITHUB_CACHE_STORE` feature flag is
-     * also on. Defaults to disabled.
-     */
-    enableGitHubCacheStore?: boolean;
     /**
      * When true, enables skill loading (including builtin skills and discovered
      * skill directories). When false, no skills are loaded regardless of
@@ -2693,6 +2734,12 @@ export interface SessionConfig extends SessionConfigBase {
      * Local sessions only: cloud creation rejects it.
      */
     name?: string;
+    /**
+     * Grants trust to the canonical working directory during session creation.
+     * "session" applies only to this session; "user" persists the grant for later
+     * sessions. Omit to leave directory trust unchanged. Not available on resume.
+     */
+    trustWorkingDirectory?: WorkingDirectoryTrust;
     /**
      * Invalidates the process-wide custom-instruction discovery cache before
      * creating this session. Use when instruction files changed in the same runtime.
@@ -2831,6 +2878,12 @@ export interface ProviderConfig {
      * API key. Optional for local providers like Ollama.
      */
     apiKey?: string;
+    /**
+     * Command run by the runtime before each provider request to obtain a fresh API key.
+     * Command failures fail the turn before sending a model request.
+     * Bearer authentication takes precedence; use {@link apiKey} for a static key.
+     */
+    apiKeyCommand?: string;
     /**
      * Bearer token for authentication. Sets the Authorization header directly.
      * Use this for services requiring bearer token auth instead of API key.
@@ -2842,10 +2895,10 @@ export interface ProviderConfig {
      * When set, the SDK keeps this function client-side (it is never serialized)
      * and the runtime calls back into this client to acquire a token before each
      * outbound request. The runtime does no caching of its own, so the callback
-     * owns token caching and refresh. When set alongside {@link apiKey} /
-     * {@link bearerToken}, this callback takes precedence: the runtime applies
-     * the token it returns as the `Authorization: Bearer` header for each
-     * request and does not send the static credential.
+     * owns token caching and refresh. When set alongside {@link apiKey},
+     * {@link apiKeyCommand}, or {@link bearerToken}, this callback takes precedence:
+     * the runtime applies its token as the `Authorization: Bearer` header for each
+     * request, without sending the static credential or running the command.
      *
      * @experimental
      */

package/docs/workflows.md

@@ -102,7 +102,13 @@ if (!finding) return { finding: null };
 
 Cancellation and hard runtime failures — a reached limit, a durable-state failure — reject instead, aborting the run. When filtering results, prefer `v => v !== null` over `Boolean`, which also discards a valid `false`, `0`, or `""`.
 
-**`schema` is a structural subset of JSON Schema, not a validator.** Honored: `type`, `required`, `enum`, `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf` — where `oneOf` is treated as `anyOf`, meaning at least one branch matches rather than exactly one. Ignored and *not* enforced: `additionalProperties`, `pattern`, `minLength`/`maxLength`, `format`, numeric ranges, and boolean schemas. Do not rely on an ignored keyword to constrain a result. A schema call retries once on a parse or match failure, so it may spawn twice, and both spawns count toward `maxTotalSubagents`.
+**`schema` is a structural subset of JSON Schema, not a validator.** Honored: `type`, `required`, `enum`, `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf` — where `oneOf` is treated as `anyOf`, meaning at least one branch matches rather than exactly one. Ignored and *not* enforced: `additionalProperties`, `pattern`, `minLength`/`maxLength`, `format`, numeric ranges, and boolean schemas. Do not rely on an ignored keyword to constrain a result.
+
+The runtime always parses and validates the returned JSON against that workflow subset. On a parse or match failure, it sends up to two correction turns to the same subagent; it does not spawn replacement subagents or repeat the original task.
+
+Eligible local first-party model routes also use provider-native structured output to strengthen generation. Native selection fails closed: the selected CAPI model must explicitly report structured-output support, the wire route must support native formats, and the schema must fit a conservative provider subset. That subset requires an object root, typed nodes, non-empty object properties, every property listed in `required`, `additionalProperties: false` on every object, object-shaped array items, and bounded depth, property count, enum size, and serialized size. It accepts nested `anyOf`, descriptions, and enums, but rejects root `anyOf`, references, boolean schemas, `allOf`, `oneOf`, `const`, and other unsupported keywords.
+
+AHP subagents, HydraFusion-selected children, BYOK providers, models without the capability, unknown routes, and schemas outside the native subset keep prompt-based JSON coercion. They retain the same parsing, validation, and same-agent correction behavior, so workflow authors use one `ctx.agent(..., { schema })` API regardless of the selected path.
 
 ### Choosing between pipeline and parallel
 

package/package.json

@@ -5,8 +5,8 @@
         "url": "https://github.com/github/copilot-agent-runtime.git",
         "directory": "src/sdk/nodejs"
     },
-    "version": "1.0.23",
-    "copilotCliVersion": "1.0.100",
+    "version": "1.0.24-preview.1",
+    "copilotCliVersion": "1.0.101-1",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -87,15 +87,17 @@
         "glob": "^13.0.1",
         "json-schema": "^0.4.0",
         "json-schema-to-typescript": "^15.0.4",
+        "jsonc-parser": "^3.3.1",
         "prettier": "file:../../../third_party/build-tools/prettier-3.8.1",
         "rimraf": "^6.1.2",
         "semver": "^7.7.3",
         "tar": "^7.5.22",
-        "tsx": "file:../../../third_party/build-tools/tsx-4.22.4",
+        "tsx": "file:../../../third_party/build-tools/tsx-4.23.13",
         "typescript": "^5.0.0",
         "vite": "file:../../../third_party/build-tools/vite-8.3.4",
         "vitest": "^4.1.11",
-        "ws": "^8.21.0"
+        "ws": "^8.21.0",
+        "yaml": "^2.8.3"
     },
     "overrides": {
         "file-entry-cache": "$file-entry-cache",
@@ -112,18 +114,18 @@
         "README.md"
     ],
     "copilotRuntime": {
-        "sourceSha": "7d20899fc4c8b13a405aa621066e75a9e78e04cd",
-        "version": "1.0.100",
+        "sourceSha": "01c5befcd0b26b1b4b0a7fce219cf441b8ae2ae1",
+        "version": "1.0.101-1",
         "visibility": "public"
     },
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.23",
-        "@github/copilot-sdk-darwin-x64": "1.0.23",
-        "@github/copilot-sdk-linux-arm64": "1.0.23",
-        "@github/copilot-sdk-linux-x64": "1.0.23",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.23",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.23",
-        "@github/copilot-sdk-win32-arm64": "1.0.23",
-        "@github/copilot-sdk-win32-x64": "1.0.23"
+        "@github/copilot-sdk-darwin-arm64": "1.0.24-preview.1",
+        "@github/copilot-sdk-darwin-x64": "1.0.24-preview.1",
+        "@github/copilot-sdk-linux-arm64": "1.0.24-preview.1",
+        "@github/copilot-sdk-linux-x64": "1.0.24-preview.1",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.24-preview.1",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.24-preview.1",
+        "@github/copilot-sdk-win32-arm64": "1.0.24-preview.1",
+        "@github/copilot-sdk-win32-x64": "1.0.24-preview.1"
     }
 }