@github/copilot-sdk 1.0.29-preview.9 → 1.0.30-preview.0

package/dist/session.d.ts

@@ -1,5 +1,5 @@
 import { createSessionRpc } from "./generated/rpc.js";
-import type { ModelSwitchAutoTierResult, SessionManagementPolicy } from "./generated/rpc.js";
+import type { ModelSwitchAutoTierResult, PermissionsSetModeResult, SessionManagementPolicy } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
 import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, SessionCreationHandler, TranscriptRecovery, TypedSessionEventHandler } from "./types.js";
 import { type SessionWorkflowApi } from "./workflow.js";
@@ -38,10 +38,11 @@ export type AssistantMessageEvent = Extract<SessionEvent, {
  * `overridesBuiltInTool: true`.
  */
 export declare class CopilotSession {
-    readonly sessionId: string;
+    private _sessionId;
     private connection;
     private _workspacePath?;
     private _transcriptRecovery?;
+    private _permissionModeResult?;
     private eventHandlers;
     private typedEventHandlers;
     private toolHandlers;
@@ -62,6 +63,7 @@ export declare class CopilotSession {
     private autoModeSwitchHandler?;
     private skillProvider?;
     private sessionCreationHandler?;
+    private memoryStoreHandler?;
     private hooks?;
     private transformCallbacks?;
     private _rpc;
@@ -95,6 +97,7 @@ export declare class CopilotSession {
      * dropped invalidation from leaving the wait pending forever.
      */
     private waitForWorkflowRun;
+    get sessionId(): string;
     /**
      * Typed session-scoped RPC methods.
      */
@@ -107,6 +110,12 @@ export declare class CopilotSession {
     get workspacePath(): string | undefined;
     /** Recovery observed while loading this session; undefined on a clean resume. */
     get transcriptRecovery(): TranscriptRecovery | undefined;
+    /**
+     * Outcome of the `permissionMode` requested when this session was created
+     * or resumed: whether it was applied, and the authoritative mode the
+     * session started in. Undefined when no mode was requested.
+     */
+    get permissionModeResult(): PermissionsSetModeResult | undefined;
     /**
      * Host capabilities reported when the session was created or resumed.
      * Use this to check feature support before calling capability-gated APIs.

package/dist/session.js

@@ -270,8 +270,8 @@ class CopilotSession {
    * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
    * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
    */
-  constructor(sessionId, connection, _workspacePath, traceContextProvider, options) {
-    this.sessionId = sessionId;
+  constructor(_sessionId, connection, _workspacePath, traceContextProvider, options) {
+    this._sessionId = _sessionId;
     this.connection = connection;
     this._workspacePath = _workspacePath;
     this.traceContextProvider = traceContextProvider;
@@ -279,10 +279,11 @@ class CopilotSession {
     this.managedSettingsEnabled = options?.managedSettingsEnabled === true;
     this.onDisconnected = options?.onDisconnected;
   }
-  sessionId;
+  _sessionId;
   connection;
   _workspacePath;
   _transcriptRecovery;
+  _permissionModeResult;
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
@@ -303,6 +304,7 @@ class CopilotSession {
   autoModeSwitchHandler;
   skillProvider;
   sessionCreationHandler;
+  memoryStoreHandler;
   hooks;
   transformCallbacks;
   _rpc = null;
@@ -455,6 +457,15 @@ class CopilotSession {
       void read();
     });
   }
+  get sessionId() {
+    return this._sessionId;
+  }
+  /** @internal */
+  _setSessionId(sessionId) {
+    this._sessionId = sessionId;
+    this._rpc = null;
+    this._internalRpc = null;
+  }
   /**
    * Typed session-scoped RPC methods.
    */
@@ -487,6 +498,18 @@ class CopilotSession {
   setTranscriptRecovery(recovery) {
     this._transcriptRecovery = recovery;
   }
+  /**
+   * Outcome of the `permissionMode` requested when this session was created
+   * or resumed: whether it was applied, and the authoritative mode the
+   * session started in. Undefined when no mode was requested.
+   */
+  get permissionModeResult() {
+    return this._permissionModeResult;
+  }
+  /** @internal */
+  setPermissionModeResult(result) {
+    this._permissionModeResult = result;
+  }
   /**
    * Host capabilities reported when the session was created or resumed.
    * Use this to check feature support before calling capability-gated APIs.
@@ -535,6 +558,7 @@ class CopilotSession {
       prompt: options.prompt,
       source: options.source,
       displayPrompt: options.displayPrompt,
+      clientTurnId: options.clientTurnId,
       attachments: options.attachments,
       mode: options.mode,
       agentMode: options.agentMode,
@@ -894,6 +918,7 @@ class CopilotSession {
       controller.abort();
     }
     this.pendingSessionCreations.clear();
+    this._clearMemoryStore();
     this.eventHandlers.clear();
     this.typedEventHandlers.clear();
     this.toolHandlers.clear();
@@ -905,6 +930,7 @@ class CopilotSession {
     this.autoModeSwitchHandler = void 0;
     this.skillProvider = void 0;
     this.sessionCreationHandler = void 0;
+    this.memoryStoreHandler = void 0;
     this.hooks = void 0;
     this.traceContextProvider = void 0;
     this.bearerTokenProviders.clear();
@@ -1122,6 +1148,7 @@ class CopilotSession {
       return;
     }
     this.pendingExternalTools.set(requestId, controller);
+    let claimed = false;
     try {
       let availableTools;
       if (toolName === TOOL_SEARCH_TOOL_NAME) {
@@ -1178,17 +1205,45 @@ class CopilotSession {
       if (!this._claimExternalTool(requestId, controller)) {
         return;
       }
+      claimed = true;
       await this.rpc.tools.handlePendingToolCall({ requestId, result });
     } catch (error) {
-      if (!this._claimExternalTool(requestId, controller)) {
+      if (claimed) {
+        if (this.disconnected) {
+          return;
+        }
+        console.error("External tool result delivery failed", {
+          sessionId: this.sessionId,
+          requestId,
+          toolName,
+          error
+        });
+      } else if (!this._claimExternalTool(requestId, controller)) {
         return;
       }
-      const message = error instanceof Error ? error.message : String(error);
-      try {
-        await this.rpc.tools.handlePendingToolCall({ requestId, error: message });
-      } catch (rpcError) {
-        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
-          throw rpcError;
+      let message = error instanceof Error ? error.message : String(error);
+      if (!message) {
+        message = error instanceof Error && error.name || "Error";
+      }
+      for (let attempt = 0; attempt < (claimed ? 1 : 2); attempt++) {
+        try {
+          await this.rpc.tools.handlePendingToolCall({ requestId, error: message });
+          return;
+        } catch (rpcError) {
+          const retryable = !claimed && attempt === 0 && !this.disconnected;
+          if (!retryable) {
+            if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+              throw rpcError;
+            }
+            return;
+          }
+          console.error("External tool error delivery failed", {
+            sessionId: this.sessionId,
+            requestId,
+            toolName,
+            error: rpcError
+          });
+          message = (rpcError instanceof Error ? rpcError.message || rpcError.name : "") || String(rpcError) || "Error";
         }
       }
     } finally {
@@ -1891,6 +1946,43 @@ class CopilotSession {
       throw error;
     }
   }
+  /**
+   * Registers the callback the runtime calls through `memoryStore.store`.
+   * Registered before create or resume declares `hasMemoryStore`.
+   * @internal
+   */
+  _registerMemoryStore(handler) {
+    this.assertConnected();
+    this.memoryStoreHandler = handler;
+  }
+  /** @internal */
+  _clearMemoryStore() {
+    this.memoryStoreHandler = void 0;
+  }
+  /** @internal */
+  async _handleMemoryStore(memory, signal) {
+    this.assertConnected();
+    const handler = this.memoryStoreHandler;
+    if (!handler) throw new Error("No memory store is registered");
+    try {
+      await handler(
+        {
+          sessionId: memory.sessionId,
+          subject: memory.subject,
+          fact: memory.fact,
+          citations: memory.citations,
+          reason: memory.reason
+        },
+        { signal }
+      );
+    } catch (error) {
+      if (signal.aborted) {
+        throw new ResponseError(-32800, "Memory store call cancelled");
+      }
+      console.warn("Memory store callback failed", error);
+      throw new Error("Memory store callback failed");
+    }
+  }
   /** @internal */
   async _handleSessionManagementCreate(request, token) {
     this.assertConnected();

package/dist/types.d.ts

@@ -6,12 +6,12 @@ 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 { AgentModelPolicy, AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, ModelProviderRef, 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, ModelProviderRef, PermissionMode, 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, AutopilotOptions, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, HostDiagnostics, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, ProtocolExternalToolNamespace, CurrentToolMetadata, KerberosAuthAcquireRequest, KerberosAuthMode, KerberosAuthScope, SandboxConfig, SessionManagementCreateHostRequest, SessionManagementCreateResult } from "./generated/rpc.js";
+import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, AutopilotOptions, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, HostDiagnostics, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, ProtocolExternalToolNamespace, CurrentToolMetadata, NetworkAuthenticateNegotiateRequest, NetworkResolveProxyRequest, NetworkScope, SandboxConfig, SessionManagementCreateHostRequest, SessionManagementCreateResult } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
-export type { KerberosAuthAcquireRequest, KerberosAuthMode, KerberosAuthScope, } from "./generated/rpc.js";
+export type { NetworkAuthenticateNegotiateRequest, NetworkResolveProxyRequest, NetworkScope, } from "./generated/rpc.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type { AutopilotOptions } from "./generated/rpc.js";
 export type { CurrentToolMetadata } from "./generated/rpc.js";
@@ -341,9 +341,11 @@ export interface CopilotClientOptions {
      */
     extensionLaunchProvider?: ExtensionLaunchProvider;
     /**
-     * Supplies Kerberos credentials from the SDK host. Registered before sessions start.
+     * Network callbacks through which the SDK host decides the runtime's proxies and supplies its
+     * Kerberos tokens. Registered before sessions start.
+     * @experimental
      */
-    kerberosAuth?: KerberosAuthConfig;
+    network?: NetworkConfig;
     /**
      * Connection-global human review for experimental installation operations.
      * Does not register or enable installation capabilities on the runtime.
@@ -473,25 +475,49 @@ export interface CopilotClientOptions {
 }
 /** Resolves launch profiles for extension entrypoints discovered by the runtime. */
 export type ExtensionLaunchProvider = GeneratedExtensionLaunchProvider;
-/** Supplies Kerberos credentials from the SDK host for a requested service principal. */
-export interface KerberosAuthConfig {
-    /** `fallback` uses the callback only when native lookup fails; `always` never attempts native lookup. */
-    mode: KerberosAuthMode;
+/**
+ * Network callbacks through which the SDK host takes over parts of the runtime's networking, for
+ * example when the runtime runs in WSL or a container and should use VS Code's proxy settings and
+ * the host's Kerberos tickets. Each registered callback replaces the runtime's own handling for the
+ * traffic in {@link NetworkConfig.scope}; without it, the runtime handles that part itself.
+ *
+ * Each callback receives a `signal` that aborts when the runtime stops waiting: it cancels the
+ * request (for example when its wait times out) or the connection closes. The SDK then stops
+ * awaiting the callback and ignores any later result.
+ * @experimental
+ */
+export interface NetworkConfig {
     /**
-     * `connection` (the default) authenticates only requests made for sessions this client creates or resumes;
-     * `runtime` also authenticates the runtime's shared background traffic. Only one connection at a time can
+     * `connection` (the default) serves only requests made for sessions this client creates or resumes;
+     * `runtime` also serves the runtime's shared background traffic. Only one connection at a time can
      * hold `runtime` scope, so startup fails if another client holds it. The registration ends when the
      * connection closes.
      */
-    scope?: KerberosAuthScope;
+    scope?: NetworkScope;
     /**
-     * Returns a fresh, single-use base64 SPNEGO token without the `Negotiate ` prefix, or `undefined` when unavailable.
-     * The SPN uses the platform-independent `service/host[@REALM]` form; validate it before issuing credentials.
-     * `signal` aborts when the runtime stops waiting: it cancels the request (for example when its wait times
-     * out) or the connection closes. The SDK then stops awaiting the callback and ignores any later result,
-     * so pass `signal` to credential lookups that support cancellation.
+     * Returns the proxies for `request.url` as a PAC-style list such as
+     * `PROXY proxy.example:8080; HTTPS proxy.example:443; DIRECT` (the format of Electron's
+     * `session.resolveProxy`); return `DIRECT` for a direct connection, or `undefined` to let the runtime
+     * resolve the proxy itself, as if no callback were registered. Entry types the runtime doesn't
+     * support, such as SOCKS and QUIC, are skipped.
+     * `request.url` is the request target as a PAC script sees it: without credentials or fragment, and for
+     * `https` and `wss` also without path and query.
+     *
+     * The callback decides every request that would otherwise follow ambient proxy settings: proxy
+     * environment variables, `NO_PROXY` and operating-system proxy settings are not consulted unless it
+     * returns `undefined`, and a failing callback fails the request rather than connecting directly.
+     * Requests to loopback targets, and requests with an explicitly configured proxy, never consult it. The
+     * runtime caches answers, including `undefined`, for a few seconds.
+     */
+    resolveProxy?: (request: NetworkResolveProxyRequest, signal: AbortSignal) => Promise<string | undefined>;
+    /**
+     * Returns a fresh, single-use base64 SPNEGO token without the `Negotiate ` prefix for a proxy's Negotiate
+     * challenge, or `undefined` when unavailable. The runtime then does not look up Kerberos credentials
+     * itself, so a missing token or a failing callback fails the request.
+     * The SPN uses the platform-independent `service/host[@REALM]` form; validate it before issuing
+     * credentials. Never log or persist tokens.
      */
-    callback: (request: KerberosAuthAcquireRequest, signal: AbortSignal) => Promise<string | undefined>;
+    authenticateNegotiate?: (request: NetworkAuthenticateNegotiateRequest, signal: AbortSignal) => Promise<string | undefined>;
 }
 /**
  * Configuration for creating a session
@@ -816,6 +842,8 @@ export interface SessionCapabilities {
         mcpApps?: boolean;
         /** Whether the host supports canvas rendering. */
         canvases?: boolean;
+        /** Whether the runtime acknowledges retained-request Auto recovery. Absence means unsupported. */
+        autoModeRecovery?: boolean;
     };
 }
 /**
@@ -1251,13 +1279,26 @@ export type ExitPlanModeHandler = (request: ExitPlanModeRequest, invocation: {
     sessionId: string;
 }) => Promise<ExitPlanModeResult> | ExitPlanModeResult;
 /**
- * Request to switch to auto mode after an eligible rate limit.
+ * Context for an offer to recover the active request using Auto.
+ */
+export interface AutoModeRecoveryContext {
+    requestId: string;
+    originalModel: string;
+    /** Whether this offer permits remembering consent. Currently true only for per-model rate limits. */
+    allowAlways: boolean;
+    interactionId?: string;
+    originatingMessageId?: string;
+}
+/**
+ * Request to switch to Auto after a rate limit or recover an eligible active request.
  */
 export interface AutoModeSwitchRequest {
-    /** The rate-limit error code that triggered the request. */
+    /** The upstream error code that triggered the request. */
     errorCode?: string;
     /** Seconds until the rate limit resets, when known. */
     retryAfterSeconds?: number;
+    /** Present only for retained-request recovery, not legacy future-message switching. */
+    autoModeRecovery?: AutoModeRecoveryContext;
 }
 /**
  * Response to an auto-mode-switch request.
@@ -1334,7 +1375,9 @@ export interface PreMcpToolCallHookOutput {
      * Hook-controlled metadata to use for the outgoing MCP request.
      * - undefined/absent: preserve the current request `_meta`
      * - object: use this object as request `_meta`
-     * - null: omit `_meta`
+     * - null: drop hook-controlled `_meta`; the runtime still sends its own keys,
+     *   `com.github.copilot/toolCallId` and `com.github.copilot/turnId` (present only
+     *   when the turn was started with a `clientTurnId`)
      */
     metaToUse?: Record<string, unknown> | null;
 }
@@ -1848,6 +1891,46 @@ export interface MemoryConfiguration {
      * @experimental This option may change or be removed in a future release.
      */
     mode?: "system-prompt" | "user-prompt";
+    /**
+     * Stores memories in the app instead of the built-in memory backends.
+     *
+     * The runtime validates the memory, filters secrets and requests approval,
+     * then calls this callback. `store_memory` succeeds only after the returned
+     * promise resolves; a rejection fails the tool call with a generic message
+     * and nothing is stored elsewhere. `options.signal` aborts when the runtime
+     * stops waiting, for example after its 60-second timeout. While set, the
+     * runtime retrieves no memories and `vote_memory` is unavailable, so supply
+     * recall yourself, for example through `systemMessage`.
+     * @experimental This option may change or be removed in a future release.
+     */
+    storeMemory?: (memory: StoredMemory, options: MemoryStoreCallOptions) => Promise<void>;
+}
+/**
+ * Per-call options passed to {@link MemoryConfiguration.storeMemory}.
+ * @experimental This type may change or be removed in a future release.
+ */
+export interface MemoryStoreCallOptions {
+    /**
+     * Aborted when the runtime cancels the call, for example when it times out
+     * or the session disconnects. The runtime ignores any later result.
+     */
+    signal: AbortSignal;
+}
+/**
+ * A memory the agent asked to store, after validation, secret filtering and approval.
+ * @experimental This type may change or be removed in a future release.
+ */
+export interface StoredMemory {
+    /** ID of the session that stored the memory. */
+    sessionId: string;
+    /** Short topic the memory is about. */
+    subject: string;
+    /** The fact to remember. */
+    fact: string;
+    /** Sources supporting the fact, such as file paths with line numbers. */
+    citations: string;
+    /** Why the agent considers the fact worth remembering. */
+    reason: string;
 }
 /**
  * Configuration for handling large tool outputs.
@@ -1864,7 +1947,8 @@ export interface LargeToolOutputConfig {
     enabled?: boolean;
     /**
      * Maximum size in bytes before output is written to a temp file.
-     * @default 51200
+     * Uses the runtime's configured threshold when unset.
+     * @default 20480
      */
     maxSizeBytes?: number;
     /**
@@ -2182,6 +2266,12 @@ export interface SkillProviderCallOptions {
  * an existing one).
  */
 export interface SessionConfigBase {
+    /**
+     * Whether the model may request multiple tool calls per response. Defaults to true.
+     * False sends a provider hint, not an execution guarantee: all returned calls
+     * are still handled and handlers may run concurrently. Re-supply on cold resume.
+     */
+    allowMultipleToolCalls?: boolean;
     /** Exact model IDs allowed by the host. Omission preserves runtime policy. */
     allowedModels?: string[];
     /**
@@ -2535,6 +2625,15 @@ export interface SessionConfigBase {
      * When provided, enables `autoModeSwitch.request` callbacks.
      */
     onAutoModeSwitchRequest?: AutoModeSwitchHandler;
+    /**
+     * Opt in to runtime-owned recovery of an eligible active request using Auto.
+     * Requires `onAutoModeSwitchRequest` and a runtime acknowledgment in
+     * `session.capabilities.ui.autoModeRecovery`; unsupported enrollment rejects
+     * create/resume and detaches the session. Re-supply when resuming.
+     * Consent has no runtime deadline. The handler must not resend or rewind.
+     * @default false
+     */
+    autoModeRecovery?: boolean;
     /**
      * Hook handlers for intercepting session lifecycle events.
      * When provided, enables hooks callback allowing custom logic at various points.
@@ -2752,6 +2851,16 @@ export interface SessionConfigBase {
      * for cloud sessions and when resuming a session that is already active.
      */
     interactiveUser?: boolean;
+    /**
+     * Permission mode applied before the session's first turn: before
+     * `createSession` returns, and before a resume continues pending work.
+     * Uses the same checks as `session.rpc.permissions.setMode`; a mode that
+     * managed policy or session capabilities refuse leaves the current mode in
+     * place. `session.permissionModeResult` reports whether it was applied and
+     * the authoritative mode. Omit to keep the default mode on create, or the
+     * restored mode on resume. Not supported for cloud sessions.
+     */
+    permissionMode?: PermissionMode;
     /**
      * Host-injected enterprise managed settings for this session.
      *
@@ -3271,6 +3380,16 @@ export interface MessageOptions {
      * If provided, this is shown in the timeline instead of `prompt`.
      */
     displayPrompt?: string;
+    /**
+     * Opaque caller-chosen ID for the turn this message starts. The runtime copies it unchanged
+     * into `_meta["com.github.copilot/turnId"]` on every MCP `tools/call` made while serving that
+     * turn, including calls from sub-agents and Autopilot continuations. When a running turn
+     * consumes the message as visible user steering, the value (or its absence) replaces the
+     * turn's ID from the next model call onward. The `user.message` event for the message echoes
+     * it as `clientTurnId` and is persisted like other events; the value stamped on MCP calls is
+     * held in memory only and is not restored on resume.
+     */
+    clientTurnId?: string;
     /**
      * JSON Schema or a Zod schema for this run's output, including requests after tool calls.
      * Independent sends do not inherit it. Ordinary immediate steering retains the active

package/docs/agent-author.md

@@ -131,6 +131,7 @@ hooks: {
 ```
 
 All hook inputs include `sessionId`, `timestamp` (`Date`) and `workingDirectory`.
+Tool hooks also receive `toolCallId` when the runtime supplies one; correlate a call's hooks with `(input.sessionId, input.toolCallId)`.
 All handlers receive `invocation: { sessionId: string }` as the second argument.
 All handlers may return `void`/`undefined` (no-op) or an output object.
 
@@ -162,7 +163,7 @@ runtime-generated context.
 
 ### onPreToolUse
 
-**Input:** `{ toolName: string, toolArgs: unknown, timestamp, workingDirectory }`
+**Input:** `{ toolCallId?: string, toolName: string, toolArgs: unknown, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -183,11 +184,11 @@ object sent with the request; to allow, deny or change the call itself, use
 **Output (all fields optional):**
 | Field | Type | Effect |
 |-------|------|--------|
-| `metaToUse` | `Record<string, unknown> \| null` | An object becomes the request's `_meta`; `null` omits it; leaving it out keeps the current `_meta` |
+| `metaToUse` | `Record<string, unknown> \| null` | An object becomes the request's `_meta`; `null` omits it, except for the runtime's `com.github.copilot/toolCallId` and `com.github.copilot/turnId` keys; leaving it out keeps the current `_meta` |
 
 ### onPostToolUse
 
-**Input:** `{ toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, workingDirectory }`
+**Input:** `{ toolCallId?: string, toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, workingDirectory }`
 
 Fires only when the tool returned a successful result. To observe non-success
 outcomes, register `onPostToolUseFailure` as well.
@@ -200,7 +201,7 @@ outcomes, register `onPostToolUseFailure` as well.
 
 ### onPostToolUseFailure
 
-**Input:** `{ toolName: string, toolArgs: unknown, error: string, timestamp, workingDirectory }`
+**Input:** `{ toolCallId?: string, toolName: string, toolArgs: unknown, error: string, timestamp, workingDirectory }`
 
 Fires after a tool execution whose result was `"failure"`. `onPostToolUse`
 does **not** fire for these outcomes, so register this handler to observe or