@github/copilot-sdk 1.0.0-beta.3 → 1.0.0-beta.5

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

@@ -2,31 +2,84 @@
  * AUTO-GENERATED FILE - DO NOT EDIT
  * Generated from: session-events.schema.json
  */
-export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PlanChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantUsageEvent | ModelCallFailureEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent;
+/**
+ * Union of all session event variants emitted by the Copilot CLI runtime.
+ */
+export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PlanChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantUsageEvent | ModelCallFailureEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | CustomNotificationEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent;
 /**
  * Hosting platform type of the repository (github or ado)
  */
-export type WorkingDirectoryContextHostType = "github" | "ado";
+export type WorkingDirectoryContextHostType = 
+/** Repository is hosted on GitHub. */
+"github"
+/** Repository is hosted on Azure DevOps. */
+ | "ado";
+/**
+ * Reasoning summary mode used for model calls, if applicable (e.g. "none", "concise", "detailed")
+ */
+export type ReasoningSummary = 
+/** Do not request reasoning summaries from the model. */
+"none"
+/** Request a concise summary of the model's reasoning. */
+ | "concise"
+/** Request a detailed summary of the model's reasoning. */
+ | "detailed";
+/**
+ * The session mode the agent is operating in
+ */
+export type SessionMode = 
+/** The agent is responding interactively to the user. */
+"interactive"
+/** The agent is preparing a plan before making changes. */
+ | "plan"
+/** The agent is working autonomously toward task completion. */
+ | "autopilot";
 /**
  * The type of operation performed on the plan file
  */
-export type PlanChangedOperation = "create" | "update" | "delete";
+export type PlanChangedOperation = 
+/** The plan file was created. */
+"create"
+/** The plan file was updated. */
+ | "update"
+/** The plan file was deleted. */
+ | "delete";
 /**
  * Whether the file was newly created or updated
  */
-export type WorkspaceFileChangedOperation = "create" | "update";
+export type WorkspaceFileChangedOperation = 
+/** The workspace file was created. */
+"create"
+/** The workspace file was updated. */
+ | "update";
 /**
  * Origin type of the session being handed off
  */
-export type HandoffSourceType = "remote" | "local";
+export type HandoffSourceType = 
+/** The handoff originated from a remote session. */
+"remote"
+/** The handoff originated from a local session. */
+ | "local";
 /**
  * Whether the session ended normally ("routine") or due to a crash/fatal error ("error")
  */
-export type ShutdownType = "routine" | "error";
+export type ShutdownType = 
+/** The session ended normally. */
+"routine"
+/** The session ended because of a crash or fatal error. */
+ | "error";
 /**
  * The agent mode that was active when this message was sent
  */
-export type UserMessageAgentMode = "interactive" | "plan" | "autopilot" | "shell";
+export type UserMessageAgentMode = 
+/** The agent is responding interactively to the user. */
+"interactive"
+/** The agent is preparing a plan before making changes. */
+ | "plan"
+/** The agent is working autonomously toward task completion. */
+ | "autopilot"
+/** The agent is in shell-focused UI mode. */
+ | "shell";
 /**
  * A user message attachment — a file, directory, code selection, blob, or GitHub reference
  */
@@ -34,19 +87,53 @@ export type UserMessageAttachment = UserMessageAttachmentFile | UserMessageAttac
 /**
  * Type of GitHub reference
  */
-export type UserMessageAttachmentGithubReferenceType = "issue" | "pr" | "discussion";
+export type UserMessageAttachmentGithubReferenceType = 
+/** GitHub issue reference. */
+"issue"
+/** GitHub pull request reference. */
+ | "pr"
+/** GitHub discussion reference. */
+ | "discussion";
 /**
  * Tool call type: "function" for standard tool calls, "custom" for grammar-based tool calls. Defaults to "function" when absent.
  */
-export type AssistantMessageToolRequestType = "function" | "custom";
+export type AssistantMessageToolRequestType = 
+/** Standard function-style tool call. */
+"function"
+/** Custom grammar-based tool call. */
+ | "custom";
+/**
+ * API endpoint used for this model call, matching CAPI supported_endpoints vocabulary
+ */
+export type AssistantUsageApiEndpoint = 
+/** Chat Completions API endpoint. */
+"/chat/completions"
+/** Anthropic Messages API endpoint. */
+ | "/v1/messages"
+/** Responses API endpoint. */
+ | "/responses"
+/** WebSocket Responses API endpoint. */
+ | "ws:/responses";
 /**
  * Where the failed model call originated
  */
-export type ModelCallFailureSource = "top_level" | "subagent" | "mcp_sampling";
+export type ModelCallFailureSource = 
+/** Model call from the top-level agent. */
+"top_level"
+/** Model call from a sub-agent. */
+ | "subagent"
+/** Model call from MCP sampling. */
+ | "mcp_sampling";
 /**
  * Finite reason code describing why the current turn was aborted
  */
-export type AbortReason = "user_initiated" | "remote_command" | "user_abort";
+export type AbortReason = 
+/** The local user requested the abort, for example by pressing Ctrl+C in the CLI. */
+"user_initiated"
+/** A remote command requested the abort. */
+ | "remote_command"
+/** An MCP server delivered a user.abort notification. */
+ | "user_abort";
 /**
  * A content block within a tool result, which may be text, terminal output, image, audio, or a resource
  */
@@ -54,7 +141,11 @@ export type ToolExecutionCompleteContent = ToolExecutionCompleteContentText | To
 /**
  * Theme variant this icon is intended for
  */
-export type ToolExecutionCompleteContentResourceLinkIconTheme = "light" | "dark";
+export type ToolExecutionCompleteContentResourceLinkIconTheme = 
+/** Icon intended for light themes. */
+"light"
+/** Icon intended for dark themes. */
+ | "dark";
 /**
  * The embedded resource contents, either text or base64-encoded binary
  */
@@ -62,7 +153,11 @@ export type ToolExecutionCompleteContentResourceDetails = EmbeddedTextResourceCo
 /**
  * Message role: "system" for system prompts, "developer" for developer-injected instructions
  */
-export type SystemMessageRole = "system" | "developer";
+export type SystemMessageRole = 
+/** System prompt message. */
+"system"
+/** Developer instruction message. */
+ | "developer";
 /**
  * Structured metadata identifying what triggered this notification
  */
@@ -70,35 +165,45 @@ export type SystemNotification = SystemNotificationAgentCompleted | SystemNotifi
 /**
  * Whether the agent completed successfully or failed
  */
-export type SystemNotificationAgentCompletedStatus = "completed" | "failed";
+export type SystemNotificationAgentCompletedStatus = 
+/** The agent completed successfully. */
+"completed"
+/** The agent failed. */
+ | "failed";
 /**
  * Details of the permission being requested
  */
-export type PermissionRequest = PermissionRequestShell | PermissionRequestWrite | PermissionRequestRead | PermissionRequestMcp | PermissionRequestUrl | PermissionRequestMemory | PermissionRequestCustomTool | PermissionRequestHook;
+export type PermissionRequest = PermissionRequestShell | PermissionRequestWrite | PermissionRequestRead | PermissionRequestMcp | PermissionRequestUrl | PermissionRequestMemory | PermissionRequestCustomTool | PermissionRequestHook | PermissionRequestExtensionManagement | PermissionRequestExtensionPermissionAccess;
 /**
  * Whether this is a store or vote memory operation
  */
-export type PermissionRequestMemoryAction = "store" | "vote";
+export type PermissionRequestMemoryAction = 
+/** Store a new memory. */
+"store"
+/** Vote on an existing memory. */
+ | "vote";
 /**
  * Vote direction (vote only)
  */
-export type PermissionRequestMemoryDirection = "upvote" | "downvote";
+export type PermissionRequestMemoryDirection = 
+/** Vote that the memory is useful or accurate. */
+"upvote"
+/** Vote that the memory is incorrect or outdated. */
+ | "downvote";
 /**
  * Derived user-facing permission prompt details for UI consumers
  */
-export type PermissionPromptRequest = PermissionPromptRequestCommands | PermissionPromptRequestWrite | PermissionPromptRequestRead | PermissionPromptRequestMcp | PermissionPromptRequestUrl | PermissionPromptRequestMemory | PermissionPromptRequestCustomTool | PermissionPromptRequestPath | PermissionPromptRequestHook;
-/**
- * Whether this is a store or vote memory operation
- */
-export type PermissionPromptRequestMemoryAction = "store" | "vote";
-/**
- * Vote direction (vote only)
- */
-export type PermissionPromptRequestMemoryDirection = "upvote" | "downvote";
+export type PermissionPromptRequest = PermissionPromptRequestCommands | PermissionPromptRequestWrite | PermissionPromptRequestRead | PermissionPromptRequestMcp | PermissionPromptRequestUrl | PermissionPromptRequestMemory | PermissionPromptRequestCustomTool | PermissionPromptRequestPath | PermissionPromptRequestHook | PermissionPromptRequestExtensionManagement | PermissionPromptRequestExtensionPermissionAccess;
 /**
  * Underlying permission kind that needs path approval
  */
-export type PermissionPromptRequestPathAccessKind = "read" | "shell" | "write";
+export type PermissionPromptRequestPathAccessKind = 
+/** Read access to a filesystem path. */
+"read"
+/** Shell command access involving a filesystem path. */
+ | "shell"
+/** Write access to a filesystem path. */
+ | "write";
 /**
  * The result of the permission request
  */
