@github/copilot-sdk 1.0.11-preview.2 → 1.0.12-preview.0

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 | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | 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 | FactoryRunUpdatedEvent | 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 | ContextClearedEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | 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 | 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;
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -76,6 +76,32 @@ export type AutopilotObjectiveChangedStatus =
  | "cap_reached"
 /** Objective was completed by the agent. */
  | "completed";
+/**
+ * Origin of an effective session model change.
+ */
+export type ModelChangeSource = 
+/** The user selected a model directly with `/model <id>`. */
+"model_command"
+/** The user selected the model with `/settings`. */
+ | "settings_command"
+/** The user selected the model with the `/config` alias. */
+ | "config_command"
+/** The user selected the model in the model picker, including the picker opened by bare `/model`. */
+ | "model_picker"
+/** Organization-managed settings selected the model. */
+ | "managed_settings"
+/** Repository settings selected the model. */
+ | "repo_settings"
+/** Startup model resolution selected the model. */
+ | "startup"
+/** Selecting an agent selected its configured model. */
+ | "agent"
+/** Entering, leaving, or reconfiguring plan mode selected the model. */
+ | "plan_mode"
+/** The runtime selected the model automatically, such as rate-limit recovery or refusal fallback. */
+ | "automatic"
+/** An SDK or RPC caller selected the model. */
+ | "sdk";
 /**
  * The session mode the agent is operating in
  */
@@ -87,16 +113,16 @@ export type SessionMode =
 /** The agent is working autonomously toward task completion. */
  | "autopilot";
 /**
- * Allow-all mode for the session.
+ * Permission mode for the session.
  */
 /** @experimental */
-export type PermissionAllowAllMode = 
+export type PermissionMode = 
 /** Permission requests follow the normal approval flow. */
-"off"
+"manual"
+/** Permission requests include an LLM safety recommendation; clients may automatically approve requests judged acceptable. */
+ | "assisted"
 /** Tool, path, and URL permission requests are automatically approved. */
- | "on"
-/** Permission requests follow the normal approval flow with an LLM advisory recommendation attached; clients may choose to auto-approve requests the judge evaluated as acceptable. */
- | "auto";
+ | "allow-all";
 /**
  * The type of operation performed on the plan file
  */
@@ -235,6 +261,14 @@ export type AssistantUsageApiEndpoint =
  | "/responses"
 /** WebSocket Responses API endpoint. */
  | "ws:/responses";
+/**
+ * Transport used for a successful model call
+ */
+export type AssistantUsageTransport = 
+/** HTTP transport, including SSE streams. */
+"http"
+/** WebSocket transport. */
+ | "websocket";
 /**
  * For HTTP 400 failures only: whether the response carried a structured CAPI error envelope (structured_error, a deterministic validation failure) or no error body (bodyless, the transient gateway/proxy signature). Absent for non-400 failures.
  */
@@ -395,7 +429,14 @@ export type SystemNotificationFactoryCompletedStatus =
 /**
  * Details of the permission being requested
  */
-export type PermissionRequest = PermissionRequestShell | PermissionRequestWrite | PermissionRequestRead | PermissionRequestMcp | PermissionRequestUrl | PermissionRequestMemory | PermissionRequestCustomTool | PermissionRequestHook | PermissionRequestExtensionManagement | PermissionRequestFactory | PermissionRequestExtensionPermissionAccess;
+export type PermissionRequest = PermissionRequestShell | PermissionRequestWrite | PermissionRequestRead | PermissionRequestMcp | PermissionRequestUrl | PermissionRequestMemory | PermissionRequestCustomTool | PermissionRequestHook | PermissionRequestExtensionManagement | PermissionRequestFactory | PermissionRequestExtensionPermissionAccess | PermissionRequestExtensionEnvAccess;
+/**
+ * Advisory recommendation the runtime attaches to a permission request whose origin it can vouch for by construction. Unlike the auto-approval judge this does not depend on auto mode and does not evaluate what the tool call does; its absence simply means the runtime has no opinion and the request follows the host's normal approval flow.
+ */
+/** @experimental */
+export type PermissionRecommendation = 
+/** The runtime vouches for the request's origin and recommends approving it without prompting. The host still owns the decision and may deny it; deny rules, managed policy, and the auto-approval safety judge all outrank this recommendation. */
+"approve";
 /**
  * Whether this is a store or vote memory operation
  */
