@github/copilot-sdk 1.0.7-preview.3 → 1.0.8-preview.0

package/dist/generated/rpc.js

@@ -734,6 +734,68 @@ function createSessionRpc(connection, sessionId) {
       }
     },
     /** @experimental */
+    factory: {
+      /**
+       * Runs a registered factory by name at the top level.
+       *
+       * @param params Parameters for invoking a registered factory.
+       *
+       * @returns Complete current or terminal factory run envelope.
+       */
+      run: async (params) => connection.sendRequest("session.factory.run", { sessionId, ...params }),
+      /**
+       * Gets the current or settled envelope for a factory run.
+       *
+       * @param params Parameters for retrieving a factory run.
+       *
+       * @returns Complete current or terminal factory run envelope.
+       */
+      getRun: async (params) => connection.sendRequest("session.factory.getRun", { sessionId, ...params }),
+      /**
+       * Requests cancellation of a factory run and returns its run envelope.
+       *
+       * @param params Parameters for cancelling a factory run.
+       *
+       * @returns Complete current or terminal factory run envelope.
+       */
+      cancel: async (params) => connection.sendRequest("session.factory.cancel", { sessionId, ...params }),
+      /**
+       * Records a batch of ordered factory progress lines.
+       *
+       * @param params Parameters for recording factory progress.
+       *
+       * @returns Acknowledgement that a factory request was accepted.
+       */
+      log: async (params) => connection.sendRequest("session.factory.log", { sessionId, ...params }),
+      /**
+       * Runs one factory-scoped subagent and returns its result.
+       *
+       * @param params Parameters for one factory-scoped subagent call.
+       *
+       * @returns Result of one factory-scoped subagent call.
+       */
+      agent: async (params) => connection.sendRequest("session.factory.agent", { sessionId, ...params }),
+      /** @experimental */
+      journal: {
+        /**
+         * Reads a memoized factory journal entry.
+         *
+         * @param params Parameters for reading a factory journal entry.
+         *
+         * @returns Result of reading a factory journal entry.
+         */
+        get: async (params) => connection.sendRequest("session.factory.journal.get", { sessionId, ...params }),
+        /**
+         * Stores a memoized factory journal entry.
+         *
+         * @param params Parameters for storing a factory journal entry.
+         *
+         * @returns Acknowledgement that a factory request was accepted.
+         */
+        put: async (params) => connection.sendRequest("session.factory.journal.put", { sessionId, ...params })
+      }
+    },
+    /** @experimental */
     model: {
       /**
        * Gets the currently selected model for the session.
@@ -1091,7 +1153,7 @@ function createSessionRpc(connection, sessionId) {
        */
       list: async () => connection.sendRequest("session.mcp.list", { sessionId }),
       /**
-       * Lists the tools exposed by a connected MCP server on this session's host.
+       * Lists the tools exposed by a connected MCP server on this session's host. This performs a live `tools/list` request. Tool UI metadata is returned independently of whether MCP Apps rendering is enabled for the session.
        *
        * @param params Server name whose tool list should be returned.
        *
@@ -1766,11 +1828,11 @@ function createSessionRpc(connection, sessionId) {
        */
       getContextHeaviestMessages: async (params) => connection.sendRequest("session.metadata.getContextHeaviestMessages", { sessionId, ...params }),
       /**
-       * Records a working-directory/git context change and emits a `session.context_changed` event.
+       * Records a working-directory/git context change and emits a `session.context_changed` event. For a local session, a report whose `cwd` diverges from the session's current working directory is ignored (the call still succeeds but records nothing and emits no event): a local session's working directory is authoritative and is moved via `metadata.setWorkingDirectory` (or an SDK `session.resume` that supplies a `workingDirectory`), not by this method.
        *
        * @param params Updated working-directory/git context to record on the session.
        *
-       * @returns Notify the session that its working directory context has changed. Emits a `session.context_changed` event so consumers (telemetry, OTel tracker, ACP, the timeline UI) can react. Use this when the host has detected a cwd/branch/repo change outside the session's normal lifecycle (e.g., after a shell command in interactive mode).
+       * @returns Notify the session that its working directory context has changed. Emits a `session.context_changed` event so consumers (telemetry, OTel tracker, ACP, the timeline UI) can react. Use this when the host has detected a cwd/branch/repo change outside the session's normal lifecycle (e.g., after a shell command in interactive mode). For a local session, a report whose `cwd` diverges from the session's current working directory is ignored (the call still succeeds but records nothing and emits no event); move a local session's working directory via `metadata.setWorkingDirectory` instead.
        */
       recordContextChange: async (params) => connection.sendRequest("session.metadata.recordContextChange", { sessionId, ...params }),
       /**
@@ -2040,6 +2102,16 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
     if (!handler) throw new Error(`No providerToken handler registered for session: ${params.sessionId}`);
     return handler.getToken(params);
   });
+  connection.onRequest("factory.execute", async (params) => {
+    const handler = getHandlers(params.sessionId).factory;
+    if (!handler) throw new Error(`No factory handler registered for session: ${params.sessionId}`);
+    return handler.execute(params);
+  });
+  connection.onRequest("factory.abort", async (params) => {
+    const handler = getHandlers(params.sessionId).factory;
+    if (!handler) throw new Error(`No factory handler registered for session: ${params.sessionId}`);
+    return handler.abort(params);
+  });
   connection.onRequest("sessionFs.readFile", async (params) => {
     const handler = getHandlers(params.sessionId).sessionFs;
     if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
@@ -2117,6 +2189,11 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
   });
 }
 function registerClientGlobalApiHandlers(connection, handlers) {
+  connection.onRequest("hooks.invoke", async (params) => {
+    const handler = handlers.hooks;
+    if (!handler) throw new Error("No hooks client-global handler registered");
+    return handler.invoke(params);
+  });
   connection.onRequest("llmInference.httpRequestStart", async (params) => {
     const handler = handlers.llmInference;
     if (!handler) throw new Error("No llmInference client-global handler registered");

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

@@ -5,7 +5,7 @@
 /**
  * Union of all session event variants emitted by the Copilot CLI runtime.
  */
-export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
+export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantTurnRetryEvent | AssistantIntentEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallStartEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -207,6 +207,14 @@ export type ModelCallFailureBadRequestKind =
 "bodyless"
 /** The 400 response carried a structured CAPI error envelope (deterministic validation failure). */
  | "structured_error";
+/**
+ * Boundary that produced a model call failure
+ */
+export type ModelCallFailureKind = 
+/** The provider returned an API error response. */
+"api"
+/** The request transport failed before a usable API response completed. */
+ | "transport";
 /**
  * Where the failed model call originated
  */
@@ -217,6 +225,14 @@ export type ModelCallFailureSource =
  | "subagent"
 /** Model call from MCP sampling. */
  | "mcp_sampling";
+/**
+ * Transport used for a failed model call
+ */
+export type ModelCallFailureTransport = 
+/** HTTP transport, including SSE streams. */
+"http"
+/** WebSocket transport. */
+ | "websocket";
 /**
  * Finite reason code describing why the current turn was aborted
  */
@@ -471,6 +487,36 @@ export type AutoModeResolvedReasoningBucket =
  | "medium"
 /** The request looks high-reasoning; a stronger model is appropriate. */
  | "high";
+/**
+ * Which channel supplied the effective enterprise managed settings (highest-authority present layer wins wholesale)
+ */
+export type ManagedSettingsResolvedSource = 
+/** Account/org policy self-fetched from the GitHub managed-settings endpoint (higher authority). */
+"server"
+/** Device-level MDM policy discovered from plist/registry/file (lower authority). */
+ | "device"
+/** No managed policy is in force (no layer contributed). */
+ | "none";
+/**
+ * The category of runtime action that enterprise managed settings governed (blocked or capped)
+ */
+export type ManagedSettingsEnforcedAction = 
+/** An attempt to turn on a bypass-permissions ("yolo") escalation was refused or capped because policy disables bypass-permissions mode. */
+"bypass_permissions_blocked";
+/**
+ * For a `bypass_permissions_blocked` action, which permission-escalation primitive was refused
+ */
+export type ManagedSettingsEnforcedEscalation = 
+/** Full allow-all ("/allow-all on") permissions — auto-approving tools, paths, and URLs. */
+"allow_all"
+/** Auto-approval of all tool permission requests. */
+ | "approve_all"
+/** Advisory auto-approval ("/allow-all auto") mode — keeps normal prompt paths and adds LLM-advised approval, distinct from full allow-all. */
+ | "auto_approval"
+/** Unrestricted filesystem access outside the session's allowed directories. */
+ | "unrestricted_paths"
+/** Unrestricted URL fetch access. */
+ | "unrestricted_urls";
 /**
  * Exit plan mode action
  */
@@ -2904,6 +2950,23 @@ export interface AssistantTurnStartData {
      */
     turnId: string;
 }
+/**
+ * Metadata for an additional model inference attempt within an existing assistant turn
+ */
+export interface AssistantTurnRetryData {
+    /**
+     * Model identifier used for this retry, when known
+     */
+    model?: string;
+    /**
+     * Provider or runtime classification that caused the retry, when known
+     */
+    reason?: string;
+    /**
+     * Identifier of the turn whose model inference is being retried
+     */
+    turnId: string;
+}
 /**
  * Session event "assistant.intent". Agent intent description for current activity or plan
  */
@@ -2943,6 +3006,53 @@ export interface AssistantIntentData {
      */
     intent: string;
 }
+/**
+ * Session event "assistant.server_tool_progress". Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message
+ */
+export interface AssistantServerToolProgressEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: AssistantServerToolProgressData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.server_tool_progress".
+     */
+    type: "assistant.server_tool_progress";
+}
+/**
+ * Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message
+ */
+export interface AssistantServerToolProgressData {
+    /**
+     * Kind of hosted server tool that is running. Only `web_search` is emitted today.
+     */
+    kind: string;
+    /**
+     * Position of the hosted tool call in the response output. Stable across the call's lifecycle events (unlike the provider's per-event item id, which CAPI rotates), so the host keys the live in-progress row on it.
+     */
+    outputIndex: number;
+    /**
+     * Lifecycle status of the hosted call: `in_progress`, `searching`, or `completed`.
+     */
+    status: string;
+}
 /**
  * Session event "assistant.reasoning". Assistant reasoning content for timeline display with complete thinking text
  */