@@ -106,32 +211,126 @@ export type PermissionResult = PermissionApproved | PermissionApprovedForSession
 /**
  * The approval to add as a session-scoped rule
  */
-export type UserToolSessionApproval = UserToolSessionApprovalCommands | UserToolSessionApprovalRead | UserToolSessionApprovalWrite | UserToolSessionApprovalMcp | UserToolSessionApprovalMemory | UserToolSessionApprovalCustomTool;
+export type UserToolSessionApproval = UserToolSessionApprovalCommands | UserToolSessionApprovalRead | UserToolSessionApprovalWrite | UserToolSessionApprovalMcp | UserToolSessionApprovalMemory | UserToolSessionApprovalCustomTool | UserToolSessionApprovalExtensionManagement | UserToolSessionApprovalExtensionPermissionAccess;
 /**
  * Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
  */
-export type ElicitationRequestedMode = "form" | "url";
+export type ElicitationRequestedMode = 
+/** Structured form-based elicitation. */
+"form"
+/** Browser URL-based elicitation. */
+ | "url";
 /**
  * The user action: "accept" (submitted form), "decline" (explicitly refused), or "cancel" (dismissed)
  */
-export type ElicitationCompletedAction = "accept" | "decline" | "cancel";
-export type ElicitationCompletedContent = string | number | boolean | string[];
+export type ElicitationCompletedAction = 
+/** The user submitted the requested form. */
+"accept"
+/** The user explicitly declined the request. */
+ | "decline"
+/** The user dismissed the request. */
+ | "cancel";
+/**
+ * Schema for the `ElicitationCompletedContent` type.
+ */
+export type ElicitationCompletedContent = (string | number | boolean | string[]) | undefined;
+/**
+ * Source-defined JSON payload for the custom notification
+ */
+export type CustomNotificationPayload = string | number | boolean | null | unknown[] | {
+    [k: string]: unknown | undefined;
+};
+/**
+ * The user's auto-mode-switch choice
+ */
+export type AutoModeSwitchResponse = 
+/** Switch models for this request. */
+"yes"
+/** Switch models now and keep using the replacement automatically. */
+ | "yes_always"
+/** Do not switch models. */
+ | "no";
+/**
+ * Exit plan mode action
+ */
+export type ExitPlanModeAction = 
+/** Exit plan mode without starting implementation. */
+"exit_only"
+/** Exit plan mode and continue in interactive mode. */
+ | "interactive"
+/** Exit plan mode and continue autonomously. */
+ | "autopilot"
+/** Exit plan mode and continue with parallel autonomous workers. */
+ | "autopilot_fleet";
+/**
+ * Source location type (e.g., project, personal-copilot, plugin, builtin)
+ */
+export type SkillSource = 
+/** Skill defined in the current project's skill directories. */
+"project"
+/** Skill discovered from a parent directory in the current workspace tree. */
+ | "inherited"
+/** Skill defined in the user's Copilot skill directory. */
+ | "personal-copilot"
+/** Skill defined in the user's personal agents skill directory. */
+ | "personal-agents"
+/** Skill provided by an installed plugin. */
+ | "plugin"
+/** Skill loaded from a configured custom skill directory. */
+ | "custom"
+/** Skill bundled with the runtime. */
+ | "builtin";
+/**
+ * Configuration source: user, workspace, plugin, or builtin
+ */
+export type McpServerSource = 
+/** Server configured in the user's global MCP configuration. */
+"user"
+/** Server configured by the current workspace. */
+ | "workspace"
+/** Server contributed by an installed plugin. */
+ | "plugin"
+/** Server bundled with the runtime. */
+ | "builtin";
 /**
  * Connection status: connected, failed, needs-auth, pending, disabled, or not_configured
  */
-export type McpServersLoadedServerStatus = "connected" | "failed" | "needs-auth" | "pending" | "disabled" | "not_configured";
-/**
- * New connection status: connected, failed, needs-auth, pending, disabled, or not_configured
- */
-export type McpServerStatusChangedStatus = "connected" | "failed" | "needs-auth" | "pending" | "disabled" | "not_configured";
+export type McpServerStatus = 
+/** The server is connected and available. */
+"connected"
+/** The server failed to connect or initialize. */
+ | "failed"
+/** The server requires authentication before it can connect. */
+ | "needs-auth"
+/** The server connection is still being established. */
+ | "pending"
+/** The server is configured but disabled. */
+ | "disabled"
+/** The server is not configured for this session. */
+ | "not_configured";
 /**
  * Discovery source
  */
-export type ExtensionsLoadedExtensionSource = "project" | "user";
+export type ExtensionsLoadedExtensionSource = 
+/** Extension discovered from the current project. */
+"project"
+/** Extension discovered from the user's extension directory. */
+ | "user";
 /**
  * Current status: running, disabled, failed, or starting
  */
-export type ExtensionsLoadedExtensionStatus = "running" | "disabled" | "failed" | "starting";
+export type ExtensionsLoadedExtensionStatus = 
+/** The extension process is running. */
+"running"
+/** The extension is installed but disabled. */
+ | "disabled"
+/** The extension failed to start or crashed. */
+ | "failed"
+/** The extension process is starting. */
+ | "starting";
+/**
+ * Session event "session.start". Session initialization metadata including context and configuration
+ */
 export interface StartEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -154,6 +353,9 @@ export interface StartEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.start".
+     */
     type: "session.start";
 }
 /**
@@ -169,16 +371,21 @@ export interface StartData {
      * Version string of the Copilot application
      */
     copilotVersion: string;
+    /**
+     * When set, identifies a parent session whose context this session continues — e.g., a detached headless rem-agent run launched on the parent's interactive shutdown. Telemetry from this session is reported under the parent's session_id.
+     */
+    detachedFromSpawningParentSessionId?: string;
     /**
      * Identifier of the software producing the events (e.g., "copilot-agent")
      */
     producer: string;
     /**
-     * Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh")
+     * Reasoning effort level used for model calls, if applicable (e.g. "none", "low", "medium", "high", "xhigh", "max")
      */
     reasoningEffort?: string;
+    reasoningSummary?: ReasoningSummary;
     /**
-     * Whether this session supports remote steering via Mission Control
+     * Whether this session supports remote steering via GitHub
      */
     remoteSteerable?: boolean;
     /**
@@ -232,6 +439,9 @@ export interface WorkingDirectoryContext {
      */
     repositoryHost?: string;
 }
+/**
+ * Session event "session.resume". Session resume metadata including current context and event count
+ */
 export interface ResumeEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -254,6 +464,9 @@ export interface ResumeEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.resume".
+     */
     type: "session.resume";
 }
 /**
@@ -274,11 +487,12 @@ export interface ResumeData {
      */
     eventCount: number;
     /**
-     * Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh")
+     * Reasoning effort level used for model calls, if applicable (e.g. "none", "low", "medium", "high", "xhigh", "max")
      */
     reasoningEffort?: string;
+    reasoningSummary?: ReasoningSummary;
     /**
-     * Whether this session supports remote steering via Mission Control
+     * Whether this session supports remote steering via GitHub
      */
     remoteSteerable?: boolean;
     /**
@@ -294,6 +508,9 @@ export interface ResumeData {
      */
     sessionWasActive?: boolean;
 }
+/**
+ * Session event "session.remote_steerable_changed". Notifies that the session's remote steering capability has changed
+ */
 export interface RemoteSteerableChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -316,17 +533,23 @@ export interface RemoteSteerableChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.remote_steerable_changed".
+     */
     type: "session.remote_steerable_changed";
 }
 /**
- * Notifies Mission Control that the session's remote steering capability has changed
+ * Notifies that the session's remote steering capability has changed
  */
 export interface RemoteSteerableChangedData {
     /**
-     * Whether this session now supports remote steering via Mission Control
+     * Whether this session now supports remote steering via GitHub
      */
     remoteSteerable: boolean;
 }
+/**
+ * Session event "session.error". Error details for timeline display including message and optional diagnostic information
+ */
 export interface ErrorEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -349,6 +572,9 @@ export interface ErrorEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.error".
+     */
     type: "session.error";
 }
 /**
@@ -360,7 +586,7 @@ export interface ErrorData {
      */
     eligibleForAutoSwitch?: boolean;
     /**
-     * Fine-grained error code from the upstream provider, when available. For `errorType: "rate_limit"`, this is one of the `RateLimitErrorCode` values (e.g., `"user_weekly_rate_limited"`, `"user_global_rate_limited"`, `"rate_limited"`, `"user_model_rate_limited"`, `"integration_rate_limited"`).
+     * Fine-grained error code from the upstream provider, when available. For `errorType: "rate_limit"`, this is one of the `RateLimitErrorCode` values (e.g., `"user_weekly_rate_limited"`, `"user_global_rate_limited"`, `"rate_limited"`, `"user_model_rate_limited"`, `"integration_rate_limited"`). For `errorType: "quota"`, this is the CAPI quota error code (e.g., `"quota_exceeded"`, `"session_quota_exceeded"`, `"billing_not_configured"`).
      */
     errorCode?: string;
     /**
@@ -388,12 +614,18 @@ export interface ErrorData {
      */
     url?: string;
 }
+/**
+ * Session event "session.idle". Payload indicating the session is idle with no background agents in flight
+ */
 export interface IdleEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: IdleData;
+    /**
+     * 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
@@ -407,6 +639,9 @@ export interface IdleEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.idle".
+     */
     type: "session.idle";
 }
 /**
@@ -418,12 +653,18 @@ export interface IdleData {
      */
     aborted?: boolean;
 }
