@github/copilot-sdk 0.1.33-unstable.1 → 0.2.1-preview.0

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

@@ -20,6 +20,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.start";
+    /**
+     * Session initialization metadata including context and configuration
+     */
     data: {
         /**
          * Unique identifier for the session
@@ -45,6 +48,10 @@ export type SessionEvent = {
          * Model selected at session creation time, if any
          */
         selectedModel?: string;
+        /**
+         * Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh")
+         */
+        reasoningEffort?: string;
         /**
          * Working directory and git context at session start
          */
@@ -58,14 +65,29 @@ export type SessionEvent = {
              */
             gitRoot?: string;
             /**
-             * Repository identifier in "owner/name" format, derived from the git remote URL
+             * Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps)
              */
             repository?: string;
+            /**
+             * Hosting platform type of the repository (github or ado)
+             */
+            hostType?: "github" | "ado";
             /**
              * Current git branch name
              */
             branch?: string;
+            /**
+             * Head commit of current git branch at session start time
+             */
+            headCommit?: string;
+            /**
+             * Base commit of current git branch at session start time
+             */
+            baseCommit?: string;
         };
+        /**
+         * Whether the session was already in use by another client at start time
+         */
         alreadyInUse?: boolean;
     };
 } | {
@@ -86,6 +108,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.resume";
+    /**
+     * Session resume metadata including current context and event count
+     */
     data: {
         /**
          * ISO 8601 timestamp when the session was resumed
@@ -95,6 +120,14 @@ export type SessionEvent = {
          * Total number of persisted events in the session at the time of resume
          */
         eventCount: number;
+        /**
+         * Model currently selected at resume time
+         */
+        selectedModel?: string;
+        /**
+         * Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh")
+         */
+        reasoningEffort?: string;
         /**
          * Updated working directory and git context at resume time
          */
@@ -108,14 +141,29 @@ export type SessionEvent = {
              */
             gitRoot?: string;
             /**
-             * Repository identifier in "owner/name" format, derived from the git remote URL
+             * Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps)
              */
             repository?: string;
+            /**
+             * Hosting platform type of the repository (github or ado)
+             */
+            hostType?: "github" | "ado";
             /**
              * Current git branch name
              */
             branch?: string;
+            /**
+             * Head commit of current git branch at session start time
+             */
+            headCommit?: string;
+            /**
+             * Base commit of current git branch at session start time
+             */
+            baseCommit?: string;
         };
+        /**
+         * Whether the session was already in use by another client at resume time
+         */
         alreadyInUse?: boolean;
     };
 } | {
@@ -136,6 +184,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.error";
+    /**
+     * Error details for timeline display including message and optional diagnostic information
+     */
     data: {
         /**
          * Category of error (e.g., "authentication", "authorization", "quota", "rate_limit", "query")
@@ -157,6 +208,10 @@ export type SessionEvent = {
          * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs
          */
         providerCallId?: string;
+        /**
+         * Optional URL associated with this error that the user can open in a browser
+         */
+        url?: string;
     };
 } | {
     /**
@@ -228,6 +283,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "session.title_changed";
+    /**
+     * Session title change payload containing the new display title
+     */
     data: {
         /**
          * The new display title for the session
@@ -252,6 +310,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.info";
+    /**
+     * Informational message for timeline display with categorization
+     */
     data: {
         /**
          * Category of informational message (e.g., "notification", "timing", "context_window", "mcp", "snapshot", "configuration", "authentication", "model")
@@ -261,6 +322,10 @@ export type SessionEvent = {
          * Human-readable informational message for display in the timeline
          */
         message: string;
+        /**
+         * Optional URL associated with this message that the user can open in a browser
+         */
+        url?: string;
     };
 } | {
     /**
@@ -280,6 +345,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.warning";
+    /**
+     * Warning message for timeline display with categorization
+     */
     data: {
         /**
          * Category of warning (e.g., "subscription", "policy", "mcp")
@@ -289,6 +357,10 @@ export type SessionEvent = {
          * Human-readable warning message for display in the timeline
          */
         message: string;
+        /**
+         * Optional URL associated with this warning that the user can open in a browser
+         */
+        url?: string;
     };
 } | {
     /**
@@ -308,6 +380,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.model_change";
+    /**
+     * Model change details including previous and new model identifiers
+     */
     data: {
         /**
          * Model that was previously selected, if any
@@ -317,6 +392,14 @@ export type SessionEvent = {
          * Newly selected model identifier
          */
         newModel: string;
+        /**
+         * Reasoning effort level before the model change, if applicable
+         */
+        previousReasoningEffort?: string;
+        /**
+         * Reasoning effort level after the model change, if applicable
+         */
+        reasoningEffort?: string;
     };
 } | {
     /**
@@ -336,6 +419,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.mode_changed";
+    /**
+     * Agent mode change details including previous and new modes
+     */
     data: {
         /**
          * Agent mode before the change (e.g., "interactive", "plan", "autopilot")
@@ -364,6 +450,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.plan_changed";
+    /**
+     * Plan file operation details indicating what changed
+     */
     data: {
         /**
          * The type of operation performed on the plan file
@@ -388,6 +477,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.workspace_file_changed";
+    /**
+     * Workspace file change details including path and operation type
+     */
     data: {
         /**
          * Relative path within the session workspace files directory
@@ -416,6 +508,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.handoff";
+    /**
+     * Session handoff metadata including source, context, and repository information
+     */
     data: {
         /**
          * ISO 8601 timestamp when the handoff occurred
@@ -454,6 +549,10 @@ export type SessionEvent = {
          * Session ID of the remote session being handed off
          */
         remoteSessionId?: string;
+        /**
+         * GitHub host URL for the source session (e.g., https://github.com or https://tenant.ghe.com)
+         */
+        host?: string;
     };
 } | {
     /**
@@ -473,6 +572,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.truncation";
+    /**
+     * Conversation truncation statistics including token counts and removed content metrics
+     */
     data: {
         /**
          * Maximum token count for the model's context window
@@ -522,6 +624,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "session.snapshot_rewind";
+    /**
+     * Session rewind details including target event and count of removed events
+     */
     data: {
         /**
          * Event ID that was rewound to; all events after this one were removed
@@ -550,6 +655,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.shutdown";
+    /**
+     * Session termination metrics including usage statistics, code changes, and shutdown reason
+     */
     data: {
         /**
          * Whether the session ended normally ("routine") or due to a crash/fatal error ("error")
@@ -633,6 +741,22 @@ export type SessionEvent = {
          * Model that was selected at the time of shutdown
          */
         currentModel?: string;
+        /**
+         * Total tokens in context window at shutdown
+         */
+        currentTokens?: number;
+        /**
+         * System message token count at shutdown
+         */
+        systemTokens?: number;
+        /**
+         * Non-system message token count at shutdown
+         */
+        conversationTokens?: number;
+        /**
+         * Tool definitions token count at shutdown
+         */
+        toolDefinitionsTokens?: number;
     };
 } | {
     /**
@@ -652,6 +776,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.context_changed";
+    /**
+     * Updated working directory and git context after the change
+     */
     data: {
         /**
          * Current working directory path
@@ -662,13 +789,25 @@ export type SessionEvent = {
          */
         gitRoot?: string;
         /**
-         * Repository identifier in "owner/name" format, derived from the git remote URL
+         * Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps)
          */
         repository?: string;
+        /**
+         * Hosting platform type of the repository (github or ado)
+         */
+        hostType?: "github" | "ado";
         /**
          * Current git branch name
          */
         branch?: string;
+        /**
+         * Head commit of current git branch at session start time
+         */
+        headCommit?: string;
+        /**
+         * Base commit of current git branch at session start time
+         */
+        baseCommit?: string;
     };
 } | {
     /**
@@ -685,6 +824,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "session.usage_info";
+    /**
+     * Current context window usage statistics including token and message counts
+     */
     data: {
         /**
          * Maximum token count for the model's context window
@@ -698,6 +840,22 @@ export type SessionEvent = {
          * Current number of messages in the conversation
          */
         messagesLength: number;
+        /**
+         * Token count from system message(s)
+         */
+        systemTokens?: number;
+        /**
+         * Token count from non-system messages (user, assistant, tool)
+         */
+        conversationTokens?: number;
+        /**
+         * Token count from tool definitions
+         */
+        toolDefinitionsTokens?: number;
+        /**
+         * Whether this is the first usage_info event emitted in this session
+         */
+        isInitial?: boolean;
     };
 } | {
     /**
@@ -718,9 +876,22 @@ export type SessionEvent = {
     ephemeral?: boolean;
     type: "session.compaction_start";
     /**
-     * Empty payload; the event signals that LLM-powered conversation compaction has begun
+     * Context window breakdown at the start of LLM-powered conversation compaction
      */
-    data: {};
+    data: {
+        /**
+         * Token count from system message(s) at compaction start
+         */
+        systemTokens?: number;
+        /**
+         * Token count from non-system messages (user, assistant, tool) at compaction start
+         */
+        conversationTokens?: number;
+        /**
+         * Token count from tool definitions at compaction start
+         */
+        toolDefinitionsTokens?: number;
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -739,6 +910,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.compaction_complete";
+    /**
+     * Conversation compaction results including success status, metrics, and optional error details
+     */
     data: {
         /**
          * Whether compaction completed successfully
@@ -801,6 +975,18 @@ export type SessionEvent = {
          * GitHub request tracing ID (x-github-request-id header) for the compaction LLM call
          */
         requestId?: string;
+        /**
+         * Token count from system message(s) after compaction
+         */
+        systemTokens?: number;
+        /**
+         * Token count from non-system messages (user, assistant, tool) after compaction
+         */
+        conversationTokens?: number;
+        /**
+         * Token count from tool definitions after compaction
+         */
+        toolDefinitionsTokens?: number;
     };
 } | {
     /**
@@ -820,11 +1006,18 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "session.task_complete";
+    /**
+     * Task completion notification with summary from the agent
+     */
     data: {
         /**
-         * Optional summary of the completed task, provided by the agent
+         * Summary of the completed task, provided by the agent
          */
         summary?: string;
+        /**
+         * Whether the tool call succeeded. False when validation failed (e.g., invalid arguments)
+         */
+        success?: boolean;
     };
 } | {
     /**
@@ -857,9 +1050,12 @@ export type SessionEvent = {
          * Files, selections, or GitHub references attached to the message
          */
         attachments?: ({
+            /**
+             * Attachment type discriminator
+             */
             type: "file";
             /**
-             * Absolute file or directory path
+             * Absolute file path
              */
             path: string;
             /**
@@ -880,28 +1076,18 @@ export type SessionEvent = {
                 end: number;
             };
         } | {
+            /**
+             * Attachment type discriminator
+             */
             type: "directory";
             /**
-             * Absolute file or directory path
+             * Absolute directory path
              */
             path: string;
             /**
              * User-facing display name for the attachment
              */
             displayName: string;
-            /**
-             * Optional line range to scope the attachment to a specific section of the file
-             */
-            lineRange?: {
-                /**
-                 * Start line number (1-based)
-                 */
-                start: number;
-                /**
-                 * End line number (1-based, inclusive)
-                 */
-                end: number;
-            };
         } | {
             /**
              * Attachment type discriminator
@@ -923,6 +1109,9 @@ export type SessionEvent = {
              * Position range of the selection within the file
              */
             selection: {
+                /**
+                 * Start position of the selection
+                 */
                 start: {
                     /**
                      * Start line number (0-based)
@@ -933,6 +1122,9 @@ export type SessionEvent = {
                      */
                     character: number;
                 };
+                /**
+                 * End position of the selection
+                 */
                 end: {
                     /**
                      * End line number (0-based)
@@ -969,6 +1161,23 @@ export type SessionEvent = {
              * URL to the referenced item on GitHub
              */
             url: string;
+        } | {
+            /**
+             * Attachment type discriminator
+             */
+            type: "blob";
+            /**
+             * Base64-encoded content
+             */
+            data: string;
+            /**
+             * MIME type of the inline data
+             */
+            mimeType: string;
+            /**
+             * User-facing display name for the attachment
+             */
+            displayName?: string;
         })[];
         /**
          * Origin of this message, used for timeline filtering (e.g., "skill-pdf" for skill-injected messages that should be hidden from the user)
@@ -1020,6 +1229,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "assistant.turn_start";
+    /**
+     * Turn initialization metadata including identifier and interaction tracking
+     */
     data: {
         /**
          * Identifier for this turn within the agentic loop, typically a stringified turn number
@@ -1045,6 +1257,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "assistant.intent";
+    /**
+     * Agent intent description for current activity or plan
+     */
     data: {
         /**
          * Short description of what the agent is currently doing or planning to do
@@ -1069,6 +1284,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "assistant.reasoning";
+    /**
+     * Assistant reasoning content for timeline display with complete thinking text
+     */
     data: {
         /**
          * Unique identifier for this reasoning block
@@ -1094,6 +1312,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "assistant.reasoning_delta";
+    /**
+     * Streaming reasoning delta for incremental extended thinking updates
+     */
     data: {
         /**
          * Reasoning block ID this delta belongs to, matching the corresponding assistant.reasoning event
@@ -1119,6 +1340,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "assistant.streaming_delta";
+    /**
+     * Streaming response progress with cumulative byte count
+     */
     data: {
         /**
          * Cumulative total bytes received from the streaming response so far
@@ -1143,6 +1367,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "assistant.message";
+    /**
+     * Assistant response containing text content, optional tool requests, and interaction metadata
+     */
     data: {
         /**
          * Unique identifier for this assistant message
@@ -1174,6 +1401,14 @@ export type SessionEvent = {
              * Tool call type: "function" for standard tool calls, "custom" for grammar-based tool calls. Defaults to "function" when absent.
              */
             type?: "function" | "custom";
+            /**
+             * Human-readable display title for the tool
+             */
+            toolTitle?: string;
+            /**
+             * Resolved intention summary describing what this specific call does
+             */
+            intentionSummary?: string | null;
         }[];
         /**
          * Opaque/encrypted extended thinking data from Anthropic models. Session-bound and stripped on resume.
@@ -1219,6 +1454,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "assistant.message_delta";
+    /**
+     * Streaming assistant message delta for incremental response updates
+     */
     data: {
         /**
          * Message ID this delta belongs to, matching the corresponding assistant.message event
@@ -1251,6 +1489,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "assistant.turn_end";
+    /**
+     * Turn completion metadata including the turn identifier
+     */
     data: {
         /**
          * Identifier of the turn that has ended, matching the corresponding assistant.turn_start event
@@ -1272,6 +1513,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "assistant.usage";
+    /**
+     * LLM API call usage metrics including tokens, costs, quotas, and billing information
+     */
     data: {
         /**
          * Model identifier used for this API call
@@ -1386,6 +1630,10 @@ export type SessionEvent = {
              */
             totalNanoAiu: number;
         };
+        /**
+         * Reasoning effort level used for model calls, if applicable (e.g. "low", "medium", "high", "xhigh")
+         */
+        reasoningEffort?: string;
     };
 } | {
     /**
@@ -1405,6 +1653,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "abort";
+    /**
+     * Turn abort information including the reason for termination
+     */
     data: {
         /**
          * Reason the current turn was aborted (e.g., "user initiated")
@@ -1429,6 +1680,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "tool.user_requested";
+    /**
+     * User-initiated tool invocation request with tool name and arguments
+     */
     data: {
         /**
          * Unique identifier for this tool call
@@ -1463,6 +1717,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "tool.execution_start";
+    /**
+     * Tool execution startup details including MCP server information when applicable
+     */
     data: {
         /**
          * Unique identifier for this tool call
@@ -1506,6 +1763,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "tool.execution_partial_result";
+    /**
+     * Streaming tool execution output for incremental result display
+     */
     data: {
         /**
          * Tool call ID this partial result belongs to
@@ -1531,6 +1791,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "tool.execution_progress";
+    /**
+     * Tool execution progress notification with status message
+     */
     data: {
         /**
          * Tool call ID this progress notification belongs to
@@ -1559,6 +1822,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "tool.execution_complete";
+    /**
+     * Tool execution completion results including success status, detailed output, and error information
+     */
     data: {
         /**
          * Unique identifier for the completed tool call
@@ -1776,6 +2042,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "skill.invoked";
+    /**
+     * Skill invocation details including content, allowed tools, and plugin metadata
+     */
     data: {
         /**
          * Name of the invoked skill
@@ -1801,6 +2070,10 @@ export type SessionEvent = {
          * Version of the plugin this skill originated from, when applicable
          */
         pluginVersion?: string;
+        /**
+         * Description of the skill from its SKILL.md frontmatter
+         */
+        description?: string;
     };
 } | {
     /**
@@ -1820,6 +2093,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "subagent.started";
+    /**
+     * Sub-agent startup details including parent tool call and agent information
+     */
     data: {
         /**
          * Tool call ID of the parent tool invocation that spawned this sub-agent
@@ -1856,6 +2132,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "subagent.completed";
+    /**
+     * Sub-agent completion details for successful execution
+     */
     data: {
         /**
          * Tool call ID of the parent tool invocation that spawned this sub-agent
@@ -1869,6 +2148,22 @@ export type SessionEvent = {
          * Human-readable display name of the sub-agent
          */
         agentDisplayName: string;
+        /**
+         * Model used by the sub-agent
+         */
+        model?: string;
+        /**
+         * Total number of tool calls made by the sub-agent
+         */
+        totalToolCalls?: number;
+        /**
+         * Total tokens (input + output) consumed by the sub-agent
+         */
+        totalTokens?: number;
+        /**
+         * Wall-clock duration of the sub-agent execution in milliseconds
+         */
+        durationMs?: number;
     };
 } | {
     /**
@@ -1888,6 +2183,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "subagent.failed";
+    /**
+     * Sub-agent failure details including error message and agent information
+     */
     data: {
         /**
          * Tool call ID of the parent tool invocation that spawned this sub-agent
@@ -1905,6 +2203,22 @@ export type SessionEvent = {
          * Error message describing why the sub-agent failed
          */
         error: string;
+        /**
+         * Model used by the sub-agent (if any model calls succeeded before failure)
+         */
+        model?: string;
+        /**
+         * Total number of tool calls made before the sub-agent failed
+         */
+        totalToolCalls?: number;
+        /**
+         * Total tokens (input + output) consumed before the sub-agent failed
+         */
+        totalTokens?: number;
+        /**
+         * Wall-clock duration of the sub-agent execution in milliseconds
+         */
+        durationMs?: number;
     };
 } | {
     /**
@@ -1924,6 +2238,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "subagent.selected";
+    /**
+     * Custom agent selection details including name and available tools
+     */
     data: {
         /**
          * Internal name of the selected custom agent
@@ -1978,6 +2295,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "hook.start";
+    /**
+     * Hook invocation start details including type and input data
+     */
     data: {
         /**
          * Unique identifier for this hook invocation
@@ -2012,6 +2332,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "hook.end";
+    /**
+     * Hook invocation completion details including output, success status, and error information
+     */
     data: {
         /**
          * Identifier matching the corresponding hook.start event
@@ -2063,6 +2386,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "system.message";
+    /**
+     * System or developer message content with role and optional template metadata
+     */
     data: {
         /**
          * The system or developer prompt text
@@ -2110,6 +2436,9 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "system.notification";
+    /**
+     * System-generated notification for runtime events like background task completion
+     */
     data: {
         /**
          * The notification text, typically wrapped in <system_notification> XML tags
@@ -2140,6 +2469,20 @@ export type SessionEvent = {
              * The full prompt given to the background agent
              */
             prompt?: string;
+        } | {
+            type: "agent_idle";
+            /**
+             * Unique identifier of the background agent
+             */
+            agentId: string;
+            /**
+             * Type of the agent (e.g., explore, task, general-purpose)
+             */
+            agentType: string;
+            /**
+             * Human-readable description of the agent task
+             */
+            description?: string;
         } | {
             type: "shell_completed";
             /**
@@ -2181,6 +2524,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "permission.requested";
+    /**
+     * Permission request notification requiring client approval with request details
+     */
     data: {
         /**
          * Unique identifier for this permission request; used to respond via session.respondToPermission()
@@ -2378,6 +2724,29 @@ export type SessionEvent = {
             args?: {
                 [k: string]: unknown;
             };
+        } | {
+            /**
+             * Permission kind discriminator
+             */
+            kind: "hook";
+            /**
+             * Tool call ID that triggered this permission request
+             */
+            toolCallId?: string;
+            /**
+             * Name of the tool the hook is gating
+             */
+            toolName: string;
+            /**
+             * Arguments of the tool call being gated
+             */
+            toolArgs?: {
+                [k: string]: unknown;
+            };
+            /**
+             * Optional message from the hook explaining why confirmation is needed
+             */
+            hookMessage?: string;
         };
     };
 } | {
@@ -2395,6 +2764,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "permission.completed";
+    /**
+     * Permission request completion notification signaling UI dismissal
+     */
     data: {
         /**
          * Request ID of the resolved permission request; clients should dismiss any UI for this request
@@ -2425,6 +2797,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "user_input.requested";
+    /**
+     * User input request notification with question and optional predefined choices
+     */
     data: {
         /**
          * Unique identifier for this input request; used to respond via session.respondToUserInput()
@@ -2442,6 +2817,10 @@ export type SessionEvent = {
          * Whether the user can provide a free-form text response in addition to predefined choices
          */
         allowFreeform?: boolean;
+        /**
+         * The LLM-assigned tool call ID that triggered this request; used by remote UIs to correlate responses
+         */
+        toolCallId?: string;
     };
 } | {
     /**
@@ -2458,6 +2837,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "user_input.completed";
+    /**
+     * User input request completion notification signaling UI dismissal
+     */
     data: {
         /**
          * Request ID of the resolved user input request; clients should dismiss any UI for this request
@@ -2479,23 +2861,37 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "elicitation.requested";
+    /**
+     * Elicitation request; may be form-based (structured input) or URL-based (browser redirect)
+     */
     data: {
         /**
          * Unique identifier for this elicitation request; used to respond via session.respondToElicitation()
          */
         requestId: string;
+        /**
+         * Tool call ID from the LLM completion; used to correlate with CompletionChunk.toolCall.id for remote UIs
+         */
+        toolCallId?: string;
+        /**
+         * The source that initiated the request (MCP server name, or absent for agent-initiated)
+         */
+        elicitationSource?: string;
         /**
          * Message describing what information is needed from the user
          */
         message: string;
         /**
-         * Elicitation mode; currently only "form" is supported. Defaults to "form" when absent.
+         * Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
          */
-        mode?: "form";
+        mode?: "form" | "url";
         /**
-         * JSON Schema describing the form fields to present to the user
+         * JSON Schema describing the form fields to present to the user (form mode only)
          */
-        requestedSchema: {
+        requestedSchema?: {
+            /**
+             * Schema type indicator (always 'object')
+             */
             type: "object";
             /**
              * Form field definitions, keyed by field name
@@ -2508,6 +2904,10 @@ export type SessionEvent = {
              */
             required?: string[];
         };
+        /**
+         * URL to open in the user's browser (url mode only)
+         */
+        url?: string;
         [k: string]: unknown;
     };
 } | {
@@ -2525,12 +2925,84 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "elicitation.completed";
+    /**
+     * Elicitation request completion notification signaling UI dismissal
+     */
     data: {
         /**
          * Request ID of the resolved elicitation request; clients should dismiss any UI for this request
          */
         requestId: string;
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "mcp.oauth_required";
+    /**
+     * OAuth authentication request for an MCP server
+     */
+    data: {
+        /**
+         * Unique identifier for this OAuth request; used to respond via session.respondToMcpOAuth()
+         */
+        requestId: string;
+        /**
+         * Display name of the MCP server that requires OAuth
+         */
+        serverName: string;
+        /**
+         * URL of the MCP server that requires OAuth
+         */
+        serverUrl: string;
+        /**
+         * Static OAuth client configuration, if the server specifies one
+         */
+        staticClientConfig?: {
+            /**
+             * OAuth client ID for the server
+             */
+            clientId: string;
+            /**
+             * Whether this is a public OAuth client
+             */
+            publicClient?: boolean;
+        };
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "mcp.oauth_completed";
+    /**
+     * MCP OAuth request completion notification
+     */
+    data: {
+        /**
+         * Request ID of the resolved OAuth request
+         */
+        requestId: string;
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -2546,6 +3018,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "external_tool.requested";
+    /**
+     * External tool invocation request for client-side tool execution
+     */
     data: {
         /**
          * Unique identifier for this request; used to respond via session.respondToExternalTool()
@@ -2569,6 +3044,14 @@ export type SessionEvent = {
         arguments?: {
             [k: string]: unknown;
         };
+        /**
+         * W3C Trace Context traceparent header for the execute_tool span
+         */
+        traceparent?: string;
+        /**
+         * W3C Trace Context tracestate header for the execute_tool span
+         */
+        tracestate?: string;
     };
 } | {
     /**
@@ -2585,6 +3068,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "external_tool.completed";
+    /**
+     * External tool completion notification signaling UI dismissal
+     */
     data: {
         /**
          * Request ID of the resolved external tool request; clients should dismiss any UI for this request
@@ -2606,6 +3092,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "command.queued";
+    /**
+     * Queued slash command dispatch request for client execution
+     */
     data: {
         /**
          * Unique identifier for this request; used to respond via session.respondToQueuedCommand()
@@ -2616,6 +3105,42 @@ export type SessionEvent = {
          */
         command: string;
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "command.execute";
+    /**
+     * Registered command dispatch request routed to the owning client
+     */
+    data: {
+        /**
+         * Unique identifier; used to respond via session.commands.handlePendingCommand()
+         */
+        requestId: string;
+        /**
+         * The full command text (e.g., /deploy production)
+         */
+        command: string;
+        /**
+         * Command name without leading /
+         */
+        commandName: string;
+        /**
+         * Raw argument string after the command name
+         */
+        args: string;
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -2631,12 +3156,42 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "command.completed";
+    /**
+     * Queued command completion notification signaling UI dismissal
+     */
     data: {
         /**
          * Request ID of the resolved command request; clients should dismiss any UI for this request
          */
         requestId: string;
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "commands.changed";
+    /**
+     * SDK command registration change notification
+     */
+    data: {
+        /**
+         * Current list of registered SDK commands
+         */
+        commands: {
+            name: string;
+            description?: string;
+        }[];
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -2652,6 +3207,9 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "exit_plan_mode.requested";
+    /**
+     * Plan approval request with plan content and available user actions
+     */
     data: {
         /**
          * Unique identifier for this request; used to respond via session.respondToExitPlanMode()
@@ -2689,10 +3247,256 @@ export type SessionEvent = {
     parentId: string | null;
     ephemeral: true;
     type: "exit_plan_mode.completed";
+    /**
+     * Plan mode exit completion notification signaling UI dismissal
+     */
     data: {
         /**
          * Request ID of the resolved exit plan mode request; clients should dismiss any UI for this request
          */
         requestId: string;
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.tools_updated";
+    data: {
+        model: string;
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.background_tasks_changed";
+    data: {};
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.skills_loaded";
+    data: {
+        /**
+         * Array of resolved skill metadata
+         */
+        skills: {
+            /**
+             * Unique identifier for the skill
+             */
+            name: string;
+            /**
+             * Description of what the skill does
+             */
+            description: string;
+            /**
+             * Source location type of the skill (e.g., project, personal, plugin)
+             */
+            source: string;
+            /**
+             * Whether the skill can be invoked by the user as a slash command
+             */
+            userInvocable: boolean;
+            /**
+             * Whether the skill is currently enabled
+             */
+            enabled: boolean;
+            /**
+             * Absolute path to the skill file, if available
+             */
+            path?: string;
+        }[];
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.custom_agents_updated";
+    data: {
+        /**
+         * Array of loaded custom agent metadata
+         */
+        agents: {
+            /**
+             * Unique identifier for the agent
+             */
+            id: string;
+            /**
+             * Internal name of the agent
+             */
+            name: string;
+            /**
+             * Human-readable display name
+             */
+            displayName: string;
+            /**
+             * Description of what the agent does
+             */
+            description: string;
+            /**
+             * Source location: user, project, inherited, remote, or plugin
+             */
+            source: string;
+            /**
+             * List of tool names available to this agent
+             */
+            tools: string[];
+            /**
+             * Whether the agent can be selected by the user
+             */
+            userInvocable: boolean;
+            /**
+             * Model override for this agent, if set
+             */
+            model?: string;
+        }[];
+        /**
+         * Non-fatal warnings from agent loading
+         */
+        warnings: string[];
+        /**
+         * Fatal errors from agent loading
+         */
+        errors: string[];
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.mcp_servers_loaded";
+    data: {
+        /**
+         * Array of MCP server status summaries
+         */
+        servers: {
+            /**
+             * Server name (config key)
+             */
+            name: string;
+            /**
+             * Connection status: connected, failed, pending, disabled, or not_configured
+             */
+            status: "connected" | "failed" | "pending" | "disabled" | "not_configured";
+            /**
+             * Configuration source: user, workspace, plugin, or builtin
+             */
+            source?: string;
+            /**
+             * Error message if the server failed to connect
+             */
+            error?: string;
+        }[];
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.mcp_server_status_changed";
+    data: {
+        /**
+         * Name of the MCP server whose status changed
+         */
+        serverName: string;
+        /**
+         * New connection status: connected, failed, pending, disabled, or not_configured
+         */
+        status: "connected" | "failed" | "pending" | "disabled" | "not_configured";
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.extensions_loaded";
+    data: {
+        /**
+         * Array of discovered extensions and their status
+         */
+        extensions: {
+            /**
+             * Source-qualified extension ID (e.g., 'project:my-ext', 'user:auth-helper')
+             */
+            id: string;
+            /**
+             * Extension name (directory name)
+             */
+            name: string;
+            /**
+             * Discovery source
+             */
+            source: "project" | "user";
+            /**
+             * Current status: running, disabled, failed, or starting
+             */
+            status: "running" | "disabled" | "failed" | "starting";
+        }[];
+    };
 };