@github/copilot-sdk 1.0.11 → 1.0.12-unstable.0

package/dist/cjs/client.js

@@ -217,9 +217,9 @@ function getBundledCliPath() {
   if (typeof import_meta.resolve === "function") {
     for (const packageName of packageNames) {
       try {
-        const sdkUrl = import_meta.resolve(`${packageName}/sdk`);
-        const sdkPath = (0, import_node_url.fileURLToPath)(sdkUrl);
-        return (0, import_node_path.join)((0, import_node_path.dirname)((0, import_node_path.dirname)(sdkPath)), "index.js");
+        const packageEntryUrl = import_meta.resolve(packageName);
+        const packageEntryPath = (0, import_node_url.fileURLToPath)(packageEntryUrl);
+        return (0, import_node_path.join)((0, import_node_path.dirname)(packageEntryPath), "index.js");
       } catch {
       }
     }
@@ -1119,7 +1119,7 @@ class CopilotClient {
         canvasProvider: config.canvasProvider,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
-          description: cmd.description
+          description: cmd.description ?? ""
         })),
         systemMessage: wireSystemMessage,
         availableTools: toolFilterOptions.availableTools,
@@ -1242,10 +1242,10 @@ class CopilotClient {
     return this.resumeSessionInternal(sessionId, config);
   }
   /** @internal */
-  async resumeSessionForExtension(sessionId, config, factories) {
-    return this.resumeSessionInternal(sessionId, config, factories);
+  async resumeSessionForExtension(sessionId, config, factories, extensionOptions) {
+    return this.resumeSessionInternal(sessionId, config, factories, extensionOptions);
   }
-  async resumeSessionInternal(sessionId, config, factories) {
+  async resumeSessionInternal(sessionId, config, factories, extensionOptions) {
     if (!this.connection) {
       await this.start();
     }
@@ -1342,7 +1342,7 @@ class CopilotClient {
         canvasProvider: config.canvasProvider,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
-          description: cmd.description
+          description: cmd.description ?? ""
         })),
         provider: bearerWireProvider,
         capi: config.capi,
@@ -1394,8 +1394,20 @@ class CopilotClient {
         openCanvases: config.openCanvases,
         expAssignments: config.expAssignments,
         enableManagedSettings: config.enableManagedSettings,
-        managedSettings: config.managedSettings
+        managedSettings: config.managedSettings,
+        ...extensionOptions?.requestedEnvironmentVariables ? {
+          requestedEnvironmentVariables: extensionOptions.requestedEnvironmentVariables
+        } : {}
       });
+      if (extensionOptions?.requestedEnvironmentVariables) {
+        const requested = new Set(extensionOptions.requestedEnvironmentVariables);
+        const { grantedEnvironmentVariables } = response;
+        for (const [name, value] of Object.entries(grantedEnvironmentVariables ?? {})) {
+          if (requested.has(name)) {
+            process.env[name] = value;
+          }
+        }
+      }
       const { workspacePath, capabilities, openCanvases } = response;
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);

package/dist/cjs/extension.js

@@ -42,6 +42,7 @@ async function joinSession(config = {}) {
   const {
     extensionSdkPath: _stripped,
     factories,
+    requestedEnvironmentVariables,
     ...rest
   } = config;
   void _stripped;
@@ -52,7 +53,8 @@ async function joinSession(config = {}) {
       onPermissionRequest: config.onPermissionRequest ?? import_types.defaultJoinSessionPermissionHandler,
       suppressResumeEvent: config.suppressResumeEvent ?? true
     },
-    factories
+    factories,
+    requestedEnvironmentVariables?.length ? { requestedEnvironmentVariables } : void 0
   );
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/cjs/generated/rpc.js