+/**
+ * Session event "session.title_changed". Session title change payload containing the new display title
+ */
 export interface TitleChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: TitleChangedData;
+    /**
+     * 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
@@ -437,6 +678,9 @@ export interface TitleChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.title_changed".
+     */
     type: "session.title_changed";
 }
 /**
@@ -448,6 +692,9 @@ export interface TitleChangedData {
      */
     title: string;
 }
+/**
+ * Session event "session.schedule_created". Scheduled prompt registered via /every or /after
+ */
 export interface ScheduleCreatedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -470,12 +717,19 @@ export interface ScheduleCreatedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.schedule_created".
+     */
     type: "session.schedule_created";
 }
 /**
- * Scheduled prompt registered via /every
+ * Scheduled prompt registered via /every or /after
  */
 export interface ScheduleCreatedData {
+    /**
+     * Optional user-facing label shown in the timeline instead of the actual prompt (e.g. `/skill-name args` when the prompt is a skill invocation expansion)
+     */
+    displayPrompt?: string;
     /**
      * Sequential id assigned to the scheduled prompt within the session
      */
@@ -488,7 +742,14 @@ export interface ScheduleCreatedData {
      * Prompt text that gets enqueued on every tick
      */
     prompt: string;
+    /**
+     * Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)
+     */
+    recurring?: boolean;
 }
+/**
+ * Session event "session.schedule_cancelled". Scheduled prompt cancelled from the schedule manager dialog
+ */
 export interface ScheduleCancelledEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -511,6 +772,9 @@ export interface ScheduleCancelledEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.schedule_cancelled".
+     */
     type: "session.schedule_cancelled";
 }
 /**
@@ -522,6 +786,9 @@ export interface ScheduleCancelledData {
      */
     id: number;
 }
+/**
+ * Session event "session.info". Informational message for timeline display with categorization
+ */
 export interface InfoEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -544,6 +811,9 @@ export interface InfoEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.info".
+     */
     type: "session.info";
 }
 /**
@@ -567,6 +837,9 @@ export interface InfoData {
      */
     url?: string;
 }
+/**
+ * Session event "session.warning". Warning message for timeline display with categorization
+ */
 export interface WarningEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -589,6 +862,9 @@ export interface WarningEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.warning".
+     */
     type: "session.warning";
 }
 /**
@@ -608,6 +884,9 @@ export interface WarningData {
      */
     warningType: string;
 }
+/**
+ * Session event "session.model_change". Model change details including previous and new model identifiers
+ */
 export interface ModelChangeEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -630,6 +909,9 @@ export interface ModelChangeEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.model_change".
+     */
     type: "session.model_change";
 }
 /**
@@ -652,11 +934,16 @@ export interface ModelChangeData {
      * Reasoning effort level before the model change, if applicable
      */
     previousReasoningEffort?: string;
+    previousReasoningSummary?: ReasoningSummary;
     /**
      * Reasoning effort level after the model change, if applicable
      */
-    reasoningEffort?: string;
+    reasoningEffort?: string | null;
+    reasoningSummary?: ReasoningSummary;
 }
+/**
+ * Session event "session.mode_changed". Agent mode change details including previous and new modes
+ */
 export interface ModeChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -679,21 +966,21 @@ export interface ModeChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.mode_changed".
+     */
     type: "session.mode_changed";
 }
 /**
  * Agent mode change details including previous and new modes
  */
 export interface ModeChangedData {
-    /**
-     * Agent mode after the change (e.g., "interactive", "plan", "autopilot")
-     */
-    newMode: string;
-    /**
-     * Agent mode before the change (e.g., "interactive", "plan", "autopilot")
-     */
-    previousMode: string;
+    newMode: SessionMode;
+    previousMode: SessionMode;
 }
+/**
+ * Session event "session.plan_changed". Plan file operation details indicating what changed
+ */
 export interface PlanChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -716,6 +1003,9 @@ export interface PlanChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.plan_changed".
+     */
     type: "session.plan_changed";
 }
 /**
@@ -724,6 +1014,9 @@ export interface PlanChangedEvent {
 export interface PlanChangedData {
     operation: PlanChangedOperation;
 }
+/**
+ * Session event "session.workspace_file_changed". Workspace file change details including path and operation type
+ */
 export interface WorkspaceFileChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -746,6 +1039,9 @@ export interface WorkspaceFileChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.workspace_file_changed".
+     */
     type: "session.workspace_file_changed";
 }
 /**
@@ -758,6 +1054,9 @@ export interface WorkspaceFileChangedData {
      */
     path: string;
 }
+/**
+ * Session event "session.handoff". Session handoff metadata including source, context, and repository information
+ */
 export interface HandoffEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -780,6 +1079,9 @@ export interface HandoffEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.handoff".
+     */
     type: "session.handoff";
 }
 /**
@@ -826,6 +1128,9 @@ export interface HandoffRepository {
      */
     owner: string;
 }
+/**
+ * Session event "session.truncation". Conversation truncation statistics including token counts and removed content metrics
+ */
 export interface TruncationEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -848,6 +1153,9 @@ export interface TruncationEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.truncation".
+     */
     type: "session.truncation";
 }
 /**
@@ -887,12 +1195,18 @@ export interface TruncationData {
      */
     tokensRemovedDuringTruncation: number;
 }
+/**
+ * Session event "session.snapshot_rewind". Session rewind details including target event and count of removed events
+ */
 export interface SnapshotRewindEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: SnapshotRewindData;
+    /**
+     * 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
@@ -906,6 +1220,9 @@ export interface SnapshotRewindEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.snapshot_rewind".
+     */
     type: "session.snapshot_rewind";
 }
 /**
@@ -921,6 +1238,9 @@ export interface SnapshotRewindData {
      */
     upToEventId: string;
 }
+/**
+ * Session event "session.shutdown". Session termination metrics including usage statistics, code changes, and shutdown reason
+ */
 export interface ShutdownEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -943,6 +1263,9 @@ export interface ShutdownEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.shutdown".
+     */
     type: "session.shutdown";
 }
 /**
@@ -970,7 +1293,7 @@ export interface ShutdownData {
      * Per-model usage breakdown, keyed by model identifier
      */
     modelMetrics: {
-        [k: string]: ShutdownModelMetric;
+        [k: string]: ShutdownModelMetric | undefined;
     };
     /**
      * Unix timestamp (milliseconds) when the session started
@@ -985,7 +1308,7 @@ export interface ShutdownData {
      * Session-wide per-token-type accumulated token counts
      */
     tokenDetails?: {
-        [k: string]: ShutdownTokenDetail;
+        [k: string]: ShutdownTokenDetail | undefined;
     };
     /**
      * Tool definitions token count at shutdown
@@ -1021,13 +1344,16 @@ export interface ShutdownCodeChanges {
      */
     linesRemoved: number;
 }
+/**
+ * Schema for the `ShutdownModelMetric` type.
+ */
 export interface ShutdownModelMetric {
     requests: ShutdownModelMetricRequests;
     /**
      * Token count details per type
      */
     tokenDetails?: {
-        [k: string]: ShutdownModelMetricTokenDetail;
+        [k: string]: ShutdownModelMetricTokenDetail | undefined;
     };
     /**
      * Accumulated nano-AI units cost for this model
@@ -1048,6 +1374,9 @@ export interface ShutdownModelMetricRequests {
      */
     count: number;
 }
+/**
+ * Schema for the `ShutdownModelMetricTokenDetail` type.
+ */
 export interface ShutdownModelMetricTokenDetail {
     /**
      * Accumulated token count for this token type
@@ -1079,12 +1408,18 @@ export interface ShutdownModelMetricUsage {
      */
     reasoningTokens?: number;
 }
+/**
+ * Schema for the `ShutdownTokenDetail` type.
+ */
 export interface ShutdownTokenDetail {
     /**
      * Accumulated token count for this token type
      */
     tokenCount: number;
 }
+/**
+ * Session event "session.context_changed". Updated working directory and git context after the change
+ */
 export interface ContextChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1107,14 +1442,23 @@ export interface ContextChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.context_changed".
+     */
     type: "session.context_changed";
 }
+/**
+ * Session event "session.usage_info". Current context window usage statistics including token and message counts
+ */
 export interface UsageInfoEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: UsageInfoData;
+    /**
+     * 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
@@ -1128,6 +1472,9 @@ export interface UsageInfoEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.usage_info".
+     */
     type: "session.usage_info";
 }
 /**
@@ -1163,6 +1510,9 @@ export interface UsageInfoData {
      */
     toolDefinitionsTokens?: number;
 }
+/**
+ * Session event "session.compaction_start". Context window breakdown at the start of LLM-powered conversation compaction
+ */
 export interface CompactionStartEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1185,6 +1535,9 @@ export interface CompactionStartEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.compaction_start".
+     */
     type: "session.compaction_start";
 }
 /**
@@ -1204,6 +1557,9 @@ export interface CompactionStartData {
      */
     toolDefinitionsTokens?: number;
 }
+/**
+ * Session event "session.compaction_complete". Conversation compaction results including success status, metrics, and optional error details
+ */
 export interface CompactionCompleteEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1226,6 +1582,9 @@ export interface CompactionCompleteEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.compaction_complete".
+     */
     type: "session.compaction_complete";
 }
 /**
@@ -1354,6 +1713,9 @@ export interface CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail {
      */
     tokenType: string;
 }
+/**
+ * Session event "session.task_complete". Task completion notification with summary from the agent
+ */
 export interface TaskCompleteEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1376,6 +1738,9 @@ export interface TaskCompleteEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.task_complete".
