@github/copilot-sdk 1.0.13-preview.4 → 1.0.13-preview.6

package/dist/generated/rpc.js

@@ -11,6 +11,17 @@ function createServerRpc(connection) {
      */
     ping: async (params) => connection.sendRequest("ping", params),
     /** @experimental */
+    hooks: {
+      /**
+       * Discovers hook actions enabled under server-side discovery settings from user, repository, plugin, and managed-policy sources.
+       *
+       * @param params Optional project paths and host-exclusion behavior for server-scoped hook discovery.
+       *
+       * @returns Server-discovered hook actions and partial-load diagnostics from user, repository, plugin, and managed-policy sources. Concrete sessions may include additional session-specific hook sources.
+       */
+      discover: async (params) => connection.sendRequest("hooks.discover", params)
+    },
+    /** @experimental */
     models: {
       /**
        * Lists Copilot models available to the authenticated user.
@@ -478,6 +489,14 @@ function createServerRpc(connection) {
        * @returns Sessions matching the filter, ordered most-recently-modified first.
        */
       list: async (params) => connection.sendRequest("sessions.list", params),
+      /**
+       * Reads a page of durable events directly from a local session's persisted journal without creating, resuming, or activating the session. The initial backward read uses a bounded tail scan for fast first paint; cursor continuations preserve the session event-log paging semantics. Persisted events may omit payloads that are reconstructed only for an active session.
+       *
+       * @param params Pagination options for reading an inactive or active local session's persisted event journal.
+       *
+       * @returns Batch of session events returned by a read, with cursor and continuation metadata.
+       */
+      readPersistedEvents: async (params) => connection.sendRequest("sessions.readPersistedEvents", params),
       /**
        * Finds the local session bound to a GitHub task ID, if any.
        *

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

@@ -9,7 +9,7 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
 /**
  * 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 | ContextClearedEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | FusionRouteStartedEvent | FusionRouteFailedEvent | FusionResolvedEvent | FusionCompletedEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantFusionPhaseStartedEvent | AssistantFusionPhaseCompletedEvent | AssistantFusionPhaseFailedEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallFinishedEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentConfiguredEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | UIEphemeralQueryEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | FactoryRunUpdatedEvent | FactoryRunStartedEvent | FactoryRunSettledEvent | 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 | ModeNoticeDeliveredEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | ContextClearedEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | CompletionReceiptEvent | FusionRouteStartedEvent | FusionRouteFailedEvent | FusionResolvedEvent | FusionCompletedEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantFusionPhaseStartedEvent | AssistantFusionPhaseActivityEvent | AssistantFusionPhaseCompletedEvent | AssistantFusionPhaseFailedEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallFinishedEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentConfiguredEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | UIEphemeralQueryEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | FactoryRunUpdatedEvent | FactoryRunStartedEvent | FactoryRunSettledEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
 /**
  * Routing preference used when the session model is `auto`.
  */
@@ -191,6 +191,30 @@ export type TaskCompletionOutcome =
  | "continue"
 /** Completion cannot proceed without intervention; the active objective is paused when one is identified. */
  | "blocked";
+/**
+ * Structured terminal status from a tool completion event.
+ */
+export type CompletionReceiptToolStatus = 
+/** The tool completed successfully. */
+"success"
+/** The tool failed without a more specific structured status. */
+ | "failure"
+/** The tool exceeded its time budget. */
+ | "timeout"
+/** The user rejected the tool call. */
+ | "rejected"
+/** The permissions service denied the tool call. */
+ | "denied";
+/**
+ * Runtime reason the completion decision was accepted.
+ */
+export type CompletionReceiptStopReason = 
+/** The model reached a natural terminal response. */
+"natural"
+/** A terminal tool ended the interaction. */
+ | "terminal_tool"
+/** The configured agentStop continuation limit was reached. */
+ | "agent_stop_block_limit";
 /**
  * Kind of turn for which HydraFusion routing is running.
  */
@@ -220,6 +244,34 @@ export type FusionPattern =
  | "cascade"
 /** Run a primary draft, a read-only critique, and a revision. */
  | "critique";
+/**
+ * HydraFusion phase kind.
+ */
+/** @experimental */
+export type FusionPhaseKind = 
+/** Primary solver phase. */
+"primary"
+/** Read-only cascade judge phase. */
+ | "judge"
+/** Cascade repair phase. */
+ | "repair"
+/** Initial critique-pattern draft phase. */
+ | "draft"
+/** Read-only critique phase. */
+ | "critic"
+/** Critique-pattern revision phase. */
+ | "revision"
+/** Follow-up phase continuing from the resolved model. */
+ | "follow_up";
+/**
+ * Conversation scope in which a HydraFusion phase executes.
+ */
+/** @experimental */
+export type FusionConversationScope = 
+/** Canonical root conversation history. */
+"root"
+/** Isolated read-only review history that does not enter the root conversation. */
+ | "review";
 /**
  * The agent mode that was active when this message was sent
  */
@@ -265,33 +317,16 @@ export type UserMessageDelivery =
 /** Enqueued while the agent was busy; processed as its own run afterward. */
  | "queued";
 /**
- * Conversation scope in which a HydraFusion phase executes.
- */
-/** @experimental */
-export type FusionConversationScope = 
-/** Canonical root conversation history. */
-"root"
-/** Isolated read-only review history that does not enter the root conversation. */
- | "review";
-/**
- * HydraFusion phase kind.
+ * Content-safe activity observed while a HydraFusion phase is running.
  */
 /** @experimental */
-export type FusionPhaseKind = 
-/** Primary solver phase. */
-"primary"
-/** Read-only cascade judge phase. */
- | "judge"
-/** Cascade repair phase. */
- | "repair"
-/** Initial critique-pattern draft phase. */
- | "draft"
-/** Read-only critique phase. */
- | "critic"
-/** Critique-pattern revision phase. */
- | "revision"
-/** Follow-up phase continuing from the resolved model. */
- | "follow_up";
+export type FusionPhaseActivityKind = 
+/** The provider produced additional private output bytes. */
+"model_output"
+/** A tool began executing inside the phase. */
+ | "tool_started"
+/** A tool finished executing inside the phase. */
+ | "tool_completed";
 /**
  * Durable outcome status of a HydraFusion phase.
  */
@@ -736,7 +771,9 @@ export type ManagedSettingsResolvedSource =
  | "device"
 /** Only session-local SDK-host injection contributed. */
  | "client"
-/** More than one channel contributed. Ordinary keys resolve device over server per key, while permissions compose restrictively across all present layers. */
+/** A policy helper registered by device or server policy contributed. Device registration takes priority when present. */
+ | "policyHelper"
+/** More than one channel contributed. Ordinary keys resolve device over server over policy helper per key, while permissions compose restrictively across all present layers. */
  | "mixed"
 /** No managed policy is in force (no channel contributed). */
  | "none";
@@ -787,7 +824,7 @@ export type FactoryRunSettledStatus =
 /** The run failed, with `failureType` carrying the class when it has one. */
  | "error";
 /**
- * Source location type (e.g., project, personal-copilot, plugin, builtin)
+ * Source location type (e.g., project, personal-copilot, plugin, builtin, sdk)
  */
 export type SkillSource = 
 /** Skill defined in the current project's skill directories. */
@@ -803,7 +840,17 @@ export type SkillSource =
 /** Skill loaded from a configured custom skill directory. */
  | "custom"
 /** Skill bundled with the runtime. */
- | "builtin";
+ | "builtin"
+/** Pathless skill supplied lazily by an SDK skill provider. */
+ | "sdk";
+/**
+ * Whether configured models are advisory preferences or required constraints
+ */
+export type AgentModelPolicy = 
+/** Treat the authored models as advisory preferences that callers may override. */
+"preferred"
+/** Require subagent execution to use one of the authored models. */
+ | "required";
 /**
  * Configuration source: user, workspace, plugin, or builtin
  */
@@ -1689,6 +1736,46 @@ export interface ModeChangedData {
     newMode: SessionMode;
     previousMode: SessionMode;
 }
+/**
+ * Session event "session.mode_notice_delivered". Records that a mode transition notice reached the model so cache-stable mode tools can remain offered across resume.
+ */
+export interface ModeNoticeDeliveredEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: ModeNoticeDeliveredData;
+    /**
+     * 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 "session.mode_notice_delivered".
+     */
+    type: "session.mode_notice_delivered";
+}
+/**
+ * Records that a mode transition notice reached the model so cache-stable mode tools can remain offered across resume.
+ */
+export interface ModeNoticeDeliveredData {
+    /**
+     * Model-visible transition notice persisted for a mid-turn delivery
+     */
+    content?: string;
+    mode: SessionMode;
+}
 /**
  * Session event "session.session_limits_changed". Session limits update details. Null clears the limits.
  */
@@ -2748,6 +2835,97 @@ export interface TaskCompleteData {
      */
     summary?: string;
 }
+/**
+ * Session event "session.completion_receipt". Behavior-neutral record of structured runtime facts present when an agent completion decision is accepted.
+ */
+/** @experimental */
+export interface CompletionReceiptEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: CompletionReceiptData;
+    /**
+     * 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 "session.completion_receipt".
+     */
+    type: "session.completion_receipt";
+}
+/**
+ * Behavior-neutral record of structured runtime facts present when an agent completion decision is accepted.
+ */
+/** @experimental */
+export interface CompletionReceiptData {
+    /**
+     * One-based accepted completion receipt ordinal in the durable session history.
+     */
+    attempt: number;
+    eventRange: CompletionReceiptEventRange;
+    /**
+     * Number of failed structured tool completions in the covered range.
+     */
+    failedToolCount: number;
+    finalTool?: CompletionReceiptFinalTool;
+    /**
+     * Version of the completion receipt payload.
+     */
+    schemaVersion: number;
+    /**
+     * Identifier of the assistant turn-end event that supplied the accepted completion boundary. This is the receipt's idempotency key, and always equals eventRange.endEventId.
+     */
+    sourceEventId: string;
+    stopReason: CompletionReceiptStopReason;
+    /**
+     * Number of successful structured tool completions in the covered range.
+     */
+    successfulToolCount: number;
+}
+/**
+ * Inclusive durable event range summarized by a completion receipt.
+ */
+export interface CompletionReceiptEventRange {
+    /**
+     * Identifier of the assistant turn-end event that ends the covered exchange. Always equals the receipt's sourceEventId, so either field is a valid join key.
+     */
+    endEventId: string;
+    /**
+     * Identifier of the user message that starts the covered exchange.
+     */
+    startEventId: string;
+}
+/**
+ * Final structured tool completion in the covered event range.
+ */
+export interface CompletionReceiptFinalTool {
+    /**
+     * Process exit code from a structured shell result, when available.
+     */
+    exitCode?: number;
+    status: CompletionReceiptToolStatus;
+    /**
+     * Unique identifier of the completed tool call.
+     */
+    toolCallId: string;
+    /**
+     * Tool name from the matching tool execution start event, when available.
+     */
+    toolName?: string;
+}
 /**
  * Session event "session.fusion_route_started". Experimental transient signal that HydraFusion routing has started for an eligible turn.
  */