@@ -43,7 +43,7 @@ function createServerRpc(connection) {
       /**
        * Lists Copilot models available to the authenticated user.
        *
-       * @param params Optional GitHub token used to list models for a specific user instead of the global auth context.
+       * @param params Optional opaque account selection or compatibility GitHub token used to list models.
        *
        * @returns List of Copilot models available to the resolved user, including capabilities and billing metadata.
        */
@@ -69,9 +69,9 @@ function createServerRpc(connection) {
     /** @experimental */
     account: {
       /**
-       * Gets Copilot quota usage for the authenticated user or supplied GitHub token.
+       * Gets Copilot quota usage for the current or opaquely selected authenticated user.
        *
-       * @param params Optional GitHub token used to look up quota for a specific user instead of the global auth context.
+       * @param params Optional opaque account selection or compatibility GitHub token used to look up quota.
        *
        * @returns Quota usage snapshots for the resolved user, keyed by quota type.
        */
@@ -89,9 +89,9 @@ function createServerRpc(connection) {
        */
       getAllUsers: async () => connection.sendRequest("account.getAllUsers", {}),
       /**
-       * Stores authentication credentials after successful login (e.g., device code flow).
+       * Validates and stores authentication credentials. When login is omitted, resolves the authenticated user from the token before persistence.
        *
-       * @param params Credentials to store after successful authentication
+       * @param params Credentials to validate and store. Omit login to resolve the authenticated user from the token.
        *
        * @returns Result of a successful login; throws on failure
        */
@@ -168,7 +168,15 @@ function createServerRpc(connection) {
        *
        * @returns MCP servers discovered from user, workspace, plugin, and built-in sources.
        */
-      discover: async (params) => connection.sendRequest("mcp.discover", params)
+      discover: async (params) => connection.sendRequest("mcp.discover", params),
+      /**
+       * Requests a side-effect-free MCP install plan from a catalog candidate handle or a caller-supplied card. This host-implemented server method is available through SDK/TUI hosts; standalone and C-ABI runtimes whose host does not implement server-method dispatch return JSON-RPC MethodNotFound. A runtime with planning available returns a normalised plan and opaque single-use plan handle; a runtime without it returns the typed planning-unavailable result. A completed plan reports resource identity, provenance, eligible transport choices, the user-scope target, required typed values and secret placeholders, the policy result, the configuration changes installing would make, and whether a reload would be needed. Planning never writes configuration, stores a secret, or reloads MCP servers, so abandoning a plan needs no call and leaves nothing behind.
+       *
+       * @param params A side-effect-free request for an MCP install plan. Computing a plan never writes configuration, stores a secret, or reloads MCP servers.
+       *
+       * @returns Outcome of an mcp.planInstall call: either a normalised plan, or one typed refusal. Nothing is written in either case.
+       */
+      planInstall: async (params) => connection.sendRequest("mcp.planInstall", params)
     },
     /** @experimental */
     extensions: {
@@ -198,6 +206,17 @@ function createServerRpc(connection) {
      */
     registerExtensionLaunchProvider: async () => connection.sendRequest("registerExtensionLaunchProvider", {}),
     /** @experimental */
+    catalog: {
+      /**
+       * Requests a bounded catalog search. This host-implemented server method is available through SDK/TUI hosts; standalone and C-ABI runtimes whose host does not implement server-method dispatch return JSON-RPC MethodNotFound. A runtime with search available returns inert candidate summaries, each with an opaque single-use handle scoped to this runtime instance; a runtime without it returns the typed search-unavailable result. Public authorities may be searched anonymously, while an authority that requires credentials yields the typed authentication-required result. All returned text, URLs, and package metadata are untrusted external data and can never trigger instructions, tools, or installation. Read-only: nothing is installed, configured, or persisted.
+       *
+       * @param params A bounded catalog search. Both the query length and the result count are capped by the schema so a caller cannot request an unbounded scan.
+       *
+       * @returns Outcome of a catalog.search call: either bounded inert candidates, or one typed refusal. Never a partial success.
+       */
+      search: async (params) => connection.sendRequest("catalog.search", params)
+    },
+    /** @experimental */
     plugins: {
       /**
        * Lists plugins installed in user/global state.
@@ -246,6 +265,15 @@ function createServerRpc(connection) {
        */
       disable: async (params) => connection.sendRequest("plugins.disable", params),
       /** @experimental */
+      builtin: {
+        /**
+         * Replaces this server's trusted built-in plugin directories while no sessions are active.
+         *
+         * @param params Trusted built-in plugin directories to use for this runtime process.
+         */
+        set: async (params) => connection.sendRequest("plugins.builtin.set", params)
+      },
+      /** @experimental */
       marketplaces: {
         /**
          * Lists all registered marketplaces (defaults + user-added).
@@ -296,7 +324,13 @@ function createServerRpc(connection) {
          *
          * @param params Skill names to mark as disabled in global configuration, replacing any previous list.
          */
-        setDisabledSkills: async (params) => connection.sendRequest("skills.config.setDisabledSkills", params)
+        setDisabledSkills: async (params) => connection.sendRequest("skills.config.setDisabledSkills", params),
+        /**
+         * Atomically adds or removes one skill from the disabled list.
+         *
+         * @param params Adds or removes a single skill from the global disabled list, leaving every other entry untouched.
+         */
+        setSkillDisabled: async (params) => connection.sendRequest("skills.config.setSkillDisabled", params)
       },
       /**
        * Discovers skills across global and project sources.
@@ -639,7 +673,7 @@ function createInternalServerRpc(connection) {
     /**
      * Performs the SDK server connection handshake and validates the optional connection token. Marked internal because this is JSON-RPC transport plumbing invoked automatically by an SDK client's own `connect()` wrapper, not a user-facing method. Stays internal as long as the SDK client owns the handshake; would only become public if the SDK ever exposed the raw schema surface to consumers without a connection wrapper.
      *
-     * @param params Parameters for the `server.connect` handshake: an optional connection token and optional connection-level opt-ins (e.g. GitHub telemetry forwarding).
+     * @param params Connection-level opt-ins for the `server.connect` handshake. Transport authentication is consumed by the native protocol boundary before dispatch.
      *
      * @returns Handshake result reporting the server's protocol version and package version on success.
      *
@@ -982,6 +1016,8 @@ function createSessionRpc(connection, sessionId) {
        * Sets the current agent interaction mode.
        *
        * @param params Agent interaction mode to apply to the session.
+       *
+       * @returns Outcome of a session mode change, including any model switch it triggered and follow-up the host must perform.
        */
       set: async (params) => connection.sendRequest("session.mode.set", { sessionId, ...params })
     },
@@ -1384,6 +1420,12 @@ function createSessionRpc(connection, sessionId) {
        * Reloads MCP server connections for the session.
        */
       reload: async () => connection.sendRequest("session.mcp.reload", { sessionId }),
+      /**
+       * Releases any turns waiting on an in-flight MCP load without cancelling the load, letting the agent proceed while MCP servers finish connecting in the background. No-op when no MCP load is in flight or waiting turns were already released.
+       *
+       * @returns Result of moving in-flight MCP loading to the background.
+       */
+      moveLoadingToBackground: async () => connection.sendRequest("session.mcp.moveLoadingToBackground", { sessionId }),
       /**
        * Runs an MCP sampling inference on behalf of an MCP server.
        *
@@ -1464,6 +1506,14 @@ function createSessionRpc(connection, sessionId) {
          * @returns OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server.
          */
         login: async (params) => connection.sendRequest("session.mcp.oauth.login", { sessionId, ...params }),
+        /**
+         * Passively probes a configured remote MCP server to classify whether OAuth is required or a cached/override token is accepted. Does not start OAuth, emit pending OAuth requests, or mutate MCP connection state.
+         *
+         * @param params Remote MCP server name for a passive OAuth status probe.
+         *
+         * @returns Passive MCP OAuth probe result. `authenticated` means the server accepted the probe request while an OAuth-origin access token was attached; it does not prove the server required or independently validated that token. The probe does not make a second unauthenticated request. Failed is an expected probe-domain outcome; JSON-RPC errors are reserved for API-call failures.
+         */
+        probe: async (params) => connection.sendRequest("session.mcp.oauth.probe", { sessionId, ...params }),
         /**
          * Responds to a pending MCP OAuth authorization request by its request id.
          *
@@ -1646,6 +1696,30 @@ function createSessionRpc(connection, sessionId) {
     },
     /** @experimental */
     tools: {
+      /**
+       * Executes one tool from the session's currently offered tool set through the native invocation pipeline.
+       *
+       * @param params A tool name and arguments to execute through the session's native invocation pipeline.
+       *
+       * @returns Canonical result returned by a session tool.
+       */
+      execute: async (params) => connection.sendRequest("session.tools.execute", { sessionId, ...params }),
+      /**
+       * Returns the Rust-owned built-in tool descriptors used to construct the session's offered tool set.
+       *
+       * @param params Options controlling how Rust-owned built-in tool descriptors are materialized.
+       *
+       * @returns Rust-owned built-in tool descriptors for the session.
+       */
+      getBuiltinDescriptors: async (params) => connection.sendRequest("session.tools.getBuiltinDescriptors", { sessionId, ...params }),
+      /**
+       * Projects a completed task_complete tool call into its label-safe session event payload.
+       *
+       * @param params Task-completion tool arguments and final result used to build a label-safe session event payload.
+       *
+       * @returns Task completion notification with summary from the agent
+       */
+      taskCompleteEventData: async (params) => connection.sendRequest("session.tools.taskCompleteEventData", { sessionId, ...params }),
       /**
        * Provides the result for a pending external tool call.
        *
@@ -1666,6 +1740,14 @@ function createSessionRpc(connection, sessionId) {
        * @returns Current lightweight tool metadata snapshot for the session.
        */
       getCurrentMetadata: async () => connection.sendRequest("session.tools.getCurrentMetadata", { sessionId }),
+      /**
+       * Atomically replaces the complete externally implemented tool list supplied by the calling connection. Built-in, MCP/plugin, extension-discovered, subagent, and tools supplied by other connections remain unchanged.
+       *
+       * @param params Complete externally implemented tool list for the calling connection. An empty list removes every tool previously supplied by that connection.
+       *
+       * @returns Empty result after replacing the calling connection's externally implemented tools.
+       */
+      set: async (params) => connection.sendRequest("session.tools.set", { sessionId, ...params }),
       /**
        * Updates the current session's live subagent settings after user settings change. The persisted user settings remain the source of truth for future sessions.
        *
@@ -1748,7 +1830,7 @@ function createSessionRpc(connection, sessionId) {
        *
        * @param params Transient question to answer without adding it to conversation history.
        *
-       * @returns Transient answer generated from current conversation context.
+       * @returns Completed transient query. Ordered chunks and the terminal outcome are also delivered through `ui.ephemeral_query` session events while it runs.
        */
       ephemeralQuery: async (params) => connection.sendRequest("session.ui.ephemeralQuery", { sessionId, ...params }),
       /**
@@ -1855,19 +1937,19 @@ function createSessionRpc(connection, sessionId) {
        */
       setApproveAll: async (params) => connection.sendRequest("session.permissions.setApproveAll", { sessionId, ...params }),
       /**
-       * Sets the allow-all permission mode for the session. Used by attach-mode clients (e.g. LocalRpcSession's `/allow-all` forwarder) to flip the target session's permission state. The `on` mode swaps in unrestricted path and URL managers and emits `session.permissions_changed` on transition; the `auto` mode keeps normal prompt paths active while attaching LLM safety recommendations. The result returns the authoritative post-mutation state so callers can update their local mirrors without racing the `session.permissions_changed` notification on the same wire.
+       * Sets the permission mode for the session. `manual` follows the normal approval flow, `assisted` attaches LLM safety recommendations, and `allow-all` automatically approves permission requests. The result returns the authoritative post-mutation mode so callers can update local state without racing the `session.permissions_changed` notification.
        *
-       * @param params Allow-all mode to apply for the session.
+       * @param params Permission mode to apply for the session.
        *
-       * @returns Indicates whether the operation succeeded and reports the post-mutation state.
+       * @returns Indicates whether the requested permission mode was applied and reports the authoritative post-mutation mode.
        */
-      setAllowAll: async (params) => connection.sendRequest("session.permissions.setAllowAll", { sessionId, ...params }),
+      setMode: async (params) => connection.sendRequest("session.permissions.setMode", { sessionId, ...params }),
       /**
-       * Returns the current allow-all permission mode for the session.
+       * Returns the current permission mode for the session.
        *
-       * @returns Current allow-all permission mode.
+       * @returns Current permission mode.
        */
-      getAllowAll: async () => connection.sendRequest("session.permissions.getAllowAll", { sessionId }),
+      getMode: async () => connection.sendRequest("session.permissions.getMode", { sessionId }),
       /**
        * Adds or removes session-scoped or location-scoped permission rules.
        *
@@ -1909,7 +1991,7 @@ function createSessionRpc(connection, sessionId) {
          */
         list: async () => connection.sendRequest("session.permissions.paths.list", { sessionId }),
         /**
-         * Adds a directory to the session's allow-list.
+         * Adds a directory to the session's allow-list and activates conventional skill and agent definitions under it.
          *
          * @param params Directory path to add to the session's allowed directories.
          *
@@ -2385,6 +2467,90 @@ function createInternalSessionRpc(connection, sessionId) {
      */
     sendSystemNotification: async (params) => connection.sendRequest("session.sendSystemNotification", { sessionId, ...params }),
     /** @experimental */
+    gitHubAuth: {
+      /**
+       * Gets the current authentication information for internal session hosts.
+       *
+       * @returns Current authentication information, or null when no authentication is active.
+       */
+      getCurrentAuthInfo: async () => connection.sendRequest("session.gitHubAuth.getCurrentAuthInfo", { sessionId }),
+      /**
+       * Gets all authentication accounts available to the internal session host.
+       *
+       * @returns Authentication accounts available to the internal session host.
+       */
+      getAllAuthAvailable: async () => connection.sendRequest("session.gitHubAuth.getAllAuthAvailable", { sessionId }),
+      /**
+       * Refreshes Copilot account metadata for the current authentication.
+       *
+       * @returns Current authentication information, or null when no authentication is active.
+       */
+      refreshCopilotUser: async () => connection.sendRequest("session.gitHubAuth.refreshCopilotUser", { sessionId }),
+      /**
+       * Logs in a GitHub user through the internal session host.
+       *
+       * @param params Internal GitHub login parameters.
+       *
+       * @returns Authentication credentials accepted only at native protocol ingress. Runtime outputs use credential-free `AuthIdentity` metadata.
+       */
+      login: async (params) => connection.sendRequest("session.gitHubAuth.login", { sessionId, ...params }),
+      /**
+       * Switches the session to another available authentication.
+       *
+       * @param params Parameters for switching the session's active authentication.
+       */
+      switchToAuth: async (params) => connection.sendRequest("session.gitHubAuth.switchToAuth", { sessionId, ...params }),
+      /**
+       * Logs out the session's current GitHub authentication.
+       *
+       * @returns Whether the current authentication was logged out.
+       */
+      logout: async () => connection.sendRequest("session.gitHubAuth.logout", { sessionId }),
+      /**
+       * Logs out a specific GitHub authentication.
+       *
+       * @param params Parameters identifying a GitHub authentication to log out.
+       *
+       * @returns Whether the requested authentication was logged out.
+       */
+      logoutUser: async (params) => connection.sendRequest("session.gitHubAuth.logoutUser", { sessionId, ...params }),
+      /**
+       * Gets validation errors from the most recent authentication attempt.
+       *
+       * @returns Validation errors from the most recent authentication attempt.
+       */
+      lastAuthErrors: async () => connection.sendRequest("session.gitHubAuth.lastAuthErrors", { sessionId })
+    },
+    /** @experimental */
+    canvas: {
+      /** @experimental */
+      provider: {
+        /**
+         * Registers an internal canvas provider connection and its contributions.
+         *
+         * @param params Internal canvas provider registration parameters.
+         */
+        register: async (params) => connection.sendRequest("session.canvas.provider.register", { sessionId, ...params }),
+        /**
+         * Unregisters an internal canvas provider connection.
+         *
+         * @param params Internal canvas provider unregistration parameters.
+         */
+        unregister: async (params) => connection.sendRequest("session.canvas.provider.unregister", { sessionId, ...params })
+      }
+    },
+    /** @experimental */
+    model: {
+      /**
+       * Resolves and applies organization-managed and repository model overlays.
+       *
+       * @param params Managed, repository, and CLI model overrides to overlay onto the session at startup.
+       *
+       * @returns The model identifier active on the session after the switch.
+       */
+      applyStartupOverlay: async (params) => connection.sendRequest("session.model.applyStartupOverlay", { sessionId, ...params })
+    },
+    /** @experimental */
     mcp: {
       /**
        * Reloads MCP server connections for the session with an explicit host-provided configuration.
@@ -2397,7 +2563,7 @@ function createInternalSessionRpc(connection, sessionId) {
       /**
        * Configures the built-in GitHub MCP server for the session's current auth context.
        *
-       * @param params Opaque auth info used to configure GitHub MCP.
+       * @param params Credential-free authentication identity used to configure GitHub MCP.
        *
        * @returns Result of configuring GitHub MCP.
        */
@@ -2416,6 +2582,17 @@ function createInternalSessionRpc(connection, sessionId) {
       unregisterExternalClient: async (params) => connection.sendRequest("session.mcp.unregisterExternalClient", { sessionId, ...params })
     },
     /** @experimental */
+    commands: {
+      /**
+       * Finalizes persistence associated with a client-applied slash-command effect.
+       *
+       * @param params The pending slash-command invocation effect to finalize, plus whether the host applied or cancelled it.
+       *
+       * @returns Whether finalizing the invocation effect succeeded, and the failure reason when it did not.
+       */
+      finalizeInvocationEffect: async (params) => connection.sendRequest("session.commands.finalizeInvocationEffect", { sessionId, ...params })
+    },
+    /** @experimental */
     settings: {
       /**
        * Returns a redacted snapshot of session runtime settings, with secrets and raw feature flags excluded. Internal: the runtime settings shape is a runtime-internal surface and is deliberately kept out of the public SDK, because consumers should not depend on the runtime's internal settings layout. It remains callable in-process and is expected to be reworked as the runtime internals are consolidated.

package/dist/cjs/session.js

@@ -1174,7 +1174,13 @@ class CopilotSession {
     }
     try {
       const result = await this.elicitationHandler(context);
-      await this.rpc.ui.handlePendingElicitation({ requestId, result });
+      await this.rpc.ui.handlePendingElicitation({
+        requestId,
+        result: {
+          action: result.action,
+          ...result.content ? { content: result.content } : {}
+        }
+      });
     } catch {
       try {
         await this.rpc.ui.handlePendingElicitation({

package/dist/client.js

@@ -194,9 +194,9 @@ function getBundledCliPath() {
   if (typeof import.meta.resolve === "function") {
     for (const packageName of packageNames) {
       try {
-        const sdkUrl = import.meta.resolve(`${packageName}/sdk`);
-        const sdkPath = fileURLToPath(sdkUrl);
-        return join(dirname(dirname(sdkPath)), "index.js");
+        const packageEntryUrl = import.meta.resolve(packageName);
+        const packageEntryPath = fileURLToPath(packageEntryUrl);
+        return join(dirname(packageEntryPath), "index.js");
       } catch {
       }
     }
@@ -1096,7 +1096,7 @@ class CopilotClient {
         canvasProvider: config.canvasProvider,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
-          description: cmd.description
+          description: cmd.description ?? ""
         })),
         systemMessage: wireSystemMessage,
         availableTools: toolFilterOptions.availableTools,
@@ -1219,10 +1219,10 @@ class CopilotClient {
     return this.resumeSessionInternal(sessionId, config);
   }
   /** @internal */
-  async resumeSessionForExtension(sessionId, config, factories) {
-    return this.resumeSessionInternal(sessionId, config, factories);
+  async resumeSessionForExtension(sessionId, config, factories, extensionOptions) {
+    return this.resumeSessionInternal(sessionId, config, factories, extensionOptions);
   }
-  async resumeSessionInternal(sessionId, config, factories) {
+  async resumeSessionInternal(sessionId, config, factories, extensionOptions) {
     if (!this.connection) {
       await this.start();
     }
@@ -1319,7 +1319,7 @@ class CopilotClient {
         canvasProvider: config.canvasProvider,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
-          description: cmd.description
+          description: cmd.description ?? ""
         })),
         provider: bearerWireProvider,
         capi: config.capi,
@@ -1371,8 +1371,20 @@ class CopilotClient {
         openCanvases: config.openCanvases,
         expAssignments: config.expAssignments,
         enableManagedSettings: config.enableManagedSettings,
-        managedSettings: config.managedSettings
+        managedSettings: config.managedSettings,
+        ...extensionOptions?.requestedEnvironmentVariables ? {
+          requestedEnvironmentVariables: extensionOptions.requestedEnvironmentVariables
+        } : {}
       });
+      if (extensionOptions?.requestedEnvironmentVariables) {
+        const requested = new Set(extensionOptions.requestedEnvironmentVariables);
+        const { grantedEnvironmentVariables } = response;
+        for (const [name, value] of Object.entries(grantedEnvironmentVariables ?? {})) {
+          if (requested.has(name)) {
+            process.env[name] = value;
+          }
+        }
+      }
       const { workspacePath, capabilities, openCanvases } = response;
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);

package/dist/extension.d.ts

@@ -4,6 +4,35 @@ import type { FactoryHandle } from "./factory.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest" | "extensionSdkPath"> & {
     onPermissionRequest?: PermissionHandler;
+    /**
+     * Names of sensitive environment variables this extension needs, such as
+     * `"GITHUB_TOKEN"`.
+     *
+     * The Copilot CLI strips sensitive variables from every extension process
+     * before it starts, so an extension that needs one must ask for it by name.
+     * The CLI prompts the user with the extension's name and the exact list of
+     * variables requested. On approval the granted values are written into this
+     * process's `process.env` before {@link joinSession} resolves, so they are
+     * readable afterwards. On denial the join rejects and the extension does not
+     * load, so its tools never reach the model.
+     *
+     * An approval is remembered against the exact set of names the user saw, so
+     * asking for an additional variable later prompts again. Names that are unset
+     * or that the CLI does not filter from extensions are not prompted for. An
+     * empty list means the same as omitting the option: nothing is requested.
+     *
+     * Requires a Copilot CLI that supports extension environment access; older
+     * CLIs ignore the request and grant nothing.
+     *
+     * @example
+     * ```typescript
+     * const session = await joinSession({
+     *     requestedEnvironmentVariables: ["GITHUB_TOKEN"],
+     * });
+     * const token = process.env.GITHUB_TOKEN;
+     * ```
+     */
+    requestedEnvironmentVariables?: string[];
     /**
      * Factory handles to register when the extension joins the session.
      *

package/dist/extension.js

@@ -23,6 +23,7 @@ async function joinSession(config = {}) {
   const {
     extensionSdkPath: _stripped,
     factories,
+    requestedEnvironmentVariables,
     ...rest
   } = config;
   void _stripped;
@@ -33,7 +34,8 @@ async function joinSession(config = {}) {
       onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
       suppressResumeEvent: config.suppressResumeEvent ?? true
     },
-    factories
+    factories,
+    requestedEnvironmentVariables?.length ? { requestedEnvironmentVariables } : void 0
   );
 }
 export {