+     */
     type: "session.task_complete";
 }
 /**
@@ -1391,6 +1756,9 @@ export interface TaskCompleteData {
      */
     summary?: string;
 }
+/**
+ * Session event "user.message".
+ */
 export interface UserMessageEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1413,8 +1781,14 @@ export interface UserMessageEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "user.message".
+     */
     type: "user.message";
 }
+/**
+ * Schema for the `UserMessageData` type.
+ */
 export interface UserMessageData {
     agentMode?: UserMessageAgentMode;
     /**
@@ -1430,7 +1804,11 @@ export interface UserMessageData {
      */
     interactionId?: string;
     /**
-     * Path-backed native document attachments that stayed on the tagged_files path flow because native upload would exceed the request size limit
+     * 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;
+    /**
+     * 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
      */
     nativeDocumentPathFallbackPaths?: string[];
     /**
@@ -1600,12 +1978,18 @@ export interface UserMessageAttachmentBlob {
      */
     type: "blob";
 }
+/**
+ * Session event "pending_messages.modified". Empty payload; the event signals that the pending message queue has changed
+ */
 export interface PendingMessagesModifiedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: PendingMessagesModifiedData;
+    /**
+     * 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
@@ -1619,6 +2003,9 @@ export interface PendingMessagesModifiedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "pending_messages.modified".
+     */
     type: "pending_messages.modified";
 }
 /**
@@ -1626,6 +2013,9 @@ export interface PendingMessagesModifiedEvent {
  */
 export interface PendingMessagesModifiedData {
 }
+/**
+ * Session event "assistant.turn_start". Turn initialization metadata including identifier and interaction tracking
+ */
 export interface AssistantTurnStartEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1648,6 +2038,9 @@ export interface AssistantTurnStartEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.turn_start".
+     */
     type: "assistant.turn_start";
 }
 /**
@@ -1663,12 +2056,18 @@ export interface AssistantTurnStartData {
      */
     turnId: string;
 }
+/**
+ * Session event "assistant.intent". Agent intent description for current activity or plan
+ */
 export interface AssistantIntentEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AssistantIntentData;
+    /**
+     * 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
@@ -1682,6 +2081,9 @@ export interface AssistantIntentEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.intent".
+     */
     type: "assistant.intent";
 }
 /**
@@ -1693,6 +2095,9 @@ export interface AssistantIntentData {
      */
     intent: string;
 }
+/**
+ * Session event "assistant.reasoning". Assistant reasoning content for timeline display with complete thinking text
+ */
 export interface AssistantReasoningEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1715,6 +2120,9 @@ export interface AssistantReasoningEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.reasoning".
+     */
     type: "assistant.reasoning";
 }
 /**
@@ -1730,12 +2138,18 @@ export interface AssistantReasoningData {
      */
     reasoningId: string;
 }
+/**
+ * Session event "assistant.reasoning_delta". Streaming reasoning delta for incremental extended thinking updates
+ */
 export interface AssistantReasoningDeltaEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AssistantReasoningDeltaData;
+    /**
+     * 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
@@ -1749,6 +2163,9 @@ export interface AssistantReasoningDeltaEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.reasoning_delta".
+     */
     type: "assistant.reasoning_delta";
 }
 /**
@@ -1764,12 +2181,18 @@ export interface AssistantReasoningDeltaData {
      */
     reasoningId: string;
 }
+/**
+ * Session event "assistant.streaming_delta". Streaming response progress with cumulative byte count
+ */
 export interface AssistantStreamingDeltaEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AssistantStreamingDeltaData;
+    /**
+     * 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
@@ -1783,6 +2206,9 @@ export interface AssistantStreamingDeltaEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.streaming_delta".
+     */
     type: "assistant.streaming_delta";
 }
 /**
@@ -1794,6 +2220,9 @@ export interface AssistantStreamingDeltaData {
      */
     totalResponseSizeBytes: number;
 }
+/**
+ * Session event "assistant.message". Assistant response containing text content, optional tool requests, and interaction metadata
+ */
 export interface AssistantMessageEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -1816,12 +2245,23 @@ export interface AssistantMessageEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.message".
+     */
     type: "assistant.message";
 }
 /**
  * Assistant response containing text content, optional tool requests, and interaction metadata
  */
 export interface AssistantMessageData {
+    /**
+     * Raw Anthropic content array with advisor blocks (server_tool_use, advisor_tool_result) for verbatim round-tripping
+     */
+    anthropicAdvisorBlocks?: unknown[];
+    /**
+     * Anthropic advisor model ID used for this response, for timeline display on replay
+     */
+    anthropicAdvisorModel?: string;
     /**
      * The assistant's text response content
      */
@@ -1838,6 +2278,10 @@ export interface AssistantMessageData {
      * Unique identifier for this assistant message
      */
     messageId: string;
+    /**
+     * Model that produced this assistant message, if known
+     */
+    model?: string;
     /**
      * Actual output token count from the API response (completion_tokens), used for accurate token accounting
      */
@@ -1880,7 +2324,7 @@ export interface AssistantMessageToolRequest {
      * Arguments to pass to the tool, format depends on the tool
      */
     arguments?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Resolved intention summary describing what this specific call does
@@ -1908,12 +2352,18 @@ export interface AssistantMessageToolRequest {
     toolTitle?: string;
     type?: AssistantMessageToolRequestType;
 }
+/**
+ * Session event "assistant.message_start". Streaming assistant message start metadata
+ */
 export interface AssistantMessageStartEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AssistantMessageStartData;
+    /**
+     * 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
@@ -1927,6 +2377,9 @@ export interface AssistantMessageStartEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.message_start".
+     */
     type: "assistant.message_start";
 }
 /**
@@ -1942,12 +2395,18 @@ export interface AssistantMessageStartData {
      */
     phase?: string;
 }
+/**
+ * Session event "assistant.message_delta". Streaming assistant message delta for incremental response updates
+ */
 export interface AssistantMessageDeltaEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AssistantMessageDeltaData;
+    /**
+     * 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
@@ -1961,6 +2420,9 @@ export interface AssistantMessageDeltaEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.message_delta".
+     */
     type: "assistant.message_delta";
 }
 /**
@@ -1981,6 +2443,9 @@ export interface AssistantMessageDeltaData {
      */
     parentToolCallId?: string;
 }
+/**
+ * Session event "assistant.turn_end". Turn completion metadata including the turn identifier
+ */
 export interface AssistantTurnEndEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2003,6 +2468,9 @@ export interface AssistantTurnEndEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.turn_end".
+     */
     type: "assistant.turn_end";
 }
 /**
@@ -2014,12 +2482,18 @@ export interface AssistantTurnEndData {
      */
     turnId: string;
 }
+/**
+ * Session event "assistant.usage". LLM API call usage metrics including tokens, costs, quotas, and billing information
+ */
 export interface AssistantUsageEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AssistantUsageData;
+    /**
+     * 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
@@ -2033,6 +2507,9 @@ export interface AssistantUsageEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.usage".
+     */
     type: "assistant.usage";
 }
 /**
@@ -2043,6 +2520,7 @@ export interface AssistantUsageData {
      * Completion ID from the model provider (e.g., chatcmpl-abc123)
      */
     apiCallId?: string;
+    apiEndpoint?: AssistantUsageApiEndpoint;
     /**
      * Number of tokens read from prompt cache
      */
@@ -2093,10 +2571,10 @@ export interface AssistantUsageData {
      * Per-quota resource usage snapshots, keyed by quota identifier
      */
     quotaSnapshots?: {
-        [k: string]: AssistantUsageQuotaSnapshot;
+        [k: string]: AssistantUsageQuotaSnapshot | undefined;
     };
     /**
-     * Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh")
+     * Reasoning effort level used for model calls, if applicable (e.g. "none", "low", "medium", "high", "xhigh", "max")
      */
     reasoningEffort?: string;
     /**
@@ -2106,7 +2584,7 @@ export interface AssistantUsageData {
     /**
      * Time to first token in milliseconds. Only available for streaming requests
      */
-    ttftMs?: number;
+    timeToFirstTokenMs?: number;
 }
 /**
  * Per-request cost and usage data from the CAPI copilot_usage response field
@@ -2142,6 +2620,9 @@ export interface AssistantUsageCopilotUsageTokenDetail {
      */
     tokenType: string;
 }
+/**
+ * Schema for the `AssistantUsageQuotaSnapshot` type.
+ */
 export interface AssistantUsageQuotaSnapshot {
     /**
      * Total requests allowed by the entitlement
@@ -2160,7 +2641,7 @@ export interface AssistantUsageQuotaSnapshot {
      */
     overageAllowedWithExhaustedQuota: boolean;
     /**
-     * Percentage of quota remaining (0.0 to 1.0)
+     * Percentage of quota remaining (0 to 100)
      */
     remainingPercentage: number;
     /**
@@ -2176,12 +2657,18 @@ export interface AssistantUsageQuotaSnapshot {
      */
     usedRequests: number;
 }
+/**
+ * Session event "model.call_failure". Failed LLM API call metadata for telemetry
+ */
 export interface ModelCallFailureEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ModelCallFailureData;
+    /**
+     * 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
@@ -2195,6 +2682,9 @@ export interface ModelCallFailureEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "model.call_failure".
+     */
     type: "model.call_failure";
 }
 /**
@@ -2231,6 +2721,9 @@ export interface ModelCallFailureData {
      */
     statusCode?: number;
 }