@@ -405,30 +446,10 @@ export type PermissionRequestMemoryAction =
 /** Vote on an existing memory. */
  | "vote";
 /**
- * Vote direction (vote only)
- */
-export type PermissionRequestMemoryDirection = 
-/** Vote that the memory is useful or accurate. */
-"upvote"
-/** Vote that the memory is incorrect or outdated. */
- | "downvote";
-/**
- * Operation gated by a factory permission request.
- */
-export type FactoryPermissionOperation = 
-/** Running a registered factory, which spends subagents, active time, and AI credits under the approved limits. */
-"run"
-/** Authoring a factory, which writes JavaScript into a session-scoped extension and loads it. */
- | "author";
-/**
- * Derived user-facing permission prompt details for UI consumers
- */
-export type PermissionPromptRequest = PermissionPromptRequestCommands | PermissionPromptRequestWrite | PermissionPromptRequestRead | PermissionPromptRequestMcp | PermissionPromptRequestUrl | PermissionPromptRequestMemory | PermissionPromptRequestCustomTool | PermissionPromptRequestPath | PermissionPromptRequestHook | PermissionPromptRequestExtensionManagement | PermissionPromptRequestFactory | PermissionPromptRequestExtensionPermissionAccess;
-/**
- * Why the auto-approval judge produced no usable recommendation. Present only alongside an `error` recommendation, where the human-readable reason is a fixed string and therefore cannot distinguish these cases. Intended to make a judge failure reportable by a consumer that has no access to the host's logs.
+ * Why the assisted-approval judge produced no usable recommendation. Present only alongside an `error` recommendation, where the human-readable reason is a fixed string and therefore cannot distinguish these cases. Intended to make a judge failure reportable by a consumer that has no access to the host's logs.
  */
 /** @experimental */
-export type AutoApprovalJudgeFailureReason = 
+export type AssistedApprovalJudgeFailureReason = 
 /** The judge model call exceeded its deadline. */
 "timeout"
 /** The judge model call was cancelled before it returned. */
@@ -440,18 +461,46 @@ export type AutoApprovalJudgeFailureReason =
 /** The judge model replied, but the reply carried no ALLOW/DENY verdict. */
  | "parse_error";
 /**
- * Outcome of the auto-approval safety judge for a permission request. Present only when auto mode is enabled; its absence means the judge did not evaluate the request (auto mode was off).
+ * Outcome of the assisted-approval safety judge for a permission request. Present only in assisted mode; its absence means the judge did not evaluate the request.
  */
 /** @experimental */
-export type AutoApprovalRecommendation = 
+export type AssistedApprovalRecommendation = 
 /** The judge evaluated the request and recommends automatically approving it. */
 "approve"
-/** The judge evaluated the request and does not recommend auto-approving it; explicit approval is required. Whether that means prompting, denying, or something else is the consumer's decision. */
+/** The judge evaluated the request and does not recommend automatically approving it; explicit approval is required. Whether that means prompting, denying, or something else is the consumer's decision. */
  | "requireApproval"
-/** Auto mode is enabled, but this request category is never auto-approvable (for example, sandbox-bypass requests), so the judge was not consulted. */
+/** Assisted mode is enabled, but this request category is never automatically approvable (for example, sandbox-bypass requests), so the judge was not consulted. */
  | "excluded"
 /** The judge was consulted but did not return a usable recommendation, so the request requires explicit approval. */
  | "error";
+/**
+ * Vote direction (vote only)
+ */
+export type PermissionRequestMemoryDirection = 
+/** Vote that the memory is useful or accurate. */
+"upvote"
+/** Vote that the memory is incorrect or outdated. */
+ | "downvote";
+/**
+ * Scope of a stored memory.
+ */
+export type PermissionRequestMemoryScope = 
+/** Store the memory for the current repository. */
+"repository"
+/** Store the memory for the current user. */
+ | "user";
+/**
+ * Operation gated by a factory permission request.
+ */
+export type FactoryPermissionOperation = 
+/** Running a registered factory, which spends subagents, active time, and AI credits under the approved limits. */
+"run"
+/** Authoring a factory, which writes JavaScript into a session-scoped extension and loads it. */
+ | "author";
+/**
+ * Derived user-facing permission prompt details for UI consumers
+ */
+export type PermissionPromptRequest = PermissionPromptRequestCommands | PermissionPromptRequestWrite | PermissionPromptRequestRead | PermissionPromptRequestMcp | PermissionPromptRequestUrl | PermissionPromptRequestMemory | PermissionPromptRequestCustomTool | PermissionPromptRequestPath | PermissionPromptRequestHook | PermissionPromptRequestExtensionManagement | PermissionPromptRequestFactory | PermissionPromptRequestExtensionPermissionAccess | PermissionPromptRequestExtensionEnvAccess;
 /**
  * Underlying permission kind that needs path approval
  */
@@ -469,7 +518,7 @@ export type PermissionResult = PermissionApproved | PermissionApprovedForSession
 /**
  * The approval to add as a session-scoped rule
  */
-export type UserToolSessionApproval = UserToolSessionApprovalCommands | UserToolSessionApprovalRead | UserToolSessionApprovalWrite | UserToolSessionApprovalMcp | UserToolSessionApprovalMemory | UserToolSessionApprovalCustomTool | UserToolSessionApprovalExtensionManagement | UserToolSessionApprovalFactory | UserToolSessionApprovalExtensionPermissionAccess;
+export type UserToolSessionApproval = UserToolSessionApprovalCommands | UserToolSessionApprovalRead | UserToolSessionApprovalWrite | UserToolSessionApprovalMcp | UserToolSessionApprovalMemory | UserToolSessionApprovalCustomTool | UserToolSessionApprovalExtensionManagement | UserToolSessionApprovalFactory | UserToolSessionApprovalExtensionPermissionAccess | UserToolSessionApprovalExtensionEnvAccess;
 /**
  * Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
  */