@@ -2921,6 +3099,12 @@ export interface FusionResolvedData {
      */
     modelUniverseVersion?: string;
     pattern: FusionPattern;
+    /**
+     * Presentation-neutral phase plan for clients that render workflow progress.
+     *
+     * @experimental
+     */
+    phasePlan?: FusionPhasePlanStep[];
     /**
      * Version of the validated execution-plan format.
      */
@@ -2979,6 +3163,22 @@ export interface FusionFollowUpRecommendation {
     compactionTurn: FusionFollowUpAction;
     userTurn: FusionFollowUpAction;
 }
+/**
+ * Presentation-neutral phase planned for a HydraFusion turn.
+ */
+/** @experimental */
+export interface FusionPhasePlanStep {
+    /**
+     * Whether the phase executes only when an earlier phase requests it.
+     */
+    conditional: boolean;
+    kind: FusionPhaseKind;
+    /**
+     * Semantic role assigned to the phase.
+     */
+    role: string;
+    scope: FusionConversationScope;
+}
 /**
  * Validated HydraFusion routing capability scores.
  */
@@ -3159,6 +3359,10 @@ export interface UserMessageData {
      * True when this user message was auto-injected by autopilot's continuation loop rather than typed by the user; used to distinguish autopilot-driven turns in telemetry.
      */
     isAutopilotContinuation?: boolean;
+    /**
+     * Stable identity of the logical user message, matching the ID returned by send and retained by pending queue snapshots
+     */
+    messageId?: string;
     /**
      * Path-backed native document attachments that stayed on the tagged_files path flow because native upload could not read them or would exceed the request size limit
      */
@@ -3799,6 +4003,67 @@ export interface FusionPhaseStartedData {
      */
     role: string;
 }
+/**
+ * Session event "assistant.fusion_phase_activity". Experimental content-safe activity signal for a running HydraFusion phase.
+ */
+/** @experimental */
+export interface AssistantFusionPhaseActivityEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: FusionPhaseActivityData;
+    /**
+     * 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.fusion_phase_activity".
+     */
+    type: "assistant.fusion_phase_activity";
+}
+/**
+ * Experimental content-safe activity signal for a running HydraFusion phase.
+ */
+/** @experimental */
+export interface FusionPhaseActivityData {
+    activity: FusionPhaseActivityKind;
+    conversationScope: FusionConversationScope;
+    /**
+     * Identifier of the HydraFusion turn containing the phase.
+     */
+    fusionId: string;
+    pattern: FusionPattern;
+    /**
+     * Stable identifier for the concrete phase.
+     */
+    phaseId: string;
+    phaseKind: FusionPhaseKind;
+    /**
+     * Semantic role assigned to the phase.
+     */
+    role: string;
+    /**
+     * Opaque hashed correlation token for matching tool-started and tool-completed activity within this Fusion activity stream. It is not the tool call identifier exposed by tool lifecycle events.
+     */
+    toolCallId?: string;
+    /**
+     * Cumulative private response bytes observed for this model call. The event never includes response text.
+     */
+    totalResponseSizeBytes?: number;
+}
 /**
  * Session event "assistant.fusion_phase_completed". Experimental durable HydraFusion phase output and lossless replay checkpoint.
  */
@@ -4509,7 +4774,7 @@ export interface FusionAttribution {
 /** @experimental */
 export interface AssistantMessageReasoningBlocks {
     /**
-     * Provider-native reasoning content blocks (e.g. Anthropic `thinking` / `redacted_thinking`) preserved verbatim, in order. A single response can carry several, each signed over the content preceding it, so dropping or reordering any of them invalidates the rest.
+     * Provider-native reasoning items or content blocks preserved verbatim, in order. A single response can carry several, and provider signatures or identifiers may depend on their exact content and ordering.
      */
     blocks?: JsonValue[];
     /**
@@ -6129,6 +6394,10 @@ export interface SkillInvokedData {
      * Description of the skill from its SKILL.md frontmatter
      */
     description?: string;
+    /**
+     * Whether model invocation is disabled for this skill
+     */
+    disableModelInvocation?: boolean;
     /**
      * Model identifier active when the skill was invoked, when known
      */
@@ -6138,7 +6407,7 @@ export interface SkillInvokedData {
      */
     name: string;
     /**
-     * File path to the SKILL.md definition
+     * File path to the SKILL.md definition, or an empty string for an SDK-provided skill without a filesystem identity
      */
     path: string;
     /**
@@ -6150,7 +6419,7 @@ export interface SkillInvokedData {
      */
     pluginVersion?: string;
     /**
-     * Source identifier for where the skill was discovered. Known values include: project (workspace skill), inherited (parent-directory skill), personal-copilot (~/.copilot/skills), personal-agents (~/.agents/skills), custom (configured directory), plugin (installed plugin), builtin (bundled runtime skill), and remote (org/enterprise skill)
+     * Source identifier for where the skill was discovered. Known values include: project (workspace skill), inherited (parent-directory skill), personal-copilot (~/.copilot/skills), personal-agents (~/.agents/skills), custom (configured directory), plugin (installed plugin), builtin (bundled runtime skill), remote (org/enterprise skill), and sdk (SDK-provided skill)
      */
     source?: string;
     trigger?: SkillInvokedTrigger;
@@ -6355,6 +6624,10 @@ export interface SubagentCompletedData {
      * Model used by the sub-agent
      */
     model?: string;
+    /**
+     * Why an explicit task-call model did not become the effective model
+     */
+    modelOverrideReason?: string;
     /**
      * Tool call ID of the parent tool invocation that spawned this sub-agent
      */
@@ -6442,6 +6715,10 @@ export interface SubagentFailedData {
      * Model selected for the sub-agent, when known
      */
     model?: string;
+    /**
+     * Why an explicit task-call model did not become the effective model
+     */
+    modelOverrideReason?: string;
     /**
      * Tool call ID of the parent tool invocation that spawned this sub-agent
      */
@@ -7107,6 +7384,7 @@ export interface PermissionRequestedEvent {
  * Permission request notification requiring client approval with request details
  */
 export interface PermissionRequestedData {
+    agentMode?: SessionMode;
     permissionRequest: PermissionRequest;
     promptRequest?: PermissionPromptRequest;
     /**
@@ -9629,7 +9907,7 @@ export interface AutoModeResolvedData {
     stickyOverride?: boolean;
 }
 /**
- * Session event "session.managed_settings_resolved". Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. 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. Device values take precedence over server values per ordinary key, while permissions compose restrictively across device, server, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes.
+ * Session event "session.managed_settings_resolved". Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. 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. Device values take precedence over server values, then the policy helper, per ordinary key, while permissions compose restrictively across device, server, policy-helper, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes.
  */
 /** @experimental */
 export interface ManagedSettingsResolvedEvent {
@@ -9660,7 +9938,7 @@ export interface ManagedSettingsResolvedEvent {
     type: "session.managed_settings_resolved";
 }
 /**
- * Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. 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. Device values take precedence over server values per ordinary key, while permissions compose restrictively across device, server, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes.
+ * Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. 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. Device values take precedence over server values, then the policy helper, per ordinary key, while permissions compose restrictively across device, server, policy-helper, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. Marked experimental while the managed-settings surface stabilizes.
  */
 /** @experimental */
 export interface ManagedSettingsResolvedData {
@@ -9688,6 +9966,10 @@ export interface ManagedSettingsResolvedData {
      * Whether at least two managed sources supplied permission allowlists, so enforcement intersects them and the flattened settings payload omits `permissions.allow`.
      */
     permissionsAllowIntersected?: boolean;
+    /**
+     * Whether the policy-helper managed-settings layer was present. The policy helper is the weakest channel: it fills keys no enterprise source set and can never replace one.
+     */
+    policyHelperManaged?: boolean;
     /**
      * Whether the effective sandbox policy forces the sandbox on *only* because managed policy could not be determined, rather than because the policy requires it. Lets clients tell a user whose `--no-sandbox` was overridden that the sandbox stayed on as a fail-closed fallback, instead of attributing it to an administrator who set no such policy.
      */
@@ -10313,7 +10595,7 @@ export interface CustomAgentsUpdatedData {
     warnings: string[];
 }
 /**
- * A single loaded custom agent in `session.custom_agents_updated`, with identity, source, tools, invocability, and model override.
+ * A single loaded custom agent in `session.custom_agents_updated`, with identity, source, tools, invocability, and authored model configuration.
  */
 export interface CustomAgentsUpdatedAgent {
     /**
@@ -10332,6 +10614,11 @@ export interface CustomAgentsUpdatedAgent {
      * Model override for this agent, if set
      */
     model?: string;
+    modelPolicy?: AgentModelPolicy;
+    /**
+     * Authored model ids in priority order, if configured
+     */
+    models?: string[];
     /**
      * Internal name of the agent
      */

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./facto
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, createAttributedPermissionResult, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, 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, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, 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, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, AutoTier, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
 export type { RunOptions, ResumeOptions, FactoryResumeErrorCode, SessionFactoryApi, FactoryAgentOptions, FactoryContext, FactoryDefinition, FactoryHandle, FactoryJsonSchema, JsonValue, FactoryPipelineStage, FactoryStepOptions, FactoryRunResult, FactoryRunStatus, FactoryRunSummary, FactoryListRunsOptions, FactoryRunsPage, FactoryRunDetail, FactoryProgressPage, FactoryProgressLine, FactoryPhaseObservation, FactoryPhaseStatus, FactoryAgentSummary, } from "./factory.js";

package/dist/runtimeArtifacts.d.ts

@@ -2,5 +2,17 @@ export interface RuntimeArtifactSources {
     packageRoot: string;
     platform: string;
 }
+export interface EnsureRuntimeBundleOptions {
+    cacheRoot?: string;
+    packageSearchPaths?: string[];
+    platform?: string;
+}
+export declare const RUNTIME_PLATFORMS: readonly ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "linuxmusl-arm64", "linuxmusl-x64", "win32-arm64", "win32-x64"];
+export declare function validateFile(path: string, label: string): void;
 export declare function defaultRuntimeCacheRoot(platform?: NodeJS.Platform, home?: string, environment?: NodeJS.ProcessEnv): string;
-export declare function materializeRuntimeBundle(sources: RuntimeArtifactSources, cacheRoot?: string): string;
+export declare function materializeRuntimeBundle(sources: RuntimeArtifactSources, cacheRoot?: string, cacheKey?: string): string;
+export declare function getRuntimePlatform(platform?: NodeJS.Platform, arch?: NodeJS.Architecture, musl?: boolean): string;
+export declare function getRuntimeReleaseAssetName(version: string, platform: string): string;
+export declare function getRuntimePackageName(platform: string): string;
+export declare function resolvePackageRoot(packageName: string, searchPaths?: string[]): string | undefined;
+export declare function ensureRuntimeBundle(version: string, options?: EnsureRuntimeBundleOptions): Promise<string>;