+/**
+ * Session event "abort". Turn abort information including the reason for termination
+ */
 export interface AbortEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2253,6 +2746,9 @@ export interface AbortEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "abort".
+     */
     type: "abort";
 }
 /**
@@ -2261,6 +2757,9 @@ export interface AbortEvent {
 export interface AbortData {
     reason: AbortReason;
 }
+/**
+ * Session event "tool.user_requested". User-initiated tool invocation request with tool name and arguments
+ */
 export interface ToolUserRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2283,6 +2782,9 @@ export interface ToolUserRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "tool.user_requested".
+     */
     type: "tool.user_requested";
 }
 /**
@@ -2293,7 +2795,7 @@ export interface ToolUserRequestedData {
      * Arguments for the tool invocation
      */
     arguments?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Unique identifier for this tool call
@@ -2304,6 +2806,9 @@ export interface ToolUserRequestedData {
      */
     toolName: string;
 }
+/**
+ * Session event "tool.execution_start". Tool execution startup details including MCP server information when applicable
+ */
 export interface ToolExecutionStartEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2326,6 +2831,9 @@ export interface ToolExecutionStartEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "tool.execution_start".
+     */
     type: "tool.execution_start";
 }
 /**
@@ -2336,7 +2844,7 @@ export interface ToolExecutionStartData {
      * Arguments passed to the tool
      */
     arguments?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Name of the MCP server hosting this tool, when the tool is an MCP tool
@@ -2364,12 +2872,18 @@ export interface ToolExecutionStartData {
      */
     turnId?: string;
 }
+/**
+ * Session event "tool.execution_partial_result". Streaming tool execution output for incremental result display
+ */
 export interface ToolExecutionPartialResultEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ToolExecutionPartialData;
+    /**
+     * 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
@@ -2383,6 +2897,9 @@ export interface ToolExecutionPartialResultEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "tool.execution_partial_result".
+     */
     type: "tool.execution_partial_result";
 }
 /**
@@ -2398,12 +2915,18 @@ export interface ToolExecutionPartialData {
      */
     toolCallId: string;
 }
+/**
+ * Session event "tool.execution_progress". Tool execution progress notification with status message
+ */
 export interface ToolExecutionProgressEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ToolExecutionProgressData;
+    /**
+     * 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
@@ -2417,6 +2940,9 @@ export interface ToolExecutionProgressEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "tool.execution_progress".
+     */
     type: "tool.execution_progress";
 }
 /**
@@ -2432,6 +2958,9 @@ export interface ToolExecutionProgressData {
      */
     toolCallId: string;
 }
+/**
+ * Session event "tool.execution_complete". Tool execution completion results including success status, detailed output, and error information
+ */
 export interface ToolExecutionCompleteEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2454,6 +2983,9 @@ export interface ToolExecutionCompleteEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "tool.execution_complete".
+     */
     type: "tool.execution_complete";
 }
 /**
@@ -2491,7 +3023,7 @@ export interface ToolExecutionCompleteData {
      * Tool-specific telemetry data (e.g., CodeQL check counts, grep match counts)
      */
     toolTelemetry?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Identifier for the agent loop turn this tool was invoked in, matching the corresponding assistant.turn_start event
@@ -2661,6 +3193,9 @@ export interface ToolExecutionCompleteContentResource {
      */
     type: "resource";
 }
+/**
+ * Schema for the `EmbeddedTextResourceContents` type.
+ */
 export interface EmbeddedTextResourceContents {
     /**
      * MIME type of the text content
@@ -2675,6 +3210,9 @@ export interface EmbeddedTextResourceContents {
      */
     uri: string;
 }
+/**
+ * Schema for the `EmbeddedBlobResourceContents` type.
+ */
 export interface EmbeddedBlobResourceContents {
     /**
      * Base64-encoded binary content of the resource
@@ -2689,6 +3227,9 @@ export interface EmbeddedBlobResourceContents {
      */
     uri: string;
 }
+/**
+ * Session event "skill.invoked". Skill invocation details including content, allowed tools, and plugin metadata
+ */
 export interface SkillInvokedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2711,6 +3252,9 @@ export interface SkillInvokedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "skill.invoked".
+     */
     type: "skill.invoked";
 }
 /**
@@ -2746,6 +3290,9 @@ export interface SkillInvokedData {
      */
     pluginVersion?: string;
 }
+/**
+ * Session event "subagent.started". Sub-agent startup details including parent tool call and agent information
+ */
 export interface SubagentStartedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2768,6 +3315,9 @@ export interface SubagentStartedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "subagent.started".
+     */
     type: "subagent.started";
 }
 /**
@@ -2795,6 +3345,9 @@ export interface SubagentStartedData {
      */
     toolCallId: string;
 }
+/**
+ * Session event "subagent.completed". Sub-agent completion details for successful execution
+ */
 export interface SubagentCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2817,6 +3370,9 @@ export interface SubagentCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "subagent.completed".
+     */
     type: "subagent.completed";
 }
 /**
@@ -2852,6 +3408,9 @@ export interface SubagentCompletedData {
      */
     totalToolCalls?: number;
 }
+/**
+ * Session event "subagent.failed". Sub-agent failure details including error message and agent information
+ */
 export interface SubagentFailedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2874,6 +3433,9 @@ export interface SubagentFailedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "subagent.failed".
+     */
     type: "subagent.failed";
 }
 /**
@@ -2913,6 +3475,9 @@ export interface SubagentFailedData {
      */
     totalToolCalls?: number;
 }
+/**
+ * Session event "subagent.selected". Custom agent selection details including name and available tools
+ */
 export interface SubagentSelectedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2935,6 +3500,9 @@ export interface SubagentSelectedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "subagent.selected".
+     */
     type: "subagent.selected";
 }
 /**
@@ -2954,6 +3522,9 @@ export interface SubagentSelectedData {
      */
     tools: string[] | null;
 }
+/**
+ * Session event "subagent.deselected". Empty payload; the event signals that the custom agent was deselected, returning to the default agent
+ */
 export interface SubagentDeselectedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -2976,6 +3547,9 @@ export interface SubagentDeselectedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "subagent.deselected".
+     */
     type: "subagent.deselected";
 }
 /**
@@ -2983,6 +3557,9 @@ export interface SubagentDeselectedEvent {
  */
 export interface SubagentDeselectedData {
 }
+/**
+ * Session event "hook.start". Hook invocation start details including type and input data
+ */
 export interface HookStartEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -3005,6 +3582,9 @@ export interface HookStartEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "hook.start".
+     */
     type: "hook.start";
 }
 /**
@@ -3023,9 +3603,12 @@ export interface HookStartData {
      * Input data passed to the hook
      */
     input?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
 }
+/**
+ * Session event "hook.end". Hook invocation completion details including output, success status, and error information
+ */
 export interface HookEndEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -3048,6 +3631,9 @@ export interface HookEndEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "hook.end".
+     */
     type: "hook.end";
 }
 /**
@@ -3067,7 +3653,7 @@ export interface HookEndData {
      * Output data produced by the hook
      */
     output?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Whether the hook completed successfully
@@ -3087,6 +3673,9 @@ export interface HookEndError {
      */
     stack?: string;
 }
+/**
+ * Session event "system.message". System/developer instruction content with role and optional template metadata
+ */
 export interface SystemMessageEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -3109,6 +3698,9 @@ export interface SystemMessageEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "system.message".
+     */
     type: "system.message";
 }
 /**
@@ -3138,9 +3730,12 @@ export interface SystemMessageMetadata {
      * Template variables used when constructing the prompt
      */
     variables?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
 }
+/**
+ * Session event "system.notification". System-generated notification for runtime events like background task completion
+ */
 export interface SystemNotificationEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -3163,6 +3758,9 @@ export interface SystemNotificationEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "system.notification".
+     */
     type: "system.notification";
 }
 /**
@@ -3175,6 +3773,9 @@ export interface SystemNotificationData {
     content: string;
     kind: SystemNotification;
 }
+/**
+ * Schema for the `SystemNotificationAgentCompleted` type.
+ */
 export interface SystemNotificationAgentCompleted {
     /**
      * Unique identifier of the background agent
@@ -3193,8 +3794,14 @@ export interface SystemNotificationAgentCompleted {
      */
     prompt?: string;
     status: SystemNotificationAgentCompletedStatus;
+    /**
+     * Type discriminator. Always "agent_completed".
+     */
     type: "agent_completed";
 }
+/**
+ * Schema for the `SystemNotificationAgentIdle` type.
+ */
 export interface SystemNotificationAgentIdle {
     /**
      * Unique identifier of the background agent
@@ -3208,8 +3815,14 @@ export interface SystemNotificationAgentIdle {
      * Human-readable description of the agent task
      */
     description?: string;
+    /**
+     * Type discriminator. Always "agent_idle".
+     */
     type: "agent_idle";
 }
+/**
+ * Schema for the `SystemNotificationNewInboxMessage` type.
+ */
 export interface SystemNotificationNewInboxMessage {
     /**
      * Unique identifier of the inbox entry
@@ -3227,8 +3840,14 @@ export interface SystemNotificationNewInboxMessage {
      * Short summary shown before the agent decides whether to read the inbox
      */
     summary: string;
+    /**
+     * Type discriminator. Always "new_inbox_message".
+     */
     type: "new_inbox_message";
 }
+/**
+ * Schema for the `SystemNotificationShellCompleted` type.
+ */
 export interface SystemNotificationShellCompleted {
     /**
      * Human-readable description of the command
@@ -3242,8 +3861,14 @@ export interface SystemNotificationShellCompleted {
      * Unique identifier of the shell session
      */
     shellId: string;
+    /**
+     * Type discriminator. Always "shell_completed".
+     */
     type: "shell_completed";
 }