@@ -536,6 +585,21 @@ export type McpHeadersRefreshCompletedOutcome =
  * Source-defined JSON payload for the custom notification
  */
 export type CustomNotificationPayload = JsonValue;
+/**
+ * Lifecycle phase for a Rust-owned ephemeral query stream.
+ */
+/** @experimental */
+export type UIEphemeralQueryPhase = 
+/** The ephemeral query stream has begun. */
+"started"
+/** A partial result chunk was produced by the stream. */
+ | "chunk"
+/** The ephemeral query stream finished successfully. */
+ | "completed"
+/** The ephemeral query stream ended with an error. */
+ | "failed"
+/** The ephemeral query stream was cancelled before completing. */
+ | "aborted";
 /**
  * The user's auto-mode-switch choice
  */
@@ -592,12 +656,12 @@ export type ManagedSettingsEnforcedAction =
  * 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. */
+/** Full allow-all permissions — automatically approving tools, paths, and URLs. */
 "allow_all"
-/** Auto-approval of all tool permission requests. */
+/** Automatic 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"
+/** Assisted mode — keeps normal prompt paths and adds an LLM recommendation, distinct from allow-all. */
+ | "assisted_approval"
 /** Unrestricted filesystem access outside the session's allowed directories. */
  | "unrestricted_paths"
 /** Unrestricted URL fetch access. */
@@ -614,6 +678,18 @@ export type ExitPlanModeAction =
  | "autopilot"
 /** Exit plan mode and continue with parallel autonomous workers. */
  | "autopilot_fleet";
+/**
+ * Terminal status a factory run committed. A settled run is never `pending` or `running`, so those two members of the run-status domain are deliberately absent.
+ */
+export type FactoryRunSettledStatus = 
+/** The factory body resolved and its result was committed. */
+"completed"
+/** The run was stopped by a limit, an approval refusal or another policy decision. */
+ | "halted"
+/** The run was cancelled by its caller or by session disposal. */
+ | "cancelled"
+/** The run failed, with `failureType` carrying the class when it has one. */
+ | "error";
 /**
  * Source location type (e.g., project, personal-copilot, plugin, builtin)
  */
@@ -1474,6 +1550,7 @@ export interface ModelChangeData {
      */
     reasoningEffort?: string | null;
     reasoningSummary?: ReasoningSummary;
+    source?: ModelChangeSource;
     verbosity?: Verbosity;
 }
 /**
@@ -1553,8 +1630,9 @@ export interface SessionLimitsChangedData {
     sessionLimits: SessionLimitsConfig | null;
 }
 /**
- * Session event "session.permissions_changed". Permissions change details carrying the aggregate allow-all transition.
+ * Session event "session.permissions_changed". Permission-mode transition details.
  */
+/** @experimental */
 export interface PermissionsChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1583,29 +1661,28 @@ export interface PermissionsChangedEvent {
     type: "session.permissions_changed";
 }
 /**
- * Permissions change details carrying the aggregate allow-all transition.
+ * Permission-mode transition details.
  */
