@github/copilot-sdk 1.0.29 → 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,20 +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;
       }
       let message = error instanceof Error ? error.message : String(error);
       if (!message) {
         message = error instanceof Error && error.name || "Error";
       }
-      try {
-        await this.rpc.tools.handlePendingToolCall({ requestId, error: message });
-      } catch (rpcError) {
-        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
-          throw rpcError;
+      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 {
@@ -1894,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

@@ -184,7 +184,7 @@ 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
 

package/docs/examples.md

@@ -25,7 +25,8 @@ const session = await joinSession({
 >
 > - Use `process.platform === "win32"` to detect Windows at runtime.
 > - Clipboard: `pbcopy` on macOS, `clip` on Windows.
-> - Use `exec()` instead of `execFile()` for `.cmd` scripts like `code`, `npx`, `npm` on Windows.
+> - Never interpolate tool arguments into `exec()` or shell command strings. Use `execFile()` or `spawn()` with argument arrays.
+> - On Windows, `.cmd` and `.bat` wrappers require a shell. Invoke the actual executable or use the library's Node.js API instead.
 > - PowerShell stderr redirection uses `*>&1` instead of `2>&1`.
 
 ---
@@ -257,16 +258,41 @@ hooks: {
 
 Use `onPostToolUse` to run side effects after a tool completes.
 
+On macOS and Linux, install the `code` command in your `PATH`. On Windows,
+set `VSCODE_EXECUTABLE` to the absolute path of your installed `Code.exe`
+(for example, `C:\Users\you\AppData\Local\Programs\Microsoft VS Code\Code.exe`),
+not the `code.cmd` wrapper. This is trusted extension configuration, not a
+tool argument.
+
 ```js
-import { exec } from "node:child_process";
+import { spawn } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+
+const isWindows = process.platform === "win32";
+const vscodeExecutable = isWindows ? process.env.VSCODE_EXECUTABLE : "code";
+if (!vscodeExecutable || (isWindows && !isAbsolute(vscodeExecutable))) {
+    throw new Error("Set VSCODE_EXECUTABLE to the absolute path of Code.exe.");
+}
+const editorEnv = { ...process.env };
+// The native editor must open the file, not run it as a Node.js script.
+delete editorEnv.ELECTRON_RUN_AS_NODE;
 
 hooks: {
     onPostToolUse: async (input) => {
         if (input.toolName === "create" || input.toolName === "edit") {
             const filePath = input.toolArgs?.path;
-            if (filePath) {
-                // Open the file in VS Code
-                exec(`code "${filePath}"`, () => {});
+            if (typeof filePath === "string" && filePath) {
+                try {
+                    const child = spawn(vscodeExecutable, [resolve(filePath)], {
+                        detached: true,
+                        stdio: "ignore",
+                        env: editorEnv,
+                    });
+                    child.on("error", (err) => console.error("Could not open file in VS Code:", err.message));
+                    child.unref();
+                } catch (err) {
+                    console.error("Could not open file in VS Code:", err.message);
+                }
             }
         }
     },
@@ -295,20 +321,34 @@ hooks: {
 
 ### Running a linter after every file edit
 
+Install ESLint in the session's working directory (`npm install --save-dev eslint`)
+and configure it for TypeScript. Only run this hook in workspaces whose ESLint
+configuration and plugins you trust. Use its Node.js API rather than `npx`:
+an extension's `process.execPath` can be the Copilot single-executable binary,
+not a general-purpose Node.js interpreter.
+
 ```js
-import { exec } from "node:child_process";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
 
 hooks: {
     onPostToolUse: async (input) => {
         if (input.toolName === "edit") {
             const filePath = input.toolArgs?.path;
-            if (filePath?.endsWith(".ts")) {
-                const result = await new Promise((resolve) => {
-                    exec(`npx eslint "${filePath}"`, (err, stdout) => {
-                        resolve(err ? stdout : "No lint errors.");
-                    });
-                });
-                return { additionalContext: `Lint result: ${result}` };
+            if (typeof filePath === "string" && filePath.endsWith(".ts")) {
+                try {
+                    const eslintModule = require.resolve("eslint", { paths: [process.cwd()] });
+                    const { ESLint } = await import(pathToFileURL(eslintModule).href);
+                    const eslint = new ESLint({ cwd: process.cwd(), globInputPaths: false });
+                    const results = await eslint.lintFiles([resolve(filePath)]);
+                    const formatter = await eslint.loadFormatter("stylish");
+                    return { additionalContext: `Lint result: ${formatter.format(results) || "No lint errors."}` };
+                } catch (err) {
+                    return { additionalContext: `Lint failed: ${err.message}` };
+                }
             }
         }
     },
@@ -603,11 +643,22 @@ const session = await joinSession({
 
 An extension that combines tools, hooks, and events.
 
+Use the same VS Code setup as in
+[Reacting when the agent creates or edits a file](#reacting-when-the-agent-creates-or-edits-a-file).
+
 ```js
-import { execFile, exec } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
 import { joinSession } from "@github/copilot-sdk/extension";
 
 const isWindows = process.platform === "win32";
+const vscodeExecutable = isWindows ? process.env.VSCODE_EXECUTABLE : "code";
+if (!vscodeExecutable || (isWindows && !isAbsolute(vscodeExecutable))) {
+    throw new Error("Set VSCODE_EXECUTABLE to the absolute path of Code.exe.");
+}
+const editorEnv = { ...process.env };
+// The native editor must open the file, not run it as a Node.js script.
+delete editorEnv.ELECTRON_RUN_AS_NODE;
 let copyNextResponse = false;
 
 function copyToClipboard(text) {
@@ -617,8 +668,17 @@ function copyToClipboard(text) {
 }
 
 function openInEditor(filePath) {
-    if (isWindows) exec(`code "${filePath}"`, () => {});
-    else execFile("code", [filePath], () => {});
+    try {
+        const child = spawn(vscodeExecutable, [resolve(filePath)], {
+            detached: true,
+            stdio: "ignore",
+            env: editorEnv,
+        });
+        child.on("error", (err) => console.error("Could not open file in VS Code:", err.message));
+        child.unref();
+    } catch (err) {
+        console.error("Could not open file in VS Code:", err.message);
+    }
 }
 
 const session = await joinSession({
@@ -645,7 +705,7 @@ const session = await joinSession({
         onPostToolUse: async (input) => {
             if (input.toolName === "create" || input.toolName === "edit") {
                 const filePath = input.toolArgs?.path;
-                if (filePath) openInEditor(filePath);
+                if (typeof filePath === "string" && filePath) openInEditor(filePath);
             }
         },
     },