+/**
+ * Schema for the `SystemNotificationShellDetachedCompleted` type.
+ */
 export interface SystemNotificationShellDetachedCompleted {
     /**
      * Human-readable description of the command
@@ -3253,8 +3878,14 @@ export interface SystemNotificationShellDetachedCompleted {
      * Unique identifier of the detached shell session
      */
     shellId: string;
+    /**
+     * Type discriminator. Always "shell_detached_completed".
+     */
     type: "shell_detached_completed";
 }
+/**
+ * Schema for the `SystemNotificationInstructionDiscovered` type.
+ */
 export interface SystemNotificationInstructionDiscovered {
     /**
      * Human-readable label for the timeline (e.g., 'AGENTS.md from packages/billing/')
@@ -3272,8 +3903,14 @@ export interface SystemNotificationInstructionDiscovered {
      * Tool command that triggered discovery (currently always 'view')
      */
     triggerTool: string;
+    /**
+     * Type discriminator. Always "instruction_discovered".
+     */
     type: "instruction_discovered";
 }
+/**
+ * Session event "permission.requested". Permission request notification requiring client approval with request details
+ */
 export interface PermissionRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -3296,6 +3933,9 @@ export interface PermissionRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "permission.requested".
+     */
     type: "permission.requested";
 }
 /**
@@ -3358,6 +3998,9 @@ export interface PermissionRequestShell {
      */
     warning?: string;
 }
+/**
+ * Schema for the `PermissionRequestShellCommand` type.
+ */
 export interface PermissionRequestShellCommand {
     /**
      * Command identifier (e.g., executable name)
@@ -3368,6 +4011,9 @@ export interface PermissionRequestShellCommand {
      */
     readOnly: boolean;
 }
+/**
+ * Schema for the `PermissionRequestShellPossibleUrl` type.
+ */
 export interface PermissionRequestShellPossibleUrl {
     /**
      * URL that may be accessed by the command
@@ -3436,7 +4082,7 @@ export interface PermissionRequestMcp {
      * Arguments to pass to the MCP tool
      */
     args?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Permission kind discriminator
@@ -3523,7 +4169,7 @@ export interface PermissionRequestCustomTool {
      * Arguments to pass to the custom tool
      */
     args?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Permission kind discriminator
@@ -3558,7 +4204,7 @@ export interface PermissionRequestHook {
      * Arguments of the tool call being gated
      */
     toolArgs?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Tool call ID that triggered this permission request
@@ -3569,6 +4215,48 @@ export interface PermissionRequestHook {
      */
     toolName: string;
 }
+/**
+ * Extension management permission request
+ */
+export interface PermissionRequestExtensionManagement {
+    /**
+     * Name of the extension being managed
+     */
+    extensionName?: string;
+    /**
+     * Permission kind discriminator
+     */
+    kind: "extension-management";
+    /**
+     * The extension management operation (scaffold, reload)
+     */
+    operation: string;
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
+/**
+ * Extension permission access request
+ */
+export interface PermissionRequestExtensionPermissionAccess {
+    /**
+     * Capabilities the extension is requesting
+     */
+    capabilities: string[];
+    /**
+     * Name of the extension requesting permission access
+     */
+    extensionName: string;
+    /**
+     * Permission kind discriminator
+     */
+    kind: "extension-permission-access";
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
 /**
  * Shell command permission prompt
  */
@@ -3707,12 +4395,12 @@ export interface PermissionPromptRequestUrl {
  * Memory operation permission prompt
  */
 export interface PermissionPromptRequestMemory {
-    action?: PermissionPromptRequestMemoryAction;
+    action?: PermissionRequestMemoryAction;
     /**
      * Source references for the stored fact (store only)
      */
     citations?: string;
-    direction?: PermissionPromptRequestMemoryDirection;
+    direction?: PermissionRequestMemoryDirection;
     /**
      * The fact being stored or voted on
      */
@@ -3742,7 +4430,7 @@ export interface PermissionPromptRequestCustomTool {
      * Arguments to pass to the custom tool
      */
     args?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Prompt kind discriminator
@@ -3795,7 +4483,7 @@ export interface PermissionPromptRequestHook {
      * Arguments of the tool call being gated
      */
     toolArgs?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Tool call ID that triggered this permission request
@@ -3806,6 +4494,51 @@ export interface PermissionPromptRequestHook {
      */
     toolName: string;
 }
+/**
+ * Extension management permission prompt
+ */
+export interface PermissionPromptRequestExtensionManagement {
+    /**
+     * Name of the extension being managed
+     */
+    extensionName?: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "extension-management";
+    /**
+     * The extension management operation (scaffold, reload)
+     */
+    operation: string;
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
+/**
+ * Extension permission access prompt
+ */
+export interface PermissionPromptRequestExtensionPermissionAccess {
+    /**
+     * Capabilities the extension is requesting
+     */
+    capabilities: string[];
+    /**
+     * Name of the extension requesting permission access
+     */
+    extensionName: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "extension-permission-access";
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
+/**
+ * Session event "permission.completed". Permission request completion notification signaling UI dismissal
+ */
 export interface PermissionCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -3828,6 +4561,9 @@ export interface PermissionCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "permission.completed".
+     */
     type: "permission.completed";
 }
 /**
@@ -3844,12 +4580,18 @@ export interface PermissionCompletedData {
      */
     toolCallId?: string;
 }
+/**
+ * Schema for the `PermissionApproved` type.
+ */
 export interface PermissionApproved {
     /**
      * The permission request was approved
      */
     kind: "approved";
 }
+/**
+ * Schema for the `PermissionApprovedForSession` type.
+ */
 export interface PermissionApprovedForSession {
     approval: UserToolSessionApproval;
     /**
@@ -3857,6 +4599,9 @@ export interface PermissionApprovedForSession {
      */
     kind: "approved-for-session";
 }
+/**
+ * Schema for the `UserToolSessionApprovalCommands` type.
+ */
 export interface UserToolSessionApprovalCommands {
     /**
      * Command identifiers approved by the user
@@ -3867,18 +4612,27 @@ export interface UserToolSessionApprovalCommands {
      */
     kind: "commands";
 }
+/**
+ * Schema for the `UserToolSessionApprovalRead` type.
+ */
 export interface UserToolSessionApprovalRead {
     /**
      * Read approval kind
      */
     kind: "read";
 }
+/**
+ * Schema for the `UserToolSessionApprovalWrite` type.
+ */
 export interface UserToolSessionApprovalWrite {
     /**
      * Write approval kind
      */
     kind: "write";
 }
+/**
+ * Schema for the `UserToolSessionApprovalMcp` type.
+ */
 export interface UserToolSessionApprovalMcp {
     /**
      * MCP tool approval kind
@@ -3893,12 +4647,18 @@ export interface UserToolSessionApprovalMcp {
      */
     toolName: string | null;
 }
+/**
+ * Schema for the `UserToolSessionApprovalMemory` type.
+ */
 export interface UserToolSessionApprovalMemory {
     /**
      * Memory approval kind
      */
     kind: "memory";
 }
+/**
+ * Schema for the `UserToolSessionApprovalCustomTool` type.
+ */
 export interface UserToolSessionApprovalCustomTool {
     /**
      * Custom tool approval kind
@@ -3909,6 +4669,35 @@ export interface UserToolSessionApprovalCustomTool {
      */
     toolName: string;
 }
+/**
+ * Schema for the `UserToolSessionApprovalExtensionManagement` type.
+ */
+export interface UserToolSessionApprovalExtensionManagement {
+    /**
+     * Extension management approval kind
+     */
+    kind: "extension-management";
+    /**
+     * Optional operation identifier
+     */
+    operation?: string;
+}
+/**
+ * Schema for the `UserToolSessionApprovalExtensionPermissionAccess` type.
+ */
+export interface UserToolSessionApprovalExtensionPermissionAccess {
+    /**
+     * Extension name
+     */
+    extensionName: string;
+    /**
+     * Extension permission access approval kind
+     */
+    kind: "extension-permission-access";
+}
+/**
+ * Schema for the `PermissionApprovedForLocation` type.
+ */
 export interface PermissionApprovedForLocation {
     approval: UserToolSessionApproval;
     /**
@@ -3920,6 +4709,9 @@ export interface PermissionApprovedForLocation {
      */
     locationKey: string;
 }
+/**
+ * Schema for the `PermissionCancelled` type.
+ */
 export interface PermissionCancelled {
     /**
      * The permission request was cancelled before a response was used
@@ -3930,6 +4722,9 @@ export interface PermissionCancelled {
      */
     reason?: string;
 }
+/**
+ * Schema for the `PermissionDeniedByRules` type.
+ */
 export interface PermissionDeniedByRules {
     /**
      * Denied because approval rules explicitly blocked it
@@ -3940,9 +4735,12 @@ export interface PermissionDeniedByRules {
      */
     rules: PermissionRule[];
 }
+/**
+ * Schema for the `PermissionRule` type.
+ */
 export interface PermissionRule {
     /**
-     * Optional rule argument matched against the request
+     * Argument value matched against the request, or null when the rule kind has no argument (e.g. 'read', 'write', 'memory').
      */
     argument: string | null;
     /**
@@ -3950,12 +4748,18 @@ export interface PermissionRule {
      */
     kind: string;
 }
+/**
+ * Schema for the `PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser` type.
+ */
 export interface PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser {
     /**
      * Denied because no approval rule matched and user confirmation was unavailable
      */
     kind: "denied-no-approval-rule-and-could-not-request-from-user";
 }
+/**
+ * Schema for the `PermissionDeniedInteractivelyByUser` type.
+ */
 export interface PermissionDeniedInteractivelyByUser {
     /**
      * Optional feedback from the user explaining the denial
@@ -3970,6 +4774,9 @@ export interface PermissionDeniedInteractivelyByUser {
      */
     kind: "denied-interactively-by-user";
 }
+/**
+ * Schema for the `PermissionDeniedByContentExclusionPolicy` type.
+ */
 export interface PermissionDeniedByContentExclusionPolicy {
     /**
      * Denied by the organization's content exclusion policy
@@ -3984,6 +4791,9 @@ export interface PermissionDeniedByContentExclusionPolicy {
      */
     path: string;
 }
+/**
+ * Schema for the `PermissionDeniedByPermissionRequestHook` type.
+ */
 export interface PermissionDeniedByPermissionRequestHook {
     /**
      * Whether to interrupt the current agent turn
@@ -3998,12 +4808,18 @@ export interface PermissionDeniedByPermissionRequestHook {
      */
     message?: string;
 }
+/**
+ * Session event "user_input.requested". User input request notification with question and optional predefined choices
+ */
 export interface UserInputRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: UserInputRequestedData;
+    /**
+     * 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
@@ -4017,6 +4833,9 @@ export interface UserInputRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "user_input.requested".
+     */
     type: "user_input.requested";
 }
 /**
@@ -4044,12 +4863,18 @@ export interface UserInputRequestedData {
      */
     toolCallId?: string;
 }
+/**
+ * Session event "user_input.completed". User input request completion with the user's response
+ */
 export interface UserInputCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: UserInputCompletedData;
+    /**
+     * 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
@@ -4063,6 +4888,9 @@ export interface UserInputCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "user_input.completed".
+     */
     type: "user_input.completed";
 }
 /**
@@ -4082,12 +4910,18 @@ export interface UserInputCompletedData {
      */
     wasFreeform?: boolean;
 }
+/**
+ * Session event "elicitation.requested". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)
+ */
 export interface ElicitationRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ElicitationRequestedData;
+    /**
+     * 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
@@ -4101,6 +4935,9 @@ export interface ElicitationRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "elicitation.requested".
+     */
     type: "elicitation.requested";
 }
 /**
@@ -4129,7 +4966,7 @@ export interface ElicitationRequestedData {
      * URL to open in the user's browser (url mode only)
      */
     url?: string;
-    [k: string]: unknown;
+    [k: string]: unknown | undefined;
 }
 /**
  * JSON Schema describing the form fields to present to the user (form mode only)
@@ -4139,7 +4976,7 @@ export interface ElicitationRequestedSchema {
      * Form field definitions, keyed by field name
      */
     properties: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * List of required field names
@@ -4150,12 +4987,18 @@ export interface ElicitationRequestedSchema {
      */
     type: "object";
 }
+/**
+ * Session event "elicitation.completed". Elicitation request completion with the user's response
+ */
 export interface ElicitationCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ElicitationCompletedData;
+    /**
+     * 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
@@ -4169,6 +5012,9 @@ export interface ElicitationCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "elicitation.completed".
+     */
     type: "elicitation.completed";
 }
 /**
@@ -4180,19 +5026,25 @@ export interface ElicitationCompletedData {
      * The submitted form data when action is 'accept'; keys match the requested schema fields
      */
     content?: {
-        [k: string]: ElicitationCompletedContent;
+        [k: string]: ElicitationCompletedContent | undefined;
     };
     /**
      * Request ID of the resolved elicitation request; clients should dismiss any UI for this request
      */
     requestId: string;
 }
+/**
+ * Session event "sampling.requested". Sampling request from an MCP server; contains the server name and a requestId for correlation
+ */
 export interface SamplingRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: SamplingRequestedData;
+    /**
+     * 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
@@ -4206,6 +5058,9 @@ export interface SamplingRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "sampling.requested".
+     */
     type: "sampling.requested";
 }
 /**
@@ -4224,14 +5079,20 @@ export interface SamplingRequestedData {
      * Name of the MCP server that initiated the sampling request
      */
     serverName: string;