+/** @experimental */
 export interface PermissionsChangedData {
     /**
-     * Allow-all mode after the change
+     * Explicit LLM judge model override used by assisted mode; omitted when the provider default applies
      *
      * @experimental
      */
-    allowAllPermissionMode?: PermissionAllowAllMode;
+    assistedApprovalModel?: string;
     /**
-     * Aggregate allow-all flag after the change
-     */
-    allowAllPermissions: boolean;
-    /**
-     * Allow-all mode before the change
+     * Permission mode after the change
      *
      * @experimental
      */
-    previousAllowAllPermissionMode?: PermissionAllowAllMode;
+    mode: PermissionMode;
     /**
-     * Aggregate allow-all flag before the change
+     * Permission mode before the change
+     *
+     * @experimental
      */
-    previousAllowAllPermissions: boolean;
+    previousMode: PermissionMode;
 }
 /**
  * Session event "session.plan_changed". Plan file operation details indicating what changed
@@ -1936,6 +2013,12 @@ export interface ShutdownEvent {
  * Session termination metrics including usage statistics, code changes, and shutdown reason
  */
 export interface ShutdownData {
+    /**
+     * Per-agent usage breakdown, keyed by agent instance identifier. The main conversation uses the stable key `main`.
+     */
+    agentMetrics?: {
+        [k: string]: ShutdownAgentMetric | undefined;
+    };
     codeChanges: ShutdownCodeChanges;
     /**
      * Non-system message token count at shutdown
@@ -1994,21 +2077,31 @@ export interface ShutdownData {
     totalNanoAiu?: number;
 }
 /**
- * Aggregate code change metrics for the session
+ * Usage attributed to one agent instance at session shutdown.
  */
-export interface ShutdownCodeChanges {
+export interface ShutdownAgentMetric {
     /**
-     * List of file paths that were modified during the session
+     * Human-readable label for this subagent invocation, copied from the originating `subagent.started` event. For task-tool subagents this is the invocation's task description rather than the agent's configured display name, so group by `agentName` for stable per-agent labels.
      */
-    filesModified: string[];
+    agentDisplayName?: string;
     /**
-     * Total number of lines added during the session
+     * Configured agent name, when this is a subagent
      */
-    linesAdded: number;
+    agentName?: string;
     /**
-     * Total number of lines removed during the session
+     * Per-model usage for this agent, keyed by model identifier
      */
-    linesRemoved: number;
+    modelMetrics: {
+        [k: string]: ShutdownModelMetric | undefined;
+    };
+    /**
+     * Time spent in model API calls by this agent, in milliseconds
+     */
+    totalApiDurationMs: number;
+    /**
+     * Accumulated nano-AI units cost for this agent
+     */
+    totalNanoAiu: number;
 }
 /**
  * Per-model shutdown metrics with request counts, token usage, nano-AI units, and token details.
@@ -2080,6 +2173,23 @@ export interface ShutdownModelMetricUsage {
      */
     reasoningTokens?: number;
 }
+/**
+ * Aggregate code change metrics for the session
+ */
+export interface ShutdownCodeChanges {
+    /**
+     * List of file paths that were modified during the session
+     */
+    filesModified: string[];
+    /**
+     * Total number of lines added during the session
+     */
+    linesAdded: number;
+    /**
+     * Total number of lines removed during the session
+     */
+    linesRemoved: number;
+}
 /**
  * A session-wide shutdown token-type entry storing the accumulated token count.
  */
@@ -2607,6 +2717,10 @@ export interface UserMessageData {
      * Transformed version of the message sent to the model, with XML wrapping, timestamps, and other augmentations for prompt caching
      */
     transformedContent?: string;
+    /**
+     * The agent-loop turn ID that consumed this message; absent when no agent-loop turn consumed it
+     */
+    turnId?: string;
 }
 /**
  * File attachment
@@ -3256,6 +3370,9 @@ export interface AssistantReasoningData {
      * Unique identifier for this reasoning block
      */
     reasoningId: string;
+    /**
+     * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
+     */
     rte?: boolean;
 }
 /**
@@ -3493,6 +3610,9 @@ export interface AssistantMessageData {
      * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs
      */
     requestId?: string;