@@ -3618,6 +3728,10 @@ export interface AssistantUsageData {
      */
     apiCallId?: string;
     apiEndpoint?: AssistantUsageApiEndpoint;
+    /**
+     * Updated prompt-cache expiration for this model call. Present only when the call establishes or refreshes known cache state.
+     */
+    cacheExpiresAt?: string;
     /**
      * Number of tokens read from prompt cache
      */
@@ -3759,6 +3873,7 @@ export interface ModelCallFailureData {
      * Completion ID from the model provider (e.g., chatcmpl-abc123)
      */
     apiCallId?: string;
+    apiEndpoint?: AssistantUsageApiEndpoint;
     badRequestKind?: ModelCallFailureBadRequestKind;
     /**
      * Duration of the failed API call in milliseconds
@@ -3776,10 +3891,27 @@ export interface ModelCallFailureData {
      * 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.
      */
     errorType?: string;
+    failureKind?: ModelCallFailureKind;
     /**
      * What initiated this API call (e.g., "sub-agent", "mcp-sampling"); absent for user-initiated calls
      */
     initiator?: string;
+    /**
+     * Whether the session selected Auto mode for the failed call
+     */
+    isAuto?: boolean;
+    /**
+     * Whether the failed call used a bring-your-own-key provider
+     */
+    isByok?: boolean;
+    /**
+     * Effective maximum output-token limit for the failed call
+     */
+    maxOutputTokens?: number;
+    /**
+     * Effective maximum prompt-token limit for the failed call
+     */
+    maxPromptTokens?: number;
     /**
      * Model identifier used for the failed API call
      */
@@ -3788,6 +3920,10 @@ export interface ModelCallFailureData {
      * GitHub request tracing ID (x-github-request-id header) for server-side log correlation
      */
     providerCallId?: string;
+    /**
+     * Reasoning effort level used for the failed model call, if applicable
+     */
+    reasoningEffort?: string;
     requestFingerprint?: ModelCallFailureRequestFingerprint;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
@@ -3798,6 +3934,7 @@ export interface ModelCallFailureData {
      * HTTP status code from the failed request
      */
     statusCode?: number;
+    transport?: ModelCallFailureTransport;
 }
 /**
  * Content-free structural summary of the failing request for diagnosing malformed 4xx calls
@@ -3832,6 +3969,19 @@ export interface ModelCallFailureRequestFingerprint {
      */
     toolResultMessageCount: number;
 }
+/**
+ * Model API dispatch metadata for internal telemetry
+ */
+export interface ModelCallStartData {
+    /**
+     * Model identifier used for this API call, when known
+     */
+    model?: string;
+    /**
+     * Identifier of the assistant turn that initiated the model call
+     */
+    turnId: string;
+}
 /**
  * Session event "abort". Turn abort information including the reason for termination
  */
@@ -4677,6 +4827,49 @@ export interface ToolExecutionCompleteToolDescriptionMetaUI {
      */
     visibility?: ToolExecutionCompleteToolDescriptionMetaUIVisibility[];
 }
+/**
+ * Session event "tool_search.activated". Persisted generic client-side tool activations restored when a session resumes.
+ */
+export interface ToolSearchActivatedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: ToolSearchActivatedData;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "tool_search.activated".
+     */
+    type: "tool_search.activated";
+}
+/**
+ * Persisted generic client-side tool activations restored when a session resumes.
+ */
+export interface ToolSearchActivatedData {
+    /**
+     * Tool-search strategy that activated the definitions.
+     */
+    strategy: string;
+    /**
+     * Names of tool definitions activated by this search invocation.
+     */
+    toolNames: string[];
+}
 /**
  * Session event "skill.invoked". Skill invocation details including content, allowed tools, and plugin metadata
  */
@@ -6851,6 +7044,7 @@ export interface McpOauthRequiredEvent {
  * OAuth authentication request for an MCP server
  */
 export interface McpOauthRequiredData {
+    httpResponse?: McpOauthHttpResponse;
     reason: McpOauthRequestReason;
     /**
      * Unique identifier for this OAuth request; used to respond via session.mcp.oauth.handlePendingRequest
@@ -6871,6 +7065,36 @@ export interface McpOauthRequiredData {
     staticClientConfig?: McpOauthRequiredStaticClientConfig;
     wwwAuthenticateParams?: McpOauthWWWAuthenticateParams;
 }
+/**
+ * Raw HTTP response details from the OAuth auth challenge, as observed by the runtime.
+ */
+export interface McpOauthHttpResponse {
+    /**
+     * Complete UTF-8 response body for host-specific challenge handling, including an empty string for an empty body. Omitted when the complete body is not valid UTF-8; body read failures fail the HTTP operation rather than exposing a partial response.
+     */
+    body?: string;
+    /**
+     * HTTP response headers as observed by the runtime. Order and casing are transport-dependent, and duplicate header names may appear multiple times.
+     */
+    headers: HeaderEntry[];
+    /**
+     * HTTP status code returned with the auth challenge.
+     */
+    statusCode: number;
+}
+/**
+ * Single HTTP header entry as a name/value pair.
+ */
+export interface HeaderEntry {
+    /**
+     * HTTP response header name as observed by the runtime.
+     */
+    name: string;
+    /**
+     * HTTP response header value as observed by the runtime.
+     */
+    value: string;
+}
 /**
  * Static OAuth client configuration, if the server specifies one
  */
@@ -7587,6 +7811,121 @@ export interface AutoModeResolvedData {
     predictedLabel?: string;
     reasoningBucket?: AutoModeResolvedReasoningBucket;
 }
+/**
+ * Session event "session.managed_settings_resolved". Enterprise managed-settings resolution: the effective managed settings the session applied and where they came from, so SDK clients can show users what is enterprise-managed and by which authority. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted; for a session-independent pull, use the SDK `getManagedSettings()` API, which returns the identical payload. Managed settings have a single authoritative source, so the highest-authority present layer (server > device) wins wholesale; `bypassPermissionsDisabled` is deny-wins across layers. Marked experimental while the managed-settings surface stabilizes.
+ */
+/** @experimental */
+export interface ManagedSettingsResolvedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: ManagedSettingsResolvedData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.managed_settings_resolved".
+     */
+    type: "session.managed_settings_resolved";
+}
+/**
+ * Enterprise managed-settings resolution: the effective managed settings the session applied and where they came from, so SDK clients can show users what is enterprise-managed and by which authority. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted; for a session-independent pull, use the SDK `getManagedSettings()` API, which returns the identical payload. Managed settings have a single authoritative source, so the highest-authority present layer (server > device) wins wholesale; `bypassPermissionsDisabled` is deny-wins across layers. Marked experimental while the managed-settings surface stabilizes.
+ */
+/** @experimental */
+export interface ManagedSettingsResolvedData {
+    /**
+     * Whether enterprise policy disables bypass-permissions ("yolo") mode for this session. Deny-wins across layers, and forced on when `failClosed` is true.
+     */
+    bypassPermissionsDisabled: boolean;
+    /**
+     * Whether the device (MDM/plist/registry/file) managed-settings layer was present
+     */
+    deviceManaged: boolean;
+    /**
+     * Whether managed policy could not be determined (e.g. a failed server fetch) and the session fell back to the fail-closed restriction. When true, restrictions such as disabling bypass-permissions are enforced even though `settings` may be absent.
+     */
+    failClosed: boolean;
+    /**
+     * The setting keys under enterprise management in the effective managed settings (e.g. `model`, `enabledPlugins`, `permissions`). Empty when no managed settings are in force.
+     */
+    managedKeys: string[];
+    /**
+     * Whether the server (account/org) managed-settings layer was present
+     */
+    serverManaged: boolean;
+    /**
+     * The effective (resolved) managed settings values, so clients can render exactly what is enforced. Absent when no managed policy is in force.
+     */
+    settings?: {
+        [k: string]: unknown | undefined;
+    };
+    source: ManagedSettingsResolvedSource;
+}
+/**
+ * Session event "session.managed_settings_enforced". Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes.
+ */
+/** @experimental */
+export interface ManagedSettingsEnforcedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: ManagedSettingsEnforcedData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.managed_settings_enforced".
+     */
+    type: "session.managed_settings_enforced";
+}
+/**
+ * Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes.
+ */
+/** @experimental */
+export interface ManagedSettingsEnforcedData {
+    action: ManagedSettingsEnforcedAction;
+    escalation?: ManagedSettingsEnforcedEscalation;
+    /**
+     * Whether the enforcement was forced by fail-closed handling (managed policy could not be determined) rather than an explicit managed setting. When true, `setting` still names the restriction that was applied.
+     */
+    failClosed: boolean;
+    /**
+     * A human-readable explanation of why the action was governed, suitable for surfacing to the user.
+     */
+    message: string;
+    /**
+     * The managed setting key responsible for the enforcement (e.g. `permissions.disableBypassPermissionsMode`).
+     */
+    setting: string;
+}
 /**
  * Session event "commands.changed". SDK command registration change notification
  */
@@ -8131,7 +8470,7 @@ export interface McpServerStatusChangedData {
     status: McpServerStatus;
 }
 /**
- * Session event "mcp.tools.list_changed". Payload of MCP `list_changed` notification events, emitted when an MCP server announces at runtime that one of its advertised lists changed.
+ * Session event "mcp.tools.list_changed". Payload identifying the MCP server associated with a list change.
  */
 export interface McpToolsListChangedEvent {
     /**
@@ -8161,7 +8500,7 @@ export interface McpToolsListChangedEvent {
     type: "mcp.tools.list_changed";
 }
 /**
- * Payload of MCP `list_changed` notification events, emitted when an MCP server announces at runtime that one of its advertised lists changed.
+ * Payload identifying the MCP server associated with a list change.
  */
 export interface McpListChangedData {
     /**
@@ -8170,7 +8509,7 @@ export interface McpListChangedData {
     serverName: string;
 }
 /**
- * Session event "mcp.resources.list_changed". Payload of MCP `list_changed` notification events, emitted when an MCP server announces at runtime that one of its advertised lists changed.
+ * Session event "mcp.resources.list_changed". Payload identifying the MCP server associated with a list change.
  */
 export interface McpResourcesListChangedEvent {
     /**
@@ -8200,7 +8539,7 @@ export interface McpResourcesListChangedEvent {
     type: "mcp.resources.list_changed";
 }
 /**
- * Session event "mcp.prompts.list_changed". Payload of MCP `list_changed` notification events, emitted when an MCP server announces at runtime that one of its advertised lists changed.
+ * Session event "mcp.prompts.list_changed". Payload identifying the MCP server associated with a list change.
  */
 export interface McpPromptsListChangedEvent {
     /**

package/dist/index.d.ts

@@ -10,4 +10,4 @@ export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";