-    [k: string]: unknown;
+    [k: string]: unknown | undefined;
 }
+/**
+ * Session event "sampling.completed". Sampling request completion notification signaling UI dismissal
+ */
 export interface SamplingCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: SamplingCompletedData;
+    /**
+     * 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
@@ -4245,6 +5106,9 @@ export interface SamplingCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "sampling.completed".
+     */
     type: "sampling.completed";
 }
 /**
@@ -4256,12 +5120,18 @@ export interface SamplingCompletedData {
      */
     requestId: string;
 }
+/**
+ * Session event "mcp.oauth_required". OAuth authentication request for an MCP server
+ */
 export interface McpOauthRequiredEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: McpOauthRequiredData;
+    /**
+     * 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
@@ -4275,6 +5145,9 @@ export interface McpOauthRequiredEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "mcp.oauth_required".
+     */
     type: "mcp.oauth_required";
 }
 /**
@@ -4312,12 +5185,18 @@ export interface McpOauthRequiredStaticClientConfig {
      */
     publicClient?: boolean;
 }
+/**
+ * Session event "mcp.oauth_completed". MCP OAuth request completion notification
+ */
 export interface McpOauthCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: McpOauthCompletedData;
+    /**
+     * 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
@@ -4331,6 +5210,9 @@ export interface McpOauthCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "mcp.oauth_completed".
+     */
     type: "mcp.oauth_completed";
 }
 /**
@@ -4342,6 +5224,64 @@ export interface McpOauthCompletedData {
      */
     requestId: string;
 }
+/**
+ * Session event "session.custom_notification". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.
+ */
+export interface CustomNotificationEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: CustomNotificationData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.custom_notification".
+     */
+    type: "session.custom_notification";
+}
+/**
+ * Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.
+ */
+export interface CustomNotificationData {
+    /**
+     * Source-defined custom notification name
+     */
+    name: string;
+    payload: CustomNotificationPayload;
+    /**
+     * Namespace for the custom notification producer
+     */
+    source: string;
+    subject?: CustomNotificationSubject;
+    /**
+     * Optional source-defined payload schema version
+     */
+    version?: number;
+}
+/**
+ * Optional source-defined string identifiers describing the payload subject
+ */
+export interface CustomNotificationSubject {
+    [k: string]: string | undefined;
+}
+/**
+ * Session event "external_tool.requested". External tool invocation request for client-side tool execution
+ */
 export interface ExternalToolRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -4364,6 +5304,9 @@ export interface ExternalToolRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "external_tool.requested".
+     */
     type: "external_tool.requested";
 }
 /**
@@ -4374,7 +5317,7 @@ export interface ExternalToolRequestedData {
      * Arguments to pass to the external tool
      */
     arguments?: {
-        [k: string]: unknown;
+        [k: string]: unknown | undefined;
     };
     /**
      * Unique identifier for this request; used to respond via session.respondToExternalTool()
@@ -4401,12 +5344,18 @@ export interface ExternalToolRequestedData {
      */
     tracestate?: string;
 }
+/**
+ * Session event "external_tool.completed". External tool completion notification signaling UI dismissal
+ */
 export interface ExternalToolCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ExternalToolCompletedData;
+    /**
+     * 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
@@ -4420,6 +5369,9 @@ export interface ExternalToolCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "external_tool.completed".
+     */
     type: "external_tool.completed";
 }
 /**
@@ -4431,12 +5383,18 @@ export interface ExternalToolCompletedData {
      */
     requestId: string;
 }
+/**
+ * Session event "command.queued". Queued slash command dispatch request for client execution
+ */
 export interface CommandQueuedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: CommandQueuedData;
+    /**
+     * 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
@@ -4450,6 +5408,9 @@ export interface CommandQueuedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "command.queued".
+     */
     type: "command.queued";
 }
 /**
@@ -4465,12 +5426,18 @@ export interface CommandQueuedData {
      */
     requestId: string;
 }
+/**
+ * Session event "command.execute". Registered command dispatch request routed to the owning client
+ */
 export interface CommandExecuteEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: CommandExecuteData;
+    /**
+     * 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
@@ -4484,6 +5451,9 @@ export interface CommandExecuteEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "command.execute".
+     */
     type: "command.execute";
 }
 /**
@@ -4507,12 +5477,18 @@ export interface CommandExecuteData {
      */
     requestId: string;
 }
+/**
+ * Session event "command.completed". Queued command completion notification signaling UI dismissal
+ */
 export interface CommandCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: CommandCompletedData;
+    /**
+     * 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
@@ -4526,6 +5502,9 @@ export interface CommandCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "command.completed".
+     */
     type: "command.completed";
 }
 /**
@@ -4537,12 +5516,18 @@ export interface CommandCompletedData {
      */
     requestId: string;
 }
+/**
+ * Session event "auto_mode_switch.requested". Auto mode switch request notification requiring user approval
+ */
 export interface AutoModeSwitchRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AutoModeSwitchRequestedData;
+    /**
+     * 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
@@ -4556,6 +5541,9 @@ export interface AutoModeSwitchRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "auto_mode_switch.requested".
+     */
     type: "auto_mode_switch.requested";
 }
 /**
@@ -4575,12 +5563,18 @@ export interface AutoModeSwitchRequestedData {
      */
     retryAfterSeconds?: number;
 }