+    /**
+     * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
+     */
     rte?: boolean;
     serverTools?: AssistantMessageServerTools;
     /**
@@ -3641,12 +3761,27 @@ export interface CitationLocationBlock {
  */
 /** @experimental */
 export interface AssistantMessageServerTools {
+    /**
+     * Advisor model identifier associated with the server-tool payload.
+     */
     advisorModel?: string;
+    /**
+     * Provider function-call namespaces keyed by function-call identifier.
+     */
     functionCallNamespaces?: {
         [k: string]: string | undefined;
     };
+    /**
+     * Provider-native server-tool call and output items preserved verbatim for replay.
+     */
     items?: JsonValue[];
+    /**
+     * Model provider that produced this server-tool payload.
+     */
     provider: string;
+    /**
+     * Raw provider content blocks retained for verbatim round-tripping.
+     */
     rawContentBlocks?: JsonValue[];
 }
 /**
@@ -3890,6 +4025,10 @@ export interface AssistantUsageEvent {
  * LLM API call usage metrics including tokens, costs, quotas, and billing information
  */
 export interface AssistantUsageData {
+    /**
+     * Number of accepted speculative prediction tokens
+     */
+    acceptedPredictionTokens?: number;
     /**
      * Completion ID from the model provider (e.g., chatcmpl-abc123)
      */
@@ -3942,6 +4081,22 @@ export interface AssistantUsageData {
      * Average inter-token latency in milliseconds. Only available for streaming requests
      */
     interTokenLatencyMs?: number;
+    /**
+     * Whether Auto mode was selected for this model call
+     */
+    isAuto?: boolean;
+    /**
+     * Whether this model call used a bring-your-own-key provider
+     */
+    isByok?: boolean;
+    /**
+     * Requested maximum output tokens used for this model call
+     */
+    maxOutputTokens?: number;
+    /**
+     * Effective maximum prompt-token limit used for this model call
+     */
+    maxPromptTokens?: number;
     /**
      * Model identifier used for this API call
      */
@@ -3963,10 +4118,18 @@ export interface AssistantUsageData {
      * Reasoning effort level used for model calls, if applicable (e.g. "none", "low", "medium", "high", "xhigh", "max")
      */
     reasoningEffort?: string;
+    reasoningSummary?: ReasoningSummary;
     /**
      * Number of output tokens used for reasoning (e.g., chain-of-thought)
      */
     reasoningTokens?: number;
+    /**
+     * Number of rejected speculative prediction tokens
+     */
+    rejectedPredictionTokens?: number;
+    /**
+     * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
+     */
     rte?: boolean;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
@@ -3976,6 +4139,7 @@ export interface AssistantUsageData {
      * Time to first token in milliseconds. Only available for streaming requests
      */
     timeToFirstTokenMs?: number;
+    transport?: AssistantUsageTransport;
 }
 /**
  * Per-request cost and usage data from the CAPI copilot_usage response field
@@ -4068,6 +4232,10 @@ export interface ModelCallFailureData {
      * What initiated this API call (e.g., "sub-agent", "mcp-sampling"); absent for user-initiated calls
      */
     initiator?: string;
+    /**
+     * Authoritative interaction classification for the failed call, matching `assistant.usage.interactionType` (for example `conversation-agent`, `conversation-subagent`, or `conversation-sampling`). Absent when the producer cannot classify the interaction.
+     */
+    interactionType?: string;
     /**
      * Whether the session selected Auto mode for the failed call
      */
@@ -4097,6 +4265,9 @@ export interface ModelCallFailureData {
      */
     reasoningEffort?: string;
     requestFingerprint?: ModelCallFailureRequestFingerprint;
+    /**
+     * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
+     */
     rte?: boolean;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
@@ -4284,6 +4455,9 @@ export interface ToolExecutionStartData {
      * Tool call ID of the parent tool invocation when this event originates from a sub-agent
      */
     parentToolCallId?: string;
+    /**
+     * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
+     */
     rte?: boolean;
     shellToolInfo?: ToolExecutionStartShellToolInfo;
     /**
@@ -4497,6 +4671,9 @@ export interface ToolExecutionCompleteData {
      */
     parentToolCallId?: string;
     result?: ToolExecutionCompleteResult;
+    /**
+     * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
+     */
     rte?: boolean;
     /**
      * Whether this tool execution ran inside a sandbox container
@@ -4910,17 +5087,35 @@ export interface ToolExecutionCompleteUIResourceMeta {
  */
 export interface ToolExecutionCompleteUIResourceMetaUI {
     csp?: ToolExecutionCompleteUIResourceMetaUICsp;
+    /**
+     * Optional dedicated origin for the rendered MCP Apps UI resource.
+     */
     domain?: string;
     permissions?: ToolExecutionCompleteUIResourceMetaUIPermissions;
+    /**
+     * Whether the host should render a border around the MCP Apps UI resource.
+     */
     prefersBorder?: boolean;
 }
 /**
  * CSP domain allowlists for an MCP Apps UI resource, including connect, resource, frame, and base URI domains.
  */
 export interface ToolExecutionCompleteUIResourceMetaUICsp {
+    /**
+     * Domains the UI resource may use as document base URIs.
+     */
     baseUriDomains?: string[];
+    /**
+     * Domains the UI resource may connect to.
+     */
     connectDomains?: string[];
+    /**
+     * Domains the UI resource may embed as nested frames.
+     */
     frameDomains?: string[];
+    /**
+     * Domains from which the UI resource may load scripts, styles, images, and other resources.
+     */
     resourceDomains?: string[];
 }
 /**
@@ -5146,6 +5341,10 @@ export interface SubagentStartedData {
      * Internal name of the sub-agent
      */
     agentName: string;
+    /**
+     * Root id of the factory run that spawned this sub-agent, when it was spawned by one.
+     */
+    factoryRunId?: string;
     /**
      * Model the sub-agent will run with, when known at start.
      */
@@ -5702,7 +5901,7 @@ export interface SystemNotificationData {
  */
 export interface SystemNotificationAgentCompleted {
     /**
-     * Unique identifier of the background agent
+     * Unique task identifier
      */
     agentId: string;
     /**
@@ -5713,6 +5912,10 @@ export interface SystemNotificationAgentCompleted {
      * Human-readable description of the agent task
      */
     description?: string;
+    /**
+     * Friendly, non-unique name intended for display
+     */
+    displayName?: string;
     /**
      * The full prompt given to the background agent
      */
@@ -5728,7 +5931,7 @@ export interface SystemNotificationAgentCompleted {
  */
 export interface SystemNotificationAgentIdle {
     /**
-     * Unique identifier of the background agent
+     * Unique task identifier
      */
     agentId: string;
     /**
@@ -5739,6 +5942,10 @@ export interface SystemNotificationAgentIdle {
      * Human-readable description of the agent task
      */
     description?: string;
+    /**
+     * Friendly, non-unique name intended for display
+     */
+    displayName?: string;
     /**
      * Type discriminator. Always "agent_idle".
      */
@@ -6126,6 +6333,12 @@ export interface PermissionRequestMcp {
      * Permission kind discriminator
      */
     kind: "mcp";
+    /**
+     * Advisory runtime permission recommendation. The SDK host remains responsible for deciding the request and may reject it.
+     *
+     * @experimental
+     */
+    permissionRecommendation?: PermissionRecommendation;
     /**
      * Whether this MCP tool is read-only (no side effects)
      */
@@ -6189,6 +6402,12 @@ export interface PermissionRequestUrl {
  */
 export interface PermissionRequestMemory {
     action?: PermissionRequestMemoryAction;
+    /**
+     * Assisted-approval judge information for this request; present only in assisted mode.
+     *
+     * @experimental
+     */
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Source references for the stored fact (store only)
      */
@@ -6206,6 +6425,11 @@ export interface PermissionRequestMemory {
      * Reason for the vote (vote only)
      */
     reason?: string;
+    /**
+     * Repository name with owner associated with the stored memory (store only)
+     */
+    repoNwo?: string;
+    scope?: PermissionRequestMemoryScope;
     /**
      * Topic or subject of the memory (store only)
      */
@@ -6215,6 +6439,22 @@ export interface PermissionRequestMemory {
      */
     toolCallId?: string;
 }
+/**
+ * Assisted-approval judge information attached to a permission request. Present only in assisted mode; its absence means the judge did not evaluate the request. The `recommendation` conveys the judge's disposition for this request.
+ */
+/** @experimental */
+export interface PermissionAssistedApproval {
+    failureReason?: AssistedApprovalJudgeFailureReason;
+    /**
+     * Model id that produced the recommendation, when the judge was consulted and reported one. Absent for `excluded` (the judge was not consulted) and for failures that occurred before a model was selected.
+     */
+    model?: string;
+    /**
+     * Human-readable reason for the judge's recommendation, when available.
+     */
+    reason?: string;
+    recommendation: AssistedApprovalRecommendation;
+}
 /**
  * Custom tool invocation permission request
  */
@@ -6227,6 +6467,10 @@ export interface PermissionRequestCustomTool {
      * Permission kind discriminator
      */
     kind: "custom-tool";
+    /**
+     * Whether the tool declared that permission may be skipped unless a deny rule matches
+     */
+    skipPermission?: boolean;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -6298,9 +6542,21 @@ export interface PermissionRequestFactory {
      * Whether this factory is eligible for persistent approval
      */
     canPersistApproval: boolean;
+    /**
+     * Factory-declared AI-credit limit before any run/resume caller override is applied.
+     */
     declaredMaxAiCredits?: number;
+    /**
+     * Factory-declared concurrent-subagent limit before any run/resume caller override is applied.
+     */
     declaredMaxConcurrentSubagents?: number;
+    /**
+     * Factory-declared total-subagent limit before any run/resume caller override is applied.
+     */
     declaredMaxTotalSubagents?: number;
+    /**
+     * Factory-declared active-time limit in seconds before any run/resume caller override is applied.
+     */
     declaredTimeoutSeconds?: number;
     /**
      * Factory description
@@ -6374,16 +6630,39 @@ export interface PermissionRequestExtensionPermissionAccess {
      */
     toolCallId?: string;
 }
+/**
+ * Extension sensitive environment variable access request
+ */
+export interface PermissionRequestExtensionEnvAccess {
+    /**
+     * Names of the sensitive environment variables the extension is requesting. Values never appear here.
+     *
+     * @minItems 1
+     */
+    environmentVariables: [string, ...string[]];
+    /**
+     * Name of the extension requesting environment variable access
+     */
+    extensionName: string;
+    /**
+     * Permission kind discriminator
+     */
+    kind: "extension-env-access";
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
 /**
  * Shell command permission prompt
  */
 export interface PermissionPromptRequestCommands {
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Whether the UI can offer session-wide approval for this command pattern
      */
@@ -6417,32 +6696,16 @@ export interface PermissionPromptRequestCommands {
      */
     warning?: string;
 }
-/**
- * Auto-approval judge information attached to a permission request. Present (non-null) only when the session's allow-all mode is "auto"; its absence means auto mode was off and the judge did not evaluate the request. The `recommendation` conveys the judge's disposition for this request.
- */
-/** @experimental */
-export interface PermissionAutoApproval {
-    failureReason?: AutoApprovalJudgeFailureReason;
-    /**
-     * Model id that produced the recommendation, when the judge was consulted and reported one. Absent for `excluded` (the judge was not consulted) and for failures that occurred before a model was selected.
-     */
-    model?: string;
-    /**
-     * Human-readable reason for the judge's recommendation, when available.
-     */
-    reason?: string;
-    recommendation: AutoApprovalRecommendation;
-}
 /**
  * File write permission prompt
  */
 export interface PermissionPromptRequestWrite {
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Whether the UI can offer session-wide approval for file write operations
      */
@@ -6481,11 +6744,11 @@ export interface PermissionPromptRequestWrite {
  */
 export interface PermissionPromptRequestRead {
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Human-readable description of why the file is being read
      */
@@ -6516,15 +6779,21 @@ export interface PermissionPromptRequestMcp {
      */
     args?: JsonValue;
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Prompt kind discriminator
      */
     kind: "mcp";
+    /**
+     * Advisory runtime permission recommendation. The host remains responsible for deciding the request and may reject it.
+     *
+     * @experimental
+     */
+    permissionRecommendation?: PermissionRecommendation;
     /**
      * Name of the MCP server providing the tool
      */
@@ -6547,11 +6816,11 @@ export interface PermissionPromptRequestMcp {
  */
 export interface PermissionPromptRequestUrl {
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Human-readable description of why the URL is being accessed
      */
@@ -6591,11 +6860,11 @@ export interface PermissionPromptRequestUrl {
 export interface PermissionPromptRequestMemory {
     action?: PermissionRequestMemoryAction;
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Source references for the stored fact (store only)
      */
@@ -6631,11 +6900,11 @@ export interface PermissionPromptRequestCustomTool {
      */
     args?: JsonValue;
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Prompt kind discriminator
      */
@@ -6659,11 +6928,11 @@ export interface PermissionPromptRequestCustomTool {
 export interface PermissionPromptRequestPath {
     accessKind: PermissionPromptRequestPathAccessKind;
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Prompt kind discriminator
      */
@@ -6682,11 +6951,11 @@ export interface PermissionPromptRequestPath {
  */
 export interface PermissionPromptRequestHook {
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Optional message from the hook explaining why confirmation is needed
      */
@@ -6713,11 +6982,11 @@ export interface PermissionPromptRequestHook {
  */
 export interface PermissionPromptRequestExtensionManagement {
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Name of the extension being managed
      */
@@ -6744,18 +7013,30 @@ export interface PermissionPromptRequestFactory {
      */
     approvalKey: string;
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Whether this factory is eligible for persistent approval
      */
     canPersistApproval: boolean;
+    /**
+     * Factory-declared AI-credit limit before any run/resume caller override is applied.
+     */
     declaredMaxAiCredits?: number;
+    /**
+     * Factory-declared concurrent-subagent limit before any run/resume caller override is applied.
+     */
     declaredMaxConcurrentSubagents?: number;
+    /**
+     * Factory-declared total-subagent limit before any run/resume caller override is applied.
+     */
     declaredMaxTotalSubagents?: number;
+    /**
+     * Factory-declared active-time limit in seconds before any run/resume caller override is applied.
+     */
     declaredTimeoutSeconds?: number;
     /**
      * Factory description
@@ -6804,11 +7085,11 @@ export interface PermissionPromptRequestFactory {
  */
 export interface PermissionPromptRequestExtensionPermissionAccess {
     /**
-     * Auto-approval judge information for this request; present only when auto mode is enabled.
+     * Assisted-approval judge information for this request; present only in assisted mode.
      *
      * @experimental
      */
-    autoApproval?: PermissionAutoApproval;
+    assistedApproval?: PermissionAssistedApproval;
     /**
      * Capabilities the extension is requesting
      */
@@ -6826,6 +7107,35 @@ export interface PermissionPromptRequestExtensionPermissionAccess {
      */
     toolCallId?: string;
 }
+/**
+ * Extension sensitive environment variable access prompt
+ */
+export interface PermissionPromptRequestExtensionEnvAccess {
+    /**
+     * Assisted-approval judge information for this request; present only in assisted mode.
+     *
+     * @experimental
+     */
+    assistedApproval?: PermissionAssistedApproval;
+    /**
+     * Names of the sensitive environment variables the extension is requesting. Values never appear here.
+     *
+     * @minItems 1
+     */
+    environmentVariables: [string, ...string[]];
+    /**
+     * Name of the extension requesting environment variable access
+     */
+    extensionName: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "extension-env-access";
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
 /**
  * Session event "permission.completed". Permission request completion notification signaling UI dismissal
  */
@@ -6878,6 +7188,10 @@ export interface PermissionApproved {
      * The permission request was approved
      */
     kind: "approved";
+    /**
+     * Whether a managed approval policy already handled this request
+     */
+    managedApprovalHandled?: boolean;
 }
 /**
  * Permission response variant that approves a request and remembers the provided approval for the rest of the session.
@@ -6888,6 +7202,10 @@ export interface PermissionApprovedForSession {
      * Approved and remembered for the rest of the session
      */
     kind: "approved-for-session";
+    /**
+     * Whether a managed approval policy already handled this request
+     */
+    managedApprovalHandled?: boolean;
 }
 /**
  * Session-scoped tool-approval rule for specific shell command identifiers.
@@ -6998,6 +7316,25 @@ export interface UserToolSessionApprovalExtensionPermissionAccess {
      */
     kind: "extension-permission-access";
 }
+/**
+ * Session-scoped tool-approval rule for an extension's access to sensitive environment variables, keyed by extension name and the exact set of variable names.
+ */
+export interface UserToolSessionApprovalExtensionEnvAccess {
+    /**
+     * Names of the sensitive environment variables this approval covers. Values are never persisted.
+     *
+     * @minItems 1
+     */
+    environmentVariables: [string, ...string[]];
+    /**
+     * Extension name
+     */
+    extensionName: string;
+    /**
+     * Extension environment access approval kind
+     */
+    kind: "extension-env-access";
+}
 /**
  * Permission response variant that approves a request and persists the provided approval to a project location key.
  */
@@ -7011,6 +7348,10 @@ export interface PermissionApprovedForLocation {
      * The location key (git root or cwd) to persist the approval to
      */
     locationKey: string;
+    /**
+     * Whether a managed approval policy already handled this request
+     */
+    managedApprovalHandled?: boolean;
 }
 /**
  * Permission response variant indicating the request was cancelled before use, with an optional reason.
@@ -7727,6 +8068,60 @@ export interface CustomNotificationData {
 export interface CustomNotificationSubject {
     [k: string]: string | undefined;
 }
+/**
+ * Session event "ui.ephemeral_query". Ordered output and terminal state for a transient query that does not modify conversation history.
+ */
+/** @experimental */
+export interface UIEphemeralQueryEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: UIEphemeralQueryData;
+    /**
+     * 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 "ui.ephemeral_query".
+     */
+    type: "ui.ephemeral_query";
+}
+/**
+ * Ordered output and terminal state for a transient query that does not modify conversation history.
+ */
+/** @experimental */
+export interface UIEphemeralQueryData {
+    /**
+     * Full response text, present for the `completed` phase.
+     */
+    answer?: string;
+    /**
+     * Ordered text delta, present for the `chunk` phase.
+     */
+    chunk?: string;
+    /**
+     * Model or transport failure message, present for the `failed` phase.
+     */
+    error?: string;
+    phase: UIEphemeralQueryPhase;
+    /**
+     * Runtime-minted query identifier.
+     */
+    requestId: string;
+}
 /**
  * Session event "external_tool.requested". External tool invocation request for client-side tool execution
  */
@@ -7765,6 +8160,10 @@ export interface ExternalToolRequestedData {
      * Arguments to pass to the external tool
      */
     arguments?: JsonValue;
+    /**
+     * Stable provider identity captured with an extension-owned tool definition; hosts use it to route the request to the same provider that was offered to the model
+     */
+    providerId?: string | null;
     /**
      * Unique identifier for this request; used to respond via session.respondToExternalTool()
      */
@@ -8514,6 +8913,10 @@ export interface ExitPlanModeRequestedData {
      * Available actions the user can take
      */
     actions: ExitPlanModeAction[];
+    /**
+     * Model the session had selected when the plan was authored, when one is known
+     */
+    model?: string;
     /**
      * Full content of the plan file
      */
@@ -8694,7 +9097,117 @@ export interface FactoryRunUpdatedData {
      * Monotonic revision now available for the run.
      */
     revision: number;
+    /**
+     * Factory run identifier.
+     */
+    runId: string;
+}
+/**
+ * Session event "factory.run_started". Ephemeral signal that a factory run attempt began executing.
+ */
+/** @experimental */
+export interface FactoryRunStartedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: FactoryRunStartedData;
+    /**
+     * 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 "factory.run_started".
+     */
+    type: "factory.run_started";
+}
+/**
+ * Ephemeral signal that a factory run attempt began executing.
+ */
+/** @experimental */
+export interface FactoryRunStartedData {
+    /**
+     * Attempt number this start committed; a resumed run increments it.
+     */
+    attempt: number;
+    /**
+     * Name of the factory this run executes. Low cardinality by construction.
+     */
+    factoryName: string;
+    /**
+     * Identifier of the factory run that started.
+     */
+    runId: string;
+}
+/**
+ * Session event "factory.run_settled". Ephemeral signal that a factory run reached a terminal status.
+ */
+/** @experimental */
+export interface FactoryRunSettledEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: FactoryRunSettledData;
+    /**
+     * 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 "factory.run_settled".
+     */
+    type: "factory.run_settled";
+}
+/**
+ * Ephemeral signal that a factory run reached a terminal status.
+ */
+/** @experimental */
+export interface FactoryRunSettledData {
+    /**
+     * AI credits this run consumed, in nano-AIU.
+     */
+    consumedNanoAiu: number;
+    /**
+     * Subagents this run consumed against its limits.
+     */
+    consumedSubagents: number;
+    /**
+     * Active milliseconds accumulated across every attempt of this run.
+     */
+    elapsedMs: number;
+    /**
+     * Typed failure class recorded on the run, when it failed with one (e.g. `factory_limit_reached`).
+     */
+    failureType?: string;
+    /**
+     * Identifier of the factory run that settled.
+     */
     runId: string;
+    status: FactoryRunSettledStatus;
 }
 /**
  * Session event "session.skills_loaded". Payload of `session.skills_loaded` listing resolved skill metadata.