+/**
+ * Session event "auto_mode_switch.completed". Auto mode switch completion notification
+ */
 export interface AutoModeSwitchCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: AutoModeSwitchCompletedData;
+    /**
+     * 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
@@ -4594,6 +5588,9 @@ export interface AutoModeSwitchCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "auto_mode_switch.completed".
+     */
     type: "auto_mode_switch.completed";
 }
 /**
@@ -4604,17 +5601,20 @@ export interface AutoModeSwitchCompletedData {
      * Request ID of the resolved request; clients should dismiss any UI for this request
      */
     requestId: string;
-    /**
-     * The user's choice: 'yes', 'yes_always', or 'no'
-     */
-    response: string;
+    response: AutoModeSwitchResponse;
 }
+/**
+ * Session event "commands.changed". SDK command registration change notification
+ */
 export interface CommandsChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: CommandsChangedData;
+    /**
+     * 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
@@ -4628,6 +5628,9 @@ export interface CommandsChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "commands.changed".
+     */
     type: "commands.changed";
 }
 /**
@@ -4639,16 +5642,31 @@ export interface CommandsChangedData {
      */
     commands: CommandsChangedCommand[];
 }
+/**
+ * Schema for the `CommandsChangedCommand` type.
+ */
 export interface CommandsChangedCommand {
+    /**
+     * Optional human-readable command description.
+     */
     description?: string;
+    /**
+     * Slash command name without the leading slash.
+     */
     name: string;
 }
+/**
+ * Session event "capabilities.changed". Session capability change notification
+ */
 export interface CapabilitiesChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: CapabilitiesChangedData;
+    /**
+     * 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
@@ -4662,6 +5680,9 @@ export interface CapabilitiesChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "capabilities.changed".
+     */
     type: "capabilities.changed";
 }
 /**
@@ -4679,12 +5700,18 @@ export interface CapabilitiesChangedUI {
      */
     elicitation?: boolean;
 }
+/**
+ * Session event "exit_plan_mode.requested". Plan approval request with plan content and available user actions
+ */
 export interface ExitPlanModeRequestedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ExitPlanModeRequestedData;
+    /**
+     * 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
@@ -4698,6 +5725,9 @@ export interface ExitPlanModeRequestedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "exit_plan_mode.requested".
+     */
     type: "exit_plan_mode.requested";
 }
 /**
@@ -4705,17 +5735,14 @@ export interface ExitPlanModeRequestedEvent {
  */
 export interface ExitPlanModeRequestedData {
     /**
-     * Available actions the user can take (e.g., approve, edit, reject)
+     * Available actions the user can take
      */
-    actions: string[];
+    actions: ExitPlanModeAction[];
     /**
      * Full content of the plan file
      */
     planContent: string;
-    /**
-     * The recommended action for the user to take
-     */
-    recommendedAction: string;
+    recommendedAction: ExitPlanModeAction;
     /**
      * Unique identifier for this request; used to respond via session.respondToExitPlanMode()
      */
@@ -4725,12 +5752,18 @@ export interface ExitPlanModeRequestedData {
      */
     summary: string;
 }
+/**
+ * Session event "exit_plan_mode.completed". Plan mode exit completion with the user's approval decision and optional feedback
+ */
 export interface ExitPlanModeCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ExitPlanModeCompletedData;
+    /**
+     * 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
@@ -4744,6 +5777,9 @@ export interface ExitPlanModeCompletedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "exit_plan_mode.completed".
+     */
     type: "exit_plan_mode.completed";
 }
 /**
@@ -4766,17 +5802,20 @@ export interface ExitPlanModeCompletedData {
      * Request ID of the resolved exit plan mode request; clients should dismiss any UI for this request
      */
     requestId: string;
-    /**
-     * Which action the user selected (e.g. 'autopilot', 'interactive', 'exit_only')
-     */
-    selectedAction?: string;
+    selectedAction?: ExitPlanModeAction;
 }
+/**
+ * Session event "session.tools_updated".
+ */
 export interface ToolsUpdatedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ToolsUpdatedData;
+    /**
+     * 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
@@ -4790,17 +5829,32 @@ export interface ToolsUpdatedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.tools_updated".
+     */
     type: "session.tools_updated";
 }
+/**
+ * Schema for the `ToolsUpdatedData` type.
+ */
 export interface ToolsUpdatedData {
+    /**
+     * Identifier of the model the resolved tools apply to.
+     */
     model: string;
 }
+/**
+ * Session event "session.background_tasks_changed".
+ */
 export interface BackgroundTasksChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: BackgroundTasksChangedData;
+    /**
+     * 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
@@ -4814,16 +5868,28 @@ export interface BackgroundTasksChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.background_tasks_changed".
+     */
     type: "session.background_tasks_changed";
 }
+/**
+ * Schema for the `BackgroundTasksChangedData` type.
+ */
 export interface BackgroundTasksChangedData {
 }
+/**
+ * Session event "session.skills_loaded".
+ */
 export interface SkillsLoadedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: SkillsLoadedData;
+    /**
+     * 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
@@ -4837,14 +5903,23 @@ export interface SkillsLoadedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.skills_loaded".
+     */
     type: "session.skills_loaded";
 }
+/**
+ * Schema for the `SkillsLoadedData` type.
+ */
 export interface SkillsLoadedData {
     /**
      * Array of resolved skill metadata
      */
     skills: SkillsLoadedSkill[];
 }
+/**
+ * Schema for the `SkillsLoadedSkill` type.
+ */
 export interface SkillsLoadedSkill {
     /**
      * Description of what the skill does
@@ -4862,21 +5937,24 @@ export interface SkillsLoadedSkill {
      * Absolute path to the skill file, if available
      */
     path?: string;
-    /**
-     * Source location type of the skill (e.g., project, personal, plugin)
-     */
-    source: string;
+    source: SkillSource;
     /**
      * Whether the skill can be invoked by the user as a slash command
      */
     userInvocable: boolean;
 }
+/**
+ * Session event "session.custom_agents_updated".
+ */
 export interface CustomAgentsUpdatedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: CustomAgentsUpdatedData;
+    /**
+     * 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
@@ -4890,8 +5968,14 @@ export interface CustomAgentsUpdatedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.custom_agents_updated".
+     */
     type: "session.custom_agents_updated";
 }
+/**
+ * Schema for the `CustomAgentsUpdatedData` type.
+ */
 export interface CustomAgentsUpdatedData {
     /**
      * Array of loaded custom agent metadata
@@ -4906,6 +5990,9 @@ export interface CustomAgentsUpdatedData {
      */
     warnings: string[];
 }
+/**
+ * Schema for the `CustomAgentsUpdatedAgent` type.
+ */
 export interface CustomAgentsUpdatedAgent {
     /**
      * Description of what the agent does
@@ -4940,12 +6027,18 @@ export interface CustomAgentsUpdatedAgent {
      */
     userInvocable: boolean;
 }
+/**
+ * Session event "session.mcp_servers_loaded".
+ */
 export interface McpServersLoadedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: McpServersLoadedData;
+    /**
+     * 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
@@ -4959,14 +6052,23 @@ export interface McpServersLoadedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.mcp_servers_loaded".
+     */
     type: "session.mcp_servers_loaded";
 }
+/**
+ * Schema for the `McpServersLoadedData` type.
+ */
 export interface McpServersLoadedData {
     /**
      * Array of MCP server status summaries
      */
     servers: McpServersLoadedServer[];
 }
+/**
+ * Schema for the `McpServersLoadedServer` type.
+ */
 export interface McpServersLoadedServer {
     /**
      * Error message if the server failed to connect
@@ -4976,18 +6078,21 @@ export interface McpServersLoadedServer {
      * Server name (config key)
      */
     name: string;
-    /**
-     * Configuration source: user, workspace, plugin, or builtin
-     */
-    source?: string;
-    status: McpServersLoadedServerStatus;
+    source?: McpServerSource;
+    status: McpServerStatus;
 }
+/**
+ * Session event "session.mcp_server_status_changed".
+ */
 export interface McpServerStatusChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: McpServerStatusChangedData;
+    /**
+     * 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
@@ -5001,21 +6106,33 @@ export interface McpServerStatusChangedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.mcp_server_status_changed".
+     */
     type: "session.mcp_server_status_changed";
 }
+/**
+ * Schema for the `McpServerStatusChangedData` type.
+ */
 export interface McpServerStatusChangedData {
     /**
      * Name of the MCP server whose status changed
      */
     serverName: string;
-    status: McpServerStatusChangedStatus;
+    status: McpServerStatus;
 }
+/**
+ * Session event "session.extensions_loaded".
+ */
 export interface ExtensionsLoadedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
      */
     agentId?: string;
     data: ExtensionsLoadedData;
+    /**
+     * 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
@@ -5029,14 +6146,23 @@ export interface ExtensionsLoadedEvent {
      * ISO 8601 timestamp when the event was created
      */
     timestamp: string;
+    /**
+     * Type discriminator. Always "session.extensions_loaded".
+     */
     type: "session.extensions_loaded";
 }
+/**
+ * Schema for the `ExtensionsLoadedData` type.
+ */
 export interface ExtensionsLoadedData {
     /**
      * Array of discovered extensions and their status
      */
     extensions: ExtensionsLoadedExtension[];
 }
+/**
+ * Schema for the `ExtensionsLoadedExtension` type.
+ */
 export interface ExtensionsLoadedExtension {
     /**
      * Source-qualified extension ID (e.g., 'project:my-ext', 'user:auth-helper')